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
run_template.py · 13.6 KB · 318 lines
| 1 | """action_run_template -- press Run on a template: validate, hold the |
| 2 | money, queue the job. |
| 3 | |
| 4 | POST {template_id, form_data?} |
| 5 | |
| 6 | This object QUEUES and never executes. A verb that both queued and ran |
| 7 | would make the queue a fiction under load, and -- worse -- would put a |
| 8 | paid provider call inside a web request, where a timeout looks to the |
| 9 | user like failure while the provider bills us anyway. Execution belongs |
| 10 | to system_template_runner, on the daemon, where a crash has a sweeper. |
| 11 | |
| 12 | ## The gate is asked at the moment of commitment |
| 13 | |
| 14 | The stamped price goes on the wallet as a HOLD, here, before anything is |
| 15 | queued -- through hook_wallet_entries, asked in process, exactly the way |
| 16 | action_checkout asks it for gift cards. The gate summing the real entries |
| 17 | at THIS moment is what makes "insufficient balance" mean something: a |
| 18 | user with five cents cannot queue four hundred runs and present the |
| 19 | provider bill later, because the four-hundredth hold fails the gate. |
| 20 | |
| 21 | Free templates (price 0) touch no wallet at all: no hold, no wallet_id on |
| 22 | the run, nothing to settle. Money machinery that runs for free jobs is |
| 23 | machinery that fails for free jobs. |
| 24 | |
| 25 | ## Capability boundaries are refused HERE, not discovered at 3am |
| 26 | |
| 27 | An ai handler needs a model (`runner.ai_model` in app_settings) and a |
| 28 | stored provider key for whoever is running it. Both are checked at queue |
| 29 | time and refused with a 409 naming exactly what to configure -- the house |
| 30 | posture: absent by default, never a stub that pretends to work. Refusing |
| 31 | here beats queueing a run that the daemon fails an hour later, because |
| 32 | the person who can fix the configuration is the one looking at the screen |
| 33 | right now. (The runner re-checks at execution -- a key can be deleted |
| 34 | between queue and run -- but that failure is the rare race, not the |
| 35 | normal path.) |
| 36 | |
| 37 | ## One execution model, not two (task_id) |
| 38 | |
| 39 | q9 (askrobots) has a SEPARATE model, `tasks.Work`, for "a template was run |
| 40 | in service of this task": task + template + worker + status + result, its |
| 41 | own row, its own history. This runner does not get a second one. `task_id` |
| 42 | on template_runs is the only piece Work had that this runner did not: |
| 43 | everything else Work would have needed -- a status machine, an idempotent |
| 44 | settlement, staleness detection, async submit/poll, an escalation path for |
| 45 | a run stuck between "submitted" and "resolved" -- template_runs already |
| 46 | has, built and proven under real money before this field existed. Work |
| 47 | had none of that; its billing lived in a THIRD, disconnected model |
| 48 | (`integrations.APILog`) that had to be kept in sync by hand. Here it is |
| 49 | the same row. |
| 50 | |
| 51 | Multiple attempts against one task are just multiple runs sharing a |
| 52 | task_id -- the append-only doctrine applies exactly as it does everywhere |
| 53 | else in this codebase: "how many times has this been attempted" is a |
| 54 | fold over rows, not a stored counter. The task's detail page renders that |
| 55 | fold with the same `related` block every other one-to-many relationship |
| 56 | in this system uses (order -> order_lines, invoice -> invoice_lines); |
| 57 | nothing new was built to show it. |
| 58 | |
| 59 | Deliberately absent: nothing here mutates task.status when a run |
| 60 | succeeds. A Design Review producing a report is not the same claim as |
| 61 | "this task is finished" -- that is a human's call, or an agent's, |
| 62 | looking at the run's own output, exactly the same "the server notices, |
| 63 | the person decides" posture system_reorder_check takes with its |
| 64 | suggestions. Automatic status transitions are a door left open, not one |
| 65 | walked through here. |
| 66 | |
| 67 | ## Ordering, and the crash between the two writes |
| 68 | |
| 69 | The hold is written BEFORE the run row. If the crash lands between them, |
| 70 | the result is a hold with no run -- money reserved for nothing, visible, |
| 71 | annoying, releasable. The other order would leave a QUEUED RUN WITH NO |
| 72 | HOLD: a job the runner would happily execute for free, invisibly. When a |
| 73 | crash must leave one of two wrongs, leave the one that fails safe and |
| 74 | shows up. (The window is one create call wide; on a run-create failure |
| 75 | this object immediately writes the release itself, so the orphan hold |
| 76 | survives only a crash, not an error.) |
| 77 | """ |
| 78 | |
| 79 | import json |
| 80 | import os |
| 81 | from datetime import datetime, timezone |
| 82 | |
| 83 | import object_execution |
| 84 | import object_ids |
| 85 | import object_records |
| 86 | import object_service_keys |
| 87 | import object_template_runs |
| 88 | import python_object_runtime |
| 89 | |
| 90 | ACTOR = "action_run_template" |
| 91 | RUNS = "template_runs" |
| 92 | MODEL_SETTING = "runner.ai_model" |
| 93 | |
| 94 | AI_HANDLERS = ("ai_text",) |
| 95 | KNOWN_HANDLERS = ("echo", "ai_text") |
| 96 | |
| 97 | |
| 98 | def _base_dir(): |
| 99 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 100 | |
| 101 | |
| 102 | def _text(value): |
| 103 | return str(value if value is not None else "").strip() |
| 104 | |
| 105 | |
| 106 | def _now(): |
| 107 | return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") |
| 108 | |
| 109 | |
| 110 | def _setting(base, key): |
| 111 | try: |
| 112 | for row in object_records.read_collection_records("app_settings", |
| 113 | base_dir=base): |
| 114 | if _text(row.get("key")) == key: |
| 115 | return _text(row.get("value")) |
| 116 | except Exception: |
| 117 | pass |
| 118 | return "" |
| 119 | |
| 120 | |
| 121 | def _call(object_id, payload, *, method="POST"): |
| 122 | """Run another installed object in process -- the pattern |
| 123 | action_checkout uses to ask hook_wallet_entries.""" |
| 124 | try: |
| 125 | runtime = python_object_runtime.PythonObjectRuntime() |
| 126 | outcome = object_execution.execute_object( |
| 127 | runtime, |
| 128 | object_execution.ObjectExecutionRequest( |
| 129 | object_id, method=method, payload=payload)) |
| 130 | except Exception as exc: |
| 131 | return None, str(exc)[:200] |
| 132 | if not outcome.ok: |
| 133 | message = getattr(outcome.error, "message", "") if outcome.error else "" |
| 134 | return None, (_text(message)[:200] or f"{object_id} failed") |
| 135 | return outcome.result, "" |
| 136 | |
| 137 | |
| 138 | def _wallet_for(base, owner_id): |
| 139 | """The owner's spending wallet: active, kind balance (or legacy blank). |
| 140 | |
| 141 | Gift cards and store credit are deliberately not reached from here in |
| 142 | slice 1 -- a template run is metered usage, and mixing tender kinds |
| 143 | into the hold path is a decision for the checkout that already makes |
| 144 | it, not a default. |
| 145 | """ |
| 146 | try: |
| 147 | rows = object_records.read_collection_records("wallets", base_dir=base) |
| 148 | except Exception: |
| 149 | return None |
| 150 | candidates = [row for row in rows |
| 151 | if _text(row.get("owner_id")) == owner_id |
| 152 | and _text(row.get("kind")) in ("", "balance") |
| 153 | and _text(row.get("is_active")).lower() != "false"] |
| 154 | candidates.sort(key=lambda row: _text(row.get("created_at"))) |
| 155 | return candidates[0] if candidates else None |
| 156 | |
| 157 | |
| 158 | def POST(request): |
| 159 | request = request or {} |
| 160 | base = _base_dir() |
| 161 | |
| 162 | identity = request.get("_identity") or {} |
| 163 | user_id = _text(identity.get("user_id")) |
| 164 | if not user_id: |
| 165 | return {"status": 401, |
| 166 | "error": "Running a template requires an account: runs are " |
| 167 | "held against a wallet, and an anonymous run would " |
| 168 | "be an open tap."} |
| 169 | |
| 170 | template_id = _text(request.get("template_id")) |
| 171 | if not template_id: |
| 172 | return {"status": 400, "error": "template_id is required."} |
| 173 | try: |
| 174 | template = object_records.get_collection_record( |
| 175 | "templates", template_id, base_dir=base) |
| 176 | except Exception: |
| 177 | return {"status": 404, |
| 178 | "error": f"There is no template {template_id!r} on this server."} |
| 179 | |
| 180 | # --- the optional task link ----------------------------------------------- |
| 181 | # |
| 182 | # A run is in service of a task, or it is not -- most are not (a SWOT |
| 183 | # from the shell, a one-off from Talk). When it is, ownership is |
| 184 | # checked HERE, at queue time, the same "refused while somebody is |
| 185 | # looking" posture the capability-boundary checks below already use: |
| 186 | # attaching a run to a task the caller cannot see would let them |
| 187 | # infer the task exists (its id, its status) through what the run |
| 188 | # settles against. Same posture as the attachments capability, which |
| 189 | # gates a file to the record it is attached to the same way. |
| 190 | task_id = _text(request.get("task_id")) |
| 191 | if task_id: |
| 192 | try: |
| 193 | task = object_records.get_collection_record( |
| 194 | "tasks", task_id, base_dir=base) |
| 195 | except Exception: |
| 196 | task = None |
| 197 | if task is None: |
| 198 | return {"status": 404, |
| 199 | "error": f"There is no task {task_id!r} on this server."} |
| 200 | is_admin = bool(identity.get("is_admin")) or "admin" in (identity.get("roles") or []) |
| 201 | if not is_admin and _text(task.get("owner_id")) != user_id: |
| 202 | return {"status": 403, |
| 203 | "error": "You can only run a template against a task you own."} |
| 204 | |
| 205 | form_data = request.get("form_data") |
| 206 | if isinstance(form_data, str): |
| 207 | try: |
| 208 | form_data = json.loads(form_data or "{}") |
| 209 | except ValueError: |
| 210 | return {"status": 400, "error": "form_data is not valid JSON."} |
| 211 | form_data = form_data if isinstance(form_data, dict) else {} |
| 212 | |
| 213 | found = object_template_runs.problems(template, form_data) |
| 214 | handler = _text(template.get("handler")) |
| 215 | if handler and handler not in KNOWN_HANDLERS: |
| 216 | found.append(f"'{handler}' is not a handler this server knows. " |
| 217 | f"Available: {', '.join(KNOWN_HANDLERS)}.") |
| 218 | if found: |
| 219 | return {"status": 400, "error": " ".join(found), "problems": found} |
| 220 | |
| 221 | # --- capability boundaries, refused while somebody is looking ------------ |
| 222 | model = "" |
| 223 | if handler in AI_HANDLERS: |
| 224 | model = _setting(base, MODEL_SETTING) |
| 225 | missing = [] |
| 226 | if not model or ":" not in model: |
| 227 | missing.append(f"set {MODEL_SETTING} in app_settings to " |
| 228 | f"'<service>:<model>' (e.g. 'anthropic:claude-sonnet-4-5')") |
| 229 | else: |
| 230 | service = model.split(":", 1)[0] |
| 231 | if not object_service_keys.get_service_key(user_id, service, |
| 232 | base_dir=base): |
| 233 | missing.append(f"store a {service} API key for {user_id} " |
| 234 | f"(Settings -> Service Keys)") |
| 235 | if missing: |
| 236 | return {"status": 409, |
| 237 | "error": ("This template runs on an AI provider, and this " |
| 238 | "server is not configured for one: " |
| 239 | + "; ".join(missing) + ". Nothing was queued " |
| 240 | "and nothing was charged."), |
| 241 | "problems": missing} |
| 242 | |
| 243 | stamped = object_template_runs.stamp(template, form_data, model=model) |
| 244 | price = int(stamped["price_cents"]) |
| 245 | run_id = object_ids.new_uuid4() |
| 246 | |
| 247 | # --- the hold, through the gate, before the run -------------------------- |
| 248 | wallet_id = "" |
| 249 | if price > 0: |
| 250 | wallet = _wallet_for(base, user_id) |
| 251 | if wallet is None: |
| 252 | return {"status": 409, |
| 253 | "error": (f"This template costs {price} cents to run and " |
| 254 | f"{user_id} has no active wallet to hold it " |
| 255 | f"against. Create a wallet and top it up first.")} |
| 256 | wallet_id = _text(wallet.get("id")) |
| 257 | hold = object_template_runs.hold_entry( |
| 258 | run_id, wallet_id, price, user_id, |
| 259 | template_name=stamped["template_name"]) |
| 260 | |
| 261 | verdict, error = _call("hook_wallet_entries", |
| 262 | {"action": "create", |
| 263 | "collection": "wallet_entries", |
| 264 | "record": hold}, |
| 265 | method="BEFORE_WRITE") |
| 266 | if error: |
| 267 | return {"status": 409, |
| 268 | "error": (f"The wallet gate could not be consulted " |
| 269 | f"({error}), so nothing was held and nothing " |
| 270 | f"was queued.")} |
| 271 | if isinstance(verdict, dict) and verdict.get("error"): |
| 272 | return {"status": int(verdict.get("status") or 402), |
| 273 | "error": _text(verdict.get("error"))} |
| 274 | |
| 275 | try: |
| 276 | object_records.create_collection_record( |
| 277 | "wallet_entries", hold, base_dir=base, actor=user_id) |
| 278 | except Exception as exc: |
| 279 | return {"status": 500, |
| 280 | "error": f"The hold could not be placed: {str(exc)[:160]}"} |
| 281 | |
| 282 | # --- the run -------------------------------------------------------------- |
| 283 | record = { |
| 284 | "id": run_id, |
| 285 | **stamped, |
| 286 | "task_id": task_id, |
| 287 | "status": "queued", |
| 288 | "idempotency_key": object_ids.new_uuid4(), |
| 289 | "wallet_id": wallet_id, |
| 290 | "owner_id": user_id, |
| 291 | } |
| 292 | try: |
| 293 | stored = object_records.create_collection_record( |
| 294 | RUNS, record, base_dir=base, actor=user_id) |
| 295 | except Exception as exc: |
| 296 | # The one wrong this ordering can leave is a hold with no run; give |
| 297 | # the money back now rather than leaving it to be noticed. |
| 298 | if price > 0: |
| 299 | for entry in object_template_runs.settlement( |
| 300 | {"id": run_id, "price_cents": str(price), |
| 301 | "wallet_id": wallet_id, "owner_id": user_id}, |
| 302 | succeeded=False): |
| 303 | try: |
| 304 | object_records.create_collection_record( |
| 305 | "wallet_entries", entry, base_dir=base, actor=ACTOR) |
| 306 | except Exception: |
| 307 | pass |
| 308 | return {"status": 500, |
| 309 | "error": f"The run could not be queued: {str(exc)[:160]}"} |
| 310 | |
| 311 | return {"ok": True, "run_id": run_id, "status": "queued", |
| 312 | "price_cents": price, "handler": handler, |
| 313 | "held": price > 0, |
| 314 | "note": ("Queued. The runner executes it on its next pass; the " |
| 315 | "hold settles when it finishes -- released in full plus " |
| 316 | "an ordinary debit on success, released alone on " |
| 317 | "failure." if price > 0 else |
| 318 | "Queued. Free to run, so no money was held.")} |