@withgateway/sdk 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2221 -962
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2212 -953
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +81 -19
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +79 -17
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/index.d.mts +2 -2
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.js +903 -221
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.mjs +868 -212
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/traces/index.js +78 -16
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +76 -14
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.js +7 -1
  29. package/dist/tracing/index.js.map +1 -1
  30. package/dist/tracing/index.mjs +7 -1
  31. package/dist/tracing/index.mjs.map +1 -1
  32. package/dist/worlds/index.d.mts +692 -410
  33. package/dist/worlds/index.d.ts +692 -410
  34. package/dist/worlds/index.js +740 -197
  35. package/dist/worlds/index.js.map +1 -1
  36. package/dist/worlds/index.mjs +736 -193
  37. package/dist/worlds/index.mjs.map +1 -1
  38. package/package.json +1 -1
  39. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  40. package/runtime/gatewaysdk/environment/_world.py +58 -65
  41. package/runtime/gatewaysdk/environment/backing.py +20 -24
  42. package/runtime/gatewaysdk/environment/core.py +1 -16
  43. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  44. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +174 -471
  46. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  47. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  48. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  50. package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
  51. package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
  52. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  53. package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
  54. package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
  55. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  56. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  58. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  59. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  60. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  62. package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
  63. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  64. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  65. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  66. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  67. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  68. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  69. package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
  70. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  71. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  72. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  73. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  74. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  75. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  76. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  77. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  78. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  79. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  82. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  83. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  84. package/runtime/gatewaysdk/environment/schema/local.py +31 -116
  85. package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
  86. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  87. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  88. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  89. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  90. package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
  91. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  92. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  93. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  94. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  95. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
  96. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
  98. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  102. package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
  103. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  104. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  105. package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
  106. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  107. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  108. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  109. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  110. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  111. package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
  112. package/runtime/gatewaysdk/environment/world.py +1 -1
  113. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  114. package/skills/agents/connector-template-author.md +5 -1
  115. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  116. package/skills/connector-schema-authoring/SKILL.md +31 -6
  117. package/skills/connector-schema-authoring/connector-worlds.md +129 -7
  118. package/skills/world-data-ingestion/ROWS.md +12 -8
  119. package/skills/world-data-ingestion/SKILL.md +13 -13
  120. package/skills/worlds-getting-started/SKILL.md +23 -23
  121. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  122. package/skills/worlds-getting-started/references/gotchas.md +35 -2
  123. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -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,21 @@ 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
120
  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
121
+ from .connector import SPEC, Operation, Spec, load_spec, stored_forms
122
+ from .cors import Cors
123
123
  from .database import WorldDatabase
124
- from .database.matching import RowMatch, dig
125
- from .envelope import Paging, page_headers, paginate, single, wrap
124
+ from .database.matching import RowMatch
125
+ from .declared_routes import DeclaredRoute, MisdeclaredRoute
126
+ from .door import Door, Entry
127
+ from .envelope import PageLink, Paging, page_headers, paginate, wrap
126
128
  from .grading import keyed_entities
127
- from .handler_errors import handled_answer, normalize_answer
129
+ from .handler_errors import handled_answer, handler_bug_body, log_contract_refusal, normalize_answer
128
130
  from .primary_key import PrimaryKey
131
+ from .request_body import RequestBody, Upload, json_value
132
+ from .route_miss import RouteMiss, served_methods
129
133
  from .validation import ContractError, fail, read_json
130
134
 
131
135
  EVENT_LOG_SIZE = 500
@@ -181,9 +185,12 @@ class ApiSettings:
181
185
  unauthorized: Any
182
186
  not_found: Any
183
187
  unauthorized_status: int = 401
188
+ unauthorized_declared: bool = False
184
189
  not_found_status: int = 404
185
190
  invalid: Any = None
186
191
  invalid_status: int = 400
192
+ wrong_method: Any = None
193
+ wrong_method_status: int = 405
187
194
  error_content_type: str = "application/json"
188
195
  hits_key: str = "hits"
189
196
  cursor_key: str = "cursor"
@@ -191,6 +198,8 @@ class ApiSettings:
191
198
  previous_key: str | None = None
192
199
  page_headers: dict[str, str] = field(default_factory=dict)
193
200
  page_links: bool = False
201
+ link_header: bool = False
202
+ cors: Cors = field(default_factory=Cors)
194
203
  paging: Paging = field(default_factory=Paging)
