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