@withgateway/sdk 0.3.3 → 0.6.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 (158) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +3005 -1401
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2996 -1392
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +128 -37
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +126 -35
  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-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  19. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  20. package/dist/index.d.mts +4 -4
  21. package/dist/index.d.ts +4 -4
  22. package/dist/index.js +1078 -260
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +1040 -251
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/replay/index.d.mts +1 -1
  27. package/dist/replay/index.d.ts +1 -1
  28. package/dist/replay/index.js.map +1 -1
  29. package/dist/replay/index.mjs.map +1 -1
  30. package/dist/traces/index.js +125 -34
  31. package/dist/traces/index.js.map +1 -1
  32. package/dist/traces/index.mjs +123 -32
  33. package/dist/traces/index.mjs.map +1 -1
  34. package/dist/tracing/index.d.mts +1 -1
  35. package/dist/tracing/index.d.ts +1 -1
  36. package/dist/tracing/index.js +7 -1
  37. package/dist/tracing/index.js.map +1 -1
  38. package/dist/tracing/index.mjs +7 -1
  39. package/dist/tracing/index.mjs.map +1 -1
  40. package/dist/worlds/index.d.mts +819 -438
  41. package/dist/worlds/index.d.ts +819 -438
  42. package/dist/worlds/index.js +912 -236
  43. package/dist/worlds/index.js.map +1 -1
  44. package/dist/worlds/index.mjs +908 -232
  45. package/dist/worlds/index.mjs.map +1 -1
  46. package/package.json +1 -1
  47. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  48. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  49. package/runtime/gatewaysdk/environment/_world.py +82 -66
  50. package/runtime/gatewaysdk/environment/backing.py +20 -24
  51. package/runtime/gatewaysdk/environment/core.py +1 -16
  52. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  53. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  54. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  55. package/runtime/gatewaysdk/environment/schema/api.py +198 -474
  56. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  57. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  58. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  59. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  60. package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
  61. package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
  62. package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
  63. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  64. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  65. package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
  66. package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
  67. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  68. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  69. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  70. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
  71. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  72. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  75. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  76. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  77. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  78. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  81. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  82. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  83. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  84. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  85. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  87. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  88. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  89. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  90. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  91. package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
  92. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  93. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  94. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  95. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  96. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  97. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
  99. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
  112. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  113. package/runtime/gatewaysdk/environment/schema/local.py +32 -116
  114. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  115. package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
  116. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  117. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  118. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  119. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  120. package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
  121. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  122. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  123. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  124. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  125. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  126. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  127. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
  128. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  129. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
  130. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
  131. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  132. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
  133. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  134. package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
  135. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  136. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  137. package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
  138. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  139. package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
  140. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  141. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  142. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  143. package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
  144. package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
  145. package/runtime/gatewaysdk/environment/world.py +1 -1
  146. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  147. package/skills/agents/connector-template-author.md +5 -1
  148. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  149. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  150. package/skills/connector-schema-authoring/SKILL.md +50 -28
  151. package/skills/connector-schema-authoring/connector-worlds.md +282 -18
  152. package/skills/connector-schema-authoring/world-schema.md +7 -6
  153. package/skills/world-data-ingestion/ROWS.md +12 -8
  154. package/skills/world-data-ingestion/SKILL.md +20 -22
  155. package/skills/worlds-getting-started/SKILL.md +25 -25
  156. package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  157. package/skills/worlds-getting-started/references/gotchas.md +71 -7
  158. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -92,12 +92,10 @@ beside the vendor routes to its admin token only; a World Host session answers n
92
92
 
93
93
  from __future__ import annotations
94
94
 
95
- import base64
96
95
  import importlib.util
97
96
  import json
98
97
  import os
99
98
  import re
100
- import secrets
101
99
  import shutil
102
100
  import sys
103
101
  import tempfile
@@ -108,7 +106,8 @@ import uuid
108
106
  from contextlib import contextmanager
109
107
  from dataclasses import dataclass, field
110
108
  from datetime import datetime, timezone
111
- from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
109
+ from functools import partial
110
+ from http.server import ThreadingHTTPServer
112
111
  from pathlib import Path
113
112
  from typing import Any, Callable, Iterator
114
113
 
@@ -116,16 +115,22 @@ from .._toml import tomllib
116
115
  from . import snapshot as snapshots
117
116
  from .admin_routes import ADMIN, RUNNER_PATHS, AdminToken
118
117
  from .bundle_runtime import stage_runtime_package
118
+ from .call_capture import Served, WorldRequestHandler, send_response
119
119
  from .call_log import AnswerShape, CallLog, Via
120
+ from .webhooks import WebhookOutbox, Webhooks
120
121
  from .compiler import check_bundle, compile_bundle
121
- from .connector import DEFAULT_TOKEN_PATH, SPEC, Operation, Spec, load_spec, stored_forms
122
- from .credentials import basic_user
122
+ from .connector import SPEC, Operation, Spec, load_spec, stored_forms
123
+ from .cors import Cors
123
124
  from .database import WorldDatabase
124
- from .database.matching import RowMatch, dig
125
- from .envelope import Paging, page_headers, paginate, single, wrap
125
+ from .database.matching import RowMatch
126
+ from .declared_routes import DeclaredRoute, MisdeclaredRoute
127
+ from .door import Door, Entry
128
+ from .envelope import PageLink, Paging, page_headers, paginate, wrap
126
129
  from .grading import keyed_entities
127
- from .handler_errors import handled_answer, normalize_answer
130
+ from .handler_errors import handled_answer, handler_bug_body, log_contract_refusal, normalize_answer
128
131
  from .primary_key import PrimaryKey
132
+ from .request_body import RequestBody, Upload, json_value
133
+ from .route_miss import RouteMiss, served_methods
129
134
  from .validation import ContractError, fail, read_json
130
135
 
131
136
  EVENT_LOG_SIZE = 500
@@ -181,9 +186,12 @@ class ApiSettings:
181
186
  unauthorized: Any
182
187
  not_found: Any
183
188
  unauthorized_status: int = 401
189
+ unauthorized_declared: bool = False
184
190
  not_found_status: int = 404
185
191
  invalid: Any = None
186
192
  invalid_status: int = 400
193
+ wrong_method: Any = None
194
+ wrong_method_status: int = 405
187
195
  error_content_type: str = "application/json"
188
196
  hits_key: str = "hits"
189
197
  cursor_key: str = "cursor"
@@ -191,6 +199,8 @@ class ApiSettings:
191
199
  previous_key: str | None = None
192
200
  page_headers: dict[str, str] = field(default_factory=dict)
193
201
  page_links: bool = False
