@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.
Files changed (123) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2221 -962
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2212 -953
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +81 -19
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +79 -17
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/index.d.mts +2 -2
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.js +903 -221
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.mjs +868 -212
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/traces/index.js +78 -16
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +76 -14
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.js +7 -1
  29. package/dist/tracing/index.js.map +1 -1
  30. package/dist/tracing/index.mjs +7 -1
  31. package/dist/tracing/index.mjs.map +1 -1
  32. package/dist/worlds/index.d.mts +692 -410
  33. package/dist/worlds/index.d.ts +692 -410
  34. package/dist/worlds/index.js +740 -197
  35. package/dist/worlds/index.js.map +1 -1
  36. package/dist/worlds/index.mjs +736 -193
  37. package/dist/worlds/index.mjs.map +1 -1
  38. package/package.json +1 -1
  39. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  40. package/runtime/gatewaysdk/environment/_world.py +58 -65
  41. package/runtime/gatewaysdk/environment/backing.py +20 -24
  42. package/runtime/gatewaysdk/environment/core.py +1 -16
  43. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  44. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +174 -471
  46. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  47. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  48. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  50. package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
  51. package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
  52. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  53. package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
  54. package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
  55. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  56. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  58. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  59. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  60. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  62. package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
  63. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  64. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  65. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  66. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  67. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  68. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  69. package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
  70. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  71. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  72. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  73. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  74. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  75. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  76. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  77. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  78. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  79. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  82. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  83. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  84. package/runtime/gatewaysdk/environment/schema/local.py +31 -116
  85. package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
  86. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  87. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  88. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  89. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  90. package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
  91. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  92. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  93. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  94. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  95. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
  96. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
  98. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  102. package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
  103. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  104. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  105. package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
  106. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  107. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  108. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  109. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  110. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  111. package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
  112. package/runtime/gatewaysdk/environment/world.py +1 -1
  113. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  114. package/skills/agents/connector-template-author.md +5 -1
  115. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  116. package/skills/connector-schema-authoring/SKILL.md +31 -6
  117. package/skills/connector-schema-authoring/connector-worlds.md +129 -7
  118. package/skills/world-data-ingestion/ROWS.md +12 -8
  119. package/skills/world-data-ingestion/SKILL.md +13 -13
  120. package/skills/worlds-getting-started/SKILL.md +23 -23
  121. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  122. package/skills/worlds-getting-started/references/gotchas.md +35 -2
  123. 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, vendor_credential, with_query
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 client_grant, task_card
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
- """Whether the world serves HTTP at all: only a tree with ``connector.toml``
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 to this session's ``/__world/*`` routes, minted when it opened.
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
- """Open one session of the world at ``root``.
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) if spec is not None else CallLog()
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, api_key=api_key, ui_origin=True),
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
- """``pid <n> (<command>)`` of whatever listens on ``port``, from ``lsof`` when this
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
- """The session's server on ``host:port``, or a refusal that NAMES the port and,
306
- when it can, who holds it: a bare ``Address already in use`` from a backgrounded
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
- """The local server's handler: ``/__session/<verb>`` is the session (the
337
- host's control verbs, one session, no secret — this is loopback on the
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(report: str | None = None, context: dict | None = None) -> dict:
362
- # Only the host runs a session task's graders, which read the report and the other worlds' evidence.
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(BaseHTTPRequestHandler):
311
+ class Handler(WorldRequestHandler):
378
312
  server_version = "gateway-world-local"
379
313
 
380
- def log_message(self, *_):
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.wfile.write(payload)
356
+ write_body(self, payload)
423
357
 
424
358
  def _ui_api(self, method: str, path: str, raw: bytes, via: Via) -> None:
425
- """The page's same-origin api call: strip the ``api_path`` prefix
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 = vendor_credential(app.router.spec, api_key or "", grant=grant)
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.wfile.write(data)
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
- world = request.get("world")
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 world_root(Path(world).resolve())
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
- if request["command"] == "validate" and request.get("world") is not None:
1422
- # Checked in place, so the ``[dependencies]`` paths beside it resolve.
1423
- root = _world_for(request, Path(directory))
1424
- elif request["command"] in (
1425
- "validate",
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
+ }