@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
@@ -0,0 +1,121 @@
1
+ """Which World Host replica owns a session this one does not, and what sending a request on to
2
+ it may meet: the platform's word on its owner (:class:`PlatformOwners`), an owner that does not
3
+ answer or no longer holds the session (:class:`OwnerUnreachable`), and the headers a relay drops."""
4
+
5
+ from __future__ import annotations
6
+
7
+ import json
8
+ import threading
9
+ import time
10
+ import urllib.error
11
+ import urllib.parse
12
+ import urllib.request
13
+ from typing import Protocol
14
+
15
+ from .admission import QUEUE_WAIT_S
16
+ from .host_workers import CALL_TIMEOUT_S
17
+ from .session_move import HOLD_S, same_host
18
+ from .workers import HEALTH_TIMEOUT_S
19
+
20
+ OWNER_CACHE_S = 60.0
21
+ #: The longest a request sent on to its owner may take there: held while its session moves, then its
22
+ #: queue wait, its call and the probes that name a timeout.
23
+ PROXY_TIMEOUT_S = HOLD_S + QUEUE_WAIT_S + CALL_TIMEOUT_S + 2 * HEALTH_TIMEOUT_S + 1.0
24
+ #: Long enough that a client hammering a closed session costs the platform one call at a time,
25
+ #: short enough that a session recovered onto another host is reached at once.
26
+ OWNER_MISS_S = 2.0
27
+ CLOSED_SESSION = {"error": "unknown or closed session"}
28
+ #: Only the framing is dropped: every header the world set must pass through a relay.
29
+ FRAMING_HEADERS = frozenset({"content-length", "connection", "transfer-encoding", "server", "date"})
30
+ HOP_BY_HOP_HEADERS = frozenset(
31
+ {"keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade", "proxy-connection"}
32
+ )
33
+ PROXIED_DROP_HEADERS = FRAMING_HEADERS | HOP_BY_HOP_HEADERS
34
+
35
+
36
+ class _NoRedirect(urllib.request.HTTPRedirectHandler):
37
+ """An owner's redirect is the client's to follow, not the proxy's: the ui
38
+ token exchange answers 303 with the session cookie, and following it here
39
+ would drop the cookie and land on the owner's 401."""
40
+
41
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
42
+ return None
43
+
44
+
45
+ PROXY_OPENER = urllib.request.build_opener(_NoRedirect)
46
+
47
+
48
+ class OwnerLookup(Protocol):
49
+ """Which host owns a session this replica does not: its control-plane
50
+ URL, or None for a closed or unknown one. ``fresh`` bypasses whatever the
51
+ lookup remembers, for a caller that has just found the remembered owner
52
+ dead."""
53
+
54
+ def __call__(self, sid: str, *, fresh: bool = False) -> str | None: ...
55
+
56
+
57
+ class PlatformOwners:
58
+ """The platform's word on which host owns a session: ``GET /api/public/world-sessions/{sid}/host``,
59
+ host-secret authenticated, answers ``{hostUrl}``, and a 404 is a closed or unknown session. Called
60
+ as an :class:`OwnerLookup` it names another host or None (our own address too: a session we do
61
+ not hold that the platform says is ours is gone, not one hop away), held briefly so a busy
62
+ session costs one call at a time; :meth:`current` asks afresh and names this host too, for a
63
+ copy pending a move here."""
64
+
65
+ def __init__(self, platform_url: str, secret: str | None, self_url: str | None) -> None:
66
+ self.base = platform_url.rstrip("/")
67
+ self.secret = secret or ""
68
+ self.self_url = self_url
69
+ self._cache: dict[str, tuple[float, str | None]] = {}
70
+ self._lock = threading.Lock()
71
+
72
+ def __call__(self, sid: str, *, fresh: bool = False) -> str | None:
73
+ now = time.time()
74
+ with self._lock:
75
+ hit = None if fresh else self._cache.get(sid)
76
+ if hit is not None and hit[0] > now:
77
+ return hit[1]
78
+ owner = self.current(sid)
79
+ other = None if same_host(owner, self.self_url) else owner
80
+ with self._lock:
81
+ self._cache[sid] = (now + (OWNER_CACHE_S if other else OWNER_MISS_S), other)
82
+ return other
83
+
84
+ def current(self, sid: str) -> str | None:
85
+ req = urllib.request.Request(
86
+ f"{self.base}/api/public/world-sessions/{urllib.parse.quote(sid, safe='')}/host",
87
+ headers={"X-Host-Secret": self.secret},
88
+ )
89
+ try:
90
+ with urllib.request.urlopen(req, timeout=5) as r:
91
+ answer = json.loads(r.read() or b"{}")
92
+ except urllib.error.HTTPError as e:
93
+ if e.code != 404:
94
+ raise
95
+ return None
96
+ url = answer.get("hostUrl") if isinstance(answer, dict) else None
97
+ return url if isinstance(url, str) and url else None
98
+
99
+
100
+ class OwnerUnreachable(Exception):
101
+ """The owner a request was proxied to did not answer, or answered that it no longer holds the
102
+ session: its ``answer``, relayed as it came when no other owner is named. ``delivered`` when the
103
+ request reached it and no answer came back: it may have run there, so it is never sent again."""
104
+
105
+ def __init__(
106
+ self, detail: str, answer: tuple[int, list[tuple[str, str]], bytes] | None = None, *, delivered: bool = False
107
+ ) -> None:
108
+ super().__init__(detail)
109
+ self.answer = answer
110
+ self.delivered = delivered
111
+
112
+
113
+ def closed_session(status: int, _headers: object, payload: bytes) -> bool:
114
+ """Whether a host answered that it holds no such session (its own 404, which a host that
115
+ handed the session off, or a pod that reused its address, answers a stale route)."""
116
+ if status != 404 or len(payload) > 256:
117
+ return False
118
+ try:
119
+ return json.loads(payload) == CLOSED_SESSION
120
+ except ValueError:
121
+ return False
@@ -0,0 +1,111 @@
1
+ """A World Host's request handler, the half that sends a request on to the replica that owns its
2
+ session, one hop, and writes another process's answer through as it came."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import http.client
7
+ import urllib.error
8
+ import urllib.request
9
+ from collections.abc import Callable, Iterable
10
+ from typing import TYPE_CHECKING
11
+
12
+ from .call_capture import WorldRequestHandler, write_body
13
+ from .host_owners import (
14
+ PROXIED_DROP_HEADERS,
15
+ PROXY_OPENER,
16
+ PROXY_TIMEOUT_S,
17
+ OwnerLookup,
18
+ OwnerUnreachable,
19
+ closed_session,
20
+ )
21
+ from .host_surfaces import HOP_HEADER, hops, tunnel
22
+ from .session_move import same_host
23
+
24
+ if TYPE_CHECKING:
25
+ from .world_host import WorldHost
26
+
27
+
28
+ class OwnerProxy(WorldRequestHandler):
29
+ """Sends a request on to its session's owner and relays the answer; the handler supplies the
30
+ host it serves (``world_host``), its memoized body (``_read``) and its own answers (``_reply``)."""
31
+
32
+ world_host: WorldHost
33
+ _read: Callable[[], bytes]
34
+ _reply: Callable[..., None]
35
+
36
+ def _proxy(self, sid: str, owner: str, lookup: OwnerLookup | None, method: str, headers: dict[str, str]) -> None:
37
+ """Send the request on to ``owner``. An owner that could not be reached, or answers that it no
38
+ longer holds the session, may be a host that handed the session off or died with it since it
39
+ was recovered elsewhere, so the platform is asked once more, uncached, and the request goes to
40
+ the owner it names now; only then is it the owner's answer, or a 502. A request the owner took
41
+ and never answered may have run there, so it is never sent again. The retry stays one hop (the
42
+ hop header goes with it)."""
43
+ websocket = headers.get("upgrade", "").lower() == "websocket"
44
+ raw = b"" if websocket else self._read()
45
+ try:
46
+ return self._forward(owner, method, headers, raw, websocket)
47
+ except OwnerUnreachable as stale:
48
+ current = None if stale.delivered or lookup is None else lookup(sid, fresh=True)
49
+ if not current or same_host(current, owner):
50
+ return self._unreachable(stale)
51
+ self.world_host.tally("requests.rerouted")
52
+ try:
53
+ self._forward(current, method, headers, raw, websocket)
54
+ except OwnerUnreachable as error:
55
+ self._unreachable(error)
56
+
57
+ def _unreachable(self, error: OwnerUnreachable) -> None:
58
+ if error.answer is not None:
59
+ return self._relay(*error.answer, drop=PROXIED_DROP_HEADERS)
60
+ self._reply(502, {"error": "owner unreachable", "detail": str(error)})
61
+
62
+ def _forward(self, owner: str, method: str, headers: dict[str, str], raw: bytes, websocket: bool) -> None:
63
+ """One attempt at ``owner``; raises :class:`OwnerUnreachable` when it did not answer, before
64
+ anything has been written to the client."""
65
+ if websocket:
66
+ owner_ws = "ws://" + owner.split("://", 1)[-1].rstrip("/")
67
+ self.close_connection = True
68
+ try:
69
+ hopped = {**headers, HOP_HEADER: str(hops(headers) + 1)}
70
+ tunnel(self.connection, owner_ws, self.path, hopped, host=headers.get("host"))
71
+ except OSError as error:
72
+ raise OwnerUnreachable(str(error)) from error
73
+ return
74
+ target = f"{owner.rstrip('/')}{self.path}"
75
+ forward = {k: v for k, v in headers.items() if k not in ("host", "content-length")}
76
+ forward["host"] = headers.get("host", "")
77
+ forward[HOP_HEADER] = str(hops(headers) + 1)
78
+ req = urllib.request.Request(target, data=raw or None, method=method, headers=forward)
79
+ try:
80
+ with PROXY_OPENER.open(req, timeout=PROXY_TIMEOUT_S) as r:
81
+ self._relay(r.status, r.headers.items(), r.read(), drop=PROXIED_DROP_HEADERS)
82
+ except urllib.error.HTTPError as e:
83
+ answer = (e.code, e.headers.items(), e.read())
84
+ if closed_session(*answer):
85
+ raise OwnerUnreachable("the owner no longer holds the session", answer) from e
86
+ self._relay(*answer, drop=PROXIED_DROP_HEADERS)
87
+ except urllib.error.URLError as error:
88
+ raise OwnerUnreachable(str(error)) from error
89
+ except (OSError, http.client.HTTPException) as error:
90
+ raise OwnerUnreachable(str(error), delivered=True) from error
91
+
92
+ def _relay(self, status: int, headers: Iterable[tuple[str, str]], payload: bytes, *, drop: frozenset[str]) -> None:
93
+ """Write another process's answer through as it came: same status, same body bytes, every
94
+ header the world set except ``drop`` (the framing, which is this connection's, and from an
95
+ owner the hop-by-hop headers too). The world's contract, its ``page_headers`` included, reads
96
+ the same from every replica."""
97
+ self.send_response(status)
98
+ content_type = None
99
+ for name, value in headers:
100
+ lower = name.lower()
101
+ if lower == "content-type":
102
+ content_type = value
103
+ elif lower not in drop:
104
+ self.send_header(name, value)
105
+ self.send_header("Content-Type", content_type or "application/json")
106
+ self.send_header("Content-Length", str(len(payload)))
107
+ try:
108
+ self.end_headers()
109
+ write_body(self, payload)
110
+ except ConnectionError:
111
+ self.close_connection = True
@@ -76,3 +76,9 @@ class BrowserRelay:
76
76
  fail("host", "browser must be {url: 'ws://host:port', token: <relay token>}")
77
77
  raise AssertionError # fail() never returns
78
78
  return cls(url.rstrip("/"), token)
79
+
80
+
81
+ def restore_sha256(restore: object) -> str | None:
82
+ """The sha256 of the export an open restores from, or None for an open that restores nothing."""
83
+ sha256 = restore.get("sha256") if isinstance(restore, dict) else None
84
+ return sha256 if isinstance(sha256, str) else None
@@ -0,0 +1,126 @@
1
+ """One session a World Host holds (:class:`Session`) and a copy of its state waiting
2
+ to be uploaded (:class:`Export`)."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import threading
7
+ import time
8
+ from dataclasses import InitVar, dataclass, field
9
+ from pathlib import Path
10
+ from typing import TYPE_CHECKING
11
+
12
+ from .door import OPEN_MODE, VENDOR_MODE, Door, same
13
+ from .host_surfaces import SessionHost, capability_host
14
+ from .request_ledger import LedgerLife
15
+ from .session_move import SessionMove
16
+
17
+ if TYPE_CHECKING:
18
+ from .api import ApiSettings, WorldApp
19
+ from .connector import Spec
20
+ from .database import WorldDatabase
21
+ from .host_requests import BrowserRelay
22
+ from .host_surfaces import UiSurface
23
+ from .runtime import WorldRuntime
24
+ from .tasks import TaskSpec
25
+ from .workers import Worker
26
+
27
+
28
+ @dataclass
29
+ class Export:
30
+ """A session's state copied to a file on this host, hashed, waiting for the
31
+ platform to hand over the presigned URL it goes to."""
32
+
33
+ export_id: str
34
+ path: Path
35
+ sha256: str
36
+ bytes: int
37
+ content_type: str
38
+
39
+ def describe(self) -> dict:
40
+ return {
41
+ "exportId": self.export_id,
42
+ "sha256": self.sha256,
43
+ "bytes": self.bytes,
44
+ "contentType": self.content_type,
45
+ }
46
+
47
+
48
+ @dataclass
49
+ class Session:
50
+ session_id: str
51
+ version_id: str
52
+ task: str | None
53
+ spec: Spec | None
54
+ token: str | None
55
+ bundle: Path
56
+ tree: Path
57
+ lease_until: float
58
+ engine: type[WorldDatabase]
59
+ runtime: WorldRuntime | None = None
60
+ worker: Worker | None = None
61
+ door: Door | None = None
62
+ ui: UiSurface | None = None
63
+ browser: BrowserRelay | None = None
64
+ #: Teardown waits for zero, so a close or expiry never pulls the database from under a handler.
65
+ inflight: int = 0
66
+ closing: bool = False
67
+ opened_at: float = field(default_factory=time.time)
68
+ #: A renewal or an export is the platform looking, not the session working: the idle clock follows this.
69
+ touched_at: float = field(default_factory=time.time)
70
+ export: Export | None = None
71
+ restored: bool = False
72
+ task_spec: TaskSpec | None = None
73
+ exporting: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
74
+ #: What the worker was asked to open, so a session reopens on the next worker if this one dies.
75
+ placement: dict | None = None
76
+ settings: ApiSettings | None = None
77
+ restore_sha256: str | None = None
78
+ pending: InitVar[bool] = False
79
+ move: SessionMove = field(init=False, repr=False, compare=False)
80
+ auth: str = VENDOR_MODE
81
+ life: LedgerLife = field(default_factory=LedgerLife)
82
+ finish_claimed: bool = field(default=False, init=False)
83
+ recoveries: int = field(default=0, init=False)
84
+ close_reason: str = field(default="closed", init=False)
85
+ unrecovered: bool = field(default=False, init=False)
86
+
87
+ def __post_init__(self, pending: bool) -> None:
88
+ self.move = SessionMove(self.session_id, pending=pending)
89
+
90
+ def preflight(self, method: str, headers: dict[str, str]) -> tuple | None:
91
+ """A browser's preflight, answered here before the token gate (it carries none) when the
92
+ world serves browsers: from the world's declared settings, never its worker."""
93
+ return None if self.settings is None else self.settings.cors.preflight(method, headers)
94
+
95
+ @property
96
+ def app(self) -> WorldApp | None:
97
+ """The world's routes over this session's store, when this process
98
+ serves it and the tree has any."""
99
+ return self.runtime.app if self.runtime is not None else None
100
+
101
+ @property
102
+ def task_key(self) -> tuple[str | None, dict | None]:
103
+ """What an open retry must match: the bundled name or the spec itself."""
104
+ return self.task, self.task_spec.raw if self.task_spec is not None else None
105
+
106
+ @property
107
+ def seconds(self) -> float:
108
+ return max(0.0, time.time() - self.opened_at)
109
+
110
+ @property
111
+ def live_worker(self) -> Worker | None:
112
+ """The worker serving this session while it runs; None for one served in this process or whose
113
+ worker is gone."""
114
+ return self.worker if self.worker is not None and self.worker.alive() else None
115
+
116
+ def opened_by(self, named: SessionHost) -> bool:
117
+ """``named`` is this open session's capability hostname. A capability label that is
118
+ not this session's, or any label on a session that is not open, reaches nothing."""
119
+ capability = self.door.capability if self.door is not None else None
120
+ return self.auth == OPEN_MODE and capability is not None and same(named.capability, capability)
121
+
122
+ def api_host(self, domain: str, opened: bool) -> str:
123
+ """The host a link the world writes points at when a request names none."""
124
+ if opened and self.door is not None and self.door.capability is not None:
125
+ return capability_host(self.session_id, self.door.capability, "api", domain)
126
+ return f"w-{self.session_id}-api.{domain}"
@@ -27,6 +27,7 @@ from __future__ import annotations
27
27
 
