@syntropika/tembra-sdk 0.0.0-stage → 0.2.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 +48 -0
- package/dist/authoring/hooks.d.ts +11 -0
- package/dist/authoring/orb.d.ts +3 -0
- package/dist/authoring/service-identities.d.ts +7 -0
- package/dist/authoring/services.d.ts +8 -0
- package/dist/authoring/types.d.ts +181 -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 +3335 -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 +98 -0
- package/dist/host.js +3278 -0
- package/dist/identifiers.d.ts +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +864 -0
- package/dist/infrastructure/coordinator.d.ts +13 -0
- package/dist/infrastructure/manager.d.ts +23 -0
- package/dist/infrastructure/rpc/channel.d.ts +55 -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 +3336 -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 +1091 -0
- package/dist/runtime/activities.d.ts +30 -0
- package/dist/runtime/calls.d.ts +22 -0
- package/dist/runtime/context.d.ts +38 -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 +237 -0
- package/src/authoring/hooks.ts +101 -0
- package/src/authoring/orb.ts +88 -0
- package/src/authoring/service-identities.ts +20 -0
- package/src/authoring/services.ts +46 -0
- package/src/authoring/types.ts +256 -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 +173 -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 +107 -0
- package/src/infrastructure/rpc/client.ts +216 -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 +128 -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 +406 -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/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";
|
package/src/host.ts
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
import { orb } from "./authoring/orb.ts";
|
|
2
|
+
import type {
|
|
3
|
+
AcquisitionOptions,
|
|
4
|
+
Completion,
|
|
5
|
+
OrbDefinition,
|
|
6
|
+
HostOptions,
|
|
7
|
+
ReloadOptions,
|
|
8
|
+
ResourceOptions,
|
|
9
|
+
DynamicReference,
|
|
10
|
+
ServiceDefinition,
|
|
11
|
+
ServiceReference,
|
|
12
|
+
} from "./authoring/types.ts";
|
|
13
|
+
import { KernelOp } from "./bridge/protocol.ts";
|
|
14
|
+
import { Context } from "./runtime/context.ts";
|
|
15
|
+
import { Session } from "./runtime/session.ts";
|
|
16
|
+
|
|
17
|
+
/** The application facade. Platform entrypoints provide its metadata kernel and module loader. */
|
|
18
|
+
export class Host {
|
|
19
|
+
readonly session: Session;
|
|
20
|
+
|
|
21
|
+
/** Create the shared session for this host. */
|
|
22
|
+
constructor(options: HostOptions) {
|
|
23
|
+
this.session = new Session(options);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Read the configured host name. */
|
|
27
|
+
get name() {
|
|
28
|
+
return this.session.name;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Read the capabilities compiled into the Rust kernel. */
|
|
32
|
+
get features() {
|
|
33
|
+
return this.session.kernel.features;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Install new orbs and activate their required scopes. */
|
|
37
|
+
install(definition: OrbDefinition | readonly OrbDefinition[]): Promise<void> {
|
|
38
|
+
return this.session.orbs.install(
|
|
39
|
+
Array.isArray(definition) ? definition : [definition as OrbDefinition],
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Load an orb with the host's module loader, then install it. */
|
|
44
|
+
async load(location: string | URL): Promise<void> {
|
|
45
|
+
if (!this.session.options.load) throw new Error("This host has no module loader");
|
|
46
|
+
await this.install(await this.session.options.load(location));
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Prepare and commit a replacement using the kernel's lifecycle order. */
|
|
50
|
+
reload(definitions: readonly OrbDefinition[], options?: ReloadOptions) {
|
|
51
|
+
return this.session.replacements.replace(definitions, options);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Build a replacement candidate without adopting it. */
|
|
55
|
+
prepare(definitions: readonly OrbDefinition[], options?: ReloadOptions) {
|
|
56
|
+
return this.session.replacements.prepare(definitions, options);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Remove named orbs through the replacement lifecycle. */
|
|
60
|
+
remove(names: readonly string[], options?: ReloadOptions) {
|
|
61
|
+
return this.session.replacements.replace([], options, names);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Acquire a reference before its asynchronous activation completes. */
|
|
65
|
+
hold<const Service extends ServiceDefinition>(
|
|
66
|
+
service: Service,
|
|
67
|
+
key: string | readonly string[],
|
|
68
|
+
options?: AcquisitionOptions,
|
|
69
|
+
): ServiceReference<Service>;
|
|
70
|
+
hold(
|
|
71
|
+
service: string,
|
|
72
|
+
key: string | readonly string[],
|
|
73
|
+
options?: AcquisitionOptions,
|
|
74
|
+
): DynamicReference;
|
|
75
|
+
hold(
|
|
76
|
+
service: string | ServiceDefinition,
|
|
77
|
+
key: string | readonly string[],
|
|
78
|
+
options?: AcquisitionOptions,
|
|
79
|
+
) {
|
|
80
|
+
return this.session.handles.hold(service, key, options);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** Acquire a reference and wait for activation. */
|
|
84
|
+
get<const Service extends ServiceDefinition>(
|
|
85
|
+
service: Service,
|
|
86
|
+
key: string | readonly string[],
|
|
87
|
+
options?: AcquisitionOptions,
|
|
88
|
+
): Promise<ServiceReference<Service>>;
|
|
89
|
+
get(
|
|
90
|
+
service: string,
|
|
91
|
+
key: string | readonly string[],
|
|
92
|
+
options?: AcquisitionOptions,
|
|
93
|
+
): Promise<DynamicReference>;
|
|
94
|
+
get(
|
|
95
|
+
service: string | ServiceDefinition,
|
|
96
|
+
key: string | readonly string[],
|
|
97
|
+
options?: AcquisitionOptions,
|
|
98
|
+
) {
|
|
99
|
+
return this.session.handles.get(service, key, options);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Run an operation with one principal and bounded context lifetime. */
|
|
103
|
+
root<T>(
|
|
104
|
+
operation: (context: Context) => Completion<T>,
|
|
105
|
+
options: { principal?: string } = {},
|
|
106
|
+
): Promise<T> {
|
|
107
|
+
return this.session.calls.root(operation, false, undefined, options.principal);
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** Declare a resource owned by this host. */
|
|
111
|
+
resource<T>(name: string, options: ResourceOptions<T>) {
|
|
112
|
+
return this.session.scopes.resource(name, options);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** Read current kernel counts and pending JS work. */
|
|
116
|
+
diagnostics() {
|
|
117
|
+
return this.session.lifecycle.diagnostics();
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** Drain errors collected by the host. */
|
|
121
|
+
errors() {
|
|
122
|
+
return this.session.errors.splice(0);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** Drain sampled call records. */
|
|
126
|
+
traces() {
|
|
127
|
+
return this.session.telemetry?.drain() ?? [];
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Describe installed orbs without activating their services. */
|
|
131
|
+
installedOrbs() {
|
|
132
|
+
return this.session.kernel
|
|
133
|
+
.command<import("./bridge/kernel.ts").KernelOrb[]>(KernelOp.Orbs)
|
|
134
|
+
.map((info) => {
|
|
135
|
+
const definition = this.session.orbs.records.get(info.id)?.definition;
|
|
136
|
+
const description = Object.freeze({
|
|
137
|
+
...info,
|
|
138
|
+
hookCapabilities: Object.fromEntries(
|
|
139
|
+
info.hooks.map((name) => [name, definition?.hooks?.[name]?.capabilities ?? []]),
|
|
140
|
+
),
|
|
141
|
+
});
|
|
142
|
+
return Object.freeze({
|
|
143
|
+
...info,
|
|
144
|
+
/** Return captured metadata without activating services. */
|
|
145
|
+
describe: () => description,
|
|
146
|
+
});
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** Wait for physical work and cleanup before releasing the kernel. */
|
|
151
|
+
close(): Promise<void> {
|
|
152
|
+
return this.session.lifecycle.close();
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/** Create a host with an explicitly supplied platform adapter. */
|
|
157
|
+
export function createHost(options: HostOptions): Host {
|
|
158
|
+
return new Host(options);
|
|
159
|
+
}
|
|
160
|
+
export { orb };
|
|
161
|
+
|
|
162
|
+
export {
|
|
163
|
+
Code,
|
|
164
|
+
HookCapability,
|
|
165
|
+
Lifetime,
|
|
166
|
+
Reason,
|
|
167
|
+
ReloadStatus,
|
|
168
|
+
Status,
|
|
169
|
+
} from "./bridge/identifiers.ts";
|
|
170
|
+
|
|
171
|
+
export { Errors, type ErrorDescriptor } from "./errors.ts";
|
|
172
|
+
|
|
173
|
+
export type { KernelPort } from "./bridge/kernel.ts";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./bridge/identifiers.ts";
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export type { Declaration } from "./authoring/declaration.ts";
|
|
2
|
+
export { orb } from "./authoring/orb.ts";
|
|
3
|
+
export { bail, middleware, parallel, series, waterfall } from "./authoring/hooks.ts";
|
|
4
|
+
export type * from "./authoring/types.ts";
|
|
5
|
+
export { jsonCodec } from "./codecs/json.ts";
|
|
6
|
+
export type { Codec } from "./codecs/json.ts";
|
|
7
|
+
export { TembraError } from "./error.ts";
|
|
8
|
+
export type { Context } from "./runtime/context.ts";
|
|
9
|
+
export type { Readable, State, StateOptions } from "./state.ts";
|
|
10
|
+
|
|
11
|
+
export {
|
|
12
|
+
Code,
|
|
13
|
+
HookCapability,
|
|
14
|
+
Lifetime,
|
|
15
|
+
Reason,
|
|
16
|
+
ReloadStatus,
|
|
17
|
+
Status,
|
|
18
|
+
} from "./bridge/identifiers.ts";
|
|
19
|
+
|
|
20
|
+
export { Errors, type ErrorDescriptor } from "./errors.ts";
|
|
21
|
+
|
|
22
|
+
export { ContextKey, ContextKind, opaqueFrom, type OpaqueContextValue } from "./context-key.ts";
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { CoordinationDecision } from "../bridge/protocol.ts";
|
|
2
|
+
import { Errors } from "../errors.ts";
|
|
3
|
+
|
|
4
|
+
import { TembraError } from "../error.ts";
|
|
5
|
+
|
|
6
|
+
export interface Participant<T> {
|
|
7
|
+
/** Prepare this participant without publishing its changes. */
|
|
8
|
+
prepare(signal: AbortSignal): Promise<T>;
|
|
9
|
+
/** Publish this participant's prepared changes. */
|
|
10
|
+
commit(ticket: T): Promise<void>;
|
|
11
|
+
/** Release this participant's uncommitted candidate. */
|
|
12
|
+
abort(ticket: T): Promise<void>;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** Bounded direct participants. A commit decision is not a durable distributed transaction. */
|
|
16
|
+
export async function coordinate<T>(
|
|
17
|
+
participants: readonly Participant<T>[],
|
|
18
|
+
options: { deadline?: number; maxParticipants?: number } = {},
|
|
19
|
+
): Promise<void> {
|
|
20
|
+
const deadline = options.deadline ?? 5000;
|
|
21
|
+
if (
|
|
22
|
+
participants.length > (options.maxParticipants ?? 32) ||
|
|
23
|
+
!Number.isFinite(deadline) ||
|
|
24
|
+
deadline <= 0
|
|
25
|
+
)
|
|
26
|
+
throw new TembraError(Errors.Invalid.CoordinationLimits);
|
|
27
|
+
const controller = new AbortController();
|
|
28
|
+
const prepared = new Map<Participant<T>, T>();
|
|
29
|
+
let decision: CoordinationDecision = CoordinationDecision.Preparing;
|
|
30
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
31
|
+
const preparation = Promise.all(
|
|
32
|
+
participants.map(async (participant) => {
|
|
33
|
+
const ticket = await participant.prepare(controller.signal);
|
|
34
|
+
if (decision === CoordinationDecision.Abort) await participant.abort(ticket);
|
|
35
|
+
else prepared.set(participant, ticket);
|
|
36
|
+
}),
|
|
37
|
+
);
|
|
38
|
+
try {
|
|
39
|
+
await Promise.race([
|
|
40
|
+
preparation,
|
|
41
|
+
new Promise<never>((_, reject) => {
|
|
42
|
+
timer = setTimeout(
|
|
43
|
+
() => reject(new TembraError(Errors.Conflict.PrepareDeadline)),
|
|
44
|
+
deadline,
|
|
45
|
+
);
|
|
46
|
+
}),
|
|
47
|
+
]);
|
|
48
|
+
decision = CoordinationDecision.Commit;
|
|
49
|
+
} catch (error) {
|
|
50
|
+
decision = CoordinationDecision.Abort;
|
|
51
|
+
controller.abort(error);
|
|
52
|
+
const aborted = await Promise.allSettled(
|
|
53
|
+
[...prepared].map(([participant, ticket]) => participant.abort(ticket)),
|
|
54
|
+
);
|
|
55
|
+
preparation.catch(() => {});
|
|
56
|
+
const errors = aborted
|
|
57
|
+
.filter((result) => result.status === "rejected")
|
|
58
|
+
.map((result) => result.reason);
|
|
59
|
+
if (errors.length)
|
|
60
|
+
throw new AggregateError([error, ...errors], "Preparation and cleanup failed");
|
|
61
|
+
throw error;
|
|
62
|
+
} finally {
|
|
63
|
+
clearTimeout(timer);
|
|
64
|
+
}
|
|
65
|
+
const committed = await Promise.allSettled(
|
|
66
|
+
[...prepared].map(([participant, ticket]) => participant.commit(ticket)),
|
|
67
|
+
);
|
|
68
|
+
const errors = committed
|
|
69
|
+
.filter((result) => result.status === "rejected")
|
|
70
|
+
.map((result) => result.reason);
|
|
71
|
+
if (errors.length)
|
|
72
|
+
throw new AggregateError(
|
|
73
|
+
errors,
|
|
74
|
+
"Commit was decided but some participants did not acknowledge it",
|
|
75
|
+
);
|
|
76
|
+
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { Errors } from "../errors.ts";
|
|
2
|
+
|
|
3
|
+
import { TembraError } from "../error.ts";
|
|
4
|
+
import type { Host } from "../host.ts";
|
|
5
|
+
|
|
6
|
+
/** Explicit infrastructure lifecycle. Replacing a host creates new memory and references. */
|
|
7
|
+
export class HostManager {
|
|
8
|
+
#hosts = new Map<string, Host>();
|
|
9
|
+
#pending = new Map<string, Promise<Host>>();
|
|
10
|
+
|
|
11
|
+
/** Read an existing host without starting it. */
|
|
12
|
+
get(name: string): Host | undefined {
|
|
13
|
+
return this.#hosts.get(name);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Share one pending creation for each host name. */
|
|
17
|
+
start(name: string, create: () => Promise<Host> | Host): Promise<Host> {
|
|
18
|
+
const existing = this.#hosts.get(name);
|
|
19
|
+
if (existing) return Promise.resolve(existing);
|
|
20
|
+
const pending = this.#pending.get(name);
|
|
21
|
+
if (pending) return pending;
|
|
22
|
+
const operation = Promise.resolve()
|
|
23
|
+
.then(create)
|
|
24
|
+
.then((host) => {
|
|
25
|
+
this.#hosts.set(name, host);
|
|
26
|
+
return host;
|
|
27
|
+
})
|
|
28
|
+
.finally(() => {
|
|
29
|
+
this.#pending.delete(name);
|
|
30
|
+
});
|
|
31
|
+
this.#pending.set(name, operation);
|
|
32
|
+
return operation;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Remove the named host and wait for its cleanup. */
|
|
36
|
+
async stop(name: string): Promise<void> {
|
|
37
|
+
await this.#pending.get(name);
|
|
38
|
+
const host = this.#hosts.get(name);
|
|
39
|
+
if (!host) return;
|
|
40
|
+
this.#hosts.delete(name);
|
|
41
|
+
await host.close();
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Close the old host before creating its replacement. */
|
|
45
|
+
async replace(name: string, create: () => Promise<Host> | Host): Promise<Host> {
|
|
46
|
+
await this.stop(name);
|
|
47
|
+
return this.start(name, create);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** Wait for every managed host and report cleanup failures together. */
|
|
51
|
+
async close(): Promise<void> {
|
|
52
|
+
const names = new Set([...this.#hosts.keys(), ...this.#pending.keys()]);
|
|
53
|
+
const results = await Promise.allSettled([...names].map((name) => this.stop(name)));
|
|
54
|
+
const errors = results
|
|
55
|
+
.filter((result) => result.status === "rejected")
|
|
56
|
+
.map((result) => result.reason);
|
|
57
|
+
if (errors.length) throw new AggregateError(errors, "Host cleanup failed");
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Route acquisitions to an application-selected host. */
|
|
62
|
+
export function router<
|
|
63
|
+
H extends {
|
|
64
|
+
/** Acquire a reference from the selected host. */
|
|
65
|
+
get(service: string, key: string | readonly string[], options?: any): any;
|
|
66
|
+
},
|
|
67
|
+
>(hosts: ReadonlyMap<string, H>, route: (service: string, key: readonly string[]) => string) {
|
|
68
|
+
return {
|
|
69
|
+
/** Choose the destination host before acquiring the reference. */
|
|
70
|
+
get(service: string, key: string | readonly string[], options?: any): ReturnType<H["get"]> {
|
|
71
|
+
const name = route(service, typeof key === "string" ? [key] : key);
|
|
72
|
+
const host = hosts.get(name);
|
|
73
|
+
if (!host) throw new TembraError(Errors.Unavailable.Route, name);
|
|
74
|
+
return host.get(service, key, options);
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
}
|