@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
@@ -1,7 +1,4 @@
1
- """A contract-less mock-tools world's state: one raw SQLite file built from
2
- ``db/schema.sql`` + ``db/seed.sql``. Its handlers write SQL through ``conn`` and
3
- its seeds are SQL text, so it is SQLite by definition and stays outside the
4
- contract-bound :class:`~gatewaysdk.environment.schema.database.WorldDatabase`."""
1
+ """Handlers write SQL through ``conn`` and seeds are SQL text, so a mock-tools world is SQLite by definition."""
5
2
 
6
3
  from __future__ import annotations
7
4
 
@@ -10,7 +7,7 @@ import sqlite3
10
7
  import tempfile
11
8
  from contextlib import AbstractContextManager, nullcontext
12
9
  from pathlib import Path
13
- from typing import Any, Dict, List, Optional
10
+ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
14
11
 
15
12
  from .backing import WorldBacking
16
13
  from .errors import VerifierError, WorldStartError
@@ -19,6 +16,9 @@ from .schema.database import SQLiteWorldDatabase
19
16
  from .schema.database.runtime_rows import CONVERSATION_EVENTS, RUN_PARAMETERS, TASK_CONTEXT, RuntimeRows, Statement
20
17
  from .schema.validation import fail
21
18
 
19
+ if TYPE_CHECKING:
20
+ from .schema.journal import JournalDatabase, JournalUse
21
+
22
22
  MODES = ("append", "replace")
23
23
  #: Undoing a failed runtime write: the outermost savepoint is the transaction, and its RELEASE is the
24
24
  #: commit, so a busy RELEASE must be answered with ROLLBACK or the connection stays inside it.
@@ -67,12 +67,7 @@ def _check_row(columns: List[str], table: str, index: int, row: dict) -> None:
67
67
 
68
68
 
69
69
  def seed_statements(columns: Dict[str, List[str]], rows: Rows, mode: str = "append") -> List[str]:
70
- """SQL text that seeds ``rows`` into tables with these ``columns``.
71
-
72
- ``append`` writes ``INSERT OR REPLACE`` (an upsert by the table's own
73
- primary key); ``replace`` prefixes ``DELETE FROM`` for each named table and
74
- writes plain inserts.
75
- """
70
+ """``append`` upserts by each table's own primary key; ``replace`` first empties only the tables ``rows`` names."""
76
71
  if mode not in MODES:
77
72
  fail("mode", f"mode must be one of {', '.join(MODES)}", "/mode")
78
73
  _check_rows(columns, rows)
@@ -94,7 +89,6 @@ def _insert(verb: str, table: str, row: dict) -> str:
94
89
 
95
90
 
96
91
  def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
97
- """Every user table's columns, in declaration order."""
98
92
  tables = [
99
93
  row[0]
100
94
  for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
@@ -103,11 +97,6 @@ def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
103
97
 
104
98
 
105
99
  def seed_sqlite(conn: sqlite3.Connection, rows: Rows, mode: str = "append") -> Dict[str, int]:
106
- """Execute the seed for ``rows`` against a live sqlite, in one transaction.
107
-
108
- Columns come from the live database itself. A refused row rolls the whole
109
- seed back. Returns the row count of every touched table afterwards.
110
- """
111
100
  statements = seed_statements(columns_of(conn), rows, mode)
112
101
  try:
113
102
  conn.execute("BEGIN")
@@ -121,7 +110,6 @@ def seed_sqlite(conn: sqlite3.Connection, rows: Rows, mode: str = "append") -> D
121
110
 
122
111
 
123
112
  def schema_columns(schema: Path) -> Dict[str, List[str]]:
124
- """The tables and columns ``db/schema.sql`` declares, loaded in memory."""
125
113
  with sqlite3.connect(":memory:") as probe:
126
114
  try:
127
115
  probe.executescript(schema.read_text(encoding="utf-8"))
@@ -131,7 +119,6 @@ def schema_columns(schema: Path) -> Dict[str, List[str]]:
131
119
 
132
120
 
133
121
  def materialize(schema: Path, seed: Path, destination: Path) -> None:
134
- """``db/schema.sql`` then ``db/seed.sql`` (each when present) into a new file."""
135
122
  conn = sqlite3.connect(destination)
136
123
  try:
137
124
  if schema.is_file():
@@ -146,8 +133,7 @@ def materialize(schema: Path, seed: Path, destination: Path) -> None:
146
133
 
147
134
 
148
135
  class LegacySQLiteBacking(WorldBacking):
149
- """A mock-tools world's raw connection: handlers read and write through it,
150
- autocommit, across threads (agents call tools from worker threads)."""
136
+ """Autocommit, shared across threads: agents call tools from worker threads."""
151
137
 
152
138
  def __init__(self, path: Path, contract: Optional[Contract] = None) -> None:
153
139
  self.path = Path(path)
@@ -172,6 +158,12 @@ class LegacySQLiteBacking(WorldBacking):
172
158
  )