195
204
  token_path: str | None = None
196
205
  handlers: Path | None = None
@@ -400,7 +409,6 @@ def operation_api_settings(entry: dict, operation: Operation, location: str) ->
400
409
  )
401
410
 
402
411
 
403
- # Every pusher drops these at any depth, so a ui built under one never reaches the hub: refused here.
404
412
  ARCHIVE_DROPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
405
413
 
406
414
 
@@ -456,10 +464,6 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
456
464
  token_path = api.get("token_path")
457
465
  if token_path is not None and (not isinstance(token_path, str) or not token_path.startswith("/")):
458
466
  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
467
  handlers_name = api.get("handlers")
464
468
  if handlers_name is not None and not isinstance(handlers_name, str):
465
469
  fail("spec", "api.handlers is the path of the world's handlers module", "/api/handlers")
@@ -487,9 +491,12 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
487
491
  unauthorized=_json_body(api, "unauthorized", {"error": "unauthorized"}, "/api"),
488
492
  not_found=_json_body(api, "not_found", {"error": "not_found"}, "/api"),
489
493
  unauthorized_status=_status(api, "unauthorized_status", 401, "/api", low=400, high=599),
494
+ unauthorized_declared="unauthorized" in api or "unauthorized_status" in api,
490
495
  not_found_status=_status(api, "not_found_status", 404, "/api", low=400, high=599),
491
496
  invalid=_json_body(api, "invalid", {"error": "invalid"}, "/api"),
492
497
  invalid_status=_status(api, "invalid_status", 400, "/api", low=400, high=599),
498
+ wrong_method=_json_body(api, "wrong_method", None, "/api"),
499
+ wrong_method_status=_status(api, "wrong_method_status", 405, "/api", low=400, high=599),
493
500
  error_content_type=_name(api, "error_content_type", "application/json", "/api"),
494
501
  hits_key=_key_name(api, "hits_key", "hits"),
495
502
  cursor_key=_name(api, "cursor_key", "cursor", "/api"),
@@ -497,8 +504,10 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
497
504
  previous_key=_name(api, "previous_key", "", "/api") if api.get("previous_key") is not None else None,
498
505
  page_headers=_page_headers(api),
499
506
  page_links=_flag(api, "page_links", "/api"),
507
+ link_header=_flag(api, "link_header", "/api"),
508
+ cors=Cors.of(_flag(api, "cors", "/api"), served_methods(spec.operations.values())),
500
509
  paging=paging,
501
- token_path=token_path,
510
+ token_path=spec.auth.token_path(token_path, spec.operations, "/api"),
502
511
  handlers=handlers if handlers.is_file() else None,
503
512
  before=before,
504
513
  operations=operations,
@@ -520,7 +529,7 @@ class WorldState:
520
529
  self.world = world
521
530
  self.contract = served.contract
522
531
  self._initial: dict | None = None
523
- self._snapshot_path = snapshots.default_snapshot(world, self.contract)
532
+ self._snapshot_path = served.path
524
533
  self.snapshot: dict | None = served.sidecar
525
534
  self._dir = tempfile.TemporaryDirectory(prefix="gateway-world-api-")
526
535
  self._lock = threading.RLock()
@@ -692,6 +701,11 @@ class WorldState:
692
701
  assert self.store is not None
693
702
  return self.store.get(entity, key)
694
703
 
704
+ def select(self, entity: str, match: RowMatch, limit: int | None, offset: int) -> tuple[list[dict], int]:
705
+ with self._lock:
706
+ assert self.store is not None
707
+ return self.store.select(entity, match, limit, offset)
708
+
695
709
  @contextmanager
696
710
  def transaction(self) -> Iterator[None]:
697
711
  """One route call: its writes and events all land, or none do."""
@@ -745,182 +759,68 @@ class WorldState:
745
759
  self._dir.cleanup()
746
760
 
747
761
 
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
762
  class Router:
763
+ """The routes of connector.toml, matched against a request."""
764
+
770
765
  def __init__(self, spec: Spec, settings: ApiSettings):
771
766
  self.spec = spec