202
+ link_header: bool = False
203
+ cors: Cors = field(default_factory=Cors)
194
204
  paging: Paging = field(default_factory=Paging)
195
205
  token_path: str | None = None
196
206
  handlers: Path | None = None
@@ -400,7 +410,6 @@ def operation_api_settings(entry: dict, operation: Operation, location: str) ->
400
410
  )
401
411
 
402
412
 
403
- # Every pusher drops these at any depth, so a ui built under one never reaches the hub: refused here.
404
413
  ARCHIVE_DROPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
405
414
 
406
415
 
@@ -456,10 +465,6 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
456
465
  token_path = api.get("token_path")
457
466
  if token_path is not None and (not isinstance(token_path, str) or not token_path.startswith("/")):
458
467
  fail("spec", "api.token_path is the path the world mints tokens on", "/api/token_path")
459
- if token_path is not None and spec.scheme != "oauth2":
460
- fail("spec", "api.token_path belongs to auth.scheme oauth2", "/api/token_path")
461
- if spec.scheme == "oauth2" and token_path is None:
462
- token_path = spec.token_url if (spec.token_url or "").startswith("/") else DEFAULT_TOKEN_PATH
463
468
  handlers_name = api.get("handlers")
464
469
  if handlers_name is not None and not isinstance(handlers_name, str):
465
470
  fail("spec", "api.handlers is the path of the world's handlers module", "/api/handlers")
@@ -487,9 +492,12 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
487
492
  unauthorized=_json_body(api, "unauthorized", {"error": "unauthorized"}, "/api"),
488
493
  not_found=_json_body(api, "not_found", {"error": "not_found"}, "/api"),
489
494
  unauthorized_status=_status(api, "unauthorized_status", 401, "/api", low=400, high=599),
495
+ unauthorized_declared="unauthorized" in api or "unauthorized_status" in api,
490
496
  not_found_status=_status(api, "not_found_status", 404, "/api", low=400, high=599),
491
497
  invalid=_json_body(api, "invalid", {"error": "invalid"}, "/api"),
492
498
  invalid_status=_status(api, "invalid_status", 400, "/api", low=400, high=599),
499
+ wrong_method=_json_body(api, "wrong_method", None, "/api"),
500
+ wrong_method_status=_status(api, "wrong_method_status", 405, "/api", low=400, high=599),
493
501
  error_content_type=_name(api, "error_content_type", "application/json", "/api"),
494
502
  hits_key=_key_name(api, "hits_key", "hits"),
495
503
  cursor_key=_name(api, "cursor_key", "cursor", "/api"),
@@ -497,8 +505,10 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
497
505
  previous_key=_name(api, "previous_key", "", "/api") if api.get("previous_key") is not None else None,
498
506
  page_headers=_page_headers(api),
499
507
  page_links=_flag(api, "page_links", "/api"),
508
+ link_header=_flag(api, "link_header", "/api"),
509
+ cors=Cors.of(_flag(api, "cors", "/api"), served_methods(spec.operations.values())),
500
510
  paging=paging,
501
- token_path=token_path,
511
+ token_path=spec.auth.token_path(token_path, spec.operations, "/api"),
502
512
  handlers=handlers if handlers.is_file() else None,
503
513
  before=before,
504
514
  operations=operations,
@@ -520,11 +530,12 @@ class WorldState:
520
530
  self.world = world
521
531
  self.contract = served.contract
522
532
  self._initial: dict | None = None
523
- self._snapshot_path = snapshots.default_snapshot(world, self.contract)
533
+ self._snapshot_path = served.path
524
534
  self.snapshot: dict | None = served.sidecar
525
535
  self._dir = tempfile.TemporaryDirectory(prefix="gateway-world-api-")
526
536
  self._lock = threading.RLock()
527
537
  self.store: WorldDatabase | None = None
538
+ self.webhooks = WebhookOutbox(None, self.rows, self.key_of, ApiContext.clock)
528
539
  self._clear_events()
529
540
  self.reset()
530
541
 
@@ -548,8 +559,15 @@ class WorldState:
548
559
  collide on every key)."""
549
560
  with self._lock:
550
561
  self._clear_events()
562
+ self.webhooks.clear()
551
563
  self._open(self._snapshot_path if initial and self.snapshot else None, initial=initial)
552
564
 
565
+ def serve_webhooks(self, webhooks: Webhooks | None) -> None:
566
+ """Deliveries this state's handlers stage go to the subscriptions ``webhooks`` declares."""
567
+ if webhooks is not None:
568
+ webhooks.check_contract(self.contract.entities)
569
+ self.webhooks = WebhookOutbox(webhooks, self.rows, self.key_of, ApiContext.clock)
570
+
553
571
  def _clear_events(self) -> None:
554
572
  self._events: list[dict] = []
555
573
  self.event_seq = 0
@@ -692,14 +710,19 @@ class WorldState:
692
710
  assert self.store is not None
693
711
  return self.store.get(entity, key)
694
712
 
713
+ def select(self, entity: str, match: RowMatch, limit: int | None, offset: int) -> tuple[list[dict], int]:
714
+ with self._lock:
715
+ assert self.store is not None
716
+ return self.store.select(entity, match, limit, offset)
717
+
695
718
  @contextmanager
696
719
  def transaction(self) -> Iterator[None]:
697
- """One route call: its writes and events all land, or none do."""
720
+ """One route call: its writes, events and deliveries all land, or none do."""
698
721
  with self._lock:
699
722
  assert self.store is not None
700
723
  events, seq = list(self._events), self.event_seq
701
724
  try:
702
- with self.store.transaction():
725
+ with self.webhooks.transaction(), self.store.transaction():
703
726
  yield
704
727
  except BaseException:
705
728
  self._events, self.event_seq = events, seq
@@ -745,182 +768,68 @@ class WorldState:
745
768
  self._dir.cleanup()
746
769
 
747
770
 
748
- def _segment_filter(operation: Operation, ctx: ApiContext, entity: str) -> dict[str, str]:
749
- """The filter a route with no ``filter`` of its own implies: each ``{segment}`` of its
750
- path that names a top-level field of its entity narrows to the rows carrying that value
751
- (``GET /wallets/{id}``, ``GET /records/by-email/{email}``). A segment naming no field
752
- (``/users/{userId}/labels``, a scope the caller must send) implies nothing; a declared
753
- ``filter`` says it all itself. Twin: ``route_bindings.implied_filters``."""
754
- fields = ctx.fields_of(entity)
755
- return {name: name for name in operation.placeholders if name in fields}
756
-
757
-
758
- def _query_field_filter(ctx: ApiContext, entity: str, sent: dict[str, list[str]]) -> dict[str, str]:
759
- """What a read route with no ``filter`` implies from its query string: each
760
- parameter that names a top-level field of the entity narrows to rows carrying
761
- that value (``GET /accounts?status=frozen``), the way every vendor's list
762
- endpoint reads. Paging parameters and names the entity does not declare are
763
- left to the pager and the handler."""
764
- fields = ctx.fields_of(entity)
765
- paging = {ctx.settings.paging.limit_param, ctx.settings.paging.offset_param, ctx.settings.paging.cursor_param}
766
- return {name: name for name in sent if name in fields and name not in paging}
767
-
768
-
769
771
  class Router:
