@withgateway/sdk 0.3.1 → 0.4.0

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 (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  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 +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. 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,20 +85,17 @@ 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
- import base64
87
- import collections
88
95
  import importlib.util
89
96
  import json
90
97
  import os
91
98
  import re
92
- import secrets
93
99
  import shutil
94
100
  import sys
95
101
  import tempfile
@@ -97,38 +103,35 @@ import threading
97
103
  import time
98
104
  import urllib.parse
99
105
  import uuid
106
+ from contextlib import contextmanager
100
107
  from dataclasses import dataclass, field
101
108
  from datetime import datetime, timezone
102
- from enum import StrEnum
103
- from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
109
+ from functools import partial
110
+ from http.server import ThreadingHTTPServer
104
111
  from pathlib import Path
105
- from typing import Any, Callable
112
+ from typing import Any, Callable, Iterator
106
113
 
107
114
  from .._toml import tomllib
108
115
  from . import snapshot as snapshots
116
+ from .admin_routes import ADMIN, RUNNER_PATHS, AdminToken
109
117
  from .bundle_runtime import stage_runtime_package
118
+ from .call_capture import Served, WorldRequestHandler, send_response
119
+ from .call_log import AnswerShape, CallLog, Via
110
120
  from .compiler import check_bundle, compile_bundle
111
- from .connector import DEFAULT_TOKEN_PATH, SPEC, Operation, Spec, load_spec, stored_forms
112
- from .credentials import basic_user
121
+ from .connector import SPEC, Operation, Spec, load_spec, stored_forms
122
+ from .cors import Cors
123
+ from .database import WorldDatabase
124
+ from .database.matching import RowMatch
125
+ from .declared_routes import DeclaredRoute, MisdeclaredRoute
126
+ from .door import Door, Entry
127
+ from .envelope import PageLink, Paging, page_headers, paginate, wrap
113
128
  from .grading import keyed_entities
114
- from .store import SQLiteStore
129
+ from .handler_errors import handled_answer, handler_bug_body, log_contract_refusal, normalize_answer
130
+ from .primary_key import PrimaryKey
131
+ from .request_body import RequestBody, Upload, json_value
132
+ from .route_miss import RouteMiss, served_methods
115
133
  from .validation import ContractError, fail, read_json
116
134
 
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
135
  EVENT_LOG_SIZE = 500
133
136
  PORT = 8080
134
137
  FILTER_KEY = "api"
@@ -139,41 +142,31 @@ ACTIONS = ("read", "create", "update", "delete", "handler")
139
142
  MATCHES = ("equals", "contains", "prefix")
140
143
  PAGING = ("none", "offset", "cursor")
141
144
  GENERATORS = ("uuid", "int", "now")
142
- #: Set to an epoch to freeze the world's clock (tests, reproducible workflows).
143
145
  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".
146
+ ROUTES_CLOSED = "this session's task lists the tools it may call, which closes the world's routes"
147
+ #: Distinct from None, which for an error body means "no body at all".
146
148
  INHERITED: Any = object()
147
149
 
148
150
 
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
151
  @dataclass(frozen=True)
159
152
  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
153
+ filter: dict[str, str] = field(default_factory=dict)
154
+ match: dict[str, str] = field(default_factory=dict)
162
155
  action: str = "read"
163
156
  status: int = 200
164
- envelope: str | None = None # None inherits [api].envelope
157
+ envelope: str | None = None
165
158
  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.
159
+ body: dict[str, str] = field(default_factory=dict)
160
+ # A handler reads the body itself; the mapping still drives the generated ui's form.
169
161
  defaults: dict[str, Any] = field(default_factory=dict)
170
162
  generate: dict[str, str] = field(default_factory=dict)
171
163
  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
164
+ paging: str | None = None
165
+ sample: dict[str, str] = field(default_factory=dict)
166
+ not_found: Any = INHERITED
167
+ not_found_status: int | None = None
168
+ cursor_absent_when_done: bool | None = None
169
+ wrapper: dict | None = None
177
170
 
178
171
 
179
172
  @dataclass(frozen=True)
@@ -181,11 +174,8 @@ class UiSettings:
181
174
  """``[ui]`` in connector.toml: a prebuilt static single-page app shipped
182
175
  with the world and served by the World Host on the session's ui origin."""
183
176
 
184
- #: Directory in the world holding ``index.html`` and its assets.
185
177
  static: str
186
- #: The page an agent lands on first.
187
178
  entry: str = "/"
188
- #: Same-origin prefix the SPA calls the api at; the host rewrites it.
189
179
  api_path: str = "/__world-api"
190
180
 
191
181
 
@@ -194,22 +184,26 @@ class ApiSettings:
194
184
  envelope: str
195
185
  unauthorized: Any
196
186
  not_found: Any
197
- filters: dict[str, dict[str, str]] # operation -> {arg: row field path}; kept for callers that read it
198
187
  unauthorized_status: int = 401
188
+ unauthorized_declared: bool = False
199
189
  not_found_status: int = 404
200
190
  invalid: Any = None
201
191
  invalid_status: int = 400
192
+ wrong_method: Any = None
193
+ wrong_method_status: int = 405
202
194
  error_content_type: str = "application/json"
203
- hits_key: str = "hits" # "" leaves the count out of the envelope
195
+ hits_key: str = "hits"
204
196
  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
197
+ cursor_absent_when_done: bool = False
198
+ previous_key: str | None = None
199
+ page_headers: dict[str, str] = field(default_factory=dict)
200
+ page_links: bool = False
201
+ link_header: bool = False
202
+ cors: Cors = field(default_factory=Cors)
209
203
  paging: Paging = field(default_factory=Paging)
210
204
  token_path: str | None = None
211
205
  handlers: Path | None = None
212
- before: str | None = None # a function in the handlers module run before every operation
206
+ before: str | None = None
213
207
  operations: dict[str, OperationSettings] = field(default_factory=dict)
214
208
  ui: UiSettings | None = None
215
209
 
@@ -227,10 +221,24 @@ class ApiSettings:
227
221
  def omits_done_cursor(self, op: OperationSettings) -> bool:
228
222
  return self.cursor_absent_when_done if op.cursor_absent_when_done is None else op.cursor_absent_when_done
229
223
 
224
+ def answer_shape(self, op: OperationSettings, operation: Operation) -> AnswerShape:
225
+ """Where a route's answer carries its rows, as the route serves them: a list at its envelope
226
+ (the world's unless the route sets one), else at ``results``; a ``single`` row bare or at its
227
+ own envelope, at ``results`` only for a handler, whose answer is the vendor's own shape."""
228
+ if not op.single:
229
+ return AnswerShape(self.envelope if op.envelope is None else op.envelope, operation.results)
230
+ return AnswerShape(op.envelope or "", operation.results if op.action == "handler" else "", True)
231
+
232
+ def refusal(self, detail: Any = None) -> tuple[int, Any]:
233
+ body = self.invalid
234
+ if detail and isinstance(body, dict):
235
+ body = {**body, "detail": detail}
236
+ return self.invalid_status, body
237
+
230
238
 
231
239
  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."""
240
+ """A JSON setting written as a string (an error body, a route's ``wrapper``), used as given.
241
+ ``""`` (like ``'null'``) means none: a vendor that answers a bare 401 needs a way to say so."""
234
242
  text = table.get(key)
235
243
  if text is None:
236
244
  return default
@@ -340,8 +348,11 @@ def operation_api_settings(entry: dict, operation: Operation, location: str) ->
340
348
  default_status = {"create": 201, "delete": 204}.get(action, 200)
341
349
  status = _status(table, "status", default_status, location, low=200, high=299)
342
350
  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")
351
+ if envelope is not None and (not isinstance(envelope, str) or (envelope and not all(envelope.split(".")))):
352
+ fail("spec", "api.envelope must be a dotted path such as message.items", f"{location}/envelope")
353
+ wrapper = _json_body(table, "wrapper", None, location)
354
+ if wrapper is not None and not isinstance(wrapper, dict):
355
+ fail("spec", "api.wrapper is a JSON object: the vendor's envelope around the rows", f"{location}/wrapper")
345
356
  single = table.get("single", action in ("create", "update"))
346
357
  if not isinstance(single, bool):
347
358
  fail("spec", "api.single must be true or false", f"{location}/single")
@@ -394,13 +405,10 @@ def operation_api_settings(entry: dict, operation: Operation, location: str) ->
394
405
  not_found=_json_body(table, "not_found", INHERITED, location),
395
406
  not_found_status=not_found_status,
396
407
  cursor_absent_when_done=cursor_absent_when_done,
408
+ wrapper=wrapper,
397
409
  )
398
410
 
399
411
 
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.
404
412
  ARCHIVE_DROPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
405
413
 
406
414
 
@@ -456,10 +464,6 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
456
464
  token_path = api.get("token_path")
457
465
  if token_path is not None and (not isinstance(token_path, str) or not token_path.startswith("/")):
458
466
  fail("spec", "api.token_path is the path the world mints tokens on", "/api/token_path")
459
- if token_path is not None and spec.scheme != "oauth2":
460
- fail("spec", "api.token_path belongs to auth.scheme oauth2", "/api/token_path")
461
- if spec.scheme == "oauth2" and token_path is None:
462
- token_path = spec.token_url if (spec.token_url or "").startswith("/") else DEFAULT_TOKEN_PATH
463
467
  handlers_name = api.get("handlers")
464
468
  if handlers_name is not None and not isinstance(handlers_name, str):
465
469
  fail("spec", "api.handlers is the path of the world's handlers module", "/api/handlers")
@@ -486,11 +490,13 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
486
490
  envelope=envelope,
487
491
  unauthorized=_json_body(api, "unauthorized", {"error": "unauthorized"}, "/api"),
488
492
  not_found=_json_body(api, "not_found", {"error": "not_found"}, "/api"),
489
- filters={name: dict(op.filter) for name, op in operations.items()},
490
493
  unauthorized_status=_status(api, "unauthorized_status", 401, "/api", low=400, high=599),
494
+ unauthorized_declared="unauthorized" in api or "unauthorized_status" in api,
491
495
  not_found_status=_status(api, "not_found_status", 404, "/api", low=400, high=599),
492
496
  invalid=_json_body(api, "invalid", {"error": "invalid"}, "/api"),
493
497
  invalid_status=_status(api, "invalid_status", 400, "/api", low=400, high=599),
498
+ wrong_method=_json_body(api, "wrong_method", None, "/api"),
499
+ wrong_method_status=_status(api, "wrong_method_status", 405, "/api", low=400, high=599),
494
500
  error_content_type=_name(api, "error_content_type", "application/json", "/api"),
495
501
  hits_key=_key_name(api, "hits_key", "hits"),
496
502
  cursor_key=_name(api, "cursor_key", "cursor", "/api"),
@@ -498,8 +504,10 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
498
504
  previous_key=_name(api, "previous_key", "", "/api") if api.get("previous_key") is not None else None,
499
505
  page_headers=_page_headers(api),
500
506
  page_links=_flag(api, "page_links", "/api"),
507
+ link_header=_flag(api, "link_header", "/api"),
508
+ cors=Cors.of(_flag(api, "cors", "/api"), served_methods(spec.operations.values())),
501
509
  paging=paging,
502
- token_path=token_path,
510
+ token_path=spec.auth.token_path(token_path, spec.operations, "/api"),
503
511
  handlers=handlers if handlers.is_file() else None,
504
512
  before=before,
505
513
  operations=operations,
@@ -510,23 +518,22 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
510
518
  class WorldState:
511
519
  """The store behind the served API.
512
520
 
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."""
521
+ With a compiled snapshot in the tree (``db/<snapshot name>`` holding the tree's data,
522
+ or the pin's, in rows this contract may open) a reset is a file copy and an open;
523
+ without one the world's initial batch is replayed, as it always was, except on a
524
+ pinned tree, whose data is only ever the hosted snapshot. ``snapshot`` is the
525
+ sidecar of the snapshot in use, or None on the legacy path."""
517
526
 
518
- def __init__(self, world: Path):
527
+ def __init__(self, world: Path, served: snapshots.ServedSnapshot | None = None):
528
+ served = served or snapshots.ServedSnapshot.of(world)
519
529
  self.world = world
520
- self.contract = check_bundle(world)
530
+ self.contract = served.contract
521
531
  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)
532
+ self._snapshot_path = served.path
533
+ self.snapshot: dict | None = served.sidecar
527
534
  self._dir = tempfile.TemporaryDirectory(prefix="gateway-world-api-")
528
- self._lock = threading.Lock()
529
- self.store: SQLiteStore | None = None
535
+ self._lock = threading.RLock()
536
+ self.store: WorldDatabase | None = None
530
537
  self._clear_events()
531
538
  self.reset()
532
539
 
@@ -579,9 +586,9 @@ class WorldState:
579
586
  self.store.close()
580
587
  database = Path(self._dir.name) / f"{uuid.uuid4().hex}.db"
581
588
  if snapshot is not None:
582
- self.store = snapshots.open_copy(snapshot, self.contract, database)
589
+ self.store = WorldDatabase.open_copy(snapshot, self.contract, database)
583
590
  return
584
- self.store = SQLiteStore.create(database, self.contract)
591
+ self.store = WorldDatabase.create(database, self.contract)
585
592
  if initial:
586
593
  self.store.apply_batch(self.initial)
587
594
 
@@ -666,11 +673,9 @@ class WorldState:
666
673
  f"No scenario {name}; the world has {', '.join(scenarios) or 'none'}",
667
674
  f"/{SCENARIOS}/{name}",
668
675
  )
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)),
676
+ built = snapshots.scenario_snapshot(self.world, name, self.contract)
677
+ if self.snapshot and snapshots.holds(
678
+ built, self.contract, snapshots.scenario_batch_digest(scenarios[name], self.digest)
674
679
  ):
