@withgateway/sdk 0.2.6 → 0.2.9
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 +24 -8
- package/dist/cli.js +15468 -11263
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +15233 -11028
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +291 -40
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +284 -37
- 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 +203 -47
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +198 -42
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
- package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
- package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
- package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2149 -615
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2053 -566
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +268 -31
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +262 -28
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +19 -11
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +19 -11
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +886 -117
- package/dist/worlds/index.d.ts +886 -117
- package/dist/worlds/index.js +1770 -452
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1752 -434
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +14 -10
- package/runtime/gatewaysdk/environment/_toml.py +3 -10
- package/runtime/gatewaysdk/environment/_world.py +95 -28
- package/runtime/gatewaysdk/environment/runtime.py +10 -6
- package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
- package/runtime/gatewaysdk/environment/schema/api.py +19 -23
- package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
- package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
- package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
- package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
- package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
- package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
- package/runtime/gatewaysdk/environment/schema/data.py +21 -5
- package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
- package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
- package/runtime/gatewaysdk/environment/schema/host.py +68 -115
- package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
- package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
- package/runtime/gatewaysdk/environment/schema/local.py +7 -10
- package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
- package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
- package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
- package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
- package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
- package/runtime/gatewaysdk/environment/schema/store.py +15 -6
- package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
- package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
- package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
- package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
- package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
- package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
- package/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/skills/connector-schema-authoring/SKILL.md +54 -4
- package/skills/connector-schema-authoring/connector-worlds.md +21 -7
- package/skills/connector-schema-authoring/world-schema.md +144 -83
- package/skills/hooks-getting-started/SKILL.md +27 -2
- package/skills/world-data-ingestion/ROWS.md +62 -0
- package/skills/world-data-ingestion/SKILL.md +91 -54
- package/skills/worlds-getting-started/SKILL.md +146 -146
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/skills/worlds-getting-started/references/openapi-import.md +90 -0
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
"""``gateway worlds schema init <dir> --from-openapi <source>``: an OpenAPI or
|
|
2
|
+
Swagger document as a world.
|
|
3
|
+
|
|
4
|
+
:class:`OpenApiImport` owns the conversion; :class:`OpenApiWorldPlan` is what it
|
|
5
|
+
produces: the entities and routes it chose, the warnings, and the files
|
|
6
|
+
(``schema/world.json``, ``connector.toml``, ``schema/provenance.json``) it
|
|
7
|
+
renders from them. It writes nothing itself: ``init_bundle_from_files`` (the
|
|
8
|
+
one scaffold writer) takes the rendered files, validates and compiles the tree
|
|
9
|
+
and removes it whole when anything refuses, so a rejected import leaves no
|
|
10
|
+
directory behind. ``--plan-only`` stops at the plan.
|
|
11
|
+
|
|
12
|
+
Entities are the keyed object schemas the selected operations reach (through
|
|
13
|
+
their responses and request bodies, then every ``$ref`` from there); a spec
|
|
14
|
+
whose operations name no schema gets every keyed schema instead. A schema with
|
|
15
|
+
no key stays a ``$defs`` entry referenced inline. Keys, names and the shape
|
|
16
|
+
rules are in ``openapi_schemas``; routes in ``openapi_routes``.
|
|
17
|
+
|
|
18
|
+
Trust boundary: the source is read where the command runs (``openapi_source``:
|
|
19
|
+
a local file, or a public URL behind the private-address guard); a
|
|
20
|
+
``drive:<path>`` is staged by the platform CLI before this code sees bytes. The
|
|
21
|
+
provenance file records the source label with credentials and query strings
|
|
22
|
+
removed, the document's version and title, its sha256 and the importer version.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import base64
|
|
28
|
+
import binascii
|
|
29
|
+
import json
|
|
30
|
+
import re
|
|
31
|
+
from dataclasses import dataclass, field
|
|
32
|
+
from pathlib import Path
|
|
33
|
+
from typing import Any
|
|
34
|
+
|
|
35
|
+
from .compiler import Contract
|
|
36
|
+
from .connector import SPEC
|
|
37
|
+
from .openapi_document import OpenApiDocument, OpenApiOperation
|
|
38
|
+
from .openapi_routes import Entity, OperationPlan, RoutePlanner, Selection, Skipped
|
|
39
|
+
from .openapi_schemas import EntityKey, Names, Namespace, SchemaConverter
|
|
40
|
+
from .openapi_source import OpenApiSource
|
|
41
|
+
from .scaffold import init_bundle_from_files
|
|
42
|
+
from .validation import DIALECT, MAX_ENTITY_NAME, fail
|
|
43
|
+
|
|
44
|
+
IMPORTER_VERSION = "1.0.0"
|
|
45
|
+
#: Template-relative, as ``init_bundle_from_files`` takes them; the scaffold lands
|
|
46
|
+
#: ``world.json`` and ``provenance.json`` under ``schema/``.
|
|
47
|
+
WORLD = "world.json"
|
|
48
|
+
PROVENANCE = "provenance.json"
|
|
49
|
+
_REF = re.compile(r'"\$ref":\s*"([^"]+)"')
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@dataclass
|
|
53
|
+
class OpenApiWorldPlan:
|
|
54
|
+
"""What an import will create, and the files that create it."""
|
|
55
|
+
|
|
56
|
+
source: OpenApiSource
|
|
57
|
+
document: OpenApiDocument
|
|
58
|
+
slug: str
|
|
59
|
+
entities: list[Entity]
|
|
60
|
+
operations: list[OperationPlan]
|
|
61
|
+
skipped: list[Skipped]
|
|
62
|
+
excluded: int
|
|
63
|
+
defs: dict[str, dict]
|
|
64
|
+
warnings: list[str] = field(default_factory=list)
|
|
65
|
+
|
|
66
|
+
# ------------------------------------------------------------- the plan
|
|
67
|
+
|
|
68
|
+
def summary(self) -> dict:
|
|
69
|
+
return {
|
|
70
|
+
"source": self.source.label,
|
|
71
|
+
"document": {"version": self.document.version, "title": self.document.title, "sha256": self.source.sha256},
|
|
72
|
+
"connector": self.slug,
|
|
73
|
+
"entities": [e.summary() for e in self.entities],
|
|
74
|
+
"operations": [o.summary() for o in self.operations],
|
|
75
|
+
"skipped": [s.summary() for s in self.skipped],
|
|
76
|
+
"excluded": self.excluded,
|
|
77
|
+
"warnings": list(self.warnings),
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
# ------------------------------------------------------------- the files
|
|
81
|
+
|
|
82
|
+
def world(self) -> dict:
|
|
83
|
+
entities = {
|
|
84
|
+
e.name: {"schema": {"$ref": f"#/$defs/{_pointer(e.source)}"}, "primary_key": [e.key]}
|
|
85
|
+
for e in sorted(self.entities, key=lambda e: e.name)
|
|
86
|
+
}
|
|
87
|
+
return {
|
|
88
|
+
"$schema": DIALECT,
|
|
89
|
+
"$id": f"urn:gateway:connector:{self.slug}",
|
|
90
|
+
"title": self.document.title,
|
|
91
|
+
"description": f"Imported from {self.source.label} ({self.document.version})",
|
|
92
|
+
"x-gateway": {
|
|
93
|
+
"version": 1,
|
|
94
|
+
"domain_version": "1.0.0",
|
|
95
|
+
"package": {"id": self.slug, "version": "1.0.0"},
|
|
96
|
+
"entities": entities,
|
|
97
|
+
"tools": {},
|
|
98
|
+
},
|
|
99
|
+
"$defs": self.defs,
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
def connector_toml(self) -> str:
|
|
103
|
+
head = [
|
|
104
|
+
"[connector]",
|
|
105
|
+
f"slug = {_s(self.slug)}",
|
|
106
|
+
f"base_url = {_s(self.base_url())}",
|
|
107
|
+
"",
|
|
108
|
+
*self._auth_lines(),
|
|
109
|
+
"[api]",
|
|
110
|
+
'envelope = ""',
|
|
111
|
+
'hits_key = ""',
|
|
112
|
+
"cursor_absent_when_done = true",
|
|
113
|
+
'page = "none"',
|
|
114
|
+
"",
|
|
115
|
+
]
|
|
116
|
+
return "\n".join(head) + "\n" + "\n".join(o.toml() for o in self.operations)
|
|
117
|
+
|
|
118
|
+
def base_url(self) -> str:
|
|
119
|
+
return self.document.base_url() or f"https://{self.slug}.invalid"
|
|
120
|
+
|
|
121
|
+
def _auth_lines(self) -> list[str]:
|
|
122
|
+
env = re.sub(r"[^A-Z0-9]+", "_", self.slug.upper()).strip("_") or "API"
|
|
123
|
+
for name, scheme in self.document.security_schemes().items():
|
|
124
|
+
lines = _auth(scheme, env)
|
|
125
|
+
if lines:
|
|
126
|
+
return ["[auth]", *lines, f"# from security scheme {name}", ""]
|
|
127
|
+
return ["[auth]", 'scheme = "none"', ""]
|
|
128
|
+
|
|
129
|
+
def provenance(self) -> dict:
|
|
130
|
+
return {
|
|
131
|
+
"importer": {"name": "gateway worlds schema init --from-openapi", "version": IMPORTER_VERSION},
|
|
132
|
+
"source": {
|
|
133
|
+
"kind": self.source.kind,
|
|
134
|
+
"label": self.source.label,
|
|
135
|
+
"sha256": self.source.sha256,
|
|
136
|
+
"bytes": self.source.size,
|
|
137
|
+
},
|
|
138
|
+
"document": {
|
|
139
|
+
"version": self.document.version,
|
|
140
|
+
"title": self.document.title,
|
|
141
|
+
"info_version": str(self.document.info.get("version", "")),
|
|
142
|
+
},
|
|
143
|
+
"entities": {
|
|
144
|
+
e.name: {"source": e.source, "pointer": e.pointer, "key": e.key, "fields": e.fields}
|
|
145
|
+
for e in self.entities
|
|
146
|
+
},
|
|
147
|
+
"operations": {o.name: {"pointer": o.pointer, "operation_id": o.operation_id} for o in self.operations},
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
def files(self) -> dict[str, bytes]:
|
|
151
|
+
return {
|
|
152
|
+
WORLD: _json_bytes(self.world()),
|
|
153
|
+
SPEC: self.connector_toml().encode("utf-8"),
|
|
154
|
+
PROVENANCE: _json_bytes(self.provenance()),
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
# ------------------------------------------------------------- writing
|
|
158
|
+
|
|
159
|
+
def write(self, destination: str | Path, *, name: str | None = None) -> Contract:
|
|
160
|
+
"""Hand the rendered files to the scaffold writer; nothing is written here."""
|
|
161
|
+
if not self.entities:
|
|
162
|
+
fail(
|
|
163
|
+
"spec",
|
|
164
|
+
"No schema of the document has a key, so no entity can be made; nothing to import",
|
|
165
|
+
self.document.schemas_pointer,
|
|
166
|
+
)
|
|
167
|
+
return init_bundle_from_files(destination, self.files(), connector=self.slug, name=name)
|
|
168
|
+
|
|
169
|
+
def run(
|
|
170
|
+
self, destination: str | Path, *, plan_only: bool = False, name: str | None = None, shown: str | None = None
|
|
171
|
+
) -> dict:
|
|
172
|
+
"""What the CLI prints: the plan, and when writing, the compiled domain and
|
|
173
|
+
the next commands (naming ``shown``, the caller's directory, when the tree
|
|
174
|
+
is written somewhere else first). ``plan_only`` writes nothing."""
|
|
175
|
+
out = {"status": "ok", "written": not plan_only, "plan": self.summary()}
|
|
176
|
+
if plan_only:
|
|
177
|
+
return out
|
|
178
|
+
contract = self.write(destination, name=name)
|
|
179
|
+
out["domain"] = contract.target
|
|
180
|
+
out["next"] = self.next_steps(shown or str(destination))
|
|
181
|
+
return out
|
|
182
|
+
|
|
183
|
+
def next_steps(self, destination: str) -> list[str]:
|
|
184
|
+
listing = next((o for o in self.operations if o.entity and not o.single and o.method == "GET"), None)
|
|
185
|
+
entity = listing.entity if listing is not None and listing.entity else self.entities[0].name
|
|
186
|
+
steps = [
|
|
187
|
+
f"gateway worlds schema compile {destination} # after any edit to schema/ or connector.toml",
|
|
188
|
+
f"gateway worlds schema check {destination}",
|
|
189
|
+
f"gateway worlds data import {destination} <rows.json> --entity {entity} # rows shaped like the vendor's response",
|
|
190
|
+
f"gateway worlds serve {destination} # then, in another shell:",
|
|
191
|
+
]
|
|
192
|
+
if listing is not None:
|
|
193
|
+
steps.append(
|
|
194
|
+
f"gateway worlds call http://127.0.0.1:<port> {listing.name} --args '{{}}' # GET {listing.path}"
|
|
195
|
+
)
|
|
196
|
+
steps.append(
|
|
197
|
+
f'gateway worlds sandbox commit <sandbox-id> -m "import {self.source.label}" # when {destination} is in a sandbox'
|
|
198
|
+
)
|
|
199
|
+
return steps
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
class OpenApiImport:
|
|
203
|
+
"""One OpenAPI document, read once, planned into a world."""
|
|
204
|
+
|
|
205
|
+
def __init__(self, source: OpenApiSource, *, selection: Selection | None = None, slug: str | None = None):
|
|
206
|
+
self.source = source
|
|
207
|
+
self.selection = selection or Selection()
|
|
208
|
+
self.document = OpenApiDocument(source.document())
|
|
209
|
+
self.slug = slug or _slug(self.document.title)
|
|
210
|
+
self.warnings: list[str] = list(self.document.warnings)
|
|
211
|
+
|
|
212
|
+
@classmethod
|
|
213
|
+
def read(
|
|
214
|
+
cls, spec: str, *, include: tuple[str, ...] = (), exclude: tuple[str, ...] = (), slug: str | None = None
|
|
215
|
+
) -> OpenApiImport:
|
|
216
|
+
return cls(OpenApiSource.read(spec), selection=Selection(tuple(include), tuple(exclude)), slug=slug)
|
|
217
|
+
|
|
218
|
+
@classmethod
|
|
219
|
+
def execute(cls, request: dict, root: Path) -> dict:
|
|
220
|
+
"""The bridge's ``init-openapi``: ``{source, document, include?, exclude?,
|
|
221
|
+
plan_only?, name?}``. ``document`` is the base64 bytes the caller already
|
|
222
|
+
holds (a local file, a URL it fetched, or a drive file read with its own
|
|
223
|
+
credentials), labelled by ``source``. Like ``conform``, the bridge never
|
|
224
|
+
opens a caller-named path or URL itself: wherever it runs, the bytes come
|
|
225
|
+
with the request."""
|
|
226
|
+
name, include, exclude = (request.get("name"), request.get("include", []), request.get("exclude", []))
|
|
227
|
+
shown = request.get("destination")
|
|
228
|
+
if not all(v is None or isinstance(v, str) for v in (name, shown)):
|
|
229
|
+
fail("input", "Expected an optional name and destination label")
|
|
230
|
+
if not all(isinstance(v, list) and all(isinstance(p, str) for p in v) for v in (include, exclude)):
|
|
231
|
+
fail("input", "include and exclude are lists of path globs or tags")
|
|
232
|
+
importer = cls(_request_source(request), selection=Selection(tuple(include), tuple(exclude)))
|
|
233
|
+
return importer.plan().run(root, plan_only=request.get("plan_only") is True, name=name, shown=shown)
|
|
234
|
+
|
|
235
|
+
def plan(self) -> OpenApiWorldPlan:
|
|
236
|
+
everything = list(self.document.operations())
|
|
237
|
+
selected = [op for op in everything if self.selection.selects(op)]
|
|
238
|
+
if not selected:
|
|
239
|
+
fail("spec", "No operation matches --include/--exclude; nothing to import", "/paths")
|
|
240
|
+
converter = SchemaConverter(self.document, {})
|
|
241
|
+
entities = self._entities(converter, self._reachable(selected), self._returned(selected))
|
|
242
|
+
routes = RoutePlanner(self.document, entities, selected).plan()
|
|
243
|
+
defs = converter.convert_all(set(entities))
|
|
244
|
+
self.warnings.extend(routes.warnings)
|
|
245
|
+
self.warnings.extend(converter.warnings)
|
|
246
|
+
self.warnings.extend(
|
|
247
|
+
f"{at}: property {source} is stored as {legal} (not an identifier)"
|
|
248
|
+
for at, source, legal in converter.renamed
|
|
249
|
+
)
|
|
250
|
+
if converter.dropped:
|
|
251
|
+
kept = ", ".join(f"{k} x{n}" for k, n in sorted(converter.dropped.items()))
|
|
252
|
+
self.warnings.append(f"schema keywords the world validator does not model were dropped: {kept}")
|
|
253
|
+
return OpenApiWorldPlan(
|
|
254
|
+
source=self.source,
|
|
255
|
+
document=self.document,
|
|
256
|
+
slug=self.slug,
|
|
257
|
+
entities=sorted(entities.values(), key=lambda e: e.name),
|
|
258
|
+
operations=routes.operations,
|
|
259
|
+
skipped=routes.skipped,
|
|
260
|
+
excluded=len(everything) - len(selected),
|
|
261
|
+
defs=defs,
|
|
262
|
+
warnings=self.warnings,
|
|
263
|
+
)
|
|
264
|
+
|
|
265
|
+
# ------------------------------------------------------------- entities
|
|
266
|
+
|
|
267
|
+
def _reachable(self, selected: list[OpenApiOperation]) -> set[str]:
|
|
268
|
+
"""Top-level schema names the selected operations reach through ``$ref``:
|
|
269
|
+
one pass over each schema's text, never a walk per reference."""
|
|
270
|
+
names = self.document.schema_name
|
|
271
|
+
queue = [n for op in selected for n in self._refs(op.request_body, *op.responses.values()) if n is not None]
|
|
272
|
+
queue = [n for n in queue if n in self.document.schemas]
|
|
273
|
+
seen: set[str] = set()
|
|
274
|
+
while queue:
|
|
275
|
+
name = queue.pop()
|
|
276
|
+
if name in seen:
|
|
277
|
+
continue
|
|
278
|
+
seen.add(name)
|
|
279
|
+
for ref in _REF.findall(json.dumps(self.document.schemas[name])):
|
|
280
|
+
target = names(ref)
|
|
281
|
+
if target is not None and target in self.document.schemas and target not in seen:
|
|
282
|
+
queue.append(target)
|
|
283
|
+
if seen:
|
|
284
|
+
return seen
|
|
285
|
+
self.warnings.append("no operation names a schema; every keyed schema becomes an entity")
|
|
286
|
+
return set(self.document.schemas)
|
|
287
|
+
|
|
288
|
+
def _refs(self, *nodes: Any) -> list[str | None]:
|
|
289
|
+
return [
|
|
290
|
+
self.document.schema_name(ref)
|
|
291
|
+
for node in nodes
|
|
292
|
+
if node is not None
|
|
293
|
+
for ref in _REF.findall(json.dumps(node))
|
|
294
|
+
]
|
|
295
|
+
|
|
296
|
+
def _returned(self, selected: list[OpenApiOperation]) -> set[str]:
|
|
297
|
+
"""Schemas some success response names directly: the only ones a key may be
|
|
298
|
+
guessed for (first required scalar); error and request shapes never are."""
|
|
299
|
+
successes = [op.success[1] for op in selected if op.success is not None]
|
|
300
|
+
return {n for n in self._refs(*successes) if n is not None}
|
|
301
|
+
|
|
302
|
+
def _entities(self, converter: SchemaConverter, candidates: set[str], returned: set[str]) -> dict[str, Entity]:
|
|
303
|
+
"""The keyed object schemas among ``candidates``, registered as the converter's roots."""
|
|
304
|
+
names = Namespace(limit=MAX_ENTITY_NAME)
|
|
305
|
+
entities: dict[str, Entity] = {}
|
|
306
|
+
for source in sorted(candidates):
|
|
307
|
+
at = f"{self.document.schemas_pointer}/{_pointer(source)}"
|
|
308
|
+
resolved, chain = converter.resolve_named(self.document.schemas[source], at, (source,))
|
|
309
|
+
if not isinstance(resolved, dict):
|
|
310
|
+
continue
|
|
311
|
+
merged = converter.merged(resolved, at, chain)
|
|
312
|
+
properties = merged.get("properties")
|
|
313
|
+
if not isinstance(properties, dict) or not properties:
|
|
314
|
+
continue
|
|
315
|
+
required = {r for r in merged.get("required", []) if isinstance(r, str)}
|
|
316
|
+
detector = EntityKey(self.document, source, properties, required)
|
|
317
|
+
key = detector.detect(fallback=source in returned)
|
|
318
|
+
if key is None:
|
|
319
|
+
continue
|
|
320
|
+
name, renamed = names.claim(Names.entity(source, MAX_ENTITY_NAME))
|
|
321
|
+
if renamed:
|
|
322
|
+
self.warnings.append(f"{at}: entity name for {source} is taken; using {name}")
|
|
323
|
+
fields = Names.fields(properties)
|
|
324
|
+
filterable = frozenset(fields[p] for p in detector.scalars())
|
|
325
|
+
converter.roots[source] = key
|
|
326
|
+
entities[source] = Entity(
|
|
327
|
+
name, source, at, fields[key], self._key_type(properties[key], at), fields, filterable
|
|
328
|
+
)
|
|
329
|
+
return entities
|
|
330
|
+
|
|
331
|
+
def _key_type(self, schema: Any, at: str) -> str:
|
|
332
|
+
resolved = self.document.resolve(schema, at)
|
|
333
|
+
declared = resolved.get("type") if isinstance(resolved, dict) else None
|
|
334
|
+
listed = [declared] if isinstance(declared, str) else declared if isinstance(declared, list) else []
|
|
335
|
+
return "integer" if [t for t in listed if t != "null"] == ["integer"] else "string"
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
# ---------------------------------------------------------------- rendering helpers
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def _request_source(request: dict) -> OpenApiSource:
|
|
342
|
+
source, document = request.get("source"), request.get("document")
|
|
343
|
+
if not isinstance(source, str) or not source:
|
|
344
|
+
fail("input", "Expected the OpenAPI source as a path, URL or drive:<path> label")
|
|
345
|
+
if not isinstance(document, str):
|
|
346
|
+
fail("input", "Expected the OpenAPI document as base64 text")
|
|
347
|
+
try:
|
|
348
|
+
data = base64.b64decode(document, validate=True)
|
|
349
|
+
except (ValueError, binascii.Error):
|
|
350
|
+
fail("input", "OpenAPI document content must be base64")
|
|
351
|
+
return OpenApiSource.from_bytes(data, OpenApiSource.safe_label(source), OpenApiSource.kind_of(source))
|
|
352
|
+
|
|
353
|
+
|
|
354
|
+
def _auth(scheme: dict, env: str) -> list[str]:
|
|
355
|
+
kind = scheme.get("type")
|
|
356
|
+
if kind == "http" and str(scheme.get("scheme", "")).lower() == "bearer" or kind == "oauth2":
|
|
357
|
+
return ['scheme = "bearer"', f"secret_env = {_s(env + '_TOKEN')}"]
|
|
358
|
+
if kind == "http" and str(scheme.get("scheme", "")).lower() == "basic" or kind == "basic":
|
|
359
|
+
return ['scheme = "basic"', f"secret_env = {_s(env + '_BASIC')}"]
|
|
360
|
+
if kind == "apiKey" and scheme.get("in") in ("header", "query") and isinstance(scheme.get("name"), str):
|
|
361
|
+
return [f"scheme = {_s(scheme['in'])}", f"name = {_s(scheme['name'])}", f"secret_env = {_s(env + '_API_KEY')}"]
|
|
362
|
+
return []
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
def _slug(title: str) -> str:
|
|
366
|
+
slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
|
|
367
|
+
slug = re.sub(r"-+", "-", slug)
|
|
368
|
+
if not slug or not slug[0].isalpha():
|
|
369
|
+
slug = "api-" + slug if slug else "imported-api"
|
|
370
|
+
return slug[:48].rstrip("-")
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
def _pointer(name: str) -> str:
|
|
374
|
+
return name.replace("~", "~0").replace("/", "~1")
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
def _s(text: str) -> str:
|
|
378
|
+
return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def _json_bytes(value: Any) -> bytes:
|
|
382
|
+
return (json.dumps(value, indent=2, ensure_ascii=False, sort_keys=False) + "\n").encode("utf-8")
|