@withgateway/sdk 0.3.1 → 0.3.3

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 (129) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2880 -2032
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2982 -2135
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +180 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +172 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  13. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1309 -540
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1287 -532
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +177 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +169 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +69 -13
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +69 -13
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +249 -120
  35. package/dist/worlds/index.d.ts +249 -120
  36. package/dist/worlds/index.js +1240 -484
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1231 -476
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -514
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  57. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  58. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  59. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  60. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  61. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  62. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  63. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  64. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  65. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  66. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  67. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  68. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  69. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  70. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  71. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  72. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  73. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  74. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  75. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  76. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  77. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  78. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  79. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  80. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  81. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  82. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  83. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  84. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  86. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  87. package/runtime/gatewaysdk/environment/schema/platform.py +123 -171
  88. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  90. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  91. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  92. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  93. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  94. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  95. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  96. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -11
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +14 -14
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +12 -12
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  103. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  104. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  105. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  106. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  107. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  108. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  109. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  110. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  111. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  112. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  113. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  114. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  115. package/runtime/gatewaysdk/environment/score.py +57 -0
  116. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  117. package/runtime/gatewaysdk/environment/world.py +42 -3
  118. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  119. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  120. package/skills/connector-schema-authoring/SKILL.md +19 -11
  121. package/skills/connector-schema-authoring/connector-worlds.md +13 -4
  122. package/skills/connector-schema-authoring/world-schema.md +103 -51
  123. package/skills/world-data-ingestion/ROWS.md +29 -3
  124. package/skills/world-data-ingestion/SKILL.md +14 -14
  125. package/skills/worlds-getting-started/SKILL.md +12 -12
  126. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  127. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  128. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  129. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -21,7 +21,7 @@ Every session carries a lease. Control calls and data-plane requests renew it;
21
21
  a session the platform stops touching expires on the host and is unlinked, so
22
22
  a missed reconcile tick on the platform is recovered, not leaked.
23
23
 
24
- A session's state is one sqlite file, so it is also its own durable form: the
24
+ A session's state is one database file, so it is also its own durable form: the
25
25
  platform asks the host to **export** a session (a consistent copy, hashed) and
26
26
  to **upload** that copy to a presigned URL the platform holds the key for, and
27
27
  later **opens** the same session id on any host with ``restore`` naming the
@@ -36,8 +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 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
39
+ api and logged ``via: ui`` (the api origin's calls ``via: api``, a declared
40
+ tool called by name ``via: tool``); the **browser** surface is a websocket tunnel to the pool Chromium the
41
41
  platform leased for the session (:mod:`host_surfaces`). Custom-server worlds
42
42
  stay on pods; this module refuses a version it cannot open rather than
43
43
  guessing.