675
680
  with self._lock:
676
681
  self._open(built)
@@ -696,6 +701,24 @@ class WorldState:
696
701
  assert self.store is not None
697
702
  return self.store.get(entity, key)
698
703
 
704
+ def select(self, entity: str, match: RowMatch, limit: int | None, offset: int) -> tuple[list[dict], int]:
705
+ with self._lock:
706
+ assert self.store is not None
707
+ return self.store.select(entity, match, limit, offset)
708
+
709
+ @contextmanager
710
+ def transaction(self) -> Iterator[None]:
711
+ """One route call: its writes and events all land, or none do."""
712
+ with self._lock:
713
+ assert self.store is not None
714
+ events, seq = list(self._events), self.event_seq
715
+ try:
716
+ with self.store.transaction():
717
+ yield
718
+ except BaseException:
719
+ self._events, self.event_seq = events, seq
720
+ raise
721
+
699
722
  def insert(self, entity: str, value: dict) -> dict:
700
723
  """Persist a row the API created; the contract validates it like any ingest."""
701
724
  with self._lock:
@@ -713,7 +736,7 @@ class WorldState:
713
736
  self.store.delete(entity, key, source={"record": "api.delete"})
714
737
 
715
738
  def key_of(self, entity: str, row: dict) -> dict:
