@withgateway/sdk 0.3.0 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -40,6 +40,15 @@ reads, writes, and whatever logic sits between them:
40
40
  not_found_status = 403 # when the vendor answers a missing row its own way
41
41
  cursor_absent_when_done = true # optional: overrides [api] for this route
42
42
 
43
+ [[operations]]
44
+ name = "list_works"
45
+ path = "/works"
46
+ params = ["query.bibliographic", "cursor"] # the vendor's names, dots and all
47
+ entity = "works"
48
+ [operations.api]
49
+ envelope = "message.items" # dotted: {message: {items, total-results, next-cursor}}
50
+ wrapper = '{"status": "ok", "message-type": "work-list"}' # the rest of the vendor's envelope
51
+
43
52
  [[operations]]
44
53
  name = "create_search"
45
54
  method = "POST"
@@ -76,15 +85,14 @@ and workflow transitions live, in the customer's world, never in this package.
76
85
  ``openapi.json``, ``seed/``, ``scenarios/``, ``server/``): the compiled world
77
86
  and this package are copied into ``server/`` so the container needs nothing
78
87
  installed, and the bundle root stays legacy-shaped because the api runner
79
- refuses a schema bundle at its root. The runner's admin endpoints
80
- (``/healthz``, ``/__world/seed``, ``/__world/reset``, ``/__world/state``) are
81
- served beside the vendor routes.
88
+ refuses a schema bundle at its root. ``serve`` answers the runner's admin
89
+ endpoints (``/__world/seed``, ``/__world/reset``, ``/__world/state``, ``/__world/calls``)
90
+ beside the vendor routes to its admin token only; a World Host session answers none of them.
82
91
  """
83
92
 
84
93
  from __future__ import annotations
85
94
 
86
95
  import base64
87
- import collections
88
96
  import importlib.util
89
97
  import json
90
98
  import os
@@ -97,38 +105,29 @@ import threading
97
105
  import time
98
106
  import urllib.parse
99
107
  import uuid
108
+ from contextlib import contextmanager
100
109
  from dataclasses import dataclass, field
101
110
  from datetime import datetime, timezone
102
- from enum import StrEnum
103
111
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
104
112
  from pathlib import Path
105
- from typing import Any, Callable
113
+ from typing import Any, Callable, Iterator
106
114
 
107
115
  from .._toml import tomllib
108
116
  from . import snapshot as snapshots
117
+ from .admin_routes import ADMIN, RUNNER_PATHS, AdminToken
109
118
  from .bundle_runtime import stage_runtime_package
119
+ from .call_log import AnswerShape, CallLog, Via
110
120
  from .compiler import check_bundle, compile_bundle
111
121
  from .connector import DEFAULT_TOKEN_PATH, SPEC, Operation, Spec, load_spec, stored_forms
112
122
  from .credentials import basic_user
123
+ from .database import WorldDatabase
124
+ from .database.matching import RowMatch, dig
125
+ from .envelope import Paging, page_headers, paginate, single, wrap
113
126
  from .grading import keyed_entities
114
- from .store import SQLiteStore
127
+ from .handler_errors import handled_answer, normalize_answer
128
+ from .primary_key import PrimaryKey
115
129
  from .validation import ContractError, fail, read_json
116
130
 
117
- ADMIN = {
118
- "seed": "/__world/seed",
119
- "reset": "/__world/reset",
120
- "state": "/__world/state",
121
- "calls": "/__world/calls",
122
- "health": "/healthz",
123
- }
124
-
125
- #: How many vendor-route requests a world keeps in its call log, unless
126
- #: ``WORLDS_CALL_LOG_MAX`` says otherwise; the oldest are dropped past it and
127
- #: ``total`` still counts every one. ``0`` keeps none. The log is what a grader
128
- #: reads to know what the agent ASKED (an investigation reads and never writes,
129
- #: so its rows tell nothing) and what ``/__world/calls`` serves.
130
- DEFAULT_CALL_LOG_MAX = 5000
131
- #: How many events :meth:`WorldState.emit` keeps for a page polling ``since``.
132
131
  EVENT_LOG_SIZE = 500
133
132
  PORT = 8080
134
133
  FILTER_KEY = "api"
@@ -139,41 +138,31 @@ ACTIONS = ("read", "create", "update", "delete", "handler")
139
138
  MATCHES = ("equals", "contains", "prefix")
140
139
  PAGING = ("none", "offset", "cursor")
141
140
  GENERATORS = ("uuid", "int", "now")
142
- #: Set to an epoch to freeze the world's clock (tests, reproducible workflows).
143
141
  CLOCK_ENV = "GATEWAY_WORLD_CLOCK"
144
- #: An ``[operations.api]`` setting left out inherits ``[api]``; distinct from None,
145
- #: which for an error body means "no body at all".
142
+ ROUTES_CLOSED = "this session's task lists the tools it may call, which closes the world's routes"
143
+ #: Distinct from None, which for an error body means "no body at all".
146
144
  INHERITED: Any = object()
147
145
 
148
146
 
149
- @dataclass(frozen=True)
150
- class Paging:
151
- style: str = "none"
152
- limit_param: str = "limit"
153
- offset_param: str = "offset"
154
- cursor_param: str = "cursor"
155
- page_size: int = 100
156
-
157
-
158
147
  @dataclass(frozen=True)
159
148
  class OperationSettings:
160
- filter: dict[str, str] = field(default_factory=dict) # arg -> row field path
161
- match: dict[str, str] = field(default_factory=dict) # arg -> equals | contains | prefix
149
+ filter: dict[str, str] = field(default_factory=dict)
150
+ match: dict[str, str] = field(default_factory=dict)
162
151
  action: str = "read"
163
152
  status: int = 200
164
- envelope: str | None = None # None inherits [api].envelope
153
+ envelope: str | None = None
165
154
  single: bool = False
166
- body: dict[str, str] = field(default_factory=dict) # row field <- body path; empty = the body as-is.
167
- # On a handler the world's own code reads the body; the mapping still tells the
168
- # generated ui which row fields its form asks for and where they go in the request.
155
+ body: dict[str, str] = field(default_factory=dict)
156
+ # A handler reads the body itself; the mapping still drives the generated ui's form.
169
157
  defaults: dict[str, Any] = field(default_factory=dict)
170
158
  generate: dict[str, str] = field(default_factory=dict)
171
159
  handler: str | None = None
172
- paging: str | None = None # None inherits [api].page
173
- sample: dict[str, str] = field(default_factory=dict) # arg -> a value the route accepts, for conformance runs
174
- not_found: Any = INHERITED # this route's own 404 body; INHERITED takes [api].not_found
175
- not_found_status: int | None = None # None inherits [api].not_found_status
176
- cursor_absent_when_done: bool | None = None # None inherits [api].cursor_absent_when_done
160
+ paging: str | None = None
161
+ sample: dict[str, str] = field(default_factory=dict)
162
+ not_found: Any = INHERITED
163
+ not_found_status: int | None = None
164
+ cursor_absent_when_done: bool | None = None
165
+ wrapper: dict | None = None
177
166
 
178
167
 
179
168
  @dataclass(frozen=True)
@@ -181,11 +170,8 @@ class UiSettings:
181
170
  """``[ui]`` in connector.toml: a prebuilt static single-page app shipped
182
171
  with the world and served by the World Host on the session's ui origin."""
183
172
 
184
- #: Directory in the world holding ``index.html`` and its assets.
185
173
  static: str
186
- #: The page an agent lands on first.
187
174
  entry: str = "/"
188
- #: Same-origin prefix the SPA calls the api at; the host rewrites it.
189
175
  api_path: str = "/__world-api"
190
176
 
191
177
 