28
28
  import hmac
29
29
  import mimetypes
30
+ import re
30
31
  import selectors
31
32
  import socket
32
33
  import time
@@ -36,6 +37,7 @@ from http.cookies import SimpleCookie
36
37
  from pathlib import Path
37
38
 
38
39
  from .._toml import tomllib
40
+ from .door import OPEN_LABEL_CHARS, OPEN_PREFIX
39
41
  from .validation import fail
40
42
 
41
43
  API_BUNDLE = "gateway-api-world.toml"
@@ -43,8 +45,10 @@ API_BUNDLE = "gateway-api-world.toml"
43
45
  SESSION_COOKIE = "__world_session"
44
46
  #: Query parameter that carries the session token exactly once, on the way in.
45
47
  TOKEN_QUERY = "token"
46
- #: Marks a request another host already forwarded once; never sent on again.
48
+ #: How many hosts a request was already sent on by. One that hopped is never sent to an owner a lookup
49
+ #: names, only to where this host handed its session; none goes past ``MAX_HOPS``.
47
50
  HOP_HEADER = "x-worlds-hop"
51
+ MAX_HOPS = 2
48
52
  #: Headers copied from a websocket client's upgrade request upstream.
49
53
  UPGRADE_HEADERS = (
50
54
  HOP_HEADER,
@@ -63,11 +67,6 @@ TUNNEL_CONNECT_TIMEOUT_S = 10.0
63
67
  TUNNEL_BUFFER = 64 * 1024
64
68
 
65
69
 
66
- # --------------------------------------------------------------------------- #
67
- # The static ui.
68
- # --------------------------------------------------------------------------- #
69
-
70
-
71
70
  @dataclass(frozen=True)
72
71
  class UiSurface:
73
72
  #: The directory holding ``index.html`` and the built assets.
@@ -155,6 +154,7 @@ _PINNED_TYPES = {
155
154
  ".woff2": "font/woff2",
156
155
  }
157
156
 
157
+
158
158
  def static_file(ui: UiSurface, path: str) -> tuple[int, dict[str, str], bytes]:
159
159
  """One static response: the file at ``path`` under the ui root, or
160
160
  ``index.html`` for a client-side route (a path with no extension). A path
@@ -189,11 +189,6 @@ def static_file(ui: UiSurface, path: str) -> tuple[int, dict[str, str], bytes]:
189
189
  return 200, {"content-type": content_type, "cache-control": cache}, candidate.read_bytes()
190
190
 
191
191
 
192
- # --------------------------------------------------------------------------- #
193
- # Admitting a person: the token cookie.
194
- # --------------------------------------------------------------------------- #
195
-
196
-
197
192
  def cross_site(headers: dict[str, str], own_origin) -> bool:
198
193
  """Whether a browser marked this request as coming from another site: a
199
194
  ``Sec-Fetch-Site`` other than same-origin/none, or an ``Origin`` that
@@ -206,6 +201,71 @@ def cross_site(headers: dict[str, str], own_origin) -> bool:
206
201
  return bool(site and site not in ("same-origin", "none")) or bool(origin and not own_origin(origin))
207
202
 
208
203
 
204
+ def public_host(host_header: str | None, worlds_domain: str) -> bool:
205
+ """True when ``Host`` names something under the worlds domain: a session,
206
+ or any other label the wildcard ALB forwarded. That is the public side.
207
+ Prometheus, the kubelet and the ALB health check address the pod itself
208
+ (``ip:port``), which is not."""
209
+ name = (host_header or "").split(":")[0].rstrip(".").lower()
210
+ domain = worlds_domain.rstrip(".").lower()
211
+ return bool(domain) and (name == domain or name.endswith("." + domain))
212
+
213
+
214
+ @dataclass(frozen=True)
215
+ class SessionHost:
216
+ """What a ``Host`` header names: a session, the surface (``api``, ``ui`` or
217
+ ``browser``) and, on an open session's capability hostname, its secret label."""
218
+
219
+ session_id: str
220
+ surface: str
221
+ capability: str | None = None
222
+
223
+
224
+ SURFACE_SUFFIXES = (("-api", "api"), ("-cdp", "browser"))
225
+ CAPABILITY = re.compile(rf"[a-z2-7]{{{OPEN_LABEL_CHARS}}}")
226
+ NO_SESSION_NAMED = {"error": "no session named by Host"}
227
+ NO_REFERRER = {"Referrer-Policy": "no-referrer"}
228
+
229
+
230
+ def session_from_host(host_header: str | None) -> SessionHost | None:
231
+ """``w-<sid>-api.<domain>`` / ``w-<sid>.<domain>`` / ``w-<sid>-cdp.<domain>``, or an
232
+ open session's capability hostname ``o-<sid>-<label>-api.<domain>`` /
233
+ ``o-<sid>-<label>.<domain>`` (never a browser), → the session it names. None when
234
+ the host names no session."""
235
+ if not host_header:
236
+ return None
237
+ label = host_header.split(":")[0].split(".")[0]
238
+ kind = label[:2]
239
+ rest, surface = _surface(label[2:])
240
+ if kind == "w-" and rest:
241
+ return SessionHost(rest, surface)
242
+ if kind == OPEN_PREFIX and surface != "browser":
243
+ return _capability_host(rest, surface)
244
+ return None
245
+
246
+
247
+ def _surface(rest: str) -> tuple[str, str]:
248
+ for suffix, surface in SURFACE_SUFFIXES:
249
+ if rest.endswith(suffix):
250
+ return rest[: -len(suffix)], surface
251
+ return rest, "ui"
252
+
253
+
254
+ def _capability_host(rest: str, surface: str) -> SessionHost | None:
255
+ """The session an ``o-`` label names; its label exactly as :func:`~.door.open_label`
256
+ spells it (lowercase base32), since a spelling the scrub does not know must not admit."""
257
+ session_id, _, capability = rest.rpartition("-")
258
+ if not session_id or not CAPABILITY.fullmatch(capability):
259
+ return None
260
+ return SessionHost(session_id, surface, capability)
261
+
262
+
263
+ def capability_host(session_id: str, capability: str, surface: str, domain: str) -> str:
264
+ """The capability hostname of an open session's ``surface`` (``api`` or ``ui``)."""
265
+ suffix = "-api" if surface == "api" else ""
266
+ return f"{OPEN_PREFIX}{session_id}-{capability}{suffix}.{domain}"
267
+
268
+
209
269
  def cookie_token(headers: dict[str, str]) -> str | None:
210
270
  """The session token a request's cookie carries, if any."""
211
271
  raw = headers.get("cookie")
@@ -249,11 +309,6 @@ def matches(candidate: str | None, token: str) -> bool:
249
309
  return candidate is not None and hmac.compare_digest(candidate, token)
250
310
 
251
311
 
252
- # --------------------------------------------------------------------------- #
253
- # Live-view grants: the relay's scheme, so a console viewer needs no token.
254
- # --------------------------------------------------------------------------- #
255
-
256
-
257
312
  def mint_live_grant(token: str, ttl_ms: int, scope: str = "view", now_ms: int | None = None) -> str:
258
313
  """``<expiresAtMs>.<scope>.<hmac>`` signed with ``token`` — the format
259
314
  ``deploy/world-browser/relay.mjs`` verifies."""
@@ -279,11 +334,6 @@ def verify_live_grant(grant: str, token: str, now_ms: int | None = None) -> str
279
334
  return scope if hmac.compare_digest(sig, expected) else None
280
335
 
281
336
 
282
- # --------------------------------------------------------------------------- #
283
- # The websocket tunnel.
284
- # --------------------------------------------------------------------------- #
285
-
286
-
287
337
  def tunnel(client: socket.socket, target: str, path: str, headers: dict[str, str], host: str | None = None) -> None:
288
338
  """Pipe a websocket client through to ``target`` (``ws://host:port``): send
289
339
  the upgrade request for ``path`` with the client's handshake headers, then
@@ -326,3 +376,11 @@ def pump(a: socket.socket, b: socket.socket) -> None:
326
376
  sink.sendall(data)
327
377
  except OSError:
328
378
  return
379
+
380
+
381
+ def hops(headers: dict[str, str]) -> int:
382
+ """How many hops ``headers`` say a request made; an unreadable count is taken as the most."""
383
+ value = headers.get(HOP_HEADER)
384
+ if value is None:
385
+ return 0
386
+ return int(value) if value.isdigit() and len(value) < 3 else MAX_HOPS
@@ -0,0 +1,127 @@
1
+ """Moving a session's bytes to and from the object store the platform presigns for: only the origins
2
+ ``WORLDS_HOST_OBJECT_STORE`` names, each transfer hashed and bounded in time."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import base64
7
+ import hashlib
8
+ import os
9
+ import re
10
+ import shutil
11
+ import urllib.error
12
+ import urllib.parse
13
+ import urllib.request
14
+ import uuid
15
+ from pathlib import Path
16
+
17
+ from .session_files import refuse_digest_mismatch
18
+ from .validation import fail
19
+
20
+ TRANSFER_TIMEOUT_S = 300.0
21
+ OBJECT_STORE_ANY = "any"
22
+ _ORIGIN_HOST = re.compile(r"^[A-Za-z0-9.-]+(:[0-9]+)?$")
23
+
24
+
25
+ def parse_origins(value: str | None) -> frozenset[str] | None:
26
+ """``WORLDS_HOST_OBJECT_STORE``: the origins (``scheme://host[:port]``,
27
+ comma-separated) the platform's presigned URLs may point at, or the word
28
+ ``any`` for a dev host reading ``file://`` bundles (``None``: every URL
29
+ admitted). Unset is refused rather than read as ``any``: a deployed host
30
+ with no allowlist is a host whose secret can aim it anywhere, and a
31
+ template's placeholder (``https://<bucket>.s3...``) is refused by name."""
32
+ if value is None or not value.strip():
33
+ fail(
34
+ "host",
35
+ "WORLDS_HOST_OBJECT_STORE is unset; name the object store's origins "
36
+ f"(https://bucket.s3.amazonaws.com) or {OBJECT_STORE_ANY!r} for a dev host",
37
+ )
38
+ if value.strip().lower() == OBJECT_STORE_ANY:
39
+ return None
40
+ origins = set()
41
+ for item in value.split(","):
42
+ item = item.strip()
43
+ if not item:
44
+ continue
45
+ parts = urllib.parse.urlsplit(item)
46
+ if parts.scheme not in ("http", "https") or not parts.netloc or parts.path not in ("", "/"):
47
+ fail(
48
+ "host",
49
+ f"WORLDS_HOST_OBJECT_STORE entries are origins like https://bucket.s3.amazonaws.com, not {item!r}",
50
+ )
51
+ if not _ORIGIN_HOST.match(parts.netloc):
52
+ fail(
53
+ "host",
54
+ f"WORLDS_HOST_OBJECT_STORE names a placeholder, not a host: {item!r}; set the real bucket origin",
55
+ )
56
+ origins.add(f"{parts.scheme}://{parts.netloc}".lower())
57
+ return frozenset(origins)
58
+
59
+
60
+ def check_object_store_url(url: object, origins: frozenset[str] | None, what: str) -> str:
61
+ """The presigned URL the control plane handed us, once it is a string on one
62
+ of the object store's origins. The control plane is trusted with the host
63
+ secret, not with the host's network: a URL pointing anywhere else (the
64
+ metadata service, a cluster Service, the internet) is refused before a
65
+ byte moves, so a leaked secret cannot turn a session's state or the host's
66
+ reach into someone else's download."""
67
+ if not isinstance(url, str) or not url:
68
+ fail("host", f"{what} must be a presigned url")
69
+ if origins is None:
70
+ return url
71
+ parts = urllib.parse.urlsplit(url)
72
+ origin = f"{parts.scheme}://{parts.netloc}".lower()
73
+ if origin not in origins:
74
+ fail("host", f"{what} must be on the object store ({', '.join(sorted(origins))}), not {origin}")
75
+ return url
76
+
77
+
78
+ def file_digest(path: Path) -> tuple[str, int]:
79
+ """The hex sha256 and size of a file, streamed."""
80
+ digest = hashlib.sha256()
81
+ size = 0
82
+ with open(path, "rb") as fh:
83
+ for chunk in iter(lambda: fh.read(1 << 20), b""):
84
+ digest.update(chunk)
85
+ size += len(chunk)
86
+ return digest.hexdigest(), size
87
+
88
+
89
+ def download_verified(url: str, sha256: str, dest: Path) -> Path:
90
+ """Fetch ``url`` into ``dest`` and refuse it unless its bytes hash to
91
+ ``sha256``; a mismatch leaves nothing behind."""
92
+ dest.parent.mkdir(parents=True, exist_ok=True)
93
+ staging = dest.with_name(f".{dest.name}.{uuid.uuid4().hex}")
94
+ try:
95
+ try:
96
+ with (
97
+ urllib.request.urlopen(urllib.request.Request(url), timeout=TRANSFER_TIMEOUT_S) as r,
98
+ open(staging, "wb") as out,
99
+ ):
100
+ shutil.copyfileobj(r, out)
101
+ except Exception as error: # noqa: BLE001 - name the stage in the message
102
+ fail("host", f"could not download the session export: {error}")
103
+ refuse_digest_mismatch(staging, sha256)
104
+ os.replace(staging, dest)
105
+ finally:
106
+ staging.unlink(missing_ok=True)
107
+ return dest
108
+
109
+
110
+ def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str) -> None:
111
+ """PUT a file to a presigned URL, sending exactly the headers the platform
112
+ signed for it: content type, length and the base64 sha256 the object store
113
+ verifies on receipt."""
114
+ headers = {
115
+ "Content-Type": content_type,
116
+ "Content-Length": str(size),
117
+ "x-amz-checksum-sha256": base64.b64encode(bytes.fromhex(sha256)).decode("ascii"),
118
+ }
119
+ with open(path, "rb") as fh:
120
+ request = urllib.request.Request(url, data=fh, method="PUT", headers=headers)
121
+ try:
122
+ with urllib.request.urlopen(request, timeout=TRANSFER_TIMEOUT_S) as response:
123
+ response.read()
124
+ except urllib.error.HTTPError as error:
125
+ fail("host", f"the export upload was refused: HTTP {error.code} {error.read()[:200]!r}")
126
+ except urllib.error.URLError as error:
127
+ fail("host", f"could not upload the export: {error.reason}")