@withgateway/sdk 0.3.1 → 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 (129) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2880 -2032
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2982 -2135
  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 +180 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +172 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  13. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1309 -540
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1287 -532
  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 +177 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +169 -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 +69 -13
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +69 -13
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +249 -120
  35. package/dist/worlds/index.d.ts +249 -120
  36. package/dist/worlds/index.js +1240 -484
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1231 -476
  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 -514
  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/compiler.py +334 -158
  57. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  58. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  59. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  60. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  61. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  62. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  63. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  64. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  65. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  66. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  67. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  68. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  69. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  70. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  71. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  72. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  73. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  74. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  75. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  76. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  77. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  78. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  79. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  80. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  81. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  82. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  83. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  84. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  86. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  87. package/runtime/gatewaysdk/environment/schema/platform.py +123 -171
  88. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  90. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  91. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  92. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  93. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  94. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  95. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  96. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -11
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +14 -14
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +12 -12
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  103. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  104. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  105. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  106. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  107. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  108. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  109. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  110. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  111. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  112. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  113. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  114. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  115. package/runtime/gatewaysdk/environment/score.py +57 -0
  116. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  117. package/runtime/gatewaysdk/environment/world.py +42 -3
  118. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  119. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  120. package/skills/connector-schema-authoring/SKILL.md +19 -11
  121. package/skills/connector-schema-authoring/connector-worlds.md +13 -4
  122. package/skills/connector-schema-authoring/world-schema.md +103 -51
  123. package/skills/world-data-ingestion/ROWS.md +29 -3
  124. package/skills/world-data-ingestion/SKILL.md +14 -14
  125. package/skills/worlds-getting-started/SKILL.md +12 -12
  126. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  127. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  128. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  129. 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:
@@ -927,11 +906,6 @@ class Router:
927
906
  return presented in self.tokens
928
907
  return key is None or presented == key
929
908
 
930
- def without_credential(self, query_all: dict) -> dict:
931
- """The query as the call log keeps it: a query-auth world's key is never recorded."""
932
- credential = self.spec.auth_name if self.spec.scheme == "query" else None
933
- return {k: v for k, v in query_all.items() if k != credential}
934
-
935
909
 
936
910
  class ApiContext:
937
911
  """What a world's handler gets: the store, the clock, and the vendor's shapes."""
@@ -944,12 +918,8 @@ class ApiContext:
944
918
  self.settings = router.settings
945
919
  self.operation = operation
946
920
  self.spec = router.spec
947
- #: (absolute URL without query, query) of the request being answered, for page links.
948
921
  self.link = link
949
- #: The request's headers, lower-cased — a gate reads the credential from here.
950
922
  self.headers: dict[str, str] = {}
951
- #: Every value of every query parameter, in order sent: ``{"expand[]": ["a", "b"]}``.
952
- #: The ``query`` a handler is passed keeps only the first, as most routes want.
953
923
  self.query_all: dict[str, list[str]] = {}
954
924
 
955
925
  def rows(self, entity: str) -> list[dict]:
@@ -960,7 +930,7 @@ class ApiContext:
960
930
 
961
931
  def find(self, entity: str, **fields: Any) -> list[dict]:
962
932
  wanted = {k: str(v) for k, v in fields.items()}
963
- 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))
964
934
 
965
935
  def insert(self, entity: str, value: dict) -> dict:
966
936
  return self.state.insert(entity, value)
@@ -1046,10 +1016,7 @@ class ApiContext:
1046
1016
  return self.settings.not_found_for(self.settings.for_operation(self.operation.name))
1047
1017
 
1048
1018
  def invalid(self, detail: str | None = None) -> tuple[int, Any]:
1049
- body = self.settings.invalid
1050
- if detail and isinstance(body, dict):
1051
- body = {**body, "detail": detail}
1052
- return self.settings.invalid_status, body
1019
+ return self.settings.refusal(detail)
1053
1020
 
1054
1021
 