716
- return {name: row.get(name) for name in self.contract.entities[entity]["primary_key"]}
739
+ return PrimaryKey.in_contract(self.contract, entity).key(row)
717
740
 
718
741
  def fields_of(self, entity: str) -> set[str]:
719
742
  schema = self.contract.entities[entity].get("schema") or {}
@@ -736,221 +759,68 @@ class WorldState:
736
759
  self._dir.cleanup()
737
760
 
738
761
 
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
- def _segment_filter(operation: Operation, ctx: ApiContext, entity: str) -> dict[str, str]:
775
- """The filter a route with no ``filter`` of its own implies: each ``{segment}`` of its
776
- path that names a top-level field of its entity narrows to the rows carrying that value
777
- (``GET /wallets/{id}``, ``GET /records/by-email/{email}``). A segment naming no field
778
- (``/users/{userId}/labels``, a scope the caller must send) implies nothing; a declared
779
- ``filter`` says it all itself. Twin: ``route_bindings.implied_filters``."""
780
- fields = ctx.fields_of(entity)
781
- return {name: name for name in operation.placeholders if name in fields}
782
-
783
-
784
- def _query_field_filter(ctx: ApiContext, entity: str, sent: dict[str, list[str]]) -> dict[str, str]:
785
- """What a read route with no ``filter`` implies from its query string: each
786
- parameter that names a top-level field of the entity narrows to rows carrying
787
- that value (``GET /accounts?status=frozen``), the way every vendor's list
788
- endpoint reads. Paging parameters and names the entity does not declare are
789
- left to the pager and the handler."""
790
- fields = ctx.fields_of(entity)
791
- paging = {ctx.settings.paging.limit_param, ctx.settings.paging.offset_param, ctx.settings.paging.cursor_param}
792
- return {name: name for name in sent if name in fields and name not in paging}
793
-
794
-
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
762
  class Router:
763
+ """The routes of connector.toml, matched against a request."""
764
+
804
765
  def __init__(self, spec: Spec, settings: ApiSettings):
805
766
  self.spec = spec
806
767
  self.settings = settings
807
- self.routes = [(operation, self._pattern(operation)) for operation in spec.operations.values()]
808
- self.tokens: set[str] = set()
809
- #: refresh token -> the subject it was minted for (password / refresh grants)
810
- self._refresh_tokens: dict[str, str] = {}
811
- self._jwt_secret = secrets.token_bytes(32)
812
- self._lock = threading.Lock()
813
-
814
- @staticmethod
815
- def _pattern(operation: Operation) -> re.Pattern:
816
- escaped = re.escape(operation.path)
817
- pattern = re.sub(r"\\\{([A-Za-z_][A-Za-z0-9_]*)\\\}", r"(?P<\1>[^/]+)", escaped)
818
- return re.compile(f"^{pattern}$")
819
-
820
- def match(self, method: str, path: str, query: dict[str, str]) -> tuple[Operation, dict[str, str]] | None:
821
- """The operation for a request. Vendors reuse one path for several lookups that
822
- differ only by query parameter, so among path matches the one whose declared
823
- parameters the caller actually sent wins; ties keep declaration order."""
768
+ self.routes = [(operation, operation.pattern) for operation in spec.operations.values()]
769
+
770
+ def match(
771
+ self, method: str, path: str, query: dict[str, str], within: tuple[str, ...] | None = None
772
+ ) -> tuple[Operation, dict[str, str]] | RouteMiss:
773
+ """The operation for a request, among the operations ``within`` names when given, or how it
774
+ missed. Vendors reuse one path for several lookups that differ only by query parameter, so
775
+ among path matches the one whose declared parameters the caller actually sent wins; ties keep
776
+ declaration order."""
824
777
  best: tuple[int, int, Operation, dict[str, str]] | None = None
778
+ on_path: list[Operation] = []
825
779
  for index, (operation, pattern) in enumerate(self.routes):
826
780
  found = pattern.match(path)
827
- if not found or method not in operation.methods:
781
+ if not found or (within is not None and operation.name not in within):
782
+ continue
783
+ on_path.append(operation)
784
+ if method not in operation.methods:
828
785
  continue
829
786
  present = sum(1 for name in operation.params if name in query)
830
787
  candidate = (present, -index, operation, {k: urllib.parse.unquote(v) for k, v in found.groupdict().items()})
831
788
  if best is None or candidate[:2] > best[:2]:
832
789
  best = candidate