@@ -194,22 +180,21 @@ class ApiSettings:
194
180
  envelope: str
195
181
  unauthorized: Any
196
182
  not_found: Any
197
- filters: dict[str, dict[str, str]] # operation -> {arg: row field path}; kept for callers that read it
198
183
  unauthorized_status: int = 401
199
184
  not_found_status: int = 404
200
185
  invalid: Any = None
201
186
  invalid_status: int = 400
202
187
  error_content_type: str = "application/json"
203
- hits_key: str = "hits" # "" leaves the count out of the envelope
188
+ hits_key: str = "hits"
204
189
  cursor_key: str = "cursor"
205
- cursor_absent_when_done: bool = False # drop the cursor key on the last page instead of sending "" / null
206
- previous_key: str | None = None # emit the previous page's cursor under this key (DRF's "previous")
207
- page_headers: dict[str, str] = field(default_factory=dict) # cursor | total | previous -> response header name
208
- page_links: bool = False # next/previous as absolute URLs of the served host, the way DRF answers
190
+ cursor_absent_when_done: bool = False
191
+ previous_key: str | None = None
192
+ page_headers: dict[str, str] = field(default_factory=dict)
193
+ page_links: bool = False
209
194
  paging: Paging = field(default_factory=Paging)
210
195
  token_path: str | None = None
211
196
  handlers: Path | None = None
212
- before: str | None = None # a function in the handlers module run before every operation
197
+ before: str | None = None
213
198
  operations: dict[str, OperationSettings] = field(default_factory=dict)
214
199
  ui: UiSettings | None = None
215
200
 
@@ -227,10 +212,24 @@ class ApiSettings:
227
212
  def omits_done_cursor(self, op: OperationSettings) -> bool:
228
213
  return self.cursor_absent_when_done if op.cursor_absent_when_done is None else op.cursor_absent_when_done
229
214
 
215
+ def answer_shape(self, op: OperationSettings, operation: Operation) -> AnswerShape:
216
+ """Where a route's answer carries its rows, as the route serves them: a list at its envelope
217
+ (the world's unless the route sets one), else at ``results``; a ``single`` row bare or at its
218
+ own envelope, at ``results`` only for a handler, whose answer is the vendor's own shape."""
219
+ if not op.single:
220
+ return AnswerShape(self.envelope if op.envelope is None else op.envelope, operation.results)
221
+ return AnswerShape(op.envelope or "", operation.results if op.action == "handler" else "", True)
222
+
223
+ def refusal(self, detail: Any = None) -> tuple[int, Any]:
224
+ body = self.invalid
225
+ if detail and isinstance(body, dict):
226
+ body = {**body, "detail": detail}
227
+ return self.invalid_status, body
228
+
230
229
 
231
230
  def _json_body(table: dict, key: str, default: Any, location: str) -> Any:
232
- """An error body setting: a JSON string replayed as given. ``""`` (like ``'null'``)
233
- means no body at all — a vendor that answers a bare 401 needs a way to say so."""
231
+ """A JSON setting written as a string (an error body, a route's ``wrapper``), used as given.
232
+ ``""`` (like ``'null'``) means none: a vendor that answers a bare 401 needs a way to say so."""
234
233
  text = table.get(key)
235
234
  if text is None:
236
235
  return default
@@ -340,8 +339,11 @@ def operation_api_settings(entry: dict, operation: Operation, location: str) ->
340
339
  default_status = {"create": 201, "delete": 204}.get(action, 200)
341
340
  status = _status(table, "status", default_status, location, low=200, high=299)
342
341
  envelope = table.get("envelope")
343
- if envelope is not None and not isinstance(envelope, str):
344
- fail("spec", "api.envelope must be a string", f"{location}/envelope")
342
+ if envelope is not None and (not isinstance(envelope, str) or (envelope and not all(envelope.split(".")))):
343
+ fail("spec", "api.envelope must be a dotted path such as message.items", f"{location}/envelope")
344
+ wrapper = _json_body(table, "wrapper", None, location)
345
+ if wrapper is not None and not isinstance(wrapper, dict):
346
+ fail("spec", "api.wrapper is a JSON object: the vendor's envelope around the rows", f"{location}/wrapper")
345
347
  single = table.get("single", action in ("create", "update"))
346
348
  if not isinstance(single, bool):
347
349
  fail("spec", "api.single must be true or false", f"{location}/single")
@@ -394,13 +396,11 @@ def operation_api_settings(entry: dict, operation: Operation, location: str) ->
394
396
  not_found=_json_body(table, "not_found", INHERITED, location),
395
397
  not_found_status=not_found_status,
396
398
  cursor_absent_when_done=cursor_absent_when_done,
399
+ wrapper=wrapper,
397
400
  )
398
401
 
399
402
 
400
- # Directory names every pusher (``bench push`` in Python and TypeScript, the
401
- # web upload) drops from a bundle at any depth, as build artifacts. A built ui
402
- # under one of them never reaches the hub, so the manifest refuses it here
403
- # rather than the host refusing every open of the version.
403
+ # Every pusher drops these at any depth, so a ui built under one never reaches the hub: refused here.
404
404
  ARCHIVE_DROPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
405
405
 
406
406
 
@@ -486,7 +486,6 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
486
486
  envelope=envelope,
487
487
  unauthorized=_json_body(api, "unauthorized", {"error": "unauthorized"}, "/api"),
488
488
  not_found=_json_body(api, "not_found", {"error": "not_found"}, "/api"),
489
- filters={name: dict(op.filter) for name, op in operations.items()},
490
489
  unauthorized_status=_status(api, "unauthorized_status", 401, "/api", low=400, high=599),
491
490
  not_found_status=_status(api, "not_found_status", 404, "/api", low=400, high=599),
492
491
  invalid=_json_body(api, "invalid", {"error": "invalid"}, "/api"),
@@ -510,23 +509,22 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
510
509
  class WorldState:
511
510
  """The store behind the served API.
512
511
 
513
- With a compiled snapshot in the tree (``db/state.sqlite`` whose sidecar names
514
- this contract) a reset is a file copy and an open; without one the world's
515
- initial batch is replayed, as it always was. ``snapshot`` is the sidecar of the
516
- snapshot in use, or None on the legacy path."""
512
+ With a compiled snapshot in the tree (``db/<snapshot name>`` holding the tree's data,
513
+ or the pin's, in rows this contract may open) a reset is a file copy and an open;
514
+ without one the world's initial batch is replayed, as it always was, except on a
515
+ pinned tree, whose data is only ever the hosted snapshot. ``snapshot`` is the
516
+ sidecar of the snapshot in use, or None on the legacy path."""
517
517
 
518
- def __init__(self, world: Path):
518
+ def __init__(self, world: Path, served: snapshots.ServedSnapshot | None = None):
519
+ served = served or snapshots.ServedSnapshot.of(world)
519
520
  self.world = world
520
- self.contract = check_bundle(world)
521
+ self.contract = served.contract
521
522
  self._initial: dict | None = None
522
- self._snapshot_path = snapshots.default_snapshot(world)
523
- # Only a snapshot that IS the tree's data through this contract (or the
524
- # platform's pin) is opened; one left behind by an earlier compile while the
525
- # journals grew is stale, and the journals are replayed instead.
526
- self.snapshot: dict | None = snapshots.current_default(world, self.contract)
523
+ self._snapshot_path = snapshots.default_snapshot(world, self.contract)
524
+ self.snapshot: dict | None = served.sidecar
527
525
  self._dir = tempfile.TemporaryDirectory(prefix="gateway-world-api-")
528
- self._lock = threading.Lock()
529
- self.store: SQLiteStore | None = None
526
+ self._lock = threading.RLock()
527
+ self.store: WorldDatabase | None = None
530
528
  self._clear_events()
531
529
  self.reset()
532
530
 
@@ -579,9 +577,9 @@ class WorldState:
579
577
  self.store.close()
580
578
  database = Path(self._dir.name) / f"{uuid.uuid4().hex}.db"
581
579
  if snapshot is not None:
582
- self.store = snapshots.open_copy(snapshot, self.contract, database)
580
+ self.store = WorldDatabase.open_copy(snapshot, self.contract, database)
583
581
  return
584
- self.store = SQLiteStore.create(database, self.contract)
582
+ self.store = WorldDatabase.create(database, self.contract)
585
583
  if initial:
586
584
  self.store.apply_batch(self.initial)
587
585
 
@@ -666,11 +664,9 @@ class WorldState:
666
664
  f"No scenario {name}; the world has {', '.join(scenarios) or 'none'}",
667
665
  f"/{SCENARIOS}/{name}",
668
666
  )
669
- built = snapshots.scenario_snapshot(self.world, name)
670
- if self.snapshot and snapshots.current(
671
- built,
672
- snapshots.contract_hash(self.contract),
673
- snapshots.scenario_batch_digest(scenarios[name], snapshots.expected_default_digest(self.world)),
667
+ built = snapshots.scenario_snapshot(self.world, name, self.contract)
668
+ if self.snapshot and snapshots.holds(
669
+ built, self.contract, snapshots.scenario_batch_digest(scenarios[name], self.digest)
674
670
  ):
675
671
  with self._lock:
676
672
  self._open(built)
@@ -696,6 +692,19 @@ class WorldState:
696
692
  assert self.store is not None
697
693
  return self.store.get(entity, key)
698
694
 
695
+ @contextmanager
696
+ def transaction(self) -> Iterator[None]:
697
+ """One route call: its writes and events all land, or none do."""
698
+ with self._lock:
699
+ assert self.store is not None
700
+ events, seq = list(self._events), self.event_seq
701
+ try:
702
+ with self.store.transaction():
703
+ yield
704
+ except BaseException:
705
+ self._events, self.event_seq = events, seq
706
+ raise
707
+
699
708
  def insert(self, entity: str, value: dict) -> dict:
700
709
  """Persist a row the API created; the contract validates it like any ingest."""
701
710
  with self._lock:
@@ -713,7 +722,7 @@ class WorldState:
713
722
  self.store.delete(entity, key, source={"record": "api.delete"})
714
723
 
715
724
  def key_of(self, entity: str, row: dict) -> dict:
716
- return {name: row.get(name) for name in self.contract.entities[entity]["primary_key"]}
725
+ return PrimaryKey.in_contract(self.contract, entity).key(row)
717
726
 
718
727
  def fields_of(self, entity: str) -> set[str]:
719
728
  schema = self.contract.entities[entity].get("schema") or {}
@@ -736,41 +745,6 @@ class WorldState:
736
745
  self._dir.cleanup()
737
746
 
738
747
 
739
- def _dig(row: Any, path: str) -> Any:
740
- for part in path.split("."):
741
- if not isinstance(row, dict) or part not in row:
742
- return None
743
- row = row[part]
744
- return row
745
-
746
-
747
- def _matches(
748
- row: dict,
749
- filters: dict[str, str],
750
- values: dict[str, str | list[str]],
751
- modes: dict[str, str] | None = None,
752
- ) -> bool:
753
- """Every filter whose argument was supplied must match; a parameter left out does not narrow.
754
-
755
- ``modes`` picks how: ``equals`` (default), ``contains`` (case-insensitive substring,
756
- the vendor's ``icontains``) or ``prefix``. A list field matches when any element does,
757
- and a parameter the client sent more than once (``status[]=a&status[]=b``) matches
758
- when any of its values does — the vendor's "any of" filter."""
759
- for arg, path in filters.items():
760
- if arg not in values:
761
- continue
762
- value = _dig(row, path)
763
- if value is None:
764
- return False
765
- mode = (modes or {}).get(arg, "equals")
766
- sent = values[arg]
767
- wanted = [w.lower() for w in (sent if isinstance(sent, list) else [sent])]
768
- candidates = value if isinstance(value, list) else [value]
769
- if not any(_compare(str(candidate).lower(), w, mode) for candidate in candidates for w in wanted):
770
- return False
771
- return True
772
-
773
-
774
748
  def _segment_filter(operation: Operation, ctx: ApiContext, entity: str) -> dict[str, str]:
775
749
  """The filter a route with no ``filter`` of its own implies: each ``{segment}`` of its
776
750
  path that names a top-level field of its entity narrows to the rows carrying that value
@@ -792,21 +766,12 @@ def _query_field_filter(ctx: ApiContext, entity: str, sent: dict[str, list[str]]
792
766
  return {name: name for name in sent if name in fields and name not in paging}
793
767
 
794
768
 
795
- def _compare(have: str, wanted: str, mode: str) -> bool:
796
- if mode == "contains":
797
- return wanted in have
798
- if mode == "prefix":
799
- return have.startswith(wanted)
800
- return have == wanted
801
-
802
-
803
769
  class Router:
804
770
  def __init__(self, spec: Spec, settings: ApiSettings):
805
771
  self.spec = spec
806
772
  self.settings = settings
807
773
  self.routes = [(operation, self._pattern(operation)) for operation in spec.operations.values()]
808
774
  self.tokens: set[str] = set()
809
- #: refresh token -> the subject it was minted for (password / refresh grants)
810
775
  self._refresh_tokens: dict[str, str] = {}
811
776
  self._jwt_secret = secrets.token_bytes(32)
812
777
  self._lock = threading.Lock()
@@ -878,20 +843,34 @@ class Router:
878
843
  def _issue_identity(self, subject: str) -> dict:
879
844
  """An ``id_token`` (HS256 JWT, one hour) and a ``refresh_token``, both
880
845
  remembered so later calls and refreshes are honoured."""
881
- import hmac
882
846
  import hashlib
847
+ import hmac
883
848
 
884
849
  now = int(time.time())
885
850
  header = base64.urlsafe_b64encode(b'{"alg":"HS256","typ":"JWT"}').rstrip(b"=").decode()
886
- payload = base64.urlsafe_b64encode(
887
- json.dumps(
888
- {"sub": subject, "iat": now, "exp": now + 3600, "iss": self.spec.slug, "jti": secrets.token_urlsafe(9)},
889
- separators=(",", ":"),
890
- ).encode()
891
- ).rstrip(b"=").decode()
892
- signature = base64.urlsafe_b64encode(
893
- hmac.new(self._jwt_secret, f"{header}.{payload}".encode(), hashlib.sha256).digest()
894
- ).rstrip(b"=").decode()
851
+ payload = (
852
+ base64.urlsafe_b64encode(
853
+ json.dumps(
854
+ {
855
+ "sub": subject,
856
+ "iat": now,
857
+ "exp": now + 3600,
858
+ "iss": self.spec.slug,
859
+ "jti": secrets.token_urlsafe(9),
860
+ },
861
+ separators=(",", ":"),
862
+ ).encode()
863
+ )
864
+ .rstrip(b"=")
865
+ .decode()
866
+ )
867
+ signature = (
868
+ base64.urlsafe_b64encode(
869
+ hmac.new(self._jwt_secret, f"{header}.{payload}".encode(), hashlib.sha256).digest()
870
+ )
871
+ .rstrip(b"=")
872
+ .decode()
873
+ )
895
874
  id_token = f"{header}.{payload}.{signature}"
896
875
  refresh = secrets.token_urlsafe(32)
897
876
  with self._lock:
@@ -939,12 +918,8 @@ class ApiContext:
939
918
  self.settings = router.settings
940
919
  self.operation = operation
941
920
  self.spec = router.spec
942
- #: (absolute URL without query, query) of the request being answered, for page links.
943
921
  self.link = link
944
- #: The request's headers, lower-cased — a gate reads the credential from here.
945
922
  self.headers: dict[str, str] = {}
946
- #: Every value of every query parameter, in order sent: ``{"expand[]": ["a", "b"]}``.
947
- #: The ``query`` a handler is passed keeps only the first, as most routes want.
948
923
  self.query_all: dict[str, list[str]] = {}
949
924
 
950
925
  def rows(self, entity: str) -> list[dict]:
@@ -955,7 +930,7 @@ class ApiContext:
955
930
 
956
931
  def find(self, entity: str, **fields: Any) -> list[dict]:
957
932
  wanted = {k: str(v) for k, v in fields.items()}
958
- return [row for row in self.state.rows(entity) if _matches(row, {k: k for k in wanted}, wanted)]
933
+ return RowMatch.on_fields(wanted).select(self.state.rows(entity))
959
934
 
960
935
  def insert(self, entity: str, value: dict) -> dict:
961
936
  return self.state.insert(entity, value)
@@ -1041,10 +1016,7 @@ class ApiContext:
1041
1016
  return self.settings.not_found_for(self.settings.for_operation(self.operation.name))
1042
1017
 
1043
1018
  def invalid(self, detail: str | None = None) -> tuple[int, Any]:
1044
- body = self.settings.invalid
1045
- if detail and isinstance(body, dict):
1046
- body = {**body, "detail": detail}
1047
- return self.settings.invalid_status, body
1019
+ return self.settings.refusal(detail)
1048
1020
 
1049
1021
 
1050
1022
  Handler = Callable[[ApiContext, dict[str, str], dict[str, str], Any], Any]
@@ -1088,143 +1060,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1088
1060
  return handlers
1089
1061
 
1090
1062
 
1091
- @dataclass(frozen=True)
1092
- class Page:
1093
- rows: list[dict]
1094
- total: int
1095
- offset: int
1096
- limit: int
1097
- style: str
1098
-
1099
- @property
1100
- def next_offset(self) -> int | None:
1101
- following = self.offset + self.limit
1102
- return following if self.style != "none" and following < self.total else None
1103
-
1104
- @property
1105
- def previous_offset(self) -> int | None:
1106
- return max(self.offset - self.limit, 0) if self.style != "none" and self.offset > 0 else None
1107
-
1108
-
1109
- def _encode_cursor(offset: int) -> str:
1110
- return base64.urlsafe_b64encode(str(offset).encode()).decode().rstrip("=")
1111
-
1112
-
1113
- def paginate(rows: list[dict], query: dict[str, str], paging: Paging) -> Page:
1114
- """One page of rows with the offsets the next and previous pages start at."""
1115
- total = len(rows)
1116
- if paging.style == "none":
1117
- return Page(rows, total, 0, total, "none")
1118
- limit = _int_param(query.get(paging.limit_param), paging.page_size)
1119
- offset = 0
1120
- if paging.style == "offset":
1121
- offset = _int_param(query.get(paging.offset_param), 0)
1122
- else:
1123
- raw = query.get(paging.cursor_param)
1124
- if raw:
1125
- try:
1126
- offset = int(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)).decode())
1127
- except (ValueError, UnicodeDecodeError):
1128
- offset = 0
1129
- return Page(rows[offset : offset + limit], total, offset, limit, paging.style)
1130
-
1131
-
1132
- def _int_param(value: str | None, default: int) -> int:
1133
- try:
1134
- parsed = int(value) if value is not None else default
1135
- except ValueError:
1136
- return default
1137
- return parsed if parsed >= 0 else default
1138
-
1139
-
1140
- def _page_ref(page: Page, offset: int | None, paging: Paging, link: tuple[str, dict[str, str]] | None) -> Any:
1141
- """What the vendor's client is handed for a neighbouring page: '' or None when there is
1142
- none, a cursor token, or — with ``page_links`` — the absolute URL DRF-style vendors answer."""
1143
- if offset is None:
1144
- return None if link is not None else ""
1145
- if link is None:
1146
- return _encode_cursor(offset)
1147
- base, query = link
1148
- following = dict(query)
1149
- if page.style == "offset":
1150
- following[paging.offset_param] = str(offset)
1151
- else:
1152
- following[paging.cursor_param] = _encode_cursor(offset)
1153
- following[paging.limit_param] = str(page.limit)
1154
- return f"{base}?{urllib.parse.urlencode(following)}"
1155
-
1156
-
1157
- def page_headers(page: Page, settings: ApiSettings, paging: Paging | None = None) -> dict[str, str] | None:
1158
- """The page's cursor/total/previous as response headers, when the vendor sends them that way."""
1159
- if not settings.page_headers:
1160
- return None
1161
- paging = paging or settings.paging
1162
- values = {
1163
- "cursor": _page_ref(page, page.next_offset, paging, None),
1164
- "total": str(page.total),
1165
- "previous": _page_ref(page, page.previous_offset, paging, None),
1166
- }
1167
- return {header: str(values[key]) for key, header in settings.page_headers.items() if values[key] not in ("", None)}
1168
-
1169
-
1170
- def wrap(
1171
- page: Page | list[dict],
1172
- settings: ApiSettings,
1173
- envelope: str | None = None,
1174
- *,
1175
- paging: Paging | None = None,
1176
- link: tuple[str, dict[str, str]] | None = None,
1177
- omit_done_cursor: bool = False,
1178
- ) -> Any:
1179
- """Rows in the vendor's envelope: ``{<envelope>: rows, <hits_key>: total, <cursor_key>: next
1180
- [, <previous_key>: previous]}``; an empty envelope key means the bare array, an empty
1181
- ``hits_key`` leaves the count out, and ``omit_done_cursor`` leaves the cursor key out
1182
- on the last page — together they make the ``{items, next_cursor?}`` shape vendors such
1183
- as Brex answer, which a client may check with ``"next_cursor" in body``."""
1184
- if not isinstance(page, Page):
1185
- page = Page(page, len(page), 0, len(page), "none")
1186
- key = settings.envelope if envelope is None else envelope
1187
- if not key:
1188
- return page.rows
1189
- paging = paging or settings.paging
1190
- link = link if settings.page_links else None
1191
- out = {key: page.rows}
1192
- if settings.hits_key:
1193
- out[settings.hits_key] = page.total
1194
- if page.next_offset is not None or not omit_done_cursor:
1195
- out[settings.cursor_key] = _page_ref(page, page.next_offset, paging, link)
1196
- if settings.previous_key:
1197
- out[settings.previous_key] = _page_ref(page, page.previous_offset, paging, link)
1198
- return out
1199
-
1200
-
1201
- def _normalize(result: Any, default_status: int | None) -> Any:
1202
- """What a handler (or the gate) hands back, as ``(status, body, headers)``.
1203
-
1204
- A handler returns a body, ``(status, body)`` or ``(status, body, headers)``;
1205
- the gate returns ``None`` to let the request through or one of those to stop it."""
1206
- if result is None and default_status is None:
1207
- return None
1208
- if (
1209
- isinstance(result, tuple)
1210
- and len(result) in (2, 3)
1211
- and isinstance(result[0], int)
1212
- and not isinstance(result[0], bool)
1213
- ):
1214
- status, body = result[0], result[1]
1215
- extra = result[2] if len(result) == 3 else None
1216
- if extra is not None and not (
1217
- isinstance(extra, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in extra.items())
1218
- ):
1219
- fail("handlers", "A handler's headers are a mapping of header names to strings", "/api/handlers")
1220
- if isinstance(body, bytes) and not any(k.lower() == "content-type" for k in extra or {}):
1221
- # Bytes go on the wire as they are (an event stream, a file); the
1222
- # handler says what they are, since the world's JSON type is not it.
1223
- fail("handlers", "A handler answering bytes names the Content-Type in its headers", "/api/handlers")
1224
- return status, body, extra
1225
- return default_status, result, None
1226
-
1227
-
1228
1063
  def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
1229
1064
  """Assign a dotted target (``attributes.note``), keeping the rest of a nested
1230
1065
  object an update leaves alone."""
@@ -1251,7 +1086,7 @@ def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | Non
1251
1086
  row: dict = json.loads(json.dumps(op.defaults)) if current is None else {}
1252
1087
  if op.body:
1253
1088
  for field_name, path in op.body.items():
1254
- value = _dig(body, path)
1089
+ value = dig(body, path)
1255
1090
  if value is not None:
1256
1091
  _set(row, field_name, value, current)
1257
1092
  else:
@@ -1289,7 +1124,7 @@ def vendor_credential(spec: Spec, presented: str, *, grant: str | None = None) -
1289
1124
  if spec.scheme == "query":
1290
1125
  return {}, {spec.auth_name or "api_key": presented}
1291
1126
  fail("spec", f"auth scheme '{spec.scheme}' has no credential shape to present", "/auth/scheme")
1292
- raise AssertionError # fail() never returns
1127
+ raise AssertionError
1293
1128
 
1294
1129
 
1295
1130
  def with_query(target: str, extra: dict[str, str]) -> str:
@@ -1305,140 +1140,15 @@ def with_query(target: str, extra: dict[str, str]) -> str:
1305
1140
  return urllib.parse.urlunsplit(url._replace(query=urllib.parse.urlencode(query)))
1306
1141
 
1307
1142
 
1308
- def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str, str, bytes]:
1309
- """``(method, target, raw body)`` of an operation called by name with a
1310
- tool call's ``args``, the way a session's ``call`` verb takes one:
1311
- ``args.path`` fills the route's ``{segments}`` (a top-level argument of
1312
- the segment's name does too, so ``get_wallet {"id": "W1"}`` reads as
1313
- ``/wallets/W1``), ``args.query`` is its query string, ``args.body`` (or
1314
- every other key, for a call written like a tool's) its JSON body; a GET
1315
- carries none. The target is under the spec's ``base_url`` path."""
1316
- path = operation.path
1317
- path_params = dict(args.get("path")) if isinstance(args.get("path"), dict) else {}
1318
- consumed: set[str] = set()
1319
- for name in operation.placeholders:
1320
- if name not in path_params and name in args and not isinstance(args[name], (dict, list)):
1321
- path_params[name] = args[name]
1322
- consumed.add(name)
1323
- for key, value in path_params.items():
1324
- path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
1325
- query = args.get("query") if isinstance(args.get("query"), dict) else {}
1326
- body = args.get("body") if isinstance(args.get("body"), dict) else None
1327
- leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body") and k not in consumed}
1328
- if operation.method == "GET" and leftovers:
1329
- # A GET carries no body: a call written like a tool's (``list_accounts {"status": "frozen"}``)
1330
- # means its query string, so the filter it asks for reaches the route.
1331
- query = {**{k: v for k, v in leftovers.items() if not isinstance(v, (dict, list))}, **query}
1332
- body = None
1333
- elif body is None:
1334
- body = leftovers or None
1335
- if query:
1336
- path = f"{path}?" + urllib.parse.urlencode({k: str(v) for k, v in query.items()})
1337
- raw = json.dumps(body).encode("utf-8") if body is not None and operation.method != "GET" else b""
1338
- base = urllib.parse.urlsplit(spec.base_url).path.rstrip("/")
1339
- return operation.method, f"{base}{path}", raw
1340
-
1341
-
1342
1143
  Response = tuple[int, Any, dict[str, str] | None]
1343
1144
 
1344
1145
 
1345
- def _strings_in(node: Any, out: list[str] | None = None) -> list[str]:
1346
- """Every string in a JSON value, however nested, once each, in document order."""
1347
- if out is None:
1348
- out = []
1349
- if isinstance(node, str):
1350
- if node not in out:
1351
- out.append(node)
1352
- elif isinstance(node, dict):
1353
- for value in node.values():
1354
- _strings_in(value, out)
1355
- elif isinstance(node, (list, tuple)):
1356
- for value in node:
1357
- _strings_in(value, out)
1358
- return out
1359
-
1360
-
1361
- class Via(StrEnum):
1362
- """The door a vendor-route request came in by, set by the server from where
1363
- it arrived and never from a request header. It names the door, not the
1364
- actor: a token holder calling the ui origin's prefix without a browser is
1365
- ``ui``."""
1366
-
1367
- API = "api"
1368
- UI = "ui"
1369
- TOOL = "tool"
1370
-
1371
-
1372
- class CallLog:
1373
- """The vendor-route requests one session answered, in order: what the agent
1374
- asked (operation, method, path, path args, query, body), the door it came
1375
- in by (``via``) and what came back (status, ``rows`` = the length of the
1376
- operation's ``results`` list when the answer carries one, elapsed).
1377
- ``selectors`` is every string the request carried wherever it sat, and
1378
- ``found`` is "answered with rows", so a grader's scalar ``where`` can ask
1379
- either without the vendor's request shape. Bounded; ``total`` counts past
1380
- the bound. ``/__world/calls`` serves it and a task's ``verify.py`` is
1381
- handed it as ``calls`` beside the rows, because a read-only investigation
1382
- leaves no row behind and its calls are the only evidence of what it did."""
1383
-
1384
- def __init__(self, maximum: int | None = None):
1385
- if maximum is None:
1386
- raw = os.environ.get("WORLDS_CALL_LOG_MAX")
1387
- maximum = int(raw) if raw else DEFAULT_CALL_LOG_MAX
1388
- self.maximum = max(0, int(maximum))
1389
- self.entries: collections.deque[dict] = collections.deque(maxlen=self.maximum or None)
1390
- self.total = 0
1391
- self._lock = threading.Lock()
1392
-
1393
- def record(
1394
- self,
1395
- operation: Operation,
1396
- method: str,
1397
- path: str,
1398
- args: dict,
1399
- query_all: dict,
1400
- body: Any,
1401
- status: int,
1402
- answer: Any,
1403
- elapsed_s: float,
1404
- via: Via | None,
1405
- ) -> None:
1406
- if self.maximum == 0:
1407
- return
1408
- rows = None
1409
- if isinstance(answer, dict) and isinstance(answer.get(operation.results), list):
1410
- rows = len(answer[operation.results])
1411
- elif isinstance(answer, list):
1412
- rows = len(answer)
1413
- query = {k: (v[0] if len(v) == 1 else list(v)) for k, v in query_all.items()}
1414
- entry = {
1415
- "seq": self.total + 1,
1416
- "at": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
1417
- "operation": operation.name,
1418
- "method": method,
1419
- "path": path,
1420
- "args": dict(args),
1421
- "query": query,
1422
- "body": body if isinstance(body, (dict, list)) and body else None,
1423
- "selectors": _strings_in([args, query, body]),
1424
- **({} if via is None else {"via": str(via)}),
1425
- "status": status,
1426
- "rows": rows,
1427
- "found": status < 400 and rows is not None and rows > 0,
1428
- "elapsed_ms": round(elapsed_s * 1000, 1),
1429
- }
1430
- with self._lock:
1431
- self.total += 1
1432
- self.entries.append(entry)
1146
+ class _Refused(Exception):
1147
+ """A route that answered an error: its writes are rolled back, its answer still sent."""
1433
1148
 
1434
- def describe(self) -> dict:
1435
- with self._lock:
1436
- return {"total": self.total, "kept": len(self.entries), "max": self.maximum, "calls": list(self.entries)}
1437
-
1438
- def clear(self) -> None:
1439
- with self._lock:
1440
- self.entries.clear()
1441
- self.total = 0
1149
+ def __init__(self, response: Response):
1150
+ super().__init__(response[0])
1151
+ self.response = response
1442
1152
 
1443
1153
 
1444
1154
  class WorldApp:
@@ -1448,7 +1158,16 @@ class WorldApp:
1448
1158
  headers, raw body) and answers ``(status, body, extra headers)``; nothing in