1055
1022
  Handler = Callable[[ApiContext, dict[str, str], dict[str, str], Any], Any]
@@ -1093,143 +1060,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1093
1060
  return handlers
1094
1061
 
1095
1062
 
1096
- @dataclass(frozen=True)
1097
- class Page:
1098
- rows: list[dict]
1099
- total: int
1100
- offset: int
1101
- limit: int
1102
- style: str
1103
-
1104
- @property
1105
- def next_offset(self) -> int | None:
1106
- following = self.offset + self.limit
1107
- return following if self.style != "none" and following < self.total else None
1108
-
1109
- @property
1110
- def previous_offset(self) -> int | None:
1111
- return max(self.offset - self.limit, 0) if self.style != "none" and self.offset > 0 else None
1112
-
1113
-
1114
- def _encode_cursor(offset: int) -> str:
1115
- return base64.urlsafe_b64encode(str(offset).encode()).decode().rstrip("=")
1116
-
1117
-
1118
- def paginate(rows: list[dict], query: dict[str, str], paging: Paging) -> Page:
1119
- """One page of rows with the offsets the next and previous pages start at."""
1120
- total = len(rows)
1121
- if paging.style == "none":
1122
- return Page(rows, total, 0, total, "none")
1123
- limit = _int_param(query.get(paging.limit_param), paging.page_size)
1124
- offset = 0
1125
- if paging.style == "offset":
1126
- offset = _int_param(query.get(paging.offset_param), 0)
1127
- else:
1128
- raw = query.get(paging.cursor_param)
1129
- if raw:
1130
- try:
1131
- offset = int(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)).decode())
1132
- except (ValueError, UnicodeDecodeError):
1133
- offset = 0
1134
- return Page(rows[offset : offset + limit], total, offset, limit, paging.style)
1135
-
1136
-
1137
- def _int_param(value: str | None, default: int) -> int:
1138
- try:
1139
- parsed = int(value) if value is not None else default
1140
- except ValueError:
1141
- return default
1142
- return parsed if parsed >= 0 else default
1143
-
1144
-
1145
- def _page_ref(page: Page, offset: int | None, paging: Paging, link: tuple[str, dict[str, str]] | None) -> Any:
1146
- """What the vendor's client is handed for a neighbouring page: '' or None when there is
1147
- none, a cursor token, or — with ``page_links`` — the absolute URL DRF-style vendors answer."""
1148
- if offset is None:
1149
- return None if link is not None else ""
1150
- if link is None:
1151
- return _encode_cursor(offset)
1152
- base, query = link
1153
- following = dict(query)
1154
- if page.style == "offset":
1155
- following[paging.offset_param] = str(offset)
1156
- else:
1157
- following[paging.cursor_param] = _encode_cursor(offset)
1158
- following[paging.limit_param] = str(page.limit)
1159
- return f"{base}?{urllib.parse.urlencode(following)}"
1160
-
1161
-
1162
- def page_headers(page: Page, settings: ApiSettings, paging: Paging | None = None) -> dict[str, str] | None:
1163
- """The page's cursor/total/previous as response headers, when the vendor sends them that way."""
1164
- if not settings.page_headers:
1165
- return None
1166
- paging = paging or settings.paging
1167
- values = {
1168
- "cursor": _page_ref(page, page.next_offset, paging, None),
1169
- "total": str(page.total),
1170
- "previous": _page_ref(page, page.previous_offset, paging, None),
1171
- }
1172
- return {header: str(values[key]) for key, header in settings.page_headers.items() if values[key] not in ("", None)}
1173
-
1174
-
1175
- def wrap(
1176
- page: Page | list[dict],
1177
- settings: ApiSettings,
1178
- envelope: str | None = None,
1179
- *,
1180
- paging: Paging | None = None,
1181
- link: tuple[str, dict[str, str]] | None = None,
1182
- omit_done_cursor: bool = False,
1183
- ) -> Any:
1184
- """Rows in the vendor's envelope: ``{<envelope>: rows, <hits_key>: total, <cursor_key>: next
1185
- [, <previous_key>: previous]}``; an empty envelope key means the bare array, an empty
1186
- ``hits_key`` leaves the count out, and ``omit_done_cursor`` leaves the cursor key out
1187
- on the last page — together they make the ``{items, next_cursor?}`` shape vendors such
1188
- as Brex answer, which a client may check with ``"next_cursor" in body``."""
1189
- if not isinstance(page, Page):
1190
- page = Page(page, len(page), 0, len(page), "none")
1191
- key = settings.envelope if envelope is None else envelope
1192
- if not key:
1193
- return page.rows
1194
- paging = paging or settings.paging
1195
- link = link if settings.page_links else None
1196
- out = {key: page.rows}
1197
- if settings.hits_key:
1198
- out[settings.hits_key] = page.total
1199
- if page.next_offset is not None or not omit_done_cursor:
1200
- out[settings.cursor_key] = _page_ref(page, page.next_offset, paging, link)
1201
- if settings.previous_key:
1202
- out[settings.previous_key] = _page_ref(page, page.previous_offset, paging, link)
1203
- return out
1204
-
1205
-
1206
- def _normalize(result: Any, default_status: int | None) -> Any:
1207
- """What a handler (or the gate) hands back, as ``(status, body, headers)``.
1208
-
1209
- A handler returns a body, ``(status, body)`` or ``(status, body, headers)``;
1210
- the gate returns ``None`` to let the request through or one of those to stop it."""
1211
- if result is None and default_status is None:
1212
- return None
1213
- if (
1214
- isinstance(result, tuple)
1215
- and len(result) in (2, 3)
1216
- and isinstance(result[0], int)
1217
- and not isinstance(result[0], bool)
1218
- ):
1219
- status, body = result[0], result[1]
1220
- extra = result[2] if len(result) == 3 else None
1221
- if extra is not None and not (
1222
- isinstance(extra, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in extra.items())
1223
- ):
1224
- fail("handlers", "A handler's headers are a mapping of header names to strings", "/api/handlers")
1225
- if isinstance(body, bytes) and not any(k.lower() == "content-type" for k in extra or {}):
1226
- # Bytes go on the wire as they are (an event stream, a file); the
1227
- # handler says what they are, since the world's JSON type is not it.
1228
- fail("handlers", "A handler answering bytes names the Content-Type in its headers", "/api/handlers")
1229
- return status, body, extra
1230
- return default_status, result, None
1231
-
1232
-
1233
1063
  def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