@@ -87,7 +87,9 @@ from .api import (
87
87
  from .compiler import check_bundle
88
88
  from .connector import Spec, load_spec
89
89
  from .credentials import basic_user
90
+ from .database import WorldDatabase
90
91
  from .dependencies import Dependency
92
+ from .handler_errors import carried, log_request_failure, request_failure_body
91
93
  from .host_requests import BrowserRelay, DependencyRef, parse_dependency_refs
92
94
  from .host_surfaces import (
93
95
  HOP_HEADER,
@@ -105,8 +107,11 @@ from .host_surfaces import (
105
107
  verify_live_grant,
106
108
  without_query_token,
107
109
  )
110
+ from .lanes import Lanes
108
111
  from .runtime import SnapshotRuntime, TreeRuntime, WorldRuntime
109
- from .tasks import TaskSpec, parse_task_spec, unknown_task_tools
112
+ from .served_names import ServedNames
113
+ from .session_files import ExportFile, SessionExport, refuse_digest_mismatch
114
+ from .tasks import TaskSpec, parse_task_spec
110
115
  from .tools_world import DependencyWorld, ToolsVersion, is_tools_bundle, load_tools_version
111
116
  from .validation import ContractError, fail
112
117
  from .verbs import SESSION_VERBS, session_verb, unknown_verb
@@ -120,35 +125,21 @@ from .workers import (
120
125
  WorkerPool,
121
126
  )
122
127
 
123
- #: The world tree inside an api bundle, or the bundle root for a bare tree.
124
128
  BUNDLED_WORLD = "server/world"
125
129
  WORLD_SPEC = "schema/world.json"
126
- #: How long a session lives with no control call or request renewing it.
127
130
  DEFAULT_LEASE_S = 3600.0
128
- #: How often the host sweeps expired leases.
129
131
  LEASE_SWEEP_S = 30.0
130
- #: How long an owner lookup answer is trusted before asking the platform again.
131
- #: An owner that does not answer a proxied request is asked about again at once.
132
132
  OWNER_CACHE_S = 60.0
133
- #: How long "no owner" is trusted: long enough that a client hammering a closed
134
- #: session costs the platform one call at a time, short enough that a session
135
- #: recovered onto another host is reached at once.
133
+ #: Long enough that a client hammering a closed session costs the platform one call at a time,
134
+ #: short enough that a session recovered onto another host is reached at once.
136
135
  OWNER_MISS_S = 2.0
137
- #: How many sessions one host takes before the platform places elsewhere.
138
136
  DEFAULT_MAX_SESSIONS = 1500
139
- #: The error code (and a 404) a control call gets for a session this host does
140
- #: not hold. The platform treats exactly this answer as "the host lost it".
137
+ #: The platform treats exactly this code (with a 404) as "the host lost the session".
141
138
  UNKNOWN_SESSION = "unknown_session"
142
- #: How often a host tells the platform it is alive and what it holds.
143
139
  HEARTBEAT_S = 10.0
144
- #: How long a draining host waits for its sessions to close before it exits.
145
140
  DEFAULT_DRAIN_S = 45.0
146
- #: Response headers a relayed answer does NOT keep: the framing is this
147
- #: connection's, everything else the world set (its ``page_headers``, a
148
- #: handler's own headers) passes through, from a worker and from an owner alike.
141
+ #: Only the framing is dropped: every header the world set must pass through a relay.
149
142
  FRAMING_HEADERS = frozenset({"content-length", "connection", "transfer-encoding", "server", "date"})
150
- #: Hop-by-hop headers (RFC 9110 §7.6.1) an owner's answer does not carry past
151
- #: the proxying replica.
152
143
  HOP_BY_HOP_HEADERS = frozenset(
153
144
  {"keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade", "proxy-connection"}
154
145
  )
@@ -164,25 +155,14 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
164
155
  return None
165
156
 
166
157
 
167
- #: The opener the one-hop proxy uses: relays the owner's answer as is, a
168
- #: redirect included, rather than following it.
169
158
  _PROXY_OPENER = urllib.request.build_opener(_NoRedirect)
170
- #: How long the grant the host mints towards the relay lives: the viewer's own
171
- #: grant was already checked, this one only has to survive the handshake.
159
+ #: Short-lived: the viewer's own grant was already checked, this one only has to survive the handshake.
172
160
  LIVE_RELAY_GRANT_MS = 60_000
173
- #: What a session export is: the session's sqlite file, as the store wrote it.
174
- EXPORT_CONTENT_TYPE = "application/vnd.sqlite3"
175
- #: How long one export upload or restore download may take.
176
161
  TRANSFER_TIMEOUT_S = 300.0
177
- #: The most a version bundle may weigh, compressed and extracted, before the
178
- #: host refuses it: the cache is one shared disk and a build's memory is the
179
- #: supervisor's.
162
+ #: Bounded because the cache is one shared disk and a build's memory is the supervisor's.
180
163
  DEFAULT_MAX_BUNDLE_MB = 2048
181
164
  MAX_BUNDLE_MEMBERS = 200_000
182
- #: The largest request body the host reads, on either plane. A body is held
183
- #: in memory whole (the seed rows, a tool call's args, a vendor route's
184
- #: payload), and the memory is the supervisor's, shared by every session on
185
- #: the replica; a client cannot be let size that allocation.
165
+ #: A body is held in memory whole, in the supervisor shared by every session: a client must not size that allocation.
186
166
  DEFAULT_MAX_BODY_MB = 32
187
167
 
188
168
 
@@ -270,16 +250,14 @@ def download_verified(url: str, sha256: str, dest: Path) -> Path:
270
250
  shutil.copyfileobj(r, out)
271
251
  except Exception as error: # noqa: BLE001 - name the stage in the message
272
252
  fail("host", f"could not download the session export: {error}")
273
- actual, _ = file_digest(staging)
274
- if actual != sha256.lower():
275
- fail("host", f"session export checksum mismatch: expected {sha256}, got {actual}")
253
+ refuse_digest_mismatch(staging, sha256)
276
254
  os.replace(staging, dest)
277
255
  finally:
278
256
  staging.unlink(missing_ok=True)
279
257
  return dest
280
258
 
281
259
 
282
- def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str = EXPORT_CONTENT_TYPE) -> None:
260
+ def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str) -> None:
283
261
  """PUT a file to a presigned URL, sending exactly the headers the platform
284
262
  signed for it: content type, length and the base64 sha256 the object store
285
263
  verifies on receipt."""
@@ -322,7 +300,7 @@ class CachedVersion:
322
300
  schema world stored as itself (``tools``: handlers, tasks and verifiers,
323
301
  sessions copied from its template — and ``spec`` + ``settings`` too when
324
302
  its tree carries connector.toml, the HTTP surface the same session serves
325
- over the same store). ``snapshot`` is set for an api bundle only."""
303
+ over the same store). ``snapshot`` and ``served`` are an api bundle's."""
326
304
 
327
305
  version_id: str
328
306
  bundle: Path
@@ -330,13 +308,12 @@ class CachedVersion:
330
308
  spec: Spec | None
331
309
  settings: ApiSettings | None
332
310
  snapshot: Path | None
333
- #: The world's own code, imported once per version — only in a process
334
- #: that runs handlers (a worker). None in the supervisor.
311
+ engine: type[WorldDatabase]
312
+ #: None in the supervisor: only a worker imports world-authored code.
335
313
  handlers: dict[str, Handler] | None = None
336
- #: The version's prebuilt static ui, when its manifest declares one.
337
314
  ui: UiSurface | None = None
338
- #: A mock-tools version; None for an api world.
339
315
  tools: ToolsVersion | None = None
316
+ served: snapshots.ServedSnapshot | None = None
340
317
 
341
318
  @property
342
319
  def runtime_class(self) -> type[WorldRuntime]:
@@ -361,9 +338,9 @@ class CachedVersion:
361
338
  def needs_worker(self) -> bool:
362
339
  return self.authored_code is not None
363
340
 
364
- def served_tools(self, dependencies: dict[str, DependencyWorld]) -> list[str]:
365
- """Every name a session task may allow."""
366
- return self.runtime_class.served_by(self, dependencies)
341
+ def served_names(self, dependencies: dict[str, DependencyWorld]) -> ServedNames:
342
+ """The tools a session task may allow, beside the routes it may not."""
343
+ return ServedNames.of(self.runtime_class.served_by(self, dependencies), self.spec)
367
344
 
368
345
  @property
369
346
  def declared_dependencies(self) -> dict[str, Dependency]:
@@ -379,15 +356,12 @@ class VersionCache:
379
356
  def __init__(self, root: Path, *, run_handlers: bool = False, max_bundle_mb: int = DEFAULT_MAX_BUNDLE_MB):
380
357
  self.root = Path(root)