772
+ """The routes of connector.toml, matched against a request."""
773
+
770
774
  def __init__(self, spec: Spec, settings: ApiSettings):
771
775
  self.spec = spec
772
776
  self.settings = settings
773
- self.routes = [(operation, self._pattern(operation)) for operation in spec.operations.values()]
774
- self.tokens: set[str] = set()
775
- self._refresh_tokens: dict[str, str] = {}
776
- self._jwt_secret = secrets.token_bytes(32)
777
- self._lock = threading.Lock()
778
-
779
- @staticmethod
780
- def _pattern(operation: Operation) -> re.Pattern:
781
- escaped = re.escape(operation.path)
782
- pattern = re.sub(r"\\\{([A-Za-z_][A-Za-z0-9_]*)\\\}", r"(?P<\1>[^/]+)", escaped)
783
- return re.compile(f"^{pattern}$")
784
-
785
- def match(self, method: str, path: str, query: dict[str, str]) -> tuple[Operation, dict[str, str]] | None:
786
- """The operation for a request. Vendors reuse one path for several lookups that
787
- differ only by query parameter, so among path matches the one whose declared
788
- parameters the caller actually sent wins; ties keep declaration order."""
777
+ self.routes = [(operation, operation.pattern) for operation in spec.operations.values()]
778
+
779
+ def match(
780
+ self, method: str, path: str, query: dict[str, str], within: tuple[str, ...] | None = None
781
+ ) -> tuple[Operation, dict[str, str]] | RouteMiss:
782
+ """The operation for a request, among the operations ``within`` names when given, or how it
783
+ missed. Vendors reuse one path for several lookups that differ only by query parameter, so
784
+ among path matches the one whose declared parameters the caller actually sent wins; ties keep
785
+ declaration order."""
789
786
  best: tuple[int, int, Operation, dict[str, str]] | None = None
787
+ on_path: list[Operation] = []
790
788
  for index, (operation, pattern) in enumerate(self.routes):
791
789
  found = pattern.match(path)
792
- if not found or method not in operation.methods:
790
+ if not found or (within is not None and operation.name not in within):
791
+ continue
792
+ on_path.append(operation)
793
+ if method not in operation.methods:
793
794
  continue
794
795
  present = sum(1 for name in operation.params if name in query)
795
796
  candidate = (present, -index, operation, {k: urllib.parse.unquote(v) for k, v in found.groupdict().items()})
796
797
  if best is None or candidate[:2] > best[:2]:
797
798
  best = candidate
798
- return None if best is None else (best[2], best[3])
799
-
800
- def issue_token(self, form: dict[str, str], key: str | None) -> dict | None:
801
- """The vendor's token endpoint. Three grants, the way real vendors mint:
802
-
803
- * ``client_credentials`` (the default): a bearer ``access_token``.
804
- * ``password``: ``email`` + ``password`` in, an ``id_token`` (an HS256 JWT
805
- carrying ``sub``/``iat``/``exp``, so a client that reads expiry from the
806
- token itself sees a real one) plus a ``refresh_token``. This is how
807
- Torchlight's clients authenticate.
808
- * ``refresh_token``: a refresh token this world minted in, a fresh
809
- ``id_token`` + ``refresh_token`` out; an unknown refresh token is refused.
810
-
811
- With ``WORLD_API_KEY`` pinned the client secret (or the password) must be that
812
- key, the way a real vendor knows its clients; unpinned, any grant is served.
813
- Every bearer this world minted — access or id token — authorizes calls."""
814
- grant = form.get("grant_type", "client_credentials")
815
- if grant == "client_credentials":
816
- if key is not None and form.get("client_secret") != key:
817
- return None
818
- token = secrets.token_urlsafe(32)
819
- with self._lock:
820
- self.tokens.add(token)
821
- answer = {"access_token": token, "token_type": "Bearer", "expires_in": 3600}
822
- if form.get("scope"):
823
- answer["scope"] = form["scope"]
824
- elif self.spec.scope:
825
- answer["scope"] = self.spec.scope
826
- return answer
827
- if grant == "password":
828
- subject = form.get("email") or form.get("username") or ""
829
- if not subject or not form.get("password"):
830
- return None
831
- if key is not None and form.get("password") != key:
832
- return None
833
- return self._issue_identity(subject)
834
- if grant == "refresh_token":
835
- presented = form.get("refresh_token") or ""
836
- with self._lock:
837
- subject = self._refresh_tokens.pop(presented, None)
838
- if subject is None:
839
- return None
840
- return self._issue_identity(subject)
841
- return None
842
-
843
- def _issue_identity(self, subject: str) -> dict:
844
- """An ``id_token`` (HS256 JWT, one hour) and a ``refresh_token``, both
845
- remembered so later calls and refreshes are honoured."""
846
- import hashlib
847
- import hmac
848
-
849
- now = int(time.time())
850
- header = base64.urlsafe_b64encode(b'{"alg":"HS256","typ":"JWT"}').rstrip(b"=").decode()
851
- payload = (
852
- base64.urlsafe_b64encode(
853
- json.dumps(
854
- {
855
- "sub": subject,
856
- "iat": now,
857
- "exp": now + 3600,
858
- "iss": self.spec.slug,
859
- "jti": secrets.token_urlsafe(9),
860
- },
861
- separators=(",", ":"),
862
- ).encode()
863
- )
864
- .rstrip(b"=")
865
- .decode()
866
- )
867
- signature = (
868
- base64.urlsafe_b64encode(
869
- hmac.new(self._jwt_secret, f"{header}.{payload}".encode(), hashlib.sha256).digest()
870
- )
871
- .rstrip(b"=")
872
- .decode()
873
- )
874
- id_token = f"{header}.{payload}.{signature}"
875
- refresh = secrets.token_urlsafe(32)
876
- with self._lock:
877
- self.tokens.add(id_token)
878
- self._refresh_tokens[refresh] = subject
879
- return {
880
- "id_token": id_token,
881
- "access_token": id_token,
882
- "refresh_token": refresh,
883
- "token_type": "Bearer",
884
- "expires_in": 3600,
885
- }
886
-
887
- def authorized(self, headers: dict[str, str], query: dict[str, str], key: str | None) -> bool:
888
- spec = self.spec
889
- if spec.scheme == "none":
890
- return True
891
- presented: str | None = None
892
- if spec.scheme == "header":
893
- presented = headers.get((spec.auth_name or "").lower())
894
- elif spec.scheme in ("bearer", "oauth2"):
895
- value = headers.get("authorization", "")
896
- presented = value[7:] if value.lower().startswith("bearer ") else None
897
- elif spec.scheme == "basic":
898
- presented = basic_user(headers.get("authorization", ""))
899
- elif spec.scheme == "query":
900
- presented = query.get(spec.auth_name or "")
901
- if not presented:
902
- return False
903
- if spec.scheme == "oauth2":
904
- # A bearer is good only if this world minted it: the client did the grant first.
905
- with self._lock:
906
- return presented in self.tokens
907
- return key is None or presented == key
799
+ return RouteMiss.of(on_path) if best is None else (best[2], best[3])
908
800
 