1234
1064
  """Assign a dotted target (``attributes.note``), keeping the rest of a nested
1235
1065
  object an update leaves alone."""
@@ -1256,7 +1086,7 @@ def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | Non
1256
1086
  row: dict = json.loads(json.dumps(op.defaults)) if current is None else {}
1257
1087
  if op.body:
1258
1088
  for field_name, path in op.body.items():
1259
- value = _dig(body, path)
1089
+ value = dig(body, path)
1260
1090
  if value is not None:
1261
1091
  _set(row, field_name, value, current)
1262
1092
  else:
@@ -1294,7 +1124,7 @@ def vendor_credential(spec: Spec, presented: str, *, grant: str | None = None) -
1294
1124
  if spec.scheme == "query":
1295
1125
  return {}, {spec.auth_name or "api_key": presented}
1296
1126
  fail("spec", f"auth scheme '{spec.scheme}' has no credential shape to present", "/auth/scheme")
1297
- raise AssertionError # fail() never returns
1127
+ raise AssertionError
1298
1128
 
1299
1129
 
1300
1130
  def with_query(target: str, extra: dict[str, str]) -> str:
@@ -1310,140 +1140,15 @@ def with_query(target: str, extra: dict[str, str]) -> str:
1310
1140
  return urllib.parse.urlunsplit(url._replace(query=urllib.parse.urlencode(query)))