381
358
  self.root.mkdir(parents=True, exist_ok=True)
382
- #: Whether this process imports a version's ``handlers.py``. Off in the
383
- #: supervisor, on in a version worker.
359
+ #: Off in the supervisor: only a version worker imports world-authored code.
384
360
  self.run_handlers = run_handlers
385
361
  self.max_bundle_bytes = max_bundle_mb * (1 << 20)
386
362
  self._lock = threading.Lock()
387
363
  self._versions: dict[str, CachedVersion] = {}
388
- #: One build at a time per version: the first open of a version does the
389
- #: download, concurrent opens of the same version wait for it.
390
- self._building: dict[str, threading.Lock] = {}
364
+ self._builds = Lanes()
391
365
 
392
366
  def ensure(
393
367
  self,
@@ -395,27 +369,20 @@ class VersionCache:
395
369
  bundle_url: str,
396
370
  snapshot: dict[str, str] | None,
397
371
  ) -> CachedVersion:
372
+ hit = self._cached(version_id)
373
+ if hit is not None:
374
+ return hit
375
+ with self._builds.turn(version_id):
376
+ return self._cached(version_id) or self._store(self._build(version_id, bundle_url, snapshot))
377
+
378
+ def _cached(self, version_id: str) -> CachedVersion | None:
398
379
  with self._lock:
399
- hit = self._versions.get(version_id)
400
- if hit is not None:
401
- return hit
402
- building = self._building.setdefault(version_id, threading.Lock())
403
- with building:
404
- with self._lock:
405
- hit = self._versions.get(version_id)
406
- if hit is not None:
407
- return hit
408
- try:
409
- cached = self._build(version_id, bundle_url, snapshot)
410
- with self._lock:
411
- self._versions[version_id] = cached
412
- return cached
413
- finally:
414
- # Success or failure, the build slot is over: a failed build
415
- # leaves nothing behind, and the next open of the version starts
416
- # a fresh one.
417
- with self._lock:
418
- self._building.pop(version_id, None)
380
+ return self._versions.get(version_id)
381
+
382
+ def _store(self, cached: CachedVersion) -> CachedVersion:
383
+ with self._lock:
384
+ self._versions[cached.version_id] = cached
385
+ return cached
419
386
 
420
387
  def has(self, version_id: str) -> bool:
421
388
  with self._lock:
@@ -433,9 +400,6 @@ class VersionCache:
433
400
  tools = load_tools_version(
434
401
  bundle, self.root / version_id / "template.db", snapshot, run_handlers=self.run_handlers
435
402
  )
436
- # A schema world stored as itself: its tools, and — when the tree
437
- # carries connector.toml — its HTTP surface from the same session,
438
- # plus the static ui that connector.toml's [ui] declares over it.
439
403
  return CachedVersion(
440
404
  version_id=version_id,
441
405
  bundle=bundle,
@@ -443,6 +407,7 @@ class VersionCache:
443
407
  spec=tools.spec,
444
408
  settings=tools.settings,
445
409
  snapshot=None,
410
+ engine=tools.engine,
446
411
  handlers=tools.api_handlers,
447
412
  ui=load_ui_surface(bundle) if tools.spec is not None else None,
448
413
  tools=tools,
@@ -451,14 +416,15 @@ class VersionCache:
451
416
  contract = check_bundle(tree)
452
417
  if snapshot:
453
418
  snapshots.fetch(tree, contract, snapshot["url"], snapshot["sha256"], snapshot["digest"])
419
+ served = snapshots.ServedSnapshot.of(tree)
454
420
  spec = load_spec(tree)
455
421
  settings = load_api_settings(tree, spec)
456
422
  handlers = load_handlers(settings) if self.run_handlers and settings.handlers is not None else None
457
- snap = snapshots.default_snapshot(tree)
423
+ snap = snapshots.default_snapshot(tree, contract)
458
424
  if not snap.is_file():
459
425
  fail(
460
426
  "host",
461
- f"version {version_id} has no compiled snapshot (db/state.sqlite); "
427
+ f"version {version_id} has no compiled snapshot ({snap.relative_to(tree)}); "
462
428
  "publish a data snapshot or pin one on the version",
463
429
  )
464
430
  return CachedVersion(
@@ -468,6 +434,8 @@ class VersionCache:
468
434
  spec=spec,
469
435
  settings=settings,
470
436
  snapshot=snap,
437
+ engine=WorldDatabase.for_contract(contract),
438
+ served=served,
471
439
  handlers=handlers,
472
440
  ui=load_ui_surface(bundle),
473
441
  )
@@ -493,7 +461,7 @@ class VersionCache:
493
461
  raise ValueError(f"the bundle is larger than {limit} bytes")
494
462
  out.write(chunk)
495
463
  except Exception as error: # noqa: BLE001 - name the stage in the message
496
- fail("host", f"could not download the bundle from {url}: {error}")
464
+ fail("host", f"could not download the bundle: {error}")
497
465
  staging.mkdir()
498
466
  with tarfile.open(tgz, "r:gz") as t:
499
467
  members = t.getmembers()
@@ -518,13 +486,14 @@ class Export:
518
486
  path: Path
519
487
  sha256: str
520
488
  bytes: int
489
+ content_type: str
521
490
 
522
491
  def describe(self) -> dict:
523
492
  return {
524
493
  "exportId": self.export_id,
525
494
  "sha256": self.sha256,
526
495
  "bytes": self.bytes,
527
- "contentType": EXPORT_CONTENT_TYPE,
496
+ "contentType": self.content_type,
528
497
  }
529
498
 
530
499
 
@@ -532,52 +501,29 @@ class Export:
532
501
  class Session:
533
502
  session_id: str
534
503
  version_id: str
535
- #: The bundled task (a ``scenarios/<task>`` of the version), or None for a
536
- #: session opened on a task of its own.
537
504
  task: str | None
538
- #: The connector spec of an api bundle, or of a schema world whose tree
539
- #: carries connector.toml; None for a tools-only tree, which has no http
540
- #: surface (its data plane is 404, its tools are ``call``).
541
505
  spec: Spec | None
542
506
  token: str | None
543
507
  bundle: Path
544
508
  tree: Path
545
- #: Unix time the lease runs out unless renewed.
546
509
  lease_until: float
547
- #: The world, when this process serves it (:class:`WorldRuntime`). None
548
- #: for a session placed on a worker, whose world lives in that process.
510
+ engine: type[WorldDatabase]
549
511
  runtime: WorldRuntime | None = None
550
- #: The version worker serving this session, or None for in-process.
551
512
  worker: Worker | None = None
552
- #: The version's static ui, served by the supervisor for this session.
553
513
  ui: UiSurface | None = None
554
- #: The pool browser leased for this session (:class:`BrowserRelay`), or
555
- #: None when the session has no browser surface. Swapped in place when
556
- #: the platform replaces a browser that died (:meth:`WorldHost.set_browser`).
557
514
  browser: BrowserRelay | None = None
558
- #: Requests inside the world right now. A session is only torn down once
559
- #: this reaches zero, so a close or an expiry never pulls the database out
560
- #: from under a handler mid-request.
515
+ #: Teardown waits for zero, so a close or expiry never pulls the database from under a handler.
561
516
  inflight: int = 0
562
- #: Set once the session has left the registry; the last request out closes
563
- #: the state.
517
+ #: Once set, the last request out closes the state.
564
518
  closing: bool = False
565
- #: Unix time the session was opened; its session-seconds are counted on close.
566
519
  opened_at: float = field(default_factory=time.time)
567
- #: Unix time of the last request that used the world: a data-plane call or
568
- #: a control operation (seed, reset, grade, call, state). A renewal or an
569
- #: export is the platform looking, not the session working, and does not
570
- #: move it. Reported on renew so the platform's idle clock follows traffic
571
- #: that never passes through it.
520
+ #: A renewal or an export is the platform looking, not the session working, and must not move it:
521
+ #: the platform's idle clock follows this.
572
522
  touched_at: float = field(default_factory=time.time)
573
- #: The last export taken and not yet uploaded, if any.
574
523
  export: Export | None = None
575
- #: Set when the session was opened from an export rather than the snapshot.
576
524
  restored: bool = False
577
- #: The task supplied at open, when the session has one instead of a
578
- #: bundled task: its seed is applied after the clone, its grader answers
579
- #: ``grade``, and it lives under ``<session>/task/`` (:mod:`tasks`).
580
525
  task_spec: TaskSpec | None = None
526
+ exporting: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
581
527
 
582
528
  @property
583
529
  def app(self) -> WorldApp | None:
@@ -622,45 +568,31 @@ class WorldHost:
622
568
  max_bundle_mb: int = DEFAULT_MAX_BUNDLE_MB,
623
569
  object_store: frozenset[str] | None = None,
624
570
  ):