909
801
 
910
802
  class ApiContext:
911
- """What a world's handler gets: the store, the clock, and the vendor's shapes."""
803
+ """What a world's handler gets: the store, the clock, and the vendor's shapes. The
804
+ request's door signs links (:meth:`signed_url`) and is not otherwise handed out.
805
+ ``raw`` is the request's body as sent and ``files`` the files it carried
806
+ (:class:`~.request_body.RequestBody`), beside the fields a handler reads as ``body``."""
912
807
 
913
808
  def __init__(
914
- self, state: WorldState, router: Router, operation: Operation, link: tuple[str, dict[str, str]] | None = None
809
+ self,
810
+ state: WorldState,
811
+ router: Router,
812
+ operation: Operation,
813
+ link: PageLink | None = None,
814
+ *,
815
+ door: Door | None = None,
816
+ origin: str = "",
817
+ signing_origin: str | None = None,
915
818
  ):
916
819
  self.state = state
917
820
  self.router = router
918
821
  self.settings = router.settings
919
822
  self.operation = operation
920
823
  self.spec = router.spec
921
- self.link = link
824
+ self.page_link = link
825
+ self.link = None if link is None else link.first_values
922
826
  self.headers: dict[str, str] = {}
923
827
  self.query_all: dict[str, list[str]] = {}
828
+ self.raw = b""
829
+ self.files: dict[str, Upload] = {}
830
+ self._door = door
831
+ self._origin = origin
832
+ self._signing_origin = signing_origin or origin
924
833
 
925
834
  def rows(self, entity: str) -> list[dict]:
926
835
  return self.state.rows(entity)
@@ -929,8 +838,12 @@ class ApiContext:
929
838
  return self.state.get(entity, key)
930
839
 
931
840
  def find(self, entity: str, **fields: Any) -> list[dict]:
932
- wanted = {k: str(v) for k, v in fields.items()}
933
- return RowMatch.on_fields(wanted).select(self.state.rows(entity))
841
+ return self.select(entity, RowMatch.on_fields({k: str(v) for k, v in fields.items()}))[0]
842
+
843
+ def select(
844
+ self, entity: str, match: RowMatch, *, limit: int | None = None, offset: int = 0
845
+ ) -> tuple[list[dict], int]:
846
+ return self.state.select(entity, match, limit, offset)
934
847
 
935
848
  def insert(self, entity: str, value: dict) -> dict:
936
849
  return self.state.insert(entity, value)
@@ -954,6 +867,13 @@ class ApiContext:
954
867
  def events_since(self, seq: int) -> list[dict]:
955
868
  return self.state.events_since(seq)
956
869
 
870
+ def deliver(
871
+ self, event_type: str, body: Any, scope: dict[str, Any] | None = None, event_id: str | None = None
872
+ ) -> list[str]:
873
+ """Send ``body`` as ``event_type`` to every subscription ``[webhooks]`` finds for it
874
+ (:class:`~.webhooks.WebhookOutbox`); the delivery ids, none when no one subscribed."""
875
+ return self.state.webhooks.deliver(event_type, body, scope, event_id)
876
+
957
877
  def stored_forms(self, field: str, plaintext: Any) -> tuple[Any, ...]:
958
878
  """The values the store may hold for a plaintext under this world's ``[redact]``
959
879
  (see :func:`connector.stored_forms`); a world without a spec stores the clear value."""
@@ -998,15 +918,15 @@ class ApiContext:
998
918
 
999
919
  def envelope(self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None) -> Any:
1000
920
  page = paginate(rows, query or {}, self.settings.paging)
1001
- return wrap(page, self.settings, envelope, link=self.link, omit_done_cursor=self._omits_done_cursor())
921
+ return wrap(page, self.settings, envelope, link=self.page_link, omit_done_cursor=self._omits_done_cursor())
1002
922
 
1003
923
  def paged(
1004
924
  self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None, status: int = 200
1005
925
  ) -> Any:
1006
926
  """``envelope`` plus the vendor's paging headers, as a handler's full answer."""
1007
927
  page = paginate(rows, query or {}, self.settings.paging)
1008
- body = wrap(page, self.settings, envelope, link=self.link, omit_done_cursor=self._omits_done_cursor())
1009
- return status, body, page_headers(page, self.settings)
928
+ body = wrap(page, self.settings, envelope, link=self.page_link, omit_done_cursor=self._omits_done_cursor())
929
+ return status, body, page_headers(page, self.settings, link=self.page_link)
1010
930
 
1011
931
  def _omits_done_cursor(self) -> bool:
1012
932
  return self.settings.omits_done_cursor(self.settings.for_operation(self.operation.name))
@@ -1018,6 +938,16 @@ class ApiContext:
1018
938
  def invalid(self, detail: str | None = None) -> tuple[int, Any]:
1019
939
  return self.settings.refusal(detail)
1020
940
 
941
+ def signed_url(self, path: str, ttl_seconds: int | None = None) -> str:
942
+ """A presigned link to ``path`` (a route ``[auth.downloads]`` names, as the client
943
+ sends it under base_url's path) that reaches it without the key for
944
+ ``ttl_seconds``, else the declared ``ttl_seconds``, else as long as the session."""
945
+ if self._door is None:
946
+ fail(
947
+ "handlers", "signed_url signs for a route call's session; this context answers none", "/auth/downloads"
948
+ )
949
+ return f"{self._signing_origin}{self._door.prefix}{path}?{self._door.signed_query(path, ttl_seconds)}"
950
+
1021
951
 