1449
1159
  it touches a socket. ``make_handler`` wraps it for ``serve()``, and the
1450
1160
  World Host calls it for whichever session a request names, so one process
1451
- can answer for many worlds without the handler knowing.
1161
+ can answer for many worlds without the handler knowing. ``routes_closed``:
1162
+ the session's task lists the tools it may call, so every route answers 403
1163
+ before any handler runs, and the list holds against a client calling the
1164
+ vendor API directly. ``calls`` is the session's call log, shared with its
1165
+ tools; a world served alone keeps its own.
1166
+
1167
+ ``admin`` serves the runner's ``/__world/*`` routes (state, calls, reset,
1168
+ seed) to the holder of its token, for the runner's bundle server (``serve()``)
1169
+ and a local session. A World Host session's doors carry the agent's token, and
1170
+ those routes read and rewrite what its grader reads, so the host passes none.
1452
1171
  """
1453
1172
 
1454
1173
  def __init__(
@@ -1457,20 +1176,19 @@ class WorldApp:
1457
1176
  router: Router,
1458
1177
  key: str | None,
1459
1178
  handlers: dict[str, Handler] | None = None,
1460
- allowed: frozenset[str] | None = None,
1461
- call_log_max: int | None = None,
1179
+ routes_closed: bool = False,
1180
+ calls: CallLog | None = None,
1181
+ admin: AdminToken | None = None,
1462
1182
  ):
1463
1183
  self.state = state
1464
1184
  self.router = router
1465
1185
  self.key = key
1186
+ self.admin = admin
1466
1187
  self.settings = router.settings
1467
1188
  self.prefix = urllib.parse.urlsplit(router.spec.base_url).path.rstrip("/")
1468
1189
  self.handlers = load_handlers(self.settings) if handlers is None else handlers
1469
- #: The operations this session's task allows, or None for all of them.
1470
- #: A route outside the list answers 403 before any handler runs, so the
1471
- #: list holds against a client that talks to the vendor API directly.
1472
- self.allowed = allowed
1473
- self.calls = CallLog(call_log_max)
1190
+ self.routes_closed = routes_closed
1191
+ self.calls = calls if calls is not None else CallLog.for_spec(router.spec)
1474
1192
 
1475
1193
  @staticmethod
1476
1194
  def _json(raw: bytes) -> Any:
@@ -1478,7 +1196,7 @@ class WorldApp:
1478
1196
  return {}
1479
1197
  try:
1480
1198
  return json.loads(raw.decode("utf-8"))
1481
- except (UnicodeDecodeError, json.JSONDecodeError):
1199
+ except (ValueError, RecursionError):
1482
1200
  return None
1483
1201
 
1484
1202
  @staticmethod
@@ -1500,7 +1218,7 @@ class WorldApp:
1500
1218
  if content_type == "application/json":
1501
1219
  try:
1502
1220
  parsed = json.loads(raw.decode("utf-8"))
1503
- except (UnicodeDecodeError, json.JSONDecodeError):
1221
+ except (ValueError, RecursionError):
1504
1222
  return {}
1505
1223
  return {k: str(v) for k, v in parsed.items()} if isinstance(parsed, dict) else {}
1506
1224
  form = {k: v[0] for k, v in urllib.parse.parse_qs(raw.decode("utf-8", "replace")).items()}
@@ -1526,47 +1244,59 @@ class WorldApp:
1526
1244
  a link uses when the request carries no Host header; ``via`` is the door
1527
1245
  the caller took it in by, recorded on the call when there is one."""
