@syntropika/tembra-sdk 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/README.md +47 -2
- package/dist/authoring/declaration.d.ts +47 -0
- package/dist/authoring/hooks.d.ts +11 -0
- package/dist/authoring/orb.d.ts +3 -0
- package/dist/authoring/types.d.ts +166 -0
- package/dist/bridge/identifiers.d.ts +207 -0
- package/dist/bridge/kernel.d.ts +117 -0
- package/dist/bridge/protocol.d.ts +181 -0
- package/dist/browser.d.ts +21 -0
- package/dist/browser.js +3282 -0
- package/dist/codec.d.ts +1 -0
- package/dist/codecs/json.d.ts +13 -0
- package/dist/codecs/msgpack.d.ts +3 -0
- package/dist/context-key.d.ts +35 -0
- package/dist/coordinator.d.ts +1 -0
- package/dist/coordinator.js +543 -0
- package/dist/embedded.d.ts +1 -0
- package/dist/embedded.js +1 -0
- package/dist/error.d.ts +13 -0
- package/dist/errors.d.ts +122 -0
- package/dist/hooks.d.ts +1 -0
- package/dist/host.d.ts +96 -0
- package/dist/host.js +3225 -0
- package/dist/identifiers.d.ts +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +833 -0
- package/dist/infrastructure/coordinator.d.ts +13 -0
- package/dist/infrastructure/manager.d.ts +23 -0
- package/dist/infrastructure/rpc/channel.d.ts +52 -0
- package/dist/infrastructure/rpc/client.d.ts +20 -0
- package/dist/infrastructure/rpc/server.d.ts +10 -0
- package/dist/infrastructure/rpc/state.d.ts +16 -0
- package/dist/kernel.d.ts +1 -0
- package/dist/manager.d.ts +1 -0
- package/dist/manager.js +390 -0
- package/dist/msgpack.d.ts +1 -0
- package/dist/msgpack.js +635 -0
- package/dist/node.d.ts +14 -0
- package/dist/node.js +3283 -0
- package/dist/orb.d.ts +1 -0
- package/dist/protocol.d.ts +1 -0
- package/dist/rpc.d.ts +3 -0
- package/dist/rpc.js +1036 -0
- package/dist/runtime/activities.d.ts +30 -0
- package/dist/runtime/calls.d.ts +22 -0
- package/dist/runtime/context.d.ts +37 -0
- package/dist/runtime/declaration.d.ts +1 -0
- package/dist/runtime/lifecycle.d.ts +28 -0
- package/dist/runtime/orbs.d.ts +39 -0
- package/dist/runtime/programs.d.ts +31 -0
- package/dist/runtime/records.d.ts +107 -0
- package/dist/runtime/references.d.ts +38 -0
- package/dist/runtime/reload.d.ts +17 -0
- package/dist/runtime/resources.d.ts +24 -0
- package/dist/runtime/scopes.d.ts +35 -0
- package/dist/runtime/session.d.ts +69 -0
- package/dist/state/binding.d.ts +28 -0
- package/dist/state/selection.d.ts +21 -0
- package/dist/state/types.d.ts +35 -0
- package/dist/state.d.ts +2 -0
- package/dist/telemetry.d.ts +23 -0
- package/dist/telemetry.js +27 -0
- package/dist/tooling/build.d.ts +3 -0
- package/dist/tooling/index.d.ts +2 -0
- package/dist/tooling/index.js +181 -0
- package/dist/tooling/resolver.d.ts +5 -0
- package/dist/tooling/typecheck.d.ts +2 -0
- package/dist/tooling/types.d.ts +29 -0
- package/dist/types.d.ts +1 -0
- package/dist/values.d.ts +23 -0
- package/package.json +103 -4
- package/src/authoring/declaration.ts +220 -0
- package/src/authoring/hooks.ts +101 -0
- package/src/authoring/orb.ts +77 -0
- package/src/authoring/types.ts +212 -0
- package/src/bridge/identifiers.ts +212 -0
- package/src/bridge/kernel.ts +117 -0
- package/src/bridge/protocol.ts +193 -0
- package/src/browser.ts +59 -0
- package/src/codec.ts +1 -0
- package/src/codecs/json.ts +147 -0
- package/src/codecs/msgpack.ts +26 -0
- package/src/context-key.ts +94 -0
- package/src/coordinator.ts +1 -0
- package/src/embedded.ts +293 -0
- package/src/error.ts +50 -0
- package/src/errors.ts +237 -0
- package/src/hooks.ts +1 -0
- package/src/host.ts +142 -0
- package/src/identifiers.ts +1 -0
- package/src/index.ts +22 -0
- package/src/infrastructure/coordinator.ts +76 -0
- package/src/infrastructure/manager.ts +77 -0
- package/src/infrastructure/rpc/channel.ts +88 -0
- package/src/infrastructure/rpc/client.ts +161 -0
- package/src/infrastructure/rpc/server.ts +201 -0
- package/src/infrastructure/rpc/state.ts +70 -0
- package/src/kernel.ts +1 -0
- package/src/manager.ts +1 -0
- package/src/msgpack.ts +1 -0
- package/src/node.ts +53 -0
- package/src/orb.ts +1 -0
- package/src/protocol.ts +1 -0
- package/src/rpc.ts +3 -0
- package/src/runtime/activities.ts +197 -0
- package/src/runtime/calls.ts +165 -0
- package/src/runtime/context.ts +113 -0
- package/src/runtime/declaration.ts +1 -0
- package/src/runtime/lifecycle.ts +227 -0
- package/src/runtime/orbs.ts +292 -0
- package/src/runtime/programs.ts +274 -0
- package/src/runtime/records.ts +127 -0
- package/src/runtime/references.ts +398 -0
- package/src/runtime/reload.ts +161 -0
- package/src/runtime/resources.ts +157 -0
- package/src/runtime/scopes.ts +210 -0
- package/src/runtime/session.ts +181 -0
- package/src/state/binding.ts +157 -0
- package/src/state/selection.ts +122 -0
- package/src/state/types.ts +47 -0
- package/src/state.ts +2 -0
- package/src/telemetry.ts +45 -0
- package/src/tooling/build.ts +83 -0
- package/src/tooling/index.ts +8 -0
- package/src/tooling/resolver.ts +95 -0
- package/src/tooling/typecheck.ts +32 -0
- package/src/tooling/types.ts +32 -0
- package/src/types.ts +1 -0
- package/src/values.ts +85 -0
package/src/embedded.ts
ADDED
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
import type { HostOptions } from "./authoring/types.ts";
|
|
2
|
+
import {
|
|
3
|
+
Code,
|
|
4
|
+
HookCapability,
|
|
5
|
+
Lifetime,
|
|
6
|
+
Reason,
|
|
7
|
+
ReloadStatus,
|
|
8
|
+
Status,
|
|
9
|
+
} from "./bridge/identifiers.ts";
|
|
10
|
+
import { jsonCodec } from "./codecs/json.ts";
|
|
11
|
+
import { failure, TembraError } from "./error.ts";
|
|
12
|
+
import { ContextKey, ContextKind, opaqueFrom } from "./context-key.ts";
|
|
13
|
+
import { Errors } from "./errors.ts";
|
|
14
|
+
import { Host } from "./host.ts";
|
|
15
|
+
import { Context } from "./runtime/context.ts";
|
|
16
|
+
import { KernelOp } from "./bridge/protocol.ts";
|
|
17
|
+
import type { Invocation } from "./bridge/kernel.ts";
|
|
18
|
+
|
|
19
|
+
declare const Deno: {
|
|
20
|
+
core: {
|
|
21
|
+
ops: Record<string, (...args: any[]) => any>;
|
|
22
|
+
unrefOpPromise(promise: Promise<unknown>): void;
|
|
23
|
+
};
|
|
24
|
+
};
|
|
25
|
+
const ops = Deno.core.ops;
|
|
26
|
+
const globals = globalThis as any;
|
|
27
|
+
|
|
28
|
+
// Embedded V8 has no browser or Node dependency. Scheduling belongs to this adapter.
|
|
29
|
+
globals.queueMicrotask ??= (callback: () => void) => Promise.resolve().then(callback);
|
|
30
|
+
globals.performance ??= {
|
|
31
|
+
/** Use the Rust runtime's monotonic clock. */
|
|
32
|
+
now: () => ops.op_tembra_now!(),
|
|
33
|
+
};
|
|
34
|
+
globals.AbortController ??= class {
|
|
35
|
+
signal = {
|
|
36
|
+
aborted: false,
|
|
37
|
+
reason: undefined as unknown,
|
|
38
|
+
listeners: new Set<any>(),
|
|
39
|
+
/** Retain a cancellation listener until it is removed or fired. */
|
|
40
|
+
addEventListener(_type: string, callback: any) {
|
|
41
|
+
this.listeners.add(callback);
|
|
42
|
+
},
|
|
43
|
+
/** Release a cancellation listener without invoking it. */
|
|
44
|
+
removeEventListener(_type: string, callback: any) {
|
|
45
|
+
this.listeners.delete(callback);
|
|
46
|
+
},
|
|
47
|
+
/** Reject work after cancellation has been signalled. */
|
|
48
|
+
throwIfAborted() {
|
|
49
|
+
if (this.aborted) throw this.reason;
|
|
50
|
+
},
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
/** Signal cancellation once without waiting for physical work. */
|
|
54
|
+
abort(reason: unknown = new Error("Aborted")) {
|
|
55
|
+
if (this.signal.aborted) return;
|
|
56
|
+
this.signal.aborted = true;
|
|
57
|
+
this.signal.reason = reason;
|
|
58
|
+
for (const callback of [...this.signal.listeners]) callback();
|
|
59
|
+
this.signal.listeners.clear();
|
|
60
|
+
}
|
|
61
|
+
};
|
|
62
|
+
let nextTimer = 0;
|
|
63
|
+
const timers = new Set<number>();
|
|
64
|
+
globals.setTimeout ??= (callback: (...args: unknown[]) => void, delay = 0, ...args: unknown[]) => {
|
|
65
|
+
const id = ++nextTimer;
|
|
66
|
+
timers.add(id);
|
|
67
|
+
void ops.op_tembra_sleep!(id, Math.max(0, Math.min(0x7fff_ffff, delay))).then(() => {
|
|
68
|
+
if (timers.delete(id)) callback(...args);
|
|
69
|
+
});
|
|
70
|
+
return id;
|
|
71
|
+
};
|
|
72
|
+
globals.clearTimeout ??= (id: number) => {
|
|
73
|
+
if (timers.delete(id)) ops.op_tembra_clear_timer!(id);
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
/** The same JS adapter used by Node and browsers, backed by injected Rust operations. */
|
|
77
|
+
function createHost(options: Omit<HostOptions, "kernel" | "native"> = {}): Host {
|
|
78
|
+
const codec = options.serialization ?? jsonCodec;
|
|
79
|
+
if (codec.id !== ops.op_tembra_codec!())
|
|
80
|
+
throw new TembraError(Errors.Conflict.Codec, "The Rust and JS host codecs must agree");
|
|
81
|
+
/** Decode native callback results with the agreed host codec. */
|
|
82
|
+
function answer(bytes: Uint8Array): any {
|
|
83
|
+
const envelope = codec.deserialize(bytes) as any;
|
|
84
|
+
if (envelope.error) throw new TembraError(envelope.error);
|
|
85
|
+
return envelope.ok;
|
|
86
|
+
}
|
|
87
|
+
const cooperative = ops.op_tembra_driver_enabled?.() ?? false;
|
|
88
|
+
const pending = new Map<
|
|
89
|
+
number,
|
|
90
|
+
{ resolve(value: unknown): void; reject(error: unknown): void }
|
|
91
|
+
>();
|
|
92
|
+
globals.__tembraDeliver = (batch: [number, Uint8Array | string, boolean][]) => {
|
|
93
|
+
for (const [id, payload, success] of batch) {
|
|
94
|
+
const waiter = pending.get(id);
|
|
95
|
+
if (!waiter) throw new Error("unknown native completion");
|
|
96
|
+
pending.delete(id);
|
|
97
|
+
try {
|
|
98
|
+
if (!success) throw new Error(payload as string);
|
|
99
|
+
waiter.resolve(answer(payload as Uint8Array));
|
|
100
|
+
} catch (error) {
|
|
101
|
+
waiter.reject(error);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
function submit(operation: string, payload: Uint8Array): Promise<any> {
|
|
106
|
+
const id = ops.op_tembra_submit!(operation, payload);
|
|
107
|
+
return new Promise((resolve, reject) => pending.set(id, { resolve, reject }));
|
|
108
|
+
}
|
|
109
|
+
const host = new Host({
|
|
110
|
+
...options,
|
|
111
|
+
clockOrigin: 0,
|
|
112
|
+
kernel: {
|
|
113
|
+
/** Exchange kernel metadata without encoding JS payload values. */
|
|
114
|
+
request: (metadata) => ops.op_tembra_kernel!(metadata),
|
|
115
|
+
},
|
|
116
|
+
native: {
|
|
117
|
+
...(cooperative
|
|
118
|
+
? {
|
|
119
|
+
admit: (reference: number, method: string, ctx: Context) => {
|
|
120
|
+
const result = JSON.parse(
|
|
121
|
+
ops.op_tembra_admit!(
|
|
122
|
+
JSON.stringify({
|
|
123
|
+
reference,
|
|
124
|
+
method,
|
|
125
|
+
root: ctx.root,
|
|
126
|
+
context: ctx.frame,
|
|
127
|
+
parent: ctx.invocation?.id,
|
|
128
|
+
}),
|
|
129
|
+
),
|
|
130
|
+
) as any;
|
|
131
|
+
if (result.error) throw new TembraError(result.error);
|
|
132
|
+
return result.ok;
|
|
133
|
+
},
|
|
134
|
+
finish: (call: number, now: number) => {
|
|
135
|
+
const result = JSON.parse(ops.op_tembra_finish!(call, String(now))) as any;
|
|
136
|
+
if (result.error) throw new TembraError(result.error);
|
|
137
|
+
return result.ok;
|
|
138
|
+
},
|
|
139
|
+
}
|
|
140
|
+
: {}),
|
|
141
|
+
rootEnded: (root) => ops.op_tembra_end_context!(root),
|
|
142
|
+
access: (orb, service, principal) =>
|
|
143
|
+
JSON.parse(ops.op_tembra_access!(orb, service, principal)) ?? undefined,
|
|
144
|
+
settled: () => ops.op_tembra_settled!(),
|
|
145
|
+
notify: (action) => ops.op_tembra_notify!(JSON.stringify(action)),
|
|
146
|
+
hasContribution: (operation) => ops.op_tembra_has_contribution?.(operation) ?? false,
|
|
147
|
+
contribute: async (operation, ctx, input) => {
|
|
148
|
+
const result = answer(
|
|
149
|
+
await ops.op_tembra_native!(
|
|
150
|
+
"contribute",
|
|
151
|
+
codec.serialize({
|
|
152
|
+
operation,
|
|
153
|
+
root: ctx.root,
|
|
154
|
+
frame: ctx.frame,
|
|
155
|
+
...(input === undefined ? {} : { input }),
|
|
156
|
+
}),
|
|
157
|
+
),
|
|
158
|
+
);
|
|
159
|
+
return result.value;
|
|
160
|
+
},
|
|
161
|
+
/** Check whether this realm must delegate the orb to Rust. */
|
|
162
|
+
hasOrb: (id) => ops.op_tembra_has_orb!(id),
|
|
163
|
+
/** Declare native scopes before the shared kernel activates them. */
|
|
164
|
+
activate: async (object, orb, service) => {
|
|
165
|
+
answer(await ops.op_tembra_native!("activate", codec.serialize({ object, orb, service })));
|
|
166
|
+
},
|
|
167
|
+
/** Encode only the call arguments that cross into Rust. */
|
|
168
|
+
invoke: async (invocation, arguments_) =>
|
|
169
|
+
cooperative
|
|
170
|
+
? submit("invoke", codec.serialize({ invocation, arguments: arguments_ }))
|
|
171
|
+
: answer(
|
|
172
|
+
await ops.op_tembra_native!(
|
|
173
|
+
"invoke",
|
|
174
|
+
codec.serialize({ invocation, arguments: arguments_ }),
|
|
175
|
+
),
|
|
176
|
+
),
|
|
177
|
+
/** Release native object storage after shared scope cleanup. */
|
|
178
|
+
dispose: async (object) => {
|
|
179
|
+
answer(await ops.op_tembra_native!("dispose", codec.serialize({ object })));
|
|
180
|
+
},
|
|
181
|
+
/** Delegate callback execution while Rust retains lifecycle ordering. */
|
|
182
|
+
effect: async (effect) =>
|
|
183
|
+
answer(await ops.op_tembra_native!("effect", codec.serialize(effect))),
|
|
184
|
+
/** Signal native cancellation without acknowledging physical settlement. */
|
|
185
|
+
cancelEffect: async (effect) => {
|
|
186
|
+
answer(await ops.op_tembra_native!("cancel-effect", codec.serialize(effect)));
|
|
187
|
+
},
|
|
188
|
+
/** Decode one native bridge value with the agreed codec. */
|
|
189
|
+
value: (id) => answer(ops.op_tembra_value!(id)),
|
|
190
|
+
/** Release the native value selected by a kernel action. */
|
|
191
|
+
dropValue: (id) => ops.op_tembra_drop_value!(id),
|
|
192
|
+
},
|
|
193
|
+
});
|
|
194
|
+
if (ops.op_tembra_callback_next) {
|
|
195
|
+
// Receiving is idle infrastructure; each callback is separately tracked physical work.
|
|
196
|
+
void (async () => {
|
|
197
|
+
for (;;) {
|
|
198
|
+
const receiving = ops.op_tembra_callback_next!();
|
|
199
|
+
Deno.core.unrefOpPromise(receiving);
|
|
200
|
+
const packet = (await receiving) as Uint8Array;
|
|
201
|
+
if (!packet.length) return;
|
|
202
|
+
const header = new DataView(packet.buffer, packet.byteOffset, 9);
|
|
203
|
+
const kind = header.getUint8(0);
|
|
204
|
+
const id = header.getUint32(1, true) + header.getUint32(5, true) * 2 ** 32;
|
|
205
|
+
if (kind !== 0) {
|
|
206
|
+
if (kind === 2) host.session.calls.releaseRoot(id);
|
|
207
|
+
if (kind === 3) host.session.handles.revoke(id);
|
|
208
|
+
host.session.lifecycle.flush();
|
|
209
|
+
continue;
|
|
210
|
+
}
|
|
211
|
+
let request: any;
|
|
212
|
+
try {
|
|
213
|
+
request = codec.deserialize(packet.subarray(9));
|
|
214
|
+
} catch (error) {
|
|
215
|
+
const { code, reason, message } = failure(error);
|
|
216
|
+
ops.op_tembra_callback_error!(id, JSON.stringify({ code, reason, message }), true);
|
|
217
|
+
continue;
|
|
218
|
+
}
|
|
219
|
+
host.session.track(
|
|
220
|
+
(async () => {
|
|
221
|
+
let envelope: unknown;
|
|
222
|
+
try {
|
|
223
|
+
let result: unknown;
|
|
224
|
+
if (request.kind === "activate") {
|
|
225
|
+
await host.session.handles.activateAcquired(
|
|
226
|
+
request.acquired,
|
|
227
|
+
request.address,
|
|
228
|
+
request.methods,
|
|
229
|
+
);
|
|
230
|
+
result = null;
|
|
231
|
+
} else {
|
|
232
|
+
const call = request.call;
|
|
233
|
+
const invocation = host.session.kernel.command<Invocation>(KernelOp.Invocation, {
|
|
234
|
+
call,
|
|
235
|
+
});
|
|
236
|
+
const ctx = new Context(host.session, invocation.root, invocation, request.frame);
|
|
237
|
+
if (request.kind === "invoke") {
|
|
238
|
+
const object = host.session.objects.get(invocation.object);
|
|
239
|
+
const environment = object?.versions.get(invocation.orb);
|
|
240
|
+
const handle =
|
|
241
|
+
environment?.orb.definition.services?.[object!.address.service]?.methods[
|
|
242
|
+
invocation.method
|
|
243
|
+
];
|
|
244
|
+
if (!handle || !environment) throw new TembraError(Errors.Gone.Implementation);
|
|
245
|
+
result = await handle(environment.value, ctx, ...request.input);
|
|
246
|
+
} else {
|
|
247
|
+
result = await host.session.orbs.runContribution(
|
|
248
|
+
request.operation,
|
|
249
|
+
ctx,
|
|
250
|
+
request.input,
|
|
251
|
+
);
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
envelope = result === undefined ? {} : { value: result };
|
|
255
|
+
} catch (error) {
|
|
256
|
+
const normalized = failure(error);
|
|
257
|
+
envelope = {
|
|
258
|
+
error: {
|
|
259
|
+
code: normalized.code,
|
|
260
|
+
reason: normalized.reason,
|
|
261
|
+
message: normalized.message,
|
|
262
|
+
},
|
|
263
|
+
};
|
|
264
|
+
}
|
|
265
|
+
try {
|
|
266
|
+
ops.op_tembra_callback_complete!(id, codec.serialize(envelope));
|
|
267
|
+
} catch (error) {
|
|
268
|
+
const { code, reason, message } = failure(error);
|
|
269
|
+
ops.op_tembra_callback_error!(id, JSON.stringify({ code, reason, message }), false);
|
|
270
|
+
}
|
|
271
|
+
})(),
|
|
272
|
+
true,
|
|
273
|
+
);
|
|
274
|
+
}
|
|
275
|
+
})();
|
|
276
|
+
}
|
|
277
|
+
return host;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
globals.Tembra = Object.freeze({
|
|
281
|
+
ContextKey,
|
|
282
|
+
ContextKind,
|
|
283
|
+
opaqueFrom,
|
|
284
|
+
createHost,
|
|
285
|
+
jsonCodec,
|
|
286
|
+
Code,
|
|
287
|
+
Reason,
|
|
288
|
+
Lifetime,
|
|
289
|
+
Status,
|
|
290
|
+
ReloadStatus,
|
|
291
|
+
HookCapability,
|
|
292
|
+
Errors,
|
|
293
|
+
});
|
package/src/error.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { Code } from "./bridge/identifiers.ts";
|
|
2
|
+
import { Errors, type ErrorDescriptor } from "./errors.ts";
|
|
3
|
+
|
|
4
|
+
const codes: ReadonlySet<unknown> = new Set(Object.values(Code));
|
|
5
|
+
|
|
6
|
+
/** Check for a structured error descriptor. */
|
|
7
|
+
function isDescriptor(value: unknown): value is ErrorDescriptor {
|
|
8
|
+
return (
|
|
9
|
+
typeof value === "object" &&
|
|
10
|
+
value !== null &&
|
|
11
|
+
"code" in value &&
|
|
12
|
+
codes.has(value.code) &&
|
|
13
|
+
"reason" in value &&
|
|
14
|
+
typeof value.reason === "string" &&
|
|
15
|
+
"message" in value &&
|
|
16
|
+
typeof value.message === "string"
|
|
17
|
+
);
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** A native JavaScript Error carrying the same structured failure fields as Rust. */
|
|
21
|
+
export class TembraError extends Error {
|
|
22
|
+
readonly code: Code;
|
|
23
|
+
readonly reason: string;
|
|
24
|
+
|
|
25
|
+
/** Preserve the error code and reason with a readable message. */
|
|
26
|
+
constructor(error: ErrorDescriptor, message = error.message, options?: ErrorOptions) {
|
|
27
|
+
super(message, options);
|
|
28
|
+
this.name = "TembraError";
|
|
29
|
+
this.code = error.code;
|
|
30
|
+
this.reason = error.reason;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Normalizes failures from other bundles or realms without relying on their constructors. */
|
|
35
|
+
export function failure(error: unknown): TembraError {
|
|
36
|
+
let message = Errors.Unavailable.Callback.message;
|
|
37
|
+
try {
|
|
38
|
+
if (error instanceof TembraError) return error;
|
|
39
|
+
if (isDescriptor(error)) return new TembraError(error, error.message, { cause: error });
|
|
40
|
+
message = String(error instanceof Error ? error.message : error);
|
|
41
|
+
} catch {
|
|
42
|
+
// Arbitrary thrown values must not interrupt error reporting or effect acknowledgement.
|
|
43
|
+
}
|
|
44
|
+
return new TembraError(Errors.Unavailable.Callback, message, { cause: error });
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Throw a structured error for a rejected operation. */
|
|
48
|
+
export function refuse(error: ErrorDescriptor, message = error.message): never {
|
|
49
|
+
throw new TembraError(error, message);
|
|
50
|
+
}
|
package/src/errors.ts
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
import { Code, Reason } from "./bridge/identifiers.ts";
|
|
2
|
+
|
|
3
|
+
/** Shared error shape, also used by Rust and transport envelopes. Orbs may supply custom reasons. */
|
|
4
|
+
export interface ErrorDescriptor {
|
|
5
|
+
readonly code: Code;
|
|
6
|
+
readonly reason: string;
|
|
7
|
+
readonly message: string;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/** Freeze a named group of structured error descriptors. */
|
|
11
|
+
function define(code: Code, reason: string, message: string): Readonly<ErrorDescriptor> {
|
|
12
|
+
return Object.freeze({ code, reason, message });
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** Built-in errors keep their identity and default message together. */
|
|
16
|
+
export const Errors = Object.freeze({
|
|
17
|
+
Cancelled: Object.freeze({
|
|
18
|
+
EngineEffect: define(Code.Cancelled, Reason.EngineEffect, "The engine effect was cancelled"),
|
|
19
|
+
Request: define(Code.Cancelled, Reason.Request, "The request was cancelled"),
|
|
20
|
+
Resource: define(Code.Cancelled, Reason.Resource, "Resource opening was cancelled"),
|
|
21
|
+
Root: define(Code.Cancelled, Reason.Root, "The operation was cancelled"),
|
|
22
|
+
Task: define(Code.Cancelled, Reason.Task, "The task was cancelled"),
|
|
23
|
+
}),
|
|
24
|
+
Closed: Object.freeze({
|
|
25
|
+
Host: define(Code.Closed, Reason.Host, "The host is closing"),
|
|
26
|
+
}),
|
|
27
|
+
Conflict: Object.freeze({
|
|
28
|
+
AlreadyCommitted: define(
|
|
29
|
+
Code.Conflict,
|
|
30
|
+
Reason.AlreadyCommitted,
|
|
31
|
+
"The replacement is already committed",
|
|
32
|
+
),
|
|
33
|
+
Codec: define(Code.Conflict, Reason.Codec, "The Rust and JS host codecs must agree"),
|
|
34
|
+
PrepareDeadline: define(
|
|
35
|
+
Code.Conflict,
|
|
36
|
+
Reason.PrepareDeadline,
|
|
37
|
+
"The preparation deadline expired",
|
|
38
|
+
),
|
|
39
|
+
ReloadRunning: define(Code.Conflict, Reason.ReloadRunning, "A replacement is already running"),
|
|
40
|
+
ReloadTicket: define(
|
|
41
|
+
Code.Conflict,
|
|
42
|
+
Reason.ReloadTicket,
|
|
43
|
+
"The replacement is no longer prepared",
|
|
44
|
+
),
|
|
45
|
+
}),
|
|
46
|
+
Exhausted: Object.freeze({
|
|
47
|
+
FrameSize: define(
|
|
48
|
+
Code.Exhausted,
|
|
49
|
+
Reason.FrameSize,
|
|
50
|
+
"The frame exceeds the configured size limit",
|
|
51
|
+
),
|
|
52
|
+
PendingRequests: define(
|
|
53
|
+
Code.Exhausted,
|
|
54
|
+
Reason.PendingRequests,
|
|
55
|
+
"The pending request limit was reached",
|
|
56
|
+
),
|
|
57
|
+
RemoteReferences: define(
|
|
58
|
+
Code.Exhausted,
|
|
59
|
+
Reason.RemoteReferences,
|
|
60
|
+
"The remote reference limit was reached",
|
|
61
|
+
),
|
|
62
|
+
RequestIds: define(Code.Exhausted, Reason.RequestIds, "Request identities are exhausted"),
|
|
63
|
+
SubscriptionQueue: define(
|
|
64
|
+
Code.Exhausted,
|
|
65
|
+
Reason.SubscriptionQueue,
|
|
66
|
+
"The subscription queue is full",
|
|
67
|
+
),
|
|
68
|
+
}),
|
|
69
|
+
Expired: Object.freeze({
|
|
70
|
+
Next: define(Code.Expired, Reason.Next, "Continuation scope has ended"),
|
|
71
|
+
}),
|
|
72
|
+
Forbidden: Object.freeze({
|
|
73
|
+
Context: define(Code.Forbidden, Reason.Context, "An issued context from this host is required"),
|
|
74
|
+
HostResource: define(Code.Forbidden, Reason.HostResource, "The host resource was not declared"),
|
|
75
|
+
Method: define(Code.Forbidden, Reason.Method, "The method is not allowed by this reference"),
|
|
76
|
+
ObservationSource: define(
|
|
77
|
+
Code.Forbidden,
|
|
78
|
+
Reason.ObservationSource,
|
|
79
|
+
"Hook observation requires the original physical invocation",
|
|
80
|
+
),
|
|
81
|
+
Opaque: define(
|
|
82
|
+
Code.Forbidden,
|
|
83
|
+
Reason.Opaque,
|
|
84
|
+
"The resource is not available as an opaque local value",
|
|
85
|
+
),
|
|
86
|
+
Service: define(Code.Forbidden, Reason.Service, "Access to this service is forbidden"),
|
|
87
|
+
StateOwner: define(
|
|
88
|
+
Code.Forbidden,
|
|
89
|
+
Reason.StateOwner,
|
|
90
|
+
"Only the owning orb may change this state",
|
|
91
|
+
),
|
|
92
|
+
UndeclaredDependency: define(
|
|
93
|
+
Code.Forbidden,
|
|
94
|
+
Reason.UndeclaredDependency,
|
|
95
|
+
"The dependency was not declared",
|
|
96
|
+
),
|
|
97
|
+
UndeclaredService: define(
|
|
98
|
+
Code.Forbidden,
|
|
99
|
+
Reason.UndeclaredService,
|
|
100
|
+
"The service was not declared as a dependency",
|
|
101
|
+
),
|
|
102
|
+
}),
|
|
103
|
+
Gone: Object.freeze({
|
|
104
|
+
Connection: define(Code.Gone, Reason.Connection, "The connection is closed"),
|
|
105
|
+
Contribution: define(Code.Gone, Reason.Contribution, "The contribution is no longer available"),
|
|
106
|
+
Implementation: define(
|
|
107
|
+
Code.Gone,
|
|
108
|
+
Reason.Implementation,
|
|
109
|
+
"The implementation is no longer available",
|
|
110
|
+
),
|
|
111
|
+
ListenerCallback: define(
|
|
112
|
+
Code.Gone,
|
|
113
|
+
Reason.ListenerCallback,
|
|
114
|
+
"The listener callback is no longer available",
|
|
115
|
+
),
|
|
116
|
+
Reference: define(Code.Gone, Reason.Reference, "The reference is no longer available"),
|
|
117
|
+
Resource: define(Code.Gone, Reason.Resource, "The resource is no longer available"),
|
|
118
|
+
Scope: define(Code.Gone, Reason.Scope, "The declaration scope is no longer available"),
|
|
119
|
+
State: define(Code.Gone, Reason.State, "State owner is gone"),
|
|
120
|
+
}),
|
|
121
|
+
Invalid: Object.freeze({
|
|
122
|
+
Address: define(Code.Invalid, Reason.Address, "Invalid address"),
|
|
123
|
+
AsyncFactory: define(Code.Invalid, Reason.AsyncFactory, "Factories must be synchronous"),
|
|
124
|
+
AsyncState: define(
|
|
125
|
+
Code.Invalid,
|
|
126
|
+
Reason.AsyncState,
|
|
127
|
+
"State updates and migrations must be synchronous",
|
|
128
|
+
),
|
|
129
|
+
CoordinationLimits: define(
|
|
130
|
+
Code.Invalid,
|
|
131
|
+
Reason.CoordinationLimits,
|
|
132
|
+
"Invalid coordination limits",
|
|
133
|
+
),
|
|
134
|
+
DependencyCycle: define(
|
|
135
|
+
Code.Invalid,
|
|
136
|
+
Reason.DependencyCycle,
|
|
137
|
+
"Orb factories cannot acquire their own services",
|
|
138
|
+
),
|
|
139
|
+
DependencyService: define(Code.Invalid, Reason.DependencyService, "Invalid dependency service"),
|
|
140
|
+
DuplicateListener: define(Code.Invalid, Reason.DuplicateListener, "Invalid duplicate listener"),
|
|
141
|
+
DuplicateResource: define(Code.Invalid, Reason.DuplicateResource, "Invalid duplicate resource"),
|
|
142
|
+
EventSource: define(Code.Invalid, Reason.EventSource, "Invalid event source"),
|
|
143
|
+
Orb: define(Code.Invalid, Reason.Orb, "An orb needs a name and positive API version"),
|
|
144
|
+
OrbGone: define(Code.Invalid, Reason.OrbGone, "Invalid orb gone"),
|
|
145
|
+
OrbInstalled: define(
|
|
146
|
+
Code.Invalid,
|
|
147
|
+
Reason.OrbInstalled,
|
|
148
|
+
"Use reload to replace an installed orb",
|
|
149
|
+
),
|
|
150
|
+
Factory: define(Code.Invalid, Reason.Factory, "Invalid factory"),
|
|
151
|
+
FactoryExpired: define(Code.Invalid, Reason.FactoryExpired, "Declarations must be synchronous"),
|
|
152
|
+
Hook: define(Code.Invalid, Reason.Hook, "Hooks need a run function"),
|
|
153
|
+
HookDependency: define(Code.Invalid, Reason.HookDependency, "Invalid hook dependency"),
|
|
154
|
+
HooksDisabled: define(Code.Invalid, Reason.HooksDisabled, "Invalid hooks disabled"),
|
|
155
|
+
JsonAccessor: define(Code.Invalid, Reason.JsonAccessor, "Invalid json accessor"),
|
|
156
|
+
JsonCycle: define(Code.Invalid, Reason.JsonCycle, "Invalid json cycle"),
|
|
157
|
+
JsonNumber: define(
|
|
158
|
+
Code.Invalid,
|
|
159
|
+
Reason.JsonNumber,
|
|
160
|
+
"Use BigInt for integers outside the safe Number range",
|
|
161
|
+
),
|
|
162
|
+
JsonSymbol: define(Code.Invalid, Reason.JsonSymbol, "Invalid json symbol"),
|
|
163
|
+
JsonTag: define(Code.Invalid, Reason.JsonTag, "Unknown or malformed portable type tag"),
|
|
164
|
+
JsonType: define(Code.Invalid, Reason.JsonType, "Supply a codec for custom object types"),
|
|
165
|
+
JsonValue: define(
|
|
166
|
+
Code.Invalid,
|
|
167
|
+
Reason.JsonValue,
|
|
168
|
+
"This JSON codec requires explicit portable values",
|
|
169
|
+
),
|
|
170
|
+
Method: define(Code.Invalid, Reason.Method, "Methods must be functions"),
|
|
171
|
+
NextUsed: define(Code.Invalid, Reason.NextUsed, "Invalid next used"),
|
|
172
|
+
Priority: define(Code.Invalid, Reason.Priority, "Invalid priority"),
|
|
173
|
+
Reference: define(Code.Invalid, Reason.Reference, "An issued local reference is required"),
|
|
174
|
+
Resource: define(Code.Invalid, Reason.Resource, "Invalid resource"),
|
|
175
|
+
ResourceHost: define(
|
|
176
|
+
Code.Invalid,
|
|
177
|
+
Reason.ResourceHost,
|
|
178
|
+
"Resource dependencies must belong to the same host",
|
|
179
|
+
),
|
|
180
|
+
ResourceInFactory: define(
|
|
181
|
+
Code.Invalid,
|
|
182
|
+
Reason.ResourceInFactory,
|
|
183
|
+
"Resources open after declaration",
|
|
184
|
+
),
|
|
185
|
+
RpcFrame: define(Code.Invalid, Reason.RpcFrame, "Invalid rpc frame"),
|
|
186
|
+
RpcOperation: define(Code.Invalid, Reason.RpcOperation, "Invalid rpc operation"),
|
|
187
|
+
RpcRequest: define(Code.Invalid, Reason.RpcRequest, "Invalid rpc request"),
|
|
188
|
+
Service: define(Code.Invalid, Reason.Service, "Invalid service"),
|
|
189
|
+
ServiceGone: define(Code.Invalid, Reason.ServiceGone, "Invalid service gone"),
|
|
190
|
+
State: define(Code.Invalid, Reason.State, "Service does not expose state"),
|
|
191
|
+
StateCycle: define(Code.Invalid, Reason.StateCycle, "State cannot contain cycles"),
|
|
192
|
+
StateValidation: define(
|
|
193
|
+
Code.Invalid,
|
|
194
|
+
Reason.StateValidation,
|
|
195
|
+
"The orb rejected the state candidate",
|
|
196
|
+
),
|
|
197
|
+
StateValue: define(Code.Invalid, Reason.StateValue, "State cannot contain accessors"),
|
|
198
|
+
StateVersion: define(Code.Invalid, Reason.StateVersion, "Invalid state version"),
|
|
199
|
+
SubscriptionsDisabled: define(
|
|
200
|
+
Code.Invalid,
|
|
201
|
+
Reason.SubscriptionsDisabled,
|
|
202
|
+
"Invalid subscriptions disabled",
|
|
203
|
+
),
|
|
204
|
+
SubscriptionSize: define(
|
|
205
|
+
Code.Invalid,
|
|
206
|
+
Reason.SubscriptionSize,
|
|
207
|
+
"A local byte budget requires an explicit sizeOf function",
|
|
208
|
+
),
|
|
209
|
+
Task: define(Code.Invalid, Reason.Task, "Invalid task"),
|
|
210
|
+
Utf8: define(Code.Invalid, Reason.Utf8, "Invalid utf8"),
|
|
211
|
+
ValueGone: define(Code.Invalid, Reason.ValueGone, "Invalid value gone"),
|
|
212
|
+
ValuesExhausted: define(Code.Invalid, Reason.ValuesExhausted, "Invalid values exhausted"),
|
|
213
|
+
}),
|
|
214
|
+
Released: Object.freeze({
|
|
215
|
+
Reference: define(Code.Released, Reason.Reference, "The reference has been released"),
|
|
216
|
+
}),
|
|
217
|
+
Unavailable: Object.freeze({
|
|
218
|
+
Callback: define(Code.Unavailable, Reason.Callback, "A callback failed"),
|
|
219
|
+
OrbScope: define(Code.Unavailable, Reason.OrbScope, "The orb scope is unavailable"),
|
|
220
|
+
NotReady: define(Code.Unavailable, Reason.NotReady, "The object is not ready"),
|
|
221
|
+
Route: define(Code.Unavailable, Reason.Route, "The route is unavailable"),
|
|
222
|
+
}),
|
|
223
|
+
Unsupported: Object.freeze({
|
|
224
|
+
EngineEffect: define(
|
|
225
|
+
Code.Unsupported,
|
|
226
|
+
Reason.EngineEffect,
|
|
227
|
+
"The engine effect is not supported by this adapter",
|
|
228
|
+
),
|
|
229
|
+
RemoteOpaque: define(
|
|
230
|
+
Code.Unsupported,
|
|
231
|
+
Reason.RemoteOpaque,
|
|
232
|
+
"Opaque resources are local to their language environment",
|
|
233
|
+
),
|
|
234
|
+
Telemetry: define(Code.Unsupported, Reason.Telemetry, "Telemetry is disabled in this kernel"),
|
|
235
|
+
Views: define(Code.Unsupported, Reason.Views, "Reference views are disabled in this kernel"),
|
|
236
|
+
}),
|
|
237
|
+
});
|
package/src/hooks.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./authoring/hooks.ts";
|