1022
952
  Handler = Callable[[ApiContext, dict[str, str], dict[str, str], Any], Any]
1023
953
 
@@ -1030,10 +960,13 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1030
960
  spec = importlib.util.spec_from_file_location(module_name, settings.handlers)
1031
961
  if spec is None or spec.loader is None:
1032
962
  fail("handlers", f"Could not load {settings.handlers}", "/api/handlers")
963
+ from .. import runtime
964
+
1033
965
  module = importlib.util.module_from_spec(spec)
1034
966
  sys.modules[module_name] = module
1035
967
  try:
1036
- spec.loader.exec_module(module)
968
+ with runtime.installed(runtime.route_module()):
969
+ spec.loader.exec_module(module)
1037
970
  finally:
1038
971
  sys.modules.pop(module_name, None)
1039
972
  handlers: dict[str, Handler] = {}
@@ -1060,73 +993,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1060
993
  return handlers
1061
994
 
1062
995
 
1063
- def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
1064
- """Assign a dotted target (``attributes.note``), keeping the rest of a nested
1065
- object an update leaves alone."""
1066
- parts = target.split(".")
1067
- if len(parts) == 1:
1068
- row[target] = value
1069
- return
1070
- head = parts[0]
1071
- if head not in row:
1072
- base = current.get(head) if current else None
1073
- row[head] = json.loads(json.dumps(base)) if isinstance(base, dict) else {}
1074
- node = row[head]
1075
- for part in parts[1:-1]:
1076
- if not isinstance(node.get(part), dict):
1077
- node[part] = {}
1078
- node = node[part]
1079
- node[parts[-1]] = value
1080
-
1081
-
1082
- def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | None = None) -> dict:
1083
- """The row a create or update writes: defaults, then the body (mapped or as-is), then generated fields."""
1084
- if body is None or not isinstance(body, dict):
1085
- body = {}
1086
- row: dict = json.loads(json.dumps(op.defaults)) if current is None else {}
1087
- if op.body:
1088
- for field_name, path in op.body.items():
1089
- value = dig(body, path)
1090
- if value is not None:
1091
- _set(row, field_name, value, current)
1092
- else:
1093
- row.update(body)
1094
- if current is None:
1095
- for field_name, kind in op.generate.items():
1096
- if row.get(field_name) is not None:
1097
- continue
1098
- if kind == "uuid":
1099
- row[field_name] = ctx.uuid()
1100
- elif kind == "now":
1101
- row[field_name] = ctx.now()
1102
- else:
1103
- existing = [r.get(field_name) for r in ctx.rows(ctx.operation.entity or "")]
1104
- row[field_name] = max([v for v in existing if isinstance(v, int)] + [0]) + 1
1105
- return row
1106
-
1107
-
1108
- def vendor_credential(spec: Spec, presented: str, *, grant: str | None = None) -> tuple[dict[str, str], dict[str, str]]:
1109
- """(headers, query) carrying the world's own credential: ``presented`` in
1110
- the shape the vendor's scheme declares — a ``query`` world reads its key
1111
- from the query string, so that half is a query parameter; an ``oauth2``
1112
- world accepts only a bearer it minted, so the caller passes its ``grant``.
1113
- The host presents a session token this way, the local server its pin."""
1114
- if spec.scheme == "none":
1115
- return {}, {}
1116
- if spec.scheme == "header":
1117
- return {(spec.auth_name or "x-api-key").lower(): presented}, {}
1118
- if spec.scheme == "bearer":
1119
- return {"authorization": f"Bearer {presented}"}, {}
1120
- if spec.scheme == "oauth2":
1121
- return {"authorization": f"Bearer {grant or ''}"}, {}
1122
- if spec.scheme == "basic":
1123
- return {"authorization": "Basic " + base64.b64encode(f"{presented}:".encode()).decode()}, {}
1124
- if spec.scheme == "query":
1125
- return {}, {spec.auth_name or "api_key": presented}
1126
- fail("spec", f"auth scheme '{spec.scheme}' has no credential shape to present", "/auth/scheme")
1127
- raise AssertionError
1128
-
1129
-
1130
996
  def with_query(target: str, extra: dict[str, str]) -> str:
1131
997
  """``target`` with ``extra`` merged into its query string: the caller's
1132
998
  params kept, duplicates and all, except one named like a credential in
@@ -1164,10 +1030,10 @@ class WorldApp:
1164
1030
  vendor API directly. ``calls`` is the session's call log, shared with its
1165
1031
  tools; a world served alone keeps its own.
1166
1032
 
1167
- ``admin`` serves the runner's ``/__world/*`` routes (state, calls, reset,
1168
- seed) to the holder of its token, for the runner's bundle server (``serve()``)
1169
- and a local session. A World Host session's doors carry the agent's token, and
1170
- those routes read and rewrite what its grader reads, so the host passes none.
1033
+ ``admin`` serves the runner's ``/__world/*`` routes (state, calls, reset, seed) to the holder
1034
+ of its token, and ``/healthz`` to anyone, for the runner's bundle server (``serve()``) and a
1035
+ local session. A World Host session's doors carry the agent's token, and those routes read and
1036
+ rewrite what its grader reads, so the host passes none: its api origin answers like the vendor's.
1171
1037
  """
1172
1038
 
1173
1039
  def __init__(
@@ -1182,86 +1048,61 @@ class WorldApp:
1182
1048
  ):
1183
1049
  self.state = state
1184
1050
  self.router = router
1185
- self.key = key
1186
1051
  self.admin = admin
1187
1052
  self.settings = router.settings
1188
- self.prefix = urllib.parse.urlsplit(router.spec.base_url).path.rstrip("/")
1053
+ self.door = Door.of(router.spec, router.settings, key)
1189
1054
  self.handlers = load_handlers(self.settings) if handlers is None else handlers
1190
1055
  self.routes_closed = routes_closed