1528
1246
  url = urllib.parse.urlsplit(target)
1529
- settings, router, state = self.settings, self.router, self.state
1530
- if method == "GET":
1531
- if url.path == ADMIN["health"]:
1532
- return 200, {"ok": True, "world": router.spec.slug}, None
1533
- if url.path == ADMIN["state"]:
1534
- return 200, {**state.dump(), "snapshot": state.describe_snapshot(), "calls": self.calls.describe()["calls"]}, None
1535
- if url.path == ADMIN["calls"]:
1536
- return 200, self.calls.describe(), None
1537
- if method == "POST":
1538
- if url.path == ADMIN["reset"]:
1539
- state.reset()
1540
- return 200, {"ok": True}, None
1541
- if url.path == ADMIN["seed"]:
1542
- body = self._json(raw)
1543
- if body is None:
1544
- return 400, {"error": "seed must be JSON"}, None
1545
- try:
1546
- state.seed(body)
1547
- except ContractError as error:
1548
- if error.detail.get("code") == "base_mismatch":
1549
- return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
1550
- return 400, {"error": "seed_rejected", "detail": str(error)}, None
1551
- except Exception as error: # a rejected seed is the caller's problem, reported plainly
1552
- return 400, {"error": "seed_rejected", "detail": str(error)}, None
1553
- return 200, {"ok": True}, None
1554
- if settings.token_path and self._strip(url.path) == settings.token_path:
1555
- issued = router.issue_token(self._form(raw, headers), self.key)
1556
- if issued is None:
1557
- return 400, {"error": "invalid_client"}, None
1558
- return 200, issued, None
1247
+ settings, router = self.settings, self.router
1248
+ answered = self._admin(method, url.path, raw, headers)
1249
+ if answered is not None:
1250
+ return answered
1251
+ if method == "POST" and settings.token_path and self._strip(url.path) == settings.token_path:
1252
+ issued = router.issue_token(self._form(raw, headers), self.key)
1253
+ if issued is None:
1254
+ return 400, {"error": "invalid_client"}, None
1255
+ return 200, issued, None
1559
1256
  if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