173
159
  return [dict(row) for row in self._conn.execute(sql, params).fetchall()]
174
160
 
161
+ def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
162
+ """A legacy tools world keeps no journal: its verifiers read none."""
163
+ from .schema.journal import JournalUse
164
+
165
+ return nullcontext(lambda statements: JournalUse.none())
166
+
175
167
  def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
176
168
  try:
177
169
  cursor = self._conn.execute(statement)
@@ -197,11 +189,9 @@ class LegacySQLiteBacking(WorldBacking):
197
189
  }
198
190
 
199
191
  def seed(self, rows: Rows, mode: str = "append") -> Dict[str, int]:
200
- """:func:`seed_sqlite` into this world's live file."""
201
192
  return seed_sqlite(self._conn, rows, mode)
202
193
 
203
194
  def entities(self) -> Rows:
204
- """Every table's rows, tables by name."""
205
195
  return {
206
196
  table: [dict(row) for row in self._conn.execute(f"SELECT * FROM {quote(table)}")]
207
197
  for table in sorted(self.columns())
@@ -218,7 +208,6 @@ class LegacySQLiteBacking(WorldBacking):
218
208
  return found.fetchone() is not None
219
209
 
220
210
  def _write_runtime(self, table: str, statements: list[Statement]) -> bool:
221
- """The store's runtime statements, all or none, where the world declares ``table``."""
222
211
  if not self._declares(table):
223
212
  return False
224
213
  outer = not self._conn.in_transaction
@@ -261,15 +250,13 @@ class LegacySQLiteBacking(WorldBacking):
261
250
 
262
251
 
263
252
  class LegacyVerifiers:
264
- """A db/schema.sql world's ``verifiers/*.sql``, each scored by :class:`SqlVerifier`'s rule
265
- against its own copy of the seeded state, so no verifier sees another's writes."""
253
+ """Each verifier scores its own copy of the seeded state, so no verifier sees another's writes."""
266
254
 
267
255
  def __init__(self, root: Path) -> None:
268
256
  self.root = Path(root)
269
257
  self.paths = sorted((self.root / "verifiers").glob("*.sql"))
270
258
 
271
259
  def scores(self) -> List[Dict[str, Any]]:
272
- """``{path, ok, score[, error]}`` per verifier; a world that does not build fails every one."""
273
260
  schema = self.root / "db" / "schema.sql"
274
261
  if not schema.is_file():
275
262
  return [self._refused(path, "db/schema.sql is missing") for path in self.paths]
@@ -24,12 +24,16 @@ falls back to discovery by function name == served tool name.
24
24
  from __future__ import annotations
25
25
 
26
26
  import re
27
+ import sys
28
+ from contextlib import contextmanager
27
29
  from contextvars import ContextVar
28
- from typing import Any, Callable, Dict, Optional
30
+ from types import ModuleType
31
+ from typing import Any, Callable, Dict, Iterator, Optional
29
32
 
33
+ from .schema.handler_errors import Refusal
30
34
  from .schema.store_contract import STORE_METHOD_NAMES, unknown_store_method_detail
31
35
 
32
- __all__ = ["tool", "db", "store"]
36
+ __all__ = ["tool", "db", "store", "webhooks", "Refusal"]
33
37
 
34
38
  _active_connection: ContextVar[Optional[Any]] = ContextVar("gateway_env_active_connection", default=None)
35
39
 
@@ -38,6 +42,7 @@ _load_registry: ContextVar[Optional[Dict[str, Callable[..., Any]]]] = ContextVar
38
42
  )
39
43
 
40
44
  _active_store: ContextVar[Any] = ContextVar("gateway_env_active_store", default=None)
45
+ _active_webhooks: ContextVar[Any] = ContextVar("gateway_env_active_webhooks", default=None)
41
46
  _strict_registration: ContextVar[bool] = ContextVar("gateway_env_strict_registration", default=False)
42
47
 
43
48
 
@@ -59,6 +64,21 @@ class _Store:
59
64
 
60
65
  store = _Store()
61
66
 