1191
- self.calls = calls if calls is not None else CallLog.for_spec(router.spec)
1192
-
1193
- @staticmethod
1194
- def _json(raw: bytes) -> Any:
1195
- if not raw:
1196
- return {}
1197
- try:
1198
- return json.loads(raw.decode("utf-8"))
1199
- except (ValueError, RecursionError):
1200
- return None
1201
-
1202
- @staticmethod
1203
- def _body(raw: bytes, headers: dict[str, str]) -> Any:
1204
- """A write's body as the route reads it: JSON, or a form (``application/
1205
- x-www-form-urlencoded``, what Slack's Web API takes and a browser page
1206
- posts) as ``{name: first value}``. A body that is JSON reads as JSON
1207
- whatever the label says — urllib labels every POST a form, and no form
1208
- field starts with ``{``. Malformed JSON is None."""
1209
- content_type = (headers.get("content-type") or "").split(";")[0].strip().lower()
1210
- if content_type == "application/x-www-form-urlencoded" and not raw.lstrip().startswith((b"{", b"[")):
1211
- pairs = urllib.parse.parse_qs(raw.decode("utf-8", "replace"), keep_blank_values=True)
1212
- return {k: v[0] for k, v in pairs.items()}
1213
- return WorldApp._json(raw)
1214
-
1215
- @staticmethod
1216
- def _form(raw: bytes, headers: dict[str, str]) -> dict[str, str]:
1217
- content_type = (headers.get("content-type") or "").split(";")[0].strip().lower()
1218
- if content_type == "application/json":
1219
- try:
1220
- parsed = json.loads(raw.decode("utf-8"))
1221
- except (ValueError, RecursionError):
1222
- return {}
1223
- return {k: str(v) for k, v in parsed.items()} if isinstance(parsed, dict) else {}
1224
- form = {k: v[0] for k, v in urllib.parse.parse_qs(raw.decode("utf-8", "replace")).items()}
1225
- basic = headers.get("authorization", "")
1226
- if basic.lower().startswith("basic "):
1227
- try:
1228
- client_id, _, client_secret = base64.b64decode(basic[6:]).decode().partition(":")
1229
- form.setdefault("client_id", client_id)
1230
- form.setdefault("client_secret", client_secret)
1231
- except (ValueError, UnicodeDecodeError):
1232
- pass
1233
- return form
1234
-
1235
- def _strip(self, path: str) -> str:
1236
- if self.prefix and path.startswith(self.prefix):
1237
- return path[len(self.prefix) :] or "/"
1238
- return path
1056
+ self.calls = calls if calls is not None else CallLog.for_spec(router.spec, secret=key)
1057
+ state.serve_webhooks(router.spec.webhooks)
1239
1058
 
1240
1059
  def handle(
1241
- self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str, *, via: Via | None
1060
+ self,
1061
+ method: str,
1062
+ target: str,
1063
+ headers: dict[str, str],
1064
+ raw: bytes,
1065
+ default_host: str,
1066
+ *,
1067
+ via: Via | None,
1068
+ opened: bool = False,
1069
+ link_host: str | None = None,
1242
1070
  ) -> Response:
1243
1071
  """Answer one request. ``headers`` are lower-cased; ``default_host`` is what
1244
1072
  a link uses when the request carries no Host header; ``via`` is the door
1245
- the caller took it in by, recorded on the call when there is one."""
1073
+ the caller took it in by, recorded on the call when there is one; ``opened``:
1074
+ it came in on an open session's capability hostname, so the world asks for
1075
+ nothing (:meth:`~.door.Door.opened`); ``link_host``: the host a link the world
1076
+ signs points at, the request's own when None. A browser's preflight is answered
1077
+ before any credential, and only by a world that serves browsers."""
1246
1078
  url = urllib.parse.urlsplit(target)
1247
- settings, router = self.settings, self.router
1248
- answered = self._admin(method, url.path, raw, headers)
1079
+ answered = self._admin(method, url.path, raw, headers, via) or self.settings.cors.preflight(method, headers)
1249
1080
  if answered is not None:
1250
1081
  return answered
1251
- if method == "POST" and settings.token_path and self._strip(url.path) == settings.token_path:
1252
- issued = router.issue_token(self._form(raw, headers), self.key)
1253
- if issued is None:
1254
- return 400, {"error": "invalid_client"}, None
1255
- return 200, issued, None
1256
- if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
1257
- return 405, {"error": "method_not_allowed"}, None
1258
- return self._route(method, url, headers, raw, default_host, via)
1259
-
1260
- def _admin(self, method: str, path: str, raw: bytes, headers: dict[str, str]) -> Response | None:
1261
- """The runner's routes, or None for a request that is not one of them. Health answers on
1262
- every door; the rest only where :attr:`admin` is set, and there only to its token."""
1082
+ unrouted = partial(self._unrouted, method, url, headers, raw, via)
1083
+ door = self.door.opened() if opened else self.door
1084
+ entry = door.vendor_entry(method, url.path, url.query, headers)
1085
+ if entry is None:
1086
+ return unrouted(self.settings.unauthorized_status, self.settings.unauthorized)
1087
+ if entry is Entry.EXCHANGE:
1088
+ return unrouted(*door.answer_exchange(raw, headers))
1089
+ hosts = (default_host, link_host)
1090
+ return self._route(method, url, headers, raw, hosts, via, unrouted, door.reachable(entry))
1091
+
1092
+ def _unrouted(
1093
+ self, method: str, url, headers: dict, raw: bytes, via: Via | None, status: int, answer: Any, extra=None
1094
+ ) -> Response:
1095
+ """A request no route took (refused, or the vendor's login route, whose request body
1096
+ is never kept): answered, kept by the request ledger, not a grader's call."""
1097
+ served = Served(headers, len(raw), extra, self.settings.error_content_type, self.door.credential, False)
1098
+ self.calls.heard(method, self.door.route_path(url.path), url.query, status, answer, via, served)
1099
+ return status, answer, self.settings.cors.carried(extra)
1100
+
1101
+ def _admin(self, method: str, path: str, raw: bytes, headers: dict[str, str], via: Via | None) -> Response | None:
1102
+ """The runner's routes, or None for a request that is not one of them: health where :attr:`admin` is set
1103
+ and on the ui door, whose page may probe it; the rest only where it is set, and only to its token."""
1263
1104
  state = self.state
1264
- if (method, path) == ("GET", ADMIN["health"]):
1105
+ if (self.admin is not None or via is Via.UI) and (method, path) == ("GET", ADMIN["health"]):
1265
1106
  return 200, {"ok": True, "world": self.router.spec.slug}, None
1266
1107
  if self.admin is None or path not in RUNNER_PATHS:
1267
1108
  return None
@@ -1279,7 +1120,7 @@ class WorldApp:
1279
1120
  return None
1280
1121
 
1281
1122
  def _seed(self, raw: bytes) -> Response:
1282
- body = self._json(raw)
1123
+ body = json_value(raw)
1283
1124
  if body is None:
1284
1125
  return 400, {"error": "seed must be JSON"}, None
1285
1126
  try:
@@ -1288,60 +1129,79 @@ class WorldApp:
1288
1129
  if error.detail.get("code") == "base_mismatch":
1289
1130
  return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
1290
1131
  return 400, {"error": "seed_rejected", "detail": str(error)}, None