1311
1141
 
1312
1142
 
1313
- def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str, str, bytes]:
1314
- """``(method, target, raw body)`` of an operation called by name with a
1315
- tool call's ``args``, the way a session's ``call`` verb takes one:
1316
- ``args.path`` fills the route's ``{segments}`` (a top-level argument of
1317
- the segment's name does too, so ``get_wallet {"id": "W1"}`` reads as
1318
- ``/wallets/W1``), ``args.query`` is its query string, ``args.body`` (or
1319
- every other key, for a call written like a tool's) its JSON body; a GET
1320
- carries none. The target is under the spec's ``base_url`` path."""
1321
- path = operation.path
1322
- path_params = dict(args.get("path")) if isinstance(args.get("path"), dict) else {}
1323
- consumed: set[str] = set()
1324
- for name in operation.placeholders:
1325
- if name not in path_params and name in args and not isinstance(args[name], (dict, list)):
1326
- path_params[name] = args[name]
1327
- consumed.add(name)
1328
- for key, value in path_params.items():
1329
- path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
1330
- query = args.get("query") if isinstance(args.get("query"), dict) else {}
1331
- body = args.get("body") if isinstance(args.get("body"), dict) else None
1332
- leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body") and k not in consumed}
1333
- if operation.method == "GET" and leftovers:
1334
- # A GET carries no body: a call written like a tool's (``list_accounts {"status": "frozen"}``)
1335
- # means its query string, so the filter it asks for reaches the route.
1336
- query = {**{k: v for k, v in leftovers.items() if not isinstance(v, (dict, list))}, **query}
1337
- body = None
1338
- elif body is None:
1339
- body = leftovers or None
1340
- if query:
1341
- path = f"{path}?" + urllib.parse.urlencode({k: str(v) for k, v in query.items()})
1342
- raw = json.dumps(body).encode("utf-8") if body is not None and operation.method != "GET" else b""
1343
- base = urllib.parse.urlsplit(spec.base_url).path.rstrip("/")
1344
- return operation.method, f"{base}{path}", raw
1345
-
1346
-
1347
1143
  Response = tuple[int, Any, dict[str, str] | None]
1348
1144
 
1349
1145
 
1350
- def _strings_in(node: Any, out: list[str] | None = None) -> list[str]:
1351
- """Every string in a JSON value, however nested, once each, in document order."""
1352
- if out is None:
1353
- out = []
1354
- if isinstance(node, str):
1355
- if node not in out:
1356
- out.append(node)
1357
- elif isinstance(node, dict):
1358
- for value in node.values():
1359
- _strings_in(value, out)
1360
- elif isinstance(node, (list, tuple)):
1361
- for value in node:
1362
- _strings_in(value, out)
1363
- return out
1364
-
1365
-
1366
- class Via(StrEnum):
1367
- """The door a vendor-route request came in by, set by the server from where
1368
- it arrived and never from a request header. It names the door, not the
1369
- actor: a token holder calling the ui origin's prefix without a browser is
1370
- ``ui``."""
1371
-
1372
- API = "api"
1373
- UI = "ui"
1374
- TOOL = "tool"
1375
-
1376
-
1377
- class CallLog:
1378
- """The vendor-route requests one session answered, in order: what the agent
1379
- asked (operation, method, path, path args, query, body), the door it came
1380
- in by (``via``) and what came back (status, ``rows`` = the length of the
1381
- operation's ``results`` list when the answer carries one, elapsed).
1382
- ``selectors`` is every string the request carried wherever it sat, and
1383
- ``found`` is "answered with rows", so a grader's scalar ``where`` can ask
1384
- either without the vendor's request shape. Bounded; ``total`` counts past
1385
- the bound. ``/__world/calls`` serves it and a task's ``verify.py`` is
1386
- handed it as ``calls`` beside the rows, because a read-only investigation
1387
- leaves no row behind and its calls are the only evidence of what it did."""
1388
-
1389
- def __init__(self, maximum: int | None = None):
1390
- if maximum is None:
1391
- raw = os.environ.get("WORLDS_CALL_LOG_MAX")
1392
- maximum = int(raw) if raw else DEFAULT_CALL_LOG_MAX
1393
- self.maximum = max(0, int(maximum))
1394
- self.entries: collections.deque[dict] = collections.deque(maxlen=self.maximum or None)
1395
- self.total = 0
1396
- self._lock = threading.Lock()
1146
+ class _Refused(Exception):
1147
+ """A route that answered an error: its writes are rolled back, its answer still sent."""
1397
1148
 
