@withgateway/sdk 0.3.3 → 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 +4 -3
- package/dist/cli.js +2221 -962
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2212 -953
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +81 -19
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +79 -17
- 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.d.mts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +903 -221
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +868 -212
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +78 -16
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +76 -14
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +7 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +7 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +692 -410
- package/dist/worlds/index.d.ts +692 -410
- package/dist/worlds/index.js +740 -197
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +736 -193
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +58 -65
- package/runtime/gatewaysdk/environment/backing.py +20 -24
- package/runtime/gatewaysdk/environment/core.py +1 -16
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
- package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +174 -471
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- 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 +230 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
- package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
- 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 +14 -13
- package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
- package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
- package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
- package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
- package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
- 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/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +31 -116
- package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
- 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 +129 -176
- package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
- 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 +8 -9
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
- package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- 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 +203 -39
- package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
- package/runtime/gatewaysdk/environment/world.py +1 -1
- package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/skills/connector-schema-authoring/SKILL.md +31 -6
- package/skills/connector-schema-authoring/connector-worlds.md +129 -7
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +13 -13
- package/skills/worlds-getting-started/SKILL.md +23 -23
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
|
@@ -1,28 +1,4 @@
|
|
|
1
|
-
"""A schema world opened on this machine the way the World Host opens it.
|
|
2
|
-
|
|
3
|
-
One :class:`LocalSession` is one session: the world's template copied into a
|
|
4
|
-
scratch directory, its handlers loaded, every ``[dependencies]`` alias opened
|
|
5
|
-
beside it from its ``path`` (dependency tools served as ``<alias>.<tool>``),
|
|
6
|
-
and, when asked, an HTTP server on a loopback port. The server speaks the
|
|
7
|
-
session verbs under ``/__session/`` for every schema world (``POST call``,
|
|
8
|
-
``GET state``, ``POST grade``, ``POST reset``, ``POST seed``, ``GET tools``,
|
|
9
|
-
``GET task``, ``POST close``, the host's own shapes) and, when the tree carries
|
|
10
|
-
``connector.toml``, the vendor routes beside them with the api pin as the key.
|
|
11
|
-
Tool calls and HTTP requests hit the SAME store, as they do on the host. The
|
|
12
|
-
runner's ``/__world/*`` routes answer only the session's own :attr:`LocalSession.admin`
|
|
13
|
-
token, which ``worlds test`` hands its pytest files; the host serves none of them.
|
|
14
|
-
|
|
15
|
-
The session is what an outside agent works against: ``GET task`` hands it the
|
|
16
|
-
prompt it is to carry out and the verifiers that will grade it (a
|
|
17
|
-
dependency's as ``<alias>/<name>``), the tools answer at ``POST call``, ``POST
|
|
18
|
-
grade`` scores every world's state where it lives, and ``POST close`` ends the
|
|
19
|
-
session — the server stops answering and whoever opened it (``gateway worlds
|
|
20
|
-
serve``) returns.
|
|
21
|
-
|
|
22
|
-
This is what ``gateway worlds call``, ``gateway worlds test`` and
|
|
23
|
-
``gateway worlds serve`` open; what passes here passes hosted, and a world
|
|
24
|
-
that will not open here will not open there either.
|
|
25
|
-
"""
|
|
1
|
+
"""A schema world opened on this machine the way the World Host opens it: what passes here passes hosted."""
|
|
26
2
|
|
|
27
3
|
from __future__ import annotations
|
|
28
4
|
|
|
@@ -40,14 +16,15 @@ from typing import Any, Callable
|
|
|
40
16
|
|
|
41
17
|
from . import snapshot as snapshots
|
|
42
18
|
from .admin_routes import AdminToken
|
|
43
|
-
from .api import Router, Via, WorldApp, load_api_settings, send_response,
|
|
19
|
+
from .api import Router, Via, WorldApp, load_api_settings, send_response, with_query
|
|
20
|
+
from .call_capture import WorldRequestHandler, write_body
|
|
44
21
|
from .call_log import CallLog
|
|
45
22
|
from .compiler import bundle_mode, fail
|
|
46
23
|
from .conform import PIN
|
|
47
24
|
from .connector import SPEC, load_spec
|
|
48
25
|
from .dependencies import local_dependency_trees
|
|
49
26
|
from .host_surfaces import UiSurface, api_target, cross_site, load_ui_surface, static_file
|
|
50
|
-
from .runtime import
|
|
27
|
+
from .runtime import task_card
|
|
51
28
|
from .tools_world import (
|
|
52
29
|
DependencyWorld,
|
|
53
30
|
ToolsTask,
|
|
@@ -63,9 +40,7 @@ LOCAL_TASK = ToolsTask(id="local", prompt="A local session; every verifier grade
|
|
|
63
40
|
|
|
64
41
|
|
|
65
42
|
def has_http(root: str | Path) -> bool:
|
|
66
|
-
"""
|
|
67
|
-
has routes. A schema world without one is tools-only, and that is a whole
|
|
68
|
-
world, not a broken one."""
|
|
43
|
+
"""A schema world without ``connector.toml`` is tools-only: a whole world, not a broken one."""
|
|
69
44
|
return (Path(root) / SPEC).is_file()
|
|
70
45
|
|
|
71
46
|
|
|
@@ -80,9 +55,6 @@ def load_local_version(root: Path, scratch: Path) -> ToolsVersion:
|
|
|
80
55
|
|
|
81
56
|
|
|
82
57
|
def load_local_dependencies(root: Path, version: ToolsVersion, scratch: Path) -> dict[str, DependencyWorld]:
|
|
83
|
-
"""Every alias the manifest declares, opened from its ``path``. A pin with
|
|
84
|
-
no path is refused by :func:`local_dependency_trees`: the platform resolves
|
|
85
|
-
pins, this machine cannot."""
|
|
86
58
|
out: dict[str, DependencyWorld] = {}
|
|
87
59
|
for alias, tree in local_dependency_trees(root, version.dependencies).items():
|
|
88
60
|
dep_version = load_local_version(tree, scratch / "deps" / alias)
|
|
@@ -99,7 +71,7 @@ class LocalSession:
|
|
|
99
71
|
calls: CallLog
|
|
100
72
|
app: WorldApp | None = None
|
|
101
73
|
api_key: str | None = PIN
|
|
102
|
-
#: The key
|
|
74
|
+
#: The only key the runner's /__world/* routes answer, minted per session; the host serves none of them.
|
|
103
75
|
admin: AdminToken = field(default_factory=AdminToken)
|
|
104
76
|
ui: UiSurface | None = None
|
|
105
77
|
#: The ui on its own origin, as the World Host lays it out, so a frontend built for the root runs unchanged.
|
|
@@ -110,27 +82,22 @@ class LocalSession:
|
|
|
110
82
|
|
|
111
83
|
@property
|
|
112
84
|
def base_url(self) -> str | None:
|
|
113
|
-
"""Where the server answers, or ``None`` when opened without one."""
|
|
114
85
|
if self.server is None:
|
|
115
86
|
return None
|
|
116
87
|
return f"http://127.0.0.1:{self.server.server_port}"
|
|
117
88
|
|
|
118
89
|
@property
|
|
119
90
|
def routes(self) -> bool:
|
|
120
|
-
"""Whether the vendor routes are served beside the session verbs."""
|
|
121
91
|
return has_http(self.root)
|
|
122
92
|
|
|
123
93
|
@property
|
|
124
94
|
def ui_url(self) -> str | None:
|
|
125
|
-
"""Where the world's ui answers: its own origin plus its entry, or None
|
|
126
|
-
when the world declares none or the session has no server."""
|
|
127
95
|
if self.ui_server is None or self.ui is None:
|
|
128
96
|
return None
|
|
129
97
|
return f"http://127.0.0.1:{self.ui_server.server_port}{self.ui.entry}"
|
|
130
98
|
|
|
131
99
|
@property
|
|
132
100
|
def ui_prefix_url(self) -> str | None:
|
|
133
|
-
"""The same page under ``/__ui/`` on the session's port, or None."""
|
|
134
101
|
if self.server is None or self.ui is None:
|
|
135
102
|
return None
|
|
136
103
|
return f"{self.base_url}{UI_PREFIX}{self.ui.entry.lstrip('/')}"
|
|
@@ -140,14 +107,9 @@ class LocalSession:
|
|
|
140
107
|
return list(self.world.served)
|
|
141
108
|
|
|
142
109
|
def task(self) -> dict:
|
|
143
|
-
"""The task this session runs, as the outside agent reads it: the prompt
|
|
144
|
-
to carry out, the tools it may call, and the verifiers that grade it,
|
|
145
|
-
the root's by name and each dependency's as ``<alias>/<name>``."""
|
|
146
110
|
return task_card(self.world)
|
|
147
111
|
|
|
148
112
|
def call(self, tool: str, args: dict[str, Any]) -> dict:
|
|
149
|
-
"""The tool's ``{status, body}``; a refusal (a route's name, an unknown
|
|
150
|
-
tool, one outside the task's list) is a 400 answer, not an error."""
|
|
151
113
|
try:
|
|
152
114
|
return self.world.call(tool, args)
|
|
153
115
|
except ContractError as error:
|
|
@@ -175,8 +137,6 @@ class LocalSession:
|
|
|
175
137
|
shutil.rmtree(self._scratch, ignore_errors=True)
|
|
176
138
|
|
|
177
139
|
def wait(self, timeout: float | None = None) -> bool:
|
|
178
|
-
"""Block until the session is asked to end (``POST /__session/close``
|
|
179
|
-
or :meth:`close`); ``False`` when ``timeout`` ran out first."""
|
|
180
140
|
return self.closing.wait(timeout)
|
|
181
141
|
|
|
182
142
|
def __enter__(self) -> LocalSession:
|
|
@@ -197,20 +157,8 @@ def open_world(
|
|
|
197
157
|
ui_port: int | None = None,
|
|
198
158
|
api_key: str | None = PIN,
|
|
199
159
|
) -> LocalSession:
|
|
200
|
-
"""
|
|
201
|
-
|
|
202
|
-
``task`` selects a task the world declares (its prompt is served, its
|
|
203
|
-
verifiers grade — the root's and, per its ``worlds``, each dependency's —
|
|
204
|
-
and its seed is laid); ``None`` opens a plain session where every
|
|
205
|
-
verifier grades.
|
|
206
|
-
``scenario`` starts the root in one of its ``scenarios/<name>``, the
|
|
207
|
-
overlay replacing whole entities on the default state. ``http`` starts the
|
|
208
|
-
server: the session verbs under ``/__session/`` for every world, the
|
|
209
|
-
vendor routes beside them when the world has ``connector.toml``. A world
|
|
210
|
-
that declares ``[ui]`` gets a second listener for the page on its own
|
|
211
|
-
origin (``ui_port``; the next port up when ``port`` is fixed, any free
|
|
212
|
-
one when it is 0), the layout the host serves it in.
|
|
213
|
-
"""
|
|
160
|
+
"""``task`` None opens a plain session every verifier grades; ``ui_port`` None is the next port up from a fixed
|
|
161
|
+
``port``, any free one when ``port`` is 0."""
|
|
214
162
|
root = Path(root)
|
|
215
163
|
scratch = tempfile.mkdtemp(prefix="gateway-local-")
|
|
216
164
|
closing = threading.Event()
|
|
@@ -224,7 +172,7 @@ def open_world(
|
|
|
224
172
|
f"no task '{task}' in {root.name}; it has {', '.join(sorted(version.tasks)) or 'none'}",
|
|
225
173
|
)
|
|
226
174
|
spec = load_spec(root) if has_http(root) else None
|
|
227
|
-
calls = CallLog.for_spec(spec
|
|
175
|
+
calls = CallLog.for_spec(spec, secret=api_key)
|
|
228
176
|
world = ToolsWorld(
|
|
229
177
|
version,
|
|
230
178
|
Path(scratch) / "session",
|
|
@@ -245,15 +193,13 @@ def open_world(
|
|
|
245
193
|
if http:
|
|
246
194
|
if app is not None:
|
|
247
195
|
ui = load_ui_surface(root)
|
|
248
|
-
server = bind_server(
|
|
249
|
-
host, port, make_session_handler(world, app, calls, closing, ui=ui, api_key=api_key)
|
|
250
|
-
)
|
|
196
|
+
server = bind_server(host, port, make_session_handler(world, app, calls, closing, ui=ui))
|
|
251
197
|
threading.Thread(target=server.serve_forever, daemon=True).start()
|
|
252
198
|
if ui is not None:
|
|
253
199
|
ui_server = bind_server(
|
|
254
200
|
host,
|
|
255
201
|
ui_port if ui_port is not None else (port + 1 if port else 0),
|
|
256
|
-
make_session_handler(world, app, calls, closing, ui=ui,
|
|
202
|
+
make_session_handler(world, app, calls, closing, ui=ui, ui_origin=True),
|
|
257
203
|
)
|
|
258
204
|
threading.Thread(target=ui_server.serve_forever, daemon=True).start()
|
|
259
205
|
except BaseException:
|
|
@@ -278,8 +224,7 @@ def open_world(
|
|
|
278
224
|
|
|
279
225
|
|
|
280
226
|
def port_owner(port: int) -> str | None:
|
|
281
|
-
"""
|
|
282
|
-
machine has it; None when nothing can be said. Best effort, never an error."""
|
|
227
|
+
"""Best effort from ``lsof``, never an error; None when nothing can be said."""
|
|
283
228
|
try:
|
|
284
229
|
found = subprocess.run(
|
|
285
230
|
["lsof", "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-Fpc"],
|
|
@@ -302,9 +247,8 @@ def port_owner(port: int) -> str | None:
|
|
|
302
247
|
|
|
303
248
|
|
|
304
249
|
def bind_server(host: str, port: int, handler: type[BaseHTTPRequestHandler]) -> ThreadingHTTPServer:
|
|
305
|
-
"""
|
|
306
|
-
|
|
307
|
-
serve goes unread while every curl after it reaches whatever else answers there."""
|
|
250
|
+
"""A refusal names the port and its holder: a bare EADDRINUSE from a backgrounded serve goes unread while
|
|
251
|
+
every curl after it reaches whatever else answers there."""
|
|
308
252
|
try:
|
|
309
253
|
return ThreadingHTTPServer((host, port), handler)
|
|
310
254
|
except OSError as error:
|
|
@@ -319,7 +263,6 @@ def bind_server(host: str, port: int, handler: type[BaseHTTPRequestHandler]) ->
|
|
|
319
263
|
|
|
320
264
|
|
|
321
265
|
SESSION_PREFIX = "/__session/"
|
|
322
|
-
#: The generated page's mount on the session port; a built ui gets its own origin, as on the host.
|
|
323
266
|
UI_PREFIX = "/__ui/"
|
|
324
267
|
|
|
325
268
|
|
|
@@ -330,24 +273,11 @@ def make_session_handler(
|
|
|
330
273
|
closing: threading.Event | None = None,
|
|
331
274
|
*,
|
|
332
275
|
ui: UiSurface | None = None,
|
|
333
|
-
api_key: str | None = PIN,
|
|
334
276
|
ui_origin: bool = False,
|
|
335
277
|
) -> type[BaseHTTPRequestHandler]:
|
|
336
|
-
"""
|
|
337
|
-
|
|
338
|
-
author's machine); ``/__ui/…`` the world's static ui when connector.toml
|
|
339
|
-
declares one, and its ``api_path`` prefix the vendor routes with the pin
|
|
340
|
-
presented for the page (the host does the same with the session cookie);
|
|
341
|
-
any other path is the vendor route when the world has routes, else a 404
|
|
342
|
-
that says where the tools are. ``POST close`` answers ``{closed: true}``
|
|
343
|
-
and sets ``closing``: the opener tears the session down (a handler cannot
|
|
344
|
-
stop the server it runs in). With ``ui_origin`` the handler is the ui's own
|
|
345
|
-
origin instead: the page at ``/`` (every path that is not a file of it
|
|
346
|
-
falls back to ``index.html``, for a client-side router) and its
|
|
347
|
-
``api_path`` prefix answered with the pin — nothing else, as on the host."""
|
|
278
|
+
"""``/__session/`` takes no secret: it is loopback on the author's machine. ``POST close`` only sets ``closing``,
|
|
279
|
+
as a handler cannot stop the server it runs in; the opener tears the session down."""
|
|
348
280
|
closing = closing if closing is not None else threading.Event()
|
|
349
|
-
# Page calls go in as a granted client, as on the host, or an oauth2 world refuses them.
|
|
350
|
-
grant = client_grant(app, api_key)
|
|
351
281
|
|
|
352
282
|
def close() -> dict:
|
|
353
283
|
closing.set()
|
|
@@ -358,8 +288,12 @@ def make_session_handler(
|
|
|
358
288
|
fail("host", "a schema world has no [redact] policy; seed it with redact=off")
|
|
359
289
|
return world.seed({"rows": rows, "mode": mode})
|
|
360
290
|
|
|
361
|
-
def grade(
|
|
362
|
-
|
|
291
|
+
def grade(
|
|
292
|
+
report: str | None = None, context: dict | None = None, journal: dict | None = None, grader: dict | None = None
|
|
293
|
+
) -> dict:
|
|
294
|
+
# Only the host runs the session-task graders these feed; a local session records no journal.
|
|
295
|
+
if grader is not None:
|
|
296
|
+
fail("host", "a candidate grader is graded on a World Host session (worlds task try)")
|
|
363
297
|
return world.grade()
|
|
364
298
|
|
|
365
299
|
operations: dict[str, Callable[..., dict]] = {
|
|
@@ -374,13 +308,10 @@ def make_session_handler(
|
|
|
374
308
|
"POST close": close,
|
|
375
309
|
}
|
|
376
310
|
|
|
377
|
-
class Handler(
|
|
311
|
+
class Handler(WorldRequestHandler):
|
|
378
312
|
server_version = "gateway-world-local"
|
|
379
313
|
|
|
380
|
-
def
|
|
381
|
-
pass
|
|
382
|
-
|
|
383
|
-
def _serve(self, method: str) -> None:
|
|
314
|
+
def _dispatch(self, method: str) -> None:
|
|
384
315
|
length = int(self.headers.get("Content-Length") or 0)
|
|
385
316
|
raw = self.rfile.read(length) if length else b""
|
|
386
317
|
path = self.path.split("?", 1)[0]
|
|
@@ -389,6 +320,9 @@ def make_session_handler(
|
|
|
389
320
|
if app is not None and api_target(ui, path) is not None:
|
|
390
321
|
return self._ui_api(method, path, raw, Via.UI)
|
|
391
322
|
return self._ui(method, path)
|
|
323
|
+
origin = self.headers.get("Origin")
|
|
324
|
+
if origin and not _local_origin(origin):
|
|
325
|
+
return self._reply(403, {"error": "this session answers this machine's pages, not another site's"})
|
|
392
326
|
if path.startswith(SESSION_PREFIX):
|
|
393
327
|
return self._session(method, path[len(SESSION_PREFIX) :].strip("/"), raw)
|
|
394
328
|
if ui is not None and (path == UI_PREFIX.rstrip("/") or path.startswith(UI_PREFIX)):
|
|
@@ -419,13 +353,10 @@ def make_session_handler(
|
|
|
419
353
|
self.send_header(name, value)
|
|
420
354
|
self.send_header("Content-Length", str(len(payload)))
|
|
421
355
|
self.end_headers()
|
|
422
|
-
self
|
|
356
|
+
write_body(self, payload)
|
|
423
357
|
|
|
424
358
|
def _ui_api(self, method: str, path: str, raw: bytes, via: Via) -> None:
|
|
425
|
-
"""
|
|
426
|
-
and answer the route with the world's own credential for the pin,
|
|
427
|
-
the way the host answers it for the session cookie. Only the ui
|
|
428
|
-
port's prefix is ``via: ui``; the session port is the api origin."""
|
|
359
|
+
"""Answers with the world's own credential for the pin, as the host does for the session cookie."""
|
|
429
360
|
assert app is not None and ui is not None
|
|
430
361
|
route = api_target(ui, path)
|
|
431
362
|
assert route is not None
|
|
@@ -436,7 +367,7 @@ def make_session_handler(
|
|
|
436
367
|
)
|
|
437
368
|
query = self.path.split("?", 1)[1] if "?" in self.path else ""
|
|
438
369
|
headers = {k.lower(): v for k, v in self.headers.items() if k.lower() not in ("cookie", "authorization")}
|
|
439
|
-
credential_headers, credential_query =
|
|
370
|
+
credential_headers, credential_query = app.door.present()
|
|
440
371
|
target = with_query(route + (f"?{query}" if query else ""), credential_query)
|
|
441
372
|
status, body, extra = app.handle(
|
|
442
373
|
method,
|
|
@@ -469,28 +400,12 @@ def make_session_handler(
|
|
|
469
400
|
self.send_header("Content-Type", "application/json")
|
|
470
401
|
self.send_header("Content-Length", str(len(data)))
|
|
471
402
|
self.end_headers()
|
|
472
|
-
self
|
|
473
|
-
|
|
474
|
-
def do_GET(self):
|
|
475
|
-
self._serve("GET")
|
|
476
|
-
|
|
477
|
-
def do_POST(self):
|
|
478
|
-
self._serve("POST")
|
|
479
|
-
|
|
480
|
-
def do_PUT(self):
|
|
481
|
-
self._serve("PUT")
|
|
482
|
-
|
|
483
|
-
def do_PATCH(self):
|
|
484
|
-
self._serve("PATCH")
|
|
485
|
-
|
|
486
|
-
def do_DELETE(self):
|
|
487
|
-
self._serve("DELETE")
|
|
403
|
+
write_body(self, data)
|
|
488
404
|
|
|
489
405
|
return Handler
|
|
490
406
|
|
|
491
407
|
|
|
492
408
|
def _local_origin(origin: str) -> bool:
|
|
493
|
-
"""Whether a browser ``Origin`` names this machine's loopback."""
|
|
494
409
|
host = urllib.parse.urlsplit(origin).hostname
|
|
495
410
|
return host in ("127.0.0.1", "localhost", "::1")
|
|
496
411
|
|
|
@@ -1222,17 +1222,22 @@ def _world_for(request: dict, staging: Path) -> Path:
|
|
|
1222
1222
|
is copied."""
|
|
1223
1223
|
if request.get("workdir") is not None:
|
|
1224
1224
|
return _prepared_tree(request)
|
|
1225
|
-
|
|
1226
|
-
if world is None:
|
|
1225
|
+
if request.get("world") is None:
|
|
1227
1226
|
root = staging / "world"
|
|
1228
1227
|
root.mkdir()
|
|
1229
1228
|
_write_files(root, request.get("files"))
|
|
1230
1229
|
return world_root(root)
|
|
1230
|
+
return world_root(_local_tree(request))
|
|
1231
|
+
|
|
1232
|
+
|
|
1233
|
+
def _local_tree(request: dict) -> Path:
|
|
1234
|
+
"""``world``, opened in place: an absolute directory on this machine, only where this runtime may run authored code."""
|
|
1235
|
+
world = request.get("world")
|
|
1231
1236
|
if not may_execute():
|
|
1232
1237
|
fail("input", "world is a local-runtime field; this runtime takes files")
|
|
1233
1238
|
if not isinstance(world, str) or not Path(world).is_absolute() or not Path(world).is_dir():
|
|
1234
1239
|
fail("input", "world must be an absolute path to a directory on this machine")
|
|
1235
|
-
return
|
|
1240
|
+
return Path(world).resolve()
|
|
1236
1241
|
|
|
1237
1242
|
|
|
1238
1243
|
def _call(request: dict) -> dict:
|
|
@@ -1402,10 +1407,7 @@ def _answering_commands() -> dict:
|
|
|
1402
1407
|
|
|
1403
1408
|
def execute(request: dict) -> dict:
|
|
1404
1409
|
if not isinstance(request, dict) or request.get("command") not in COMMANDS:
|
|
1405
|
-
fail(
|
|
1406
|
-
"command",
|
|
1407
|
-
"Expected one of " + ", ".join(COMMANDS[:-1]) + " or " + COMMANDS[-1],
|
|
1408
|
-
)
|
|
1410
|
+
fail("command", "Expected one of " + ", ".join(COMMANDS[:-1]) + " or " + COMMANDS[-1])
|
|
1409
1411
|
handler = _answering_commands().get(request["command"])
|
|
1410
1412
|
if handler is not None:
|
|
1411
1413
|
return handler(request)
|
|
@@ -1418,15 +1420,11 @@ def execute(request: dict) -> dict:
|
|
|
1418
1420
|
root = world_root(root)
|
|
1419
1421
|
if bundle_mode(root) is None:
|
|
1420
1422
|
return {"status": "ok", "mode": "legacy"}
|
|
1421
|
-
|
|
1422
|
-
|
|
1423
|
-
|
|
1424
|
-
|
|
1425
|
-
|
|
1426
|
-
"compile",
|
|
1427
|
-
"apply-batch",
|
|
1428
|
-
"refresh-slack",
|
|
1429
|
-
):
|
|
1423
|
+
in_place = request["command"] in ("validate", "compile") and request.get("world") is not None
|
|
1424
|
+
if in_place:
|
|
1425
|
+
# In place, so the ``[dependencies]`` paths beside it resolve and its snapshots are compiled where they are.
|
|
1426
|
+
root = _local_tree(request)
|
|
1427
|
+
elif request["command"] in ("validate", "compile", "apply-batch", "refresh-slack"):
|
|
1430
1428
|
_write_files(root, request.get("files"))
|
|
1431
1429
|
# A schema world's api bundle keeps the world under server/world; the whole tree still travels back.
|
|
1432
1430
|
world = world_root(root)
|
|
@@ -1486,7 +1484,7 @@ def execute(request: dict) -> dict:
|
|
|
1486
1484
|
**validate_bundle(world_root(root), execute=_flag(request, "execute", False)),
|
|
1487
1485
|
**extra,
|
|
1488
1486
|
}
|
|
1489
|
-
if request["command"] not in ("validate", "validate-archive"):
|
|
1487
|
+
if request["command"] not in ("validate", "validate-archive") and not in_place:
|
|
1490
1488
|
paths = [path for path in sorted(root.rglob("*")) if path.is_file()]
|
|
1491
1489
|
if len(paths) > MAX_FILES:
|
|
1492
1490
|
fail("size", f"The world tree has {len(paths)} files, over the {MAX_FILES} limit")
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
"""A route request's body as a world reads it: one :class:`RequestBody` kind per
|
|
2
|
+
media type, decided in :meth:`RequestBody.of` alone.
|
|
3
|
+
|
|
4
|
+
``fields`` is what a route reads, a handler's ``body`` and a declared route's
|
|
5
|
+
input: a JSON value; a form's fields, each name's first value; a multipart
|
|
6
|
+
form's fields, each name's first part, a file part read as ``{"filename",
|
|
7
|
+
"content_type", "size"}`` with its bytes in ``files``; a multipart/related
|
|
8
|
+
body's first part as JSON, the parts after it in ``files`` keyed ``"1"``,
|
|
9
|
+
``"2"``... A body of any other type is an upload (``application/octet-stream``,
|
|
10
|
+
``text/csv``, ``image/png``): its fields are its JSON when it is JSON, since
|
|
11
|
+
clients label JSON many ways, and else None, which a declared route refuses as
|
|
12
|
+
the vendor's 400 and a handler route reads as ``{}`` beside the bytes
|
|
13
|
+
(``ctx.raw``). JSON that does not parse under a JSON label, and a multipart
|
|
14
|
+
body that does not split, are None to every route. Every part is found in time
|
|
15
|
+
linear in the body; a body of more than :data:`MAX_PARTS` parts, or a part
|
|
16
|
+
whose headers pass :data:`MAX_PART_HEAD` bytes, does not split.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import json
|
|
22
|
+
import re
|
|
23
|
+
import urllib.parse
|
|
24
|
+
from abc import ABC, abstractmethod
|
|
25
|
+
from dataclasses import dataclass
|
|
26
|
+
from functools import cached_property
|
|
27
|
+
from typing import Any, ClassVar, Mapping
|
|
28
|
+
|
|
29
|
+
MAX_PARTS = 1000
|
|
30
|
+
MAX_PART_HEAD = 8 * 1024
|
|
31
|
+
_BOUNDARY = re.compile(r"""(?:^|;)\s*boundary=(?:"([^"\r\n]{1,70})"|([^\s;"]{1,70}))""", re.IGNORECASE)
|
|
32
|
+
_PARAM = re.compile(r""";\s*([A-Za-z0-9!#$%&'*+.^_`|~-]+)\s*=\s*("(?:[^"\\]|\\.)*"|[^;]*)""")
|
|
33
|
+
_CRLF = b"\r\n"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def json_value(raw: bytes) -> Any:
|
|
37
|
+
"""``raw`` as JSON: ``{}`` when empty, None when it is not JSON."""
|
|
38
|
+
if not raw:
|
|
39
|
+
return {}
|
|
40
|
+
try:
|
|
41
|
+
return json.loads(raw.decode("utf-8"))
|
|
42
|
+
except (ValueError, RecursionError):
|
|
43
|
+
return None
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def form_fields(raw: bytes) -> dict[str, str]:
|
|
47
|
+
"""``raw`` as an ``application/x-www-form-urlencoded`` form, each name's first value."""
|
|
48
|
+
pairs = urllib.parse.parse_qs(raw.decode("utf-8", "replace"), keep_blank_values=True)
|
|
49
|
+
return {name: values[0] for name, values in pairs.items()}
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@dataclass(frozen=True)
|
|
53
|
+
class Upload:
|
|
54
|
+
"""One file a request carried: its name and type as the client gave them, and its bytes."""
|
|
55
|
+
|
|
56
|
+
filename: str | None
|
|
57
|
+
content_type: str | None
|
|
58
|
+
content: bytes
|
|
59
|
+
|
|
60
|
+
def described(self) -> dict:
|
|
61
|
+
return {"filename": self.filename, "content_type": self.content_type, "size": len(self.content)}
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
@dataclass(frozen=True)
|
|
65
|
+
class Part:
|
|
66
|
+
"""One part of a multipart body: its headers, names lower-cased, and its bytes."""
|
|
67
|
+
|
|
68
|
+
headers: dict[str, str]
|
|
69
|
+
content: bytes
|
|
70
|
+
|
|
71
|
+
@cached_property
|
|
72
|
+
def disposition(self) -> dict[str, str]:
|
|
73
|
+
params = _PARAM.findall(";" + self.headers.get("content-disposition", "").partition(";")[2])
|
|
74
|
+
return {name.lower(): _unquoted(value.strip()) for name, value in params}
|
|
75
|
+
|
|
76
|
+
@property
|
|
77
|
+
def name(self) -> str | None:
|
|
78
|
+
return self.disposition.get("name")
|
|
79
|
+
|
|
80
|
+
@property
|
|
81
|
+
def is_file(self) -> bool:
|
|
82
|
+
return "filename" in self.disposition
|
|
83
|
+
|
|
84
|
+
def upload(self) -> Upload:
|
|
85
|
+
return Upload(self.disposition.get("filename"), self.headers.get("content-type"), self.content)
|
|
86
|
+
|
|
87
|
+
def field(self) -> Any:
|
|
88
|
+
return self.upload().described() if self.is_file else self.content.decode("utf-8", "replace")
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _unquoted(value: str) -> str:
|
|
92
|
+
quoted = len(value) > 1 and value[0] == value[-1] == '"'
|
|
93
|
+
return re.sub(r"\\(.)", r"\1", value[1:-1]) if quoted else value
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _part(chunk: bytes) -> Part | None:
|
|
97
|
+
"""One part from what follows its delimiter: transport padding, a line break, its
|
|
98
|
+
headers and a blank line, then its bytes."""
|
|
99
|
+
padded = chunk.lstrip(b" \t")
|
|
100
|
+
if not padded.startswith(_CRLF):
|
|
101
|
+
return None
|
|
102
|
+
body = padded[2:]
|
|
103
|
+
if body.startswith(_CRLF):
|
|
104
|
+
return Part({}, body[2:])
|
|
105
|
+
head, separator, content = body.partition(_CRLF + _CRLF)
|
|
106
|
+
if not separator or len(head) > MAX_PART_HEAD:
|
|
107
|
+
return None
|
|
108
|
+
named = [line.partition(":") for line in head.decode("utf-8", "replace").split("\r\n")]
|
|
109
|
+
return Part({name.strip().lower(): value.strip() for name, _, value in named}, content)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def multipart_parts(raw: bytes, content_type: str) -> list[Part] | None:
|
|
113
|
+
"""The parts of a multipart body labelled ``content_type``, or None when it does not split."""
|
|
114
|
+
found = _BOUNDARY.search(content_type)
|
|
115
|
+
if found is None:
|
|
116
|
+
return None
|
|
117
|
+
delimiter = _CRLF + b"--" + (found.group(1) or found.group(2)).encode("latin-1")
|
|
118
|
+
chunks = (_CRLF + raw).split(delimiter, MAX_PARTS + 2)
|
|
119
|
+
if not 2 < len(chunks) <= MAX_PARTS + 2 or not chunks[-1].startswith(b"--"):
|
|
120
|
+
return None
|
|
121
|
+
parts = [_part(chunk) for chunk in chunks[1:-1]]
|
|
122
|
+
return None if None in parts else parts
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _first_by_name(parts: list[Part]) -> dict[str, Part]:
|
|
126
|
+
named: dict[str, Part] = {}
|
|
127
|
+
for part in parts:
|
|
128
|
+
named.setdefault(part.name or "", part)
|
|
129
|
+
named.pop("", None)
|
|
130
|
+
return named
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
@dataclass(frozen=True)
|
|
134
|
+
class RequestBody(ABC):
|
|
135
|
+
"""A request's body (module docstring): the bytes as sent and the label they came under."""
|
|
136
|
+
|
|
137
|
+
raw: bytes
|
|
138
|
+
content_type: str = ""
|
|
139
|
+
media: ClassVar[tuple[str, ...]] = ()
|
|
140
|
+
uploads: ClassVar[bool] = False
|
|
141
|
+
|
|
142
|
+
@staticmethod
|
|
143
|
+
def of(raw: bytes, headers: Mapping[str, str]) -> RequestBody:
|
|
144
|
+
"""The kind ``headers``' content type names, a new one for every request: the one
|
|
145
|
+
place a body's kind is decided. An empty body is ``{}`` whatever its label."""
|
|
146
|
+
content_type = headers.get("content-type") or ""
|
|
147
|
+
media = content_type.partition(";")[0].strip().lower()
|
|
148
|
+
labelled = KINDS.get(media) or (UploadBody if media and not media.endswith("+json") else JsonBody)
|
|
149
|
+
return (labelled if raw else JsonBody)(raw, content_type)
|
|
150
|
+
|
|
151
|
+
@property
|
|
152
|
+
@abstractmethod
|
|
153
|
+
def fields(self) -> Any:
|
|
154
|
+
"""What a route reads (module docstring), or None when the body cannot be read so."""
|
|
155
|
+
|
|
156
|
+
@property
|
|
157
|
+
def files(self) -> dict[str, Upload]:
|
|
158
|
+
"""The files the body carried, by the field or position that names each."""
|
|
159
|
+
return {}
|
|
160
|
+
|
|
161
|
+
def fields_for(self, handler: bool) -> Any:
|
|
162
|
+
"""What one route reads: :attr:`fields`, or for a handler route ``{}`` beside an
|
|
163
|
+
upload's bytes; None when the route cannot read it."""
|
|
164
|
+
return {} if self.fields is None and self.uploads and handler else self.fields
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
@dataclass(frozen=True)
|
|
168
|
+
class JsonBody(RequestBody):
|
|
169
|
+
media = ("application/json",)
|
|
170
|
+
|
|
171
|
+
@cached_property
|
|
172
|
+
def fields(self) -> Any:
|
|
173
|
+
return json_value(self.raw)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
@dataclass(frozen=True)
|
|
177
|
+
class UploadBody(RequestBody):
|
|
178
|
+
uploads = True
|
|
179
|
+
|
|
180
|
+
@cached_property
|
|
181
|
+
def fields(self) -> Any:
|
|
182
|
+
return json_value(self.raw)
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
@dataclass(frozen=True)
|
|
186
|
+
class FormBody(RequestBody):
|
|
187
|
+
"""A form, or JSON under a form's label: no form field starts with ``{`` or ``[``,
|
|
188
|
+
and some clients label every POST a form."""
|
|
189
|
+
|
|
190
|
+
media = ("application/x-www-form-urlencoded",)
|
|
191
|
+
|
|
192
|
+
@cached_property
|
|
193
|
+
def fields(self) -> Any:
|
|
194
|
+
return json_value(self.raw) if self.raw.lstrip().startswith((b"{", b"[")) else form_fields(self.raw)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
@dataclass(frozen=True)
|
|
198
|
+
class MultipartFormBody(RequestBody):
|
|
199
|
+
media = ("multipart/form-data",)
|
|
200
|
+
|
|
201
|
+
@cached_property
|
|
202
|
+
def named(self) -> dict[str, Part] | None:
|
|
203
|
+
parts = multipart_parts(self.raw, self.content_type)
|
|
204
|
+
return None if parts is None else _first_by_name(parts)
|
|
205
|
+
|
|
206
|
+
@cached_property
|
|
207
|
+
def fields(self) -> Any:
|
|
208
|
+
return None if self.named is None else {name: part.field() for name, part in self.named.items()}
|
|
209
|
+
|
|
210
|
+
@property
|
|
211
|
+
def files(self) -> dict[str, Upload]:
|
|
212
|
+
return {name: part.upload() for name, part in (self.named or {}).items() if part.is_file}
|
|
213
|
+
|
|
214
|
+
def fields_for(self, handler: bool) -> Any:
|
|
215
|
+
"""A form with a file reaches a handler alone: a declared route reads no file."""
|
|
216
|
+
return None if self.files and not handler else self.fields
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
@dataclass(frozen=True)
|
|
220
|
+
class MultipartRelatedBody(RequestBody):
|
|
221
|
+
media = ("multipart/related",)
|
|
222
|
+
|
|
223
|
+
@cached_property
|
|
224
|
+
def parts(self) -> list[Part]:
|
|
225
|
+
return multipart_parts(self.raw, self.content_type) or []
|
|
226
|
+
|
|
227
|
+
@cached_property
|
|
228
|
+
def fields(self) -> Any:
|
|
229
|
+
return json_value(self.parts[0].content) if self.parts else None
|
|
230
|
+
|
|
231
|
+
@property
|
|
232
|
+
def files(self) -> dict[str, Upload]:
|
|
233
|
+
return {str(index): part.upload() for index, part in enumerate(self.parts[1:], start=1)}
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
KINDS: dict[str, type[RequestBody]] = {
|
|
237
|
+
media: kind for kind in (JsonBody, FormBody, MultipartFormBody, MultipartRelatedBody) for media in kind.media
|
|
238
|
+
}
|