1291
- except Exception as error: # a rejected seed is the caller's problem, reported plainly
1132
+ except Exception as error:
1292
1133
  return 400, {"error": "seed_rejected", "detail": str(error)}, None
1293
1134
  return 200, {"ok": True}, None
1294
1135
 
1295
1136
  def _route(
1296
- self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
1137
+ self,
1138
+ method: str,
1139
+ url,
1140
+ headers: dict[str, str],
1141
+ raw: bytes,
1142
+ hosts: tuple[str, str | None],
1143
+ via: Via | None,
1144
+ unrouted,
1145
+ within: tuple[str, ...] | None,
1297
1146
  ) -> Response:
1298
1147
  settings, router = self.settings, self.router
1299
- path = self._strip(url.path)
1148
+ path = self.door.route_path(url.path)
1300
1149
  query_all = {k: list(v) for k, v in urllib.parse.parse_qs(url.query).items()}
1301
1150
  query = {k: v[0] for k, v in query_all.items()}
1302
- if not router.authorized(headers, query, self.key):
1303
- return settings.unauthorized_status, settings.unauthorized, None
1304
- matched = router.match(method, path, query)
1305
- if matched is None:
1306
- return settings.not_found_status, settings.not_found, None
1151
+ matched = router.match(method, path, query, within)
1152
+ if isinstance(matched, RouteMiss):
1153
+ return unrouted(*matched.answer(settings))
1307
1154
  operation, args = matched
1308
1155
  if self.routes_closed:
1309
- return 403, {"error": "route_not_allowed", "operation": operation.name, "detail": ROUTES_CLOSED}, None
1156
+ return unrouted(403, {"error": "route_not_allowed", "operation": operation.name, "detail": ROUTES_CLOSED})
1310
1157
  op = settings.for_operation(operation.name)
1311
- body = self._body(raw, headers) if method in ("POST", "PUT", "PATCH") else {}
1158
+ read = method in ("POST", "PUT", "PATCH") or (method == "DELETE" and bool(raw))
1159
+ sent = RequestBody.of(raw if read else b"", headers)
1160
+ body = sent.fields_for(op.action == "handler")
1312
1161
  if body is None:
1313
- return settings.invalid_status, settings.invalid, None
1162
+ return unrouted(settings.invalid_status, settings.invalid)
1314
1163
  started = time.monotonic()
1315
1164
  status, answer, extra = 500, None, None
1316
1165
  try:
1317
1166
  status, answer, extra = self._answer_atomically(
1318
- op, operation, args, query, query_all, body, headers, url, default_host
1167
+ op, operation, args, query, query_all, body, sent, headers, url, hosts
1319
1168
  )
1320
1169
  finally:
1321
1170
  elapsed = time.monotonic() - started
1322
1171
  shape = settings.answer_shape(op, operation)
1323
- self.calls.record(operation, method, path, args, query_all, body, status, answer, elapsed, via, shape=shape)
1324
- return status, answer, extra
1172
+ served = Served(headers, len(raw), extra, settings.error_content_type, self.door.credential, read)
1173
+ self.calls.record(
1174
+ operation, method, path, args, query_all, body, status, answer, elapsed, via, shape=shape, served=served
1175
+ )
1176
+ self.calls.record_webhooks(self.state.webhooks.take())
1177
+ return status, answer, settings.cors.carried(extra)
1325
1178
 
1326
- def _answer_atomically(self, *request) -> Response:
1179
+ def _answer_atomically(self, op, operation, *request) -> Response:
1327
1180
  try:
1328
1181
  with self.state.transaction():
1329
- response = self._answer_route(*request)
1182
+ response = self._answer_route(op, operation, *request)
1330
1183
  if response[0] >= 400:
1331
1184
  raise _Refused(response)
1332
1185
  except _Refused as refused:
1333
1186
  return refused.response
1187
+ except MisdeclaredRoute as bug:
1188
+ return 400, handler_bug_body(operation.name, bug), None
1334
1189
  except ContractError as error:
1335
- return (*self.settings.refusal(getattr(error, "detail", None) or {"message": str(error)}), None)
1190
+ log_contract_refusal(self.router.spec.slug, operation.name, error)
1191
+ return (*self.settings.refusal(), None)
1336
1192
  return response
1337
1193
 
1338
- def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
1194
+ def _answer_route(self, op, operation, args, query, query_all, body, sent, headers, url, hosts) -> Response:
1339
1195
  router, state, handlers = self.router, self.state, self.handlers
1196
+ default_host, link_host = hosts
1340
1197
  host = headers.get("host") or default_host
1341
1198
  forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
1342
- ctx = ApiContext(state, router, operation, link=(f"{forwarded}://{host}{url.path}", query))
1343
- ctx.headers = headers
1344
- ctx.query_all = query_all
1199
+ origin = f"{forwarded}://{host}"
1200
+ link = PageLink.of(f"{origin}{url.path}", query_all, self.calls.redaction.credential_params)
1201
+ signing = f"{forwarded}://{link_host or host}"
1202
+ ctx = ApiContext(state, router, operation, link=link, door=self.door, origin=origin, signing_origin=signing)
1203
+ ctx.headers, ctx.query_all = headers, query_all
1204
+ ctx.raw, ctx.files = sent.raw, sent.files
1345
1205
  request = (ctx, args, query, body)
1346
1206
  gate = self.settings.before or BEFORE
1347
1207
  verdict = handled_answer(gate, handlers[BEFORE], request, None) if BEFORE in handlers else None
@@ -1349,124 +1209,16 @@ class WorldApp:
1349
1209
  return verdict
1350
1210
  if op.action == "handler":
1351
1211
  return handled_answer(op.handler or operation.name, handlers[operation.name], request, op.status)