67
+
68
+ class _Webhooks:
69
+ """``deliver`` binds to the world whose tool is executing (:class:`~.schema.webhooks.WebhookOutbox`)."""
70
+
71
+ def deliver(
72
+ self, event_type: str, body: Any, scope: Optional[Dict[str, Any]] = None, event_id: Optional[str] = None
73
+ ) -> list[str]:
74
+ active = _active_webhooks.get()
75
+ if active is None:
76
+ raise RuntimeError("gateway_env.webhooks.deliver requires an executing tool in a schema-backed world")
77
+ return active.deliver(event_type, body, scope, event_id)
78
+
79
+
80
+ webhooks = _Webhooks()
81
+
62
82
  _IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
63
83
 
64
84
 
@@ -147,3 +167,26 @@ def tool(fn: Optional[Callable[..., Any]] = None, *, name: Optional[str] = None)
147
167
  return register(handler, name or handler.__name__)
148
168
 
149
169
  return decorator
170
+
171
+
172
+ @contextmanager
173
+ def installed(module: ModuleType) -> Iterator[None]:
174
+ """``gateway_env`` names ``module`` for a handler load's dynamic extent, and whatever it named before after."""
175
+ saved = sys.modules.get("gateway_env")
176
+ sys.modules["gateway_env"] = module
177
+ try:
178
+ yield
179
+ finally:
180
+ if saved is None:
181
+ sys.modules.pop("gateway_env", None)
182
+ else:
183
+ sys.modules["gateway_env"] = saved
184
+
185
+
186
+ def route_module() -> ModuleType:
187
+ """What a route handler may import: ``Refusal`` alone; ``store``, ``db`` and ``tool`` belong to tools."""
188
+ module = ModuleType("gateway_env")
189
+ module.Refusal = Refusal
190
+ module.__all__ = ["Refusal"]
191
+ return module
192
+
@@ -0,0 +1,174 @@
1
+ """``Admission``: how many requests run on one version at once, and how many wait.
2
+
3
+ Every session of a version is served by one process (its version worker, or the
4
+ host itself for a world with no code of its own), so a burst on a version is a
5
+ burst on that process. The host admits a version's requests a few at a time and
6
+ one per session (a session's store answers one request at a time anyway); the
7
+ rest wait their turn in the order they came, up to a bound. A request past the
8
+ bound, or one whose turn did not come in time, is refused ``busy`` with when to
9
+ come back, so a burst queues or is told to retry and the process never holds
10
+ more requests than it has room for. A request held outside the queue (its session moving to
11
+ another host) is counted against the same bounds (:meth:`Admission.waiting`).
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import threading
17
+ import time
18
+ from collections import Counter, deque
19
+ from collections.abc import Iterator
20
+ from contextlib import contextmanager
21
+ from dataclasses import dataclass
22
+
23
+ from .validation import fail
24
+
25
+ VERSION_SLOTS = 8
26
+ SESSION_SLOTS = 1
27
+ QUEUE_DEPTH = 256
28
+ #: A session's own share of the waiting, so one session's burst cannot fill its version's queue.
29
+ SESSION_QUEUE_DEPTH = 32
30
+ #: With a call's own budget it stays under the platform's 60 s (``conformance/world-sessions.json``).
31
+ QUEUE_WAIT_S = 10.0
32
+ RETRY_AFTER_S = 1
33
+ BUSY = "busy"
34
+
35
+
36
+ def _less(counter: Counter, key: object) -> None:
37
+ counter[key] -= 1
38
+ if counter[key] <= 0:
39
+ del counter[key]
40
+
41
+
42
+ @dataclass(eq=False)
43
+ class _Turn:
44
+ version: str
45
+ session: str
46
+ started: float | None = None
47
+
48
+
49
+ class Admission:
50
+ """Turns on each version, first come first served within the version's and
51
+ each session's slots; another version never waits."""
52
+
53
+ def __init__(
54
+ self,
55
+ *,
56
+ slots: int = VERSION_SLOTS,
57
+ per_session: int = SESSION_SLOTS,
58
+ queue: int = QUEUE_DEPTH,
59
+ session_queue: int = SESSION_QUEUE_DEPTH,
60
+ wait_s: float = QUEUE_WAIT_S,
61
+ retry_after_s: int = RETRY_AFTER_S,
62
+ ) -> None:
63
+ self.slots = slots
64
+ self.per_session = per_session
65
+ self.queue = queue
66
+ self.session_queue = session_queue
67
+ self.wait_s = wait_s
68
+ self.retry_after_s = retry_after_s
69
+ self._lock = threading.Lock()
70
+ self._changed = threading.Condition(self._lock)
71
+ self._running: Counter[str] = Counter()
72
+ self._holding: dict[tuple[str, str], list[_Turn]] = {}
73
+ self._waiting: dict[str, deque[_Turn]] = {}
74
+ self._outside: Counter[str] = Counter()
75
+ self._outside_by: Counter[tuple[str, str]] = Counter()
76
+
77
+ @contextmanager
78
+ def turn(self, version: str, session: str) -> Iterator[None]:
79
+ """Hold one of ``version``'s slots for ``session`` while the block runs; refused
80
+ ``busy`` (a :class:`ContractError` carrying ``retryAfter``) when none comes."""
81
+ turn = self._enter(_Turn(version, session))
82
+ try:
83
+ yield
84
+ finally:
85
+ self._leave(turn)
86
+
87
+ @contextmanager
88
+ def waiting(self, version: str, session: str) -> Iterator[None]:
89
+ """Count a request waiting outside the queue against ``version``'s and ``session``'s waiting
90
+ bounds while the block runs; refused ``busy`` past them, as a queued request would be."""
91
+ with self._lock:
92
+ self._outside[version] += 1
93
+ self._outside_by[(version, session)] += 1
94
+ if self._overfull(version, session):
95
+ self._unwait(version, session)
96
+ self._refuse(version, "too many requests are waiting")
97
+ try:
98
+ yield
99
+ finally:
100
+ with self._lock:
101
+ self._unwait(version, session)
102
+
103
+ def _unwait(self, version: str, session: str) -> None:
104
+ _less(self._outside, version)
105
+ _less(self._outside_by, (version, session))
106
+
107
+ def held_ages(self) -> dict[str, float]:
108
+ """Each session holding a turn now, with how long its oldest has run, in seconds."""
109
+ now = time.monotonic()
110
+ with self._lock:
111
+ return {
112
+ session: now - min(turn.started for turn in turns if turn.started is not None)
113
+ for (_, session), turns in self._holding.items()
114
+ if turns
115
+ }
116
+
117
+ def _enter(self, turn: _Turn) -> _Turn:
118
+ with self._lock:
119
+ queue = self._waiting.setdefault(turn.version, deque())
120
+ queue.append(turn)
121
+ self._admit(turn.version)
122
+ if turn.started is None and self._overfull(turn.version, turn.session):
123
+ queue.remove(turn)
124
+ self._refuse(turn.version, f"{len(queue)} requests are waiting")
125
+ deadline = time.monotonic() + self.wait_s
126
+ while turn.started is None:
127
+ left = deadline - time.monotonic()
128
+ if left <= 0:
129
+ queue.remove(turn)
130
+ self._refuse(turn.version, f"no turn came within {self.wait_s:g} s")
131
+ self._changed.wait(left)
132
+ return turn
133
+
134
+ def _overfull(self, version: str, session: str) -> bool:
135
+ queue = self._waiting.get(version, deque())
136
+ mine = sum(waiting.session == session for waiting in queue) + self._outside_by[(version, session)]
137
+ return len(queue) + self._outside[version] > self.queue or mine > self.session_queue
138
+
139
+ def _leave(self, turn: _Turn) -> None:
140
+ with self._lock:
141
+ key = (turn.version, turn.session)
142
+ self._holding[key].remove(turn)
143
+ if not self._holding[key]:
144
+ del self._holding[key]
145
+ self._running[turn.version] -= 1
146
+ if self._running[turn.version] <= 0:
147
+ del self._running[turn.version]
148
+ self._admit(turn.version)
149
+ self._forget(turn.version)
150
+
151
+ def _admit(self, version: str) -> None:
152
+ """Under the lock: give free slots to the earliest waiters whose session has room."""
153
+ queue = self._waiting.get(version, deque())
154
+ for waiting in list(queue):
155
+ if self._running[version] >= self.slots:
156
+ break
157
+ if len(self._holding.get((version, waiting.session), ())) < self.per_session:
158
+ queue.remove(waiting)
159
+ waiting.started = time.monotonic()
160
+ self._running[version] += 1
161
+ self._holding.setdefault((version, waiting.session), []).append(waiting)
162
+ self._changed.notify_all()
163
+
164
+ def _forget(self, version: str) -> None:
165
+ if not self._waiting.get(version) and not self._running[version]:
166
+ self._waiting.pop(version, None)
167
+
168
+ def _refuse(self, version: str, why: str) -> None:
169
+ self._forget(version)
170
+ fail(
171
+ BUSY,
172
+ f"this world's version is busy ({why}); retry after {self.retry_after_s} s",
173
+ retryAfter=self.retry_after_s,
174
+ )