833
- return None if best is None else (best[2], best[3])
834
-
835
- def issue_token(self, form: dict[str, str], key: str | None) -> dict | None:
836
- """The vendor's token endpoint. Three grants, the way real vendors mint:
837
-
838
- * ``client_credentials`` (the default): a bearer ``access_token``.
839
- * ``password``: ``email`` + ``password`` in, an ``id_token`` (an HS256 JWT
840
- carrying ``sub``/``iat``/``exp``, so a client that reads expiry from the
841
- token itself sees a real one) plus a ``refresh_token``. This is how
842
- Torchlight's clients authenticate.
843
- * ``refresh_token``: a refresh token this world minted in, a fresh
844
- ``id_token`` + ``refresh_token`` out; an unknown refresh token is refused.
845
-
846
- With ``WORLD_API_KEY`` pinned the client secret (or the password) must be that
847
- key, the way a real vendor knows its clients; unpinned, any grant is served.
848
- Every bearer this world minted — access or id token — authorizes calls."""
849
- grant = form.get("grant_type", "client_credentials")
850
- if grant == "client_credentials":
851
- if key is not None and form.get("client_secret") != key:
852
- return None
853
- token = secrets.token_urlsafe(32)
854
- with self._lock:
855
- self.tokens.add(token)
856
- answer = {"access_token": token, "token_type": "Bearer", "expires_in": 3600}
857
- if form.get("scope"):
858
- answer["scope"] = form["scope"]
859
- elif self.spec.scope:
860
- answer["scope"] = self.spec.scope
861
- return answer
862
- if grant == "password":
863
- subject = form.get("email") or form.get("username") or ""
864
- if not subject or not form.get("password"):
865
- return None
866
- if key is not None and form.get("password") != key:
867
- return None
868
- return self._issue_identity(subject)
869
- if grant == "refresh_token":
870
- presented = form.get("refresh_token") or ""
871
- with self._lock:
872
- subject = self._refresh_tokens.pop(presented, None)
873
- if subject is None:
874
- return None
875
- return self._issue_identity(subject)
876
- return None
877
-
878
- def _issue_identity(self, subject: str) -> dict:
879
- """An ``id_token`` (HS256 JWT, one hour) and a ``refresh_token``, both
880
- remembered so later calls and refreshes are honoured."""
881
- import hmac
882
- import hashlib
883
-
884
- now = int(time.time())
885
- 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()
895
- id_token = f"{header}.{payload}.{signature}"
896
- refresh = secrets.token_urlsafe(32)
897
- with self._lock:
898
- self.tokens.add(id_token)
899
- self._refresh_tokens[refresh] = subject
900
- return {
901
- "id_token": id_token,
902
- "access_token": id_token,
903
- "refresh_token": refresh,
904
- "token_type": "Bearer",
905
- "expires_in": 3600,
906
- }
907
-
908
- def authorized(self, headers: dict[str, str], query: dict[str, str], key: str | None) -> bool:
909
- spec = self.spec
910
- if spec.scheme == "none":
911
- return True
912
- presented: str | None = None
913
- if spec.scheme == "header":
914
- presented = headers.get((spec.auth_name or "").lower())
915
- elif spec.scheme in ("bearer", "oauth2"):
916
- value = headers.get("authorization", "")
917
- presented = value[7:] if value.lower().startswith("bearer ") else None
918
- elif spec.scheme == "basic":
919
- presented = basic_user(headers.get("authorization", ""))
920
- elif spec.scheme == "query":
921
- presented = query.get(spec.auth_name or "")
922
- if not presented:
923
- return False
924
- if spec.scheme == "oauth2":
925
- # A bearer is good only if this world minted it: the client did the grant first.
926
- with self._lock:
927
- return presented in self.tokens
928
- return key is None or presented == key
929
-
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}
790
+ return RouteMiss.of(on_path) if best is None else (best[2], best[3])
934
791
 
935
792
 
936
793
  class ApiContext:
937
- """What a world's handler gets: the store, the clock, and the vendor's shapes."""
794
+ """What a world's handler gets: the store, the clock, and the vendor's shapes. The
795
+ request's door signs links (:meth:`signed_url`) and is not otherwise handed out.
796
+ ``raw`` is the request's body as sent and ``files`` the files it carried
797
+ (:class:`~.request_body.RequestBody`), beside the fields a handler reads as ``body``."""
938
798
 
939
799
  def __init__(
940
- self, state: WorldState, router: Router, operation: Operation, link: tuple[str, dict[str, str]] | None = None
800
+ self,
801
+ state: WorldState,
802
+ router: Router,
803
+ operation: Operation,
804
+ link: PageLink | None = None,
805
+ *,
806
+ door: Door | None = None,
807
+ origin: str = "",
808
+ signing_origin: str | None = None,
941
809
  ):
942
810
  self.state = state
943
811
  self.router = router
944
812
  self.settings = router.settings
945
813
  self.operation = operation
946
814
  self.spec = router.spec
947
- #: (absolute URL without query, query) of the request being answered, for page links.
948
- self.link = link
949
- #: The request's headers, lower-cased — a gate reads the credential from here.
815
+ self.page_link = link
816
+ self.link = None if link is None else link.first_values
950
817
  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
818
  self.query_all: dict[str, list[str]] = {}
819
+ self.raw = b""
820
+ self.files: dict[str, Upload] = {}
821
+ self._door = door
822
+ self._origin = origin
823
+ self._signing_origin = signing_origin or origin
954
824
 
955
825
  def rows(self, entity: str) -> list[dict]:
956
826
  return self.state.rows(entity)
@@ -959,8 +829,12 @@ class ApiContext:
959
829
  return self.state.get(entity, key)
960
830
 
961
831
  def find(self, entity: str, **fields: Any) -> list[dict]:
962
- 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)]
832
+ return self.select(entity, RowMatch.on_fields({k: str(v) for k, v in fields.items()}))[0]
833
+
834
+ def select(
835
+ self, entity: str, match: RowMatch, *, limit: int | None = None, offset: int = 0
836
+ ) -> tuple[list[dict], int]:
837
+ return self.state.select(entity, match, limit, offset)
964
838
 
965
839
  def insert(self, entity: str, value: dict) -> dict:
966
840
  return self.state.insert(entity, value)
@@ -1028,15 +902,15 @@ class ApiContext:
1028
902
 
1029
903
  def envelope(self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None) -> Any:
1030
904
  page = paginate(rows, query or {}, self.settings.paging)
1031
- return wrap(page, self.settings, envelope, link=self.link, omit_done_cursor=self._omits_done_cursor())
905
+ return wrap(page, self.settings, envelope, link=self.page_link, omit_done_cursor=self._omits_done_cursor())
1032
906
 
1033
907
  def paged(
1034
908
  self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None, status: int = 200
1035
909
  ) -> Any:
1036
910
  """``envelope`` plus the vendor's paging headers, as a handler's full answer."""
1037
911
  page = paginate(rows, query or {}, self.settings.paging)
1038
- body = wrap(page, self.settings, envelope, link=self.link, omit_done_cursor=self._omits_done_cursor())
1039
- return status, body, page_headers(page, self.settings)
912
+ body = wrap(page, self.settings, envelope, link=self.page_link, omit_done_cursor=self._omits_done_cursor())
913
+ return status, body, page_headers(page, self.settings, link=self.page_link)
1040
914
 
1041
915
  def _omits_done_cursor(self) -> bool:
1042
916
  return self.settings.omits_done_cursor(self.settings.for_operation(self.operation.name))
@@ -1046,10 +920,17 @@ class ApiContext:
1046
920
  return self.settings.not_found_for(self.settings.for_operation(self.operation.name))
1047
921
 
1048
922
  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
923
+ return self.settings.refusal(detail)
924
+
925
+ def signed_url(self, path: str, ttl_seconds: int | None = None) -> str:
926
+ """A presigned link to ``path`` (a route ``[auth.downloads]`` names, as the client
927
+ sends it under base_url's path) that reaches it without the key for
928
+ ``ttl_seconds``, else the declared ``ttl_seconds``, else as long as the session."""
929
+ if self._door is None:
930
+ fail(
931
+ "handlers", "signed_url signs for a route call's session; this context answers none", "/auth/downloads"
932
+ )
933
+ return f"{self._signing_origin}{self._door.prefix}{path}?{self._door.signed_query(path, ttl_seconds)}"
1053
934
 