1560
1257
  return 405, {"error": "method_not_allowed"}, None
1561
1258
  return self._route(method, url, headers, raw, default_host, via)
1562
1259
 
1260
+ def _admin(self, method: str, path: str, raw: bytes, headers: dict[str, str]) -> Response | None:
1261
+ """The runner's routes, or None for a request that is not one of them. Health answers on
1262
+ every door; the rest only where :attr:`admin` is set, and there only to its token."""
1263
+ state = self.state
1264
+ if (method, path) == ("GET", ADMIN["health"]):
1265
+ return 200, {"ok": True, "world": self.router.spec.slug}, None
1266
+ if self.admin is None or path not in RUNNER_PATHS:
1267
+ return None
1268
+ if not self.admin.admits(headers):
1269
+ return 403, {"error": "admin_token_required"}, None
1270
+ if (method, path) == ("GET", ADMIN["state"]):
1271
+ return 200, self.calls.into_state({**state.dump(), "snapshot": state.describe_snapshot()}), None
1272
+ if (method, path) == ("GET", ADMIN["calls"]):
1273
+ return 200, self.calls.describe(), None
1274
+ if (method, path) == ("POST", ADMIN["reset"]):
1275
+ state.reset()
1276
+ return 200, {"ok": True}, None
1277
+ if (method, path) == ("POST", ADMIN["seed"]):
1278
+ return self._seed(raw)
1279
+ return None
1280
+
1281
+ def _seed(self, raw: bytes) -> Response:
1282
+ body = self._json(raw)
1283
+ if body is None:
1284
+ return 400, {"error": "seed must be JSON"}, None
1285
+ try:
1286
+ self.state.seed(body)
1287
+ except ContractError as error:
1288
+ if error.detail.get("code") == "base_mismatch":
1289
+ return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
1290
+ return 400, {"error": "seed_rejected", "detail": str(error)}, None
1291
+ except Exception as error: # a rejected seed is the caller's problem, reported plainly
1292
+ return 400, {"error": "seed_rejected", "detail": str(error)}, None
1293
+ return 200, {"ok": True}, None
1294
+
1563
1295
  def _route(
1564
1296
  self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
1565
1297
  ) -> Response:
1566
1298
  settings, router = self.settings, self.router
1567
1299
  path = self._strip(url.path)
1568
- # Every value of a repeated key is kept; ``query`` hands routes the first, the way
1569
- # they always read it, and ``ctx.query_all`` hands handlers and filters the rest.
1570
1300
  query_all = {k: list(v) for k, v in urllib.parse.parse_qs(url.query).items()}
1571
1301
  query = {k: v[0] for k, v in query_all.items()}
1572
1302
  if not router.authorized(headers, query, self.key):
@@ -1575,40 +1305,51 @@ class WorldApp:
1575
1305
  if matched is None:
1576
1306
  return settings.not_found_status, settings.not_found, None
1577
1307
  operation, args = matched
1578
- if self.allowed is not None and operation.name not in self.allowed:
1579
- return 403, {"error": "tool_not_allowed", "tool": operation.name}, None
1308
+ if self.routes_closed:
1309
+ return 403, {"error": "route_not_allowed", "operation": operation.name, "detail": ROUTES_CLOSED}, None
1580
1310
  op = settings.for_operation(operation.name)
1581
1311
  body = self._body(raw, headers) if method in ("POST", "PUT", "PATCH") else {}
1582
1312
  if body is None:
1583
1313
  return settings.invalid_status, settings.invalid, None
1584
1314
  started = time.monotonic()
1585
- status, answer, extra = self._answer_route(op, operation, args, query, query_all, body, headers, url, default_host)
1586
- elapsed = time.monotonic() - started
1587
- self.calls.record(operation, method, path, args, query_all, body, status, answer, elapsed, via)
1315
+ status, answer, extra = 500, None, None
1316
+ try:
1317
+ status, answer, extra = self._answer_atomically(
1318
+ op, operation, args, query, query_all, body, headers, url, default_host
1319
+ )
1320
+ finally:
1321
+ elapsed = time.monotonic() - started
1322
+ shape = settings.answer_shape(op, operation)
1323
+ self.calls.record(operation, method, path, args, query_all, body, status, answer, elapsed, via, shape=shape)
1588
1324
  return status, answer, extra
1589
1325
 
1326
+ def _answer_atomically(self, *request) -> Response:
1327
+ try:
1328
+ with self.state.transaction():
1329
+ response = self._answer_route(*request)
1330
+ if response[0] >= 400:
1331
+ raise _Refused(response)
1332
+ except _Refused as refused:
1333
+ return refused.response
1334
+ except ContractError as error:
1335
+ return (*self.settings.refusal(getattr(error, "detail", None) or {"message": str(error)}), None)
1336
+ return response
1337
+
1590
1338
  def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
1591
- settings, router, state, handlers = self.settings, self.router, self.state, self.handlers
1339
+ router, state, handlers = self.router, self.state, self.handlers
1592
1340
  host = headers.get("host") or default_host
1593
1341
  forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
1594
1342
  ctx = ApiContext(state, router, operation, link=(f"{forwarded}://{host}{url.path}", query))
1595
1343
  ctx.headers = headers
1596
1344
  ctx.query_all = query_all
1597
- try:
1598
- if BEFORE in handlers:
1599
- # The world's gate: quotas, allow-lists, key states — whatever the vendor
1600
- # checks before any route, declarative ones included.
1601
- verdict = _normalize(handlers[BEFORE](ctx, args, query, body), None)
1602
- if verdict is not None:
1603
- return verdict
1604
- status, answer, extra = _normalize(self._answer(op, operation, ctx, args, query, body, handlers), op.status)
1605
- except ContractError as error:
1606
- detail = getattr(error, "detail", None) or {"message": str(error)}
1607
- invalid = settings.invalid
1608
- if isinstance(invalid, dict):
1609
- invalid = {**invalid, "detail": detail}
1610
- return settings.invalid_status, invalid, None
1611
- return status, answer, extra
1345
+ request = (ctx, args, query, body)
1346
+ gate = self.settings.before or BEFORE
1347
+ verdict = handled_answer(gate, handlers[BEFORE], request, None) if BEFORE in handlers else None
1348
+ if verdict is not None:
1349
+ return verdict
1350
+ if op.action == "handler":
1351
+ return handled_answer(op.handler or operation.name, handlers[operation.name], request, op.status)
1352
+ return normalize_answer(self._answer(op, operation, ctx, args, query, body), op.status)
1612
1353
 
1613
1354
  @staticmethod
1614
1355
  def _answer(
@@ -1618,34 +1359,32 @@ class WorldApp:
1618
1359
  args: dict[str, str],
1619
1360
  query: dict[str, str],
1620
1361
  body: Any,
1621
- handlers: dict[str, Handler],
1622
1362
  ) -> Any:
1623
- if op.action == "handler":
1624
- return handlers[operation.name](ctx, args, query, body)
1625
1363
  if not operation.entity:
1626
1364
  return 501, {"error": "not_modelled", "operation": operation.name}
1627
1365
  entity = operation.entity
1628
1366
  omit_done_cursor = ctx.settings.omits_done_cursor(op)
1629
1367
  if op.action == "create":
1630
1368
  row = ctx.insert(entity, _bind(op, ctx, body))
1631
- return op.status, row if op.single else wrap([row], ctx.settings, op.envelope)
1632
- filters = op.filter or _segment_filter(operation, ctx, entity)
1369
+ return op.status, _one(op, ctx, row)
1370
+ selection = op.filter or _segment_filter(operation, ctx, entity)
1371
+ if not selection and (op.action in ("update", "delete") or (op.single and operation.placeholders)):
1372
+ fail(
1373
+ "spec",
1374
+ f"route {operation.name} finds its row by nothing: its path names no field of {entity} and it "
1375
+ "declares no api.filter; map a path argument to a field with api.filter, or answer the route with "
1376
+ 'action = "handler"',
1377
+ f"/operations/{operation.name}/api/filter",
1378
+ )
1379
+ filters = selection
1633
1380
  if not op.filter and op.action == "read":
1634
1381
  filters = {**_query_field_filter(ctx, entity, ctx.query_all), **filters}
1635
- # A declared parameter filters on every value the client sent, so ``status[]=a&status[]=b``
1636
- # reads as "either", not as "a" with "b" silently dropped.
1382
+ # Every value sent filters: ``status[]=a&status[]=b`` reads as either, never as a with b dropped.
1637
1383
  values: dict[str, str | list[str]] = {
1638
1384
  **{k: v for k, v in ctx.query_all.items() if k in operation.params or k in filters},
1639
1385
  **args,
1640
1386
  }
1641
- if op.action in ("update", "delete") and not filters:
1642
- fail(
1643
- "spec",
1644
- f"route {operation.name} finds its row by nothing: its path names no primary-key field of {entity} "
1645
- f"and it declares no api.filter",
1646
- f"/operations/{operation.name}/api/filter",
1647
- )
1648
- rows = [row for row in ctx.rows(entity) if _matches(row, filters, values, op.match)]
1387
+ rows = RowMatch(filters, values, op.match or {}).select(ctx.rows(entity))
1649
1388
  if op.action in ("update", "delete"):
