@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,157 @@
|
|
|
1
|
+
import { EnvironmentPhase, KernelOp } from "../bridge/protocol.ts";
|
|
2
|
+
import { Errors } from "../errors.ts";
|
|
3
|
+
|
|
4
|
+
import type { Resource, ResourceOptions } from "../authoring/types.ts";
|
|
5
|
+
import { TembraError, refuse } from "../error.ts";
|
|
6
|
+
import type { Environment, ResourceRecord } from "./records.ts";
|
|
7
|
+
import type { Session } from "./session.ts";
|
|
8
|
+
|
|
9
|
+
const issued = new WeakMap<object, ResourceRecord & { session: Session }>();
|
|
10
|
+
|
|
11
|
+
export class Resources {
|
|
12
|
+
readonly records = new Map<number, ResourceRecord>();
|
|
13
|
+
readonly closedRecords = new Map<number, ResourceRecord>();
|
|
14
|
+
|
|
15
|
+
/** Retain callbacks for live and closed resource identities. */
|
|
16
|
+
constructor(readonly session: Session) {}
|
|
17
|
+
|
|
18
|
+
/** Resolve a live or recently closed callback record by its kernel identity. */
|
|
19
|
+
find(id: number): ResourceRecord | undefined {
|
|
20
|
+
return this.records.get(id) ?? this.closedRecords.get(id);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Validate local dependency ownership and collect resource identities. */
|
|
24
|
+
dependencyIds(options: ResourceOptions<any>): number[] {
|
|
25
|
+
const dependencies: number[] = [];
|
|
26
|
+
for (const dependency of options.deps ?? []) {
|
|
27
|
+
const resource =
|
|
28
|
+
typeof dependency === "object" && dependency !== null ? issued.get(dependency) : undefined;
|
|
29
|
+
if (resource) {
|
|
30
|
+
if (resource.session !== this.session)
|
|
31
|
+
refuse(Errors.Invalid.ResourceHost, "Resource dependencies must belong to the same host");
|
|
32
|
+
dependencies.push(resource.id);
|
|
33
|
+
} else {
|
|
34
|
+
this.session.handles.reference(dependency);
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
return dependencies;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Ask Rust to resolve this named resource declaration. */
|
|
41
|
+
private register(environment: Environment, name: string, options: ResourceOptions<any>): number {
|
|
42
|
+
return this.session.kernel.command<{ id: number; value: number | null }>(KernelOp.Resource, {
|
|
43
|
+
owner: environment.owner,
|
|
44
|
+
name,
|
|
45
|
+
version: options.version ?? 1,
|
|
46
|
+
exclusive: options.exclusive ?? false,
|
|
47
|
+
dependencies: this.dependencyIds(options),
|
|
48
|
+
}).id;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Rebind closed host resources to a fresh declared scope. */
|
|
52
|
+
redeclare(environment: Environment, previous: Environment): void {
|
|
53
|
+
for (const resource of previous.resources.values()) {
|
|
54
|
+
this.records.delete(resource.id);
|
|
55
|
+
this.closedRecords.delete(resource.id);
|
|
56
|
+
resource.reset(this.register(environment, resource.name, resource.options));
|
|
57
|
+
resource.dependencies = this.dependencyIds(resource.options);
|
|
58
|
+
this.records.set(resource.id, resource);
|
|
59
|
+
environment.resources.set(resource.name, resource);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Issue a local resource handle and retain its physical callbacks. */
|
|
64
|
+
declare<T>(environment: Environment, name: string, options: ResourceOptions<T>): ResourceRecord {
|
|
65
|
+
if (!name || typeof options.open !== "function") refuse(Errors.Invalid.Resource);
|
|
66
|
+
const id = this.register(environment, name, options);
|
|
67
|
+
const reused = this.records.get(id);
|
|
68
|
+
if (reused) {
|
|
69
|
+
// The engine's adoption effect publishes candidates; abort leaves live callbacks intact.
|
|
70
|
+
(environment.resourceDeclarations ??= new Map()).set(reused, options);
|
|
71
|
+
return reused;
|
|
72
|
+
}
|
|
73
|
+
const controller = new AbortController();
|
|
74
|
+
const handle: Resource<T> = Object.freeze({
|
|
75
|
+
/** Read the opened resource value after declaration has finished. */
|
|
76
|
+
get value() {
|
|
77
|
+
if (environment.phase === EnvironmentPhase.Declaring)
|
|
78
|
+
refuse(Errors.Invalid.ResourceInFactory, "Resources open after declaration");
|
|
79
|
+
const value = record.session.kernel.command<number>(KernelOp.ResourceValue, {
|
|
80
|
+
resource: record.id,
|
|
81
|
+
});
|
|
82
|
+
return record.session.value<T>(value);
|
|
83
|
+
},
|
|
84
|
+
version: options.version ?? 1,
|
|
85
|
+
});
|
|
86
|
+
const record = {
|
|
87
|
+
id,
|
|
88
|
+
name,
|
|
89
|
+
options,
|
|
90
|
+
handle,
|
|
91
|
+
dependencies: this.dependencyIds(options),
|
|
92
|
+
controller,
|
|
93
|
+
session: this.session,
|
|
94
|
+
/** Clear physical completion state before reopening a restored resource. */
|
|
95
|
+
reset: (id: number) => {
|
|
96
|
+
record.id = id;
|
|
97
|
+
record.controller = new AbortController();
|
|
98
|
+
delete record.value;
|
|
99
|
+
delete record.closed;
|
|
100
|
+
delete record.started;
|
|
101
|
+
},
|
|
102
|
+
/** Share one opener promise until its physical callback settles. */
|
|
103
|
+
start: () => {
|
|
104
|
+
record.started ??= (async () => {
|
|
105
|
+
const declaration = record.options;
|
|
106
|
+
const value = await declaration.open(record.controller.signal);
|
|
107
|
+
const id = this.session.values.put(value);
|
|
108
|
+
try {
|
|
109
|
+
this.session.kernel.command(KernelOp.ResourceOpened, {
|
|
110
|
+
resource: record.id,
|
|
111
|
+
value: id,
|
|
112
|
+
});
|
|
113
|
+
} catch (error) {
|
|
114
|
+
this.session.values.drop(id);
|
|
115
|
+
if (declaration.close)
|
|
116
|
+
await this.session.calls.root((ctx) => declaration.close!(value, ctx), true);
|
|
117
|
+
throw error;
|
|
118
|
+
}
|
|
119
|
+
record.value = id;
|
|
120
|
+
})();
|
|
121
|
+
record.started.catch(() => {});
|
|
122
|
+
return record.started;
|
|
123
|
+
},
|
|
124
|
+
} as ResourceRecord & { session: Session };
|
|
125
|
+
issued.set(handle, record);
|
|
126
|
+
this.records.set(id, record);
|
|
127
|
+
return record;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Wait for opening and closing callbacks before acknowledging release. */
|
|
131
|
+
async close(record: ResourceRecord): Promise<void> {
|
|
132
|
+
record.closed ??= (async () => {
|
|
133
|
+
record.controller.abort(new TembraError(Errors.Cancelled.Resource));
|
|
134
|
+
await record.started?.catch(() => {});
|
|
135
|
+
try {
|
|
136
|
+
if (record.value !== undefined && record.options.close) {
|
|
137
|
+
const value = this.session.value(record.value);
|
|
138
|
+
await this.session.calls.root((ctx) => record.options.close!(value, ctx), true);
|
|
139
|
+
}
|
|
140
|
+
} finally {
|
|
141
|
+
this.session.kernel.command(KernelOp.ResourceClosed, { resource: record.id });
|
|
142
|
+
this.records.delete(record.id);
|
|
143
|
+
this.closedRecords.set(record.id, record);
|
|
144
|
+
this.session.lifecycle.flush();
|
|
145
|
+
}
|
|
146
|
+
})();
|
|
147
|
+
return record.closed;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** Rebind a restored resource and wait for its new value. */
|
|
151
|
+
async reopen(record: ResourceRecord, id: number): Promise<void> {
|
|
152
|
+
this.closedRecords.delete(record.id);
|
|
153
|
+
record.reset(id);
|
|
154
|
+
this.records.set(id, record);
|
|
155
|
+
await record.start();
|
|
156
|
+
}
|
|
157
|
+
}
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
import { Declaration } from "../authoring/declaration.ts";
|
|
2
|
+
import type { Resource, ResourceOptions } from "../authoring/types.ts";
|
|
3
|
+
import { Code, Reason, Status } from "../bridge/identifiers.ts";
|
|
4
|
+
import type { Acquisition, KernelOrb, Owner } from "../bridge/kernel.ts";
|
|
5
|
+
import { EnvironmentPhase, KernelOp, OwnerKind } from "../bridge/protocol.ts";
|
|
6
|
+
import { refuse, TembraError } from "../error.ts";
|
|
7
|
+
import { Errors } from "../errors.ts";
|
|
8
|
+
import { StateBinding } from "../state.ts";
|
|
9
|
+
import type { Environment, OrbRecord, ObjectRecord, ResourceRecord } from "./records.ts";
|
|
10
|
+
import type { Session } from "./session.ts";
|
|
11
|
+
|
|
12
|
+
/** Declare JS scopes and execute activation effects. */
|
|
13
|
+
export class Scopes {
|
|
14
|
+
/** Track host resource names and pending host activations. */
|
|
15
|
+
constructor(readonly session: Session) {}
|
|
16
|
+
|
|
17
|
+
#hostResources = new Map<string, ResourceRecord>();
|
|
18
|
+
#pendingHostScopes = new Set<Environment>();
|
|
19
|
+
#hostActivation: Promise<void> | undefined;
|
|
20
|
+
|
|
21
|
+
/** Allocate the JS callback storage for one declared scope. */
|
|
22
|
+
environment(owner: Owner, orb: OrbRecord, object?: ObjectRecord): Environment {
|
|
23
|
+
const environment: Environment = {
|
|
24
|
+
id: this.session.kernel.command<number>(KernelOp.Allocate),
|
|
25
|
+
owner,
|
|
26
|
+
orb,
|
|
27
|
+
...(object ? { object } : {}),
|
|
28
|
+
phase: EnvironmentPhase.Declaring,
|
|
29
|
+
value: {},
|
|
30
|
+
dependencies: new Map(),
|
|
31
|
+
resources: new Map(),
|
|
32
|
+
tasks: [],
|
|
33
|
+
listeners: [],
|
|
34
|
+
};
|
|
35
|
+
this.session.programs.scopes.set(environment.id, environment);
|
|
36
|
+
return environment;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Declare native or JS object scopes and wait for readiness. */
|
|
40
|
+
async activate(object: ObjectRecord, acquired: Acquisition): Promise<void> {
|
|
41
|
+
const session = this.session;
|
|
42
|
+
if (session.options.native?.hasOrb(acquired.orb)) {
|
|
43
|
+
await session.options.native.activate(
|
|
44
|
+
object.id,
|
|
45
|
+
acquired.orb,
|
|
46
|
+
object.address.service,
|
|
47
|
+
object.address.key,
|
|
48
|
+
object.address.principal,
|
|
49
|
+
);
|
|
50
|
+
const scopes = session.kernel.command<number[]>(KernelOp.ScopesForOwner, {
|
|
51
|
+
owner: { kind: OwnerKind.Object, id: object.id },
|
|
52
|
+
});
|
|
53
|
+
await Promise.all(scopes.map((scope) => session.programs.activate(scope)));
|
|
54
|
+
try {
|
|
55
|
+
session.snapshot(object.id);
|
|
56
|
+
object.binding = new StateBinding(session, object.id);
|
|
57
|
+
} catch {
|
|
58
|
+
/* State is optional. */
|
|
59
|
+
}
|
|
60
|
+
} else {
|
|
61
|
+
const orb = session.orbs.records.get(acquired.orb);
|
|
62
|
+
if (!orb) refuse(Errors.Invalid.OrbGone);
|
|
63
|
+
await session.orbs.ready(orb);
|
|
64
|
+
const environment = this.createEnvironment(object, orb);
|
|
65
|
+
object.versions.set(orb.info.id, environment);
|
|
66
|
+
await this.session.programs.activate(environment.id);
|
|
67
|
+
}
|
|
68
|
+
if (
|
|
69
|
+
session.kernel.command<Status>(KernelOp.Status, { reference: acquired.reference }) ===
|
|
70
|
+
Status.Loading
|
|
71
|
+
)
|
|
72
|
+
session.kernel.command(KernelOp.Ready, { object: object.id });
|
|
73
|
+
object.live = true;
|
|
74
|
+
session.lifecycle.flush();
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Run a service factory synchronously and register its scope. */
|
|
78
|
+
createEnvironment(object: ObjectRecord, orb: OrbRecord): Environment {
|
|
79
|
+
const definition = orb.definition.services?.[object.address.service];
|
|
80
|
+
if (!definition) refuse(Errors.Invalid.ServiceGone);
|
|
81
|
+
const environment = this.environment({ kind: OwnerKind.Object, id: object.id }, orb, object);
|
|
82
|
+
try {
|
|
83
|
+
const value = definition.create?.(new Declaration(this.session, environment)) ?? {};
|
|
84
|
+
if (value && typeof (value as { then?: unknown }).then === "function")
|
|
85
|
+
refuse(Errors.Invalid.AsyncFactory, "Factories must be synchronous");
|
|
86
|
+
environment.value = value;
|
|
87
|
+
return environment;
|
|
88
|
+
} finally {
|
|
89
|
+
environment.phase = EnvironmentPhase.Prepared;
|
|
90
|
+
this.session.programs.register(environment);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Share host activation and reopen retired resource scopes. */
|
|
95
|
+
readyHostScope(): Promise<void> {
|
|
96
|
+
const session = this.session;
|
|
97
|
+
if (session.closing) return Promise.reject(new TembraError(Errors.Closed.Host));
|
|
98
|
+
if (this.#hostActivation) return this.#hostActivation;
|
|
99
|
+
const activation = (async () => {
|
|
100
|
+
if (session.hostScope.phase === EnvironmentPhase.Closed)
|
|
101
|
+
session.hostScope = await this.redeclareHostScope(session.hostScope);
|
|
102
|
+
await this.session.programs.activate(session.hostScope.id);
|
|
103
|
+
while (this.#pendingHostScopes.size) {
|
|
104
|
+
let environment = this.#pendingHostScopes.values().next().value!;
|
|
105
|
+
if (
|
|
106
|
+
environment.phase === EnvironmentPhase.Closed ||
|
|
107
|
+
[...environment.resources.values()].some((resource) =>
|
|
108
|
+
session.resources
|
|
109
|
+
.dependencyIds(resource.options)
|
|
110
|
+
.some((id, index) => id !== resource.dependencies[index]),
|
|
111
|
+
)
|
|
112
|
+
) {
|
|
113
|
+
const previous = environment;
|
|
114
|
+
environment = await this.redeclareHostScope(previous);
|
|
115
|
+
this.#pendingHostScopes.delete(previous);
|
|
116
|
+
this.#pendingHostScopes.add(environment);
|
|
117
|
+
}
|
|
118
|
+
await this.session.programs.activate(environment.id);
|
|
119
|
+
this.#pendingHostScopes.delete(environment);
|
|
120
|
+
}
|
|
121
|
+
})();
|
|
122
|
+
this.#hostActivation = activation;
|
|
123
|
+
const clear = () => {
|
|
124
|
+
if (this.#hostActivation === activation) this.#hostActivation = undefined;
|
|
125
|
+
};
|
|
126
|
+
activation.then(clear, clear);
|
|
127
|
+
return activation;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Clean up the previous scope before rebinding its resources. */
|
|
131
|
+
private async redeclareHostScope(previous: Environment): Promise<Environment> {
|
|
132
|
+
const session = this.session;
|
|
133
|
+
await session.programs.cleanup([previous]);
|
|
134
|
+
const environment = this.environment({ kind: OwnerKind.Host }, previous.orb);
|
|
135
|
+
session.resources.redeclare(environment, previous);
|
|
136
|
+
environment.phase = EnvironmentPhase.Prepared;
|
|
137
|
+
session.programs.register(environment);
|
|
138
|
+
return environment;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** Resolve a declared dependency and its allowed methods. */
|
|
142
|
+
requirement(
|
|
143
|
+
environment: Environment,
|
|
144
|
+
service: string,
|
|
145
|
+
): { service: string; apiVersion?: number; methods?: readonly string[] } {
|
|
146
|
+
const own = environment.orb.definition.services?.[service];
|
|
147
|
+
if (own) return { service, apiVersion: environment.orb.info.apiVersion };
|
|
148
|
+
for (const [alias, requirement] of Object.entries(environment.orb.definition.requires ?? {})) {
|
|
149
|
+
let provider: KernelOrb;
|
|
150
|
+
try {
|
|
151
|
+
provider = this.session.kernel.command<KernelOrb>(KernelOp.OrbNamed, {
|
|
152
|
+
name: requirement.orb ?? alias,
|
|
153
|
+
ticket: environment.orb.ticket,
|
|
154
|
+
});
|
|
155
|
+
} catch (error) {
|
|
156
|
+
if (error instanceof TembraError && error.code === Code.Gone && error.reason === Reason.Orb)
|
|
157
|
+
continue;
|
|
158
|
+
throw error;
|
|
159
|
+
}
|
|
160
|
+
const selected =
|
|
161
|
+
alias === service
|
|
162
|
+
? (provider.services.find((s) => s.name === alias) ??
|
|
163
|
+
(provider.services.length === 1 ? provider.services[0] : undefined))
|
|
164
|
+
: provider.services.find((s) => s.name === service);
|
|
165
|
+
if (!selected) continue;
|
|
166
|
+
const methods = requirement.services?.[selected.name] ?? requirement.methods;
|
|
167
|
+
if (!methods) throw new TembraError(Errors.Forbidden.UndeclaredService, service);
|
|
168
|
+
return { service: selected.name, apiVersion: requirement.apiVersion, methods };
|
|
169
|
+
}
|
|
170
|
+
throw new TembraError(Errors.Forbidden.UndeclaredDependency, service);
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** Require a named resource declared by this host. */
|
|
174
|
+
hostResource<T>(name: string): Resource<T> {
|
|
175
|
+
const resource = this.#hostResources.get(name);
|
|
176
|
+
if (!resource) throw new TembraError(Errors.Forbidden.HostResource, name);
|
|
177
|
+
return resource.handle;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** Add a host-owned resource and schedule its activation. */
|
|
181
|
+
resource<T>(name: string, options: ResourceOptions<T>): Resource<T> {
|
|
182
|
+
const session = this.session;
|
|
183
|
+
if (session.closing) throw new TembraError(Errors.Closed.Host);
|
|
184
|
+
if (this.#hostResources.has(name)) refuse(Errors.Invalid.DuplicateResource);
|
|
185
|
+
const environment = this.environment({ kind: OwnerKind.Host }, session.hostScope.orb);
|
|
186
|
+
try {
|
|
187
|
+
const resource = new Declaration(session, environment).resource(name, options);
|
|
188
|
+
this.#hostResources.set(name, environment.resources.get(name)!);
|
|
189
|
+
environment.phase = EnvironmentPhase.Prepared;
|
|
190
|
+
session.programs.register(environment);
|
|
191
|
+
this.#pendingHostScopes.add(environment);
|
|
192
|
+
session.track(this.readyHostScope()).catch((error) => session.report(error));
|
|
193
|
+
return resource;
|
|
194
|
+
} catch (error) {
|
|
195
|
+
session.programs.scopes.delete(environment.id);
|
|
196
|
+
throw error;
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** Index resources declared by the initial host scope. */
|
|
201
|
+
registerHost(environment: Environment): void {
|
|
202
|
+
for (const [name, resource] of environment.resources) this.#hostResources.set(name, resource);
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/** Drop host resource indexes during shutdown. */
|
|
206
|
+
clear(): void {
|
|
207
|
+
this.#hostResources.clear();
|
|
208
|
+
this.#pendingHostScopes.clear();
|
|
209
|
+
}
|
|
210
|
+
}
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import { Declaration } from "../authoring/declaration.ts";
|
|
2
|
+
import type { HostOptions } from "../authoring/types.ts";
|
|
3
|
+
import type { Invocation, Snapshot } from "../bridge/kernel.ts";
|
|
4
|
+
import { Kernel } from "../bridge/kernel.ts";
|
|
5
|
+
import { EnvironmentPhase, KernelOp, OwnerKind } from "../bridge/protocol.ts";
|
|
6
|
+
import { jsonCodec } from "../codecs/json.ts";
|
|
7
|
+
import { failure, refuse, TembraError } from "../error.ts";
|
|
8
|
+
import { Errors } from "../errors.ts";
|
|
9
|
+
import type { StateBackend } from "../state.ts";
|
|
10
|
+
import { Telemetry } from "../telemetry.ts";
|
|
11
|
+
import { Values } from "../values.ts";
|
|
12
|
+
import { Activities } from "./activities.ts";
|
|
13
|
+
import { Calls } from "./calls.ts";
|
|
14
|
+
import { context } from "./context.ts";
|
|
15
|
+
import { Orbs } from "./orbs.ts";
|
|
16
|
+
import { Lifecycle } from "./lifecycle.ts";
|
|
17
|
+
import { Programs } from "./programs.ts";
|
|
18
|
+
import type { Environment, OrbRecord, ObjectRecord, ReferenceRecord } from "./records.ts";
|
|
19
|
+
import { References } from "./references.ts";
|
|
20
|
+
import { Replacements } from "./reload.ts";
|
|
21
|
+
import { Resources } from "./resources.ts";
|
|
22
|
+
import { Scopes } from "./scopes.ts";
|
|
23
|
+
|
|
24
|
+
/** Shared JS values and callbacks. Rust owns lifecycle policy. */
|
|
25
|
+
export class Session implements StateBackend {
|
|
26
|
+
readonly contextTokens = new WeakMap<object, { root: number; source: number }>();
|
|
27
|
+
readonly calls = new Calls(this);
|
|
28
|
+
readonly handles = new References(this);
|
|
29
|
+
readonly scopes = new Scopes(this);
|
|
30
|
+
readonly lifecycle = new Lifecycle(this);
|
|
31
|
+
readonly kernel: Kernel;
|
|
32
|
+
readonly values: Values;
|
|
33
|
+
readonly resources = new Resources(this);
|
|
34
|
+
readonly activities = new Activities(this);
|
|
35
|
+
readonly orbs = new Orbs(this);
|
|
36
|
+
readonly replacements = new Replacements(this);
|
|
37
|
+
readonly programs = new Programs(this);
|
|
38
|
+
readonly objects = new Map<number, ObjectRecord>();
|
|
39
|
+
readonly references = new Map<number, ReferenceRecord>();
|
|
40
|
+
readonly rootReferences = new Map<number, Set<number>>();
|
|
41
|
+
readonly controllers = new Map<number, AbortController>();
|
|
42
|
+
readonly jobs = new Set<Promise<unknown>>();
|
|
43
|
+
readonly cleanupErrors: unknown[] = [];
|
|
44
|
+
hostScope: Environment;
|
|
45
|
+
readonly codec;
|
|
46
|
+
readonly name: string;
|
|
47
|
+
readonly principal: string;
|
|
48
|
+
readonly errors: TembraError[] = [];
|
|
49
|
+
readonly now: () => number;
|
|
50
|
+
readonly telemetry: Telemetry | undefined;
|
|
51
|
+
closing = false;
|
|
52
|
+
|
|
53
|
+
#publishing = false;
|
|
54
|
+
|
|
55
|
+
#publications: (() => void)[] = [];
|
|
56
|
+
|
|
57
|
+
/** Create callback storage around one Rust lifecycle kernel. */
|
|
58
|
+
constructor(readonly options: HostOptions) {
|
|
59
|
+
this.kernel = new Kernel(options.kernel);
|
|
60
|
+
if (options.telemetry && !this.kernel.features.telemetry)
|
|
61
|
+
throw new TembraError(Errors.Unsupported.Telemetry);
|
|
62
|
+
this.telemetry = options.telemetry
|
|
63
|
+
? new Telemetry(options.telemetry.capacity, options.telemetry.sampleEvery)
|
|
64
|
+
: undefined;
|
|
65
|
+
this.values = new Values(() => this.kernel.command<number>(KernelOp.Allocate));
|
|
66
|
+
this.codec = options.serialization ?? jsonCodec;
|
|
67
|
+
this.name = options.name ?? "host";
|
|
68
|
+
this.principal = options.principal ?? "host";
|
|
69
|
+
const clock = options.now ?? (() => performance.now());
|
|
70
|
+
const origin = options.clockOrigin ?? clock();
|
|
71
|
+
this.now = () => Math.floor(clock() - origin);
|
|
72
|
+
const hostOrb: OrbRecord = {
|
|
73
|
+
info: {
|
|
74
|
+
id: 0,
|
|
75
|
+
owner: 0,
|
|
76
|
+
name: "$host",
|
|
77
|
+
apiVersion: 1,
|
|
78
|
+
codeVersion: 1,
|
|
79
|
+
services: [],
|
|
80
|
+
hooks: [],
|
|
81
|
+
requires: [],
|
|
82
|
+
},
|
|
83
|
+
definition: { name: "$host", apiVersion: 1 },
|
|
84
|
+
};
|
|
85
|
+
this.hostScope = this.scopes.environment({ kind: OwnerKind.Host }, hostOrb);
|
|
86
|
+
for (const [name, declaration] of Object.entries(options.resources ?? {})) {
|
|
87
|
+
new Declaration(this, this.hostScope).resource(name, declaration);
|
|
88
|
+
}
|
|
89
|
+
this.scopes.registerHost(this.hostScope);
|
|
90
|
+
this.hostScope.phase = EnvironmentPhase.Prepared;
|
|
91
|
+
this.programs.register(this.hostScope);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Read the object owner, or use the host identity. */
|
|
95
|
+
principalFor(object: number): string {
|
|
96
|
+
return this.objects.get(object)?.address.principal ?? this.principal;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Read the current value identity and state revision. */
|
|
100
|
+
snapshot(object: number): Snapshot {
|
|
101
|
+
return this.kernel.command(KernelOp.Snapshot, { object });
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Resolve a local value or cache its native decoded value. */
|
|
105
|
+
value<T>(id: number): T {
|
|
106
|
+
if (this.values.has(id)) return this.values.get<T>(id);
|
|
107
|
+
if (!this.options.native) refuse(Errors.Invalid.ValueGone);
|
|
108
|
+
const value = this.options.native.value(id) as T;
|
|
109
|
+
this.values.set(id, value);
|
|
110
|
+
return value;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** Require an admitted call for the target state owner. */
|
|
114
|
+
check(value: unknown, object: number): Invocation {
|
|
115
|
+
const ctx = context(value, this);
|
|
116
|
+
if (!ctx.invocation || ctx.invocation.object !== object)
|
|
117
|
+
throw new TembraError(Errors.Forbidden.StateOwner);
|
|
118
|
+
return ctx.invocation;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Publish candidate state only if its expected revision still matches. */
|
|
122
|
+
adopt(object: number, value: unknown, revision: string, candidate: unknown): Snapshot {
|
|
123
|
+
const invocation = this.check(value, object);
|
|
124
|
+
const id = this.values.put(candidate);
|
|
125
|
+
try {
|
|
126
|
+
return this.kernel.command(KernelOp.StateAdopt, {
|
|
127
|
+
call: invocation.id,
|
|
128
|
+
object,
|
|
129
|
+
revision,
|
|
130
|
+
value: id,
|
|
131
|
+
});
|
|
132
|
+
} catch (error) {
|
|
133
|
+
this.values.drop(id);
|
|
134
|
+
throw error;
|
|
135
|
+
} finally {
|
|
136
|
+
this.lifecycle.flush();
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Serialize notifications so reentrant updates preserve publication order. */
|
|
141
|
+
publish(operation: () => void): void {
|
|
142
|
+
this.#publications.push(operation);
|
|
143
|
+
if (this.#publishing) return;
|
|
144
|
+
this.#publishing = true;
|
|
145
|
+
try {
|
|
146
|
+
while (this.#publications.length) this.#publications.shift()!();
|
|
147
|
+
} finally {
|
|
148
|
+
this.#publishing = false;
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** Retain a bounded error history without disrupting state adoption. */
|
|
153
|
+
report(error: unknown): void {
|
|
154
|
+
const reported = failure(error);
|
|
155
|
+
if (this.errors.length === 64) this.errors.shift();
|
|
156
|
+
this.errors.push(reported);
|
|
157
|
+
try {
|
|
158
|
+
this.options.onError?.(reported);
|
|
159
|
+
} catch {
|
|
160
|
+
/* Error reporting cannot invalidate an adopted state. */
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Retain physical work until settlement, including cancelled callers. */
|
|
165
|
+
track<T>(job: Promise<T>, cleanup = false): Promise<T> {
|
|
166
|
+
this.jobs.add(job);
|
|
167
|
+
job.then(
|
|
168
|
+
() => {
|
|
169
|
+
this.jobs.delete(job);
|
|
170
|
+
},
|
|
171
|
+
(error) => {
|
|
172
|
+
this.jobs.delete(job);
|
|
173
|
+
if (cleanup) {
|
|
174
|
+
this.cleanupErrors.push(error);
|
|
175
|
+
this.report(error);
|
|
176
|
+
}
|
|
177
|
+
},
|
|
178
|
+
);
|
|
179
|
+
return job;
|
|
180
|
+
}
|
|
181
|
+
}
|