@withgateway/sdk 0.9.1 → 0.9.3
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/dist/agents/index.d.mts +12 -4
- package/dist/agents/index.d.ts +12 -4
- package/dist/agents/index.js +30 -0
- package/dist/agents/index.js.map +1 -1
- package/dist/agents/index.mjs +30 -0
- package/dist/agents/index.mjs.map +1 -1
- package/dist/cli.js +2291 -945
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2290 -944
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs.map +1 -1
- package/dist/index.js +325 -184
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +324 -183
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +1 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +1 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +3 -1
- package/dist/worlds/index.d.ts +3 -1
- package/dist/worlds/index.js +178 -67
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +177 -66
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/bundle_manifest.py +297 -9
- package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
- package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
- package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
- package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
- package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
- package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
- package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
- package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
- package/runtime/gatewaysdk/environment/schema/host.py +21 -2
- package/runtime/gatewaysdk/environment/schema/host_control.py +3 -1
- package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
- package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +21 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +7 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +4 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
- package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
- package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
- package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +57 -3
- package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
- package/runtime/gatewaysdk/environment/schema/platform_templates.py +105 -17
- package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
- package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +14 -0
- package/runtime/gatewaysdk/environment/schema/scaffold.py +21 -4
- package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
- package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
- package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -4
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +14 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +7 -4
- package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +237 -68
- package/runtime/gatewaysdk/environment/schema/world_host.py +56 -62
- package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
- package/skills/connector-schema-authoring/SKILL.md +1 -0
- package/skills/connector-schema-authoring/connector-worlds.md +1 -0
- package/skills/connector-schema-authoring/world-schema.md +7 -0
- package/skills/factory-orchestrator/SKILL.md +147 -0
- package/skills/world-data-ingestion/ROWS.md +5 -1
- package/skills/world-data-ingestion/SKILL.md +4 -4
- package/skills/worlds-getting-started/SKILL.md +2 -2
- package/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
- package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
|
@@ -296,12 +296,13 @@ class WorldTemplate:
|
|
|
296
296
|
) -> Contract:
|
|
297
297
|
tools = sorted(world["x-gateway"].get("tools") or {})
|
|
298
298
|
entity = min(world["x-gateway"]["entities"])
|
|
299
|
-
(destination
|
|
300
|
-
(destination / "schema/world.json").write_bytes(_pretty(world))
|
|
301
|
-
shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
|
|
299
|
+
self._lay_out_schema(destination, world, placed)
|
|
302
300
|
(destination / "tools").mkdir()
|
|
303
301
|
(destination / "tools/handlers.py").write_bytes(self._handlers())
|
|
304
|
-
_write(
|
|
302
|
+
_write(
|
|
303
|
+
destination,
|
|
304
|
+
{target: content for target, content in placed.items() if not _carried(target) and not _schema(target)},
|
|
305
|
+
)
|
|
305
306
|
(destination / "gateway-env.toml").write_text(
|
|
306
307
|
MANIFEST.format(name=name, connector=connector, serve=", ".join(f'"{t}"' for t in tools)),
|
|
307
308
|
encoding="utf-8",
|
|
@@ -325,6 +326,22 @@ class WorldTemplate:
|
|
|
325
326
|
TemplateRecord.of_world(destination, connector=connector, digest=self.digest).write(destination)
|
|
326
327
|
return contract
|
|
327
328
|
|
|
329
|
+
def lay_out_schema(self, destination: Path) -> None:
|
|
330
|
+
"""The schema documents :meth:`write` resolves (``world.json``, the packaged ``base.json`` and the
|
|
331
|
+
template's own), uncompiled; the package is not renamed and no rendered file is rendered."""
|
|
332
|
+
self._lay_out_schema(destination, self.world(), self._placed(CUSTOM))
|
|
333
|
+
|
|
334
|
+
@staticmethod
|
|
335
|
+
def _lay_out_schema(destination: Path, world: dict, placed: dict[str, bytes]) -> None:
|
|
336
|
+
(destination / "schema").mkdir(parents=True)
|
|
337
|
+
(destination / "schema/world.json").write_bytes(_pretty(world))
|
|
338
|
+
shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
|
|
339
|
+
_write(destination, {target: content for target, content in placed.items() if _schema(target)})
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
def _schema(target: str) -> bool:
|
|
343
|
+
return target.startswith("schema/")
|
|
344
|
+
|
|
328
345
|
|
|
329
346
|
class TemplateWorld(WorldTemplate):
|
|
330
347
|
"""An official world's head as stored: a schema world built from a connector template, whose
|
|
@@ -0,0 +1,493 @@
|
|
|
1
|
+
"""The shape catalog ``describe`` carries. The TypeScript reader is ``WorldShapeCatalog``
|
|
2
|
+
(``packages/shared/src/world/shapeCatalog``), pinned to this builder by
|
|
3
|
+
``conformance/world-shape-catalogs.json``."""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from abc import ABC, abstractmethod
|
|
8
|
+
from dataclasses import dataclass, field, replace
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import TYPE_CHECKING, Any
|
|
11
|
+
|
|
12
|
+
from .cast import FieldType, LocalDefinitions, allowed_values, schema_fields, schema_types
|
|
13
|
+
from .shape_declarations import AnswerDeclaration, dotted_pointer, json_pointer
|
|
14
|
+
from .tree_import import PUBLICATION_FILE_BYTES
|
|
15
|
+
from .validation import ContractError, InlineBudgetExceeded, Resolver, fail, local_references
|
|
16
|
+
|
|
17
|
+
if TYPE_CHECKING:
|
|
18
|
+
from .api import ApiSettings
|
|
19
|
+
from .connector import Operation, Spec
|
|
20
|
+
|
|
21
|
+
CATALOG_VERSION = 1
|
|
22
|
+
DESCRIBE_ENTITY = "describe_entity"
|
|
23
|
+
MAX_DEPTH = 12
|
|
24
|
+
ANNOTATIONS = frozenset(
|
|
25
|
+
{"description", "title", "examples", "example", "$comment", "default", "deprecated", "readOnly", "writeOnly"}
|
|
26
|
+
)
|
|
27
|
+
SCHEMA_MAPS = ("properties", "patternProperties", "$defs", "definitions", "dependentSchemas")
|
|
28
|
+
SCHEMA_ONE = ("items", "additionalProperties", "not", "contains", "propertyNames", "if", "then", "else")
|
|
29
|
+
SCHEMA_MANY = ("allOf", "anyOf", "oneOf", "prefixItems", "items")
|
|
30
|
+
LEGEND = {
|
|
31
|
+
"hash": 'sha256 of "<slug>:<value>", stored as sha256:<hex>; a lookup by plaintext computes the same form',
|
|
32
|
+
"preserve": "a digest that keeps the value's shape: same length, digits stay digits, letters stay letters",
|
|
33
|
+
"round": "the number rounded to n decimals (round:n)",
|
|
34
|
+
"drop": "never stored",
|
|
35
|
+
}
|
|
36
|
+
WRITES = (
|
|
37
|
+
"Capture stores these forms, and an import, seed or upload stores them only when it asks for "
|
|
38
|
+
"--redact apply; every other write, a factory write included, is stored as written."
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def stripped(schema: Any) -> Any:
|
|
43
|
+
if not isinstance(schema, dict):
|
|
44
|
+
return schema
|
|
45
|
+
out: dict = {}
|
|
46
|
+
for key, value in schema.items():
|
|
47
|
+
if key in ANNOTATIONS or key.startswith("x-"):
|
|
48
|
+
continue
|
|
49
|
+
out[key] = _stripped_member(key, value)
|
|
50
|
+
return out
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _stripped_member(key: str, value: Any) -> Any:
|
|
54
|
+
if key in SCHEMA_MAPS and isinstance(value, dict):
|
|
55
|
+
return {name: stripped(child) for name, child in value.items()}
|
|
56
|
+
if key in SCHEMA_MANY and isinstance(value, list):
|
|
57
|
+
return [stripped(child) for child in value]
|
|
58
|
+
if key in SCHEMA_ONE and isinstance(value, dict):
|
|
59
|
+
return stripped(value)
|
|
60
|
+
return value
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def local_refs(schema: Any) -> set[str]:
|
|
64
|
+
return {name for name in local_references(schema) if name} if isinstance(schema, dict) else set()
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
@dataclass(frozen=True)
|
|
68
|
+
class CatalogWorld:
|
|
69
|
+
document: dict
|
|
70
|
+
spec: "Spec | None" = None
|
|
71
|
+
settings: "ApiSettings | None" = None
|
|
72
|
+
answers: dict[str, AnswerDeclaration] = field(default_factory=dict)
|
|
73
|
+
redacted: bool = False
|
|
74
|
+
roots: dict[str, dict] = field(default_factory=dict)
|
|
75
|
+
defs: dict[str, dict] = field(default_factory=dict)
|
|
76
|
+
orders: dict[str, list[str]] = field(default_factory=dict)
|
|
77
|
+
|
|
78
|
+
@classmethod
|
|
79
|
+
def of_bundle(cls, root: Path, **connection: Any) -> "CatalogWorld":
|
|
80
|
+
"""Through the compiler's shared resolver, so a type in a sibling file under ``schema/``
|
|
81
|
+
reads like one in ``world.json`` and every reference left is a local ``#/$defs/<key>``.
|
|
82
|
+
A world the shared form refuses, such as two definitions that share a name, is read
|
|
83
|
+
inlined, the form the compiler builds it in first."""
|
|
84
|
+
try:
|
|
85
|
+
return cls._read(Resolver(root, shared=True), connection)
|
|
86
|
+
except ContractError as refused:
|
|
87
|
+
return cls._inlined(root, connection, refused)
|
|
88
|
+
|
|
89
|
+
@classmethod
|
|
90
|
+
def _inlined(cls, root: Path, connection: dict, refused: ContractError) -> "CatalogWorld":
|
|
91
|
+
try:
|
|
92
|
+
return cls._read(Resolver(root, budget=PUBLICATION_FILE_BYTES), connection)
|
|
93
|
+
except InlineBudgetExceeded:
|
|
94
|
+
raise refused from None
|
|
95
|
+
|
|
96
|
+
@classmethod
|
|
97
|
+
def _read(cls, resolver: Resolver, connection: dict) -> "CatalogWorld":
|
|
98
|
+
document = resolver.load("world.json")
|
|
99
|
+
gateway = document.get("x-gateway") if isinstance(document.get("x-gateway"), dict) else {}
|
|
100
|
+
entities = gateway.get("entities") if isinstance(gateway.get("entities"), dict) else {}
|
|
101
|
+
roots = {
|
|
102
|
+
name: resolver.resolve(_schema_of(entity), "world.json", f"world.json#/x-gateway/entities/{name}/schema")
|
|
103
|
+
for name, entity in sorted(entities.items())
|
|
104
|
+
}
|
|
105
|
+
orders = {name: _authored_properties(resolver, _schema_of(entity)) for name, entity in entities.items()}
|
|
106
|
+
return cls(document, roots=roots, defs=dict(resolver.definitions), orders=orders, **connection)
|
|
107
|
+
|
|
108
|
+
@property
|
|
109
|
+
def entities(self) -> dict[str, dict]:
|
|
110
|
+
gateway = self.document.get("x-gateway")
|
|
111
|
+
entities = gateway.get("entities") if isinstance(gateway, dict) else None
|
|
112
|
+
return entities if isinstance(entities, dict) else {}
|
|
113
|
+
|
|
114
|
+
def resolved(self, schema: Any, seen: frozenset[str] = frozenset()) -> tuple[dict, frozenset[str]]:
|
|
115
|
+
return LocalDefinitions(self.defs)(schema, seen)
|
|
116
|
+
|
|
117
|
+
def root(self, entity: str) -> dict:
|
|
118
|
+
return self.roots.get(entity) or {}
|
|
119
|
+
|
|
120
|
+
def fields(self, entity: str) -> dict[str, Any]:
|
|
121
|
+
properties = self.root(entity).get("properties")
|
|
122
|
+
return properties if isinstance(properties, dict) else {}
|
|
123
|
+
|
|
124
|
+
def declared(self, entity: str, member: str) -> list[dict]:
|
|
125
|
+
listed = (self.entities.get(entity) or {}).get(member)
|
|
126
|
+
return listed if isinstance(listed, list) else []
|
|
127
|
+
|
|
128
|
+
def kinds(self, schema: Any) -> set[str]:
|
|
129
|
+
return set(schema_types(schema, self.resolved))
|
|
130
|
+
|
|
131
|
+
def entity_fields(self) -> dict[str, list[FieldType]]:
|
|
132
|
+
"""In the order the entity's authored schema lists them; the resolver sorts ``properties``."""
|
|
133
|
+
return {
|
|
134
|
+
name: self._authored_order(name, schema_fields(self.root(name), self.resolved))
|
|
135
|
+
for name in sorted(self.entities)
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
def _authored_order(self, entity: str, fields: list[FieldType]) -> list[FieldType]:
|
|
139
|
+
order = {name: index for index, name in enumerate(self.orders.get(entity) or [])}
|
|
140
|
+
return sorted(fields, key=lambda item: order.get(item.name, len(order)))
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def _schema_of(entity: Any) -> Any:
|
|
144
|
+
return entity.get("schema") if isinstance(entity, dict) else None
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def _authored_properties(resolver: Resolver, schema: Any) -> list[str]:
|
|
148
|
+
name, seen = "world.json", set()
|
|
149
|
+
while isinstance(schema, dict) and isinstance(schema.get("$ref"), str) and "properties" not in schema:
|
|
150
|
+
schema, name, key = resolver.reference(schema["$ref"], name, f"{name}#")
|
|
151
|
+
if key in seen:
|
|
152
|
+
break
|
|
153
|
+
seen.add(key)
|
|
154
|
+
properties = schema.get("properties") if isinstance(schema, dict) else None
|
|
155
|
+
return list(properties) if isinstance(properties, dict) else []
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
class CatalogKind(ABC):
|
|
159
|
+
key: str
|
|
160
|
+
|
|
161
|
+
@abstractmethod
|
|
162
|
+
def read(self, world: CatalogWorld) -> Any: ...
|
|
163
|
+
|
|
164
|
+
def narrowed(self, value: Any, entity: str) -> Any:
|
|
165
|
+
return [entry for entry in value if entry.get("entity") == entity]
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
class Enumerations(CatalogKind):
|
|
169
|
+
key = "enumerations"
|
|
170
|
+
|
|
171
|
+
def read(self, world: CatalogWorld) -> list[dict]:
|
|
172
|
+
found: dict[tuple[str, str], dict] = {}
|
|
173
|
+
for entity in sorted(world.entities):
|
|
174
|
+
for name, schema in world.fields(entity).items():
|
|
175
|
+
self._walk(world, entity, schema, [name], frozenset(), found)
|
|
176
|
+
return list(found.values())
|
|
177
|
+
|
|
178
|
+
def _walk(
|
|
179
|
+
self, world: CatalogWorld, entity: str, schema: Any, at: list[str], seen, found: dict, quiet: bool = False
|
|
180
|
+
) -> None:
|
|
181
|
+
"""``quiet``: a branch of a union that also admits other values lists nothing at its own pointer."""
|
|
182
|
+
node, seen = world.resolved(schema, seen)
|
|
183
|
+
if len(at) > MAX_DEPTH:
|
|
184
|
+
return
|
|
185
|
+
allowed = allowed_values(node, world.resolved, seen)
|
|
186
|
+
if allowed is not None and not quiet:
|
|
187
|
+
self._record(found, entity, json_pointer(at), *allowed)
|
|
188
|
+
if allowed is not None:
|
|
189
|
+
return
|
|
190
|
+
for name, child in (node.get("properties") or {}).items():
|
|
191
|
+
self._walk(world, entity, child, [*at, name], seen, found)
|
|
192
|
+
for key in ("items", "additionalProperties"):
|
|
193
|
+
if isinstance(node.get(key), dict):
|
|
194
|
+
self._walk(world, entity, node[key], [*at, "*"], seen, found)
|
|
195
|
+
for key, branch_quiet in (("anyOf", True), ("oneOf", True), ("allOf", quiet)):
|
|
196
|
+
for branch in node.get(key) or []:
|
|
197
|
+
self._walk(world, entity, branch, at, seen, found, branch_quiet)
|
|
198
|
+
|
|
199
|
+
@staticmethod
|
|
200
|
+
def _record(found: dict, entity: str, at: str, values: list, labels: list[dict]) -> None:
|
|
201
|
+
entry = found.setdefault((entity, at), {"entity": entity, "pointer": at, "values": []})
|
|
202
|
+
entry["values"] += [value for value in values if value not in entry["values"]]
|
|
203
|
+
if labels:
|
|
204
|
+
entry.setdefault("labels", [])
|
|
205
|
+
entry["labels"] += [label for label in labels if label not in entry["labels"]]
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
class Columns(CatalogKind):
|
|
209
|
+
key = "columns"
|
|
210
|
+
|
|
211
|
+
def read(self, world: CatalogWorld) -> list[dict]:
|
|
212
|
+
return [
|
|
213
|
+
{"entity": entity, "field": name, "schema": stripped(schema)}
|
|
214
|
+
for entity in sorted(world.entities)
|
|
215
|
+
for name, schema in world.fields(entity).items()
|
|
216
|
+
if world.kinds(schema) & {"object", "array"}
|
|
217
|
+
]
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
class CustomFields(CatalogKind):
|
|
221
|
+
key = "customFields"
|
|
222
|
+
|
|
223
|
+
def read(self, world: CatalogWorld) -> list[dict]:
|
|
224
|
+
return [
|
|
225
|
+
self._entry(world, entity, declared)
|
|
226
|
+
for entity in sorted(world.entities)
|
|
227
|
+
for declared in world.declared(entity, "custom_fields")
|
|
228
|
+
]
|
|
229
|
+
|
|
230
|
+
@staticmethod
|
|
231
|
+
def _entry(world: CatalogWorld, entity: str, declared: dict) -> dict:
|
|
232
|
+
where = dict(declared.get("where") or {})
|
|
233
|
+
definitions = declared["definitions"]
|
|
234
|
+
required = world.root(definitions).get("required") or []
|
|
235
|
+
entry = {
|
|
236
|
+
"entity": entity,
|
|
237
|
+
"field": declared["field"],
|
|
238
|
+
"definitions": definitions,
|
|
239
|
+
"key": declared["key"],
|
|
240
|
+
"where": where,
|
|
241
|
+
}
|
|
242
|
+
if "pairs" in declared:
|
|
243
|
+
entry["pairs"] = dict(declared["pairs"])
|
|
244
|
+
entry["add"] = {
|
|
245
|
+
"entity": definitions,
|
|
246
|
+
"set": where,
|
|
247
|
+
"key": declared["key"],
|
|
248
|
+
"required": [name for name in required if name != declared["key"] and name not in where],
|
|
249
|
+
}
|
|
250
|
+
return entry
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
class Ids(CatalogKind):
|
|
254
|
+
key = "ids"
|
|
255
|
+
|
|
256
|
+
def read(self, world: CatalogWorld) -> list[dict]:
|
|
257
|
+
return [
|
|
258
|
+
self._entry(entity, declared)
|
|
259
|
+
for entity in sorted(world.entities)
|
|
260
|
+
for declared in world.declared(entity, "ids")
|
|
261
|
+
]
|
|
262
|
+
|
|
263
|
+
@staticmethod
|
|
264
|
+
def _entry(entity: str, declared: dict) -> dict:
|
|
265
|
+
entry: dict = {"entity": entity, "pointer": declared["pointer"]}
|
|
266
|
+
if "values" in declared:
|
|
267
|
+
entry["values"] = [{"id": value["id"], "label": value["label"]} for value in declared["values"]]
|
|
268
|
+
return entry
|
|
269
|
+
entry["target"] = {
|
|
270
|
+
"entity": declared["entity"],
|
|
271
|
+
"key": declared["key"],
|
|
272
|
+
"where": dict(declared.get("where") or {}),
|
|
273
|
+
}
|
|
274
|
+
return entry
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
class Sequences(CatalogKind):
|
|
278
|
+
key = "sequences"
|
|
279
|
+
|
|
280
|
+
def read(self, world: CatalogWorld) -> list[dict]:
|
|
281
|
+
found: dict[tuple[str, str], dict] = {}
|
|
282
|
+
for entity, field_name, operation in self._generated(world):
|
|
283
|
+
entry = found.setdefault(
|
|
284
|
+
(entity, field_name),
|
|
285
|
+
{
|
|
286
|
+
"entity": entity,
|
|
287
|
+
"field": field_name,
|
|
288
|
+
"scope": [],
|
|
289
|
+
"start": 1,
|
|
290
|
+
"source": "generate",
|
|
291
|
+
"operations": [],
|
|
292
|
+
},
|
|
293
|
+
)
|
|
294
|
+
entry["operations"].append(operation)
|
|
295
|
+
for entity in sorted(world.entities):
|
|
296
|
+
for declared in world.declared(entity, "sequences"):
|
|
297
|
+
entry = found.setdefault((entity, declared["field"]), {"entity": entity, "field": declared["field"]})
|
|
298
|
+
entry.update(
|
|
299
|
+
scope=list(declared.get("scope") or []),
|
|
300
|
+
start=declared.get("start", 1),
|
|
301
|
+
source="declared",
|
|
302
|
+
operations=entry.get("operations", []),
|
|
303
|
+
)
|
|
304
|
+
return [found[key] for key in sorted(found)]
|
|
305
|
+
|
|
306
|
+
@staticmethod
|
|
307
|
+
def _generated(world: CatalogWorld) -> list[tuple[str, str, str]]:
|
|
308
|
+
if world.spec is None or world.settings is None:
|
|
309
|
+
return []
|
|
310
|
+
return [
|
|
311
|
+
(operation.entity, field_name, operation.name)
|
|
312
|
+
for operation in world.spec.operations.values()
|
|
313
|
+
if operation.entity
|
|
314
|
+
for field_name, generator in world.settings.for_operation(operation.name).generate.items()
|
|
315
|
+
if generator == "int"
|
|
316
|
+
]
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
class Redaction(CatalogKind):
|
|
320
|
+
key = "redaction"
|
|
321
|
+
|
|
322
|
+
def read(self, world: CatalogWorld) -> dict | None:
|
|
323
|
+
return {"legend": dict(LEGEND), "writes": WRITES} if world.redacted else None
|
|
324
|
+
|
|
325
|
+
def narrowed(self, value: Any, entity: str) -> Any:
|
|
326
|
+
return value
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
class Answers(CatalogKind):
|
|
330
|
+
key = "answers"
|
|
331
|
+
|
|
332
|
+
def read(self, world: CatalogWorld) -> list[dict]:
|
|
333
|
+
if world.spec is None:
|
|
334
|
+
return []
|
|
335
|
+
return [RouteAnswer.of(world, operation).document() for operation in world.spec.operations.values()]
|
|
336
|
+
|
|
337
|
+
def narrowed(self, value: Any, entity: str) -> Any:
|
|
338
|
+
return value
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
@dataclass(frozen=True)
|
|
342
|
+
class RouteAnswer:
|
|
343
|
+
operation: str
|
|
344
|
+
methods: list[str]
|
|
345
|
+
path: str
|
|
346
|
+
params: list[str]
|
|
347
|
+
entity: str | None
|
|
348
|
+
single: bool
|
|
349
|
+
records: str | None = None
|
|
350
|
+
id: str | None = None
|
|
351
|
+
fields: list[str] = field(default_factory=list)
|
|
352
|
+
count: str | None = None
|
|
353
|
+
total: str | None = None
|
|
354
|
+
cursor: str | None = None
|
|
355
|
+
cursor_param: str | None = None
|
|
356
|
+
declared: list[str] = field(default_factory=list)
|
|
357
|
+
|
|
358
|
+
@classmethod
|
|
359
|
+
def of(cls, world: CatalogWorld, operation: "Operation") -> "RouteAnswer":
|
|
360
|
+
base = cls(
|
|
361
|
+
operation=operation.name,
|
|
362
|
+
methods=list(operation.methods),
|
|
363
|
+
path=operation.path,
|
|
364
|
+
params=list(operation.params),
|
|
365
|
+
entity=operation.entity,
|
|
366
|
+
single=False,
|
|
367
|
+
id=cls._id(world, operation.entity),
|
|
368
|
+
)
|
|
369
|
+
served = base if world.settings is None else base._served(world.settings, operation)
|
|
370
|
+
return served._declared(world.answers.get(operation.name))
|
|
371
|
+
|
|
372
|
+
@staticmethod
|
|
373
|
+
def _id(world: CatalogWorld, entity: str | None) -> str | None:
|
|
374
|
+
key = (world.entities.get(entity or "") or {}).get("primary_key") or []
|
|
375
|
+
return key[0] if len(key) == 1 and not key[0].startswith("/") else None
|
|
376
|
+
|
|
377
|
+
def _served(self, settings: "ApiSettings", operation: "Operation") -> "RouteAnswer":
|
|
378
|
+
op = settings.for_operation(operation.name)
|
|
379
|
+
shape = settings.answer_shape(op, operation)
|
|
380
|
+
if op.action == "delete" or (operation.entity is None and op.action != "handler"):
|
|
381
|
+
return self
|
|
382
|
+
if shape.single:
|
|
383
|
+
return replace(self, single=True, records=dotted_pointer(shape.envelope or shape.results))
|
|
384
|
+
if op.action == "handler":
|
|
385
|
+
return replace(self, records=dotted_pointer(shape.results) if shape.results else None)
|
|
386
|
+
if not shape.envelope:
|
|
387
|
+
return replace(self, records="")
|
|
388
|
+
return self._enveloped(settings, op, shape.envelope)
|
|
389
|
+
|
|
390
|
+
def _enveloped(self, settings: "ApiSettings", op: Any, envelope: str) -> "RouteAnswer":
|
|
391
|
+
outer = envelope.split(".")[:-1]
|
|
392
|
+
paged = (op.paging or settings.paging.style) == "cursor"
|
|
393
|
+
return replace(
|
|
394
|
+
self,
|
|
395
|
+
records=dotted_pointer(envelope),
|
|
396
|
+
total=json_pointer([*outer, settings.hits_key]) if settings.hits_key else None,
|
|
397
|
+
cursor=json_pointer([*outer, settings.cursor_key]) if paged else None,
|
|
398
|
+
cursor_param=settings.paging.cursor_param if paged and not settings.page_links else None,
|
|
399
|
+
)
|
|
400
|
+
|
|
401
|
+
def _declared(self, declaration: AnswerDeclaration | None) -> "RouteAnswer":
|
|
402
|
+
if declaration is None:
|
|
403
|
+
return self
|
|
404
|
+
values = declaration.values
|
|
405
|
+
return replace(
|
|
406
|
+
self,
|
|
407
|
+
**{
|
|
408
|
+
key: values[key]
|
|
409
|
+
for key in ("records", "id", "count", "total", "cursor", "cursor_param")
|
|
410
|
+
if key in values
|
|
411
|
+
},
|
|
412
|
+
fields=list(values.get("fields", self.fields)),
|
|
413
|
+
declared=declaration.declared,
|
|
414
|
+
)
|
|
415
|
+
|
|
416
|
+
def document(self) -> dict:
|
|
417
|
+
return {
|
|
418
|
+
"operation": self.operation,
|
|
419
|
+
"methods": self.methods,
|
|
420
|
+
"path": self.path,
|
|
421
|
+
"params": self.params,
|
|
422
|
+
"entity": self.entity,
|
|
423
|
+
"single": self.single,
|
|
424
|
+
"records": self.records,
|
|
425
|
+
"id": self.id,
|
|
426
|
+
"fields": self.fields,
|
|
427
|
+
"count": self.count,
|
|
428
|
+
"total": self.total,
|
|
429
|
+
"cursor": self.cursor,
|
|
430
|
+
"cursorParam": self.cursor_param,
|
|
431
|
+
"declared": self.declared,
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
KINDS: tuple[CatalogKind, ...] = (
|
|
436
|
+
Enumerations(),
|
|
437
|
+
Columns(),
|
|
438
|
+
CustomFields(),
|
|
439
|
+
Ids(),
|
|
440
|
+
Sequences(),
|
|
441
|
+
Redaction(),
|
|
442
|
+
Answers(),
|
|
443
|
+
)
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
@dataclass(frozen=True)
|
|
447
|
+
class ShapeCatalog:
|
|
448
|
+
parts: dict[str, Any]
|
|
449
|
+
defs: dict
|
|
450
|
+
|
|
451
|
+
@classmethod
|
|
452
|
+
def of(cls, world: CatalogWorld) -> "ShapeCatalog":
|
|
453
|
+
return cls({kind.key: kind.read(world) for kind in KINDS}, world.defs)
|
|
454
|
+
|
|
455
|
+
@classmethod
|
|
456
|
+
def from_document(cls, document: dict) -> "ShapeCatalog":
|
|
457
|
+
return cls({kind.key: document[kind.key] for kind in KINDS}, dict(document.get("types") or {}))
|
|
458
|
+
|
|
459
|
+
def narrowed(self, entity: str) -> "ShapeCatalog":
|
|
460
|
+
return replace(self, parts={kind.key: kind.narrowed(self.parts[kind.key], entity) for kind in KINDS})
|
|
461
|
+
|
|
462
|
+
def types(self) -> dict:
|
|
463
|
+
reached: set[str] = set()
|
|
464
|
+
pending = sorted({name for column in self.parts["columns"] for name in local_refs(column["schema"])})
|
|
465
|
+
while pending:
|
|
466
|
+
name = pending.pop()
|
|
467
|
+
if name in reached or not isinstance(self.defs.get(name), dict):
|
|
468
|
+
continue
|
|
469
|
+
reached.add(name)
|
|
470
|
+
pending += sorted(local_refs(self.defs[name]) - reached)
|
|
471
|
+
return {name: stripped(self.defs[name]) for name in sorted(reached)}
|
|
472
|
+
|
|
473
|
+
def document(self) -> dict:
|
|
474
|
+
return {"version": CATALOG_VERSION, **self.parts, "types": self.types()}
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
def narrowed_description(description: dict, entity: Any) -> dict:
|
|
478
|
+
"""Answers stay whole: a request is routed among every route, whichever entity it lands on."""
|
|
479
|
+
if entity is None:
|
|
480
|
+
return description
|
|
481
|
+
entities = description.get("entities") or []
|
|
482
|
+
names = [item.get("name") for item in entities]
|
|
483
|
+
if not isinstance(entity, str) or entity not in names:
|
|
484
|
+
fail(
|
|
485
|
+
DESCRIBE_ENTITY,
|
|
486
|
+
f"{entity!r} is not an entity of this world; its entities are {', '.join(map(str, names)) or 'none'}",
|
|
487
|
+
"/entity",
|
|
488
|
+
)
|
|
489
|
+
narrowed = {**description, "entities": [item for item in entities if item.get("name") == entity]}
|
|
490
|
+
catalog = description.get("catalog")
|
|
491
|
+
if isinstance(catalog, dict):
|
|
492
|
+
narrowed["catalog"] = ShapeCatalog.from_document(catalog).narrowed(entity).document()
|
|
493
|
+
return narrowed
|