1054
935
 
1055
936
  Handler = Callable[[ApiContext, dict[str, str], dict[str, str], Any], Any]
@@ -1093,210 +974,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1093
974
  return handlers
1094
975
 
1095
976
 
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
- def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
1234
- """Assign a dotted target (``attributes.note``), keeping the rest of a nested
1235
- object an update leaves alone."""
1236
- parts = target.split(".")
1237
- if len(parts) == 1:
1238
- row[target] = value
1239
- return
1240
- head = parts[0]
1241
- if head not in row:
1242
- base = current.get(head) if current else None
1243
- row[head] = json.loads(json.dumps(base)) if isinstance(base, dict) else {}
1244
- node = row[head]
1245
- for part in parts[1:-1]:
1246
- if not isinstance(node.get(part), dict):
1247
- node[part] = {}
1248
- node = node[part]
1249
- node[parts[-1]] = value
1250
-
1251
-
1252
- def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | None = None) -> dict:
1253
- """The row a create or update writes: defaults, then the body (mapped or as-is), then generated fields."""
1254
- if body is None or not isinstance(body, dict):
1255
- body = {}
1256
- row: dict = json.loads(json.dumps(op.defaults)) if current is None else {}
1257
- if op.body:
1258
- for field_name, path in op.body.items():
1259
- value = _dig(body, path)
1260
- if value is not None:
1261
- _set(row, field_name, value, current)
1262
- else:
1263
- row.update(body)
1264
- if current is None:
1265
- for field_name, kind in op.generate.items():
1266
- if row.get(field_name) is not None:
1267
- continue
1268
- if kind == "uuid":
1269
- row[field_name] = ctx.uuid()
1270
- elif kind == "now":
1271
- row[field_name] = ctx.now()
1272
- else:
1273
- existing = [r.get(field_name) for r in ctx.rows(ctx.operation.entity or "")]
1274
- row[field_name] = max([v for v in existing if isinstance(v, int)] + [0]) + 1
1275
- return row
1276
-
1277
-
1278
- def vendor_credential(spec: Spec, presented: str, *, grant: str | None = None) -> tuple[dict[str, str], dict[str, str]]:
1279
- """(headers, query) carrying the world's own credential: ``presented`` in
1280
- the shape the vendor's scheme declares — a ``query`` world reads its key
1281
- from the query string, so that half is a query parameter; an ``oauth2``
1282
- world accepts only a bearer it minted, so the caller passes its ``grant``.
1283
- The host presents a session token this way, the local server its pin."""
1284
- if spec.scheme == "none":
1285
- return {}, {}
1286
- if spec.scheme == "header":
1287
- return {(spec.auth_name or "x-api-key").lower(): presented}, {}
1288
- if spec.scheme == "bearer":
1289
- return {"authorization": f"Bearer {presented}"}, {}
1290
- if spec.scheme == "oauth2":
1291
- return {"authorization": f"Bearer {grant or ''}"}, {}
1292
- if spec.scheme == "basic":
1293
- return {"authorization": "Basic " + base64.b64encode(f"{presented}:".encode()).decode()}, {}
1294
- if spec.scheme == "query":
1295
- return {}, {spec.auth_name or "api_key": presented}
1296
- fail("spec", f"auth scheme '{spec.scheme}' has no credential shape to present", "/auth/scheme")
1297
- raise AssertionError # fail() never returns
1298
-
1299
-
1300
977
  def with_query(target: str, extra: dict[str, str]) -> str:
1301
978
  """``target`` with ``extra`` merged into its query string: the caller's
1302
979
  params kept, duplicates and all, except one named like a credential in
@@ -1310,140 +987,15 @@ def with_query(target: str, extra: dict[str, str]) -> str:
1310
987
  return urllib.parse.urlunsplit(url._replace(query=urllib.parse.urlencode(query)))
1311
988
 
1312
989
 
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
990
  Response = tuple[int, Any, dict[str, str] | None]
1348
991
 
1349
992
 
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()
1397
-
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)}
993
+ class _Refused(Exception):
994
+ """A route that answered an error: its writes are rolled back, its answer still sent."""
1442
995
 
1443
- def clear(self) -> None:
1444
- with self._lock:
1445
- self.entries.clear()
1446
- self.total = 0
996
+ def __init__(self, response: Response):
997
+ super().__init__(response[0])
998
+ self.response = response
1447
999
 
1448
1000
 
1449
1001
  class WorldApp:
@@ -1453,7 +1005,16 @@ class WorldApp:
1453
1005
  headers, raw body) and answers ``(status, body, extra headers)``; nothing in
1454
1006
  it touches a socket. ``make_handler`` wraps it for ``serve()``, and the
1455
1007
  World Host calls it for whichever session a request names, so one process
1456
- can answer for many worlds without the handler knowing.
1008
+ can answer for many worlds without the handler knowing. ``routes_closed``:
1009
+ the session's task lists the tools it may call, so every route answers 403
1010
+ before any handler runs, and the list holds against a client calling the
1011
+ vendor API directly. ``calls`` is the session's call log, shared with its
1012
+ tools; a world served alone keeps its own.
1013
+
1014
+ ``admin`` serves the runner's ``/__world/*`` routes (state, calls, reset, seed) to the holder
1015
+ of its token, and ``/healthz`` to anyone, for the runner's bundle server (``serve()``) and a
1016
+ local session. A World Host session's doors carry the agent's token, and those routes read and
1017
+ rewrite what its grader reads, so the host passes none: its api origin answers like the vendor's.
1457
1018
  """
1458
1019
 
1459
1020
  def __init__(
@@ -1462,259 +1023,181 @@ class WorldApp:
1462
1023
  router: Router,
1463
1024
  key: str | None,
1464
1025
  handlers: dict[str, Handler] | None = None,
1465
- allowed: frozenset[str] | None = None,
1466
- call_log_max: int | None = None,
1026
+ routes_closed: bool = False,
1027
+ calls: CallLog | None = None,
1028
+ admin: AdminToken | None = None,
1467
1029
  ):
1468
1030
  self.state = state
1469
1031
  self.router = router
1470
- self.key = key
1032
+ self.admin = admin
1471
1033
  self.settings = router.settings
1472
- self.prefix = urllib.parse.urlsplit(router.spec.base_url).path.rstrip("/")
1034
+ self.door = Door.of(router.spec, router.settings, key)
1473
1035
  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)
