@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.
- package/README.md +4 -3
- package/dist/cli.js +3005 -1401
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2996 -1392
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +128 -37
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +126 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +124 -11
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +124 -11
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
- package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
- package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
- package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1078 -260
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1040 -251
- package/dist/index.mjs.map +1 -1
- package/dist/replay/index.d.mts +1 -1
- package/dist/replay/index.d.ts +1 -1
- package/dist/replay/index.js.map +1 -1
- package/dist/replay/index.mjs.map +1 -1
- package/dist/traces/index.js +125 -34
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +123 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +7 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +7 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +819 -438
- package/dist/worlds/index.d.ts +819 -438
- package/dist/worlds/index.js +912 -236
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +908 -232
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +4 -6
- package/runtime/gatewaysdk/environment/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +82 -66
- package/runtime/gatewaysdk/environment/backing.py +20 -24
- package/runtime/gatewaysdk/environment/core.py +1 -16
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
- package/runtime/gatewaysdk/environment/runtime.py +45 -2
- package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +198 -474
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
- package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
- package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
- package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
- package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
- package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
- package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
- package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
- package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
- package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
- package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
- package/runtime/gatewaysdk/environment/schema/data.py +14 -13
- package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
- package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
- package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
- package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
- package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
- package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
- package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
- package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
- package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
- package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
- package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +32 -116
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
- package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
- package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
- package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
- package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
- package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
- package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
- package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
- package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
- package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
- package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
- package/runtime/gatewaysdk/environment/world.py +1 -1
- package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +50 -28
- package/skills/connector-schema-authoring/connector-worlds.md +282 -18
- package/skills/connector-schema-authoring/world-schema.md +7 -6
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +20 -22
- package/skills/worlds-getting-started/SKILL.md +25 -25
- package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/skills/worlds-getting-started/references/gotchas.md +71 -7
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
|
@@ -1,7 +1,4 @@
|
|
|
1
|
-
"""
|
|
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
|
-
"""
|
|
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
|
-
"""
|
|
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
|
-
"""
|
|
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
|
|
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
|
+
)
|