625
- #: Where every presigned URL the control plane hands this host must
626
- #: point (bundle, snapshot, export upload, restore); None admits any.
571
+ #: Every presigned URL the control plane hands this host must point here; None admits any.
627
572
  self.object_store = object_store
628
573
  self.cache = VersionCache(
629
574
  versions_root or Path(cache_root) / "versions", run_handlers=run_handlers, max_bundle_mb=max_bundle_mb
630
575
  )
631
576
  self.sessions_root = Path(cache_root) / "sessions"
632
- # Sessions live in this process; whatever a previous one left on disk is
633
- # unreachable, so a start begins with an empty sessions tree.
577
+ # Sessions live in this process, so whatever a previous one left on disk is unreachable.
634
578
  shutil.rmtree(self.sessions_root, ignore_errors=True)
635
579
  self.sessions_root.mkdir(parents=True, exist_ok=True)
636
580
  self.lease_s = lease_s
637
- #: The address the platform pins a session to, so control calls reach
638
- #: this replica and not the Service's round-robin. None = one replica.
639
581
  self.advertise_url = advertise_url
640
582
  self.workers = workers
641
583
  self.run_handlers = run_handlers
642
584
  self.pinned_version = pinned_version
643
- #: The rlimits this process runs under (a worker's), for ``/healthz``.
644
585
  self.limits = limits
645
- #: Sessions this host admits before ``open`` answers 503 and the
646
- #: platform places elsewhere; the heartbeat advertises it as capacity.
647
586
  self.max_sessions = max_sessions
648
- #: Set on SIGTERM: no new sessions, existing ones served until they
649
- #: close or the drain grace runs out.
650
587
  self.draining = False
651
588
  self.started_at = time.time()
652
589
  self._lock = threading.Lock()
653
590
  self._sessions: dict[str, Session] = {}
654
- #: Ids of sessions being opened: each holds one of ``max_sessions`` from
655
- #: the moment its open is admitted, so concurrent opens cannot all pass
656
- #: the capacity check and land past the limit.
591
+ #: Each holds a slot from admission, so concurrent opens cannot all pass the capacity check.
657
592
  self._opening: set[str] = set()
658
- #: Opens the platform closed before they finished: it gave up waiting
659
- #: and told this host to forget the session, so the session is closed
660
- #: the moment it exists rather than held until its lease runs out.
593
+ #: Opens the platform closed before they finished: closed the moment they exist, not at lease end.
661
594
  self._abandoned: set[str] = set()
662
- #: Lifetime counts for ``/metrics``: opens, closes by reason, requests
663
- #: by surface, session-seconds of closed sessions.
595
+ self._opens = Lanes()
664
596
  self._counters: Counter[str] = Counter()
