@withgateway/sdk 0.2.9 → 0.3.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 (49) hide show
  1. package/dist/cli.js +2355 -486
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +2335 -466
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.d.mts +1 -0
  6. package/dist/files/index.d.ts +1 -0
  7. package/dist/files/index.js +1324 -21
  8. package/dist/files/index.js.map +1 -1
  9. package/dist/files/index.mjs +1322 -13
  10. package/dist/files/index.mjs.map +1 -1
  11. package/dist/{index-Cz8Q6Keo.d.mts → index-D6oi1TWE.d.mts} +93 -34
  12. package/dist/{index-BO2SNSgy.d.ts → index-DAb-FCMg.d.ts} +93 -34
  13. package/dist/index.d.mts +4 -3
  14. package/dist/index.d.ts +4 -3
  15. package/dist/index.js +1758 -116
  16. package/dist/index.js.map +1 -1
  17. package/dist/index.mjs +1720 -97
  18. package/dist/index.mjs.map +1 -1
  19. package/dist/media-CbcAfQvd.d.mts +83 -0
  20. package/dist/media-CbcAfQvd.d.ts +83 -0
  21. package/dist/traces/index.d.mts +1 -0
  22. package/dist/traces/index.d.ts +1 -0
  23. package/dist/traces/index.js +1321 -18
  24. package/dist/traces/index.js.map +1 -1
  25. package/dist/traces/index.mjs +1319 -10
  26. package/dist/traces/index.mjs.map +1 -1
  27. package/dist/tracing/index.d.mts +2 -1
  28. package/dist/tracing/index.d.ts +2 -1
  29. package/dist/tracing/index.js +512 -11
  30. package/dist/tracing/index.js.map +1 -1
  31. package/dist/tracing/index.mjs +501 -10
  32. package/dist/tracing/index.mjs.map +1 -1
  33. package/dist/worlds/index.d.mts +583 -63
  34. package/dist/worlds/index.d.ts +583 -63
  35. package/dist/worlds/index.js +1703 -94
  36. package/dist/worlds/index.js.map +1 -1
  37. package/dist/worlds/index.mjs +1689 -80
  38. package/dist/worlds/index.mjs.map +1 -1
  39. package/package.json +1 -1
  40. package/runtime/gatewaysdk/environment/schema/api.py +38 -56
  41. package/runtime/gatewaysdk/environment/schema/grading.py +1 -5
  42. package/runtime/gatewaysdk/environment/schema/host.py +53 -90
  43. package/runtime/gatewaysdk/environment/schema/local.py +15 -7
  44. package/runtime/gatewaysdk/environment/schema/runtime.py +9 -9
  45. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +7 -7
  46. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
  47. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -1
  48. package/skills/worlds-getting-started/SKILL.md +7 -7
  49. package/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.2.9",
3
+ "version": "0.3.0",
4
4
  "description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -99,6 +99,7 @@ import urllib.parse
99
99
  import uuid
100
100
  from dataclasses import dataclass, field
101
101
  from datetime import datetime, timezone
102
+ from enum import StrEnum
102
103
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
103
104
  from pathlib import Path
104
105
  from typing import Any, Callable
@@ -145,9 +146,6 @@ CLOCK_ENV = "GATEWAY_WORLD_CLOCK"
145
146
  INHERITED: Any = object()
146
147
 
147
148
 
148
- # ---------------------------------------------------------------- settings
149
-
150
-
151
149
  @dataclass(frozen=True)
152
150
  class Paging:
153
151
  style: str = "none"
@@ -509,9 +507,6 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
509
507
  )
510
508
 
511
509
 
512
- # ---------------------------------------------------------------- state
513
-
514
-
515
510
  class WorldState:
516
511
  """The store behind the served API.
517
512
 
@@ -557,8 +552,6 @@ class WorldState:
557
552
  self._clear_events()
558
553
  self._open(self._snapshot_path if initial and self.snapshot else None, initial=initial)
559
554
 
560
- # -- the live feed: what changed, for a page that polls
561
-
562
555
  def _clear_events(self) -> None:
563
556
  self._events: list[dict] = []
564
557
  self.event_seq = 0
@@ -743,9 +736,6 @@ class WorldState:
743
736
  self._dir.cleanup()
744
737
 
745
738
 
746
- # ---------------------------------------------------------------- routing
747
-
748
-
749
739
  def _dig(row: Any, path: str) -> Any:
750
740
  for part in path.split("."):
751
741
  if not isinstance(row, dict) or part not in row:
@@ -938,9 +928,6 @@ class Router:
938
928
  return key is None or presented == key
939
929
 
940
930
 
941
- # ---------------------------------------------------------------- handlers
942
-
943
-
944
931
  class ApiContext:
945
932
  """What a world's handler gets: the store, the clock, and the vendor's shapes."""
946
933
 
@@ -960,7 +947,6 @@ class ApiContext:
960
947
  #: The ``query`` a handler is passed keeps only the first, as most routes want.
961
948
  self.query_all: dict[str, list[str]] = {}
962
949
 
963
- # -- the store
964
950
  def rows(self, entity: str) -> list[dict]:
965
951
  return self.state.rows(entity)
966
952
 
@@ -986,7 +972,6 @@ class ApiContext:
986
972
  def fields_of(self, entity: str) -> set[str]:
987
973
  return self.state.fields_of(entity)
988
974
 
989
- # -- the live feed
990
975
  def emit(self, event: dict) -> dict:
991
976
  """Record what this write changed for a page that polls (:meth:`WorldState.emit`)."""
992
977
  return self.state.emit(event)
@@ -1001,7 +986,6 @@ class ApiContext:
1001
986
  return (plaintext,)
1002
987
  return stored_forms(self.spec, field, plaintext)
1003
988
 
1004
- # -- time and identity
1005
989
  @staticmethod
1006
990
  def clock() -> float:
1007
991
  frozen = os.environ.get(CLOCK_ENV)
@@ -1037,7 +1021,6 @@ class ApiContext:
1037
1021
  def uuid() -> str:
1038
1022
  return str(uuid.uuid4())
1039
1023
 
1040
- # -- the vendor's shapes
1041
1024
  def envelope(self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None) -> Any:
1042
1025
  page = paginate(rows, query or {}, self.settings.paging)
1043
1026
  return wrap(page, self.settings, envelope, link=self.link, omit_done_cursor=self._omits_done_cursor())
@@ -1105,9 +1088,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1105
1088
  return handlers
1106
1089
 
1107
1090
 
1108
- # ---------------------------------------------------------------- pages and envelopes
1109
-
1110
-
1111
1091
  @dataclass(frozen=True)
1112
1092
  class Page:
1113
1093
  rows: list[dict]
@@ -1245,9 +1225,6 @@ def _normalize(result: Any, default_status: int | None) -> Any:
1245
1225
  return default_status, result, None
1246
1226
 
1247
1227
 
1248
- # ---------------------------------------------------------------- writes
1249
-
1250
-
1251
1228
  def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
1252
1229
  """Assign a dotted target (``attributes.note``), keeping the rest of a nested
1253
1230
  object an update leaves alone."""
@@ -1293,9 +1270,6 @@ def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | Non
1293
1270
  return row
1294
1271
 
1295
1272
 
1296
- # ---------------------------------------------------------------- presenting a credential
1297
-
1298
-
1299
1273
  def vendor_credential(spec: Spec, presented: str, *, grant: str | None = None) -> tuple[dict[str, str], dict[str, str]]:
1300
1274
  """(headers, query) carrying the world's own credential: ``presented`` in
1301
1275
  the shape the vendor's scheme declares — a ``query`` world reads its key
@@ -1365,9 +1339,6 @@ def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str
1365
1339
  return operation.method, f"{base}{path}", raw
1366
1340
 
1367
1341
 
1368
- # ---------------------------------------------------------------- the server
1369
-
1370
-
1371
1342
  Response = tuple[int, Any, dict[str, str] | None]
1372
1343
 
1373
1344
 
@@ -1387,14 +1358,28 @@ def _strings_in(node: Any, out: list[str] | None = None) -> list[str]:
1387
1358
  return out
1388
1359
 
1389
1360
 
1361
+ class Via(StrEnum):
1362
+ """The door a vendor-route request came in by, set by the server from where
1363
+ it arrived and never from a request header. It names the door, not the
1364
+ actor: a token holder calling the ui origin's prefix without a browser is
1365
+ ``ui``."""
1366
+
1367
+ API = "api"
1368
+ UI = "ui"
1369
+ TOOL = "tool"
1370
+
1371
+
1390
1372
  class CallLog:
1391
1373
  """The vendor-route requests one session answered, in order: what the agent
1392
- asked (operation, method, path, path args, query, body) and what came back
1393
- (status, ``rows`` = the length of the operation's ``results`` list when the
1394
- answer carries one, elapsed). Bounded; ``total`` counts past the bound.
1395
- ``/__world/calls`` serves it and a task's ``verify.py`` is handed it as
1396
- ``calls`` beside the rows, because a read-only investigation leaves no row
1397
- behind and its calls are the only evidence of what it did."""
1374
+ asked (operation, method, path, path args, query, body), the door it came
1375
+ in by (``via``) and what came back (status, ``rows`` = the length of the
1376
+ operation's ``results`` list when the answer carries one, elapsed).
1377
+ ``selectors`` is every string the request carried wherever it sat, and
1378
+ ``found`` is "answered with rows", so a grader's scalar ``where`` can ask
1379
+ either without the vendor's request shape. Bounded; ``total`` counts past
1380
+ the bound. ``/__world/calls`` serves it and a task's ``verify.py`` is
1381
+ handed it as ``calls`` beside the rows, because a read-only investigation
1382
+ leaves no row behind and its calls are the only evidence of what it did."""
1398
1383
 
1399
1384
  def __init__(self, maximum: int | None = None):
1400
1385
  if maximum is None:
@@ -1416,6 +1401,7 @@ class CallLog:
1416
1401
  status: int,
1417
1402
  answer: Any,
1418
1403
  elapsed_s: float,
1404
+ via: Via | None,
1419
1405
  ) -> None:
1420
1406
  if self.maximum == 0:
1421
1407
  return
@@ -1434,15 +1420,10 @@ class CallLog:
1434
1420
  "args": dict(args),
1435
1421
  "query": query,
1436
1422
  "body": body if isinstance(body, (dict, list)) and body else None,
1437
- # Every string the request carried, wherever it sat (a path segment, a
1438
- # query value, a body list of lists), so a grader can ask "was X searched"
1439
- # with one `contains` and no knowledge of the vendor's request shape.
1440
1423
  "selectors": _strings_in([args, query, body]),
1424
+ **({} if via is None else {"via": str(via)}),
1441
1425
  "status": status,
1442
1426
  "rows": rows,
1443
- # `found`: the request was answered and returned rows. A grader's `where`
1444
- # takes scalars, and "asked and got something back" is the question an
1445
- # investigation's grader asks most.
1446
1427
  "found": status < 400 and rows is not None and rows > 0,
1447
1428
  "elapsed_ms": round(elapsed_s * 1000, 1),
1448
1429
  }
@@ -1491,8 +1472,6 @@ class WorldApp:
1491
1472
  self.allowed = allowed
1492
1473
  self.calls = CallLog(call_log_max)
1493
1474
 
1494
- # ------------------------------------------------------------ helpers
1495
-
1496
1475
  @staticmethod
1497
1476
  def _json(raw: bytes) -> Any:
1498
1477
  if not raw:
@@ -1540,11 +1519,12 @@ class WorldApp:
1540
1519
  return path[len(self.prefix) :] or "/"
1541
1520
  return path
1542
1521
 
1543
- # ------------------------------------------------------------ the request
1544
-
1545
- def handle(self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str) -> Response:
1522
+ def handle(
1523
+ self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str, *, via: Via | None
1524
+ ) -> Response:
1546
1525
  """Answer one request. ``headers`` are lower-cased; ``default_host`` is what
1547
- a link uses when the request carries no Host header."""
1526
+ a link uses when the request carries no Host header; ``via`` is the door
1527
+ the caller took it in by, recorded on the call when there is one."""
1548
1528
  url = urllib.parse.urlsplit(target)
1549
1529
  settings, router, state = self.settings, self.router, self.state
1550
1530
  if method == "GET":
@@ -1578,10 +1558,12 @@ class WorldApp:
1578
1558
  return 200, issued, None
1579
1559
  if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
1580
1560
  return 405, {"error": "method_not_allowed"}, None
1581
- return self._route(method, url, headers, raw, default_host)
1561
+ return self._route(method, url, headers, raw, default_host, via)
1582
1562
 
1583
- def _route(self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str) -> Response:
1584
- settings, router, state, handlers = self.settings, self.router, self.state, self.handlers
1563
+ def _route(
1564
+ self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
1565
+ ) -> Response:
1566
+ settings, router = self.settings, self.router
1585
1567
  path = self._strip(url.path)
1586
1568
  # Every value of a repeated key is kept; ``query`` hands routes the first, the way
1587
1569
  # they always read it, and ``ctx.query_all`` hands handlers and filters the rest.
@@ -1601,7 +1583,8 @@ class WorldApp:
1601
1583
  return settings.invalid_status, settings.invalid, None
1602
1584
  started = time.monotonic()
1603
1585
  status, answer, extra = self._answer_route(op, operation, args, query, query_all, body, headers, url, default_host)
1604
- self.calls.record(operation, method, path, args, query_all, body, status, answer, time.monotonic() - started)
1586
+ elapsed = time.monotonic() - started
1587
+ self.calls.record(operation, method, path, args, query_all, body, status, answer, elapsed, via)
1605
1588
  return status, answer, extra
1606
1589
 
1607
1590
  def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
@@ -1734,7 +1717,9 @@ def make_handler(state: WorldState, router: Router, key: str | None):
1734
1717
  length = int(self.headers.get("Content-Length") or 0)
1735
1718
  raw = self.rfile.read(length) if length else b""
1736
1719
  headers = {k.lower(): v for k, v in self.headers.items()}
1737
- status, body, extra = app.handle(method, self.path, headers, raw, f"127.0.0.1:{self.server.server_port}")
1720
+ default_host = f"127.0.0.1:{self.server.server_port}"
1721
+ # A runner forwards tool calls here too, so this server cannot name the door.
1722
+ status, body, extra = app.handle(method, self.path, headers, raw, default_host, via=None)
1738
1723
  send_response(self, status, body, extra, app.settings.error_content_type)
1739
1724
 
1740
1725
  def do_GET(self):
@@ -1815,9 +1800,6 @@ def serve_forever(
1815
1800
  server.world_state.close() # type: ignore[attr-defined]
1816
1801
 
1817
1802
 
1818
- # ---------------------------------------------------------------- bundle
1819
-
1820
-
1821
1803
  def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
1822
1804
  parameters = {"header": "header", "query": "query"}
1823
1805
  security_scheme: dict[str, Any] = {}
@@ -28,16 +28,12 @@ from pathlib import Path
28
28
  from typing import Any, Protocol
29
29
 
30
30
  from ..world_session_contract import NO_GRADER_REASON
31
- from .tasks import evaluate_assertions
31
+ from .tasks import GraderError, evaluate_assertions
32
32
 
33
33
  GRADER_KINDS = ("assertions", "python", "rubric")
34
34
  VERIFY_TIMEOUT_S = 30.0
35
35
 
36
36
 
37
- class GraderError(Exception):
38
- """A grader that could not deliver a grade, with the reason a reader acts on."""
39
-
40
-
41
37
  @dataclass(frozen=True)
42
38
  class Grade:
43
39
  """A task's grade: the scalar ``reward`` (None when ungraded) and every
@@ -36,7 +36,8 @@ environment, running the same :class:`WorldHost` with ``run_handlers`` on. The
36
36
  supervisor keeps the registry, the leases and the token gate; the worker keeps
37
37
  the world. The **ui** surface is the version's prebuilt static app, served from
38
38
  the cache by the supervisor with its ``api_path`` rewritten onto the session's
39
- api; the **browser** surface is a websocket tunnel to the pool Chromium the
39
+ api and logged ``via: ui`` (the api origin's calls ``via: api``, an operation
40
+ called by name ``via: tool``); the **browser** surface is a websocket tunnel to the pool Chromium the
40
41
  platform leased for the session (:mod:`host_surfaces`). Custom-server worlds
41
42
  stay on pods; this module refuses a version it cannot open rather than
42
43
  guessing.
@@ -76,6 +77,7 @@ from .api import (
76
77
  ApiSettings,
77
78
  Handler,
78
79
  Router,
80
+ Via,
79
81
  WorldApp,
80
82
  load_api_settings,
81
83
  load_handlers,
@@ -297,11 +299,6 @@ def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str
297
299
  fail("host", f"could not upload the export: {error.reason}")
298
300
 
299
301
 
300
- # --------------------------------------------------------------------------- #
301
- # Locating and reading a world tree.
302
- # --------------------------------------------------------------------------- #
303
-
304
-
305
302
  def world_tree(bundle: Path) -> Path:
306
303
  """The compiled schema world inside an extracted bundle (``WorldTree.world``:
307
304
  ``bench push`` packages a schema world as its api bundle with the tree
@@ -318,11 +315,6 @@ def world_tree(bundle: Path) -> Path:
318
315
  raise AssertionError # fail() never returns
319
316
 
320
317
 
321
- # --------------------------------------------------------------------------- #
322
- # Per-version cache: bundle + snapshot + parsed spec, fetched once per host.
323
- # --------------------------------------------------------------------------- #
324
-
325
-
326
318
  @dataclass
327
319
  class CachedVersion:
328
320
  """One cached version, of either shape the host serves: an api bundle (a
@@ -517,11 +509,6 @@ class VersionCache:
517
509
  shutil.rmtree(staging, ignore_errors=True)
518
510
 
519
511
 
520
- # --------------------------------------------------------------------------- #
521
- # Session state: the cached snapshot, cloned into this session's own file.
522
- # --------------------------------------------------------------------------- #
523
-
524
-
525
512
  @dataclass
526
513
  class Export:
527
514
  """A session's state copied to a file on this host, hashed, waiting for the
@@ -611,11 +598,6 @@ class Session:
611
598
  return max(0.0, time.time() - self.opened_at)
612
599
 
613
600
 
614
- # --------------------------------------------------------------------------- #
615
- # The host: the session registry and the control operations.
616
- # --------------------------------------------------------------------------- #
617
-
618
-
619
601
  class WorldHost:
620
602
  """The session registry and the control operations, in one of two roles:
621
603
 
@@ -682,8 +664,6 @@ class WorldHost:
682
664
  self._counters: Counter[str] = Counter()
683
665
  self._session_seconds = 0.0
684
666
 
685
- # -- lifecycle ---------------------------------------------------------- #
686
-
687
667
  def open(
688
668
  self,
689
669
  session_id: str,
@@ -833,9 +813,10 @@ class WorldHost:
833
813
  ) -> dict:
834
814
  """Place the session on the version's worker. The worker opens it from
835
815
  the bundle this process already cached (no snapshot to fetch: the file
836
- is on disk), and the supervisor records only where it went. The ui and
837
- browser surfaces are the supervisor's own (static files, a tunnel), so
838
- the worker hears nothing of them. An export to restore from is fetched
816
+ is on disk), and the supervisor records only where it went. The ui's
817
+ static files and the browser tunnel stay the supervisor's; the ui's
818
+ api-prefix calls are relayed as they came, so the worker logs them
819
+ ``via: ui``. An export to restore from is fetched
839
820
  and verified here too, then handed to the worker as a local file.
840
821
  A worker every one of whose peers holds sessions cannot be started
841
822
  past the pool's memory budget: that is ``at_capacity``, and the
@@ -1003,8 +984,6 @@ class WorldHost:
1003
984
  session.browser = relay
1004
985
  return {"sessionId": session_id, "browser": True}
1005
986
 
1006
- # -- durability: a session's state as a file the platform keeps ---------- #
1007
-
1008
987
  def export(self, session_id: str, known_sha256: str | None = None) -> dict:
1009
988
  """Copy the session's state to a file on this host and hash it. The copy
1010
989
  is consistent (sqlite's online backup under the store's lock) and waits
@@ -1159,8 +1138,6 @@ class WorldHost:
1159
1138
  def worker_count(self) -> int:
1160
1139
  return len(self.workers._workers) if self.workers is not None else 0
1161
1140
 
1162
- # -- fleet: warming, draining, what the platform and prometheus see ------- #
1163
-
1164
1141
  def warm(self, version_id: str, bundle_url: str, snapshot: dict[str, str] | None) -> dict:
1165
1142
  """Cache a version before any session asks for it, so the first open
1166
1143
  pays nothing. Idempotent: a version already here is reported, not
@@ -1316,8 +1293,6 @@ class WorldHost:
1316
1293
  with self._lock:
1317
1294
  return session_id in self._sessions
1318
1295
 
1319
- # -- control operations (the platform's rendezvous, run in-process) ----- #
1320
-
1321
1296
  def _control(self, session: Session, method: str, verb: str, body: dict | None) -> dict:
1322
1297
  return self._worker_control(session.worker, method, f"/__host/sessions/{session.session_id}/{verb}", body)
1323
1298
 
@@ -1392,11 +1367,6 @@ HOSTED_OPERATIONS: dict[str, Callable[..., dict]] = {
1392
1367
  assert set(HOSTED_OPERATIONS) == {verb.route for verb in SESSION_VERBS}, "the host serves every session verb"
1393
1368
 
1394
1369
 
1395
- # --------------------------------------------------------------------------- #
1396
- # The HTTP server: control plane by secret, data plane by Host header.
1397
- # --------------------------------------------------------------------------- #
1398
-
1399
-
1400
1370
  def public_host(host_header: str | None, worlds_domain: str) -> bool:
1401
1371
  """True when ``Host`` names something under the worlds domain: a session,
1402
1372
  or any other label the wildcard ALB forwarded. That is the public side.
@@ -1490,7 +1460,7 @@ def admits(session: Session, path: str, headers: dict[str, str]) -> str | None:
1490
1460
  return "session"
1491
1461
  if session.spec is not None and session.spec.scheme == "oauth2":
1492
1462
  if session.app is None:
1493
- return "world" # the world's tokens live in its worker, which runs this same gate # the world's tokens live in its worker, which runs this same gate
1463
+ return "world" # the world's tokens live in its worker, which runs this same gate
1494
1464
  token_path = session.app.settings.token_path
1495
1465
  if token_path and session.app._strip(path) == token_path:
1496
1466
  return "world"
@@ -1589,8 +1559,6 @@ def make_host_handler(
1589
1559
  def log_message(self, format: str, *args: object) -> None:
1590
1560
  pass
1591
1561
 
1592
- # -- plumbing ------------------------------------------------------- #
1593
-
1594
1562
  def _read(self) -> bytes:
1595
1563
  declared = self.headers.get("Content-Length")
1596
1564
  if declared is None:
@@ -1611,8 +1579,6 @@ def make_host_handler(
1611
1579
  def _headers(self) -> dict[str, str]:
1612
1580
  return {k.lower(): v for k, v in self.headers.items()}
1613
1581
 
1614
- # -- dispatch ------------------------------------------------------- #
1615
-
1616
1582
  def do_GET(self):
1617
1583
  self._dispatch("GET")
1618
1584
 
@@ -1651,8 +1617,6 @@ def make_host_handler(
1651
1617
  self.close_connection = True
1652
1618
  return self._reply(refused.status, {"error": refused.error}, {"Connection": "close"})
1653
1619
 
1654
- # -- control plane -------------------------------------------------- #
1655
-
1656
1620
  def _control(self, method: str, url) -> None:
1657
1621
  if not hmac.compare_digest(self.headers.get("X-Host-Secret") or "", secret):
1658
1622
  return self._reply(403, {"error": "forbidden"})
@@ -1730,8 +1694,6 @@ def make_host_handler(
1730
1694
  except WorkerGone as error:
1731
1695
  return self._reply(502, {"error": "worker exited", "detail": str(error)})
1732
1696
 
1733
- # -- data plane ----------------------------------------------------- #
1734
-
1735
1697
  def _data(self, method: str, url) -> None:
1736
1698
  headers = self._headers()
1737
1699
  named = session_from_host(headers.get("host"))
@@ -1769,25 +1731,30 @@ def make_host_handler(
1769
1731
  admitted = admits(session, url.path, headers)
1770
1732
  if admitted is None:
1771
1733
  return self._reply(401, {"error": "invalid session token"})
1772
- self._serve_api(session, method, self.path, headers, admitted)
1734
+ if session.worker is not None:
1735
+ return self._on_worker(session, method, headers)
1736
+ self._serve_api(session, method, self.path, headers, admitted, Via.API)
1737
+
1738
+ def _on_worker(self, session: Session, method: str, headers: dict[str, str]) -> None:
1739
+ """Relay the request as it came, Host and path unchanged, to the
1740
+ session's version worker: it runs the same gate and picks the same
1741
+ door (api or ui) on its own copy of the session."""
1742
+ assert session.worker is not None
1743
+ try:
1744
+ status, answer_headers, payload = session.worker.request(method, self.path, headers, self._read())
1745
+ except WorkerGone as error:
1746
+ host.lose_worker(session.worker)
1747
+ return self._reply(502, {"error": "worker exited", "detail": str(error)})
1748
+ return self._relay(status, answer_headers, payload, drop=FRAMING_HEADERS)
1773
1749
 
1774
1750
  def _serve_api(
1775
- self, session: Session, method: str, target: str, headers: dict[str, str], admitted: str
1751
+ self, session: Session, method: str, target: str, headers: dict[str, str], admitted: str, via: Via
1776
1752
  ) -> None:
1777
- """Answer ``target`` (a path plus query) from the session's world,
1778
- in this process or its worker, once the gate has admitted it."""
1779
- sid = session.session_id
1780
- raw = self._read()
1781
- if session.worker is not None:
1782
- # The gate passed here; the worker runs it again and presents the
1783
- # world its credential, so the request goes over as it came.
1784
- try:
1785
- status, answer_headers, payload = session.worker.request(method, target, headers, raw)
1786
- except WorkerGone as error:
1787
- host.lose_worker(session.worker)
1788
- return self._reply(502, {"error": "worker exited", "detail": str(error)})
1789
- return self._relay(status, answer_headers, payload, drop=FRAMING_HEADERS)
1753
+ """Answer ``target`` (a path plus query) from the session's world in
1754
+ this process, once the gate has admitted it; the call is logged as
1755
+ having come in by ``via``, the door this host took it in by."""
1790
1756
  assert session.app is not None
1757
+ raw = self._read()
1791
1758
  world_headers = headers
1792
1759
  if admitted == "session":
1793
1760
  # The host's token gate is the access control; present the world
@@ -1795,48 +1762,44 @@ def make_host_handler(
1795
1762
  credential_headers, credential_query = world_credential(session)
1796
1763
  world_headers = {**headers, **credential_headers}
1797
1764
  target = with_query(target, credential_query)
1798
- status, body, extra = session.app.handle(method, target, world_headers, raw, f"w-{sid}-api.{worlds_domain}")
1765
+ default_host = f"w-{session.session_id}-api.{worlds_domain}"
1766
+ status, body, extra = session.app.handle(method, target, world_headers, raw, default_host, via=via)
1799
1767
  self._reply(status, body, extra)
1800
1768
 
1801
- # -- the ui surface -------------------------------------------------- #
1802
-
1803
1769
  def _serve_ui(self, session: Session, method: str, url, headers: dict[str, str]) -> None:
1804
1770
  ui = session.ui
1805
1771
  if ui is None:
1806
1772
  return self._reply(404, {"error": "this world has no static ui"})
1807
1773
  token = session.token
1808
- if token is not None:
1809
- if matches(query_token(url.query), token):
1810
- # The way in: trade the one-time ``?token=`` for the cookie
1811
- # and land on the same page without it.
1812
- landing = without_query_token(url)
1813
- return self._reply(
1814
- 303,
1815
- {"location": landing},
1816
- {
1817
- "Location": landing,
1818
- "Set-Cookie": session_cookie(token, secure=secure_cookies, max_age_s=host.lease_s),
1819
- },
1820
- )
1821
- if not matches(cookie_token(headers), token) and not matches(bearer_of(headers), token):
1822
- return self._reply(401, {"error": "invalid session token"})
1774
+ if token is not None and matches(query_token(url.query), token):
1775
+ return self._trade_token_for_cookie(url, token)
1776
+ if token is not None and not (matches(cookie_token(headers), token) or matches(bearer_of(headers), token)):
1777
+ return self._reply(401, {"error": "invalid session token"})
1823
1778
  route = api_target(ui, url.path)
1824
- if route is not None: # as the api origin answers the token; a version worker routes by Host
1825
- if cross_site(headers, lambda origin: urllib.parse.urlsplit(origin).netloc == headers.get("host")):
1826
- return self._reply(403, {"error": "the ui's api prefix answers its own page, not another site"})
1827
- target = urllib.parse.urlunsplit(("", "", route, url.query, ""))
1828
- api_headers = {k: v for k, v in headers.items() if k not in ("cookie", "authorization")}
1829
- api_headers["host"] = f"w-{session.session_id}-api.{worlds_domain}"
1830
- if token is not None:
1831
- api_headers["authorization"] = f"Bearer {token}"
1832
- return self._serve_api(session, method, target, api_headers, "session")
1779
+ if route is None:
1780
+ return self._serve_static(ui, method, url)
1781
+ if cross_site(headers, lambda origin: urllib.parse.urlsplit(origin).netloc == headers.get("host")):
1782
+ return self._reply(403, {"error": "the ui's api prefix answers its own page, not another site"})
1783
+ if session.worker is not None:
1784
+ return self._on_worker(session, method, headers)
1785
+ target = urllib.parse.urlunsplit(("", "", route, url.query, ""))
1786
+ api_headers = {k: v for k, v in headers.items() if k not in ("cookie", "authorization")}
1787
+ api_headers["host"] = f"w-{session.session_id}-api.{worlds_domain}"
1788
+ if token is not None:
1789
+ api_headers["authorization"] = f"Bearer {token}"
1790
+ return self._serve_api(session, method, target, api_headers, "session", Via.UI)
1791
+
1792
+ def _trade_token_for_cookie(self, url, token: str) -> None:
1793
+ landing = without_query_token(url)
1794
+ cookie = session_cookie(token, secure=secure_cookies, max_age_s=host.lease_s)
1795
+ self._reply(303, {"location": landing}, {"Location": landing, "Set-Cookie": cookie})
1796
+
1797
+ def _serve_static(self, ui: UiSurface, method: str, url) -> None:
1833
1798
  if method != "GET":
1834
1799
  return self._reply(405, {"error": "the static ui answers GET only"})
1835
1800
  status, static_headers, payload = static_file(ui, url.path)
1836
1801
  self._relay(status, static_headers.items(), payload, drop=FRAMING_HEADERS)
1837
1802
 
1838
- # -- the browser surface --------------------------------------------- #
1839
-
1840
1803
  def _serve_browser(self, session: Session, url, headers: dict[str, str]) -> None:
1841
1804
  """``/cdp/<session token>`` and ``/live/<grant>`` on the session's
1842
1805
  cdp host: check the credential against the SESSION, then tunnel
@@ -37,7 +37,7 @@ from pathlib import Path
37
37
  from typing import Any, Callable
38
38
 
39
39
  from . import snapshot as snapshots
40
- from .api import Router, WorldApp, load_api_settings, send_response, vendor_credential, with_query
40
+ from .api import Router, Via, WorldApp, load_api_settings, send_response, vendor_credential, with_query
41
41
  from .compiler import bundle_mode, fail
42
42
  from .conform import PIN
43
43
  from .connector import SPEC, load_spec
@@ -395,14 +395,14 @@ def make_session_handler(
395
395
  if ui_origin:
396
396
  assert ui is not None
397
397
  if app is not None and api_target(ui, path) is not None:
398
- return self._ui_api(method, path, raw)
398
+ return self._ui_api(method, path, raw, Via.UI)
399
399
  return self._ui(method, path)
400
400
  if path.startswith(SESSION_PREFIX):
401
401
  return self._session(method, path[len(SESSION_PREFIX) :].strip("/"), raw)
402
402
  if ui is not None and (path == UI_PREFIX.rstrip("/") or path.startswith(UI_PREFIX)):
403
403
  return self._ui(method, path[len(UI_PREFIX) - 1 :] if path.startswith(UI_PREFIX) else "/")
404
404
  if app is not None and ui is not None and api_target(ui, path) is not None:
405
- return self._ui_api(method, path, raw)
405
+ return self._ui_api(method, path, raw, Via.API)
406
406
  if app is None:
407
407
  return self._reply(
408
408
  404,
@@ -412,7 +412,9 @@ def make_session_handler(
412
412
  },
413
413
  )
414
414
  headers = {k.lower(): v for k, v in self.headers.items()}
415
- status, body, extra = app.handle(method, self.path, headers, raw, f"127.0.0.1:{self.server.server_port}")
415
+ status, body, extra = app.handle(
416
+ method, self.path, headers, raw, f"127.0.0.1:{self.server.server_port}", via=Via.API
417
+ )
416
418
  send_response(self, status, body, extra, app.settings.error_content_type)
417
419
 
418
420
  def _ui(self, method: str, path: str) -> None:
@@ -427,10 +429,11 @@ def make_session_handler(
427
429
  self.end_headers()
428
430
  self.wfile.write(payload)
429
431
 
430
- def _ui_api(self, method: str, path: str, raw: bytes) -> None:
432
+ def _ui_api(self, method: str, path: str, raw: bytes, via: Via) -> None:
431
433
  """The page's same-origin api call: strip the ``api_path`` prefix
432
434
  and answer the route with the world's own credential for the pin,
433
- the way the host answers it for the session cookie."""
435
+ the way the host answers it for the session cookie. Only the ui
436
+ port's prefix is ``via: ui``; the session port is the api origin."""
434
437
  assert app is not None and ui is not None
435
438
  route = api_target(ui, path)
436
439
  assert route is not None
@@ -444,7 +447,12 @@ def make_session_handler(
444
447
  credential_headers, credential_query = vendor_credential(app.router.spec, api_key or "", grant=grant)
445
448
  target = with_query(route + (f"?{query}" if query else ""), credential_query)
446
449
  status, body, extra = app.handle(
447
- method, target, {**headers, **credential_headers}, raw, f"127.0.0.1:{self.server.server_port}"
450
+ method,
451
+ target,
452
+ {**headers, **credential_headers},
453
+ raw,
454
+ f"127.0.0.1:{self.server.server_port}",
455
+ via=via,
448
456
  )
449
457
  send_response(self, status, body, extra, app.settings.error_content_type)
450
458