@withgateway/sdk 0.3.0 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -1
- package/dist/cli.js +3971 -2338
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +3950 -2318
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +214 -41
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +206 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
- package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1456 -564
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1433 -557
- package/dist/index.mjs.map +1 -1
- package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
- package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
- package/dist/traces/index.d.mts +1 -1
- package/dist/traces/index.d.ts +1 -1
- package/dist/traces/index.js +211 -38
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +203 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +2 -2
- package/dist/tracing/index.d.ts +2 -2
- package/dist/tracing/index.js +96 -21
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +96 -21
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +300 -123
- package/dist/worlds/index.d.ts +300 -123
- package/dist/worlds/index.js +1385 -508
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1377 -501
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +2 -27
- package/runtime/gatewaysdk/environment/_materialize.py +49 -69
- package/runtime/gatewaysdk/environment/_world.py +122 -197
- package/runtime/gatewaysdk/environment/backing.py +137 -0
- package/runtime/gatewaysdk/environment/core.py +1 -1
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
- package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
- package/runtime/gatewaysdk/environment/runtime.py +8 -13
- package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
- package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
- package/runtime/gatewaysdk/environment/schema/api.py +266 -515
- package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
- package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
- package/runtime/gatewaysdk/environment/schema/data.py +50 -207
- package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
- package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
- package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
- package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
- package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
- package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
- package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
- package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
- package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
- package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
- package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
- package/runtime/gatewaysdk/environment/schema/host.py +158 -250
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/local.py +44 -71
- package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
- package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
- package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
- package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
- package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
- package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
- package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
- package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
- package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
- package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
- package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
- package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
- package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
- package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
- package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
- package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
- package/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/skills/connector-schema-authoring/SKILL.md +22 -14
- package/skills/connector-schema-authoring/connector-worlds.md +26 -10
- package/skills/connector-schema-authoring/world-schema.md +111 -51
- package/skills/world-data-ingestion/ROWS.md +29 -3
- package/skills/world-data-ingestion/SKILL.md +16 -16
- package/skills/worlds-getting-started/SKILL.md +18 -18
- package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- 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.
|
|
80
|
-
(``/
|
|
81
|
-
|
|
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 .
|
|
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
|
-
|
|
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)
|
|
161
|
-
match: dict[str, str] = field(default_factory=dict)
|
|
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
|
|
153
|
+
envelope: str | None = None
|
|
165
154
|
single: bool = False
|
|
166
|
-
body: dict[str, str] = field(default_factory=dict)
|
|
167
|
-
#
|
|
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
|
|
173
|
-
sample: dict[str, str] = field(default_factory=dict)
|
|
174
|
-
not_found: Any = INHERITED
|
|
175
|
-
not_found_status: int | None = None
|
|
176
|
-
cursor_absent_when_done: bool | None = None
|
|
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"
|
|
188
|
+
hits_key: str = "hits"
|
|
204
189
|
cursor_key: str = "cursor"
|
|
205
|
-
cursor_absent_when_done: bool = False
|
|
206
|
-
previous_key: str | None = None
|
|
207
|
-
page_headers: dict[str, str] = field(default_factory=dict)
|
|
208
|
-
page_links: bool = False
|
|
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
|
|
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
|
-
"""
|
|
233
|
-
|
|
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
|
|
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
|
-
#
|
|
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
|
|
514
|
-
this contract) a reset is a file copy and an open;
|
|
515
|
-
initial batch is replayed, as it always was
|
|
516
|
-
|
|
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 =
|
|
521
|
+
self.contract = served.contract
|
|
521
522
|
self._initial: dict | None = None
|
|
522
|
-
self._snapshot_path = snapshots.default_snapshot(world)
|
|
523
|
-
|
|
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.
|
|
529
|
-
self.store:
|
|
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 =
|
|
580
|
+
self.store = WorldDatabase.open_copy(snapshot, self.contract, database)
|
|
583
581
|
return
|
|
584
|
-
self.store =
|
|
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.
|
|
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
|
|
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 =
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
851
|
+
payload = (
|
|
852
|
+
base64.urlsafe_b64encode(
|
|
853
|
+
json.dumps(
|
|
854
|
+
{
|
|
855
|
+
"sub": subject,
|
|
856
|
+
"iat": now,
|
|
857
|
+
"exp": now + 3600,
|
|
858
|
+
"iss": self.spec.slug,
|
|
859
|
+
"jti": secrets.token_urlsafe(9),
|
|
860
|
+
},
|
|
861
|
+
separators=(",", ":"),
|
|
862
|
+
).encode()
|
|
863
|
+
)
|
|
864
|
+
.rstrip(b"=")
|
|
865
|
+
.decode()
|
|
866
|
+
)
|
|
867
|
+
signature = (
|
|
868
|
+
base64.urlsafe_b64encode(
|
|
869
|
+
hmac.new(self._jwt_secret, f"{header}.{payload}".encode(), hashlib.sha256).digest()
|
|
870
|
+
)
|
|
871
|
+
.rstrip(b"=")
|
|
872
|
+
.decode()
|
|
873
|
+
)
|
|
895
874
|
id_token = f"{header}.{payload}.{signature}"
|
|
896
875
|
refresh = secrets.token_urlsafe(32)
|
|
897
876
|
with self._lock:
|
|
@@ -939,12 +918,8 @@ class ApiContext:
|
|
|
939
918
|
self.settings = router.settings
|
|
940
919
|
self.operation = operation
|
|
941
920
|
self.spec = router.spec
|
|
942
|
-
#: (absolute URL without query, query) of the request being answered, for page links.
|
|
943
921
|
self.link = link
|
|
944
|
-
#: The request's headers, lower-cased — a gate reads the credential from here.
|
|
945
922
|
self.headers: dict[str, str] = {}
|
|
946
|
-
#: Every value of every query parameter, in order sent: ``{"expand[]": ["a", "b"]}``.
|
|
947
|
-
#: The ``query`` a handler is passed keeps only the first, as most routes want.
|
|
948
923
|
self.query_all: dict[str, list[str]] = {}
|
|
949
924
|
|
|
950
925
|
def rows(self, entity: str) -> list[dict]:
|
|
@@ -955,7 +930,7 @@ class ApiContext:
|
|
|
955
930
|
|
|
956
931
|
def find(self, entity: str, **fields: Any) -> list[dict]:
|
|
957
932
|
wanted = {k: str(v) for k, v in fields.items()}
|
|
958
|
-
return
|
|
933
|
+
return RowMatch.on_fields(wanted).select(self.state.rows(entity))
|
|
959
934
|
|
|
960
935
|
def insert(self, entity: str, value: dict) -> dict:
|
|
961
936
|
return self.state.insert(entity, value)
|
|
@@ -1041,10 +1016,7 @@ class ApiContext:
|
|
|
1041
1016
|
return self.settings.not_found_for(self.settings.for_operation(self.operation.name))
|
|
1042
1017
|
|
|
1043
1018
|
def invalid(self, detail: str | None = None) -> tuple[int, Any]:
|
|
1044
|
-
|
|
1045
|
-
if detail and isinstance(body, dict):
|
|
1046
|
-
body = {**body, "detail": detail}
|
|
1047
|
-
return self.settings.invalid_status, body
|
|
1019
|
+
return self.settings.refusal(detail)
|
|
1048
1020
|
|
|
1049
1021
|
|
|
1050
1022
|
Handler = Callable[[ApiContext, dict[str, str], dict[str, str], Any], Any]
|
|
@@ -1088,143 +1060,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
|
|
|
1088
1060
|
return handlers
|
|
1089
1061
|
|
|
1090
1062
|
|
|
1091
|
-
@dataclass(frozen=True)
|
|
1092
|
-
class Page:
|
|
1093
|
-
rows: list[dict]
|
|
1094
|
-
total: int
|
|
1095
|
-
offset: int
|
|
1096
|
-
limit: int
|
|
1097
|
-
style: str
|
|
1098
|
-
|
|
1099
|
-
@property
|
|
1100
|
-
def next_offset(self) -> int | None:
|
|
1101
|
-
following = self.offset + self.limit
|
|
1102
|
-
return following if self.style != "none" and following < self.total else None
|
|
1103
|
-
|
|
1104
|
-
@property
|
|
1105
|
-
def previous_offset(self) -> int | None:
|
|
1106
|
-
return max(self.offset - self.limit, 0) if self.style != "none" and self.offset > 0 else None
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
def _encode_cursor(offset: int) -> str:
|
|
1110
|
-
return base64.urlsafe_b64encode(str(offset).encode()).decode().rstrip("=")
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
def paginate(rows: list[dict], query: dict[str, str], paging: Paging) -> Page:
|
|
1114
|
-
"""One page of rows with the offsets the next and previous pages start at."""
|
|
1115
|
-
total = len(rows)
|
|
1116
|
-
if paging.style == "none":
|
|
1117
|
-
return Page(rows, total, 0, total, "none")
|
|
1118
|
-
limit = _int_param(query.get(paging.limit_param), paging.page_size)
|
|
1119
|
-
offset = 0
|
|
1120
|
-
if paging.style == "offset":
|
|
1121
|
-
offset = _int_param(query.get(paging.offset_param), 0)
|
|
1122
|
-
else:
|
|
1123
|
-
raw = query.get(paging.cursor_param)
|
|
1124
|
-
if raw:
|
|
1125
|
-
try:
|
|
1126
|
-
offset = int(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)).decode())
|
|
1127
|
-
except (ValueError, UnicodeDecodeError):
|
|
1128
|
-
offset = 0
|
|
1129
|
-
return Page(rows[offset : offset + limit], total, offset, limit, paging.style)
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
def _int_param(value: str | None, default: int) -> int:
|
|
1133
|
-
try:
|
|
1134
|
-
parsed = int(value) if value is not None else default
|
|
1135
|
-
except ValueError:
|
|
1136
|
-
return default
|
|
1137
|
-
return parsed if parsed >= 0 else default
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
def _page_ref(page: Page, offset: int | None, paging: Paging, link: tuple[str, dict[str, str]] | None) -> Any:
|
|
1141
|
-
"""What the vendor's client is handed for a neighbouring page: '' or None when there is
|
|
1142
|
-
none, a cursor token, or — with ``page_links`` — the absolute URL DRF-style vendors answer."""
|
|
1143
|
-
if offset is None:
|
|
1144
|
-
return None if link is not None else ""
|
|
1145
|
-
if link is None:
|
|
1146
|
-
return _encode_cursor(offset)
|
|
1147
|
-
base, query = link
|
|
1148
|
-
following = dict(query)
|
|
1149
|
-
if page.style == "offset":
|
|
1150
|
-
following[paging.offset_param] = str(offset)
|
|
1151
|
-
else:
|
|
1152
|
-
following[paging.cursor_param] = _encode_cursor(offset)
|
|
1153
|
-
following[paging.limit_param] = str(page.limit)
|
|
1154
|
-
return f"{base}?{urllib.parse.urlencode(following)}"
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
def page_headers(page: Page, settings: ApiSettings, paging: Paging | None = None) -> dict[str, str] | None:
|
|
1158
|
-
"""The page's cursor/total/previous as response headers, when the vendor sends them that way."""
|
|
1159
|
-
if not settings.page_headers:
|
|
1160
|
-
return None
|
|
1161
|
-
paging = paging or settings.paging
|
|
1162
|
-
values = {
|
|
1163
|
-
"cursor": _page_ref(page, page.next_offset, paging, None),
|
|
1164
|
-
"total": str(page.total),
|
|
1165
|
-
"previous": _page_ref(page, page.previous_offset, paging, None),
|
|
1166
|
-
}
|
|
1167
|
-
return {header: str(values[key]) for key, header in settings.page_headers.items() if values[key] not in ("", None)}
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
def wrap(
|
|
1171
|
-
page: Page | list[dict],
|
|
1172
|
-
settings: ApiSettings,
|
|
1173
|
-
envelope: str | None = None,
|
|
1174
|
-
*,
|
|
1175
|
-
paging: Paging | None = None,
|
|
1176
|
-
link: tuple[str, dict[str, str]] | None = None,
|
|
1177
|
-
omit_done_cursor: bool = False,
|
|
1178
|
-
) -> Any:
|
|
1179
|
-
"""Rows in the vendor's envelope: ``{<envelope>: rows, <hits_key>: total, <cursor_key>: next
|
|
1180
|
-
[, <previous_key>: previous]}``; an empty envelope key means the bare array, an empty
|
|
1181
|
-
``hits_key`` leaves the count out, and ``omit_done_cursor`` leaves the cursor key out
|
|
1182
|
-
on the last page — together they make the ``{items, next_cursor?}`` shape vendors such
|
|
1183
|
-
as Brex answer, which a client may check with ``"next_cursor" in body``."""
|
|
1184
|
-
if not isinstance(page, Page):
|
|
1185
|
-
page = Page(page, len(page), 0, len(page), "none")
|
|
1186
|
-
key = settings.envelope if envelope is None else envelope
|
|
1187
|
-
if not key:
|
|
1188
|
-
return page.rows
|
|
1189
|
-
paging = paging or settings.paging
|
|
1190
|
-
link = link if settings.page_links else None
|
|
1191
|
-
out = {key: page.rows}
|
|
1192
|
-
if settings.hits_key:
|
|
1193
|
-
out[settings.hits_key] = page.total
|
|
1194
|
-
if page.next_offset is not None or not omit_done_cursor:
|
|
1195
|
-
out[settings.cursor_key] = _page_ref(page, page.next_offset, paging, link)
|
|
1196
|
-
if settings.previous_key:
|
|
1197
|
-
out[settings.previous_key] = _page_ref(page, page.previous_offset, paging, link)
|
|
1198
|
-
return out
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
def _normalize(result: Any, default_status: int | None) -> Any:
|
|
1202
|
-
"""What a handler (or the gate) hands back, as ``(status, body, headers)``.
|
|
1203
|
-
|
|
1204
|
-
A handler returns a body, ``(status, body)`` or ``(status, body, headers)``;
|
|
1205
|
-
the gate returns ``None`` to let the request through or one of those to stop it."""
|
|
1206
|
-
if result is None and default_status is None:
|
|
1207
|
-
return None
|
|
1208
|
-
if (
|
|
1209
|
-
isinstance(result, tuple)
|
|
1210
|
-
and len(result) in (2, 3)
|
|
1211
|
-
and isinstance(result[0], int)
|
|
1212
|
-
and not isinstance(result[0], bool)
|
|
1213
|
-
):
|
|
1214
|
-
status, body = result[0], result[1]
|
|
1215
|
-
extra = result[2] if len(result) == 3 else None
|
|
1216
|
-
if extra is not None and not (
|
|
1217
|
-
isinstance(extra, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in extra.items())
|
|
1218
|
-
):
|
|
1219
|
-
fail("handlers", "A handler's headers are a mapping of header names to strings", "/api/handlers")
|
|
1220
|
-
if isinstance(body, bytes) and not any(k.lower() == "content-type" for k in extra or {}):
|
|
1221
|
-
# Bytes go on the wire as they are (an event stream, a file); the
|
|
1222
|
-
# handler says what they are, since the world's JSON type is not it.
|
|
1223
|
-
fail("handlers", "A handler answering bytes names the Content-Type in its headers", "/api/handlers")
|
|
1224
|
-
return status, body, extra
|
|
1225
|
-
return default_status, result, None
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
1063
|
def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
|
|
1229
1064
|
"""Assign a dotted target (``attributes.note``), keeping the rest of a nested
|
|
1230
1065
|
object an update leaves alone."""
|
|
@@ -1251,7 +1086,7 @@ def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | Non
|
|
|
1251
1086
|
row: dict = json.loads(json.dumps(op.defaults)) if current is None else {}
|
|
1252
1087
|
if op.body:
|
|
1253
1088
|
for field_name, path in op.body.items():
|
|
1254
|
-
value =
|
|
1089
|
+
value = dig(body, path)
|
|
1255
1090
|
if value is not None:
|
|
1256
1091
|
_set(row, field_name, value, current)
|
|
1257
1092
|
else:
|
|
@@ -1289,7 +1124,7 @@ def vendor_credential(spec: Spec, presented: str, *, grant: str | None = None) -
|
|
|
1289
1124
|
if spec.scheme == "query":
|
|
1290
1125
|
return {}, {spec.auth_name or "api_key": presented}
|
|
1291
1126
|
fail("spec", f"auth scheme '{spec.scheme}' has no credential shape to present", "/auth/scheme")
|
|
1292
|
-
raise AssertionError
|
|
1127
|
+
raise AssertionError
|
|
1293
1128
|
|
|
1294
1129
|
|
|
1295
1130
|
def with_query(target: str, extra: dict[str, str]) -> str:
|
|
@@ -1305,140 +1140,15 @@ def with_query(target: str, extra: dict[str, str]) -> str:
|
|
|
1305
1140
|
return urllib.parse.urlunsplit(url._replace(query=urllib.parse.urlencode(query)))
|
|
1306
1141
|
|
|
1307
1142
|
|
|
1308
|
-
def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str, str, bytes]:
|
|
1309
|
-
"""``(method, target, raw body)`` of an operation called by name with a
|
|
1310
|
-
tool call's ``args``, the way a session's ``call`` verb takes one:
|
|
1311
|
-
``args.path`` fills the route's ``{segments}`` (a top-level argument of
|
|
1312
|
-
the segment's name does too, so ``get_wallet {"id": "W1"}`` reads as
|
|
1313
|
-
``/wallets/W1``), ``args.query`` is its query string, ``args.body`` (or
|
|
1314
|
-
every other key, for a call written like a tool's) its JSON body; a GET
|
|
1315
|
-
carries none. The target is under the spec's ``base_url`` path."""
|
|
1316
|
-
path = operation.path
|
|
1317
|
-
path_params = dict(args.get("path")) if isinstance(args.get("path"), dict) else {}
|
|
1318
|
-
consumed: set[str] = set()
|
|
1319
|
-
for name in operation.placeholders:
|
|
1320
|
-
if name not in path_params and name in args and not isinstance(args[name], (dict, list)):
|
|
1321
|
-
path_params[name] = args[name]
|
|
1322
|
-
consumed.add(name)
|
|
1323
|
-
for key, value in path_params.items():
|
|
1324
|
-
path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
|
|
1325
|
-
query = args.get("query") if isinstance(args.get("query"), dict) else {}
|
|
1326
|
-
body = args.get("body") if isinstance(args.get("body"), dict) else None
|
|
1327
|
-
leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body") and k not in consumed}
|
|
1328
|
-
if operation.method == "GET" and leftovers:
|
|
1329
|
-
# A GET carries no body: a call written like a tool's (``list_accounts {"status": "frozen"}``)
|
|
1330
|
-
# means its query string, so the filter it asks for reaches the route.
|
|
1331
|
-
query = {**{k: v for k, v in leftovers.items() if not isinstance(v, (dict, list))}, **query}
|
|
1332
|
-
body = None
|
|
1333
|
-
elif body is None:
|
|
1334
|
-
body = leftovers or None
|
|
1335
|
-
if query:
|
|
1336
|
-
path = f"{path}?" + urllib.parse.urlencode({k: str(v) for k, v in query.items()})
|
|
1337
|
-
raw = json.dumps(body).encode("utf-8") if body is not None and operation.method != "GET" else b""
|
|
1338
|
-
base = urllib.parse.urlsplit(spec.base_url).path.rstrip("/")
|
|
1339
|
-
return operation.method, f"{base}{path}", raw
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
1143
|
Response = tuple[int, Any, dict[str, str] | None]
|
|
1343
1144
|
|
|
1344
1145
|
|
|
1345
|
-
|
|
1346
|
-
"""
|
|
1347
|
-
if out is None:
|
|
1348
|
-
out = []
|
|
1349
|
-
if isinstance(node, str):
|
|
1350
|
-
if node not in out:
|
|
1351
|
-
out.append(node)
|
|
1352
|
-
elif isinstance(node, dict):
|
|
1353
|
-
for value in node.values():
|
|
1354
|
-
_strings_in(value, out)
|
|
1355
|
-
elif isinstance(node, (list, tuple)):
|
|
1356
|
-
for value in node:
|
|
1357
|
-
_strings_in(value, out)
|
|
1358
|
-
return out
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
class Via(StrEnum):
|
|
1362
|
-
"""The door a vendor-route request came in by, set by the server from where
|
|
1363
|
-
it arrived and never from a request header. It names the door, not the
|
|
1364
|
-
actor: a token holder calling the ui origin's prefix without a browser is
|
|
1365
|
-
``ui``."""
|
|
1366
|
-
|
|
1367
|
-
API = "api"
|
|
1368
|
-
UI = "ui"
|
|
1369
|
-
TOOL = "tool"
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
class CallLog:
|
|
1373
|
-
"""The vendor-route requests one session answered, in order: what the agent
|
|
1374
|
-
asked (operation, method, path, path args, query, body), the door it came
|
|
1375
|
-
in by (``via``) and what came back (status, ``rows`` = the length of the
|
|
1376
|
-
operation's ``results`` list when the answer carries one, elapsed).
|
|
1377
|
-
``selectors`` is every string the request carried wherever it sat, and
|
|
1378
|
-
``found`` is "answered with rows", so a grader's scalar ``where`` can ask
|
|
1379
|
-
either without the vendor's request shape. Bounded; ``total`` counts past
|
|
1380
|
-
the bound. ``/__world/calls`` serves it and a task's ``verify.py`` is
|
|
1381
|
-
handed it as ``calls`` beside the rows, because a read-only investigation
|
|
1382
|
-
leaves no row behind and its calls are the only evidence of what it did."""
|
|
1383
|
-
|
|
1384
|
-
def __init__(self, maximum: int | None = None):
|
|
1385
|
-
if maximum is None:
|
|
1386
|
-
raw = os.environ.get("WORLDS_CALL_LOG_MAX")
|
|
1387
|
-
maximum = int(raw) if raw else DEFAULT_CALL_LOG_MAX
|
|
1388
|
-
self.maximum = max(0, int(maximum))
|
|
1389
|
-
self.entries: collections.deque[dict] = collections.deque(maxlen=self.maximum or None)
|
|
1390
|
-
self.total = 0
|
|
1391
|
-
self._lock = threading.Lock()
|
|
1392
|
-
|
|
1393
|
-
def record(
|
|
1394
|
-
self,
|
|
1395
|
-
operation: Operation,
|
|
1396
|
-
method: str,
|
|
1397
|
-
path: str,
|
|
1398
|
-
args: dict,
|
|
1399
|
-
query_all: dict,
|
|
1400
|
-
body: Any,
|
|
1401
|
-
status: int,
|
|
1402
|
-
answer: Any,
|
|
1403
|
-
elapsed_s: float,
|
|
1404
|
-
via: Via | None,
|
|
1405
|
-
) -> None:
|
|
1406
|
-
if self.maximum == 0:
|
|
1407
|
-
return
|
|
1408
|
-
rows = None
|
|
1409
|
-
if isinstance(answer, dict) and isinstance(answer.get(operation.results), list):
|
|
1410
|
-
rows = len(answer[operation.results])
|
|
1411
|
-
elif isinstance(answer, list):
|
|
1412
|
-
rows = len(answer)
|
|
1413
|
-
query = {k: (v[0] if len(v) == 1 else list(v)) for k, v in query_all.items()}
|
|
1414
|
-
entry = {
|
|
1415
|
-
"seq": self.total + 1,
|
|
1416
|
-
"at": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
|
|
1417
|
-
"operation": operation.name,
|
|
1418
|
-
"method": method,
|
|
1419
|
-
"path": path,
|
|
1420
|
-
"args": dict(args),
|
|
1421
|
-
"query": query,
|
|
1422
|
-
"body": body if isinstance(body, (dict, list)) and body else None,
|
|
1423
|
-
"selectors": _strings_in([args, query, body]),
|
|
1424
|
-
**({} if via is None else {"via": str(via)}),
|
|
1425
|
-
"status": status,
|
|
1426
|
-
"rows": rows,
|
|
1427
|
-
"found": status < 400 and rows is not None and rows > 0,
|
|
1428
|
-
"elapsed_ms": round(elapsed_s * 1000, 1),
|
|
1429
|
-
}
|
|
1430
|
-
with self._lock:
|
|
1431
|
-
self.total += 1
|
|
1432
|
-
self.entries.append(entry)
|
|
1146
|
+
class _Refused(Exception):
|
|
1147
|
+
"""A route that answered an error: its writes are rolled back, its answer still sent."""
|
|
1433
1148
|
|
|
1434
|
-
def
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
def clear(self) -> None:
|
|
1439
|
-
with self._lock:
|
|
1440
|
-
self.entries.clear()
|
|
1441
|
-
self.total = 0
|
|
1149
|
+
def __init__(self, response: Response):
|
|
1150
|
+
super().__init__(response[0])
|
|
1151
|
+
self.response = response
|
|
1442
1152
|
|
|
1443
1153
|
|
|
1444
1154
|
class WorldApp:
|
|
@@ -1448,7 +1158,16 @@ class WorldApp:
|
|
|
1448
1158
|
headers, raw body) and answers ``(status, body, extra headers)``; nothing in
|
|
1449
1159
|
it touches a socket. ``make_handler`` wraps it for ``serve()``, and the
|
|
1450
1160
|
World Host calls it for whichever session a request names, so one process
|
|
1451
|
-
can answer for many worlds without the handler knowing.
|
|
1161
|
+
can answer for many worlds without the handler knowing. ``routes_closed``:
|
|
1162
|
+
the session's task lists the tools it may call, so every route answers 403
|
|
1163
|
+
before any handler runs, and the list holds against a client calling the
|
|
1164
|
+
vendor API directly. ``calls`` is the session's call log, shared with its
|
|
1165
|
+
tools; a world served alone keeps its own.
|
|
1166
|
+
|
|
1167
|
+
``admin`` serves the runner's ``/__world/*`` routes (state, calls, reset,
|
|
1168
|
+
seed) to the holder of its token, for the runner's bundle server (``serve()``)
|
|
1169
|
+
and a local session. A World Host session's doors carry the agent's token, and
|
|
1170
|
+
those routes read and rewrite what its grader reads, so the host passes none.
|
|
1452
1171
|
"""
|
|
1453
1172
|
|
|
1454
1173
|
def __init__(
|
|
@@ -1457,20 +1176,19 @@ class WorldApp:
|
|
|
1457
1176
|
router: Router,
|
|
1458
1177
|
key: str | None,
|
|
1459
1178
|
handlers: dict[str, Handler] | None = None,
|
|
1460
|
-
|
|
1461
|
-
|
|
1179
|
+
routes_closed: bool = False,
|
|
1180
|
+
calls: CallLog | None = None,
|
|
1181
|
+
admin: AdminToken | None = None,
|
|
1462
1182
|
):
|
|
1463
1183
|
self.state = state
|
|
1464
1184
|
self.router = router
|
|
1465
1185
|
self.key = key
|
|
1186
|
+
self.admin = admin
|
|
1466
1187
|
self.settings = router.settings
|
|
1467
1188
|
self.prefix = urllib.parse.urlsplit(router.spec.base_url).path.rstrip("/")
|
|
1468
1189
|
self.handlers = load_handlers(self.settings) if handlers is None else handlers
|
|
1469
|
-
|
|
1470
|
-
|
|
1471
|
-
#: list holds against a client that talks to the vendor API directly.
|
|
1472
|
-
self.allowed = allowed
|
|
1473
|
-
self.calls = CallLog(call_log_max)
|
|
1190
|
+
self.routes_closed = routes_closed
|
|
1191
|
+
self.calls = calls if calls is not None else CallLog.for_spec(router.spec)
|
|
1474
1192
|
|
|
1475
1193
|
@staticmethod
|
|
1476
1194
|
def _json(raw: bytes) -> Any:
|
|
@@ -1478,7 +1196,7 @@ class WorldApp:
|
|
|
1478
1196
|
return {}
|
|
1479
1197
|
try:
|
|
1480
1198
|
return json.loads(raw.decode("utf-8"))
|
|
1481
|
-
except (
|
|
1199
|
+
except (ValueError, RecursionError):
|
|
1482
1200
|
return None
|
|
1483
1201
|
|
|
1484
1202
|
@staticmethod
|
|
@@ -1500,7 +1218,7 @@ class WorldApp:
|
|
|
1500
1218
|
if content_type == "application/json":
|
|
1501
1219
|
try:
|
|
1502
1220
|
parsed = json.loads(raw.decode("utf-8"))
|
|
1503
|
-
except (
|
|
1221
|
+
except (ValueError, RecursionError):
|
|
1504
1222
|
return {}
|
|
1505
1223
|
return {k: str(v) for k, v in parsed.items()} if isinstance(parsed, dict) else {}
|
|
1506
1224
|
form = {k: v[0] for k, v in urllib.parse.parse_qs(raw.decode("utf-8", "replace")).items()}
|
|
@@ -1526,47 +1244,59 @@ class WorldApp:
|
|
|
1526
1244
|
a link uses when the request carries no Host header; ``via`` is the door
|
|
1527
1245
|
the caller took it in by, recorded on the call when there is one."""
|
|
1528
1246
|
url = urllib.parse.urlsplit(target)
|
|
1529
|
-
settings, router
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
|
|
1533
|
-
|
|
1534
|
-
|
|
1535
|
-
if
|
|
1536
|
-
return
|
|
1537
|
-
|
|
1538
|
-
if url.path == ADMIN["reset"]:
|
|
1539
|
-
state.reset()
|
|
1540
|
-
return 200, {"ok": True}, None
|
|
1541
|
-
if url.path == ADMIN["seed"]:
|
|
1542
|
-
body = self._json(raw)
|
|
1543
|
-
if body is None:
|
|
1544
|
-
return 400, {"error": "seed must be JSON"}, None
|
|
1545
|
-
try:
|
|
1546
|
-
state.seed(body)
|
|
1547
|
-
except ContractError as error:
|
|
1548
|
-
if error.detail.get("code") == "base_mismatch":
|
|
1549
|
-
return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
|
|
1550
|
-
return 400, {"error": "seed_rejected", "detail": str(error)}, None
|
|
1551
|
-
except Exception as error: # a rejected seed is the caller's problem, reported plainly
|
|
1552
|
-
return 400, {"error": "seed_rejected", "detail": str(error)}, None
|
|
1553
|
-
return 200, {"ok": True}, None
|
|
1554
|
-
if settings.token_path and self._strip(url.path) == settings.token_path:
|
|
1555
|
-
issued = router.issue_token(self._form(raw, headers), self.key)
|
|
1556
|
-
if issued is None:
|
|
1557
|
-
return 400, {"error": "invalid_client"}, None
|
|
1558
|
-
return 200, issued, None
|
|
1247
|
+
settings, router = self.settings, self.router
|
|
1248
|
+
answered = self._admin(method, url.path, raw, headers)
|
|
1249
|
+
if answered is not None:
|
|
1250
|
+
return answered
|
|
1251
|
+
if method == "POST" and settings.token_path and self._strip(url.path) == settings.token_path:
|
|
1252
|
+
issued = router.issue_token(self._form(raw, headers), self.key)
|
|
1253
|
+
if issued is None:
|
|
1254
|
+
return 400, {"error": "invalid_client"}, None
|
|
1255
|
+
return 200, issued, None
|
|
1559
1256
|
if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
|
|
1560
1257
|
return 405, {"error": "method_not_allowed"}, None
|
|
1561
1258
|
return self._route(method, url, headers, raw, default_host, via)
|
|
1562
1259
|
|
|
1260
|
+
def _admin(self, method: str, path: str, raw: bytes, headers: dict[str, str]) -> Response | None:
|
|
1261
|
+
"""The runner's routes, or None for a request that is not one of them. Health answers on
|
|
1262
|
+
every door; the rest only where :attr:`admin` is set, and there only to its token."""
|
|
1263
|
+
state = self.state
|
|
1264
|
+
if (method, path) == ("GET", ADMIN["health"]):
|
|
1265
|
+
return 200, {"ok": True, "world": self.router.spec.slug}, None
|
|
1266
|
+
if self.admin is None or path not in RUNNER_PATHS:
|
|
1267
|
+
return None
|
|
1268
|
+
if not self.admin.admits(headers):
|
|
1269
|
+
return 403, {"error": "admin_token_required"}, None
|
|
1270
|
+
if (method, path) == ("GET", ADMIN["state"]):
|
|
1271
|
+
return 200, self.calls.into_state({**state.dump(), "snapshot": state.describe_snapshot()}), None
|
|
1272
|
+
if (method, path) == ("GET", ADMIN["calls"]):
|
|
1273
|
+
return 200, self.calls.describe(), None
|
|
1274
|
+
if (method, path) == ("POST", ADMIN["reset"]):
|
|
1275
|
+
state.reset()
|
|
1276
|
+
return 200, {"ok": True}, None
|
|
1277
|
+
if (method, path) == ("POST", ADMIN["seed"]):
|
|
1278
|
+
return self._seed(raw)
|
|
1279
|
+
return None
|
|
1280
|
+
|
|
1281
|
+
def _seed(self, raw: bytes) -> Response:
|
|
1282
|
+
body = self._json(raw)
|
|
1283
|
+
if body is None:
|
|
1284
|
+
return 400, {"error": "seed must be JSON"}, None
|
|
1285
|
+
try:
|
|
1286
|
+
self.state.seed(body)
|
|
1287
|
+
except ContractError as error:
|
|
1288
|
+
if error.detail.get("code") == "base_mismatch":
|
|
1289
|
+
return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
|
|
1290
|
+
return 400, {"error": "seed_rejected", "detail": str(error)}, None
|
|
1291
|
+
except Exception as error: # a rejected seed is the caller's problem, reported plainly
|
|
1292
|
+
return 400, {"error": "seed_rejected", "detail": str(error)}, None
|
|
1293
|
+
return 200, {"ok": True}, None
|
|
1294
|
+
|
|
1563
1295
|
def _route(
|
|
1564
1296
|
self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
|
|
1565
1297
|
) -> Response:
|
|
1566
1298
|
settings, router = self.settings, self.router
|
|
1567
1299
|
path = self._strip(url.path)
|
|
1568
|
-
# Every value of a repeated key is kept; ``query`` hands routes the first, the way
|
|
1569
|
-
# they always read it, and ``ctx.query_all`` hands handlers and filters the rest.
|
|
1570
1300
|
query_all = {k: list(v) for k, v in urllib.parse.parse_qs(url.query).items()}
|
|
1571
1301
|
query = {k: v[0] for k, v in query_all.items()}
|
|
1572
1302
|
if not router.authorized(headers, query, self.key):
|
|
@@ -1575,40 +1305,51 @@ class WorldApp:
|
|
|
1575
1305
|
if matched is None:
|
|
1576
1306
|
return settings.not_found_status, settings.not_found, None
|
|
1577
1307
|
operation, args = matched
|
|
1578
|
-
if self.
|
|
1579
|
-
return 403, {"error": "
|
|
1308
|
+
if self.routes_closed:
|
|
1309
|
+
return 403, {"error": "route_not_allowed", "operation": operation.name, "detail": ROUTES_CLOSED}, None
|
|
1580
1310
|
op = settings.for_operation(operation.name)
|
|
1581
1311
|
body = self._body(raw, headers) if method in ("POST", "PUT", "PATCH") else {}
|
|
1582
1312
|
if body is None:
|
|
1583
1313
|
return settings.invalid_status, settings.invalid, None
|
|
1584
1314
|
started = time.monotonic()
|
|
1585
|
-
status, answer, extra =
|
|
1586
|
-
|
|
1587
|
-
|
|
1315
|
+
status, answer, extra = 500, None, None
|
|
1316
|
+
try:
|
|
1317
|
+
status, answer, extra = self._answer_atomically(
|
|
1318
|
+
op, operation, args, query, query_all, body, headers, url, default_host
|
|
1319
|
+
)
|
|
1320
|
+
finally:
|
|
1321
|
+
elapsed = time.monotonic() - started
|
|
1322
|
+
shape = settings.answer_shape(op, operation)
|
|
1323
|
+
self.calls.record(operation, method, path, args, query_all, body, status, answer, elapsed, via, shape=shape)
|
|
1588
1324
|
return status, answer, extra
|
|
1589
1325
|
|
|
1326
|
+
def _answer_atomically(self, *request) -> Response:
|
|
1327
|
+
try:
|
|
1328
|
+
with self.state.transaction():
|
|
1329
|
+
response = self._answer_route(*request)
|
|
1330
|
+
if response[0] >= 400:
|
|
1331
|
+
raise _Refused(response)
|
|
1332
|
+
except _Refused as refused:
|
|
1333
|
+
return refused.response
|
|
1334
|
+
except ContractError as error:
|
|
1335
|
+
return (*self.settings.refusal(getattr(error, "detail", None) or {"message": str(error)}), None)
|
|
1336
|
+
return response
|
|
1337
|
+
|
|
1590
1338
|
def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
|
|
1591
|
-
|
|
1339
|
+
router, state, handlers = self.router, self.state, self.handlers
|
|
1592
1340
|
host = headers.get("host") or default_host
|
|
1593
1341
|
forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
|
|
1594
1342
|
ctx = ApiContext(state, router, operation, link=(f"{forwarded}://{host}{url.path}", query))
|
|
1595
1343
|
ctx.headers = headers
|
|
1596
1344
|
ctx.query_all = query_all
|
|
1597
|
-
|
|
1598
|
-
|
|
1599
|
-
|
|
1600
|
-
|
|
1601
|
-
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
|
-
|
|
1605
|
-
except ContractError as error:
|
|
1606
|
-
detail = getattr(error, "detail", None) or {"message": str(error)}
|
|
1607
|
-
invalid = settings.invalid
|
|
1608
|
-
if isinstance(invalid, dict):
|
|
1609
|
-
invalid = {**invalid, "detail": detail}
|
|
1610
|
-
return settings.invalid_status, invalid, None
|
|
1611
|
-
return status, answer, extra
|
|
1345
|
+
request = (ctx, args, query, body)
|
|
1346
|
+
gate = self.settings.before or BEFORE
|
|
1347
|
+
verdict = handled_answer(gate, handlers[BEFORE], request, None) if BEFORE in handlers else None
|
|
1348
|
+
if verdict is not None:
|
|
1349
|
+
return verdict
|
|
1350
|
+
if op.action == "handler":
|
|
1351
|
+
return handled_answer(op.handler or operation.name, handlers[operation.name], request, op.status)
|
|
1352
|
+
return normalize_answer(self._answer(op, operation, ctx, args, query, body), op.status)
|
|
1612
1353
|
|
|
1613
1354
|
@staticmethod
|
|
1614
1355
|
def _answer(
|
|
@@ -1618,34 +1359,32 @@ class WorldApp:
|
|
|
1618
1359
|
args: dict[str, str],
|
|
1619
1360
|
query: dict[str, str],
|
|
1620
1361
|
body: Any,
|
|
1621
|
-
handlers: dict[str, Handler],
|
|
1622
1362
|
) -> Any:
|
|
1623
|
-
if op.action == "handler":
|
|
1624
|
-
return handlers[operation.name](ctx, args, query, body)
|
|
1625
1363
|
if not operation.entity:
|
|
1626
1364
|
return 501, {"error": "not_modelled", "operation": operation.name}
|
|
1627
1365
|
entity = operation.entity
|
|
1628
1366
|
omit_done_cursor = ctx.settings.omits_done_cursor(op)
|
|
1629
1367
|
if op.action == "create":
|
|
1630
1368
|
row = ctx.insert(entity, _bind(op, ctx, body))
|
|
1631
|
-
return op.status,
|
|
1632
|
-
|
|
1369
|
+
return op.status, _one(op, ctx, row)
|
|
1370
|
+
selection = op.filter or _segment_filter(operation, ctx, entity)
|
|
1371
|
+
if not selection and (op.action in ("update", "delete") or (op.single and operation.placeholders)):
|
|
1372
|
+
fail(
|
|
1373
|
+
"spec",
|
|
1374
|
+
f"route {operation.name} finds its row by nothing: its path names no field of {entity} and it "
|
|
1375
|
+
"declares no api.filter; map a path argument to a field with api.filter, or answer the route with "
|
|
1376
|
+
'action = "handler"',
|
|
1377
|
+
f"/operations/{operation.name}/api/filter",
|
|
1378
|
+
)
|
|
1379
|
+
filters = selection
|
|
1633
1380
|
if not op.filter and op.action == "read":
|
|
1634
1381
|
filters = {**_query_field_filter(ctx, entity, ctx.query_all), **filters}
|
|
1635
|
-
#
|
|
1636
|
-
# reads as "either", not as "a" with "b" silently dropped.
|
|
1382
|
+
# Every value sent filters: ``status[]=a&status[]=b`` reads as either, never as a with b dropped.
|
|
1637
1383
|
values: dict[str, str | list[str]] = {
|
|
1638
1384
|
**{k: v for k, v in ctx.query_all.items() if k in operation.params or k in filters},
|
|
1639
1385
|
**args,
|
|
1640
1386
|
}
|
|
1641
|
-
|
|
1642
|
-
fail(
|
|
1643
|
-
"spec",
|
|
1644
|
-
f"route {operation.name} finds its row by nothing: its path names no primary-key field of {entity} "
|
|
1645
|
-
f"and it declares no api.filter",
|
|
1646
|
-
f"/operations/{operation.name}/api/filter",
|
|
1647
|
-
)
|
|
1648
|
-
rows = [row for row in ctx.rows(entity) if _matches(row, filters, values, op.match)]
|
|
1387
|
+
rows = RowMatch(filters, values, op.match or {}).select(ctx.rows(entity))
|
|
1649
1388
|
if op.action in ("update", "delete"):
|
|
1650
1389
|
if len(rows) != 1:
|
|
1651
1390
|
return ctx.not_found()
|
|
@@ -1654,11 +1393,11 @@ class WorldApp:
|
|
|
1654
1393
|
ctx.delete(entity, key)
|
|
1655
1394
|
return op.status, None
|
|
1656
1395
|
row = ctx.update(entity, key, _bind(op, ctx, body, current=rows[0]))
|
|
1657
|
-
return op.status,
|
|
1396
|
+
return op.status, _one(op, ctx, row)
|
|
1397
|
+
if op.single and not rows:
|
|
1398
|
+
return ctx.not_found()
|
|
1658
1399
|
if op.single:
|
|
1659
|
-
|
|
1660
|
-
return ctx.not_found()
|
|
1661
|
-
return op.status, rows[0]
|
|
1400
|
+
return op.status, single(rows[0], op.envelope, op.wrapper)
|
|
1662
1401
|
paging = (
|
|
1663
1402
|
ctx.settings.paging
|
|
1664
1403
|
if op.paging is None
|
|
@@ -1673,11 +1412,26 @@ class WorldApp:
|
|
|
1673
1412
|
page = paginate(rows, query, paging)
|
|
1674
1413
|
return (
|
|
1675
1414
|
op.status,
|
|
1676
|
-
wrap(
|
|
1415
|
+
wrap(
|
|
1416
|
+
page,
|
|
1417
|
+
ctx.settings,
|
|
1418
|
+
op.envelope,
|
|
1419
|
+
paging=paging,
|
|
1420
|
+
link=ctx.link,
|
|
1421
|
+
omit_done_cursor=omit_done_cursor,
|
|
1422
|
+
wrapper=op.wrapper,
|
|
1423
|
+
),
|
|
1677
1424
|
page_headers(page, ctx.settings, paging),
|
|
1678
1425
|
)
|
|
1679
1426
|
|
|
1680
1427
|
|
|
1428
|
+
def _one(op: OperationSettings, ctx: ApiContext, row: dict) -> Any:
|
|
1429
|
+
"""A written row answered the route's way: alone (at its own envelope), or as a list of one."""
|
|
1430
|
+
if op.single:
|
|
1431
|
+
return single(row, op.envelope, op.wrapper)
|
|
1432
|
+
return wrap([row], ctx.settings, op.envelope, wrapper=op.wrapper)
|
|
1433
|
+
|
|
1434
|
+
|
|
1681
1435
|
def send_response(
|
|
1682
1436
|
handler: BaseHTTPRequestHandler, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str
|
|
1683
1437
|
) -> None:
|
|
@@ -1691,7 +1445,6 @@ def send_response(
|
|
|
1691
1445
|
return
|
|
1692
1446
|
headers = dict(extra or {})
|
|
1693
1447
|
if isinstance(body, bytes):
|
|
1694
|
-
# As the handler shaped them, under the Content-Type it named (checked in _normalize).
|
|
1695
1448
|
payload = body
|
|
1696
1449
|
else:
|
|
1697
1450
|
payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
|
|
@@ -1704,8 +1457,8 @@ def send_response(
|
|
|
1704
1457
|
handler.wfile.write(payload)
|
|
1705
1458
|
|
|
1706
1459
|
|
|
1707
|
-
def make_handler(state: WorldState, router: Router, key: str | None):
|
|
1708
|
-
app = WorldApp(state, router, key)
|
|
1460
|
+
def make_handler(state: WorldState, router: Router, key: str | None, admin: AdminToken | None = None):
|
|
1461
|
+
app = WorldApp(state, router, key, admin=admin or AdminToken())
|
|
1709
1462
|
|
|
1710
1463
|
class Handler(BaseHTTPRequestHandler):
|
|
1711
1464
|
server_version = f"gateway-world-api/{router.spec.slug}"
|
|
@@ -1747,22 +1500,24 @@ def serve(
|
|
|
1747
1500
|
host: str = "0.0.0.0",
|
|
1748
1501
|
api_key: str | None = None,
|
|
1749
1502
|
scenario: str | None = None,
|
|
1503
|
+
admin: AdminToken | None = None,
|
|
1750
1504
|
) -> ThreadingHTTPServer:
|
|
1751
|
-
"""Start the world's API and return the server; the caller decides how long it runs.
|
|
1505
|
+
"""Start the world's API and return the server; the caller decides how long it runs.
|
|
1506
|
+
``admin`` admits its holder to the runner's ``/__world/*`` routes; without one they are refused."""
|
|
1752
1507
|
root = Path(world)
|
|
1753
1508
|
spec = load_spec(root)
|
|
1754
1509
|
settings = load_api_settings(root, spec)
|
|
1755
1510
|
state = WorldState(root)
|
|
1756
1511
|
if scenario:
|
|
1757
1512
|
state.apply_scenario(scenario)
|
|
1758
|
-
server = ThreadingHTTPServer((host, port), make_handler(state, Router(spec, settings), api_key))
|
|
1759
|
-
server.world_state = state # type: ignore[attr-defined]
|
|
1513
|
+
server = ThreadingHTTPServer((host, port), make_handler(state, Router(spec, settings), api_key, admin))
|
|
1514
|
+
server.world_state = state # type: ignore[attr-defined] # close() finds the state on its server
|
|
1760
1515
|
return server
|
|
1761
1516
|
|
|
1762
1517
|
|
|
1763
1518
|
def fetch_hosted_snapshot(world: str | Path, environ: dict[str, str] | None = None) -> dict | None:
|
|
1764
1519
|
"""The hosted pod's snapshot, when ``WORLD_SNAPSHOT_URL`` / ``_SHA256`` / ``_DIGEST``
|
|
1765
|
-
are set: downloaded to ``db
|
|
1520
|
+
are set: downloaded to ``db/<snapshot name>``, verified, sidecar written. All three
|
|
1766
1521
|
are required together; a digest mismatch is fatal and names the digest."""
|
|
1767
1522
|
env = os.environ if environ is None else environ
|
|
1768
1523
|
values = {name: env.get(name) for name in (snapshots.ENV_URL, snapshots.ENV_SHA256, snapshots.ENV_DIGEST)}
|
|
@@ -1791,13 +1546,13 @@ def serve_forever(
|
|
|
1791
1546
|
raise SystemExit(2)
|
|
1792
1547
|
if fetched:
|
|
1793
1548
|
print(f"world snapshot {fetched['batchDigest']} opened", file=sys.stderr)
|
|
1794
|
-
server = serve(world, port=port, api_key=api_key, scenario=scenario)
|
|
1549
|
+
server = serve(world, port=port, api_key=api_key, scenario=scenario, admin=AdminToken.from_env())
|
|
1795
1550
|
try:
|
|
1796
1551
|
print(f"world api listening on http://0.0.0.0:{port}", file=sys.stderr)
|
|
1797
1552
|
server.serve_forever()
|
|
1798
1553
|
finally:
|
|
1799
1554
|
server.server_close()
|
|
1800
|
-
server.world_state.close() # type: ignore[attr-defined]
|
|
1555
|
+
server.world_state.close() # type: ignore[attr-defined] # set by serve()
|
|
1801
1556
|
|
|
1802
1557
|
|
|
1803
1558
|
def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
|
|
@@ -1840,14 +1595,11 @@ def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None
|
|
|
1840
1595
|
):
|
|
1841
1596
|
entry["requestBody"] = {"content": {"application/json": {"schema": {"type": "object"}}}}
|
|
1842
1597
|
if len(operation.methods) > 1:
|
|
1843
|
-
# One OpenAPI operation, listed under the verb a capture sends; the
|
|
1844
|
-
# others the served route also answers are named here.
|
|
1845
1598
|
entry["x-gateway-methods"] = list(operation.methods)
|
|
1846
1599
|
methods = paths.setdefault(operation.path, {})
|
|
1847
1600
|
method = operation.method.lower()
|
|
1848
1601
|
if method in methods:
|
|
1849
|
-
# OpenAPI keys one operation per path+method
|
|
1850
|
-
# by query parameter keeps every one of them here rather than losing all but the first.
|
|
1602
|
+
# OpenAPI keys one operation per path+method, so query-parameter variants ride here, not lost.
|
|
1851
1603
|
methods[method].setdefault("x-gateway-variants", []).append(
|
|
1852
1604
|
{
|
|
1853
1605
|
k: v
|
|
@@ -1926,8 +1678,7 @@ def build_api_bundle(world: str | Path, out: str | Path) -> Path:
|
|
|
1926
1678
|
"",
|
|
1927
1679
|
]
|
|
1928
1680
|
if settings.ui is not None:
|
|
1929
|
-
# The built ui
|
|
1930
|
-
# there, so no ui image is ever built for a schema world.
|
|
1681
|
+
# The built ui ships inside the copied world, so no ui image is built for a schema world.
|
|
1931
1682
|
manifest += [
|
|
1932
1683
|
"[ui]",
|
|
1933
1684
|
f'static = "server/world/{settings.ui.static}"',
|