@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.
- package/README.md +4 -3
- package/dist/cli.js +2221 -962
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2212 -953
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +81 -19
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +79 -17
- 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.d.mts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +903 -221
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +868 -212
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +78 -16
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +76 -14
- package/dist/traces/index.mjs.map +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 +692 -410
- package/dist/worlds/index.d.ts +692 -410
- package/dist/worlds/index.js +740 -197
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +736 -193
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +58 -65
- 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/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +174 -471
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
- package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -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 +43 -36
- 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 +25 -4
- 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 +437 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +31 -116
- package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
- 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 +129 -176
- 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/SKILL.md +31 -6
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
- 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 +84 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
- 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 +953 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -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/SKILL.md +31 -6
- package/skills/connector-schema-authoring/connector-worlds.md +129 -7
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +13 -13
- package/skills/worlds-getting-started/SKILL.md +23 -23
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
"""A route its declaration answers alone: ``[operations.api]`` action ``read``,
|
|
2
|
+
``create``, ``update`` or ``delete`` over the route's entity, no handler.
|
|
3
|
+
|
|
4
|
+
Its rows are the ones its filter selects: a declared ``filter``, else each path
|
|
5
|
+
segment naming a field of the entity, and for a read each query parameter naming
|
|
6
|
+
one. They are read through the store's selection (``WorldDatabase.select``), so a
|
|
7
|
+
keyed or related read decodes its page and never every row of the entity.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import json
|
|
13
|
+
from typing import TYPE_CHECKING, Any
|
|
14
|
+
|
|
15
|
+
from .database.matching import RowMatch, dig
|
|
16
|
+
from .envelope import Page, Paging, page_headers, single, wrap
|
|
17
|
+
from .validation import ContractError
|
|
18
|
+
|
|
19
|
+
if TYPE_CHECKING:
|
|
20
|
+
from .api import ApiContext, OperationSettings
|
|
21
|
+
from .connector import Operation
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class MisdeclaredRoute(ContractError):
|
|
25
|
+
"""A declared route that cannot answer the request it took: the world author's bug, answered
|
|
26
|
+
as one (the 400 a handler's bug gets), never as the contract refusing the caller's write."""
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class DeclaredRoute:
|
|
30
|
+
"""One request to a declared route; :meth:`answer` is its action's answer."""
|
|
31
|
+
|
|
32
|
+
def __init__(
|
|
33
|
+
self,
|
|
34
|
+
op: OperationSettings,
|
|
35
|
+
operation: Operation,
|
|
36
|
+
ctx: ApiContext,
|
|
37
|
+
args: dict[str, str],
|
|
38
|
+
query: dict[str, str],
|
|
39
|
+
body: Any,
|
|
40
|
+
) -> None:
|
|
41
|
+
self.op = op
|
|
42
|
+
self.operation = operation
|
|
43
|
+
self.ctx = ctx
|
|
44
|
+
self.args = args
|
|
45
|
+
self.query = query
|
|
46
|
+
self.body = body
|
|
47
|
+
self.entity = operation.entity or ""
|
|
48
|
+
|
|
49
|
+
def answer(self) -> Any:
|
|
50
|
+
if not self.operation.entity:
|
|
51
|
+
return 501, {"error": "not_modelled", "operation": self.operation.name}
|
|
52
|
+
return ACTIONS[self.op.action](self)
|
|
53
|
+
|
|
54
|
+
def _create(self) -> Any:
|
|
55
|
+
return self.op.status, self._one(self.ctx.insert(self.entity, self._bound(self.body)))
|
|
56
|
+
|
|
57
|
+
def _read(self) -> Any:
|
|
58
|
+
match = self._match()
|
|
59
|
+
if self.op.single:
|
|
60
|
+
rows, _ = self.ctx.select(self.entity, match, limit=1)
|
|
61
|
+
return (
|
|
62
|
+
(self.op.status, single(rows[0], self.op.envelope, self.op.wrapper)) if rows else self.ctx.not_found()
|
|
63
|
+
)
|
|
64
|
+
paging = self._paging()
|
|
65
|
+
offset, limit = paging.window(self.query)
|
|
66
|
+
rows, total = self.ctx.select(self.entity, match, limit=limit, offset=offset)
|
|
67
|
+
page = Page.of(rows, total, offset, limit, paging.style)
|
|
68
|
+
settings = self.ctx.settings
|
|
69
|
+
body = wrap(
|
|
70
|
+
page,
|
|
71
|
+
settings,
|
|
72
|
+
self.op.envelope,
|
|
73
|
+
paging=paging,
|
|
74
|
+
link=self.ctx.page_link,
|
|
75
|
+
omit_done_cursor=settings.omits_done_cursor(self.op),
|
|
76
|
+
wrapper=self.op.wrapper,
|
|
77
|
+
)
|
|
78
|
+
return self.op.status, body, page_headers(page, settings, paging, self.ctx.page_link)
|
|
79
|
+
|
|
80
|
+
def _update(self) -> Any:
|
|
81
|
+
row = self._only()
|
|
82
|
+
if row is None:
|
|
83
|
+
return self.ctx.not_found()
|
|
84
|
+
written = self.ctx.update(self.entity, self.ctx.key_of(self.entity, row), self._bound(self.body, current=row))
|
|
85
|
+
return self.op.status, self._one(written)
|
|
86
|
+
|
|
87
|
+
def _delete(self) -> Any:
|
|
88
|
+
row = self._only()
|
|
89
|
+
if row is None:
|
|
90
|
+
return self.ctx.not_found()
|
|
91
|
+
self.ctx.delete(self.entity, self.ctx.key_of(self.entity, row))
|
|
92
|
+
return self.op.status, None
|
|
93
|
+
|
|
94
|
+
def _only(self) -> dict | None:
|
|
95
|
+
"""The one row the route writes, or None when its filter selects none or several."""
|
|
96
|
+
rows, total = self.ctx.select(self.entity, self._match(), limit=1)
|
|
97
|
+
return rows[0] if total == 1 else None
|
|
98
|
+
|
|
99
|
+
def _match(self) -> RowMatch:
|
|
100
|
+
op, operation = self.op, self.operation
|
|
101
|
+
selection = op.filter or self._segment_filter()
|
|
102
|
+
if not selection and (op.action in ("update", "delete") or (op.single and operation.placeholders)):
|
|
103
|
+
raise MisdeclaredRoute(
|
|
104
|
+
"spec",
|
|
105
|
+
f"route {operation.name} finds its row by nothing: its path names no field of {self.entity} and it "
|
|
106
|
+
"declares no api.filter; map a path argument to a field with api.filter, or answer the route with "
|
|
107
|
+
'action = "handler"',
|
|
108
|
+
schema_path=f"/operations/{operation.name}/api/filter",
|
|
109
|
+
)
|
|
110
|
+
filters = selection
|
|
111
|
+
if not op.filter and op.action == "read":
|
|
112
|
+
filters = {**self._query_field_filter(), **filters}
|
|
113
|
+
# Every value sent filters: ``status[]=a&status[]=b`` reads as either, never as a with b dropped.
|
|
114
|
+
values: dict[str, str | list[str]] = {
|
|
115
|
+
**{k: v for k, v in self.ctx.query_all.items() if k in operation.params or k in filters},
|
|
116
|
+
**self.args,
|
|
117
|
+
}
|
|
118
|
+
return RowMatch(filters, values, op.match or {})
|
|
119
|
+
|
|
120
|
+
def _segment_filter(self) -> dict[str, str]:
|
|
121
|
+
"""The filter a route with no ``filter`` of its own implies: each ``{segment}`` of its
|
|
122
|
+
path that names a top-level field of its entity narrows to the rows carrying that value
|
|
123
|
+
(``GET /wallets/{id}``, ``GET /records/by-email/{email}``). A segment naming no field
|
|
124
|
+
(``/users/{userId}/labels``, a scope the caller must send) implies nothing; a declared
|
|
125
|
+
``filter`` says it all itself. Twin: ``route_bindings.implied_filters``."""
|
|
126
|
+
fields = self.ctx.fields_of(self.entity)
|
|
127
|
+
return {name: name for name in self.operation.placeholders if name in fields}
|
|
128
|
+
|
|
129
|
+
def _query_field_filter(self) -> dict[str, str]:
|
|
130
|
+
"""What a read route with no ``filter`` implies from its query string: each
|
|
131
|
+
parameter that names a top-level field of the entity narrows to rows carrying
|
|
132
|
+
that value (``GET /accounts?status=frozen``), the way every vendor's list
|
|
133
|
+
endpoint reads. Paging parameters and names the entity does not declare are
|
|
134
|
+
left to the pager and the handler."""
|
|
135
|
+
fields = self.ctx.fields_of(self.entity)
|
|
136
|
+
skipped = self.ctx.settings.paging.params
|
|
137
|
+
return {name: name for name in self.ctx.query_all if name in fields and name not in skipped}
|
|
138
|
+
|
|
139
|
+
def _paging(self) -> Paging:
|
|
140
|
+
default = self.ctx.settings.paging
|
|
141
|
+
if self.op.paging is None:
|
|
142
|
+
return default
|
|
143
|
+
return Paging(
|
|
144
|
+
self.op.paging, default.limit_param, default.offset_param, default.cursor_param, default.page_size
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
def _one(self, row: dict) -> Any:
|
|
148
|
+
"""A written row answered the route's way: alone (at its own envelope), or as a list of one."""
|
|
149
|
+
if self.op.single:
|
|
150
|
+
return single(row, self.op.envelope, self.op.wrapper)
|
|
151
|
+
return wrap([row], self.ctx.settings, self.op.envelope, wrapper=self.op.wrapper)
|
|
152
|
+
|
|
153
|
+
def _bound(self, body: Any, current: dict | None = None) -> dict:
|
|
154
|
+
"""The row a create or update writes: defaults, then the body (mapped or as-is), then generated fields."""
|
|
155
|
+
sent = body if isinstance(body, dict) else {}
|
|
156
|
+
row: dict = json.loads(json.dumps(self.op.defaults)) if current is None else {}
|
|
157
|
+
self._fill(row, sent, current)
|
|
158
|
+
if current is None:
|
|
159
|
+
self._generate(row)
|
|
160
|
+
return row
|
|
161
|
+
|
|
162
|
+
def _fill(self, row: dict, body: dict, current: dict | None) -> None:
|
|
163
|
+
if not self.op.body:
|
|
164
|
+
row.update(body)
|
|
165
|
+
return
|
|
166
|
+
for field_name, path in self.op.body.items():
|
|
167
|
+
value = dig(body, path)
|
|
168
|
+
if value is not None:
|
|
169
|
+
_assign(row, field_name, value, current)
|
|
170
|
+
|
|
171
|
+
def _generate(self, row: dict) -> None:
|
|
172
|
+
for field_name, kind in self.op.generate.items():
|
|
173
|
+
if row.get(field_name) is None:
|
|
174
|
+
row[field_name] = GENERATED[kind](self, field_name)
|
|
175
|
+
|
|
176
|
+
def _next_int(self, field_name: str) -> int:
|
|
177
|
+
existing = [r.get(field_name) for r in self.ctx.rows(self.entity)]
|
|
178
|
+
return max([v for v in existing if isinstance(v, int)] + [0]) + 1
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
ACTIONS = {
|
|
182
|
+
"read": DeclaredRoute._read,
|
|
183
|
+
"create": DeclaredRoute._create,
|
|
184
|
+
"update": DeclaredRoute._update,
|
|
185
|
+
"delete": DeclaredRoute._delete,
|
|
186
|
+
}
|
|
187
|
+
GENERATED = {
|
|
188
|
+
"uuid": lambda route, _field: route.ctx.uuid(),
|
|
189
|
+
"now": lambda route, _field: route.ctx.now(),
|
|
190
|
+
"int": DeclaredRoute._next_int,
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _assign(row: dict, target: str, value: Any, current: dict | None) -> None:
|
|
195
|
+
"""Assign a dotted target (``attributes.note``), keeping the rest of a nested
|
|
196
|
+
object an update leaves alone."""
|
|
197
|
+
parts = target.split(".")
|
|
198
|
+
if len(parts) == 1:
|
|
199
|
+
row[target] = value
|
|
200
|
+
return
|
|
201
|
+
head = parts[0]
|
|
202
|
+
if head not in row:
|
|
203
|
+
base = current.get(head) if current else None
|
|
204
|
+
row[head] = json.loads(json.dumps(base)) if isinstance(base, dict) else {}
|
|
205
|
+
node = row[head]
|
|
206
|
+
for part in parts[1:-1]:
|
|
207
|
+
if not isinstance(node.get(part), dict):
|
|
208
|
+
node[part] = {}
|
|
209
|
+
node = node[part]
|
|
210
|
+
node[parts[-1]] = value
|