772
767
  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."""
768
+ self.routes = [(operation, operation.pattern) for operation in spec.operations.values()]
769
+
770
+ def match(
771
+ self, method: str, path: str, query: dict[str, str], within: tuple[str, ...] | None = None
772
+ ) -> tuple[Operation, dict[str, str]] | RouteMiss:
773
+ """The operation for a request, among the operations ``within`` names when given, or how it
774
+ missed. Vendors reuse one path for several lookups that differ only by query parameter, so
775
+ among path matches the one whose declared parameters the caller actually sent wins; ties keep
776
+ declaration order."""
789
777
  best: tuple[int, int, Operation, dict[str, str]] | None = None
778
+ on_path: list[Operation] = []
790
779
  for index, (operation, pattern) in enumerate(self.routes):
791
780
  found = pattern.match(path)
792
- if not found or method not in operation.methods:
781
+ if not found or (within is not None and operation.name not in within):
782
+ continue
783
+ on_path.append(operation)
784
+ if method not in operation.methods:
793
785
  continue
794
786
  present = sum(1 for name in operation.params if name in query)
795
787
  candidate = (present, -index, operation, {k: urllib.parse.unquote(v) for k, v in found.groupdict().items()})
796
788
  if best is None or candidate[:2] > best[:2]:
797
789
  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
790
+ return RouteMiss.of(on_path) if best is None else (best[2], best[3])
908
791
 
909
792
 
910
793
  class ApiContext:
911
- """What a world's handler gets: the store, the clock, and the vendor's shapes."""
794
+ """What a world's handler gets: the store, the clock, and the vendor's shapes. The
795
+ request's door signs links (:meth:`signed_url`) and is not otherwise handed out.
796
+ ``raw`` is the request's body as sent and ``files`` the files it carried
797
+ (:class:`~.request_body.RequestBody`), beside the fields a handler reads as ``body``."""
912
798
 
913
799
  def __init__(
914
- self, state: WorldState, router: Router, operation: Operation, link: tuple[str, dict[str, str]] | None = None
800
+ self,
801
+ state: WorldState,
802
+ router: Router,
803
+ operation: Operation,
804
+ link: PageLink | None = None,
805
+ *,
806
+ door: Door | None = None,
807
+ origin: str = "",
808
+ signing_origin: str | None = None,
915
809
  ):
916
810
  self.state = state
917
811
  self.router = router
918
812
  self.settings = router.settings
919
813
  self.operation = operation
920
814
  self.spec = router.spec
921
- self.link = link
815
+ self.page_link = link
816
+ self.link = None if link is None else link.first_values
922
817
  self.headers: dict[str, str] = {}
923
818
  self.query_all: dict[str, list[str]] = {}
819
+ self.raw = b""
820
+ self.files: dict[str, Upload] = {}
821
+ self._door = door
822
+ self._origin = origin
823
+ self._signing_origin = signing_origin or origin
924
824
 
925
825
  def rows(self, entity: str) -> list[dict]:
926
826
  return self.state.rows(entity)
@@ -929,8 +829,12 @@ class ApiContext:
929
829
  return self.state.get(entity, key)
930
830
 
931
831
  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))
832
+ return self.select(entity, RowMatch.on_fields({k: str(v) for k, v in fields.items()}))[0]
833
+
834
+ def select(
835
+ self, entity: str, match: RowMatch, *, limit: int | None = None, offset: int = 0
836
+ ) -> tuple[list[dict], int]:
837
+ return self.state.select(entity, match, limit, offset)
934
838
 
935
839
  def insert(self, entity: str, value: dict) -> dict:
936
840
  return self.state.insert(entity, value)
@@ -998,15 +902,15 @@ class ApiContext:
998
902
 
999
903
  def envelope(self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None) -> Any:
1000
904
  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())
905
+ return wrap(page, self.settings, envelope, link=self.page_link, omit_done_cursor=self._omits_done_cursor())
1002
906
 
1003
907
  def paged(
1004
908
  self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None, status: int = 200
1005
909
  ) -> Any:
1006
910
  """``envelope`` plus the vendor's paging headers, as a handler's full answer."""
1007
911
  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)
912
+ body = wrap(page, self.settings, envelope, link=self.page_link, omit_done_cursor=self._omits_done_cursor())
913
+ return status, body, page_headers(page, self.settings, link=self.page_link)
1010
914
 
1011
915
  def _omits_done_cursor(self) -> bool:
1012
916
  return self.settings.omits_done_cursor(self.settings.for_operation(self.operation.name))
@@ -1018,6 +922,16 @@ class ApiContext:
1018
922
  def invalid(self, detail: str | None = None) -> tuple[int, Any]:
1019
923
  return self.settings.refusal(detail)
1020
924
 
925
+ def signed_url(self, path: str, ttl_seconds: int | None = None) -> str:
926
+ """A presigned link to ``path`` (a route ``[auth.downloads]`` names, as the client
927
+ sends it under base_url's path) that reaches it without the key for
928
+ ``ttl_seconds``, else the declared ``ttl_seconds``, else as long as the session."""
929
+ if self._door is None:
930
+ fail(
931
+ "handlers", "signed_url signs for a route call's session; this context answers none", "/auth/downloads"
932
+ )
933
+ return f"{self._signing_origin}{self._door.prefix}{path}?{self._door.signed_query(path, ttl_seconds)}"
934
+
1021
935
 
1022
936
  Handler = Callable[[ApiContext, dict[str, str], dict[str, str], Any], Any]
1023
937
 
@@ -1060,73 +974,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1060
974
  return handlers
1061
975
 
1062
976
 
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
977
  def with_query(target: str, extra: dict[str, str]) -> str:
1131
978
  """``target`` with ``extra`` merged into its query string: the caller's
1132
979
  params kept, duplicates and all, except one named like a credential in
@@ -1164,10 +1011,10 @@ class WorldApp:
1164
1011
  vendor API directly. ``calls`` is the session's call log, shared with its
1165
1012
  tools; a world served alone keeps its own.
1166
1013
 
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.
1014
+ ``admin`` serves the runner's ``/__world/*`` routes (state, calls, reset, seed) to the holder
1015
+ of its token, and ``/healthz`` to anyone, for the runner's bundle server (``serve()``) and a
1016
+ local session. A World Host session's doors carry the agent's token, and those routes read and
1017
+ rewrite what its grader reads, so the host passes none: its api origin answers like the vendor's.
1171
1018
  """
1172
1019
 
1173
1020
  def __init__(
@@ -1182,86 +1029,60 @@ class WorldApp:
1182
1029
  ):
1183
1030
  self.state = state
1184
1031
  self.router = router
1185
- self.key = key
1186
1032
  self.admin = admin
1187
1033
  self.settings = router.settings
1188
- self.prefix = urllib.parse.urlsplit(router.spec.base_url).path.rstrip("/")
1034
+ self.door = Door.of(router.spec, router.settings, key)
1189
1035
  self.handlers = load_handlers(self.settings) if handlers is None else handlers
1190
1036
  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
1037
+ self.calls = calls if calls is not None else CallLog.for_spec(router.spec, secret=key)
1239
1038
 
1240
1039
  def handle(
1241
- self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str, *, via: Via | None
1040
+ self,
1041
+ method: str,
1042
+ target: str,
1043
+ headers: dict[str, str],
1044
+ raw: bytes,
1045
+ default_host: str,
1046
+ *,
1047
+ via: Via | None,
1048
+ opened: bool = False,
1049
+ link_host: str | None = None,
1242
1050
  ) -> Response:
1243
1051
  """Answer one request. ``headers`` are lower-cased; ``default_host`` is what
1244
1052
  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."""
1053
+ the caller took it in by, recorded on the call when there is one; ``opened``:
1054
+ it came in on an open session's capability hostname, so the world asks for
1055
+ nothing (:meth:`~.door.Door.opened`); ``link_host``: the host a link the world
1056
+ signs points at, the request's own when None. A browser's preflight is answered
1057
+ before any credential, and only by a world that serves browsers."""
1246
1058
  url = urllib.parse.urlsplit(target)
1247
- settings, router = self.settings, self.router
1248
- answered = self._admin(method, url.path, raw, headers)
1059
+ answered = self._admin(method, url.path, raw, headers, via) or self.settings.cors.preflight(method, headers)
1249
1060
  if answered is not None:
1250
1061
  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."""
1062
+ unrouted = partial(self._unrouted, method, url, headers, raw, via)
1063
+ door = self.door.opened() if opened else self.door
1064
+ entry = door.vendor_entry(method, url.path, url.query, headers)
1065
+ if entry is None:
1066
+ return unrouted(self.settings.unauthorized_status, self.settings.unauthorized)
1067
+ if entry is Entry.EXCHANGE:
1068
+ return unrouted(*door.answer_exchange(raw, headers))
1069
+ hosts = (default_host, link_host)
1070
+ return self._route(method, url, headers, raw, hosts, via, unrouted, door.reachable(entry))
1071
+
1072
+ def _unrouted(
1073
+ self, method: str, url, headers: dict, raw: bytes, via: Via | None, status: int, answer: Any, extra=None
1074
+ ) -> Response:
1075
+ """A request no route took (refused, or the vendor's login route, whose request body
1076
+ is never kept): answered, kept by the request ledger, not a grader's call."""
1077
+ served = Served(headers, len(raw), extra, self.settings.error_content_type, self.door.credential, False)
1078
+ self.calls.heard(method, self.door.route_path(url.path), url.query, status, answer, via, served)
1079
+ return status, answer, self.settings.cors.carried(extra)
1080
+
1081
+ def _admin(self, method: str, path: str, raw: bytes, headers: dict[str, str], via: Via | None) -> Response | None:
1082
+ """The runner's routes, or None for a request that is not one of them: health where :attr:`admin` is set
1083
+ and on the ui door, whose page may probe it; the rest only where it is set, and only to its token."""
1263
1084
  state = self.state
1264
- if (method, path) == ("GET", ADMIN["health"]):
1085
+ if (self.admin is not None or via is Via.UI) and (method, path) == ("GET", ADMIN["health"]):
1265
1086
  return 200, {"ok": True, "world": self.router.spec.slug}, None
1266
1087
  if self.admin is None or path not in RUNNER_PATHS:
1267
1088
  return None
@@ -1279,7 +1100,7 @@ class WorldApp:
1279
1100
  return None
1280
1101
 
1281
1102
  def _seed(self, raw: bytes) -> Response:
1282
- body = self._json(raw)
1103
+ body = json_value(raw)
1283
1104
  if body is None:
1284
1105
  return 400, {"error": "seed must be JSON"}, None
1285
1106
  try:
@@ -1288,60 +1109,78 @@ class WorldApp:
1288
1109
  if error.detail.get("code") == "base_mismatch":
1289
1110
  return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
1290
1111
  return 400, {"error": "seed_rejected", "detail": str(error)}, None
1291
- except Exception as error: # a rejected seed is the caller's problem, reported plainly
1112
+ except Exception as error:
1292
1113
  return 400, {"error": "seed_rejected", "detail": str(error)}, None
1293
1114
  return 200, {"ok": True}, None
1294
1115
 
1295
1116
  def _route(
1296
- self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
1117
+ self,
1118
+ method: str,
1119
+ url,
1120
+ headers: dict[str, str],
1121
+ raw: bytes,
1122
+ hosts: tuple[str, str | None],
1123
+ via: Via | None,
1124
+ unrouted,
1125
+ within: tuple[str, ...] | None,
1297
1126
  ) -> Response:
1298
1127
  settings, router = self.settings, self.router
1299
- path = self._strip(url.path)
1128
+ path = self.door.route_path(url.path)
1300
1129
  query_all = {k: list(v) for k, v in urllib.parse.parse_qs(url.query).items()}
1301
1130
  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
1131
+ matched = router.match(method, path, query, within)
1132
+ if isinstance(matched, RouteMiss):
1133
+ return unrouted(*matched.answer(settings))
1307
1134
  operation, args = matched
1308
1135
  if self.routes_closed:
1309
- return 403, {"error": "route_not_allowed", "operation": operation.name, "detail": ROUTES_CLOSED}, None
1136
+ return unrouted(403, {"error": "route_not_allowed", "operation": operation.name, "detail": ROUTES_CLOSED})
1310
1137
  op = settings.for_operation(operation.name)
1311
- body = self._body(raw, headers) if method in ("POST", "PUT", "PATCH") else {}
1138
+ read = method in ("POST", "PUT", "PATCH") or (method == "DELETE" and bool(raw))
1139
+ sent = RequestBody.of(raw if read else b"", headers)
1140
+ body = sent.fields_for(op.action == "handler")
1312
1141
  if body is None:
1313
- return settings.invalid_status, settings.invalid, None
1142
+ return unrouted(settings.invalid_status, settings.invalid)
1314
1143
  started = time.monotonic()
1315
1144
  status, answer, extra = 500, None, None
1316
1145
  try:
1317
1146
  status, answer, extra = self._answer_atomically(
1318
- op, operation, args, query, query_all, body, headers, url, default_host
1147
+ op, operation, args, query, query_all, body, sent, headers, url, hosts
1319
1148
  )
1320
1149
  finally:
1321
1150
  elapsed = time.monotonic() - started
1322
1151
  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
1152
+ served = Served(headers, len(raw), extra, settings.error_content_type, self.door.credential, read)
1153
+ self.calls.record(
1154
+ operation, method, path, args, query_all, body, status, answer, elapsed, via, shape=shape, served=served
1155
+ )
1156
+ return status, answer, settings.cors.carried(extra)
1325
1157
 
1326
- def _answer_atomically(self, *request) -> Response:
1158
+ def _answer_atomically(self, op, operation, *request) -> Response:
1327
1159
  try:
1328
1160
  with self.state.transaction():
1329
- response = self._answer_route(*request)
1161
+ response = self._answer_route(op, operation, *request)
1330
1162
  if response[0] >= 400:
1331
1163
  raise _Refused(response)
1332
1164
  except _Refused as refused:
1333
1165
  return refused.response
1166
+ except MisdeclaredRoute as bug:
1167
+ return 400, handler_bug_body(operation.name, bug), None
1334
1168
  except ContractError as error:
1335
- return (*self.settings.refusal(getattr(error, "detail", None) or {"message": str(error)}), None)
1169
+ log_contract_refusal(self.router.spec.slug, operation.name, error)
1170
+ return (*self.settings.refusal(), None)
1336
1171
  return response
1337
1172
 
1338
- def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
1173
+ def _answer_route(self, op, operation, args, query, query_all, body, sent, headers, url, hosts) -> Response:
1339
1174
  router, state, handlers = self.router, self.state, self.handlers
1175
+ default_host, link_host = hosts
1340
1176
  host = headers.get("host") or default_host
1341
1177
  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
1178
+ origin = f"{forwarded}://{host}"
1179
+ link = PageLink.of(f"{origin}{url.path}", query_all, self.calls.redaction.credential_params)
1180
+ signing = f"{forwarded}://{link_host or host}"
1181
+ ctx = ApiContext(state, router, operation, link=link, door=self.door, origin=origin, signing_origin=signing)
1182
+ ctx.headers, ctx.query_all = headers, query_all
1183
+ ctx.raw, ctx.files = sent.raw, sent.files
1345
1184
  request = (ctx, args, query, body)
1346
1185
  gate = self.settings.before or BEFORE
1347
1186
  verdict = handled_answer(gate, handlers[BEFORE], request, None) if BEFORE in handlers else None
@@ -1349,124 +1188,16 @@ class WorldApp:
1349
1188
  return verdict
1350
1189
  if op.action == "handler":
1351
1190
  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)
