@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
|
@@ -0,0 +1,398 @@
|
|
|
1
|
+
import { consumerState } from "../authoring/declaration.ts";
|
|
2
|
+
import type {
|
|
3
|
+
AcquisitionOptions,
|
|
4
|
+
DynamicReference,
|
|
5
|
+
ServiceDefinition,
|
|
6
|
+
} from "../authoring/types.ts";
|
|
7
|
+
import { Code, Status } from "../bridge/identifiers.ts";
|
|
8
|
+
import type { Acquisition, KernelOrb } from "../bridge/kernel.ts";
|
|
9
|
+
import { KernelOp } from "../bridge/protocol.ts";
|
|
10
|
+
import { refuse, TembraError } from "../error.ts";
|
|
11
|
+
import { Errors } from "../errors.ts";
|
|
12
|
+
import { Context, context, isContext } from "./context.ts";
|
|
13
|
+
import type { Address, OrbRecord, ObjectRecord, ReferenceRecord } from "./records.ts";
|
|
14
|
+
import { deferred } from "./records.ts";
|
|
15
|
+
import type { Session } from "./session.ts";
|
|
16
|
+
|
|
17
|
+
const references = new WeakMap<object, { session: Session; record: ReferenceRecord }>();
|
|
18
|
+
const finalizer =
|
|
19
|
+
typeof FinalizationRegistry === "undefined"
|
|
20
|
+
? undefined
|
|
21
|
+
: new FinalizationRegistry<{ session: WeakRef<Session>; id: number }>((held) =>
|
|
22
|
+
held.session.deref()?.handles.release(held.id),
|
|
23
|
+
);
|
|
24
|
+
|
|
25
|
+
/** JS reference handles and per-object visibility. */
|
|
26
|
+
export class References {
|
|
27
|
+
/** Retain handle metadata and index references by object. */
|
|
28
|
+
constructor(readonly session: Session) {}
|
|
29
|
+
|
|
30
|
+
#metadata = new Map<number, KernelOrb>();
|
|
31
|
+
#byObject = new Map<number, Set<ReferenceRecord>>();
|
|
32
|
+
|
|
33
|
+
/** Activate an object reserved by the native facade in this shared kernel. */
|
|
34
|
+
activateAcquired(
|
|
35
|
+
acquired: Acquisition,
|
|
36
|
+
address: Address,
|
|
37
|
+
requiredMethods: string[] = [],
|
|
38
|
+
): Promise<void> {
|
|
39
|
+
const session = this.session;
|
|
40
|
+
let object = session.objects.get(acquired.object);
|
|
41
|
+
if (!object) {
|
|
42
|
+
const activation = deferred<void>();
|
|
43
|
+
object = {
|
|
44
|
+
id: acquired.object,
|
|
45
|
+
address,
|
|
46
|
+
orb: acquired.orb,
|
|
47
|
+
versions: new Map(),
|
|
48
|
+
activation: activation.promise,
|
|
49
|
+
};
|
|
50
|
+
session.objects.set(object.id, object);
|
|
51
|
+
const record = object;
|
|
52
|
+
session.track(
|
|
53
|
+
session.scopes.activate(record, acquired).then(activation.resolve, (error) => {
|
|
54
|
+
record.error = error;
|
|
55
|
+
try {
|
|
56
|
+
session.kernel.command(KernelOp.Fail, { object: record.id });
|
|
57
|
+
} catch {
|
|
58
|
+
// Concurrent shutdown can already have retired the reserved object.
|
|
59
|
+
}
|
|
60
|
+
activation.reject(error);
|
|
61
|
+
session.lifecycle.flush();
|
|
62
|
+
}),
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
// Every native claim needs its own policy and reload index, including reused objects.
|
|
66
|
+
if (!this.claimExists(acquired.reference)) return object.activation;
|
|
67
|
+
const provider = this.orbMetadata(object.orb);
|
|
68
|
+
const methods =
|
|
69
|
+
provider.services.find((service) => service.name === address.service)?.methods ?? [];
|
|
70
|
+
const record: ReferenceRecord = {
|
|
71
|
+
id: acquired.reference,
|
|
72
|
+
object: acquired.object,
|
|
73
|
+
address,
|
|
74
|
+
methods: new Set(methods),
|
|
75
|
+
requiredMethods: new Set(requiredMethods),
|
|
76
|
+
stateCleanups: new Set(),
|
|
77
|
+
ready: object.activation,
|
|
78
|
+
released: false,
|
|
79
|
+
nativeOwned: true,
|
|
80
|
+
};
|
|
81
|
+
const access = session.orbs.records.get(object.orb)?.definition.services?.[address.service]
|
|
82
|
+
?.access;
|
|
83
|
+
try {
|
|
84
|
+
this.referenceMethods(record, methods, access);
|
|
85
|
+
} catch (error) {
|
|
86
|
+
if (session.kernel.features.views && this.claimExists(record.id))
|
|
87
|
+
session.kernel.command(KernelOp.Restrict, { reference: record.id, methods: [] });
|
|
88
|
+
throw error;
|
|
89
|
+
}
|
|
90
|
+
session.references.set(record.id, record);
|
|
91
|
+
let owned = this.#byObject.get(record.object);
|
|
92
|
+
if (!owned) this.#byObject.set(record.object, (owned = new Set()));
|
|
93
|
+
owned.add(record);
|
|
94
|
+
return object.activation;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** Acquire ownership and create a local service handle. */
|
|
98
|
+
hold(
|
|
99
|
+
service: string,
|
|
100
|
+
key: string | readonly string[],
|
|
101
|
+
options: AcquisitionOptions = {},
|
|
102
|
+
ctx?: Context,
|
|
103
|
+
): DynamicReference {
|
|
104
|
+
const session = this.session;
|
|
105
|
+
if (ctx) context(ctx, session);
|
|
106
|
+
session.kernel.command(KernelOp.Tick, { now: session.now() });
|
|
107
|
+
const address: Address = {
|
|
108
|
+
service,
|
|
109
|
+
key: typeof key === "string" ? [key] : [...key],
|
|
110
|
+
principal: options.principal ?? ctx?.principal ?? session.principal,
|
|
111
|
+
};
|
|
112
|
+
const acquired = session.kernel.command<Acquisition>(KernelOp.Acquire, {
|
|
113
|
+
...address,
|
|
114
|
+
apiVersion: options.apiVersion ?? 0,
|
|
115
|
+
methods: options.methods ?? [],
|
|
116
|
+
});
|
|
117
|
+
let object = session.objects.get(acquired.object);
|
|
118
|
+
if (!object) {
|
|
119
|
+
const activation = deferred<void>();
|
|
120
|
+
object = {
|
|
121
|
+
id: acquired.object,
|
|
122
|
+
address,
|
|
123
|
+
orb: acquired.orb,
|
|
124
|
+
versions: new Map(),
|
|
125
|
+
activation: activation.promise,
|
|
126
|
+
};
|
|
127
|
+
session.objects.set(object.id, object);
|
|
128
|
+
const record = object;
|
|
129
|
+
queueMicrotask(() => {
|
|
130
|
+
session.track(
|
|
131
|
+
session.scopes.activate(record, acquired).then(activation.resolve, (error) => {
|
|
132
|
+
record.error = error;
|
|
133
|
+
try {
|
|
134
|
+
session.kernel.command(KernelOp.Fail, { object: record.id });
|
|
135
|
+
} catch {
|
|
136
|
+
/* A concurrent close may already retire activation. */
|
|
137
|
+
}
|
|
138
|
+
activation.reject(error);
|
|
139
|
+
session.lifecycle.flush();
|
|
140
|
+
}),
|
|
141
|
+
);
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
const provider = this.orbMetadata(acquired.orb);
|
|
145
|
+
const methods = new Set(provider.services.find((s) => s.name === service)?.methods ?? []);
|
|
146
|
+
const record: ReferenceRecord = {
|
|
147
|
+
id: acquired.reference,
|
|
148
|
+
object: acquired.object,
|
|
149
|
+
address,
|
|
150
|
+
methods,
|
|
151
|
+
requiredMethods: new Set(options.methods ?? []),
|
|
152
|
+
stateCleanups: new Set(),
|
|
153
|
+
ready: object.activation,
|
|
154
|
+
released: false,
|
|
155
|
+
...(ctx ? { context: ctx } : {}),
|
|
156
|
+
};
|
|
157
|
+
const nativeAccess = session.options.native?.access?.(acquired.orb, service, address.principal);
|
|
158
|
+
const access = nativeAccess
|
|
159
|
+
? () => ({ methods: nativeAccess })
|
|
160
|
+
: session.orbs.records.get(acquired.orb)?.definition.services?.[service]?.access;
|
|
161
|
+
try {
|
|
162
|
+
this.referenceMethods(record, methods, access);
|
|
163
|
+
} catch (error) {
|
|
164
|
+
session.kernel.command(KernelOp.Release, { reference: record.id });
|
|
165
|
+
session.kernel.command(KernelOp.Forget, { reference: record.id });
|
|
166
|
+
session.lifecycle.flush();
|
|
167
|
+
throw error;
|
|
168
|
+
}
|
|
169
|
+
session.references.set(record.id, record);
|
|
170
|
+
let owned = this.#byObject.get(record.object);
|
|
171
|
+
if (!owned) {
|
|
172
|
+
owned = new Set();
|
|
173
|
+
this.#byObject.set(record.object, owned);
|
|
174
|
+
}
|
|
175
|
+
owned.add(record);
|
|
176
|
+
if (ctx) {
|
|
177
|
+
let owned = session.rootReferences.get(ctx.root);
|
|
178
|
+
if (!owned) {
|
|
179
|
+
owned = new Set();
|
|
180
|
+
session.rootReferences.set(ctx.root, owned);
|
|
181
|
+
}
|
|
182
|
+
owned.add(record.id);
|
|
183
|
+
}
|
|
184
|
+
const check = () => {
|
|
185
|
+
if (record.released) throw new TembraError(Errors.Released.Reference);
|
|
186
|
+
if (session.closing) throw new TembraError(Errors.Gone.Reference);
|
|
187
|
+
const object = session.objects.get(record.object);
|
|
188
|
+
if (!object || object.disposing || object.error) throw new TembraError(Errors.Gone.Reference);
|
|
189
|
+
if (!object.live) throw new TembraError(Errors.Unavailable.NotReady);
|
|
190
|
+
};
|
|
191
|
+
const target = {
|
|
192
|
+
/** Wait for the acquired object's physical activation. */
|
|
193
|
+
get ready() {
|
|
194
|
+
return record.ready;
|
|
195
|
+
},
|
|
196
|
+
/** Read current kernel status unless this handle is already invalid. */
|
|
197
|
+
get status() {
|
|
198
|
+
return record.released
|
|
199
|
+
? Status.Released
|
|
200
|
+
: recordSession.closing
|
|
201
|
+
? Status.Gone
|
|
202
|
+
: recordSession.kernel.command(KernelOp.Status, { reference: record.id });
|
|
203
|
+
},
|
|
204
|
+
/** Expose a state view bound to this reference's lifetime. */
|
|
205
|
+
get state() {
|
|
206
|
+
check();
|
|
207
|
+
const binding = recordSession.objects.get(record.object)?.binding;
|
|
208
|
+
if (!binding) refuse(Errors.Invalid.State, "Service does not expose state");
|
|
209
|
+
return consumerState(binding, check, record.stateCleanups);
|
|
210
|
+
},
|
|
211
|
+
/** Release this handle's claim and detach its state observers. */
|
|
212
|
+
release: () => this.release(record.id),
|
|
213
|
+
/** Read only resources explicitly exposed by the local service. */
|
|
214
|
+
opaque: (name: string) => {
|
|
215
|
+
check();
|
|
216
|
+
const object = session.objects.get(record.object)!;
|
|
217
|
+
const resource = object.versions.get(object.orb)?.resources.get(name);
|
|
218
|
+
if (!resource?.options.opaque) throw new TembraError(Errors.Forbidden.Opaque, name);
|
|
219
|
+
return resource.handle.value;
|
|
220
|
+
},
|
|
221
|
+
};
|
|
222
|
+
const recordSession = session;
|
|
223
|
+
const proxy = new Proxy(target, {
|
|
224
|
+
/** Resolve service methods without exposing inherited object members. */
|
|
225
|
+
get: (target, property, receiver) => {
|
|
226
|
+
if (property === "then") return undefined;
|
|
227
|
+
if (Object.hasOwn(target, property)) return Reflect.get(target, property, receiver);
|
|
228
|
+
if (typeof property !== "string") return undefined;
|
|
229
|
+
if (!record.methods.has(property)) return undefined;
|
|
230
|
+
return (...arguments_: unknown[]) => {
|
|
231
|
+
let callContext = record.context;
|
|
232
|
+
if (isContext(arguments_.at(-1))) callContext = arguments_.pop() as Context;
|
|
233
|
+
return callContext
|
|
234
|
+
? session.calls.invoke(record, property, arguments_, context(callContext, session))
|
|
235
|
+
: session.calls.root(
|
|
236
|
+
(ctx) => session.calls.invoke(record, property, arguments_, ctx),
|
|
237
|
+
false,
|
|
238
|
+
undefined,
|
|
239
|
+
record.address.principal,
|
|
240
|
+
);
|
|
241
|
+
};
|
|
242
|
+
},
|
|
243
|
+
}) as DynamicReference;
|
|
244
|
+
references.set(proxy, { session: session, record });
|
|
245
|
+
finalizer?.register(proxy, { session: new WeakRef(session), id: record.id }, record);
|
|
246
|
+
return proxy;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** Release the acquired claim if activation fails. */
|
|
250
|
+
async get(
|
|
251
|
+
service: string,
|
|
252
|
+
key: string | readonly string[],
|
|
253
|
+
options: AcquisitionOptions = {},
|
|
254
|
+
ctx?: Context,
|
|
255
|
+
): Promise<DynamicReference> {
|
|
256
|
+
const reference = this.hold(service, key, options, ctx);
|
|
257
|
+
try {
|
|
258
|
+
await reference.ready;
|
|
259
|
+
return reference;
|
|
260
|
+
} catch (error) {
|
|
261
|
+
reference.release();
|
|
262
|
+
throw error;
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
/** Require a reference issued by this session. */
|
|
267
|
+
reference(value: unknown): ReferenceRecord {
|
|
268
|
+
const issued = typeof value === "object" && value !== null ? references.get(value) : undefined;
|
|
269
|
+
if (!issued || issued.session !== this.session)
|
|
270
|
+
refuse(Errors.Invalid.Reference, "An issued local reference is required");
|
|
271
|
+
return issued.record;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** Cache native orb metadata once per version. */
|
|
275
|
+
private orbMetadata(id: number): KernelOrb {
|
|
276
|
+
const definition = this.session.orbs.records.get(id)?.info;
|
|
277
|
+
if (definition) return definition;
|
|
278
|
+
let metadata = this.#metadata.get(id);
|
|
279
|
+
if (!metadata) {
|
|
280
|
+
metadata = this.session.kernel.command<KernelOrb>(KernelOp.Orb, { id });
|
|
281
|
+
this.#metadata.set(id, metadata);
|
|
282
|
+
}
|
|
283
|
+
return metadata;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/** Intersect declared requirements with current access permissions. */
|
|
287
|
+
private referenceMethods(
|
|
288
|
+
record: ReferenceRecord,
|
|
289
|
+
methods: Iterable<string>,
|
|
290
|
+
access?: ServiceDefinition["access"],
|
|
291
|
+
resetAccess = false,
|
|
292
|
+
): void {
|
|
293
|
+
const session = this.session;
|
|
294
|
+
if (access && !session.kernel.features.views) throw new TembraError(Errors.Unsupported.Views);
|
|
295
|
+
const allowed = access ? new Set(access(record.address.principal).methods) : undefined;
|
|
296
|
+
const visible = new Set(
|
|
297
|
+
[...methods].filter(
|
|
298
|
+
(method) =>
|
|
299
|
+
(!record.requiredMethods.size || record.requiredMethods.has(method)) &&
|
|
300
|
+
(!allowed || allowed.has(method)),
|
|
301
|
+
),
|
|
302
|
+
);
|
|
303
|
+
if (access || (resetAccess && session.kernel.features.views))
|
|
304
|
+
session.kernel.command(KernelOp.Restrict, {
|
|
305
|
+
reference: record.id,
|
|
306
|
+
methods: [...visible],
|
|
307
|
+
});
|
|
308
|
+
record.methods = visible;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/** Update only references indexed under the changed object. */
|
|
312
|
+
refreshReferences(object: ObjectRecord, orb: OrbRecord): void {
|
|
313
|
+
const session = this.session;
|
|
314
|
+
const service = orb.definition.services?.[object.address.service];
|
|
315
|
+
if (!service) return;
|
|
316
|
+
const methods = Object.keys(service.methods);
|
|
317
|
+
for (const reference of this.#byObject.get(object.id) ?? []) {
|
|
318
|
+
if (reference.released) continue;
|
|
319
|
+
if (reference.nativeOwned && !this.claimExists(reference.id)) {
|
|
320
|
+
this.revoke(reference.id);
|
|
321
|
+
continue;
|
|
322
|
+
}
|
|
323
|
+
try {
|
|
324
|
+
this.referenceMethods(reference, methods, service.access, true);
|
|
325
|
+
} catch (error) {
|
|
326
|
+
reference.methods.clear();
|
|
327
|
+
if (!reference.released && session.kernel.features.views)
|
|
328
|
+
session.kernel.command(KernelOp.Restrict, { reference: reference.id, methods: [] });
|
|
329
|
+
session.report(error);
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
/** Native claim release can precede its asynchronous metadata notification. */
|
|
335
|
+
private claimExists(reference: number): boolean {
|
|
336
|
+
try {
|
|
337
|
+
const status = this.session.kernel.command<Status>(KernelOp.Status, { reference });
|
|
338
|
+
return status !== Status.Released && status !== Status.Gone;
|
|
339
|
+
} catch (error) {
|
|
340
|
+
if (
|
|
341
|
+
error instanceof TembraError &&
|
|
342
|
+
(error.code === Code.Gone || error.code === Code.Released)
|
|
343
|
+
)
|
|
344
|
+
return false;
|
|
345
|
+
throw error;
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
/** Detach state observers and remove local reference indexes. */
|
|
350
|
+
private forget(record: ReferenceRecord): void {
|
|
351
|
+
for (const cleanup of record.stateCleanups) cleanup();
|
|
352
|
+
record.stateCleanups.clear();
|
|
353
|
+
this.session.references.delete(record.id);
|
|
354
|
+
const owned = this.#byObject.get(record.object);
|
|
355
|
+
owned?.delete(record);
|
|
356
|
+
if (!owned?.size) this.#byObject.delete(record.object);
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
/** Release the kernel claim and local observers once. */
|
|
360
|
+
release(id: number): void {
|
|
361
|
+
const session = this.session;
|
|
362
|
+
const record = session.references.get(id);
|
|
363
|
+
if (!record || record.released) return;
|
|
364
|
+
record.released = true;
|
|
365
|
+
finalizer?.unregister(record);
|
|
366
|
+
if (session.lifecycle.closedDiagnostics) {
|
|
367
|
+
this.forget(record);
|
|
368
|
+
return;
|
|
369
|
+
}
|
|
370
|
+
session.kernel.command(KernelOp.Tick, { now: session.now() });
|
|
371
|
+
session.kernel.command(KernelOp.Release, { reference: id });
|
|
372
|
+
session.kernel.command(KernelOp.Forget, { reference: id });
|
|
373
|
+
this.forget(record);
|
|
374
|
+
session.lifecycle.flush();
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/** Revokes a JS handle after the engine has released its claim. */
|
|
378
|
+
revoke(id: number): void {
|
|
379
|
+
const record = this.session.references.get(id);
|
|
380
|
+
if (!record) return;
|
|
381
|
+
record.released = true;
|
|
382
|
+
finalizer?.unregister(record);
|
|
383
|
+
this.forget(record);
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
/** Remove cached metadata for a retired orb version. */
|
|
387
|
+
retire(orb: number): void {
|
|
388
|
+
this.#metadata.delete(orb);
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
/** Detach all remaining observers during host shutdown. */
|
|
392
|
+
clear(): void {
|
|
393
|
+
for (const reference of this.session.references.values()) this.forget(reference);
|
|
394
|
+
this.session.references.clear();
|
|
395
|
+
this.#byObject.clear();
|
|
396
|
+
this.#metadata.clear();
|
|
397
|
+
}
|
|
398
|
+
}
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
OrbDefinition,
|
|
3
|
+
PreparedReload,
|
|
4
|
+
ReloadOptions,
|
|
5
|
+
ReloadReport,
|
|
6
|
+
} from "../authoring/types.ts";
|
|
7
|
+
import { Reason, ReloadStatus } from "../bridge/identifiers.ts";
|
|
8
|
+
import type { Reload } from "../bridge/kernel.ts";
|
|
9
|
+
import { KernelOp } from "../bridge/protocol.ts";
|
|
10
|
+
import { TembraError } from "../error.ts";
|
|
11
|
+
import { Errors } from "../errors.ts";
|
|
12
|
+
import type { OrbRecord } from "./records.ts";
|
|
13
|
+
import type { Session } from "./session.ts";
|
|
14
|
+
|
|
15
|
+
/** Captures JS factories and exposes the engine's transaction handle. No reload policy lives here. */
|
|
16
|
+
export class Replacements {
|
|
17
|
+
#pending: Promise<PreparedReload> | undefined;
|
|
18
|
+
#program: number | undefined;
|
|
19
|
+
#prepared: PreparedReload | undefined;
|
|
20
|
+
|
|
21
|
+
/** Track one replacement candidate for this session. */
|
|
22
|
+
constructor(readonly session: Session) {}
|
|
23
|
+
|
|
24
|
+
/** Prepare and commit a replacement in one operation. */
|
|
25
|
+
async replace(
|
|
26
|
+
definitions: readonly OrbDefinition[],
|
|
27
|
+
options: ReloadOptions = {},
|
|
28
|
+
remove: readonly string[] = [],
|
|
29
|
+
): Promise<ReloadReport> {
|
|
30
|
+
return (await this.prepare(definitions, options, remove)).commit();
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Reject overlapping replacement attempts before capturing callbacks. */
|
|
34
|
+
prepare(
|
|
35
|
+
definitions: readonly OrbDefinition[],
|
|
36
|
+
options: ReloadOptions = {},
|
|
37
|
+
remove: readonly string[] = [],
|
|
38
|
+
): Promise<PreparedReload> {
|
|
39
|
+
if (this.session.closing) return Promise.reject(new TembraError(Errors.Closed.Host));
|
|
40
|
+
if (this.#pending) return Promise.reject(new TembraError(Errors.Conflict.ReloadRunning));
|
|
41
|
+
const pending = this.capture(definitions, options, remove);
|
|
42
|
+
this.#pending = pending;
|
|
43
|
+
pending.catch(() => {
|
|
44
|
+
if (this.#pending === pending) this.#pending = undefined;
|
|
45
|
+
});
|
|
46
|
+
return pending;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Abort pending preparation and wait for physical recovery. */
|
|
50
|
+
async cancel(): Promise<void> {
|
|
51
|
+
if (this.#prepared?.status === ReloadStatus.Prepared) return this.#prepared.abort();
|
|
52
|
+
if (this.#program !== undefined) {
|
|
53
|
+
this.session.kernel.command(KernelOp.ProgramAbort, { program: this.#program });
|
|
54
|
+
const settled = this.session.programs.run(this.#program);
|
|
55
|
+
this.session.lifecycle.flush();
|
|
56
|
+
await settled.catch(() => {});
|
|
57
|
+
}
|
|
58
|
+
await this.#pending?.catch(() => undefined);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Bind candidate callbacks to the kernel's prepared replacement. */
|
|
62
|
+
private async capture(
|
|
63
|
+
definitions: readonly OrbDefinition[],
|
|
64
|
+
options: ReloadOptions,
|
|
65
|
+
remove: readonly string[],
|
|
66
|
+
): Promise<PreparedReload> {
|
|
67
|
+
const session = this.session;
|
|
68
|
+
const declarations = session.orbs.declarations(definitions);
|
|
69
|
+
const reload = session.kernel.command<Reload>(KernelOp.Prepare, {
|
|
70
|
+
orbs: declarations.metadata,
|
|
71
|
+
remove,
|
|
72
|
+
});
|
|
73
|
+
const definitionsByName = new Map(
|
|
74
|
+
declarations.definitions.map((definition) => [definition.name, definition]),
|
|
75
|
+
);
|
|
76
|
+
const records: OrbRecord[] = reload.orbs.map((info) => ({
|
|
77
|
+
info,
|
|
78
|
+
definition: definitionsByName.get(info.name)!,
|
|
79
|
+
ticket: reload.id,
|
|
80
|
+
}));
|
|
81
|
+
const recordsById = new Map(records.map((record) => [record.info.id, record]));
|
|
82
|
+
let program: number | undefined;
|
|
83
|
+
try {
|
|
84
|
+
for (const record of records) session.orbs.scope(record);
|
|
85
|
+
for (const id of reload.objects) {
|
|
86
|
+
const object = session.objects.get(id);
|
|
87
|
+
if (!object) continue;
|
|
88
|
+
const orb = reload.providers[object.address.service];
|
|
89
|
+
const record = orb === undefined ? undefined : recordsById.get(orb);
|
|
90
|
+
if (record) session.scopes.createEnvironment(object, record);
|
|
91
|
+
}
|
|
92
|
+
for (const record of records) record.ticket = undefined;
|
|
93
|
+
program = session.kernel.command<number>(KernelOp.ScopesReloadRegistered, {
|
|
94
|
+
ticket: reload.id,
|
|
95
|
+
deadline: options.deadline ?? 5000,
|
|
96
|
+
now: session.now(),
|
|
97
|
+
});
|
|
98
|
+
this.#program = program;
|
|
99
|
+
await session.programs.run(program);
|
|
100
|
+
// Preparation may have settled just before close; observe physical abort before returning.
|
|
101
|
+
if (session.closing) await session.programs.run(program);
|
|
102
|
+
} catch (error) {
|
|
103
|
+
this.#program = undefined;
|
|
104
|
+
if (program === undefined) {
|
|
105
|
+
session.kernel.command(KernelOp.Abort, { ticket: reload.id });
|
|
106
|
+
const scopes = reload.orbs.flatMap((orb) =>
|
|
107
|
+
session.kernel.command<number[]>(KernelOp.ScopesForOrb, { orb: orb.id }),
|
|
108
|
+
);
|
|
109
|
+
await session.programs.cleanupScopes(scopes);
|
|
110
|
+
}
|
|
111
|
+
throw error;
|
|
112
|
+
}
|
|
113
|
+
this.#program = undefined;
|
|
114
|
+
const id = program;
|
|
115
|
+
const report = {
|
|
116
|
+
codeVersion: reload.codeVersion,
|
|
117
|
+
orbs: records.map((record) => record.info.name),
|
|
118
|
+
};
|
|
119
|
+
let status: PreparedReload["status"] = ReloadStatus.Prepared;
|
|
120
|
+
return (this.#prepared = {
|
|
121
|
+
report,
|
|
122
|
+
/** Read whether this prepared candidate can still commit or abort. */
|
|
123
|
+
get status() {
|
|
124
|
+
return status;
|
|
125
|
+
},
|
|
126
|
+
/** Publish a prepared candidate once, then await its activation. */
|
|
127
|
+
commit: async () => {
|
|
128
|
+
if (status !== ReloadStatus.Prepared) throw new TembraError(Errors.Conflict.ReloadTicket);
|
|
129
|
+
this.#prepared = undefined;
|
|
130
|
+
try {
|
|
131
|
+
session.kernel.command(KernelOp.ProgramCommit, { program: id });
|
|
132
|
+
} catch (error) {
|
|
133
|
+
session.kernel.command(KernelOp.ProgramAbort, { program: id });
|
|
134
|
+
await session.programs.run(id).catch(() => {});
|
|
135
|
+
status = ReloadStatus.Aborted;
|
|
136
|
+
this.#pending = undefined;
|
|
137
|
+
throw error;
|
|
138
|
+
}
|
|
139
|
+
status = ReloadStatus.Committed;
|
|
140
|
+
this.#pending = undefined;
|
|
141
|
+
await session.programs.run(id);
|
|
142
|
+
return report;
|
|
143
|
+
},
|
|
144
|
+
/** Discard an uncommitted candidate and await physical recovery. */
|
|
145
|
+
abort: async () => {
|
|
146
|
+
if (status === ReloadStatus.Aborted) return;
|
|
147
|
+
if (status !== ReloadStatus.Prepared)
|
|
148
|
+
throw new TembraError(Errors.Conflict.AlreadyCommitted);
|
|
149
|
+
status = ReloadStatus.Aborted;
|
|
150
|
+
this.#prepared = undefined;
|
|
151
|
+
this.#pending = undefined;
|
|
152
|
+
session.kernel.command(KernelOp.ProgramAbort, { program: id });
|
|
153
|
+
try {
|
|
154
|
+
await session.programs.run(id);
|
|
155
|
+
} catch (error) {
|
|
156
|
+
if (!(error instanceof TembraError) || error.reason !== Reason.ReloadAborted) throw error;
|
|
157
|
+
}
|
|
158
|
+
},
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
}
|