@syntropika/tembra-sdk 0.2.1 → 0.3.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 +43 -17
- package/dist/authoring/types.d.ts +64 -3
- package/dist/authoring/wit.d.ts +6 -0
- package/dist/bridge/commands.d.ts +1190 -0
- package/dist/bridge/identifiers.d.ts +2 -0
- package/dist/bridge/kernel.d.ts +18 -107
- package/dist/bridge/protocol.d.ts +3 -138
- package/dist/browser.d.ts +14 -1
- package/dist/browser.js +141 -3298
- package/dist/chunks/browser-b8jamxw2.js +3399 -0
- package/dist/chunks/execution-nsqc6nrt.js +1419 -0
- package/dist/chunks/index-01zk0xqx.js +160 -0
- package/dist/chunks/index-3fjdfdfd.js +152 -0
- package/dist/chunks/index-aaymjn7v.js +787 -0
- package/dist/chunks/index-c1w7z9hx.js +356 -0
- package/dist/chunks/index-h8t0n42q.js +738 -0
- package/dist/chunks/index-hfds9mzp.js +308 -0
- package/dist/chunks/index-kr4x67wt.js +177 -0
- package/dist/chunks/index-kr6bnh34.js +117 -0
- package/dist/chunks/index-kyt9dj0a.js +1421 -0
- package/dist/chunks/index-n1wxzc9w.js +830 -0
- package/dist/chunks/index-pvac426d.js +74 -0
- package/dist/chunks/index-smyds5ce.js +3234 -0
- package/dist/chunks/index-sse8aapb.js +121 -0
- package/dist/chunks/index-v6heph77.js +643 -0
- package/dist/chunks/index-xrdvnv37.js +3448 -0
- package/dist/chunks/index-za4mg94e.js +26 -0
- package/dist/chunks/index-zkqmnjj8.js +167 -0
- package/dist/coordinator.js +9 -500
- package/dist/error.d.ts +2 -0
- package/dist/errors.d.ts +3 -0
- package/dist/guest.d.ts +173 -0
- package/dist/guest.js +26 -0
- package/dist/host.d.ts +36 -30
- package/dist/host.js +37 -3276
- package/dist/http/bytes.d.ts +8 -0
- package/dist/http/events.d.ts +7 -0
- package/dist/http.d.ts +45 -0
- package/dist/http.js +291 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +49 -862
- package/dist/infrastructure/rpc/client.d.ts +2 -1
- package/dist/infrastructure/rpc/resources.d.ts +28 -0
- package/dist/interpreter/abi.d.ts +54 -0
- package/dist/interpreter/acquire.d.ts +18 -0
- package/dist/interpreter/browser-network.d.ts +52 -0
- package/dist/interpreter/browser-port.d.ts +55 -0
- package/dist/interpreter/browser.d.ts +79 -0
- package/dist/interpreter/cli.d.ts +5 -0
- package/dist/interpreter/codec.d.ts +42 -0
- package/dist/interpreter/component/execution.d.ts +42 -0
- package/dist/interpreter/component/host.d.ts +69 -0
- package/dist/interpreter/component/instance.d.ts +40 -0
- package/dist/interpreter/component/kernel.d.ts +120 -0
- package/dist/interpreter/component/names.d.ts +5 -0
- package/dist/interpreter/component/port.d.ts +85 -0
- package/dist/interpreter/component/prepared.d.ts +97 -0
- package/dist/interpreter/component/resources.d.ts +45 -0
- package/dist/interpreter/component/revision.d.ts +87 -0
- package/dist/interpreter/component/scope.d.ts +116 -0
- package/dist/interpreter/component/streams.d.ts +28 -0
- package/dist/interpreter/component/values.d.ts +79 -0
- package/dist/interpreter/component/wasi-filesystem.d.ts +21 -0
- package/dist/interpreter/component/wasi-host.d.ts +64 -0
- package/dist/interpreter/component/wasi-http.d.ts +33 -0
- package/dist/interpreter/component/wasi-sockets.d.ts +183 -0
- package/dist/interpreter/component/wasi.d.ts +41 -0
- package/dist/interpreter/core.d.ts +64 -0
- package/dist/interpreter/fetch-http-provider.d.ts +17 -0
- package/dist/interpreter/filesystem/contract.d.ts +85 -0
- package/dist/interpreter/filesystem/memory.d.ts +3 -0
- package/dist/interpreter/filesystem/opfs.d.ts +3 -0
- package/dist/interpreter/filesystem/scope.d.ts +35 -0
- package/dist/interpreter/filesystem.d.ts +8 -0
- package/dist/interpreter/gate.d.ts +6 -0
- package/dist/interpreter/host-protocol.d.ts +100 -0
- package/dist/interpreter/http-ingress-fetch.d.ts +7 -0
- package/dist/interpreter/http-ingress.d.ts +96 -0
- package/dist/interpreter/http-provider.d.ts +85 -0
- package/dist/interpreter/io.d.ts +20 -0
- package/dist/interpreter/mobile.d.ts +149 -0
- package/dist/interpreter/native-ingress.d.ts +95 -0
- package/dist/interpreter/node-port.d.ts +25 -0
- package/dist/interpreter/node.d.ts +36 -0
- package/dist/interpreter/revision.d.ts +64 -0
- package/dist/interpreter/scope.d.ts +89 -0
- package/dist/interpreter/socket-addresses.d.ts +50 -0
- package/dist/interpreter/socket-provider.d.ts +110 -0
- package/dist/interpreter/standard-cli.d.ts +34 -0
- package/dist/interpreter/standard-codec.d.ts +96 -0
- package/dist/interpreter/standard-filesystem.d.ts +47 -0
- package/dist/interpreter/standard-host.d.ts +71 -0
- package/dist/interpreter/standard-http-values.d.ts +159 -0
- package/dist/interpreter/standard-http.d.ts +9 -0
- package/dist/interpreter/standard-ingress.d.ts +63 -0
- package/dist/interpreter/standard-sockets.d.ts +177 -0
- package/dist/interpreter/standard-streams.d.ts +218 -0
- package/dist/interpreter/standard-system.d.ts +35 -0
- package/dist/interpreter/standard-utf8.d.ts +4 -0
- package/dist/interpreter/standard.d.ts +18 -0
- package/dist/interpreter/types.d.ts +152 -0
- package/dist/interpreter/wit-shape.d.ts +92 -0
- package/dist/manager.js +5 -332
- package/dist/msgpack.js +9 -615
- package/dist/node.d.ts +8 -1
- package/dist/node.js +248 -3287
- package/dist/rpc.js +196 -699
- package/dist/runtime/adapters.d.ts +120 -0
- package/dist/runtime/adapters.js +38 -0
- package/dist/runtime/calls.d.ts +9 -3
- package/dist/runtime/lifecycle.d.ts +3 -1
- package/dist/runtime/orbs.d.ts +5 -4
- package/dist/runtime/references.d.ts +27 -1
- package/dist/runtime/reload.d.ts +5 -3
- package/dist/runtime/scopes.d.ts +1 -1
- package/dist/runtime/signals.d.ts +4 -0
- package/dist/runtime/wit-client.d.ts +38 -0
- package/dist/telemetry.js +4 -25
- package/dist/tooling/build.d.ts +2 -2
- package/dist/tooling/client-resources.d.ts +23 -0
- package/dist/tooling/client.d.ts +10 -0
- package/dist/tooling/component-glue.d.ts +17 -0
- package/dist/tooling/component.d.ts +11 -0
- package/dist/tooling/index.d.ts +3 -1
- package/dist/tooling/index.js +1155 -102
- package/dist/tooling/resolver.d.ts +4 -4
- package/dist/tooling/typecheck.d.ts +2 -1
- package/dist/tooling/types.d.ts +27 -12
- package/dist/tooling/wit.d.ts +9 -0
- package/dist/wasi/wasi-clocks-types.d.ts +2 -0
- package/dist/wasi/wasi-http-client.d.ts +5 -0
- package/dist/wasi/wasi-http-types.d.ts +285 -0
- package/dist/wasi/wasi-sockets-ip-name-lookup.d.ts +23 -0
- package/dist/wasi/wasi-sockets-types.d.ts +146 -0
- package/package.json +62 -35
- package/src/authoring/declaration.ts +1 -1
- package/src/authoring/types.ts +53 -3
- package/src/authoring/wit.ts +15 -0
- package/src/bridge/commands.ts +1105 -0
- package/src/bridge/identifiers.ts +2 -0
- package/src/bridge/kernel.ts +56 -98
- package/src/bridge/protocol.ts +3 -142
- package/src/browser.ts +90 -6
- package/src/context-key.ts +4 -7
- package/src/error.ts +1 -1
- package/src/errors.ts +7 -0
- package/src/guest.ts +327 -0
- package/src/host.ts +128 -23
- package/src/http/bytes.ts +87 -0
- package/src/http/events.ts +34 -0
- package/src/http.ts +272 -0
- package/src/index.ts +3 -0
- package/src/infrastructure/rpc/client.ts +136 -17
- package/src/infrastructure/rpc/resources.ts +123 -0
- package/src/interpreter/abi.ts +69 -0
- package/src/interpreter/acquire.ts +58 -0
- package/src/interpreter/browser-network.ts +170 -0
- package/src/interpreter/browser-port.ts +425 -0
- package/src/interpreter/browser.ts +340 -0
- package/src/interpreter/cli.ts +30 -0
- package/src/interpreter/codec.ts +298 -0
- package/src/interpreter/component/execution.ts +264 -0
- package/src/interpreter/component/host.ts +409 -0
- package/src/interpreter/component/instance.ts +138 -0
- package/src/interpreter/component/kernel.ts +611 -0
- package/src/interpreter/component/names.ts +13 -0
- package/src/interpreter/component/port.ts +598 -0
- package/src/interpreter/component/prepared.ts +194 -0
- package/src/interpreter/component/resources.ts +345 -0
- package/src/interpreter/component/revision.ts +702 -0
- package/src/interpreter/component/scope.ts +447 -0
- package/src/interpreter/component/streams.ts +180 -0
- package/src/interpreter/component/values.ts +254 -0
- package/src/interpreter/component/wasi-filesystem.ts +472 -0
- package/src/interpreter/component/wasi-host.ts +197 -0
- package/src/interpreter/component/wasi-http.ts +939 -0
- package/src/interpreter/component/wasi-sockets.ts +958 -0
- package/src/interpreter/component/wasi.ts +238 -0
- package/src/interpreter/core.ts +386 -0
- package/src/interpreter/fetch-http-provider.ts +98 -0
- package/src/interpreter/filesystem/contract.ts +138 -0
- package/src/interpreter/filesystem/memory.ts +180 -0
- package/src/interpreter/filesystem/opfs.ts +294 -0
- package/src/interpreter/filesystem/scope.ts +390 -0
- package/src/interpreter/filesystem.ts +20 -0
- package/src/interpreter/gate.ts +55 -0
- package/src/interpreter/host-protocol.ts +242 -0
- package/src/interpreter/http-ingress-fetch.ts +133 -0
- package/src/interpreter/http-ingress.ts +203 -0
- package/src/interpreter/http-provider.ts +105 -0
- package/src/interpreter/io.ts +66 -0
- package/src/interpreter/mobile.ts +385 -0
- package/src/interpreter/native-ingress.ts +550 -0
- package/src/interpreter/node-port.ts +218 -0
- package/src/interpreter/node.ts +114 -0
- package/src/interpreter/revision.ts +450 -0
- package/src/interpreter/scope.ts +453 -0
- package/src/interpreter/socket-addresses.ts +246 -0
- package/src/interpreter/socket-provider.ts +126 -0
- package/src/interpreter/standard-cli.ts +184 -0
- package/src/interpreter/standard-codec.ts +403 -0
- package/src/interpreter/standard-filesystem.ts +545 -0
- package/src/interpreter/standard-host.ts +840 -0
- package/src/interpreter/standard-http-values.ts +624 -0
- package/src/interpreter/standard-http.ts +622 -0
- package/src/interpreter/standard-ingress.ts +344 -0
- package/src/interpreter/standard-sockets.ts +847 -0
- package/src/interpreter/standard-streams.ts +710 -0
- package/src/interpreter/standard-system.ts +182 -0
- package/src/interpreter/standard-utf8.ts +72 -0
- package/src/interpreter/standard.ts +283 -0
- package/src/interpreter/types.ts +163 -0
- package/src/interpreter/wit-shape.ts +175 -0
- package/src/node.ts +43 -14
- package/src/runtime/activities.ts +6 -6
- package/src/runtime/adapters.ts +314 -0
- package/src/runtime/calls.ts +218 -56
- package/src/runtime/context.ts +7 -7
- package/src/runtime/lifecycle.ts +36 -17
- package/src/runtime/orbs.ts +81 -39
- package/src/runtime/programs.ts +16 -8
- package/src/runtime/references.ts +128 -11
- package/src/runtime/reload.ts +71 -30
- package/src/runtime/resources.ts +2 -2
- package/src/runtime/scopes.ts +17 -17
- package/src/runtime/session.ts +3 -1
- package/src/runtime/signals.ts +31 -0
- package/src/runtime/wit-client.ts +228 -0
- package/src/tooling/build.ts +152 -54
- package/src/tooling/client-resources.ts +74 -0
- package/src/tooling/client.ts +531 -0
- package/src/tooling/component-glue.ts +288 -0
- package/src/tooling/component.ts +225 -0
- package/src/tooling/index.ts +3 -7
- package/src/tooling/resolver.ts +42 -25
- package/src/tooling/typecheck.ts +59 -4
- package/src/tooling/types.ts +27 -12
- package/src/tooling/wit.ts +188 -0
- package/dist/embedded.d.ts +0 -1
- package/dist/embedded.js +0 -1
- package/src/embedded.ts +0 -293
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Application-owned prepared components: the only way a compiled Orb runs in a browser.
|
|
3
|
+
*
|
|
4
|
+
* Tembra's build tooling verifies a compiled artifact's real WIT types natively, generates its
|
|
5
|
+
* bindings once with JCO, instruments the glue and every core module, and emits an ES module that
|
|
6
|
+
* calls `preparedComponent`. That module is host-trusted application code: the application
|
|
7
|
+
* imports it explicitly and registers it with `createHost({ isolated: { components } })`.
|
|
8
|
+
* Nothing an Orb names (a URL, a sidecar, a claimed hash) is ever imported or trusted; an
|
|
9
|
+
* uploaded artifact selects an adapter only when the browser verifier hashed its actual bytes
|
|
10
|
+
* to the adapter's `artifact` digest.
|
|
11
|
+
*
|
|
12
|
+
* This module is small and loaded with the browser facade; execution code loads lazily.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/** Format of the generated adapter modules this SDK accepts. */
|
|
16
|
+
export const PREPARED_FORMAT = 1;
|
|
17
|
+
/** The generator whose output the build-time glue instrumentation recognizes exactly. */
|
|
18
|
+
export const PREPARED_GENERATOR = "@bytecodealliance/jco-transpile@0.23.0";
|
|
19
|
+
/** Pages of a 32-bit memory: the build-time clamp; installations budget below it at runtime. */
|
|
20
|
+
export const PREPARED_MAXIMUM_PAGES = 65536;
|
|
21
|
+
/** Generated component core modules; all are instrumented with `tembra:limits`. */
|
|
22
|
+
export const COMPONENT_CORE = /^orb\.core[0-9]*\.wasm$/;
|
|
23
|
+
/** JCO's own JSPI trampolines: fixed helpers carrying no component code. */
|
|
24
|
+
export const TRAMPOLINE_CORE =
|
|
25
|
+
/^orb\.conditional-(?:host-import-[0-9]+|suspending-(?:[123]-i32-to-i32|3-i32-to-void))\.wasm$/;
|
|
26
|
+
|
|
27
|
+
/** The generated `instantiate` export of instrumented JCO glue. */
|
|
28
|
+
export type Instantiate = (
|
|
29
|
+
getCoreModule: (name: string) => Promise<WebAssembly.Module>,
|
|
30
|
+
imports: Record<string, unknown>,
|
|
31
|
+
instantiateCore: (
|
|
32
|
+
module: WebAssembly.Module,
|
|
33
|
+
imports: WebAssembly.Imports,
|
|
34
|
+
) => Promise<WebAssembly.Instance>,
|
|
35
|
+
options: { tembraObserver: unknown },
|
|
36
|
+
) => Promise<Record<string, unknown>>;
|
|
37
|
+
|
|
38
|
+
/** Core module bytes as a generated loader supplies them. */
|
|
39
|
+
export type CoreSource = Response | ArrayBuffer | ArrayBufferView | WebAssembly.Module;
|
|
40
|
+
|
|
41
|
+
/** One generated core module of a prepared component. */
|
|
42
|
+
export interface PreparedCoreSource {
|
|
43
|
+
/** The name the generated glue requests. */
|
|
44
|
+
readonly name: string;
|
|
45
|
+
/** Pages one instantiation allocates (instrumented component cores only). */
|
|
46
|
+
readonly pages?: number;
|
|
47
|
+
/** Load the module's bytes; called at most once per successful compilation. */
|
|
48
|
+
readonly load: () => CoreSource | Promise<CoreSource>;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** What a generated adapter module passes to `preparedComponent`. */
|
|
52
|
+
export interface PreparedComponentSource {
|
|
53
|
+
readonly format: number;
|
|
54
|
+
readonly generator: string;
|
|
55
|
+
/** Identity of the prepared Orb, checked against the artifact's own metadata. */
|
|
56
|
+
readonly orb: { readonly name: string; readonly apiVersion: number };
|
|
57
|
+
/** Lowercase hexadecimal SHA-256 of the exact original artifact bytes. */
|
|
58
|
+
readonly artifact: string;
|
|
59
|
+
/** The page clamp the core modules were instrumented with. */
|
|
60
|
+
readonly maximumPages: number;
|
|
61
|
+
/** Exact versioned top-level import names of the verified component. */
|
|
62
|
+
readonly imports: readonly string[];
|
|
63
|
+
/** `import#function` names generated as suspending (JSPI) host imports. */
|
|
64
|
+
readonly suspending: readonly string[];
|
|
65
|
+
/** `export#function` names generated as promising (JSPI) exports. */
|
|
66
|
+
readonly promising: readonly string[];
|
|
67
|
+
readonly cores: readonly PreparedCoreSource[];
|
|
68
|
+
readonly instantiate: Instantiate;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* An application-owned compiled component adapter, created by a build-generated module. Pass it
|
|
73
|
+
* to `createHost({ isolated: { components: [...] } })`; its fields are informational.
|
|
74
|
+
*/
|
|
75
|
+
export interface PreparedComponent {
|
|
76
|
+
readonly orb: { readonly name: string; readonly apiVersion: number };
|
|
77
|
+
/** SHA-256 of the exact compiled artifact this adapter executes. */
|
|
78
|
+
readonly artifact: string;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The checked, immutable adapter record behind one `PreparedComponent`. */
|
|
82
|
+
export interface PreparedRecord {
|
|
83
|
+
readonly orb: PreparedComponent["orb"];
|
|
84
|
+
readonly artifact: string;
|
|
85
|
+
readonly maximumPages: number;
|
|
86
|
+
readonly imports: readonly string[];
|
|
87
|
+
readonly suspending: ReadonlySet<string>;
|
|
88
|
+
readonly promising: ReadonlySet<string>;
|
|
89
|
+
readonly cores: readonly PreparedCoreSource[];
|
|
90
|
+
readonly instantiate: Instantiate;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** A browser platform requirement is missing; no other engine is tried. */
|
|
94
|
+
export class BrowserPlatformError extends Error {
|
|
95
|
+
override readonly name = "BrowserPlatformError";
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const records = new WeakMap<object, PreparedRecord>();
|
|
99
|
+
|
|
100
|
+
const invalid = (detail: string) =>
|
|
101
|
+
new TypeError(`Invalid prepared component module (${detail}); rebuild it with Tembra tooling`);
|
|
102
|
+
|
|
103
|
+
function names(value: unknown, field: string): readonly string[] {
|
|
104
|
+
if (!Array.isArray(value) || value.some((name) => typeof name !== "string"))
|
|
105
|
+
throw invalid(`${field} must list names`);
|
|
106
|
+
if (new Set(value).size !== value.length) throw invalid(`duplicate ${field} name`);
|
|
107
|
+
return Object.freeze([...value]);
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Check a build-generated adapter description and capture it. Only generated modules call this;
|
|
112
|
+
* applications register the returned value.
|
|
113
|
+
*/
|
|
114
|
+
export function preparedComponent(source: PreparedComponentSource): PreparedComponent {
|
|
115
|
+
if (source?.format !== PREPARED_FORMAT) throw invalid("unsupported format");
|
|
116
|
+
if (source.generator !== PREPARED_GENERATOR)
|
|
117
|
+
throw invalid(`generated by ${String(source.generator)}, expected ${PREPARED_GENERATOR}`);
|
|
118
|
+
const orb = source.orb;
|
|
119
|
+
if (
|
|
120
|
+
typeof orb?.name !== "string" ||
|
|
121
|
+
!orb.name ||
|
|
122
|
+
!Number.isSafeInteger(orb.apiVersion) ||
|
|
123
|
+
orb.apiVersion <= 0
|
|
124
|
+
)
|
|
125
|
+
throw invalid("orb identity");
|
|
126
|
+
if (typeof source.artifact !== "string" || !/^[0-9a-f]{64}$/.test(source.artifact))
|
|
127
|
+
throw invalid("artifact digest");
|
|
128
|
+
if (
|
|
129
|
+
!Number.isSafeInteger(source.maximumPages) ||
|
|
130
|
+
source.maximumPages < 1 ||
|
|
131
|
+
source.maximumPages > PREPARED_MAXIMUM_PAGES
|
|
132
|
+
)
|
|
133
|
+
throw invalid("maximum pages");
|
|
134
|
+
if (typeof source.instantiate !== "function") throw invalid("instantiate");
|
|
135
|
+
if (!Array.isArray(source.cores)) throw invalid("cores");
|
|
136
|
+
const cores = source.cores.map((core): PreparedCoreSource => {
|
|
137
|
+
if (typeof core?.name !== "string" || typeof core.load !== "function")
|
|
138
|
+
throw invalid("core module");
|
|
139
|
+
if (COMPONENT_CORE.test(core.name)) {
|
|
140
|
+
if (!Number.isSafeInteger(core.pages) || core.pages! < 0 || core.pages! > source.maximumPages)
|
|
141
|
+
throw invalid(`initial pages of ${core.name}`);
|
|
142
|
+
return Object.freeze({ name: core.name, pages: core.pages!, load: core.load });
|
|
143
|
+
}
|
|
144
|
+
if (TRAMPOLINE_CORE.test(core.name) && core.pages === undefined)
|
|
145
|
+
return Object.freeze({ name: core.name, load: core.load });
|
|
146
|
+
throw invalid(`unexpected core module ${core.name}`);
|
|
147
|
+
});
|
|
148
|
+
if (new Set(cores.map((core) => core.name)).size !== cores.length)
|
|
149
|
+
throw invalid("duplicate core module");
|
|
150
|
+
if (!cores.some((core) => core.pages !== undefined)) throw invalid("no component core module");
|
|
151
|
+
const identity = Object.freeze({ name: orb.name, apiVersion: orb.apiVersion });
|
|
152
|
+
const record: PreparedRecord = {
|
|
153
|
+
orb: identity,
|
|
154
|
+
artifact: source.artifact,
|
|
155
|
+
maximumPages: source.maximumPages,
|
|
156
|
+
imports: names(source.imports, "import"),
|
|
157
|
+
suspending: new Set(names(source.suspending, "suspending import")),
|
|
158
|
+
promising: new Set(names(source.promising, "promising export")),
|
|
159
|
+
cores: Object.freeze(cores),
|
|
160
|
+
instantiate: source.instantiate,
|
|
161
|
+
};
|
|
162
|
+
const component: PreparedComponent = Object.freeze({
|
|
163
|
+
orb: identity,
|
|
164
|
+
artifact: source.artifact,
|
|
165
|
+
});
|
|
166
|
+
records.set(component, record);
|
|
167
|
+
return component;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* Index registered adapters by artifact digest. A value not created by `preparedComponent` (for
|
|
172
|
+
* example a copied object or a different SDK instance) is refused rather than trusted.
|
|
173
|
+
*/
|
|
174
|
+
export function preparedRegistry(
|
|
175
|
+
components: readonly PreparedComponent[] | undefined,
|
|
176
|
+
): ReadonlyMap<string, PreparedRecord> {
|
|
177
|
+
const registry = new Map<string, PreparedRecord>();
|
|
178
|
+
if (components === undefined) return registry;
|
|
179
|
+
if (!Array.isArray(components))
|
|
180
|
+
throw new TypeError("isolated.components must list prepared components");
|
|
181
|
+
for (const component of components) {
|
|
182
|
+
const record = records.get(component as object);
|
|
183
|
+
if (!record)
|
|
184
|
+
throw new TypeError(
|
|
185
|
+
"isolated.components accepts only modules generated by Tembra tooling (build with " +
|
|
186
|
+
"`browser: true`) and imported from the same @syntropika/tembra-sdk",
|
|
187
|
+
);
|
|
188
|
+
const existing = registry.get(record.artifact);
|
|
189
|
+
if (existing && existing !== record)
|
|
190
|
+
throw new TypeError(`Two prepared components are registered for artifact ${record.artifact}`);
|
|
191
|
+
registry.set(record.artifact, record);
|
|
192
|
+
}
|
|
193
|
+
return registry;
|
|
194
|
+
}
|
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
/** Provider-owned WIT resources of the bounded compiled capability profile. */
|
|
2
|
+
import type { ReferenceRecord } from "../../runtime/records.ts";
|
|
3
|
+
import type { Session } from "../../runtime/session.ts";
|
|
4
|
+
import type { ResourceCapability, ResourceLoan } from "#tembra-adapters";
|
|
5
|
+
import type { GraphFunction, TypeGraph } from "./values.ts";
|
|
6
|
+
import { bindingName } from "./names.ts";
|
|
7
|
+
|
|
8
|
+
export interface Nominal {
|
|
9
|
+
readonly interface: string;
|
|
10
|
+
readonly name: string;
|
|
11
|
+
}
|
|
12
|
+
export interface ResourceRoles {
|
|
13
|
+
readonly arguments?:
|
|
14
|
+
| ((value: unknown, own: (nominal: Nominal, value: unknown) => unknown) => unknown)
|
|
15
|
+
| undefined;
|
|
16
|
+
readonly receiver?: Nominal | undefined;
|
|
17
|
+
readonly owned?: readonly Nominal[] | undefined;
|
|
18
|
+
/** Map only own positions in the host-domain result; other values remain ordinary data. */
|
|
19
|
+
readonly result?:
|
|
20
|
+
| ((value: unknown, own: (nominal: Nominal, value: unknown) => unknown) => unknown)
|
|
21
|
+
| undefined;
|
|
22
|
+
readonly stream?: boolean | undefined;
|
|
23
|
+
readonly resource?: Nominal | undefined;
|
|
24
|
+
readonly member?: string | undefined;
|
|
25
|
+
readonly construct?: boolean | undefined;
|
|
26
|
+
}
|
|
27
|
+
const same = (a: Nominal, b: Nominal) => a.interface === b.interface && a.name === b.name;
|
|
28
|
+
|
|
29
|
+
/** Physical resource state survives ownership moves and outstanding borrowed calls. */
|
|
30
|
+
class ResourceState {
|
|
31
|
+
anchor: { session: Session; reference: ReferenceRecord } | undefined;
|
|
32
|
+
borrows = 0;
|
|
33
|
+
closing = false;
|
|
34
|
+
closed = false;
|
|
35
|
+
settled = false;
|
|
36
|
+
transferred = false;
|
|
37
|
+
readonly callbacks = new Set<() => void>();
|
|
38
|
+
constructor(
|
|
39
|
+
readonly issuer: object,
|
|
40
|
+
readonly environment: number,
|
|
41
|
+
readonly value: object,
|
|
42
|
+
readonly destroy: () => void | Promise<void>,
|
|
43
|
+
) {}
|
|
44
|
+
close(): void {
|
|
45
|
+
this.closing = true;
|
|
46
|
+
this.finish();
|
|
47
|
+
}
|
|
48
|
+
finish(): void {
|
|
49
|
+
if (!this.closing || this.closed || this.borrows) return;
|
|
50
|
+
this.closed = true;
|
|
51
|
+
const finish = () => {
|
|
52
|
+
if (this.anchor) this.anchor.session.handles.release(this.anchor.reference.id);
|
|
53
|
+
this.anchor = undefined;
|
|
54
|
+
this.settled = true;
|
|
55
|
+
for (const operation of this.callbacks) operation();
|
|
56
|
+
this.callbacks.clear();
|
|
57
|
+
};
|
|
58
|
+
try {
|
|
59
|
+
const pending = this.transferred ? undefined : this.destroy();
|
|
60
|
+
if (pending) {
|
|
61
|
+
void pending.then(finish, finish);
|
|
62
|
+
return;
|
|
63
|
+
}
|
|
64
|
+
} catch (error) {
|
|
65
|
+
finish();
|
|
66
|
+
throw error;
|
|
67
|
+
}
|
|
68
|
+
finish();
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** One live ownership generation; moving extracts all physical authority from stale aliases. */
|
|
73
|
+
export class ResourceOwner implements ResourceCapability {
|
|
74
|
+
readonly kind = "resource";
|
|
75
|
+
#state: ResourceState | undefined;
|
|
76
|
+
readonly #invalidated = new Map<() => void, () => void>();
|
|
77
|
+
constructor(
|
|
78
|
+
readonly nominal: Nominal,
|
|
79
|
+
issuer: object,
|
|
80
|
+
environment: number,
|
|
81
|
+
value: object,
|
|
82
|
+
destroy: () => void | Promise<void>,
|
|
83
|
+
) {
|
|
84
|
+
this.#state = new ResourceState(issuer, environment, value, destroy);
|
|
85
|
+
}
|
|
86
|
+
#live(): ResourceState {
|
|
87
|
+
const state = this.#state;
|
|
88
|
+
if (!state || state.closing) throw new Error("Resource is not live");
|
|
89
|
+
return state;
|
|
90
|
+
}
|
|
91
|
+
#invalidate(): void {
|
|
92
|
+
const state = this.#state;
|
|
93
|
+
this.#state = undefined;
|
|
94
|
+
for (const [operation, callback] of this.#invalidated) {
|
|
95
|
+
state?.callbacks.delete(callback);
|
|
96
|
+
operation();
|
|
97
|
+
}
|
|
98
|
+
this.#invalidated.clear();
|
|
99
|
+
}
|
|
100
|
+
/** Revision retirement follows the physical resource even after its original wrapper moves. */
|
|
101
|
+
retirement(): () => void {
|
|
102
|
+
const state = this.#live();
|
|
103
|
+
return () => state.close();
|
|
104
|
+
}
|
|
105
|
+
whenRetired(operation: () => void): void {
|
|
106
|
+
const state = this.#live();
|
|
107
|
+
state.callbacks.add(operation);
|
|
108
|
+
}
|
|
109
|
+
anchor(session: Session, reference: ReferenceRecord): void {
|
|
110
|
+
const state = this.#live();
|
|
111
|
+
if (state.anchor) throw new Error("Resource was already delivered or closed");
|
|
112
|
+
state.anchor = { session, reference: session.handles.duplicate(reference) };
|
|
113
|
+
}
|
|
114
|
+
get reference(): ReferenceRecord {
|
|
115
|
+
const state = this.#live();
|
|
116
|
+
if (!state.anchor) throw new Error("Resource is not live");
|
|
117
|
+
return state.anchor.reference;
|
|
118
|
+
}
|
|
119
|
+
lend(): ResourceLoan {
|
|
120
|
+
const state = this.#live();
|
|
121
|
+
state.borrows++;
|
|
122
|
+
let borrowed: ResourceState | undefined = state;
|
|
123
|
+
const nominal = this.nominal;
|
|
124
|
+
return Object.assign(
|
|
125
|
+
() => {
|
|
126
|
+
const current = borrowed;
|
|
127
|
+
if (!current) return;
|
|
128
|
+
borrowed = undefined;
|
|
129
|
+
current.borrows--;
|
|
130
|
+
current.finish();
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
receiver: {
|
|
134
|
+
redeem(issuer: object, environment: number, expected: Nominal) {
|
|
135
|
+
const current = borrowed;
|
|
136
|
+
if (
|
|
137
|
+
!current ||
|
|
138
|
+
current.closed ||
|
|
139
|
+
current.issuer !== issuer ||
|
|
140
|
+
current.environment !== environment
|
|
141
|
+
)
|
|
142
|
+
throw new Error("Resource belongs to another instance or a retired revision");
|
|
143
|
+
if (!same(nominal, expected)) throw new Error("Resource has another nominal type");
|
|
144
|
+
return current.value;
|
|
145
|
+
},
|
|
146
|
+
},
|
|
147
|
+
},
|
|
148
|
+
);
|
|
149
|
+
}
|
|
150
|
+
redeem(issuer: object, environment: number, expected: Nominal): object {
|
|
151
|
+
const state = this.#state;
|
|
152
|
+
if (!state || state.closed || state.issuer !== issuer || state.environment !== environment)
|
|
153
|
+
throw new Error("Resource belongs to another instance or a retired revision");
|
|
154
|
+
if (!same(this.nominal, expected)) throw new Error("Resource has another nominal type");
|
|
155
|
+
return state.value;
|
|
156
|
+
}
|
|
157
|
+
issuedBy(issuer: object): boolean {
|
|
158
|
+
return this.#live().issuer === issuer;
|
|
159
|
+
}
|
|
160
|
+
move(): ResourceOwner {
|
|
161
|
+
const state = this.#live();
|
|
162
|
+
const next = new ResourceOwner(
|
|
163
|
+
this.nominal,
|
|
164
|
+
state.issuer,
|
|
165
|
+
state.environment,
|
|
166
|
+
state.value,
|
|
167
|
+
state.destroy,
|
|
168
|
+
);
|
|
169
|
+
next.#state = state;
|
|
170
|
+
this.#invalidate();
|
|
171
|
+
return next;
|
|
172
|
+
}
|
|
173
|
+
take(issuer: object, expected: Nominal): object {
|
|
174
|
+
const state = this.#live();
|
|
175
|
+
if (state.issuer !== issuer || !same(this.nominal, expected))
|
|
176
|
+
throw new Error("Resource belongs to another issuing instance or nominal type");
|
|
177
|
+
state.transferred = true;
|
|
178
|
+
this.#invalidate();
|
|
179
|
+
state.close();
|
|
180
|
+
return state.value;
|
|
181
|
+
}
|
|
182
|
+
whenClosed(operation: () => void): void {
|
|
183
|
+
const state = this.#state;
|
|
184
|
+
if (!state || state.settled) operation();
|
|
185
|
+
else if (!this.#invalidated.has(operation)) {
|
|
186
|
+
const callback = () => {
|
|
187
|
+
if (this.#invalidated.delete(operation)) operation();
|
|
188
|
+
};
|
|
189
|
+
this.#invalidated.set(operation, callback);
|
|
190
|
+
state.callbacks.add(callback);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
close(): void {
|
|
194
|
+
this.#state?.close();
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/** Read roles already admitted by the Rust resource profile; handles remain outside data. */
|
|
199
|
+
export function resourceRoles(graph: TypeGraph, binding: string, fn: GraphFunction): ResourceRoles {
|
|
200
|
+
const definitions = new Map(graph.types.map(({ id, definition }) => [id, definition]));
|
|
201
|
+
const resolve = (type: unknown): unknown => {
|
|
202
|
+
for (let depth = 0; typeof type === "number" && depth < 64; depth++) {
|
|
203
|
+
const kind = definitions.get(type)?.kind;
|
|
204
|
+
if (typeof kind !== "object" || kind.type === undefined) break;
|
|
205
|
+
type = kind.type;
|
|
206
|
+
}
|
|
207
|
+
return type;
|
|
208
|
+
};
|
|
209
|
+
const nominal = (id: unknown, foreign = false): Nominal => {
|
|
210
|
+
const definition = typeof id === "number" ? definitions.get(resolve(id) as number) : undefined;
|
|
211
|
+
if (definition?.kind !== "resource" || !definition.owner || !definition.name)
|
|
212
|
+
throw new Error("Resource has no portable nominal identity");
|
|
213
|
+
if (definition.owner !== binding && !foreign)
|
|
214
|
+
throw new Error("Resource requires its defining interface");
|
|
215
|
+
if (definition.owner !== binding && foreign) {
|
|
216
|
+
const imports = (
|
|
217
|
+
graph as TypeGraph & {
|
|
218
|
+
imports?: { binding: string; contract?: string }[];
|
|
219
|
+
}
|
|
220
|
+
).imports;
|
|
221
|
+
if (!imports?.some((entry) => (entry.contract ?? entry.binding) === definition.owner))
|
|
222
|
+
throw new Error("Resource argument requires its imported defining interface");
|
|
223
|
+
}
|
|
224
|
+
return { interface: definition.owner, name: definition.name };
|
|
225
|
+
};
|
|
226
|
+
const kind = fn.kind;
|
|
227
|
+
let receiver: Nominal | undefined;
|
|
228
|
+
let resource: Nominal | undefined;
|
|
229
|
+
let constructor = false;
|
|
230
|
+
let member: string | undefined;
|
|
231
|
+
if (typeof kind === "object" && kind !== null) {
|
|
232
|
+
const [form, id] = Object.entries(kind)[0] ?? [];
|
|
233
|
+
resource = nominal(id);
|
|
234
|
+
constructor = form === "constructor";
|
|
235
|
+
if (form === "method" || form === "async-method") receiver = resource;
|
|
236
|
+
if (!constructor) member = fn.name?.split(".").at(-1);
|
|
237
|
+
}
|
|
238
|
+
const owned = new Map<string, Nominal>();
|
|
239
|
+
type MapOwn = (value: unknown, own: (nominal: Nominal, value: unknown) => unknown) => unknown;
|
|
240
|
+
const mapper = (type: unknown, foreign = false): MapOwn | undefined => {
|
|
241
|
+
const kind = definitions.get(resolve(type) as number)?.kind;
|
|
242
|
+
if (typeof kind !== "object") return undefined;
|
|
243
|
+
if (kind.handle?.own !== undefined) {
|
|
244
|
+
const identity = nominal(kind.handle.own, foreign);
|
|
245
|
+
if (!foreign) owned.set(identity.name, identity);
|
|
246
|
+
return (value, own) => own(identity, value);
|
|
247
|
+
}
|
|
248
|
+
if (kind.list !== undefined) {
|
|
249
|
+
const item = mapper(kind.list, foreign);
|
|
250
|
+
return item
|
|
251
|
+
? (value, own) => (value as unknown[]).map((value) => item(value, own))
|
|
252
|
+
: undefined;
|
|
253
|
+
}
|
|
254
|
+
if (kind.option !== undefined) {
|
|
255
|
+
const inner = mapper(kind.option, foreign);
|
|
256
|
+
return inner ? (value, own) => (value == null ? value : inner(value, own)) : undefined;
|
|
257
|
+
}
|
|
258
|
+
if (kind.record) {
|
|
259
|
+
const fields = kind.record.fields.map(
|
|
260
|
+
({ name, type }) => [graph.javascriptNames[name]!, mapper(type, foreign)] as const,
|
|
261
|
+
);
|
|
262
|
+
if (!fields.some(([, map]) => map)) return undefined;
|
|
263
|
+
return (value, own) => {
|
|
264
|
+
const output = { ...(value as Record<string, unknown>) };
|
|
265
|
+
for (const [name, map] of fields) if (map) output[name] = map(output[name], own);
|
|
266
|
+
return output;
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
if (kind.tuple) {
|
|
270
|
+
const fields = kind.tuple.types.map((type) => mapper(type, foreign));
|
|
271
|
+
return fields.some(Boolean)
|
|
272
|
+
? (value, own) =>
|
|
273
|
+
(value as unknown[]).map((value, index) => {
|
|
274
|
+
const map = fields[index];
|
|
275
|
+
return map ? map(value, own) : value;
|
|
276
|
+
})
|
|
277
|
+
: undefined;
|
|
278
|
+
}
|
|
279
|
+
if (kind.variant || kind.result) {
|
|
280
|
+
const cases = kind.variant?.cases ?? [
|
|
281
|
+
{ name: "ok", type: kind.result!.ok },
|
|
282
|
+
{ name: "err", type: kind.result!.err },
|
|
283
|
+
];
|
|
284
|
+
const maps = new Map(cases.map(({ name, type }) => [name, mapper(type, foreign)]));
|
|
285
|
+
if (![...maps.values()].some(Boolean)) return undefined;
|
|
286
|
+
return (value, own) => {
|
|
287
|
+
const tagged = value as { tag: string; val?: unknown };
|
|
288
|
+
const map = maps.get(tagged.tag);
|
|
289
|
+
return map ? { tag: tagged.tag, val: map(tagged.val, own) } : value;
|
|
290
|
+
};
|
|
291
|
+
}
|
|
292
|
+
return undefined;
|
|
293
|
+
};
|
|
294
|
+
const resultKind = definitions.get(resolve(fn.result) as number)?.kind;
|
|
295
|
+
const stream = typeof resultKind === "object" && resolve(resultKind.stream) === "u8";
|
|
296
|
+
const result = mapper(fn.result);
|
|
297
|
+
const params = (receiver ? fn.params.slice(1) : fn.params).map(({ type }) => mapper(type, true));
|
|
298
|
+
const arguments_: MapOwn | undefined = params.some(Boolean)
|
|
299
|
+
? (value, own) => (value as unknown[]).map((item, index) => params[index]?.(item, own) ?? item)
|
|
300
|
+
: undefined;
|
|
301
|
+
return {
|
|
302
|
+
arguments: arguments_,
|
|
303
|
+
receiver,
|
|
304
|
+
owned: owned.size ? [...owned.values()] : undefined,
|
|
305
|
+
result,
|
|
306
|
+
stream,
|
|
307
|
+
resource,
|
|
308
|
+
member,
|
|
309
|
+
construct: constructor,
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** The signature of the checked data lane: self and whole capabilities travel separately. */
|
|
314
|
+
export function resourceDataFunction(fn: GraphFunction, roles: ResourceRoles): GraphFunction {
|
|
315
|
+
return {
|
|
316
|
+
...fn,
|
|
317
|
+
params: roles.receiver ? fn.params.slice(1) : fn.params,
|
|
318
|
+
result: roles.stream ? undefined : fn.result,
|
|
319
|
+
};
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/** Resolve the JCO resource class/member rather than its flattened contract spelling. */
|
|
323
|
+
export function resourceExport(
|
|
324
|
+
exports: Record<string, unknown>,
|
|
325
|
+
spelling: string,
|
|
326
|
+
roles: ResourceRoles,
|
|
327
|
+
receiver: object | undefined,
|
|
328
|
+
args: readonly unknown[],
|
|
329
|
+
enter?: () => readonly unknown[],
|
|
330
|
+
): unknown {
|
|
331
|
+
if (!roles.resource) {
|
|
332
|
+
const fn = exports[spelling];
|
|
333
|
+
if (typeof fn !== "function") throw new Error(`Missing component export ${spelling}`);
|
|
334
|
+
return fn(...(enter?.() ?? args));
|
|
335
|
+
}
|
|
336
|
+
const Resource = exports[bindingName(roles.resource.name, true)] as
|
|
337
|
+
| (new (...args: unknown[]) => unknown)
|
|
338
|
+
| undefined;
|
|
339
|
+
if (typeof Resource !== "function") throw new Error("Missing component resource class");
|
|
340
|
+
if (roles.construct) return new Resource(...(enter?.() ?? args));
|
|
341
|
+
const target = roles.receiver ? receiver : Resource;
|
|
342
|
+
const fn = (target as Record<string, unknown> | undefined)?.[bindingName(roles.member!, false)];
|
|
343
|
+
if (typeof fn !== "function") throw new Error("Missing component resource method");
|
|
344
|
+
return fn.apply(target, enter?.() ?? args);
|
|
345
|
+
}
|