1398
- def record(
1399
- self,
1400
- operation: Operation,
1401
- method: str,
1402
- path: str,
1403
- args: dict,
1404
- query_all: dict,
1405
- body: Any,
1406
- status: int,
1407
- answer: Any,
1408
- elapsed_s: float,
1409
- via: Via | None,
1410
- ) -> None:
1411
- if self.maximum == 0:
1412
- return
1413
- rows = None
1414
- if isinstance(answer, dict) and isinstance(answer.get(operation.results), list):
1415
- rows = len(answer[operation.results])
1416
- elif isinstance(answer, list):
1417
- rows = len(answer)
1418
- query = {k: (v[0] if len(v) == 1 else list(v)) for k, v in query_all.items()}
1419
- entry = {
1420
- "seq": self.total + 1,
1421
- "at": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
1422
- "operation": operation.name,
1423
- "method": method,
1424
- "path": path,
1425
- "args": dict(args),
1426
- "query": query,
1427
- "body": body if isinstance(body, (dict, list)) and body else None,
1428
- "selectors": _strings_in([args, query, body]),
1429
- **({} if via is None else {"via": str(via)}),
1430
- "status": status,
1431
- "rows": rows,
1432
- "found": status < 400 and rows is not None and rows > 0,
1433
- "elapsed_ms": round(elapsed_s * 1000, 1),
1434
- }
1435
- with self._lock:
1436
- self.total += 1
1437
- self.entries.append(entry)
1438
-
1439
- def describe(self) -> dict:
1440
- with self._lock:
1441
- return {"total": self.total, "kept": len(self.entries), "max": self.maximum, "calls": list(self.entries)}
1442
-
1443
- def clear(self) -> None:
1444
- with self._lock:
1445
- self.entries.clear()
1446
- self.total = 0
1149
+ def __init__(self, response: Response):
1150
+ super().__init__(response[0])
1151
+ self.response = response
1447
1152
 
1448
1153
 
1449
1154
  class WorldApp:
@@ -1453,7 +1158,16 @@ class WorldApp:
1453
1158
  headers, raw body) and answers ``(status, body, extra headers)``; nothing in
1454
1159
  it touches a socket. ``make_handler`` wraps it for ``serve()``, and the
1455
1160
  World Host calls it for whichever session a request names, so one process
