askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
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 |
| 2 | asking about the ones that will never answer. |
| 3 | |
| 4 | POST {limit?, today?} -- the scheduled pass declared in this package's |
| 5 | `schedules`. It reads; it writes back only what the carrier said, plus the |
| 6 | one derived move that follows from it: a parcel the carrier reports as |
| 7 | delivered becomes `delivered`, and system_order_fulfillment turns that into |
| 8 | an order status the way it already turns `shipped` into one. This object |
| 9 | therefore never touches an order, never composes a stock move and never |
| 10 | sends anything -- it is a reader with one status stamp, and everything |
| 11 | downstream of that stamp is somebody else's already-tested job. |
| 12 | |
| 13 | Time-driven state belongs to a daemon pass (docs/logic-decisions.md #2). |
| 14 | Nothing writes when a van drives, so no reaction can notice a delivery, and |
| 15 | a surface computing "probably arrived by now" from a ship date would be |
| 16 | exactly the fake precision the shipments schema refuses elsewhere. Hourly |
| 17 | is the cadence, argued in the manifest: a carrier scan lands a handful of |
| 18 | times a day, so hourly is well inside the resolution of the underlying |
| 19 | facts, while a shop with parcels out is a shop whose customers are emailing |
| 20 | about them TODAY -- a nightly pass would mean the answer to "did it arrive?" |
| 21 | is up to a day stale exactly when somebody is asking. |
| 22 | |
| 23 | WHICH PARCELS. Outbound only, in `shipped` or `in_transit`, with a tracking |
| 24 | number, that have not already failed MAX_ATTEMPTS times. Outbound only is a |
| 25 | decision, not an omission: an inbound RMA's ladder ends at `received`, which |
| 26 | means 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 |
| 28 | the returns bench a parcel had arrived and been accepted when nobody had |
| 29 | touched it. No tracking number means there is nothing to ask WITH; the |
| 30 | manual shop that hands parcels to a driver is not failing, it simply is not |
| 31 | in this queue. |
| 32 | |
| 33 | FAILURE POSTURE, copied from system_scan_processor deliberately, because |
| 34 | this is the same shape of problem: something outside the box will sometimes |
| 35 | not answer, and a pass that treats every silence identically either churns a |
| 36 | metered API forever or retires a whole warehouse's parcels the day somebody |
| 37 | mistypes a key. So the two silences are told apart explicitly and by the |
| 38 | CONNECTOR'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 |
| 53 | tracking number does not exist will say the same thing tomorrow, and three |
| 54 | polite retries against a typo is just three more chances to be wrong slowly. |
| 55 | """ |
| 56 | |
| 57 | import os |
| 58 | from datetime import date, datetime, timezone |
| 59 | from pathlib import Path |
| 60 | |
| 61 | import object_connectors |
| 62 | import object_packages |
| 63 | import object_records |
| 64 | |
| 65 | ACTOR = "system_tracking_poll" |
| 66 | |
| 67 | DEFAULT_LIMIT = 50 |
| 68 | MAX_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. |
| 73 | POLLABLE = {"shipped", "in_transit"} |
| 74 | |
| 75 | |
| 76 | def _base_dir(): |
| 77 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 78 | |
| 79 | |
| 80 | def _text(value): |
| 81 | return str(value if value is not None else "").strip() |
| 82 | |
| 83 | |
| 84 | def _int(value, default=0): |
| 85 | try: |
| 86 | return int(_text(value) or default) |
| 87 | except (TypeError, ValueError): |
| 88 | return default |
| 89 | |
| 90 | |
| 91 | def _now(): |
| 92 | return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") |
| 93 | |
| 94 | |
| 95 | def _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 | |
| 117 | def _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 | |
| 139 | def _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 | |
| 185 | def 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 |