1352
- return normalize_answer(self._answer(op, operation, ctx, args, query, body), op.status)
1353
-
1354
- @staticmethod
1355
- def _answer(
1356
- op: OperationSettings,
1357
- operation: Operation,
1358
- ctx: ApiContext,
1359
- args: dict[str, str],
1360
- query: dict[str, str],
1361
- body: Any,
1362
- ) -> Any:
1363
- if not operation.entity:
1364
- return 501, {"error": "not_modelled", "operation": operation.name}
1365
- entity = operation.entity
1366
- omit_done_cursor = ctx.settings.omits_done_cursor(op)
1367
- if op.action == "create":
1368
- row = ctx.insert(entity, _bind(op, ctx, body))
1369
- return op.status, _one(op, ctx, row)
1370
- selection = op.filter or _segment_filter(operation, ctx, entity)
1371
- if not selection and (op.action in ("update", "delete") or (op.single and operation.placeholders)):
1372
- fail(
1373
- "spec",
1374
- f"route {operation.name} finds its row by nothing: its path names no field of {entity} and it "
1375
- "declares no api.filter; map a path argument to a field with api.filter, or answer the route with "
1376
- 'action = "handler"',
1377
- f"/operations/{operation.name}/api/filter",
1378
- )
1379
- filters = selection
1380
- if not op.filter and op.action == "read":
1381
- filters = {**_query_field_filter(ctx, entity, ctx.query_all), **filters}
1382
- # Every value sent filters: ``status[]=a&status[]=b`` reads as either, never as a with b dropped.
1383
- values: dict[str, str | list[str]] = {
1384
- **{k: v for k, v in ctx.query_all.items() if k in operation.params or k in filters},
1385
- **args,
1386
- }
1387
- rows = RowMatch(filters, values, op.match or {}).select(ctx.rows(entity))
1388
- if op.action in ("update", "delete"):
1389
- if len(rows) != 1:
1390
- return ctx.not_found()
1391
- key = ctx.key_of(entity, rows[0])
1392
- if op.action == "delete":
1393
- ctx.delete(entity, key)
1394
- return op.status, None
1395
- row = ctx.update(entity, key, _bind(op, ctx, body, current=rows[0]))
1396
- return op.status, _one(op, ctx, row)
1397
- if op.single and not rows:
1398
- return ctx.not_found()
1399
- if op.single:
1400
- return op.status, single(rows[0], op.envelope, op.wrapper)
1401
- paging = (
1402
- ctx.settings.paging
1403
- if op.paging is None
1404
- else Paging(
1405
- op.paging,
1406
- ctx.settings.paging.limit_param,
1407
- ctx.settings.paging.offset_param,
1408
- ctx.settings.paging.cursor_param,
1409
- ctx.settings.paging.page_size,
1410
- )
1411
- )
1412
- page = paginate(rows, query, paging)
1413
- return (
1414
- op.status,
1415
- wrap(
1416
- page,
1417
- ctx.settings,
1418
- op.envelope,
1419
- paging=paging,
1420
- link=ctx.link,
1421
- omit_done_cursor=omit_done_cursor,
1422
- wrapper=op.wrapper,
1423
- ),
1424
- page_headers(page, ctx.settings, paging),
1425
- )
1426
-
1427
-
1428
- def _one(op: OperationSettings, ctx: ApiContext, row: dict) -> Any:
1429
- """A written row answered the route's way: alone (at its own envelope), or as a list of one."""
1430
- if op.single:
1431
- return single(row, op.envelope, op.wrapper)
1432
- return wrap([row], ctx.settings, op.envelope, wrapper=op.wrapper)
1433
-
1434
-
1435
- def send_response(
1436
- handler: BaseHTTPRequestHandler, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str
1437
- ) -> None:
1438
- """Write one ``WorldApp`` answer to a request handler's socket."""
1439
- if status == 204 or body is None:
1440
- handler.send_response(status)
1441
- for name, value in (extra or {}).items():
1442
- handler.send_header(name, value)
1443
- handler.send_header("Content-Length", "0")
1444
- handler.end_headers()
1445
- return
1446
- headers = dict(extra or {})
1447
- if isinstance(body, bytes):
1448
- payload = body
1449
- else:
1450
- payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
1451
- headers = {"Content-Type": error_content_type if status >= 400 else "application/json", **headers}
1452
- handler.send_response(status)
1453
- for name, value in headers.items():
1454
- handler.send_header(name, value)
1455
- handler.send_header("Content-Length", str(len(payload)))
1456
- handler.end_headers()
1457
- handler.wfile.write(payload)
1212
+ return normalize_answer(DeclaredRoute(op, operation, ctx, args, query, body).answer(), op.status)
1458
1213
 
1459
1214
 
1460
1215
  def make_handler(state: WorldState, router: Router, key: str | None, admin: AdminToken | None = None):
1461
1216
  app = WorldApp(state, router, key, admin=admin or AdminToken())
1462
1217
 
1463
- class Handler(BaseHTTPRequestHandler):
1218
+ class Handler(WorldRequestHandler):
1464
1219
  server_version = f"gateway-world-api/{router.spec.slug}"
1465
1220
 
1466
- def log_message(self, *_):
1467
- pass
1468
-
1469
- def _serve(self, method: str) -> None:
1221
+ def _dispatch(self, method: str) -> None:
1470
1222
  length = int(self.headers.get("Content-Length") or 0)
1471
1223
  raw = self.rfile.read(length) if length else b""
1472
1224
  headers = {k.lower(): v for k, v in self.headers.items()}
@@ -1475,21 +1227,6 @@ def make_handler(state: WorldState, router: Router, key: str | None, admin: Admi
1475
1227
  status, body, extra = app.handle(method, self.path, headers, raw, default_host, via=None)
1476
1228
  send_response(self, status, body, extra, app.settings.error_content_type)
1477
1229
 
1478
- def do_GET(self):
1479
- self._serve("GET")
1480
-
1481
- def do_POST(self):
1482
- self._serve("POST")
1483
-
1484
- def do_PUT(self):
1485
- self._serve("PUT")
1486
-
1487
- def do_PATCH(self):
1488
- self._serve("PATCH")
1489
-
1490
- def do_DELETE(self):
1491
- self._serve("DELETE")
1492
-
1493
1230
  return Handler
1494
1231
 
1495
1232
 
@@ -1556,20 +1293,7 @@ def serve_forever(
1556
1293
 
1557
1294
 
1558
1295
  def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
1559
- parameters = {"header": "header", "query": "query"}
1560
- security_scheme: dict[str, Any] = {}
1561
- if spec.scheme in ("header", "query"):
1562
- security_scheme = {"type": "apiKey", "in": parameters[spec.scheme], "name": spec.auth_name}
1563
- elif spec.scheme == "bearer":
1564
- security_scheme = {"type": "http", "scheme": "bearer"}
1565
- elif spec.scheme == "basic":
1566
- security_scheme = {"type": "http", "scheme": "basic"}
1567
- elif spec.scheme == "oauth2":
1568
- token_url = (settings.token_path if settings else None) or DEFAULT_TOKEN_PATH
1569
- security_scheme = {
1570
- "type": "oauth2",
1571
- "flows": {"clientCredentials": {"tokenUrl": token_url, "scopes": {spec.scope or "api": "API access"}}},
1572
- }
1296
+ security_scheme = spec.auth.scheme.security_scheme(settings.token_path if settings else None)
1573
1297
  paths: dict[str, dict] = {}
1574
1298
  for operation in spec.operations.values():
1575
1299
  op = settings.for_operation(operation.name) if settings else OperationSettings()