1456
- 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.
1457
1171
  """
1458
1172
 
1459
1173
  def __init__(
@@ -1462,20 +1176,19 @@ class WorldApp:
1462
1176
  router: Router,
1463
1177
  key: str | None,
1464
1178
  handlers: dict[str, Handler] | None = None,
1465
- allowed: frozenset[str] | None = None,
1466
- call_log_max: int | None = None,
1179
+ routes_closed: bool = False,
1180
+ calls: CallLog | None = None,
1181
+ admin: AdminToken | None = None,
1467
1182
  ):
1468
1183
  self.state = state
1469
1184
  self.router = router
1470
1185
  self.key = key
1186
+ self.admin = admin
1471
1187
  self.settings = router.settings
1472
1188
  self.prefix = urllib.parse.urlsplit(router.spec.base_url).path.rstrip("/")
1473
1189
  self.handlers = load_handlers(self.settings) if handlers is None else handlers
1474
- #: The operations this session's task allows, or None for all of them.
1475
- #: A route outside the list answers 403 before any handler runs, so the
1476
- #: list holds against a client that talks to the vendor API directly.
1477
- self.allowed = allowed
1478
- 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)
1479
1192
 
1480
1193
  @staticmethod
1481
1194
  def _json(raw: bytes) -> Any:
@@ -1483,7 +1196,7 @@ class WorldApp:
1483
1196
  return {}
1484
1197
  try:
1485
1198
  return json.loads(raw.decode("utf-8"))
1486
- except (UnicodeDecodeError, json.JSONDecodeError):
1199
+ except (ValueError, RecursionError):
1487
1200
  return None
1488
1201
 
1489
1202
  @staticmethod
@@ -1505,7 +1218,7 @@ class WorldApp:
1505
1218
  if content_type == "application/json":
1506
1219
  try:
1507
1220
  parsed = json.loads(raw.decode("utf-8"))
1508
- except (UnicodeDecodeError, json.JSONDecodeError):
1221
+ except (ValueError, RecursionError):
1509
1222
  return {}
1510
1223
  return {k: str(v) for k, v in parsed.items()} if isinstance(parsed, dict) else {}
1511
1224
  form = {k: v[0] for k, v in urllib.parse.parse_qs(raw.decode("utf-8", "replace")).items()}
@@ -1531,40 +1244,54 @@ class WorldApp:
1531
1244
  a link uses when the request carries no Host header; ``via`` is the door
1532
1245
  the caller took it in by, recorded on the call when there is one."""
1533
1246
  url = urllib.parse.urlsplit(target)
1534
- settings, router, state = self.settings, self.router, self.state
1535
- if method == "GET":
1536
- if url.path == ADMIN["health"]:
1537
- return 200, {"ok": True, "world": router.spec.slug}, None
1538
- if url.path == ADMIN["state"]:
1539
- return 200, {**state.dump(), "snapshot": state.describe_snapshot(), "calls": self.calls.describe()["calls"]}, None
1540
- if url.path == ADMIN["calls"]:
1541
- return 200, self.calls.describe(), None
1542
- if method == "POST":
1543
- if url.path == ADMIN["reset"]:
1544
- state.reset()
1545
- return 200, {"ok": True}, None
1546
- if url.path == ADMIN["seed"]:
1547
- body = self._json(raw)
1548
- if body is None:
1549
- return 400, {"error": "seed must be JSON"}, None
1550
- try:
1551
- state.seed(body)
1552
- except ContractError as error:
1553
- if error.detail.get("code") == "base_mismatch":
1554
- return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
1555
- return 400, {"error": "seed_rejected", "detail": str(error)}, None
1556
- except Exception as error: # a rejected seed is the caller's problem, reported plainly
1557
- return 400, {"error": "seed_rejected", "detail": str(error)}, None
1558
- return 200, {"ok": True}, None
1559
- if settings.token_path and self._strip(url.path) == settings.token_path:
1560
- issued = router.issue_token(self._form(raw, headers), self.key)
1561
- if issued is None:
1562
- return 400, {"error": "invalid_client"}, None
1563
- 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
1564
1256
  if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
1565
1257
  return 405, {"error": "method_not_allowed"}, None
1566
1258
  return self._route(method, url, headers, raw, default_host, via)
1567
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
+
1568
1295
  def _route(
1569
1296
  self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
1570
1297
  ) -> Response:
@@ -1578,39 +1305,51 @@ class WorldApp:
1578
1305
  if matched is None:
1579
1306
  return settings.not_found_status, settings.not_found, None
1580
1307
  operation, args = matched
1581
- if self.allowed is not None and operation.name not in self.allowed:
1582
- 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
1583
1310
  op = settings.for_operation(operation.name)
1584
1311
  body = self._body(raw, headers) if method in ("POST", "PUT", "PATCH") else {}
1585
1312
  if body is None:
1586
1313
  return settings.invalid_status, settings.invalid, None