665
597
  self._session_seconds = 0.0
666
598
 
@@ -693,15 +625,13 @@ class WorldHost:
693
625
  with self._lock:
694
626
  existing = self._sessions.get(session_id)
695
627
  if existing is None:
696
- # A retry of an open this host already served is answered even
697
- # while draining: refusing it would send the platform to open
698
- # the same id elsewhere while this copy holds the live writes.
628
+ # A retry of an open already served is answered even while draining: refusing it would
629
+ # send the platform to open the same id elsewhere while this copy holds the live writes.
699
630
  if self.draining:
700
631
  fail("draining", "this host is draining and takes no new sessions")
701
632
  self._admit(session_id)
702
633
  if existing is not None:
703
- # The platform retried an open that already succeeded: the same
704
- # session is the answer, never a rebuild that drops its writes.
634
+ # A retried open gets the same session, never a rebuild that drops its writes.
705
635
  wanted = (version_id, (task, spec.raw if spec is not None else None), token)
706
636
  if (existing.version_id, existing.task_key, existing.token) != wanted:
707
637
  fail("host", f"session {session_id} is already open as another version, task or token")
@@ -749,38 +679,26 @@ class WorldHost:
749
679
  ) -> dict:
750
680
  cached = self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
751
681
  dependencies = self._dependency_worlds(cached, deps)
752
- # A session task runs on either shape the host serves: an api bundle
753
- # clones its snapshot and grades by the spec; a schema world copies its
754
- # template and grades by the spec too, else with its bundled verifiers
755
- # (:meth:`_grade`). Its allow-list may name a tool or, on a tree
756
- # with connector.toml, an operation.
757
682
  if cached.spec is not None:
758
683
  unsupported = unsupported_auth(cached.spec)
759
684
  if unsupported:
760
685
  fail("host", unsupported)
761
686
  if spec is not None:
762
- self._check_task_tools(spec, cached.served_tools(dependencies))
687
+ cached.served_names(dependencies).check_allowed(spec.tools)
763
688
  relay = BrowserRelay.parse(browser)
764
689
  if cached.needs_worker and not self.run_handlers:
765
- if self.workers is None:
766
- fail(
767
- "host",
768
- f"version {version_id} runs world-authored code ({cached.authored_code}); "
769
- "this host runs none in its process and has no version workers",
770
- )
771
- return self._open_on_worker(
772
- cached, session_id, bundle_url, task, spec, token, relay, restore, deps
773
- )
690
+ return self._open_on_worker(cached, session_id, bundle_url, task, spec, token, relay, restore, deps)
774
691
  session_dir = self.sessions_root / session_id
775
- runtime = WorldRuntime.open(
776
- cached,
777
- session_dir,
778
- task=task,
779
- spec=spec,
780
- token=token,
781
- dependencies=dependencies,
782
- restore=lambda load: self._restore_into(restore, session_dir, load),
783
- )
692
+ with self._opens.turn(version_id):
693
+ runtime = WorldRuntime.open(
694
+ cached,
695
+ session_dir,
696
+ task=task,
697
+ spec=spec,
698
+ token=token,
699
+ dependencies=dependencies,
700
+ restore=lambda load: self._restore_into(restore, session_dir, load, cached.engine),
701
+ )
784
702
  session = Session(
785
703
  session_id=session_id,
786
704
  version_id=version_id,
@@ -790,6 +708,7 @@ class WorldHost:
790
708
  bundle=cached.bundle,
791
709
  tree=cached.tree,
792
710
  lease_until=time.time() + self.lease_s,
711
+ engine=cached.engine,
793
712
  runtime=runtime,
794
713
  ui=cached.ui,
795
714
  browser=relay,
@@ -816,38 +735,44 @@ class WorldHost:
816
735
  is on disk), and the supervisor records only where it went. The ui's
817
736
  static files and the browser tunnel stay the supervisor's; the ui's
818
737
  api-prefix calls are relayed as they came, so the worker logs them
819
- ``via: ui``. An export to restore from is fetched
820
- and verified here too, then handed to the worker as a local file.
738
+ ``via: ui``. An export to restore from is fetched and verified here
739
+ too, then handed to the worker as a local file with its sha256, which
740
+ the worker checks again before it opens the file.
821
741
  A worker every one of whose peers holds sessions cannot be started
822
742
  past the pool's memory budget: that is ``at_capacity``, and the
