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