1587
1314
  started = time.monotonic()
1588
- status, answer, extra = self._answer_route(op, operation, args, query, query_all, body, headers, url, default_host)
1589
- elapsed = time.monotonic() - started
1590
- logged_query = router.without_credential(query_all)
1591
- self.calls.record(operation, method, path, args, logged_query, 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)
1592
1324
  return status, answer, extra
1593
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
+
1594
1338
  def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
1595
- settings, router, state, handlers = self.settings, self.router, self.state, self.handlers
1339
+ router, state, handlers = self.router, self.state, self.handlers
1596
1340
  host = headers.get("host") or default_host
1597
1341
  forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
1598
1342
  ctx = ApiContext(state, router, operation, link=(f"{forwarded}://{host}{url.path}", query))
1599
1343
  ctx.headers = headers
1600
1344
  ctx.query_all = query_all
1601
- try:
1602
- if BEFORE in handlers:
1603
- verdict = _normalize(handlers[BEFORE](ctx, args, query, body), None)
1604
- if verdict is not None:
1605
- return verdict
1606
- status, answer, extra = _normalize(self._answer(op, operation, ctx, args, query, body, handlers), op.status)
1607
- except ContractError as error:
1608
- detail = getattr(error, "detail", None) or {"message": str(error)}
1609
- invalid = settings.invalid
1610
- if isinstance(invalid, dict):
1611
- invalid = {**invalid, "detail": detail}
1612
- return settings.invalid_status, invalid, None
1613
- 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)
1614
1353
 
1615
1354
  @staticmethod
1616
1355
  def _answer(
@@ -1620,34 +1359,32 @@ class WorldApp:
1620
1359
  args: dict[str, str],
1621
1360
  query: dict[str, str],
1622
1361
  body: Any,
1623
- handlers: dict[str, Handler],
1624
1362
  ) -> Any:
1625
- if op.action == "handler":
1626
- return handlers[operation.name](ctx, args, query, body)
1627
1363
  if not operation.entity:
1628
1364
  return 501, {"error": "not_modelled", "operation": operation.name}
1629
1365
  entity = operation.entity
1630
1366
  omit_done_cursor = ctx.settings.omits_done_cursor(op)
1631
1367
  if op.action == "create":
1632
1368
  row = ctx.insert(entity, _bind(op, ctx, body))
1633
- return op.status, row if op.single else wrap([row], ctx.settings, op.envelope)
1634
- 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
1635
1380
  if not op.filter and op.action == "read":
1636
1381
  filters = {**_query_field_filter(ctx, entity, ctx.query_all), **filters}
1637
- # A declared parameter filters on every value the client sent, so ``status[]=a&status[]=b``
1638
- # 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.
1639
1383
  values: dict[str, str | list[str]] = {
1640
1384
  **{k: v for k, v in ctx.query_all.items() if k in operation.params or k in filters},
1641
1385
  **args,
1642
1386
  }
1643
- if op.action in ("update", "delete") and not filters:
1644
- fail(
1645
- "spec",
1646
- f"route {operation.name} finds its row by nothing: its path names no primary-key field of {entity} "
1647
- f"and it declares no api.filter",
1648
- f"/operations/{operation.name}/api/filter",
1649
- )
1650
- 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))
1651
1388
  if op.action in ("update", "delete"):
1652
1389
  if len(rows) != 1:
1653
1390
  return ctx.not_found()
@@ -1656,11 +1393,11 @@ class WorldApp:
1656
1393
  ctx.delete(entity, key)
1657
1394
  return op.status, None
1658
1395
  row = ctx.update(entity, key, _bind(op, ctx, body, current=rows[0]))
1659
- 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()
1660
1399
  if op.single:
1661
- if not rows:
1662
- return ctx.not_found()
1663
- return op.status, rows[0]
1400
+ return op.status, single(rows[0], op.envelope, op.wrapper)
1664
1401
  paging = (
1665
1402
  ctx.settings.paging
1666
1403
  if op.paging is None
@@ -1675,11 +1412,26 @@ class WorldApp:
1675
1412
  page = paginate(rows, query, paging)
1676
1413
  return (
1677
1414
  op.status,
1678
- 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
+ ),
1679
1424
  page_headers(page, ctx.settings, paging),
1680
1425
  )
1681
1426
 
1682
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
+
1683
1435
  def send_response(
1684
1436
  handler: BaseHTTPRequestHandler, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str
1685
1437
  ) -> None:
@@ -1705,8 +1457,8 @@ def send_response(
1705
1457
  handler.wfile.write(payload)
1706
1458
 
1707
1459
 
1708
- def make_handler(state: WorldState, router: Router, key: str | None):
1709
- 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())
1710
1462
 
1711
1463
  class Handler(BaseHTTPRequestHandler):
1712
1464
  server_version = f"gateway-world-api/{router.spec.slug}"
@@ -1748,22 +1500,24 @@ def serve(
1748
1500
  host: str = "0.0.0.0",
1749
1501
  api_key: str | None = None,
1750
1502
  scenario: str | None = None,
1503
+ admin: AdminToken | None = None,
1751
1504
  ) -> ThreadingHTTPServer:
1752
- """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."""
1753
1507
  root = Path(world)
1754
1508
  spec = load_spec(root)
1755
1509
  settings = load_api_settings(root, spec)
1756
1510
  state = WorldState(root)
1757
1511
  if scenario:
1758
1512
  state.apply_scenario(scenario)
1759
- server = ThreadingHTTPServer((host, port), make_handler(state, Router(spec, settings), api_key))
1760
- 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
1761
1515
  return server
1762
1516
 
1763
1517
 
1764
1518
  def fetch_hosted_snapshot(world: str | Path, environ: dict[str, str] | None = None) -> dict | None:
1765
1519
  """The hosted pod's snapshot, when ``WORLD_SNAPSHOT_URL`` / ``_SHA256`` / ``_DIGEST``
1766
- 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
1767
1521
  are required together; a digest mismatch is fatal and names the digest."""
1768
1522
  env = os.environ if environ is None else environ
1769
1523
  values = {name: env.get(name) for name in (snapshots.ENV_URL, snapshots.ENV_SHA256, snapshots.ENV_DIGEST)}
@@ -1792,13 +1546,13 @@ def serve_forever(
1792
1546
  raise SystemExit(2)
1793
1547
  if fetched:
1794
1548
  print(f"world snapshot {fetched['batchDigest']} opened", file=sys.stderr)
1795
- 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())
1796
1550
  try:
1797
1551
  print(f"world api listening on http://0.0.0.0:{port}", file=sys.stderr)
1798
1552
  server.serve_forever()
1799
1553
  finally:
1800
1554
  server.server_close()
1801
- server.world_state.close() # type: ignore[attr-defined]
1555
+ server.world_state.close() # type: ignore[attr-defined] # set by serve()
1802
1556
 
1803
1557
 
1804
1558
  def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
@@ -1845,8 +1599,7 @@ def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None
1845
1599
  methods = paths.setdefault(operation.path, {})
1846
1600
  method = operation.method.lower()
1847
1601
  if method in methods:
1848
- # OpenAPI keys one operation per path+method; a vendor that tells lookups apart
1849
- # 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.
1850
1603
  methods[method].setdefault("x-gateway-variants", []).append(
1851
1604
  {
1852
1605
  k: v
@@ -1925,8 +1678,7 @@ def build_api_bundle(world: str | Path, out: str | Path) -> Path:
1925
1678
  "",
1926
1679
  ]
1927
1680
  if settings.ui is not None:
1928
- # The built ui travels inside the copied world; the host serves it from
1929
- # 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.
1930
1682
  manifest += [
1931
1683
  "[ui]",
1932
1684
  f'static = "server/world/{settings.ui.static}"',