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
manual.py · 7.5 KB · 142 lines
| 1 | """The manual carrier: the operator IS the integration. |
| 2 | |
| 3 | This is app-shipping's own carrier connector, declared in the manifest |
| 4 | under `connectors` for the `shipments` collection and loaded at runtime by |
| 5 | object_connectors.load_connector -- the mechanism the mail connector spec |
| 6 | already established (plan/vocabulary/03-external-connectors-spec.md). |
| 7 | Open core never imports it statically; a deployment that swaps in a real |
| 8 | carrier installs a package declaring `connectors` for `shipments` too, and |
| 9 | the private overlay's declaration wins for the whole box. That swap is the |
| 10 | entire point of this file existing rather than the manual behaviour being |
| 11 | welded into the two objects that use it: if the free path is not shaped |
| 12 | exactly like the paid one, the paid one is a rewrite rather than a plug-in. |
| 13 | |
| 14 | THE CARRIER INTERFACE, in full, so an adapter author needs nothing else: |
| 15 | |
| 16 | PROVIDER = "manual" the value of app_settings carrier.provider this |
| 17 | module answers to. The objects refuse to use a |
| 18 | module whose PROVIDER disagrees with the |
| 19 | setting rather than quietly doing something |
| 20 | other than what the shop configured. |
| 21 | |
| 22 | track(shipment, *, base_dir) -> outcome |
| 23 | Ask the carrier where this parcel is. |
| 24 | {"ok": True, "status": "Out for delivery", "delivered": False} |
| 25 | {"ok": True, "status": "Delivered", "delivered": True, |
| 26 | "delivered_on": "2026-07-24"} -- moves the shipment to delivered |
| 27 | |
| 28 | buy_label(shipment, *, base_dir, tracking_number="", label_bytes=None, |
| 29 | label_content_type="", label_filename="") -> outcome |
| 30 | Get a label for this parcel. Direction is on the shipment: an |
| 31 | INBOUND shipment is a return label, and there is deliberately no |
| 32 | second verb for it -- a return label is the same purchase with the |
| 33 | addresses the other way round, and two verbs would be two places |
| 34 | for the credentials, the errors and the file to drift. |
| 35 | {"ok": True, "tracking_number": "1Z...", "label_bytes": b"%PDF...", |
| 36 | "label_content_type": "application/pdf", "label_filename": "..."} |
| 37 | |
| 38 | reconcile(record, *, base_dir) -> outcome |
| 39 | The entry object_daemon's connector pass calls. See below. |
| 40 | |
| 41 | Every one of them answers in the SAME vocabulary object_connectors already |
| 42 | defines for reconcile, and reusing it is deliberate: |
| 43 | |
| 44 | {"ok": True, ...} it worked; here is what we learned |
| 45 | {"skip": True, "reason": "..."} declined this tick -- the HOST is |
| 46 | not set up. The row is left exactly |
| 47 | as it is and NOTHING is counted |
| 48 | against it. |
| 49 | {"ok": False, "error": "..."} THIS parcel could not be read; count |
| 50 | the attempt against it. |
| 51 | {"ok": False, "error": "...", |
| 52 | "permanent": True} ...and do not bother asking again. |
| 53 | |
| 54 | That distinction is the one system_scan_processor spells `recoverable`, and |
| 55 | it is the difference between "somebody has not pasted the API key in yet" |
| 56 | and "this tracking number is nonsense". Spelling it a third way here would |
| 57 | mean three subsystems that agree about the rule and disagree about the word, |
| 58 | so this file borrows the connector contract's word and the poll borrows its |
| 59 | meaning. |
| 60 | |
| 61 | WHAT `manual` ACTUALLY DOES: |
| 62 | |
| 63 | `track` always declines. There is no carrier to ask -- the operator is the |
| 64 | one who reads the tracking page and types what it said, and a poll that |
| 65 | "succeeded" every hour by writing back the status a human typed would burn |
| 66 | tracking_checked_at into a timestamp that means nothing. Declining is the |
| 67 | honest answer, and because it declines rather than fails, nothing is ever |
| 68 | counted against a manually-tracked parcel. |
| 69 | |
| 70 | `buy_label` accepts what the operator brings back from the post office |
| 71 | counter: the tracking number, and optionally the label PDF they were handed. |
| 72 | It buys nothing and pretends to buy nothing. It is still worth routing |
| 73 | through the connector interface, because it is what proves the interface |
| 74 | covers the free path -- and because the day a real adapter lands, the |
| 75 | operator-typed path is still there for the parcel the API refuses to quote. |
| 76 | |
| 77 | `reconcile` declines every tick, always, and that is not a stub. The |
| 78 | daemon's connector pass converges an external system toward what our |
| 79 | records DESIRE; a parcel is the opposite shape of fact. We cannot make a |
| 80 | van arrive by wishing, the carrier's truth flows toward us rather than away, |
| 81 | and reading it is time-driven work that belongs to a scheduled pass |
| 82 | (docs/logic-decisions.md #2) -- system_tracking_poll, declared in this |
| 83 | package's `schedules`. The declaration exists so that the module is |
| 84 | DISCOVERABLE by the mechanism that already resolves connector modules |
| 85 | safely (escape-checked, package-relative, dynamically loaded); implementing |
| 86 | `reconcile` as an explicit decline is how it stays discoverable without the |
| 87 | reconcile pass quietly acquiring a meaning nobody wanted. |
| 88 | """ |
| 89 | |
| 90 | PROVIDER = "manual" |
| 91 | |
| 92 | # Kept short because it is written into a poll's report and read by somebody |
| 93 | # scanning a list of skipped rows. |
| 94 | _NO_CARRIER = ("carrier.provider is manual: tracking is whatever the operator " |
| 95 | "typed, so there is nobody to ask") |
| 96 | |
| 97 | |
| 98 | def track(shipment, *, base_dir=None): |
| 99 | """Decline, always -- see the module docstring. Not an attempt, not a |
| 100 | failure: the row waits exactly as the operator left it.""" |
| 101 | return {"skip": True, "reason": _NO_CARRIER} |
| 102 | |
| 103 | |
| 104 | def buy_label(shipment, *, base_dir=None, tracking_number="", |
| 105 | label_bytes=None, label_content_type="", label_filename=""): |
| 106 | """Take what the human brings back from the counter. |
| 107 | |
| 108 | The one refusal here is an empty tracking number, and it is a refusal |
| 109 | rather than a shrug because the whole reason to press this button |
| 110 | manually is to put a tracking number on the parcel -- stamping an empty |
| 111 | string would leave a shipment that claims to have a label and cannot be |
| 112 | followed. The label FILE is optional: plenty of shops print the label |
| 113 | from the carrier's own site and never hold the bytes, and refusing them |
| 114 | a tracking number over a missing PDF would be paperwork for its own |
| 115 | sake. |
| 116 | """ |
| 117 | number = str(tracking_number or "").strip() |
| 118 | if not number: |
| 119 | return {"ok": False, "permanent": True, |
| 120 | "error": ("A manual label needs the tracking number the " |
| 121 | "carrier gave you -- that number is the whole " |
| 122 | "point of the button, and a label with no number " |
| 123 | "cannot be followed by anybody.")} |
| 124 | outcome = {"ok": True, "tracking_number": number, |
| 125 | "provider": PROVIDER, |
| 126 | "note": ("recorded from the counter; nothing was bought and " |
| 127 | "nothing pretended to be")} |
| 128 | if label_bytes: |
| 129 | outcome["label_bytes"] = label_bytes |
| 130 | outcome["label_content_type"] = (str(label_content_type or "").strip() |
| 131 | or "application/pdf") |
| 132 | outcome["label_filename"] = (str(label_filename or "").strip() |
| 133 | or f"label-{number}.pdf") |
| 134 | return outcome |
| 135 | |
| 136 | |
| 137 | def reconcile(record, *, base_dir=None): |
| 138 | """The daemon's desired-state pass has nothing to converge here.""" |
| 139 | return {"skip": True, |
| 140 | "reason": ("a shipment is not desired state: the carrier's truth " |
| 141 | "flows toward us, and reading it is system_tracking_" |
| 142 | "poll's scheduled job")} |