1650
1389
  if len(rows) != 1:
1651
1390
  return ctx.not_found()
@@ -1654,11 +1393,11 @@ class WorldApp:
1654
1393
  ctx.delete(entity, key)
1655
1394
  return op.status, None
1656
1395
  row = ctx.update(entity, key, _bind(op, ctx, body, current=rows[0]))
1657
- return op.status, row if op.single else wrap([row], ctx.settings, op.envelope)
1396
+ return op.status, _one(op, ctx, row)
1397
+ if op.single and not rows:
1398
+ return ctx.not_found()
1658
1399
  if op.single:
1659
- if not rows:
1660
- return ctx.not_found()
1661
- return op.status, rows[0]
1400
+ return op.status, single(rows[0], op.envelope, op.wrapper)
1662
1401
  paging = (
1663
1402
  ctx.settings.paging
1664
1403
  if op.paging is None
@@ -1673,11 +1412,26 @@ class WorldApp:
1673
1412
  page = paginate(rows, query, paging)
1674
1413
  return (
1675
1414
  op.status,
1676
- wrap(page, ctx.settings, op.envelope, paging=paging, link=ctx.link, omit_done_cursor=omit_done_cursor),
1415
+ wrap(
1416
+ page,
1417
+ ctx.settings,
1418
+ op.envelope,
1419
+ paging=paging,
1420
+ link=ctx.link,
1421
+ omit_done_cursor=omit_done_cursor,
1422
+ wrapper=op.wrapper,
1423
+ ),
1677
1424
  page_headers(page, ctx.settings, paging),
1678
1425
  )
1679
1426
 
1680
1427
 
1428
+ def _one(op: OperationSettings, ctx: ApiContext, row: dict) -> Any:
1429
+ """A written row answered the route's way: alone (at its own envelope), or as a list of one."""
1430
+ if op.single:
1431
+ return single(row, op.envelope, op.wrapper)
1432
+ return wrap([row], ctx.settings, op.envelope, wrapper=op.wrapper)
1433
+
1434
+
1681
1435
  def send_response(
1682
1436
  handler: BaseHTTPRequestHandler, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str
1683
1437
  ) -> None:
@@ -1691,7 +1445,6 @@ def send_response(
1691
1445
  return
1692
1446
  headers = dict(extra or {})
1693
1447
  if isinstance(body, bytes):
1694
- # As the handler shaped them, under the Content-Type it named (checked in _normalize).
1695
1448
  payload = body
1696
1449
  else:
1697
1450
  payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
@@ -1704,8 +1457,8 @@ def send_response(
1704
1457
  handler.wfile.write(payload)
1705
1458
 
1706
1459
 
1707
- def make_handler(state: WorldState, router: Router, key: str | None):
1708
- app = WorldApp(state, router, key)
1460
+ def make_handler(state: WorldState, router: Router, key: str | None, admin: AdminToken | None = None):
1461
+ app = WorldApp(state, router, key, admin=admin or AdminToken())
1709
1462
 
1710
1463
  class Handler(BaseHTTPRequestHandler):
1711
1464
  server_version = f"gateway-world-api/{router.spec.slug}"
@@ -1747,22 +1500,24 @@ def serve(
1747
1500
  host: str = "0.0.0.0",
1748
1501
  api_key: str | None = None,
1749
1502
  scenario: str | None = None,
1503
+ admin: AdminToken | None = None,
1750
1504
  ) -> ThreadingHTTPServer:
1751
- """Start the world's API and return the server; the caller decides how long it runs."""
1505
+ """Start the world's API and return the server; the caller decides how long it runs.
1506
+ ``admin`` admits its holder to the runner's ``/__world/*`` routes; without one they are refused."""
1752
1507
  root = Path(world)
1753
1508
  spec = load_spec(root)
1754
1509
  settings = load_api_settings(root, spec)
1755
1510
  state = WorldState(root)
1756
1511
  if scenario:
1757
1512
  state.apply_scenario(scenario)
1758
- server = ThreadingHTTPServer((host, port), make_handler(state, Router(spec, settings), api_key))
1759
- server.world_state = state # type: ignore[attr-defined]
1513
+ server = ThreadingHTTPServer((host, port), make_handler(state, Router(spec, settings), api_key, admin))
1514
+ server.world_state = state # type: ignore[attr-defined] # close() finds the state on its server
1760
1515
  return server
1761
1516
 
1762
1517
 
1763
1518
  def fetch_hosted_snapshot(world: str | Path, environ: dict[str, str] | None = None) -> dict | None:
1764
1519
  """The hosted pod's snapshot, when ``WORLD_SNAPSHOT_URL`` / ``_SHA256`` / ``_DIGEST``
1765
- are set: downloaded to ``db/state.sqlite``, verified, sidecar written. All three
1520
+ are set: downloaded to ``db/<snapshot name>``, verified, sidecar written. All three
1766
1521
  are required together; a digest mismatch is fatal and names the digest."""
1767
1522
  env = os.environ if environ is None else environ
1768
1523
  values = {name: env.get(name) for name in (snapshots.ENV_URL, snapshots.ENV_SHA256, snapshots.ENV_DIGEST)}
@@ -1791,13 +1546,13 @@ def serve_forever(
1791
1546
  raise SystemExit(2)
1792
1547
  if fetched:
1793
1548
  print(f"world snapshot {fetched['batchDigest']} opened", file=sys.stderr)
1794
- server = serve(world, port=port, api_key=api_key, scenario=scenario)
1549
+ server = serve(world, port=port, api_key=api_key, scenario=scenario, admin=AdminToken.from_env())
1795
1550
  try:
1796
1551
  print(f"world api listening on http://0.0.0.0:{port}", file=sys.stderr)
1797
1552
  server.serve_forever()
1798
1553
  finally:
1799
1554
  server.server_close()
1800
- server.world_state.close() # type: ignore[attr-defined]
1555
+ server.world_state.close() # type: ignore[attr-defined] # set by serve()
1801
1556
 
1802
1557
 
1803
1558
  def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
@@ -1840,14 +1595,11 @@ def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None
1840
1595
  ):
1841
1596
  entry["requestBody"] = {"content": {"application/json": {"schema": {"type": "object"}}}}
1842
1597
  if len(operation.methods) > 1:
1843
- # One OpenAPI operation, listed under the verb a capture sends; the
1844
- # others the served route also answers are named here.
1845
1598
  entry["x-gateway-methods"] = list(operation.methods)
1846
1599
  methods = paths.setdefault(operation.path, {})
1847
1600
  method = operation.method.lower()
1848
1601
  if method in methods:
1849
- # OpenAPI keys one operation per path+method; a vendor that tells lookups apart
1850
- # by query parameter keeps every one of them here rather than losing all but the first.
1602
+ # OpenAPI keys one operation per path+method, so query-parameter variants ride here, not lost.
1851
1603
  methods[method].setdefault("x-gateway-variants", []).append(
1852
1604
  {
1853
1605
  k: v
@@ -1926,8 +1678,7 @@ def build_api_bundle(world: str | Path, out: str | Path) -> Path:
1926
1678
  "",
1927
1679
  ]
1928
1680
  if settings.ui is not None:
1929
- # The built ui travels inside the copied world; the host serves it from
1930
- # there, so no ui image is ever built for a schema world.
1681
+ # The built ui ships inside the copied world, so no ui image is built for a schema world.
1931
1682
  manifest += [
1932
1683
  "[ui]",
1933
1684
  f'static = "server/world/{settings.ui.static}"',