1479
-
1480
- @staticmethod
1481
- def _json(raw: bytes) -> Any:
1482
- if not raw:
1483
- return {}
1484
- try:
1485
- return json.loads(raw.decode("utf-8"))
1486
- except (UnicodeDecodeError, json.JSONDecodeError):
1487
- return None
1488
-
1489
- @staticmethod
1490
- def _body(raw: bytes, headers: dict[str, str]) -> Any:
1491
- """A write's body as the route reads it: JSON, or a form (``application/
1492
- x-www-form-urlencoded``, what Slack's Web API takes and a browser page
1493
- posts) as ``{name: first value}``. A body that is JSON reads as JSON
1494
- whatever the label says — urllib labels every POST a form, and no form
1495
- field starts with ``{``. Malformed JSON is None."""
1496
- content_type = (headers.get("content-type") or "").split(";")[0].strip().lower()
1497
- if content_type == "application/x-www-form-urlencoded" and not raw.lstrip().startswith((b"{", b"[")):
1498
- pairs = urllib.parse.parse_qs(raw.decode("utf-8", "replace"), keep_blank_values=True)
1499
- return {k: v[0] for k, v in pairs.items()}
1500
- return WorldApp._json(raw)
1501
-
1502
- @staticmethod
1503
- def _form(raw: bytes, headers: dict[str, str]) -> dict[str, str]:
1504
- content_type = (headers.get("content-type") or "").split(";")[0].strip().lower()
1505
- if content_type == "application/json":
1506
- try:
1507
- parsed = json.loads(raw.decode("utf-8"))
1508
- except (UnicodeDecodeError, json.JSONDecodeError):
1509
- return {}
1510
- return {k: str(v) for k, v in parsed.items()} if isinstance(parsed, dict) else {}
1511
- form = {k: v[0] for k, v in urllib.parse.parse_qs(raw.decode("utf-8", "replace")).items()}
1512
- basic = headers.get("authorization", "")
1513
- if basic.lower().startswith("basic "):
1514
- try:
1515
- client_id, _, client_secret = base64.b64decode(basic[6:]).decode().partition(":")
1516
- form.setdefault("client_id", client_id)
1517
- form.setdefault("client_secret", client_secret)
1518
- except (ValueError, UnicodeDecodeError):
1519
- pass
1520
- return form
1521
-
1522
- def _strip(self, path: str) -> str:
1523
- if self.prefix and path.startswith(self.prefix):
1524
- return path[len(self.prefix) :] or "/"
1525
- return path
1036
+ self.routes_closed = routes_closed
1037
+ self.calls = calls if calls is not None else CallLog.for_spec(router.spec, secret=key)
1526
1038
 
1527
1039
  def handle(
1528
- self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str, *, via: Via | None
1040
+ self,
1041
+ method: str,
1042
+ target: str,
1043
+ headers: dict[str, str],
1044
+ raw: bytes,
1045
+ default_host: str,
1046
+ *,
1047
+ via: Via | None,
1048
+ opened: bool = False,
1049
+ link_host: str | None = None,
1529
1050
  ) -> Response:
1530
1051
  """Answer one request. ``headers`` are lower-cased; ``default_host`` is what
1531
1052
  a link uses when the request carries no Host header; ``via`` is the door
1532
- the caller took it in by, recorded on the call when there is one."""
1053
+ the caller took it in by, recorded on the call when there is one; ``opened``:
1054
+ it came in on an open session's capability hostname, so the world asks for
1055
+ nothing (:meth:`~.door.Door.opened`); ``link_host``: the host a link the world
1056
+ signs points at, the request's own when None. A browser's preflight is answered
1057
+ before any credential, and only by a world that serves browsers."""
1533
1058
  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
1564
- if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
1565
- return 405, {"error": "method_not_allowed"}, None
1566
- return self._route(method, url, headers, raw, default_host, via)
1059
+ answered = self._admin(method, url.path, raw, headers, via) or self.settings.cors.preflight(method, headers)
1060
+ if answered is not None:
1061
+ return answered
1062
+ unrouted = partial(self._unrouted, method, url, headers, raw, via)
1063
+ door = self.door.opened() if opened else self.door
1064
+ entry = door.vendor_entry(method, url.path, url.query, headers)
1065
+ if entry is None:
1066
+ return unrouted(self.settings.unauthorized_status, self.settings.unauthorized)
1067
+ if entry is Entry.EXCHANGE:
1068
+ return unrouted(*door.answer_exchange(raw, headers))
1069
+ hosts = (default_host, link_host)
1070
+ return self._route(method, url, headers, raw, hosts, via, unrouted, door.reachable(entry))
1071
+
1072
+ def _unrouted(
1073
+ self, method: str, url, headers: dict, raw: bytes, via: Via | None, status: int, answer: Any, extra=None
1074
+ ) -> Response:
1075
+ """A request no route took (refused, or the vendor's login route, whose request body
1076
+ is never kept): answered, kept by the request ledger, not a grader's call."""
1077
+ served = Served(headers, len(raw), extra, self.settings.error_content_type, self.door.credential, False)
1078
+ self.calls.heard(method, self.door.route_path(url.path), url.query, status, answer, via, served)
1079
+ return status, answer, self.settings.cors.carried(extra)
1080
+
1081
+ def _admin(self, method: str, path: str, raw: bytes, headers: dict[str, str], via: Via | None) -> Response | None:
1082
+ """The runner's routes, or None for a request that is not one of them: health where :attr:`admin` is set
1083
+ and on the ui door, whose page may probe it; the rest only where it is set, and only to its token."""
1084
+ state = self.state
1085
+ if (self.admin is not None or via is Via.UI) and (method, path) == ("GET", ADMIN["health"]):
1086
+ return 200, {"ok": True, "world": self.router.spec.slug}, None
1087
+ if self.admin is None or path not in RUNNER_PATHS:
1088
+ return None
1089
+ if not self.admin.admits(headers):
1090
+ return 403, {"error": "admin_token_required"}, None
1091
+ if (method, path) == ("GET", ADMIN["state"]):
1092
+ return 200, self.calls.into_state({**state.dump(), "snapshot": state.describe_snapshot()}), None
1093
+ if (method, path) == ("GET", ADMIN["calls"]):
1094
+ return 200, self.calls.describe(), None
1095
+ if (method, path) == ("POST", ADMIN["reset"]):
1096
+ state.reset()
1097
+ return 200, {"ok": True}, None
1098
+ if (method, path) == ("POST", ADMIN["seed"]):
1099
+ return self._seed(raw)
1100
+ return None
1101
+
1102
+ def _seed(self, raw: bytes) -> Response:
1103
+ body = json_value(raw)
1104
+ if body is None:
1105
+ return 400, {"error": "seed must be JSON"}, None
1106
+ try:
1107
+ self.state.seed(body)
1108
+ except ContractError as error:
1109
+ if error.detail.get("code") == "base_mismatch":
1110
+ return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
1111
+ return 400, {"error": "seed_rejected", "detail": str(error)}, None
1112
+ except Exception as error:
1113
+ return 400, {"error": "seed_rejected", "detail": str(error)}, None
1114
+ return 200, {"ok": True}, None
1567
1115
 
1568
1116
  def _route(
1569
- self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
1117
+ self,
1118
+ method: str,
1119
+ url,
1120
+ headers: dict[str, str],
1121
+ raw: bytes,
1122
+ hosts: tuple[str, str | None],
1123
+ via: Via | None,
1124
+ unrouted,
1125
+ within: tuple[str, ...] | None,
1570
1126
  ) -> Response:
1571
1127
  settings, router = self.settings, self.router
1572
- path = self._strip(url.path)
1128
+ path = self.door.route_path(url.path)
1573
1129
  query_all = {k: list(v) for k, v in urllib.parse.parse_qs(url.query).items()}
1574
1130
  query = {k: v[0] for k, v in query_all.items()}
1575
- if not router.authorized(headers, query, self.key):
1576
- return settings.unauthorized_status, settings.unauthorized, None
1577
- matched = router.match(method, path, query)
1578
- if matched is None:
1579
- return settings.not_found_status, settings.not_found, None
1131
+ matched = router.match(method, path, query, within)
1132
+ if isinstance(matched, RouteMiss):
1133
+ return unrouted(*matched.answer(settings))
1580
1134
  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
1135
+ if self.routes_closed:
1136
+ return unrouted(403, {"error": "route_not_allowed", "operation": operation.name, "detail": ROUTES_CLOSED})
1583
1137
  op = settings.for_operation(operation.name)
1584
- body = self._body(raw, headers) if method in ("POST", "PUT", "PATCH") else {}
1138
+ read = method in ("POST", "PUT", "PATCH") or (method == "DELETE" and bool(raw))
1139
+ sent = RequestBody.of(raw if read else b"", headers)
1140
+ body = sent.fields_for(op.action == "handler")
1585
1141
  if body is None:
1586
- return settings.invalid_status, settings.invalid, None
1142
+ return unrouted(settings.invalid_status, settings.invalid)
1587
1143
  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)
1592
- return status, answer, extra
1593
-
1594
- 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
1596
- host = headers.get("host") or default_host
1597
- forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
1598
- ctx = ApiContext(state, router, operation, link=(f"{forwarded}://{host}{url.path}", query))
1599
- ctx.headers = headers
1600
- ctx.query_all = query_all
1144
+ status, answer, extra = 500, None, None
1145
+ try:
1146
+ status, answer, extra = self._answer_atomically(
1147
+ op, operation, args, query, query_all, body, sent, headers, url, hosts
1148
+ )
1149
+ finally:
1150
+ elapsed = time.monotonic() - started
1151
+ shape = settings.answer_shape(op, operation)
1152
+ served = Served(headers, len(raw), extra, settings.error_content_type, self.door.credential, read)
1153
+ self.calls.record(
1154
+ operation, method, path, args, query_all, body, status, answer, elapsed, via, shape=shape, served=served
1155
+ )
1156
+ return status, answer, settings.cors.carried(extra)
1157
+
1158
+ def _answer_atomically(self, op, operation, *request) -> Response:
1601
1159
  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)
1160
+ with self.state.transaction():
1161
+ response = self._answer_route(op, operation, *request)
1162
+ if response[0] >= 400:
1163
+ raise _Refused(response)
1164
+ except _Refused as refused:
1165
+ return refused.response
1166
+ except MisdeclaredRoute as bug:
1167
+ return 400, handler_bug_body(operation.name, bug), None
1607
1168
  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
1169
+ log_contract_refusal(self.router.spec.slug, operation.name, error)
1170
+ return (*self.settings.refusal(), None)
1171
+ return response
1614
1172
 
1615
- @staticmethod
1616
- def _answer(
1617
- op: OperationSettings,
1618
- operation: Operation,
1619
- ctx: ApiContext,
1620
- args: dict[str, str],
1621
- query: dict[str, str],
1622
- body: Any,
1623
- handlers: dict[str, Handler],
1624
- ) -> Any:
1173
+ def _answer_route(self, op, operation, args, query, query_all, body, sent, headers, url, hosts) -> Response:
1174
+ router, state, handlers = self.router, self.state, self.handlers
1175
+ default_host, link_host = hosts
1176
+ host = headers.get("host") or default_host
1177
+ forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
1178
+ origin = f"{forwarded}://{host}"
1179
+ link = PageLink.of(f"{origin}{url.path}", query_all, self.calls.redaction.credential_params)
1180
+ signing = f"{forwarded}://{link_host or host}"
1181
+ ctx = ApiContext(state, router, operation, link=link, door=self.door, origin=origin, signing_origin=signing)
1182
+ ctx.headers, ctx.query_all = headers, query_all
1183
+ ctx.raw, ctx.files = sent.raw, sent.files
1184
+ request = (ctx, args, query, body)
1185
+ gate = self.settings.before or BEFORE
1186
+ verdict = handled_answer(gate, handlers[BEFORE], request, None) if BEFORE in handlers else None
1187
+ if verdict is not None:
1188
+ return verdict
1625
1189
  if op.action == "handler":
1626
- return handlers[operation.name](ctx, args, query, body)
1627
- if not operation.entity:
1628
- return 501, {"error": "not_modelled", "operation": operation.name}
1629
- entity = operation.entity
1630
- omit_done_cursor = ctx.settings.omits_done_cursor(op)
1631
- if op.action == "create":
1632
- 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)
1635
- if not op.filter and op.action == "read":
1636
- 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.
1639
- values: dict[str, str | list[str]] = {
1640
- **{k: v for k, v in ctx.query_all.items() if k in operation.params or k in filters},
1641
- **args,
1642
- }
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)]
1651
- if op.action in ("update", "delete"):
1652
- if len(rows) != 1:
1653
- return ctx.not_found()
1654
- key = ctx.key_of(entity, rows[0])
1655
- if op.action == "delete":
1656
- ctx.delete(entity, key)
1657
- return op.status, None
1658
- 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)
1660
- if op.single:
1661
- if not rows:
1662
- return ctx.not_found()
1663
- return op.status, rows[0]
1664
- paging = (
1665
- ctx.settings.paging
1666
- if op.paging is None
1667
- else Paging(
1668
- op.paging,
1669
- ctx.settings.paging.limit_param,
1670
- ctx.settings.paging.offset_param,
1671
- ctx.settings.paging.cursor_param,
1672
- ctx.settings.paging.page_size,
1673
- )
1674
- )
1675
- page = paginate(rows, query, paging)
1676
- return (
1677
- op.status,
1678
- wrap(page, ctx.settings, op.envelope, paging=paging, link=ctx.link, omit_done_cursor=omit_done_cursor),
1679
- page_headers(page, ctx.settings, paging),
1680
- )
1190
+ return handled_answer(op.handler or operation.name, handlers[operation.name], request, op.status)
1191
+ return normalize_answer(DeclaredRoute(op, operation, ctx, args, query, body).answer(), op.status)
1681
1192
 
1682
1193
 