823
743
  platform places the session on another replica."""
824
- assert self.workers is not None
744
+ if self.workers is None:
745
+ fail(
746
+ "host",
747
+ f"version {cached.version_id} runs world-authored code ({cached.authored_code}); "
748
+ "this host runs none in its process and has no version workers",
749
+ )
825
750
  try:
826
751
  worker = self.workers.get(cached.version_id)
827
752
  except WorkerCapacity as error:
828
753
  fail("at_capacity", str(error))
829
- # The session is the worker's from here, so another version's open
830
- # cannot stop this worker as session-less while it is being placed.
754
+ # Claimed before placement, so another open cannot stop this worker as session-less meanwhile.
831
755
  with self._lock:
832
756
  worker.sessions.add(session_id)
833
757
  source = None
834
758
  try:
835
759
  source = self._restore_source(restore, self._worker_session_dir(worker, session_id))
836
- self._worker_control(
837
- worker,
838
- "POST",
839
- "/__host/sessions",
840
- {
841
- "sessionId": session_id,
842
- "versionId": cached.version_id,
843
- "bundleUrl": bundle_url,
844
- "task": task,
845
- "taskSpec": spec.raw if spec is not None else None,
846
- "token": token,
847
- "restore": {"path": str(source)} if source is not None else None,
848
- "dependencies": [dep.raw for dep in deps],
849
- },
850
- )
760
+ with self._opens.turn(cached.version_id):
761
+ self._worker_control(
762
+ worker,
763
+ "POST",
764
+ "/__host/sessions",
765
+ {
766
+ "sessionId": session_id,
767
+ "versionId": cached.version_id,
768
+ "bundleUrl": bundle_url,
769
+ "task": task,
770
+ "taskSpec": spec.raw if spec is not None else None,
771
+ "token": token,
772
+ "restore": source.for_worker() if source is not None else None,
773
+ "dependencies": [dep.raw for dep in deps],
774
+ },
775
+ )
851
776
  except BaseException:
852
777
  with self._lock:
853
778
  worker.sessions.discard(session_id)
@@ -856,7 +781,7 @@ class WorldHost:
856
781
  raise
857
782
  finally:
858
783
  if source is not None:
859
- source.unlink(missing_ok=True)
784
+ source.path.unlink(missing_ok=True)
860
785
  session = Session(
861
786
  session_id=session_id,
862
787
  version_id=cached.version_id,
@@ -866,6 +791,7 @@ class WorldHost:
866
791
  bundle=cached.bundle,
867
792
  tree=cached.tree,
868
793
  lease_until=time.time() + self.lease_s,
794
+ engine=cached.engine,
869
795
  worker=worker,
870
796
  ui=cached.ui,
871
797
  browser=relay,
@@ -881,40 +807,52 @@ class WorldHost:
881
807
  assert self.workers is not None
882
808
  return self.workers.root / "workers" / worker.version_id / "sessions" / session_id
883
809
 
884
- def _restore_into(self, restore: dict[str, str] | None, session_dir: Path, load: Callable[[Path], None]) -> bool:
885
- """Load the export ``restore`` names into a freshly opened world, then
886
- drop the fetched file. False when there was nothing to restore."""
810
+ def _restore_into(
811
+ self,
812
+ restore: dict[str, str] | None,
813
+ session_dir: Path,
814
+ load: Callable[[SessionExport], None],
815
+ engine: type[WorldDatabase],
816
+ ) -> bool:
817
+ """Load the export ``restore`` names into a freshly opened world, its
818
+ bytes checked against the recorded sha256 here, where they are opened,
819
+ then drop the fetched file. False when there was nothing to restore."""
887
820
  source = self._restore_source(restore, session_dir)
888
821
  if source is None:
889
822
  return False
890
823
  try:
891
- load(source)
824
+ load(SessionExport.verified(source, engine))
892
825
  finally:
893
- source.unlink(missing_ok=True)
826
+ source.path.unlink(missing_ok=True)
894
827
  return True
895
828
 
896
- def _restore_source(self, restore: dict[str, str] | None, session_dir: Path) -> Path | None:
897
- """The export a session continues from, as a local file, or None for a
898
- fresh session. The platform names it by ``{url, sha256}`` and the file is
899
- fetched into the session's directory and verified; a supervisor names it
900
- to its worker by ``{path}``, already verified, and only the supervisor
901
- reaches a worker's control socket."""
829
+ def _restore_source(self, restore: dict[str, str] | None, session_dir: Path) -> ExportFile | None:
830
+ """The export a session continues from, as a local file and the sha256
831
+ the platform recorded for it, or None for a fresh session. The platform
832
+ names it by ``{url, sha256}`` and the file is fetched into the session's
833
+ directory and verified; a supervisor names it to its worker by ``{path,
834
+ sha256}``, and only the supervisor reaches a worker's control socket."""
902
835
  if not restore:
903
836
  return None
904
837
  path = restore.get("path")
905
838
  if path is not None:
906
- if not self.run_handlers:
907
- fail("host", "restore by path is a worker's; name the export by {url, sha256}")
908
- source = Path(path)
909
- if not source.is_file():
910
- fail("host", f"restore file {path} is missing")
911
- return source
839
+ return self._worker_restore_source(Path(path), restore.get("sha256"))
912
840
  url, sha256 = restore.get("url"), restore.get("sha256")
913
841
  if not isinstance(url, str) or not isinstance(sha256, str) or len(sha256) != 64:
914
842
  fail("host", "restore must be {url: <presigned export url>, sha256: <hex digest>}")
915
843
  raise AssertionError # fail() never returns
916
844
  check_object_store_url(url, self.object_store, "restore.url")
917
- return download_verified(url, sha256, session_dir / "restore.sqlite")
845
+ return ExportFile(download_verified(url, sha256, session_dir / "restore.db"), sha256)
846
+
847
+ def _worker_restore_source(self, path: Path, sha256: object) -> ExportFile:
848
+ if not self.run_handlers:
849
+ fail("host", "restore by path is a worker's; name the export by {url, sha256}")
850
+ if not path.is_file():
851
+ fail("host", f"restore file {path} is missing")
852
+ if not isinstance(sha256, str) or len(sha256) != 64:
853
+ fail("host", "restore by path names the export's sha256 beside it")
854
+ raise AssertionError # fail() never returns
855
+ return ExportFile(path, sha256)
918
856
 
919
857
  def _trusted_version(self, bundle_url: str, snapshot: dict[str, str] | None) -> tuple[str, dict[str, str] | None]:
920
858
  check_object_store_url(bundle_url, self.object_store, "bundleUrl")
@@ -985,19 +923,19 @@ class WorldHost:
985
923
  return {"sessionId": session_id, "browser": True}
986
924
 
987
925
  def export(self, session_id: str, known_sha256: str | None = None) -> dict:
