Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
tracking_poll.py · 13.6 KB · 299 lines
1"""system_tracking_poll -- ask the carrier where the parcel is, and stop
2asking about the ones that will never answer.
3
4POST {limit?, today?} -- the scheduled pass declared in this package's
5`schedules`. It reads; it writes back only what the carrier said, plus the
6one derived move that follows from it: a parcel the carrier reports as
7delivered becomes `delivered`, and system_order_fulfillment turns that into
8an order status the way it already turns `shipped` into one. This object
9therefore never touches an order, never composes a stock move and never
10sends anything -- it is a reader with one status stamp, and everything
11downstream of that stamp is somebody else's already-tested job.
12
13Time-driven state belongs to a daemon pass (docs/logic-decisions.md #2).
14Nothing writes when a van drives, so no reaction can notice a delivery, and
15a surface computing "probably arrived by now" from a ship date would be
16exactly the fake precision the shipments schema refuses elsewhere. Hourly
17is the cadence, argued in the manifest: a carrier scan lands a handful of
18times a day, so hourly is well inside the resolution of the underlying
19facts, while a shop with parcels out is a shop whose customers are emailing
20about them TODAY -- a nightly pass would mean the answer to "did it arrive?"
21is up to a day stale exactly when somebody is asking.
22
23WHICH PARCELS. Outbound only, in `shipped` or `in_transit`, with a tracking
24number, that have not already failed MAX_ATTEMPTS times. Outbound only is a
25decision, not an omission: an inbound RMA's ladder ends at `received`, which
26means a human has the box on the dock and has looked at it. A carrier saying
27"delivered" is not that fact, and writing it in as though it were would tell
28the returns bench a parcel had arrived and been accepted when nobody had
29touched it. No tracking number means there is nothing to ask WITH; the
30manual shop that hands parcels to a driver is not failing, it simply is not
31in this queue.
32
33FAILURE POSTURE, copied from system_scan_processor deliberately, because
34this is the same shape of problem: something outside the box will sometimes
35not answer, and a pass that treats every silence identically either churns a
36metered API forever or retires a whole warehouse's parcels the day somebody
37mistypes a key. So the two silences are told apart explicitly and by the
38CONNECTOR'S OWN WORD rather than a third spelling of it:
39
40 the host is not set up `{"skip": True}` from the carrier, or no carrier
41 configured at all. The row is untouched, NOTHING
42 is counted against it, and the pass says why in
43 its report. Fixing the configuration drains the
44 backlog; nothing had to be un-failed first.
45 this parcel cannot be `{"ok": False, "error": ...}`. tracking_attempts
46 read goes up, tracking_error records what was said,
47 and at MAX_ATTEMPTS the parcel stops being polled
48 and starts being VISIBLE in `needing_a_human` --
49 and in the stuck-parcel attention count, which is
50 where a human actually finds it.
51
52`permanent` jumps straight to the attempt ceiling. A carrier that says a
53tracking number does not exist will say the same thing tomorrow, and three
54polite retries against a typo is just three more chances to be wrong slowly.
55"""
56
57import os
58from datetime import date, datetime, timezone
59from pathlib import Path
60
61import object_connectors
62import object_packages
63import object_records
64
65ACTOR = "system_tracking_poll"
66
67DEFAULT_LIMIT = 50
68MAX_ATTEMPTS = 3
69
70# Outbound and still on the road. `delivered`, `lost` and
71# `returned_to_sender` are all terminal answers about a parcel; asking the
72# carrier again is spending somebody's API quota on a settled fact.
73POLLABLE = {"shipped", "in_transit"}
74
75
76def _base_dir():
77 return os.environ.get("DBBASIC_DATA_DIR", "data")
78
79
80def _text(value):
81 return str(value if value is not None else "").strip()
82
83
84def _int(value, default=0):
85 try:
86 return int(_text(value) or default)
87 except (TypeError, ValueError):
88 return default
89
90
91def _now():
92 return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
93
94
95def _setting(base, key, default=""):
96 """Duplicated on purpose, same as every other package that reads
97 app_settings (docs/logic-decisions.md #4)."""
98 try:
99 for row in object_records.read_collection_records("app_settings",
100 base_dir=base):
101 if row.get("key") == key and _text(row.get("value")):
102 return _text(row["value"])
103 except Exception:
104 pass
105 return default
106
107
108# --- the carrier boundary -----------------------------------------------------
109#
110# The next two helpers are a deliberate second copy of the pair in
111# action_buy_label, named in both files. Objects cannot import each other on
112# this platform (a sibling is reached by executing it, not by importing it),
113# and #4 says to wait for the third occurrence before extracting a layer --
114# so the third carrier-facing object is the one that should be made to hurt,
115# not this one.
116
117def _carrier_declaration():
118 """The connector declaration that owns `shipments` on this box.
119
120 Resolved through object_packages.iter_connectors, which is the existing
121 mechanism: it validates that the module lives inside its package, hands
122 back an absolute path, and lets a private overlay's declaration win --
123 exactly the resolution object_daemon's reconcile pass uses. Finding the
124 module any other way would be a second registry for connector modules,
125 and two registries is how a deployment ends up running an adapter
126 nobody declared.
127 """
128 packages = os.environ.get("DBBASIC_PACKAGES_DIR", object_packages.PACKAGES_DIR)
129 private = (os.environ.get("DBBASIC_PRIVATE_PACKAGES_DIR")
130 or str(Path(packages).parent / "packages-private"))
131 roots = ([private] if Path(private).is_dir() else []) + [packages]
132 for root in roots:
133 for declaration in object_packages.iter_connectors(root=root):
134 if declaration["collection"] == "shipments":
135 return declaration
136 return None
137
138
139def _carrier(base, entry):
140 """(function, provider, problem) -- the configured carrier's `entry`, or
141 the honest reason there is not one.
142
143 A `problem` is always a HOST problem: nothing is configured, nothing is
144 installed, or what is installed answers to a different name than the
145 setting. None of those are a parcel's fault, so every caller here treats
146 a problem as a decline rather than a failure.
147 """
148 provider = _setting(base, "carrier.provider", "none").lower() or "none"
149 if provider == "none":
150 return None, provider, (
151 "carrier.provider is `none`, so nobody is asked and nothing is "
152 "counted: tracking is whatever an operator typed on the shipment. "
153 "Set app_settings carrier.provider to `manual` or to an installed "
154 "carrier adapter's name to change that.")
155
156 declaration = _carrier_declaration()
157 if declaration is None:
158 return None, provider, (
159 f"carrier.provider is {provider!r} but no installed package "
160 f"declares a connector for the shipments collection, so there is "
161 f"nothing to ask.")
162 try:
163 function = object_connectors.load_connector(declaration["module"], entry)
164 except object_connectors.ConnectorLoadError as exc:
165 return None, provider, (
166 f"the carrier connector for {provider!r} could not be loaded "
167 f"({str(exc)[:160]}), so no parcel was asked about.")
168
169 # The module's own name for itself, read off the loaded function's
170 # globals -- load_connector deliberately does not register the module in
171 # sys.modules, and a second loader just to read one constant would be a
172 # second loader.
173 declared = _text(function.__globals__.get("PROVIDER"))
174 if declared and declared.lower() != provider:
175 return None, provider, (
176 f"carrier.provider is {provider!r} but the connector installed "
177 f"for shipments answers to {declared!r}. Nothing was asked: "
178 f"quietly using a carrier the shop did not configure is worse "
179 f"than a pass that did nothing and said so.")
180 return function, provider, ""
181
182
183# --- the pass ------------------------------------------------------------------
184
185def POST(request):
186 base = _base_dir()
187 limit = _int(request.get("limit"), DEFAULT_LIMIT) or DEFAULT_LIMIT
188 today = _text(request.get("today")) or date.today().isoformat()
189
190 try:
191 shipments = object_records.read_collection_records("shipments",
192 base_dir=base)
193 except Exception:
194 return {"ok": True, "skipped": "shipping not installed (shipments absent)"}
195
196 on_the_road = [row for row in shipments
197 if _text(row.get("direction")) != "inbound"
198 and _text(row.get("status")) in POLLABLE]
199 # Parcels that have already used up their attempts are not polled again;
200 # they are REPORTED, which is the difference between a queue that drains
201 # and one that grinds.
202 stuck = [row["id"] for row in on_the_road
203 if _int(row.get("tracking_attempts")) >= MAX_ATTEMPTS]
204 pending = [row for row in on_the_road
205 if _text(row.get("tracking_number"))
206 and _int(row.get("tracking_attempts")) < MAX_ATTEMPTS]
207 # Least recently answered first, so one busy parcel cannot starve the
208 # rest when a shop has more in flight than `limit`. A blank
209 # tracking_checked_at sorts first, which is right: never asked is the
210 # oldest answer there is.
211 pending.sort(key=lambda row: (_text(row.get("tracking_checked_at")),
212 _text(row.get("created_at"))))
213
214 report = {"ok": True, "today": today, "considered": len(pending),
215 "polled": 0, "delivered": 0, "failed": 0, "declined": 0,
216 "needing_a_human": stuck, "results": []}
217
218 track, provider, problem = _carrier(base, "track")
219 report["provider"] = provider
220 if problem:
221 # Not an attempt against anybody. The host is what is unfinished.
222 report["skipped"] = problem
223 return report
224
225 for shipment in pending[:limit]:
226 shipment_id = shipment["id"]
227 try:
228 outcome = track(shipment, base_dir=base)
229 if not isinstance(outcome, dict):
230 outcome = {"ok": False,
231 "error": (f"the carrier connector returned "
232 f"{type(outcome).__name__}, expected a dict")}
233 except Exception as exc: # noqa: BLE001
234 # One bad parcel must not end the pass for the rest of the shop.
235 outcome = {"ok": False,
236 "error": f"the carrier connector raised: {str(exc)[:160]}"}
237
238 if outcome.get("skip"):
239 report["declined"] += 1
240 report["results"].append({"shipment": shipment_id,
241 "declined": _text(outcome.get("reason"))})
242 continue
243
244 if not outcome.get("ok"):
245 attempts = _int(shipment.get("tracking_attempts")) + 1
246 if outcome.get("permanent"):
247 # Asking again will produce the same sentence.
248 attempts = max(attempts, MAX_ATTEMPTS)
249 error = _text(outcome.get("error"))[:500]
250 object_records.update_collection_record(
251 "shipments", shipment_id,
252 {"tracking_attempts": str(attempts), "tracking_error": error,
253 "tracking_checked_at": _now()},
254 base_dir=base, actor=ACTOR)
255 report["failed"] += 1
256 report["results"].append({"shipment": shipment_id, "error": error,
257 "attempts": attempts})
258 if attempts >= MAX_ATTEMPTS and shipment_id not in stuck:
259 stuck.append(shipment_id)
260 continue
261
262 update = {
263 "tracking_status": (_text(outcome.get("status"))
264 or _text(shipment.get("tracking_status"))),
265 "tracking_checked_at": _now(),
266 "tracking_attempts": "0",
267 "tracking_error": "",
268 }
269 arrived = bool(outcome.get("delivered"))
270 if arrived:
271 update["status"] = "delivered"
272 update["delivered_on"] = (_text(outcome.get("delivered_on"))
273 or _text(shipment.get("delivered_on"))
274 or today)
275 result = {"shipment": shipment_id}
276 try:
277 object_records.update_collection_record(
278 "shipments", shipment_id, update, base_dir=base, actor=ACTOR)
279 except Exception as exc: # noqa: BLE001
280 # A ladder that refuses the move is a real answer, not a crash:
281 # keep what the carrier SAID, drop only the derived move, and say
282 # so. Losing the carrier's words because our own enum disagreed
283 # would leave nothing for a human to work from.
284 arrived = False
285 update.pop("status", None)
286 update.pop("delivered_on", None)
287 object_records.update_collection_record(
288 "shipments", shipment_id, update, base_dir=base, actor=ACTOR)
289 result["status_error"] = str(exc)[:200]
290
291 report["polled"] += 1
292 if arrived:
293 report["delivered"] += 1
294 result["tracking_status"] = update["tracking_status"]
295 result["delivered"] = arrived
296 report["results"].append(result)
297
298 report["needing_a_human"] = stuck
299 return report