1191
+ return normalize_answer(DeclaredRoute(op, operation, ctx, args, query, body).answer(), op.status)
1458
1192
 
1459
1193
 
1460
1194
  def make_handler(state: WorldState, router: Router, key: str | None, admin: AdminToken | None = None):
1461
1195
  app = WorldApp(state, router, key, admin=admin or AdminToken())
1462
1196
 
1463
- class Handler(BaseHTTPRequestHandler):
1197
+ class Handler(WorldRequestHandler):
1464
1198
  server_version = f"gateway-world-api/{router.spec.slug}"
1465
1199
 
1466
- def log_message(self, *_):
1467
- pass
1468
-
1469
- def _serve(self, method: str) -> None:
1200
+ def _dispatch(self, method: str) -> None:
1470
1201
  length = int(self.headers.get("Content-Length") or 0)
1471
1202
  raw = self.rfile.read(length) if length else b""
1472
1203
  headers = {k.lower(): v for k, v in self.headers.items()}
@@ -1475,21 +1206,6 @@ def make_handler(state: WorldState, router: Router, key: str | None, admin: Admi
1475
1206
  status, body, extra = app.handle(method, self.path, headers, raw, default_host, via=None)
1476
1207
  send_response(self, status, body, extra, app.settings.error_content_type)
1477
1208
 
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
1209
  return Handler
1494
1210
 
1495
1211
 
@@ -1556,20 +1272,7 @@ def serve_forever(
1556
1272
 
1557
1273
 
1558
1274
  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
- }
1275
+ security_scheme = spec.auth.scheme.security_scheme(settings.token_path if settings else None)
1573
1276
  paths: dict[str, dict] = {}
1574
1277
  for operation in spec.operations.values():
1575
1278
  op = settings.for_operation(operation.name) if settings else OperationSettings()