988
- """Copy the session's state to a file on this host and hash it. The copy
989
- is consistent (sqlite's online backup under the store's lock) and waits
990
- for :meth:`upload_export`; taking a new one discards the last. A copy
991
- that hashes to ``known_sha256`` (the platform's last export of the
926
+ """Copy the session's state to a file on this host and hash it, one export of
927
+ a session at a time; it waits for :meth:`upload_export`, and a new one discards
928
+ the last. A copy hashing to ``known_sha256`` (the platform's last export of the
992
929
  session) is thrown away and reported ``unchanged``: nothing to upload."""
993
- with self.using(session_id, touch=False) as session:
930
+ with self.using(session_id, touch=False) as session, session.exporting:
931
+ engine = session.engine
994
932
  if session.worker is not None:
995
933
  answer = self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/export", {})
996
934
  path = self._worker_export_path(session, answer)
997
935
  else:
998
936
  exports = self.sessions_root / session_id / "exports"
999
937
  shutil.rmtree(exports, ignore_errors=True)
1000
- path = exports / f"{uuid.uuid4().hex}.sqlite"
938
+ path = exports / f"{uuid.uuid4().hex}{Path(engine.snapshot_name).suffix}"
1001
939
  assert session.runtime is not None
1002
940
  session.runtime.export(path)
1003
941
  sha256, size = file_digest(path)
@@ -1007,7 +945,7 @@ class WorldHost:
1007
945
  session.export = None
1008
946
  self._counters["exports_unchanged"] += 1
1009
947
  return {"exportId": None, "sha256": sha256, "bytes": size, "unchanged": True}
1010
- export = Export(export_id=path.stem, path=path, sha256=sha256, bytes=size)
948
+ export = Export(export_id=path.stem, path=path, sha256=sha256, bytes=size, content_type=engine.content_type)
1011
949
  with self._lock:
1012
950
  session.export = export
1013
951
  self._counters["exports"] += 1
@@ -1040,7 +978,7 @@ class WorldHost:
1040
978
  if export is None or export.export_id != export_id:
1041
979
  fail("host", f"no export {export_id} for session {session_id}; take one first")
1042
980
  raise AssertionError # fail() never returns
1043
- upload_file(url, export.path, export.sha256, export.bytes)
981
+ upload_file(url, export.path, export.sha256, export.bytes, export.content_type)
1044
982
  export.path.unlink(missing_ok=True)
1045
983
  with self._lock:
1046
984
  session.export = None
@@ -1243,24 +1181,9 @@ class WorldHost:
1243
1181
  fail("host", f"dependency '{ref.alias}' ({ref.version_id}) is an api bundle, not a schema world")
1244
1182
  raise AssertionError # fail() never returns
1245
1183
  worlds[ref.alias] = DependencyWorld.of(dependency, dep.tools)
1246
- cached.served_tools(worlds) # refuses a root tool that reads as a dependency's
1184
+ cached.served_names(worlds) # refuses a root tool that reads as a dependency's
1247
1185
  return worlds
1248
1186
 
1249
- @staticmethod
1250
- def _check_task_tools(spec: TaskSpec, served_tools: Iterable[str]) -> None:
1251
- """A task's allow-list names tools the world serves, every one of them:
1252
- a misspelt name would narrow the list without anyone noticing. The
1253
- served tools are what :meth:`CachedVersion.served_tools` lists."""
1254
- served_tools = list(served_tools)
1255
- unknown = unknown_task_tools(spec, served_tools)
1256
- if unknown:
1257
- served = ", ".join(sorted(served_tools)) or "none"
1258
- fail(
1259
- "task",
1260
- f"the task allows {', '.join(unknown)}, which this world does not serve; its tools are {served}",
1261
- "/task/tools",
1262
- )
1263
-
1264
1187
  @contextmanager
1265
1188
  def using(self, session_id: str, *, touch: bool = True) -> Iterator[Session]:
1266
1189
  """The session for the duration of one request: its lease renewed (any
@@ -1337,9 +1260,8 @@ class WorldHost:
1337
1260
  return self._verb(session_id, "POST", "grade", body, lambda runtime: runtime.grade(report, context))
1338
1261
 
1339
1262
  def call(self, session_id: str, tool: str, args: dict) -> dict:
1340
- """Invoke one of the world's tools or vendor routes by name, in process.
1341
- A route's arg shape mirrors the runner's ``execute_route``: ``path``/
1342
- ``query``/``body``, or leftover top-level keys as the body."""
1263
+ """One of the session's declared tools by name, a dependency's as
1264
+ ``alias.tool``; a route's name is refused (routes answer over HTTP)."""
1343
1265
  with self.using(session_id) as session:
1344
1266
  if session.worker is not None:
1345
1267
  return self._control(session, "POST", "call", {"tool": tool, "args": args})
@@ -1347,9 +1269,7 @@ class WorldHost:
1347
1269
  return session.runtime.call(tool, args)
1348
1270
 
1349
1271
 
1350
- #: The session protocol (:data:`verbs.SESSION_VERBS`) bound to the host's
1351
- #: operations, by route. Every row of the table is served: the local session
1352
- #: (``local.py``) binds the same rows to its own, so the two cannot drift.
1272
+ #: ``local.py`` binds the same rows to its own operations, so the two cannot drift.
1353
1273
  HOSTED_OPERATIONS: dict[str, Callable[..., dict]] = {
1354
1274
  "GET tools": WorldHost.tools,
1355
1275
  "GET task": WorldHost.task,
@@ -1393,9 +1313,7 @@ def session_from_host(host_header: str | None) -> tuple[str, str] | None:
1393
1313
  return rest, "ui"
1394
1314
 
1395
1315
 
1396
- #: Auth schemes the host can present a world's own credential for. Everything
1397
- #: in ``connector.SCHEMES`` is here; the list is explicit so a new scheme is
1398
- #: refused at open rather than admitted with no credential.
1316
+ #: Explicit so a new ``connector.SCHEMES`` entry is refused at open rather than admitted with no credential.
1399
1317
  SUPPORTED_AUTH_SCHEMES = ("none", "header", "bearer", "basic", "query", "oauth2")
1400
1318
 
1401
1319
 
@@ -1453,10 +1371,7 @@ def admits(session: Session, path: str, headers: dict[str, str]) -> str | None:
1453
1371
  if bearer is not None and hmac.compare_digest(bearer, session.token):
1454
1372
  return "session"
1455
1373
  if session.spec is not None and vendor_shaped_token(session.spec, headers, session.token):
1456
- # The vendor's own wire shape carrying the session token: a client
1457
- # written against the real vendor (`x-api-key: …`, a Basic user) works
1458
- # unchanged with the session token as its key. The same secret as the
1459
- # bearer, in the header the world declares — never in the URL.
1374
+ # The session token in the vendor's own header shape, never in the URL.
1460
1375
  return "session"
1461
1376
  if session.spec is not None and session.spec.scheme == "oauth2":
1462
1377
  if session.app is None:
@@ -1596,10 +1511,8 @@ def make_host_handler(
1596
1511
 
1597
1512
  def _dispatch(self, method: str) -> None:
1598
1513
  url = urllib.parse.urlsplit(self.path)
1599
- # The public side is whatever arrives under the worlds domain. It
1600
- # gets sessions and nothing about the host: the probes' answer is
1601
- # a bare ok, the counters and the rest live on the pod address
1602
- # (prometheus) or behind the control-plane secret (/__host/stats).
1514
+ # The public worlds domain learns nothing about the host: probes get a bare ok, counters
1515
+ # stay on the pod address or behind the control-plane secret.
1603
1516
  if url.path == "/healthz":
1604
1517
  return self._reply(200, {"ok": True})
1605
1518
  if url.path == "/metrics" and not public_host(self.headers.get("Host"), worlds_domain):
@@ -1616,6 +1529,9 @@ def make_host_handler(
1616
1529
  # request: answer and hang up.
1617
1530
  self.close_connection = True
1618
1531
  return self._reply(refused.status, {"error": refused.error}, {"Connection": "close"})
1532
+ except Exception as error:
1533
+ log_request_failure(error, method, url.path)
1534
+ return self._reply(500, request_failure_body(error))
1619
1535
 
1620
1536
  def _control(self, method: str, url) -> None:
1621
1537
  if not hmac.compare_digest(self.headers.get("X-Host-Secret") or "", secret):
@@ -1627,7 +1543,7 @@ def make_host_handler(
1627
1543
  return self._reply(400, {"error": "malformed json", "detail": str(error)})
1628
1544
  if not isinstance(body, dict):
1629
1545
  return self._reply(400, {"error": "malformed json", "detail": "the body must be a json object"})
1630
- parts = url.path.strip("/").split("/") # __host, sessions, [sid], [verb]
1546
+ parts = url.path.strip("/").split("/")
1631
1547
  try:
1632
1548
  if method == "GET" and parts == ["__host", "stats"]:
1633
1549
  return self._reply(200, host.stats())
@@ -1672,14 +1588,11 @@ def make_host_handler(
1672
1588
  return self._reply(
1673
1589
  404, unknown_verb(method, verb, hosted=True, prefix=f"/__host/sessions/{sid}/")
1674
1590
  )
1675
- return self._reply(200, HOSTED_OPERATIONS[row.route](host, sid, **row.read(body)))
1591
+ return self._reply(200, carried(HOSTED_OPERATIONS[row.route](host, sid, **row.read(body))))
1676
1592
  return self._reply(404, {"error": "unknown control route"})
1677
1593
  except ContractError as error:
1678
1594
  code = error.detail.get("code", "host")
1679
- # A host that will not take the session is not a bad request:
1680
- # the platform places it on another replica. A session this
1681
- # host does not hold is the one answer the platform may read
1682
- # as "lost"; every other refusal is about the request.
1595
+ # 503 sends the platform to another replica; 404 is the one answer it reads as "lost".
1683
1596
  if code in ("draining", "at_capacity"):
1684
1597
  status = 503
1685
1598
  elif code == UNKNOWN_SESSION:
@@ -1701,9 +1614,7 @@ def make_host_handler(
1701
1614
  return self._reply(404, {"error": "no session named by Host"})
1702
1615
  sid, surface = named
1703
1616
  if not host.owns(sid):
1704
- # Another host owns it (or it is closed). Proxy one hop when the
1705
- # platform can point us at the owner; a request that already
1706
- # hopped once is not sent on again.
1617
+ # Proxy at most one hop: a request that already hopped is not sent on again.
1707
1618
  hopped = HOP_HEADER in headers
1708
1619
  owner = owner_lookup(sid) if owner_lookup and not hopped else None
1709
1620
  if owner and owner_lookup:
@@ -1763,8 +1674,7 @@ def make_host_handler(
1763
1674
  world_headers = {**headers, **credential_headers}
1764
1675
  target = with_query(target, credential_query)
1765
1676
  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)
1767
- self._reply(status, body, extra)
1677
+ self._reply(*session.app.handle(method, target, world_headers, raw, default_host, via=via))
1768
1678
 
1769
1679
  def _serve_ui(self, session: Session, method: str, url, headers: dict[str, str]) -> None:
1770
1680
  ui = session.ui
@@ -1986,8 +1896,6 @@ class HostServer(ThreadingHTTPServer):
1986
1896
  super().__init__(address, handler)
1987
1897
  self.world_host = world_host
1988
1898
  self.lease_sweeper = start_lease_sweeper(world_host)
1989
- #: ``(platform url, secret)`` to report to; None runs unregistered (one
1990
- #: replica behind WORLDS_HOST_URL needs no registry).
1991
1899
  self.heartbeat = start_heartbeat(world_host, *heartbeat, interval_s=heartbeat_s) if heartbeat else None
1992
1900
  self.drain_s = drain_s
1993
1901