1683
- def send_response(
1684
- handler: BaseHTTPRequestHandler, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str
1685
- ) -> None:
1686
- """Write one ``WorldApp`` answer to a request handler's socket."""
1687
- if status == 204 or body is None:
1688
- handler.send_response(status)
1689
- for name, value in (extra or {}).items():
1690
- handler.send_header(name, value)
1691
- handler.send_header("Content-Length", "0")
1692
- handler.end_headers()
1693
- return
1694
- headers = dict(extra or {})
1695
- if isinstance(body, bytes):
1696
- payload = body
1697
- else:
1698
- payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
1699
- headers = {"Content-Type": error_content_type if status >= 400 else "application/json", **headers}
1700
- handler.send_response(status)
1701
- for name, value in headers.items():
1702
- handler.send_header(name, value)
1703
- handler.send_header("Content-Length", str(len(payload)))
1704
- handler.end_headers()
1705
- handler.wfile.write(payload)
1706
-
1707
-
1708
- def make_handler(state: WorldState, router: Router, key: str | None):
1709
- app = WorldApp(state, router, key)
1710
-
1711
- class Handler(BaseHTTPRequestHandler):
1712
- server_version = f"gateway-world-api/{router.spec.slug}"
1194
+ def make_handler(state: WorldState, router: Router, key: str | None, admin: AdminToken | None = None):
1195
+ app = WorldApp(state, router, key, admin=admin or AdminToken())
1713
1196
 
1714
- def log_message(self, *_):
1715
- pass
1197
+ class Handler(WorldRequestHandler):
1198
+ server_version = f"gateway-world-api/{router.spec.slug}"
1716
1199
 
1717
- def _serve(self, method: str) -> None:
1200
+ def _dispatch(self, method: str) -> None:
1718
1201
  length = int(self.headers.get("Content-Length") or 0)
1719
1202
  raw = self.rfile.read(length) if length else b""
1720
1203
  headers = {k.lower(): v for k, v in self.headers.items()}
@@ -1723,21 +1206,6 @@ def make_handler(state: WorldState, router: Router, key: str | None):
1723
1206
  status, body, extra = app.handle(method, self.path, headers, raw, default_host, via=None)
1724
1207
  send_response(self, status, body, extra, app.settings.error_content_type)
1725
1208
 
1726
- def do_GET(self):
1727
- self._serve("GET")
1728
-
1729
- def do_POST(self):
1730
- self._serve("POST")
1731
-
1732
- def do_PUT(self):
1733
- self._serve("PUT")
1734
-
1735
- def do_PATCH(self):
1736
- self._serve("PATCH")
1737
-
1738
- def do_DELETE(self):
1739
- self._serve("DELETE")
1740
-
1741
1209
  return Handler
1742
1210
 
1743
1211
 
@@ -1748,22 +1216,24 @@ def serve(
1748
1216
  host: str = "0.0.0.0",
1749
1217
  api_key: str | None = None,
1750
1218
  scenario: str | None = None,
1219
+ admin: AdminToken | None = None,
1751
1220
  ) -> ThreadingHTTPServer:
1752
- """Start the world's API and return the server; the caller decides how long it runs."""
1221
+ """Start the world's API and return the server; the caller decides how long it runs.
1222
+ ``admin`` admits its holder to the runner's ``/__world/*`` routes; without one they are refused."""
1753
1223
  root = Path(world)
1754
1224
  spec = load_spec(root)
1755
1225
  settings = load_api_settings(root, spec)
1756
1226
  state = WorldState(root)
1757
1227
  if scenario:
1758
1228
  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]
1229
+ server = ThreadingHTTPServer((host, port), make_handler(state, Router(spec, settings), api_key, admin))
1230
+ server.world_state = state # type: ignore[attr-defined] # close() finds the state on its server
1761
1231
  return server
1762
1232
 
1763
1233
 
1764
1234
  def fetch_hosted_snapshot(world: str | Path, environ: dict[str, str] | None = None) -> dict | None:
1765
1235
  """The hosted pod's snapshot, when ``WORLD_SNAPSHOT_URL`` / ``_SHA256`` / ``_DIGEST``
1766
- are set: downloaded to ``db/state.sqlite``, verified, sidecar written. All three
1236
+ are set: downloaded to ``db/<snapshot name>``, verified, sidecar written. All three
1767
1237
  are required together; a digest mismatch is fatal and names the digest."""
1768
1238
  env = os.environ if environ is None else environ
1769
1239
  values = {name: env.get(name) for name in (snapshots.ENV_URL, snapshots.ENV_SHA256, snapshots.ENV_DIGEST)}
@@ -1792,30 +1262,17 @@ def serve_forever(
1792
1262
  raise SystemExit(2)
1793
1263
  if fetched:
1794
1264
  print(f"world snapshot {fetched['batchDigest']} opened", file=sys.stderr)
1795
- server = serve(world, port=port, api_key=api_key, scenario=scenario)
1265
+ server = serve(world, port=port, api_key=api_key, scenario=scenario, admin=AdminToken.from_env())
1796
1266
  try:
1797
1267
  print(f"world api listening on http://0.0.0.0:{port}", file=sys.stderr)
1798
1268
  server.serve_forever()
1799
1269
  finally:
1800
1270
  server.server_close()
1801
- server.world_state.close() # type: ignore[attr-defined]
1271
+ server.world_state.close() # type: ignore[attr-defined] # set by serve()
1802
1272
 
1803
1273
 
1804
1274
  def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
1805
- parameters = {"header": "header", "query": "query"}
1806
- security_scheme: dict[str, Any] = {}
1807
- if spec.scheme in ("header", "query"):
1808
- security_scheme = {"type": "apiKey", "in": parameters[spec.scheme], "name": spec.auth_name}
1809
- elif spec.scheme == "bearer":
1810
- security_scheme = {"type": "http", "scheme": "bearer"}
1811
- elif spec.scheme == "basic":
1812
- security_scheme = {"type": "http", "scheme": "basic"}
1813
- elif spec.scheme == "oauth2":
1814
- token_url = (settings.token_path if settings else None) or DEFAULT_TOKEN_PATH
1815
- security_scheme = {
1816
- "type": "oauth2",
1817
- "flows": {"clientCredentials": {"tokenUrl": token_url, "scopes": {spec.scope or "api": "API access"}}},
1818
- }
1275
+ security_scheme = spec.auth.scheme.security_scheme(settings.token_path if settings else None)
1819
1276
  paths: dict[str, dict] = {}
1820
1277
  for operation in spec.operations.values():
1821
1278
  op = settings.for_operation(operation.name) if settings else OperationSettings()
@@ -1845,8 +1302,7 @@ def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None
1845
1302
  methods = paths.setdefault(operation.path, {})
1846
1303
  method = operation.method.lower()
1847
1304
  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.
1305
+ # OpenAPI keys one operation per path+method, so query-parameter variants ride here, not lost.
1850
1306
  methods[method].setdefault("x-gateway-variants", []).append(
1851
1307
  {
1852
1308
  k: v
@@ -1925,8 +1381,7 @@ def build_api_bundle(world: str | Path, out: str | Path) -> Path:
1925
1381
  "",
1926
1382
  ]
1927
1383
  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.
1384
+ # The built ui ships inside the copied world, so no ui image is built for a schema world.
1930
1385
  manifest += [
1931
1386
  "[ui]",
1932
1387
  f'static = "server/world/{settings.ui.static}"',