@niwa-labs/host 0.0.0-stage → 0.0.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 +21 -0
- package/README.md +2 -2
- package/package.json +16 -4
- package/src/access-actions.ts +193 -0
- package/src/access-control.ts +333 -0
- package/src/call-operations.ts +176 -0
- package/src/cockpit-catalog.ts +99 -0
- package/src/describe.ts +55 -0
- package/src/doors.ts +272 -0
- package/src/host-types.ts +43 -0
- package/src/host.ts +3346 -0
- package/src/index.ts +10 -0
- package/src/plugin-install.ts +249 -0
- package/src/state.ts +261 -0
- package/src/stores.ts +131 -0
- package/test/abandon.test.ts +58 -0
- package/test/action-refusal-restart.test.ts +46 -0
- package/test/action-step.test.ts +363 -0
- package/test/action-wait-restart.test.ts +96 -0
- package/test/builtin-actions.test.ts +21 -0
- package/test/cancel-steps.test.ts +150 -0
- package/test/catch-up.test.ts +378 -0
- package/test/causes.test.ts +138 -0
- package/test/client.test.ts +190 -0
- package/test/cockpit-catalog.test.ts +118 -0
- package/test/crash-between-steps.test.ts +88 -0
- package/test/declared-values.test.ts +175 -0
- package/test/deep-nested-pause.test.ts +147 -0
- package/test/fixtures/action-step-host.ts +166 -0
- package/test/fixtures/action-wait-restart-host.ts +62 -0
- package/test/fixtures/catch-up-host.ts +91 -0
- package/test/fixtures/causes-host.ts +78 -0
- package/test/fixtures/client-host.ts +52 -0
- package/test/fixtures/crash-between-steps-host.ts +71 -0
- package/test/fixtures/declared-values-host.ts +110 -0
- package/test/fixtures/intercept-order-host.ts +112 -0
- package/test/fixtures/intercept-step-host.ts +106 -0
- package/test/fixtures/live-frames-host.ts +81 -0
- package/test/fixtures/long-wait-host.ts +78 -0
- package/test/fixtures/nested-wait-host.ts +120 -0
- package/test/fixtures/no-repeat-crash-host.ts +79 -0
- package/test/fixtures/plugin-replace-host.ts +176 -0
- package/test/fixtures/record-refusal-crash.ts +50 -0
- package/test/fixtures/recovery-contracts-host.ts +79 -0
- package/test/fixtures/repeated-write-host.ts +39 -0
- package/test/fixtures/replay-mismatch-host.ts +66 -0
- package/test/fixtures/single-writer-host.ts +113 -0
- package/test/fixtures/state-host.ts +118 -0
- package/test/fixtures/wait-restart-host.ts +82 -0
- package/test/guards.test.ts +448 -0
- package/test/handler-emit.test.ts +116 -0
- package/test/host.test.ts +114 -0
- package/test/intercept-adjust.test.ts +318 -0
- package/test/intercept-order.test.ts +276 -0
- package/test/intercept-step.test.ts +144 -0
- package/test/large-outcome.test.ts +60 -0
- package/test/live-frames.test.ts +150 -0
- package/test/live-ready.test.ts +61 -0
- package/test/long-wait.test.ts +168 -0
- package/test/nested-outcome.test.ts +75 -0
- package/test/nested-wait.test.ts +111 -0
- package/test/no-repeat-crash.test.ts +132 -0
- package/test/offer-replace.test.ts +39 -0
- package/test/plugin-async-setup.test.ts +22 -0
- package/test/plugin-copies.test.ts +87 -0
- package/test/plugin-emit.test.ts +43 -0
- package/test/plugin-install-failure.test.ts +121 -0
- package/test/plugin-install-hash.test.ts +57 -0
- package/test/plugin-needs.test.ts +80 -0
- package/test/plugin-replace.test.ts +225 -0
- package/test/plugin-uninstall.test.ts +70 -0
- package/test/plugin-version-copies.test.ts +53 -0
- package/test/plugin-version.test.ts +180 -0
- package/test/read-filter.test.ts +136 -0
- package/test/read-query.test.ts +92 -0
- package/test/record-admission.test.ts +294 -0
- package/test/recovery-contracts.test.ts +107 -0
- package/test/repeated-write.test.ts +119 -0
- package/test/replay-mismatch.test.ts +79 -0
- package/test/replay.test.ts +135 -0
- package/test/single-writer.test.ts +267 -0
- package/test/state.test.ts +246 -0
- package/test/step-by-name.test.ts +122 -0
- package/test/stores.test.ts +102 -0
- package/test/stream.test.ts +154 -0
- package/test/subscriber-stream.test.ts +71 -0
- package/test/subscribers.test.ts +101 -0
- package/test/subscriptions.test.ts +632 -0
- package/test/trace-call.test.ts +124 -0
- package/test/trigger-filter.test.ts +42 -0
- package/test/use-many.test.ts +151 -0
- package/test/wait-query.test.ts +117 -0
- package/test/wait-restart.test.ts +187 -0
- package/test/wire-read-access.test.ts +85 -0
- package/tsconfig.json +6 -0
package/src/host.ts
ADDED
|
@@ -0,0 +1,3346 @@
|
|
|
1
|
+
// The host: the one process that owns the journal and runs the plugins.
|
|
2
|
+
//
|
|
3
|
+
// The rules this file keeps:
|
|
4
|
+
// - one writer: the journal is opened once, and only here;
|
|
5
|
+
// - append first, publish after: nobody sees a record before it is committed;
|
|
6
|
+
// - delivery is at-least-once: the identity of an invocation is deterministic, so admitting it
|
|
7
|
+
// twice is harmless;
|
|
8
|
+
// - an invocation is pinned to the version of the plugin it was admitted on: work in
|
|
9
|
+
// flight finishes on its own code;
|
|
10
|
+
// - a client is named by the host from the connection, never by what it sends.
|
|
11
|
+
|
|
12
|
+
import { chmodSync, existsSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
13
|
+
import { homedir } from "node:os";
|
|
14
|
+
|
|
15
|
+
import { z } from "zod";
|
|
16
|
+
|
|
17
|
+
import {
|
|
18
|
+
effectOfCall,
|
|
19
|
+
actionEmits,
|
|
20
|
+
RecordRefused,
|
|
21
|
+
action,
|
|
22
|
+
actionName,
|
|
23
|
+
realClock,
|
|
24
|
+
IntegrityError,
|
|
25
|
+
PluginInstallFailed,
|
|
26
|
+
CatchableError,
|
|
27
|
+
effectPossibleAfter,
|
|
28
|
+
LostOwnership,
|
|
29
|
+
MissingNeed,
|
|
30
|
+
MissingProvider,
|
|
31
|
+
MissingReader,
|
|
32
|
+
UnknownAction,
|
|
33
|
+
UnknownType,
|
|
34
|
+
ValidationError,
|
|
35
|
+
WriterBusy,
|
|
36
|
+
causes,
|
|
37
|
+
trace,
|
|
38
|
+
DeniedError,
|
|
39
|
+
WAIT_ACTION,
|
|
40
|
+
offeredChoices,
|
|
41
|
+
OWNER,
|
|
42
|
+
OWNER_TOKEN_FILE,
|
|
43
|
+
principalOf,
|
|
44
|
+
CANCEL_STEPS_ACTION,
|
|
45
|
+
MOVE_ACTION,
|
|
46
|
+
RESOLVE_ACTION,
|
|
47
|
+
attemptRecordId,
|
|
48
|
+
attemptsOf,
|
|
49
|
+
resolveId,
|
|
50
|
+
shortInvocation,
|
|
51
|
+
CORE_TYPES,
|
|
52
|
+
newId,
|
|
53
|
+
newRecordId,
|
|
54
|
+
recordId,
|
|
55
|
+
recordTypeName,
|
|
56
|
+
seq,
|
|
57
|
+
streamId,
|
|
58
|
+
timestamp,
|
|
59
|
+
readFiltered,
|
|
60
|
+
targetName,
|
|
61
|
+
matchesQuery,
|
|
62
|
+
stableJson,
|
|
63
|
+
overlaps,
|
|
64
|
+
resolveQuery,
|
|
65
|
+
selectsType,
|
|
66
|
+
} from "@niwa-labs/core";
|
|
67
|
+
import type {
|
|
68
|
+
ArtifactStore,
|
|
69
|
+
SecretStore,
|
|
70
|
+
Clock,
|
|
71
|
+
DeniedDetails,
|
|
72
|
+
Found,
|
|
73
|
+
ActionRef,
|
|
74
|
+
ActionTarget,
|
|
75
|
+
Action,
|
|
76
|
+
ActionName,
|
|
77
|
+
ActionStep,
|
|
78
|
+
Ask,
|
|
79
|
+
AskOutcome,
|
|
80
|
+
AuthorizeHow,
|
|
81
|
+
Asker,
|
|
82
|
+
CallOptions,
|
|
83
|
+
Grant,
|
|
84
|
+
AdjustFn,
|
|
85
|
+
AnyWaited,
|
|
86
|
+
AppendEntry,
|
|
87
|
+
Caller,
|
|
88
|
+
Effect,
|
|
89
|
+
ClientId,
|
|
90
|
+
Description,
|
|
91
|
+
EmitOptions,
|
|
92
|
+
EmitBatch,
|
|
93
|
+
GuardFn,
|
|
94
|
+
Handler,
|
|
95
|
+
HandlerId,
|
|
96
|
+
InvocationId,
|
|
97
|
+
Journal,
|
|
98
|
+
LiveFrame,
|
|
99
|
+
NewRecord,
|
|
100
|
+
OperationId,
|
|
101
|
+
Outcome,
|
|
102
|
+
PluginName,
|
|
103
|
+
PluginVersion,
|
|
104
|
+
Principal,
|
|
105
|
+
RecordId,
|
|
106
|
+
RecordType,
|
|
107
|
+
RecordTypeName,
|
|
108
|
+
Seq,
|
|
109
|
+
StreamId,
|
|
110
|
+
Timestamp,
|
|
111
|
+
StepKey,
|
|
112
|
+
StoredRecord,
|
|
113
|
+
Token,
|
|
114
|
+
TracedRecord,
|
|
115
|
+
Verb,
|
|
116
|
+
RecordReadQuery,
|
|
117
|
+
RecordQuery,
|
|
118
|
+
ResolvedQuery,
|
|
119
|
+
WaitEntry,
|
|
120
|
+
WaitKey,
|
|
121
|
+
WaitQuery,
|
|
122
|
+
Waited,
|
|
123
|
+
} from "@niwa-labs/core";
|
|
124
|
+
import { describe as buildDescription } from "./describe.ts";
|
|
125
|
+
import {
|
|
126
|
+
NO_INTERCEPTS,
|
|
127
|
+
decide,
|
|
128
|
+
newIntercepts,
|
|
129
|
+
permit,
|
|
130
|
+
settleAsk,
|
|
131
|
+
admits,
|
|
132
|
+
findWaited,
|
|
133
|
+
invocationId,
|
|
134
|
+
abortSteps,
|
|
135
|
+
runInvocation,
|
|
136
|
+
stepKey,
|
|
137
|
+
openJournal,
|
|
138
|
+
} from "@niwa-labs/core/journal";
|
|
139
|
+
import type { Intercepts, Permit, Placement, RunnerDeps } from "@niwa-labs/core/journal";
|
|
140
|
+
import { Doors, loadHostKey } from "./doors.ts";
|
|
141
|
+
import {
|
|
142
|
+
readOwnerToken,
|
|
143
|
+
LiveBus,
|
|
144
|
+
LiveFeed,
|
|
145
|
+
channelName,
|
|
146
|
+
frameFor,
|
|
147
|
+
decodeClientMessage,
|
|
148
|
+
encode,
|
|
149
|
+
lineDecoder,
|
|
150
|
+
requestIdOf,
|
|
151
|
+
socketPath,
|
|
152
|
+
CAUSES_ACTION,
|
|
153
|
+
DESCRIBE_ACTION,
|
|
154
|
+
RECORDS_READ_ACTION,
|
|
155
|
+
CATALOG_ACTION,
|
|
156
|
+
CatalogOutput,
|
|
157
|
+
RECORDS_SEARCH_ACTION,
|
|
158
|
+
STATUS_ACTION,
|
|
159
|
+
STOP_ACTION,
|
|
160
|
+
StatusOutput,
|
|
161
|
+
TRACE_ACTION,
|
|
162
|
+
DescriptionOutput,
|
|
163
|
+
RecordWalkInput,
|
|
164
|
+
RecordList,
|
|
165
|
+
RecordsOutput,
|
|
166
|
+
RecordsReadInput,
|
|
167
|
+
RecordsSearchInput,
|
|
168
|
+
TracedRecordsOutput,
|
|
169
|
+
} from "@niwa-labs/client";
|
|
170
|
+
import { AccessControl } from "./access-control.ts";
|
|
171
|
+
import { CallOperations } from "./call-operations.ts";
|
|
172
|
+
import { accessActions } from "./access-actions.ts";
|
|
173
|
+
import { PluginInstalledData, currentInstallations, installationOf, pluginInstallAction, pluginUninstallAction, removeCopyIfStale, removeStaleCopies, restorePlugin } from "./plugin-install.ts";
|
|
174
|
+
import { COCKPIT_MODULE, handlerSource, pluginVersion, pluginName, sealVersion } from "@niwa-labs/plugin";
|
|
175
|
+
import { catalogOf } from "./cockpit-catalog.ts";
|
|
176
|
+
import { StateStore } from "./state.ts";
|
|
177
|
+
import { artifactStore, secretStore } from "./stores.ts";
|
|
178
|
+
import type { HostMessage, LiveSubscription, RecordFeed } from "@niwa-labs/client";
|
|
179
|
+
import { isTrigger } from "@niwa-labs/plugin";
|
|
180
|
+
import type { Trigger } from "@niwa-labs/plugin";
|
|
181
|
+
import type { OfferKey, Offered, HandlerOptions, Plugin, PluginNeeds, Service, ServiceContext, StateHandle, Subscribable, Subscriber, SubscriptionConcurrency, SubscriptionKey, SubscriptionStart } from "@niwa-labs/plugin";
|
|
182
|
+
import type { Host, HostOptions } from "./host-types.ts";
|
|
183
|
+
|
|
184
|
+
/** The reader of an offer point that the host itself reads. */
|
|
185
|
+
const HOST_READER = "host";
|
|
186
|
+
|
|
187
|
+
type AnyType = RecordType<any>;
|
|
188
|
+
type AnyAction = Action<any, any>;
|
|
189
|
+
|
|
190
|
+
// The brand constructors this file needs: each name is built here from parts that are valid.
|
|
191
|
+
|
|
192
|
+
function handlerIdOf(value: string): HandlerId {
|
|
193
|
+
return value as HandlerId;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
function clientIdOf(value: string): ClientId {
|
|
197
|
+
return value as ClientId;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
function newOperationId(): OperationId {
|
|
201
|
+
return newId("op") as OperationId;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** The pseudo-key of a pause that is not about a step. */
|
|
205
|
+
const NO_STEP = "" as StepKey;
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* The clock of the transport: the real time.
|
|
209
|
+
*
|
|
210
|
+
* The probe of the socket is about the transport, not about the domain time of the host, so it
|
|
211
|
+
* waits on the real clock and not on the clock of the host: a host whose clock is moved by hand
|
|
212
|
+
* must not hang its own start.
|
|
213
|
+
*/
|
|
214
|
+
const TRANSPORT_CLOCK: Clock = realClock();
|
|
215
|
+
|
|
216
|
+
/** A call a client named with an operation id: the id it runs under, and what to do as it begins. */
|
|
217
|
+
interface MadeUnder {
|
|
218
|
+
readonly actor: Caller;
|
|
219
|
+
readonly operation: OperationId;
|
|
220
|
+
began(): void;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* What a call outside an invocation ended with.
|
|
225
|
+
*
|
|
226
|
+
* A call that was denied, or whose input or output did not fit, ends here and not with an
|
|
227
|
+
* exception: `step.outcome` asks for the outcome, and the code that asked decides what to do
|
|
228
|
+
* with it.
|
|
229
|
+
*/
|
|
230
|
+
type OutsideCall<O> =
|
|
231
|
+
| { kind: "completed"; value: O }
|
|
232
|
+
| { kind: "unknown-action"; action: ActionName }
|
|
233
|
+
| { kind: "denied"; reason: string; denied?: DeniedDetails }
|
|
234
|
+
| { kind: "invalid-input"; message: string; issues: unknown }
|
|
235
|
+
| { kind: "invalid-output"; message: string; issues: unknown };
|
|
236
|
+
|
|
237
|
+
/** The records the table of the doors is folded from. */
|
|
238
|
+
const ACCESS_TYPES = new Set<string>([
|
|
239
|
+
CORE_TYPES.accessIssued,
|
|
240
|
+
CORE_TYPES.accessGranted,
|
|
241
|
+
CORE_TYPES.accessClosed,
|
|
242
|
+
CORE_TYPES.accessProfile,
|
|
243
|
+
CORE_TYPES.accessSwitched,
|
|
244
|
+
CORE_TYPES.accessAnswered,
|
|
245
|
+
]);
|
|
246
|
+
|
|
247
|
+
/** The types the core writes itself: nothing outside writes them. */
|
|
248
|
+
const CORE_TYPE_NAMES = new Set<string>(Object.values(CORE_TYPES));
|
|
249
|
+
|
|
250
|
+
/** What the core wrote into an admitted record that the host reads back. */
|
|
251
|
+
const AdmittedData = z.object({
|
|
252
|
+
handler: z.string().includes("/"),
|
|
253
|
+
record: z.string(),
|
|
254
|
+
pluginVersion: z.string().min(1),
|
|
255
|
+
keyed: z.object({ key: z.union([z.string(), z.number()]), cursor: z.number().int().nonnegative() }).optional(),
|
|
256
|
+
});
|
|
257
|
+
const AdmittedWithPosition = AdmittedData.extend({ recordSeq: z.number(), recordType: z.string() });
|
|
258
|
+
const PositionData = z.object({ subscription: z.string(), seq: z.number().int().nonnegative(), reason: z.string() });
|
|
259
|
+
|
|
260
|
+
/** Why a subscription's position moved past records without admitting them again. */
|
|
261
|
+
type PassReason = "installed" | "filtered" | "schema" | "self" | "reentry" | "already-admitted";
|
|
262
|
+
const StateData = z.object({
|
|
263
|
+
invocation: z.string(),
|
|
264
|
+
state: z.string(),
|
|
265
|
+
key: z.string().optional(),
|
|
266
|
+
choices: z.array(z.string()).optional(),
|
|
267
|
+
});
|
|
268
|
+
const MovedData = z.object({ to: z.string().min(1) });
|
|
269
|
+
const IntentData = z.object({
|
|
270
|
+
invocation: z.string().optional(),
|
|
271
|
+
key: z.string().optional(),
|
|
272
|
+
action: z.string(),
|
|
273
|
+
input: z
|
|
274
|
+
.object({
|
|
275
|
+
type: z.string().optional(),
|
|
276
|
+
types: z.array(z.string()).optional(),
|
|
277
|
+
// A key that does not parse is no key: the wait is indexed by its type alone, which wakes
|
|
278
|
+
// it for more records than it needs but never for fewer. Failing the whole intent instead
|
|
279
|
+
// would drop the wait from the index and lose its wake.
|
|
280
|
+
key: z.object({ field: z.string(), equals: z.string() }).optional().catch(undefined),
|
|
281
|
+
})
|
|
282
|
+
.optional(),
|
|
283
|
+
});
|
|
284
|
+
|
|
285
|
+
/** What a handler says about the records it subscribes to, checked when it is registered. */
|
|
286
|
+
interface Subscribing {
|
|
287
|
+
/** Equality on paths of the data: records that do not hold it advance the position and wake nothing. */
|
|
288
|
+
readonly filter: Readonly<Record<string, unknown>> | undefined;
|
|
289
|
+
/** Where a new subscription starts: now, the start, or the position a subscriber from the journal gives. */
|
|
290
|
+
readonly from: SubscriptionStart | Seq;
|
|
291
|
+
/** A limit on unfinished invocations, or one per selected key. */
|
|
292
|
+
readonly concurrency: SubscriptionConcurrency<any>;
|
|
293
|
+
/** How many of its own invocations may stand on the chain of a record that wakes it; 0 when none may. */
|
|
294
|
+
readonly depth: number;
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/** The subscribing of a handler that says nothing: from now, one at a time, never its own records. */
|
|
298
|
+
const SUBSCRIBING: Subscribing = { filter: undefined, from: "now", concurrency: 1, depth: 0 };
|
|
299
|
+
|
|
300
|
+
/** The options of a handler as the host keeps them, refused when they cannot be served. */
|
|
301
|
+
function subscribingOf(where: string, options: HandlerOptions<any>): Subscribing {
|
|
302
|
+
const concurrency = options.concurrency === undefined ? 1 : options.concurrency;
|
|
303
|
+
if (typeof concurrency === "number") {
|
|
304
|
+
if (!(concurrency === Infinity || (Number.isInteger(concurrency) && concurrency >= 1))) {
|
|
305
|
+
throw new TypeError(`${where}: concurrency is a whole number from 1 or Infinity, not ${String(concurrency)}`);
|
|
306
|
+
}
|
|
307
|
+
} else if (concurrency === null || typeof concurrency !== "object" || Array.isArray(concurrency) || typeof concurrency.by !== "function") {
|
|
308
|
+
throw new TypeError(`${where}: keyed concurrency requires { by: (data) => key }`);
|
|
309
|
+
}
|
|
310
|
+
const depth = options.reentrant?.depth ?? 0;
|
|
311
|
+
if (options.reentrant !== undefined && !(Number.isInteger(depth) && depth >= 1)) {
|
|
312
|
+
throw new TypeError(`${where}: the depth of a reentrant handler is a whole number from 1, not ${String(depth)}`);
|
|
313
|
+
}
|
|
314
|
+
const from = options.from ?? "now";
|
|
315
|
+
if (from !== "now" && from !== "start") throw new TypeError(`${where}: from is "now" or "start", not ${String(from)}`);
|
|
316
|
+
const filter = options.filter as Readonly<Record<string, unknown>> | undefined;
|
|
317
|
+
if (filter !== undefined && (typeof filter !== "object" || filter === null || Array.isArray(filter))) {
|
|
318
|
+
throw new TypeError(`${where}: a filter is an object of values by field name or dotted path`);
|
|
319
|
+
}
|
|
320
|
+
return { filter, from, concurrency, depth };
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/** One handler a plugin declared. */
|
|
324
|
+
interface HandlerEntry {
|
|
325
|
+
readonly name: string;
|
|
326
|
+
readonly type: AnyType;
|
|
327
|
+
readonly handler: Handler<any>;
|
|
328
|
+
/** The record types another plugin has to declare for this handler to work. */
|
|
329
|
+
readonly requires: readonly AnyType[];
|
|
330
|
+
readonly subscribing: Subscribing;
|
|
331
|
+
/** Set when the handler subscribes to a trigger: the plugin named as the one that writes its records. */
|
|
332
|
+
readonly trigger?: { readonly provider: string | undefined };
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/** A subscription the host serves: a handler a plugin registered, or a subscriber it reads from the journal. */
|
|
336
|
+
interface Served {
|
|
337
|
+
/** The record types it reads, as names or families: every type of its selectors. */
|
|
338
|
+
readonly types: readonly RecordTypeName[];
|
|
339
|
+
/** What wakes it: a record of one selector's types whose data holds that selector's filter. */
|
|
340
|
+
readonly selectors: readonly Selector[];
|
|
341
|
+
/** The version of the schema a record must have to be read through the handler's type; any when absent. */
|
|
342
|
+
readonly schema: number | undefined;
|
|
343
|
+
readonly version: PluginVersion;
|
|
344
|
+
readonly handler: Handler<any>;
|
|
345
|
+
readonly subscribing: Subscribing;
|
|
346
|
+
/** The position after which it admits nothing: the end of a subscriber that ended. */
|
|
347
|
+
readonly until?: Seq;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* One part of what wakes a subscription: a query of the core without a position. The types are
|
|
352
|
+
* absent when the query names none, as they are in the core: every type.
|
|
353
|
+
*/
|
|
354
|
+
type Selector = Omit<ResolvedQuery, "from">;
|
|
355
|
+
|
|
356
|
+
/** The type a subscriber's handler reads its records through: any data, as it was written. */
|
|
357
|
+
const ANY_DATA = z.unknown();
|
|
358
|
+
|
|
359
|
+
/** What one installed version of a plugin declared while its setup function ran. */
|
|
360
|
+
interface Installed {
|
|
361
|
+
readonly source: Plugin;
|
|
362
|
+
/** Known once the setup has run: the default version covers the handlers it registered. */
|
|
363
|
+
version: PluginVersion;
|
|
364
|
+
readonly types: AnyType[];
|
|
365
|
+
readonly actions: AnyAction[];
|
|
366
|
+
readonly handlers: HandlerEntry[];
|
|
367
|
+
/** The intercepts the plugin registered, by the name of the action they are on. */
|
|
368
|
+
readonly intercepts: Map<ActionName, Intercepts>;
|
|
369
|
+
/** The services the plugin declared: they run while the host serves. */
|
|
370
|
+
readonly services: Service[];
|
|
371
|
+
/** The profiles the plugin declared: the only ones it may set. */
|
|
372
|
+
readonly profiles: Set<string>;
|
|
373
|
+
/** The actions the plugin reads from the journal as it grows, besides the ones it declared. */
|
|
374
|
+
readonly catalogs: Array<() => readonly AnyAction[]>;
|
|
375
|
+
/** The subscriptions the plugin reads from the journal as it grows, besides the handlers it registered. */
|
|
376
|
+
readonly subscribers: Array<() => readonly Subscriber[]>;
|
|
377
|
+
/** How the plugin puts the question of an `ask` rule to the owner, when it does. */
|
|
378
|
+
asker?: Asker;
|
|
379
|
+
/** The counts the plugin shows in the status of the host. */
|
|
380
|
+
summary?: () => Record<string, number>;
|
|
381
|
+
/** What the plugin offers at the points other plugins read, by the name of the point. */
|
|
382
|
+
readonly offers: Array<{ readonly key: OfferKey<unknown>; readonly value: unknown }>;
|
|
383
|
+
/** The points the plugin read in its setup: a plugin installed after it may not offer there. */
|
|
384
|
+
readonly readInSetup: Set<string>;
|
|
385
|
+
/** What the plugin needs the host to serve, besides what it declares itself. */
|
|
386
|
+
readonly needs: { readonly actions: Set<string>; readonly types: Set<string> };
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
/** A handler of one version of one plugin, kept so work in flight can finish on it. */
|
|
390
|
+
interface Pinned {
|
|
391
|
+
readonly handler: Handler<any>;
|
|
392
|
+
readonly type: AnyType;
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
/** One invocation the host has to run, as its admitted record says. */
|
|
396
|
+
interface RunSpec {
|
|
397
|
+
readonly invocation: InvocationId;
|
|
398
|
+
readonly handlerId: HandlerId;
|
|
399
|
+
readonly record: StoredRecord;
|
|
400
|
+
readonly version: PluginVersion;
|
|
401
|
+
/** The key selected at admission, kept through waits, pauses and replay. */
|
|
402
|
+
readonly key: SubscriptionKey | undefined;
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
/** The occupied places of a subscription, including numeric admissions with no key. */
|
|
406
|
+
interface ActiveSubscription {
|
|
407
|
+
size: number;
|
|
408
|
+
readonly keys: Map<SubscriptionKey | undefined, number>;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
/** The index slot a wait sits in: its type alone, or the type with the field and value of its key. */
|
|
412
|
+
function indexSlot(type: RecordTypeName, key: WaitKey | undefined): string {
|
|
413
|
+
return key === undefined ? type : JSON.stringify([type, key.field, key.equals]);
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
/** One thing a waiting invocation waits for: a record type, and the key a record of it must carry. */
|
|
417
|
+
interface WaitSlot {
|
|
418
|
+
readonly type: RecordTypeName;
|
|
419
|
+
readonly key: WaitKey | undefined;
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/** What a step intent waits for: nothing when it is not a wait, else each type under its key. */
|
|
423
|
+
function slotsOf(intent: z.infer<typeof IntentData>): WaitSlot[] {
|
|
424
|
+
if (intent.action !== WAIT_ACTION || intent.input === undefined) return [];
|
|
425
|
+
const { type, types, key } = intent.input;
|
|
426
|
+
return (types ?? (type === undefined ? [] : [type])).map((name) => ({ type: recordTypeName(name), key }));
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
function pinKey(handler: HandlerId, version: PluginVersion): string {
|
|
430
|
+
return `${handler}@${version}`;
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
/**
|
|
434
|
+
* A live view of the journal. It is subscribed before the history is read, so a record
|
|
435
|
+
* committed in between is buffered and not lost; the cursor makes the handover duplicate-free.
|
|
436
|
+
*/
|
|
437
|
+
class Feed {
|
|
438
|
+
private readonly queue: StoredRecord[] = [];
|
|
439
|
+
private wake: (() => void) | undefined;
|
|
440
|
+
private closed = false;
|
|
441
|
+
|
|
442
|
+
constructor(private readonly query: ResolvedQuery) {}
|
|
443
|
+
|
|
444
|
+
push(record: StoredRecord): void {
|
|
445
|
+
if (this.closed) return;
|
|
446
|
+
if (!matchesQuery({ ...this.query, from: undefined }, record)) return;
|
|
447
|
+
this.queue.push(record);
|
|
448
|
+
this.notify();
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
close(): void {
|
|
452
|
+
this.closed = true;
|
|
453
|
+
this.notify();
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
/** The records that arrive from here on, after the position given, until the feed is closed. */
|
|
457
|
+
async *iterate(from: Seq): AsyncGenerator<StoredRecord, void, undefined> {
|
|
458
|
+
let cursor = from;
|
|
459
|
+
while (!this.closed) {
|
|
460
|
+
const record = this.queue.shift();
|
|
461
|
+
if (record === undefined) {
|
|
462
|
+
await new Promise<void>((resolve) => {
|
|
463
|
+
this.wake = resolve;
|
|
464
|
+
});
|
|
465
|
+
} else if (record.seq > cursor) {
|
|
466
|
+
cursor = record.seq;
|
|
467
|
+
yield record;
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
private notify(): void {
|
|
473
|
+
const wake = this.wake;
|
|
474
|
+
this.wake = undefined;
|
|
475
|
+
wake?.();
|
|
476
|
+
}
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
/** Live frames a client may have waiting in its socket queue; the frames past it are dropped. */
|
|
480
|
+
const MAX_LIVE_BACKLOG = 256;
|
|
481
|
+
|
|
482
|
+
/** One connection of a client. Its caller is named by the host: the label is only for people. */
|
|
483
|
+
class Connection {
|
|
484
|
+
/** The subscriptions this connection opened: closed with it. */
|
|
485
|
+
readonly feeds = new Set<Feed>();
|
|
486
|
+
/** The live channels this connection listens to: closed with it. */
|
|
487
|
+
readonly liveFeeds = new Set<LiveFeed>();
|
|
488
|
+
private readonly receive: (chunk: Uint8Array | string) => void;
|
|
489
|
+
/** The frames the socket did not take yet; the head may be partly written. */
|
|
490
|
+
private readonly queue: Uint8Array[] = [];
|
|
491
|
+
private open = true;
|
|
492
|
+
private greeted = false;
|
|
493
|
+
private id: ClientId;
|
|
494
|
+
/** Who the token of the connection says it is; a connection with none is a plain client. */
|
|
495
|
+
private who: Principal;
|
|
496
|
+
private named = false;
|
|
497
|
+
|
|
498
|
+
constructor(
|
|
499
|
+
private readonly socket: Bun.Socket<Connection>,
|
|
500
|
+
private readonly number: number,
|
|
501
|
+
onMessage: (connection: Connection, raw: unknown) => void,
|
|
502
|
+
) {
|
|
503
|
+
this.id = clientIdOf(`client#${number}`);
|
|
504
|
+
this.who = principalOf("client", this.id);
|
|
505
|
+
// A line that is too long or is not JSON breaks the framing: the connection is not trusted on.
|
|
506
|
+
this.receive = lineDecoder((raw) => onMessage(this, raw), { onError: () => this.end() });
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
get caller(): ClientId {
|
|
510
|
+
return this.id;
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
get isOpen(): boolean {
|
|
514
|
+
return this.open;
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
get principal(): Principal {
|
|
518
|
+
return this.who;
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/** Does the principal come from a token? A plain client is told apart only by its connection, which a reconnect changes. */
|
|
522
|
+
get isNamed(): boolean {
|
|
523
|
+
return this.named;
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
/**
|
|
527
|
+
* Take the label the client gives itself, and the principal its token gave it; only once.
|
|
528
|
+
* Returns false when it was said before. The label is only a name: it decides nothing.
|
|
529
|
+
*/
|
|
530
|
+
greet(label: ClientId, principal: Principal | undefined): boolean {
|
|
531
|
+
if (this.greeted) return false;
|
|
532
|
+
this.greeted = true;
|
|
533
|
+
this.id = clientIdOf(`${label}#${this.number}`);
|
|
534
|
+
this.who = principal ?? principalOf("client", this.id);
|
|
535
|
+
this.named = principal !== undefined;
|
|
536
|
+
return true;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
receiveBytes(chunk: Uint8Array | string): void {
|
|
540
|
+
this.receive(chunk);
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
/** Write one frame, whole: what the socket does not take waits for the drain. */
|
|
544
|
+
send(message: HostMessage): void {
|
|
545
|
+
if (!this.open) return;
|
|
546
|
+
this.queue.push(new TextEncoder().encode(encode(message)));
|
|
547
|
+
this.flush();
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
/**
|
|
551
|
+
* Write a live frame, unless the client is already behind: a frame is not worth waiting for
|
|
552
|
+
* and must not grow the queue of a slow client without bound.
|
|
553
|
+
*/
|
|
554
|
+
sendLive(message: HostMessage): void {
|
|
555
|
+
if (this.queue.length >= MAX_LIVE_BACKLOG) return;
|
|
556
|
+
this.send(message);
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
flush(): void {
|
|
560
|
+
try {
|
|
561
|
+
for (let head = this.queue[0]; head !== undefined; head = this.queue[0]) {
|
|
562
|
+
const written = this.socket.write(head);
|
|
563
|
+
if (written <= 0) return;
|
|
564
|
+
if (written < head.length) this.queue[0] = head.subarray(written);
|
|
565
|
+
else this.queue.shift();
|
|
566
|
+
}
|
|
567
|
+
} catch {
|
|
568
|
+
this.end();
|
|
569
|
+
}
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/** The socket is gone: nothing more is written, the subscriptions stop. */
|
|
573
|
+
drop(): void {
|
|
574
|
+
this.open = false;
|
|
575
|
+
this.queue.length = 0;
|
|
576
|
+
for (const feed of this.feeds) feed.close();
|
|
577
|
+
for (const feed of this.liveFeeds) feed.close();
|
|
578
|
+
}
|
|
579
|
+
|
|
580
|
+
/** The host gives the connection up. */
|
|
581
|
+
end(): void {
|
|
582
|
+
this.drop();
|
|
583
|
+
this.socket.end();
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
|
|
587
|
+
/** The state of one invocation, as the last state record says. */
|
|
588
|
+
function latestStates(journal: Journal): Map<string, string> {
|
|
589
|
+
const states = new Map<string, string>();
|
|
590
|
+
for (const row of journal.find({ type: CORE_TYPES.invocationState })) {
|
|
591
|
+
const data = StateData.safeParse(row.data);
|
|
592
|
+
if (data.success) states.set(data.data.invocation, data.data.state);
|
|
593
|
+
}
|
|
594
|
+
return states;
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
const MoveInput = z.object({ invocation: z.string() });
|
|
598
|
+
|
|
599
|
+
/** What a cancel of steps names: the invocation, the key prefixes it gives up, the ones it spares, and why. */
|
|
600
|
+
const CancelStepsInput = z.object({
|
|
601
|
+
invocation: z.string(),
|
|
602
|
+
prefixes: z.array(z.string().min(1)).min(1),
|
|
603
|
+
except: z.array(z.string().min(1)).optional(),
|
|
604
|
+
reason: z.string().min(1),
|
|
605
|
+
});
|
|
606
|
+
|
|
607
|
+
const ResolveInput = z
|
|
608
|
+
.object({
|
|
609
|
+
invocation: z.string().optional(),
|
|
610
|
+
/** Instead of the invocation: the run whose one paused invocation it is. */
|
|
611
|
+
run: z.string().optional(),
|
|
612
|
+
choice: z.enum(["retry", "skip", "cancel"]),
|
|
613
|
+
key: z.string().optional(),
|
|
614
|
+
})
|
|
615
|
+
.refine((input) => (input.invocation === undefined) !== (input.run === undefined), "give the invocation (id, or a unique start or end of it), or the run whose paused invocation it is");
|
|
616
|
+
|
|
617
|
+
/** The longest the host waits for one service to release what it owns. */
|
|
618
|
+
const STOP_TIMEOUT_MS = 5_000;
|
|
619
|
+
|
|
620
|
+
/** The longest delay a timer takes: a longer one fires at once. */
|
|
621
|
+
const MAX_TIMER_MS = 2 ** 31 - 1;
|
|
622
|
+
|
|
623
|
+
/** What the host does about itself is the owner's: a client of another principal is refused, whatever its grant says. */
|
|
624
|
+
function requireOwner(caller: Caller, what: string): void {
|
|
625
|
+
if (caller.kind === "client" && caller.principal?.kind !== "owner") throw new DeniedError(`only the owner ${what}`);
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
/** The answer to a request to stop is sent before the host closes. */
|
|
629
|
+
const STOP_DELAY_MS = 100;
|
|
630
|
+
|
|
631
|
+
/** A stop that hangs must not hang the host: it is given up on after a bound wait. */
|
|
632
|
+
function boundedStop(stopping: Promise<void>): Promise<void> {
|
|
633
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
634
|
+
const timeout = new Promise<void>((_, reject) => {
|
|
635
|
+
timer = setTimeout(() => reject(new Error(`did not stop within ${STOP_TIMEOUT_MS} ms`)), STOP_TIMEOUT_MS);
|
|
636
|
+
});
|
|
637
|
+
return Promise.race([stopping, timeout]).finally(() => clearTimeout(timer));
|
|
638
|
+
}
|
|
639
|
+
|
|
640
|
+
class Niwa implements Host {
|
|
641
|
+
private readonly home: string;
|
|
642
|
+
private readonly plugins = new Map<PluginName, Installed>();
|
|
643
|
+
private readonly configured = new Set<PluginName>();
|
|
644
|
+
/** Every version of every handler that was installed: work in flight finishes on its own. */
|
|
645
|
+
private readonly pinned = new Map<string, Pinned>();
|
|
646
|
+
private readonly types = new Map<RecordTypeName, AnyType>();
|
|
647
|
+
/** Reads that wait for a commit: each is called when a record is committed. */
|
|
648
|
+
private readonly commitWaiters = new Set<() => void>();
|
|
649
|
+
/** The types declared as a family (`wf.*`): every name under the prefix is one of them, with the family's schema. */
|
|
650
|
+
private readonly families: AnyType[] = [];
|
|
651
|
+
/** The plugin that declares each type: the only one that writes it over the wire unless it is open. */
|
|
652
|
+
private readonly typeOwners = new Map<RecordTypeName, PluginName>();
|
|
653
|
+
/** The tokens and the grants this host made, folded from the journal; present while the host serves. */
|
|
654
|
+
private doors: Doors | undefined;
|
|
655
|
+
/** The grants and the profiles: what writes the records of access. */
|
|
656
|
+
private readonly access = new AccessControl({
|
|
657
|
+
doors: () => this.requireDoors(),
|
|
658
|
+
commit: (records) => this.append(records),
|
|
659
|
+
read: (id) => this.journal?.get(id),
|
|
660
|
+
effectOf: (name) => this.effectOf(name),
|
|
661
|
+
});
|
|
662
|
+
/** The artifacts of this host: data too large for a record, kept whole by its digest under the home. */
|
|
663
|
+
readonly artifacts: ArtifactStore = artifactStore(() => this.realHome());
|
|
664
|
+
/** The secrets of this host's owner, resolved by name where they are used. */
|
|
665
|
+
readonly secrets: SecretStore = secretStore(() => this.realHome());
|
|
666
|
+
/** The calls clients named with an operation id: a retry under one answers the first call. */
|
|
667
|
+
private readonly operations = new CallOperations({
|
|
668
|
+
get: id => this.requireJournal().get(id),
|
|
669
|
+
find: (type, operation) => this.requireJournal().find({ type, field: "operation", equals: operation }),
|
|
670
|
+
commit: (records) => {
|
|
671
|
+
this.append(records);
|
|
672
|
+
},
|
|
673
|
+
artifacts: this.artifacts,
|
|
674
|
+
});
|
|
675
|
+
/** The actions of access: the host registers them for itself. */
|
|
676
|
+
private readonly accessActionList = accessActions(this.access, () => this.requireDoors());
|
|
677
|
+
/** The types each action may write: the ones its own plugin declares. */
|
|
678
|
+
private readonly typesOf = new Map<ActionName, Set<RecordTypeName>>();
|
|
679
|
+
private readonly actions = new Map<ActionName, AnyAction>();
|
|
680
|
+
/** The intercepts of the current plugins, by the name of the action they are on. */
|
|
681
|
+
private readonly intercepts = new Map<ActionName, Intercepts>();
|
|
682
|
+
private readonly handlers = new Map<HandlerId, Served>();
|
|
683
|
+
/** Everything that watches the journal: the host's own subscriptions and the clients'. */
|
|
684
|
+
private readonly feeds = new Set<Feed>();
|
|
685
|
+
private readonly connections = new Set<Connection>();
|
|
686
|
+
/** The invocations that run; `again` says a run was asked for while it ran. */
|
|
687
|
+
private readonly running = new Map<InvocationId, { again: boolean; woken: boolean }>();
|
|
688
|
+
/** The invocations suspended on a wait, with what each of their open waits waits for. */
|
|
689
|
+
private readonly waiting = new Map<InvocationId, { slots: readonly WaitSlot[]; spec: RunSpec }>();
|
|
690
|
+
/** The invocations whose steps were cancelled while they ran: one that ends waiting runs again at once. */
|
|
691
|
+
private readonly cancelledWhileRunning = new Set<InvocationId>();
|
|
692
|
+
/**
|
|
693
|
+
* The waiting invocations by what wakes them: a wait without a key under its type, a keyed one
|
|
694
|
+
* under (type, field, value). A record looks up only the entries it can match, so it does not
|
|
695
|
+
* walk every waiter. Rebuilt by park() from the journal's wait intents, so it needs no storage.
|
|
696
|
+
*/
|
|
697
|
+
private readonly waitIndex = new Map<string, Set<InvocationId>>();
|
|
698
|
+
/** For each type, the key fields some keyed waiter uses, with how many: the fields a record checks. */
|
|
699
|
+
private readonly waitFields = new Map<RecordTypeName, Map<string, number>>();
|
|
700
|
+
/** How far each subscription has looked: read from the journal on first use. */
|
|
701
|
+
private readonly positions = new Map<HandlerId, Seq>();
|
|
702
|
+
/** How far each subscription's position is kept in the journal: by a position record or an admission. */
|
|
703
|
+
private readonly kept = new Map<HandlerId, Seq>();
|
|
704
|
+
/** The unfinished invocations of each subscription: admitted and not done, the waiting and the paused too. */
|
|
705
|
+
private readonly active = new Map<HandlerId, ActiveSubscription>();
|
|
706
|
+
/** The subscribers read from the journal at the last look: they are read again at the next. */
|
|
707
|
+
private readonly dynamic = new Set<HandlerId>();
|
|
708
|
+
/** The subscription of each unfinished invocation, to free its place when it is done. */
|
|
709
|
+
private readonly activeOf = new Map<InvocationId, { id: HandlerId; key: SubscriptionKey | undefined }>();
|
|
710
|
+
/** The state of the plugins: values by key, projected from the journal. */
|
|
711
|
+
private readonly states = new StateStore();
|
|
712
|
+
/** The functions that stop the running services, by the plugin that declared them. */
|
|
713
|
+
private readonly stoppers = new Map<PluginName, Array<() => void | Promise<void>>>();
|
|
714
|
+
/** What the services are still releasing: the host waits for it before it is gone. */
|
|
715
|
+
private readonly stopping: Array<Promise<void>> = [];
|
|
716
|
+
private readonly resolver = this.resolveAction();
|
|
717
|
+
private readonly mover = this.moveAction();
|
|
718
|
+
private readonly canceller = this.cancelStepsAction();
|
|
719
|
+
private readonly installer = pluginInstallAction({
|
|
720
|
+
check: (name) => this.checkModuleName(pluginName(name)),
|
|
721
|
+
recorded: (id) => {
|
|
722
|
+
const row = this.requireJournal().get(id);
|
|
723
|
+
return row?.type === CORE_TYPES.pluginInstalled ? PluginInstalledData.parse(row.data) : undefined;
|
|
724
|
+
},
|
|
725
|
+
install: async (caller, plugin, data, id) => {
|
|
726
|
+
const journal = this.requireJournal();
|
|
727
|
+
this.checkModuleName(plugin.name);
|
|
728
|
+
const before = installationOf(journal, data.plugin);
|
|
729
|
+
this.install(plugin, { commit: () => {
|
|
730
|
+
this.append([{ id, stream: streamId("plugin"), type: CORE_TYPES.pluginInstalled, schema: 1, data: { ...data, version: plugin.version }, actor: caller, cause: null, root: id }]);
|
|
731
|
+
} });
|
|
732
|
+
if (before !== undefined) await removeCopyIfStale(journal, before);
|
|
733
|
+
},
|
|
734
|
+
});
|
|
735
|
+
private readonly uninstaller = pluginUninstallAction(
|
|
736
|
+
() => this.requireJournal(),
|
|
737
|
+
async (caller, installation, id) => {
|
|
738
|
+
const name = pluginName(installation.plugin);
|
|
739
|
+
if (this.configured.has(name)) throw new Error(`"${name}" is configured on this host`);
|
|
740
|
+
const installed = this.plugins.get(name);
|
|
741
|
+
if (installed !== undefined) {
|
|
742
|
+
for (const [other, entry] of this.plugins) {
|
|
743
|
+
if (other === name) continue;
|
|
744
|
+
for (const point of entry.readInSetup) {
|
|
745
|
+
if (installed.offers.some(({ key }) => key.name === point)) {
|
|
746
|
+
throw new Error(`"${other}" read offers from "${name}" at "${point}" during setup`);
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
}
|
|
750
|
+
}
|
|
751
|
+
this.requireProviders(name);
|
|
752
|
+
const data = { plugin: installation.plugin, hash: installation.hash };
|
|
753
|
+
this.append([{ id, stream: streamId("plugin"), type: CORE_TYPES.pluginUninstalled, schema: 1, data, actor: caller, cause: null, root: id }]);
|
|
754
|
+
this.unload(name);
|
|
755
|
+
await removeCopyIfStale(this.requireJournal(), installation);
|
|
756
|
+
},
|
|
757
|
+
);
|
|
758
|
+
|
|
759
|
+
private checkModuleName(name: PluginName): void {
|
|
760
|
+
if (this.configured.has(name)) throw new Error(`"${name}" is configured on this host`);
|
|
761
|
+
}
|
|
762
|
+
|
|
763
|
+
/** The actions the host registers for itself: observation and the description. */
|
|
764
|
+
private readonly readers = [
|
|
765
|
+
this.recordsReadAction(),
|
|
766
|
+
this.recordsSearchAction(),
|
|
767
|
+
this.traceAction(),
|
|
768
|
+
this.causesAction(),
|
|
769
|
+
this.describeAction(),
|
|
770
|
+
this.statusAction(),
|
|
771
|
+
this.stopAction(),
|
|
772
|
+
this.catalogAction(),
|
|
773
|
+
];
|
|
774
|
+
/** The live frames: they go to the listeners of the moment and are never written down. */
|
|
775
|
+
private readonly liveBus = new LiveBus();
|
|
776
|
+
/** This host takes the journal even from a living holder. */
|
|
777
|
+
private readonly takeover: boolean;
|
|
778
|
+
/** The clock of this host: everything that reads the time or waits for it asks here. */
|
|
779
|
+
private readonly clock: Clock;
|
|
780
|
+
/** The identity of the socket file this host bound: only that file is this host's to remove. */
|
|
781
|
+
private socketFile: string | undefined;
|
|
782
|
+
private journal: Journal | undefined;
|
|
783
|
+
private server: Bun.UnixSocketListener<Connection> | undefined;
|
|
784
|
+
private serving: Promise<void> | undefined;
|
|
785
|
+
private pumpQueued = false;
|
|
786
|
+
private connectionCount = 0;
|
|
787
|
+
private closed = false;
|
|
788
|
+
|
|
789
|
+
/** What a request to stop does. */
|
|
790
|
+
private readonly onStop: () => void;
|
|
791
|
+
|
|
792
|
+
|
|
793
|
+
/** The home with its links resolved, once it exists. */
|
|
794
|
+
private realHome(): string {
|
|
795
|
+
return existsSync(this.home) ? realpathSync(this.home) : this.home;
|
|
796
|
+
}
|
|
797
|
+
|
|
798
|
+
constructor(opts: { home: string; takeover?: boolean; clock?: Clock; onStop?: () => void }) {
|
|
799
|
+
this.onStop = opts.onStop ?? (() => void this.close());
|
|
800
|
+
this.home = expandHome(opts.home);
|
|
801
|
+
this.takeover = opts.takeover === true;
|
|
802
|
+
this.clock = opts.clock ?? realClock();
|
|
803
|
+
// The actions of the host are registered before any plugin is: a host with none still has them.
|
|
804
|
+
this.rebuild();
|
|
805
|
+
}
|
|
806
|
+
|
|
807
|
+
// --- plugins ---------------------------------------------------------------
|
|
808
|
+
|
|
809
|
+
use(...plugins: Plugin[]): void {
|
|
810
|
+
for (const [index, plugin] of plugins.entries()) {
|
|
811
|
+
try {
|
|
812
|
+
this.install(plugin);
|
|
813
|
+
this.configured.add(plugin.name);
|
|
814
|
+
} catch (error) {
|
|
815
|
+
throw new PluginInstallFailed(
|
|
816
|
+
plugin.name,
|
|
817
|
+
plugins.slice(0, index).map((done) => done.name),
|
|
818
|
+
plugins.slice(index + 1).map((rest) => rest.name),
|
|
819
|
+
error,
|
|
820
|
+
);
|
|
821
|
+
}
|
|
822
|
+
}
|
|
823
|
+
}
|
|
824
|
+
|
|
825
|
+
/**
|
|
826
|
+
* The offers at a point, in the order the plugins were installed. `settingUp` is the plugin whose setup
|
|
827
|
+
* reads them: its own offers count, and its earlier version's do not.
|
|
828
|
+
*/
|
|
829
|
+
private offersAt<T>(key: OfferKey<T>, settingUp: Installed | undefined): Offered<T>[] {
|
|
830
|
+
const found: Offered<T>[] = [];
|
|
831
|
+
const add = (name: PluginName, installed: Installed): void => {
|
|
832
|
+
for (const one of installed.offers) if (one.key.name === key.name) found.push({ plugin: name, value: one.value as T });
|
|
833
|
+
};
|
|
834
|
+
for (const [name, installed] of this.plugins) {
|
|
835
|
+
if (settingUp !== undefined && name === settingUp.source.name) continue;
|
|
836
|
+
add(name, installed);
|
|
837
|
+
}
|
|
838
|
+
if (settingUp !== undefined) add(settingUp.source.name, settingUp);
|
|
839
|
+
return found;
|
|
840
|
+
}
|
|
841
|
+
|
|
842
|
+
/** The type of this name that an installed plugin declares. */
|
|
843
|
+
private declaredBefore(name: string): AnyType | undefined {
|
|
844
|
+
for (const installed of this.plugins.values()) {
|
|
845
|
+
const found = installed.types.find((type) => type.name === name);
|
|
846
|
+
if (found !== undefined) return found;
|
|
847
|
+
}
|
|
848
|
+
return undefined;
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
/**
|
|
852
|
+
* Install a plugin, or replace the one of its name.
|
|
853
|
+
*
|
|
854
|
+
* The plugin is staged first: its setup runs against a copy of what it may change in the host
|
|
855
|
+
* besides its own registrations (the profiles and the keys of state it declares). Only a setup
|
|
856
|
+
* that ran to its end is swapped in. Any other outcome puts the shared things back and leaves the
|
|
857
|
+
* installed plugin as it was.
|
|
858
|
+
*/
|
|
859
|
+
private install(plugin: Plugin, options: { restoringVersion?: string; commit?: () => void } = {}): void {
|
|
860
|
+
const profiles = this.access.declaredProfiles();
|
|
861
|
+
const keys = this.states.declared();
|
|
862
|
+
// Set when the install is refused: the api of the plugin then changes nothing in the host.
|
|
863
|
+
let refused = false;
|
|
864
|
+
const live = (): void => {
|
|
865
|
+
if (refused) throw new Error(`plugin "${plugin.name}" was not installed: its api changes nothing any more`);
|
|
866
|
+
};
|
|
867
|
+
try {
|
|
868
|
+
this.stage(plugin, live, options);
|
|
869
|
+
} catch (error) {
|
|
870
|
+
refused = true;
|
|
871
|
+
this.access.restoreProfiles(profiles);
|
|
872
|
+
this.states.restore(keys);
|
|
873
|
+
throw error;
|
|
874
|
+
}
|
|
875
|
+
}
|
|
876
|
+
|
|
877
|
+
private stage(plugin: Plugin, live: () => void, options: { restoringVersion?: string; commit?: () => void }): void {
|
|
878
|
+
const sources: string[] = [];
|
|
879
|
+
const installed: Installed = {
|
|
880
|
+
source: plugin,
|
|
881
|
+
version: plugin.version,
|
|
882
|
+
types: [],
|
|
883
|
+
actions: [],
|
|
884
|
+
handlers: [],
|
|
885
|
+
intercepts: new Map(),
|
|
886
|
+
services: [],
|
|
887
|
+
profiles: new Set(),
|
|
888
|
+
catalogs: [],
|
|
889
|
+
subscribers: [],
|
|
890
|
+
offers: [],
|
|
891
|
+
readInSetup: new Set(),
|
|
892
|
+
needs: { actions: new Set(), types: new Set() },
|
|
893
|
+
};
|
|
894
|
+
let inSetup = true;
|
|
895
|
+
const offer = <T>(key: OfferKey<T>, value: T): void => {
|
|
896
|
+
// A plugin that read the point when it was installed would never see this offer: it is refused, not lost. A
|
|
897
|
+
// new version of a plugin installed before the reader keeps its place, and its offers are read as it is.
|
|
898
|
+
for (const [name, other] of this.plugins) {
|
|
899
|
+
if (name === plugin.name) break;
|
|
900
|
+
if (other.readInSetup.has(key.name)) {
|
|
901
|
+
throw new TypeError(`plugin "${plugin.name}" offers "${key.name}", which "${name}" read when it was installed: install "${plugin.name}" before "${name}"`);
|
|
902
|
+
}
|
|
903
|
+
}
|
|
904
|
+
installed.offers.push({ key, value });
|
|
905
|
+
};
|
|
906
|
+
const returned: unknown = plugin.setup({
|
|
907
|
+
declare: (...types: AnyType[]) => {
|
|
908
|
+
// A trigger is a view of a type, not a type: declaring one would replace the type it narrows.
|
|
909
|
+
for (const type of types as ReadonlyArray<Subscribable<any>>) {
|
|
910
|
+
if (isTrigger(type)) {
|
|
911
|
+
throw new TypeError(`"${type.name}" is a trigger: declare the type it narrows, "${type.type.name}", not the trigger`);
|
|
912
|
+
}
|
|
913
|
+
}
|
|
914
|
+
installed.types.push(...types);
|
|
915
|
+
},
|
|
916
|
+
offer: <T>(key: OfferKey<T>, value: T) => offer(key, value),
|
|
917
|
+
offers: <T>(key: OfferKey<T>): Offered<T>[] => {
|
|
918
|
+
if (inSetup) installed.readInSetup.add(key.name);
|
|
919
|
+
return this.offersAt(key, inSetup ? installed : undefined);
|
|
920
|
+
},
|
|
921
|
+
service: (start: Service) => {
|
|
922
|
+
installed.services.push(start);
|
|
923
|
+
},
|
|
924
|
+
action: (a: AnyAction) => {
|
|
925
|
+
installed.actions.push(a);
|
|
926
|
+
},
|
|
927
|
+
catalog: (read: () => readonly AnyAction[]) => {
|
|
928
|
+
installed.catalogs.push(read);
|
|
929
|
+
},
|
|
930
|
+
subscribers: (read: () => readonly Subscriber[]) => {
|
|
931
|
+
installed.subscribers.push(read);
|
|
932
|
+
},
|
|
933
|
+
adjust: (target: ActionRef<any, any>, fn: AdjustFn<any>) => {
|
|
934
|
+
const set = installed.intercepts.get(target.name) ?? newIntercepts();
|
|
935
|
+
set.adjusts.push(fn);
|
|
936
|
+
installed.intercepts.set(target.name, set);
|
|
937
|
+
},
|
|
938
|
+
guard: (target: ActionRef<any, any>, fn: GuardFn<any>) => {
|
|
939
|
+
const set = installed.intercepts.get(target.name) ?? newIntercepts();
|
|
940
|
+
set.guards.push(fn);
|
|
941
|
+
installed.intercepts.set(target.name, set);
|
|
942
|
+
},
|
|
943
|
+
live: (channel: string, frame: LiveFrame) => {
|
|
944
|
+
this.liveBus.send(channelName(channel), frameFor(channel, frame));
|
|
945
|
+
},
|
|
946
|
+
on: (
|
|
947
|
+
source: Subscribable<any>,
|
|
948
|
+
optsOrHandler: HandlerOptions<any> | Handler<any>,
|
|
949
|
+
maybeHandler?: Handler<any>,
|
|
950
|
+
) => {
|
|
951
|
+
const type = isTrigger(source) ? source.type : source;
|
|
952
|
+
const [options, handler]: [HandlerOptions<any>, Handler<any> | undefined] =
|
|
953
|
+
typeof optsOrHandler === "function"
|
|
954
|
+
? [{}, optsOrHandler]
|
|
955
|
+
: [optsOrHandler, maybeHandler];
|
|
956
|
+
if (handler === undefined) throw new TypeError(`a handler of "${type.name}" is missing`);
|
|
957
|
+
// A trigger names its handlers after what it watches, so two triggers of the same type are two
|
|
958
|
+
// different handlers.
|
|
959
|
+
const name = options.id ?? source.name;
|
|
960
|
+
if (name.includes("/")) {
|
|
961
|
+
throw new TypeError(
|
|
962
|
+
`plugin "${plugin.name}" names a handler "${name}": a handler id is the name of the plugin, a "/" and the handler's own name, so the name has none`,
|
|
963
|
+
);
|
|
964
|
+
}
|
|
965
|
+
// The journal holds the handler id, not the function: two with one id could not be told apart.
|
|
966
|
+
if (installed.handlers.some((entry) => entry.name === name)) {
|
|
967
|
+
throw new Error(
|
|
968
|
+
`plugin "${plugin.name}" declares two handlers with the id "${name}": a handler id must name one handler`,
|
|
969
|
+
);
|
|
970
|
+
}
|
|
971
|
+
const filter = isTrigger(source)
|
|
972
|
+
? combinedFilter(`plugin "${plugin.name}", handler "${name}"`, source, options.filter)
|
|
973
|
+
: options.filter;
|
|
974
|
+
const subscribing = subscribingOf(`plugin "${plugin.name}", handler "${name}"`, { ...options, filter });
|
|
975
|
+
// What a trigger needs offered for its records to be written at all, the subscribing plugin offers.
|
|
976
|
+
if (isTrigger(source) && source.offer !== undefined) offer(source.offer.key, source.offer.value);
|
|
977
|
+
installed.handlers.push({
|
|
978
|
+
name,
|
|
979
|
+
type,
|
|
980
|
+
handler,
|
|
981
|
+
requires: options.requires ?? [],
|
|
982
|
+
subscribing,
|
|
983
|
+
...(isTrigger(source) ? { trigger: { provider: source.provider } } : {}),
|
|
984
|
+
});
|
|
985
|
+
sources.push(handlerSource(name, handler));
|
|
986
|
+
},
|
|
987
|
+
// The reader is a function: the journal opens when the host starts serving, which is
|
|
988
|
+
// after the plugin is installed. A plugin asks for it when it needs it, and gets
|
|
989
|
+
// undefined before the journal is open.
|
|
990
|
+
journal: () => this.journal,
|
|
991
|
+
summarize: (read) => {
|
|
992
|
+
installed.summary = read;
|
|
993
|
+
},
|
|
994
|
+
needs: (needs: PluginNeeds) => {
|
|
995
|
+
for (const action of needs.actions ?? []) installed.needs.actions.add(typeof action === "string" ? action : action.name);
|
|
996
|
+
for (const type of needs.types ?? []) installed.needs.types.add(typeof type === "string" ? type : type.name);
|
|
997
|
+
},
|
|
998
|
+
recordType: (name) => installed.types.find((type) => type.name === name) ?? this.declaredBefore(name),
|
|
999
|
+
untilCommit: (ms) => this.untilCommit(ms),
|
|
1000
|
+
socket: () => socketPath(realpathSync(this.home)),
|
|
1001
|
+
home: () => realpathSync(this.home),
|
|
1002
|
+
artifacts: this.artifacts,
|
|
1003
|
+
secrets: this.secrets,
|
|
1004
|
+
emit: async <T>(type: RecordType<T>, data: T, opts?: EmitOptions): Promise<StoredRecord> => {
|
|
1005
|
+
if (this.plugins.get(plugin.name) !== installed || !installed.types.some((own) => own.name === type.name)) {
|
|
1006
|
+
throw new UnknownType(type.name);
|
|
1007
|
+
}
|
|
1008
|
+
return this.write({ kind: "host" }, type.name, data, opts);
|
|
1009
|
+
},
|
|
1010
|
+
emitAll: async entries => {
|
|
1011
|
+
if (this.plugins.get(plugin.name) !== installed) throw new Error(`plugin "${plugin.name}" is not installed`);
|
|
1012
|
+
return this.writeOwned(installed.types, entries);
|
|
1013
|
+
},
|
|
1014
|
+
state: <T>(name: string, schema: z.ZodType<T>, initial: T): StateHandle<T> => {
|
|
1015
|
+
live();
|
|
1016
|
+
return this.states.define(plugin.name, name, schema, initial);
|
|
1017
|
+
},
|
|
1018
|
+
// A plugin starts sessions and runs; the owner and the plugins are the host's to make.
|
|
1019
|
+
issueToken: (kind, id, opts) => {
|
|
1020
|
+
if (kind !== "session" && kind !== "run") throw new TypeError(`a plugin makes no token for "${String(kind)}"`);
|
|
1021
|
+
return this.issue(principalOf(kind, id), opts);
|
|
1022
|
+
},
|
|
1023
|
+
narrow: (caller, requested) => this.access.narrowFor(caller, requested),
|
|
1024
|
+
rights: (caller) => this.access.rightsOf(caller),
|
|
1025
|
+
effectOf: (name) => this.effectOf(name),
|
|
1026
|
+
profile: (name, rules) => {
|
|
1027
|
+
live();
|
|
1028
|
+
installed.profiles.add(name);
|
|
1029
|
+
this.access.declareProfile(name, rules);
|
|
1030
|
+
},
|
|
1031
|
+
asker: (ask) => {
|
|
1032
|
+
installed.asker = ask;
|
|
1033
|
+
},
|
|
1034
|
+
setProfile: (name, rules, by) => {
|
|
1035
|
+
if (!installed.profiles.has(name)) {
|
|
1036
|
+
throw new TypeError(`plugin "${plugin.name}" did not declare the profile "${name}": it sets only its own`);
|
|
1037
|
+
}
|
|
1038
|
+
return this.access.setProfile(by, name, rules);
|
|
1039
|
+
},
|
|
1040
|
+
authorize: (caller, verb, name, how) => this.authorize(caller, verb, name, how),
|
|
1041
|
+
});
|
|
1042
|
+
|
|
1043
|
+
inSetup = false;
|
|
1044
|
+
if (isThenable(returned)) {
|
|
1045
|
+
// What the promise does later is nobody's to see: it must not fail the process on its own.
|
|
1046
|
+
Promise.resolve(returned).catch(() => undefined);
|
|
1047
|
+
throw new TypeError(
|
|
1048
|
+
`plugin "${plugin.name}" has an asynchronous setup: a setup runs to its end before the plugin is installed, so it must not return a promise`,
|
|
1049
|
+
);
|
|
1050
|
+
}
|
|
1051
|
+
// The version of a plugin without an explicit one covers the handlers it registered, wherever
|
|
1052
|
+
// they are defined: the setup has run, so they are known now.
|
|
1053
|
+
for (const {name, guard} of installed.types) {
|
|
1054
|
+
if (guard) sources.push(JSON.stringify([name, guard.group, ...[guard.key, guard.initial, guard.admit, guard.fold].map(String)]));
|
|
1055
|
+
}
|
|
1056
|
+
sealVersion(plugin, sources);
|
|
1057
|
+
installed.version = plugin.version;
|
|
1058
|
+
if (options.restoringVersion !== undefined && installed.version !== options.restoringVersion) {
|
|
1059
|
+
throw new Error(`the restored version of "${plugin.name}" differs from its recorded version`);
|
|
1060
|
+
}
|
|
1061
|
+
// A plugin that read a point when it was installed keeps what it read: a replacement of the plugin that
|
|
1062
|
+
// offered there that offers something else is refused, because the reader would go on with the old.
|
|
1063
|
+
const replaced = this.plugins.get(plugin.name);
|
|
1064
|
+
if (replaced !== undefined) {
|
|
1065
|
+
for (const [name, other] of this.plugins) {
|
|
1066
|
+
if (name === plugin.name) continue;
|
|
1067
|
+
for (const point of other.readInSetup) {
|
|
1068
|
+
if (offeredAt(replaced, point) !== offeredAt(installed, point)) {
|
|
1069
|
+
throw new TypeError(
|
|
1070
|
+
`plugin "${plugin.name}" changes what it offers at "${point}", which "${name}" read when it was installed: unload "${name}" first and install it again after this one`,
|
|
1071
|
+
);
|
|
1072
|
+
}
|
|
1073
|
+
}
|
|
1074
|
+
}
|
|
1075
|
+
}
|
|
1076
|
+
// The owner of a record type is one plugin: two would each be refused the other's writes, and a
|
|
1077
|
+
// name under another plugin's family would have two schemas.
|
|
1078
|
+
for (const [name, other] of this.plugins) {
|
|
1079
|
+
if (name === plugin.name) continue;
|
|
1080
|
+
for (const type of installed.types) {
|
|
1081
|
+
const taken = other.types.find((theirs) => overlaps(theirs.name, type.name));
|
|
1082
|
+
if (type.guard && other.types.some(theirs => theirs.guard?.group === type.guard!.group)) {
|
|
1083
|
+
throw new TypeError(`guard group "${type.guard.group}" is owned by plugin "${name}"`);
|
|
1084
|
+
}
|
|
1085
|
+
if (taken !== undefined) {
|
|
1086
|
+
throw new TypeError(
|
|
1087
|
+
`plugin "${plugin.name}" declares "${type.name}", which "${name}" owns as "${taken.name}": a record type has one owner`,
|
|
1088
|
+
);
|
|
1089
|
+
}
|
|
1090
|
+
}
|
|
1091
|
+
}
|
|
1092
|
+
for (const type of installed.types) {
|
|
1093
|
+
if (type.guard && [...CORE_TYPE_NAMES].some(core => overlaps(type.name, core))) {
|
|
1094
|
+
throw new TypeError(`plugin "${plugin.name}" cannot guard core records with "${type.name}"`);
|
|
1095
|
+
}
|
|
1096
|
+
}
|
|
1097
|
+
// A plugin that replaces another takes its services over: the old ones stop, the new ones
|
|
1098
|
+
// start when the host is already serving.
|
|
1099
|
+
this.plugins.set(plugin.name, installed);
|
|
1100
|
+
let guardIndexChanged = false;
|
|
1101
|
+
try {
|
|
1102
|
+
if (options.commit !== undefined) this.requireProviders();
|
|
1103
|
+
this.prepareGuards(plugin.name, installed.types);
|
|
1104
|
+
guardIndexChanged = true;
|
|
1105
|
+
options.commit?.();
|
|
1106
|
+
} catch (error) {
|
|
1107
|
+
if (replaced === undefined) this.plugins.delete(plugin.name);
|
|
1108
|
+
else this.plugins.set(plugin.name, replaced);
|
|
1109
|
+
if (guardIndexChanged) this.prepareGuards(plugin.name, replaced?.types ?? []);
|
|
1110
|
+
throw error;
|
|
1111
|
+
}
|
|
1112
|
+
// Earlier versions stay pinned: they were pinned when they were installed.
|
|
1113
|
+
for (const entry of installed.handlers) {
|
|
1114
|
+
this.pinned.set(pinKey(handlerIdOf(`${plugin.name}/${entry.name}`), plugin.version), {
|
|
1115
|
+
handler: entry.handler,
|
|
1116
|
+
type: entry.type,
|
|
1117
|
+
});
|
|
1118
|
+
}
|
|
1119
|
+
if (options.restoringVersion !== undefined) return;
|
|
1120
|
+
this.stopServicesOf(plugin.name);
|
|
1121
|
+
this.rebuild();
|
|
1122
|
+
if (this.journal !== undefined) this.startServicesOf(plugin.name);
|
|
1123
|
+
}
|
|
1124
|
+
|
|
1125
|
+
/** A replacement whose fold cannot replay history leaves the previous plugin serving. */
|
|
1126
|
+
private prepareGuards(owner: PluginName, next: readonly AnyType[]): void {
|
|
1127
|
+
if (!this.journal) return;
|
|
1128
|
+
const others = [...this.plugins].flatMap(([name, plugin]) => name === owner ? [] : plugin.types);
|
|
1129
|
+
this.journal.setGuards([...others, ...next]);
|
|
1130
|
+
}
|
|
1131
|
+
|
|
1132
|
+
installed(name: PluginName): Plugin | undefined {
|
|
1133
|
+
return this.plugins.get(name)?.source;
|
|
1134
|
+
}
|
|
1135
|
+
|
|
1136
|
+
unload(name: PluginName): void {
|
|
1137
|
+
this.prepareGuards(name, []);
|
|
1138
|
+
this.stopServicesOf(name);
|
|
1139
|
+
this.plugins.delete(name);
|
|
1140
|
+
this.rebuild();
|
|
1141
|
+
}
|
|
1142
|
+
|
|
1143
|
+
/**
|
|
1144
|
+
* Start the services of the plugins that are installed.
|
|
1145
|
+
*
|
|
1146
|
+
* A service runs while the host serves and stops when it does not. It is started after the
|
|
1147
|
+
* journal is open, so what it writes lands in the journal of this host.
|
|
1148
|
+
*/
|
|
1149
|
+
private startServices(): void {
|
|
1150
|
+
for (const name of this.plugins.keys()) this.startServicesOf(name);
|
|
1151
|
+
}
|
|
1152
|
+
|
|
1153
|
+
/** Start the services of one installed plugin. */
|
|
1154
|
+
private startServicesOf(name: PluginName): void {
|
|
1155
|
+
for (const start of this.plugins.get(name)?.services ?? []) {
|
|
1156
|
+
const run = { stopped: false };
|
|
1157
|
+
try {
|
|
1158
|
+
const stop = start(this.serviceContext(name, run));
|
|
1159
|
+
this.stoppers.set(name, [
|
|
1160
|
+
...(this.stoppers.get(name) ?? []),
|
|
1161
|
+
() => {
|
|
1162
|
+
run.stopped = true;
|
|
1163
|
+
return stop();
|
|
1164
|
+
},
|
|
1165
|
+
]);
|
|
1166
|
+
} catch (error) {
|
|
1167
|
+
run.stopped = true;
|
|
1168
|
+
this.fail(`starting the service of "${name}"`, error);
|
|
1169
|
+
}
|
|
1170
|
+
}
|
|
1171
|
+
}
|
|
1172
|
+
|
|
1173
|
+
/** Stop the services of one plugin: they do not outlive the plugin that declared them. */
|
|
1174
|
+
private stopServicesOf(name: PluginName): void {
|
|
1175
|
+
const stoppers = this.stoppers.get(name);
|
|
1176
|
+
if (stoppers === undefined) return;
|
|
1177
|
+
this.stoppers.delete(name);
|
|
1178
|
+
for (const stop of stoppers) {
|
|
1179
|
+
try {
|
|
1180
|
+
const stopping = stop();
|
|
1181
|
+
if (stopping instanceof Promise) {
|
|
1182
|
+
// A service that owns something releases it asynchronously: the host waits for it, so
|
|
1183
|
+
// what the service owns is gone before the host is gone.
|
|
1184
|
+
this.stopping.push(
|
|
1185
|
+
boundedStop(stopping).catch((error: unknown) => {
|
|
1186
|
+
this.fail(`stopping the service of "${name}"`, error);
|
|
1187
|
+
}),
|
|
1188
|
+
);
|
|
1189
|
+
}
|
|
1190
|
+
} catch (error) {
|
|
1191
|
+
this.fail(`stopping the service of "${name}"`, error);
|
|
1192
|
+
}
|
|
1193
|
+
}
|
|
1194
|
+
}
|
|
1195
|
+
|
|
1196
|
+
/** What a service of one plugin is given: it writes only what that plugin declared. */
|
|
1197
|
+
private serviceContext(name: PluginName, run: { stopped: boolean }): ServiceContext {
|
|
1198
|
+
const installed = this.plugins.get(name);
|
|
1199
|
+
const own = installed?.types ?? [];
|
|
1200
|
+
return {
|
|
1201
|
+
emit: async <T>(type: RecordType<T>, data: T, opts?: EmitOptions): Promise<StoredRecord> => {
|
|
1202
|
+
if (run.stopped) throw new Error(`the service of "${name}" has stopped: it writes nothing more`);
|
|
1203
|
+
if (!own.some((declared) => declared.name === type.name)) {
|
|
1204
|
+
throw new UnknownType(type.name);
|
|
1205
|
+
}
|
|
1206
|
+
return this.write({ kind: "host" }, type.name, data, opts);
|
|
1207
|
+
},
|
|
1208
|
+
emitAll: async entries => {
|
|
1209
|
+
if (run.stopped) throw new Error(`the service of "${name}" has stopped`);
|
|
1210
|
+
return this.writeOwned(own, entries);
|
|
1211
|
+
},
|
|
1212
|
+
now: (): Timestamp => timestamp(this.clock.now()),
|
|
1213
|
+
schedule: (at, fn) => this.clock.schedule(at, fn),
|
|
1214
|
+
};
|
|
1215
|
+
}
|
|
1216
|
+
|
|
1217
|
+
/**
|
|
1218
|
+
* The action the host registers for itself: read the records of the journal.
|
|
1219
|
+
*
|
|
1220
|
+
* The read is one-shot: it answers with the records that are committed now and ends. It reads
|
|
1221
|
+
* the history and never waits for more, so a caller knows when the answer is the whole thing.
|
|
1222
|
+
*/
|
|
1223
|
+
private recordsReadAction(): AnyAction {
|
|
1224
|
+
return action(RECORDS_READ_ACTION, {
|
|
1225
|
+
description:
|
|
1226
|
+
"The records of the journal after a position that answer a record query: types as exact names or prefix.* families, equality on paths of the data, a stream. In commit order, up to the ones committed now.",
|
|
1227
|
+
input: RecordsReadInput,
|
|
1228
|
+
output: RecordsOutput,
|
|
1229
|
+
// A read writes nothing: it may be made again.
|
|
1230
|
+
recovery: "repeat",
|
|
1231
|
+
effect: "read",
|
|
1232
|
+
world: "niwa",
|
|
1233
|
+
run: async (input: z.infer<typeof RecordsReadInput>) =>
|
|
1234
|
+
this.untilFound(input.waitMs, () => this.readQuery(input)),
|
|
1235
|
+
});
|
|
1236
|
+
}
|
|
1237
|
+
|
|
1238
|
+
/**
|
|
1239
|
+
* The action the host registers for itself: search the records as a person looks for them — by
|
|
1240
|
+
* who wrote them, what they are about, a text, a span of time. It is not a record query: what it
|
|
1241
|
+
* finds may depend on the journal around a record (a run is all it grew into).
|
|
1242
|
+
*/
|
|
1243
|
+
private recordsSearchAction(): AnyAction {
|
|
1244
|
+
return action(RECORDS_SEARCH_ACTION, {
|
|
1245
|
+
description:
|
|
1246
|
+
"Search the records of the journal after a position: type patterns, an actor, a run, session, request or task, a text in the data, a span of time or of positions.",
|
|
1247
|
+
input: RecordsSearchInput,
|
|
1248
|
+
output: RecordsOutput,
|
|
1249
|
+
recovery: "repeat",
|
|
1250
|
+
effect: "read",
|
|
1251
|
+
world: "niwa",
|
|
1252
|
+
run: async (input: z.infer<typeof RecordsSearchInput>) =>
|
|
1253
|
+
this.untilFound(input.waitMs, () =>
|
|
1254
|
+
readFiltered(this.requireJournal(), seq(input.from ?? 0), input.filter ?? {}, {
|
|
1255
|
+
...(input.limit === undefined ? {} : { limit: input.limit }),
|
|
1256
|
+
...(input.tail === undefined ? {} : { tail: input.tail }),
|
|
1257
|
+
...(input.stream === undefined ? {} : { stream: streamId(input.stream) }),
|
|
1258
|
+
}),
|
|
1259
|
+
),
|
|
1260
|
+
});
|
|
1261
|
+
}
|
|
1262
|
+
|
|
1263
|
+
/** Read until something is found or the time is over: a read with nothing waits for a commit and looks again. */
|
|
1264
|
+
private async untilFound(waitMs: number | undefined, read: () => Found): Promise<Found> {
|
|
1265
|
+
const deadline = Date.now() + (waitMs ?? 0);
|
|
1266
|
+
for (;;) {
|
|
1267
|
+
const found = read();
|
|
1268
|
+
const left = deadline - Date.now();
|
|
1269
|
+
if (found.records.length > 0 || left <= 0) return found;
|
|
1270
|
+
// The wait is registered in the step that looked, so a record committed in between is not missed.
|
|
1271
|
+
await this.untilCommit(left);
|
|
1272
|
+
}
|
|
1273
|
+
}
|
|
1274
|
+
|
|
1275
|
+
/** What a read asks for, answered: the records that answer its query now, and where the next read goes on. */
|
|
1276
|
+
private readQuery(input: z.infer<typeof RecordsReadInput>): Found {
|
|
1277
|
+
const journal = this.requireJournal();
|
|
1278
|
+
const from = seq(input.from ?? 0);
|
|
1279
|
+
const query = resolveQuery({
|
|
1280
|
+
from,
|
|
1281
|
+
...(input.types === undefined ? {} : { types: input.types }),
|
|
1282
|
+
...(input.filter === undefined ? {} : { filter: input.filter }),
|
|
1283
|
+
...(input.stream === undefined ? {} : { stream: input.stream }),
|
|
1284
|
+
});
|
|
1285
|
+
const end = journal.last();
|
|
1286
|
+
if (input.tail !== undefined) {
|
|
1287
|
+
return { records: journal.tail(query, input.tail), next: seq(Math.max(end, from)) };
|
|
1288
|
+
}
|
|
1289
|
+
const records = journal.query(query, input.limit);
|
|
1290
|
+
const full = input.limit !== undefined && records.length === input.limit;
|
|
1291
|
+
return { records, next: full ? seq(records[records.length - 1]?.seq ?? from) : seq(Math.max(end, from)) };
|
|
1292
|
+
}
|
|
1293
|
+
|
|
1294
|
+
/** Wait until a record is committed, or the time is over. */
|
|
1295
|
+
private untilCommit(ms: number): Promise<void> {
|
|
1296
|
+
return new Promise((resolve) => {
|
|
1297
|
+
const done = (): void => {
|
|
1298
|
+
clearTimeout(timer);
|
|
1299
|
+
this.commitWaiters.delete(done);
|
|
1300
|
+
resolve();
|
|
1301
|
+
};
|
|
1302
|
+
// A timer longer than the runtime's limit fires at once, and a wait would then spin.
|
|
1303
|
+
const timer = setTimeout(done, Math.min(ms, MAX_TIMER_MS));
|
|
1304
|
+
this.commitWaiters.add(done);
|
|
1305
|
+
});
|
|
1306
|
+
}
|
|
1307
|
+
|
|
1308
|
+
/**
|
|
1309
|
+
* The action the host registers for itself: everything that grew from a record.
|
|
1310
|
+
*
|
|
1311
|
+
* The walk goes down, through causes and links, depth-first, each record once.
|
|
1312
|
+
*/
|
|
1313
|
+
private traceAction(): AnyAction {
|
|
1314
|
+
return action(TRACE_ACTION, {
|
|
1315
|
+
description:
|
|
1316
|
+
"Everything that grew from a record, depth-first, each record once, with its depth.",
|
|
1317
|
+
input: RecordWalkInput,
|
|
1318
|
+
output: TracedRecordsOutput,
|
|
1319
|
+
// A walk reads the records and writes nothing: it may be made again.
|
|
1320
|
+
recovery: "repeat",
|
|
1321
|
+
effect: "read",
|
|
1322
|
+
world: "niwa",
|
|
1323
|
+
run: async (input: z.infer<typeof RecordWalkInput>) =>
|
|
1324
|
+
trace(this.requireJournal(), recordId(input.id)),
|
|
1325
|
+
});
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1328
|
+
/**
|
|
1329
|
+
* The action the host registers for itself: what a record depends on.
|
|
1330
|
+
*
|
|
1331
|
+
* The walk goes up, through the cause and the links of the record.
|
|
1332
|
+
*/
|
|
1333
|
+
private causesAction(): AnyAction {
|
|
1334
|
+
return action(CAUSES_ACTION, {
|
|
1335
|
+
description: "What a record depends on: up through its cause and its links.",
|
|
1336
|
+
input: RecordWalkInput,
|
|
1337
|
+
output: RecordList,
|
|
1338
|
+
// A walk reads the records and writes nothing: it may be made again.
|
|
1339
|
+
recovery: "repeat",
|
|
1340
|
+
effect: "read",
|
|
1341
|
+
world: "niwa",
|
|
1342
|
+
run: async (input: z.infer<typeof RecordWalkInput>) =>
|
|
1343
|
+
causes(this.requireJournal(), recordId(input.id)),
|
|
1344
|
+
});
|
|
1345
|
+
}
|
|
1346
|
+
|
|
1347
|
+
/**
|
|
1348
|
+
* The action the host registers for itself: say what niwa is.
|
|
1349
|
+
*
|
|
1350
|
+
* The description is the list of the actions and the record types, with their schemas. It is
|
|
1351
|
+
* an action like any other, so a surface that lists what it may do reads it from here.
|
|
1352
|
+
*/
|
|
1353
|
+
private describeAction(): AnyAction {
|
|
1354
|
+
return action(DESCRIBE_ACTION, {
|
|
1355
|
+
description: "What niwa is: its actions and its record types, with their schemas.",
|
|
1356
|
+
input: z.object({}),
|
|
1357
|
+
output: DescriptionOutput,
|
|
1358
|
+
// A description reads the registrations and writes nothing: it may be made again.
|
|
1359
|
+
recovery: "repeat",
|
|
1360
|
+
effect: "read",
|
|
1361
|
+
world: "niwa",
|
|
1362
|
+
run: async () => this.describe(),
|
|
1363
|
+
});
|
|
1364
|
+
}
|
|
1365
|
+
|
|
1366
|
+
/** The one paused invocation of a run: the ones whose waking record names the run (a unique start of its id is enough). */
|
|
1367
|
+
private pausedOfRun(journal: Journal, run: string, pausedIds: readonly string[]): string {
|
|
1368
|
+
const of = pausedIds.filter((id) => {
|
|
1369
|
+
const admitted = journal.get(recordId(id));
|
|
1370
|
+
const data = admitted === undefined ? undefined : AdmittedData.safeParse(admitted.data);
|
|
1371
|
+
const woken = data?.success === true ? journal.get(recordId(data.data.record)) : undefined;
|
|
1372
|
+
const named = (woken?.data as { run?: unknown } | undefined)?.run;
|
|
1373
|
+
return typeof named === "string" && named.startsWith(run);
|
|
1374
|
+
});
|
|
1375
|
+
const [only, ...more] = of;
|
|
1376
|
+
if (only === undefined) throw new Error(`the run "${run}" has no paused invocation`);
|
|
1377
|
+
if (more.length > 0) throw new Error(`the run "${run}" has ${String(of.length)} paused invocations: ${of.join(", ")}: name one`);
|
|
1378
|
+
return only;
|
|
1379
|
+
}
|
|
1380
|
+
|
|
1381
|
+
/** The action that says whether the host is up and what it holds. */
|
|
1382
|
+
private statusAction(): AnyAction {
|
|
1383
|
+
return action(STATUS_ACTION, {
|
|
1384
|
+
description: "Whether the host is up: its process, its home, the position of its journal, and what each plugin holds (runs by state, open requests, live sessions).",
|
|
1385
|
+
input: z.object({}),
|
|
1386
|
+
output: StatusOutput,
|
|
1387
|
+
// It reads and writes nothing: it may be made again.
|
|
1388
|
+
recovery: "repeat",
|
|
1389
|
+
effect: "read",
|
|
1390
|
+
world: "niwa",
|
|
1391
|
+
run: (_input, ctx) => {
|
|
1392
|
+
requireOwner(ctx.caller, "sees the status of the host");
|
|
1393
|
+
return {
|
|
1394
|
+
pid: process.pid,
|
|
1395
|
+
home: this.home,
|
|
1396
|
+
seq: this.requireJournal().last(),
|
|
1397
|
+
plugins: [...this.plugins].map(([name, installed]) => ({
|
|
1398
|
+
name,
|
|
1399
|
+
version: installed.version,
|
|
1400
|
+
...(installed.summary === undefined ? {} : { summary: installed.summary() }),
|
|
1401
|
+
})),
|
|
1402
|
+
};
|
|
1403
|
+
},
|
|
1404
|
+
});
|
|
1405
|
+
}
|
|
1406
|
+
|
|
1407
|
+
/** The action that lists the cockpit modules the plugins offer, with the hash of each one's code. */
|
|
1408
|
+
private catalogAction(): AnyAction {
|
|
1409
|
+
return action(CATALOG_ACTION, {
|
|
1410
|
+
description: "The client modules the installed plugins offer to the cockpit: the id, the plugin and its version, the entry file and the hash of the module's code.",
|
|
1411
|
+
input: z.object({}),
|
|
1412
|
+
output: CatalogOutput,
|
|
1413
|
+
// It reads files and writes nothing: it may be made again.
|
|
1414
|
+
recovery: "repeat",
|
|
1415
|
+
effect: "read",
|
|
1416
|
+
world: "niwa",
|
|
1417
|
+
run: () => catalogOf(this.offersAt(COCKPIT_MODULE, undefined), (plugin) => this.plugins.get(pluginName(plugin))?.version ?? ""),
|
|
1418
|
+
});
|
|
1419
|
+
}
|
|
1420
|
+
|
|
1421
|
+
/** The action that stops the host: it answers first, and the host closes after. */
|
|
1422
|
+
private stopAction(): AnyAction {
|
|
1423
|
+
return action(STOP_ACTION, {
|
|
1424
|
+
description: "Stop the host gracefully: the work in flight stays in the journal and goes on when the host is served again.",
|
|
1425
|
+
input: z.object({}),
|
|
1426
|
+
output: z.object({ stopping: z.literal(true) }),
|
|
1427
|
+
// A stop that was cut off is not made again: it would stop the host that took its place.
|
|
1428
|
+
recovery: "do-not-repeat",
|
|
1429
|
+
effect: "write",
|
|
1430
|
+
world: "local",
|
|
1431
|
+
run: (_input, ctx) => {
|
|
1432
|
+
requireOwner(ctx.caller, "stops the host");
|
|
1433
|
+
setTimeout(this.onStop, STOP_DELAY_MS);
|
|
1434
|
+
return { stopping: true as const };
|
|
1435
|
+
},
|
|
1436
|
+
});
|
|
1437
|
+
}
|
|
1438
|
+
|
|
1439
|
+
/** The declared type of a name: the type itself, or the family whose prefix the name is under. */
|
|
1440
|
+
private declaredType(name: RecordTypeName): AnyType | undefined {
|
|
1441
|
+
return this.types.get(name) ?? this.families.find((family) => name.startsWith(family.name.slice(0, -1)));
|
|
1442
|
+
}
|
|
1443
|
+
|
|
1444
|
+
/** The action of a name: a declared one, or one a plugin's catalog reads from the journal now. */
|
|
1445
|
+
private actionOf(name: ActionName): AnyAction | undefined {
|
|
1446
|
+
return this.actions.get(name) ?? this.catalogued().find((entry) => entry.action.name === name)?.action;
|
|
1447
|
+
}
|
|
1448
|
+
|
|
1449
|
+
/** The effect of an action by its name; undefined for a name nothing serves. */
|
|
1450
|
+
private effectOf(name: string): Effect | undefined {
|
|
1451
|
+
try {
|
|
1452
|
+
return this.actionOf(actionName(name))?.effect;
|
|
1453
|
+
} catch {
|
|
1454
|
+
return undefined;
|
|
1455
|
+
}
|
|
1456
|
+
}
|
|
1457
|
+
|
|
1458
|
+
/** Every action: the declared ones, then the ones the catalogs read now that no declared one shadows. */
|
|
1459
|
+
private allActions(): AnyAction[] {
|
|
1460
|
+
const read = this.catalogued().map((entry) => entry.action).filter((entry) => !this.actions.has(entry.name));
|
|
1461
|
+
return [...this.actions.values(), ...read];
|
|
1462
|
+
}
|
|
1463
|
+
|
|
1464
|
+
/** The record types an action may write: the ones of the plugin that declares or catalogs it. */
|
|
1465
|
+
private typesOfAction(name: ActionName): Set<RecordTypeName> | undefined {
|
|
1466
|
+
const declared = this.typesOf.get(name);
|
|
1467
|
+
if (declared !== undefined) return declared;
|
|
1468
|
+
const owner = this.catalogued().find((entry) => entry.action.name === name)?.installed;
|
|
1469
|
+
return owner === undefined ? undefined : new Set(owner.types.map((type) => type.name));
|
|
1470
|
+
}
|
|
1471
|
+
|
|
1472
|
+
/** The actions the catalogs of the loaded plugins hold now, each with its plugin. */
|
|
1473
|
+
private catalogued(): Array<{ action: AnyAction; installed: Installed }> {
|
|
1474
|
+
if (this.journal === undefined) return [];
|
|
1475
|
+
return [...this.plugins.values()].flatMap((installed) =>
|
|
1476
|
+
installed.catalogs.flatMap((read) => read().map((action) => ({ action, installed }))),
|
|
1477
|
+
);
|
|
1478
|
+
}
|
|
1479
|
+
|
|
1480
|
+
/** The current registrations: what the loaded plugins declare. Then look for new work. */
|
|
1481
|
+
private rebuild(): void {
|
|
1482
|
+
this.types.clear();
|
|
1483
|
+
this.actions.clear();
|
|
1484
|
+
this.typesOf.clear();
|
|
1485
|
+
this.typeOwners.clear();
|
|
1486
|
+
this.families.length = 0;
|
|
1487
|
+
this.handlers.clear();
|
|
1488
|
+
this.intercepts.clear();
|
|
1489
|
+
for (const [name, installed] of this.plugins) {
|
|
1490
|
+
for (const type of installed.types) {
|
|
1491
|
+
if (type.providerOnly !== undefined && type.providerOnly !== name) throw new TypeError(`"${type.name}" requires provider "${type.providerOnly}"`);
|
|
1492
|
+
this.types.set(type.name, type);
|
|
1493
|
+
this.typeOwners.set(type.name, name);
|
|
1494
|
+
if (type.name.endsWith(".*")) this.families.push(type);
|
|
1495
|
+
}
|
|
1496
|
+
for (const declared of installed.actions) {
|
|
1497
|
+
this.actions.set(declared.name, declared);
|
|
1498
|
+
this.typesOf.set(declared.name, new Set(installed.types.map((type) => type.name)));
|
|
1499
|
+
}
|
|
1500
|
+
for (const [target, set] of installed.intercepts) {
|
|
1501
|
+
// The intercepts of several plugins on one action are one list, and the order of
|
|
1502
|
+
// registration is the order they run in.
|
|
1503
|
+
const current = this.intercepts.get(target) ?? newIntercepts();
|
|
1504
|
+
current.adjusts.push(...set.adjusts);
|
|
1505
|
+
current.guards.push(...set.guards);
|
|
1506
|
+
this.intercepts.set(target, current);
|
|
1507
|
+
}
|
|
1508
|
+
for (const entry of installed.handlers) {
|
|
1509
|
+
this.handlers.set(handlerIdOf(`${name}/${entry.name}`), {
|
|
1510
|
+
types: [entry.type.name],
|
|
1511
|
+
selectors: [{ types: [entry.type.name], filter: entry.subscribing.filter }],
|
|
1512
|
+
schema: entry.type.version,
|
|
1513
|
+
version: installed.version,
|
|
1514
|
+
handler: entry.handler,
|
|
1515
|
+
subscribing: entry.subscribing,
|
|
1516
|
+
});
|
|
1517
|
+
}
|
|
1518
|
+
}
|
|
1519
|
+
// The host registers one action for itself: the way an owner answers a paused invocation.
|
|
1520
|
+
this.actions.set(this.resolver.name, this.resolver);
|
|
1521
|
+
this.actions.set(this.mover.name, this.mover);
|
|
1522
|
+
this.actions.set(this.canceller.name, this.canceller);
|
|
1523
|
+
// And one more: the way anyone asks what a plugin would do differently over recorded records.
|
|
1524
|
+
// And the install of a plugin from a file: its target is the plugin, so a grant can limit it.
|
|
1525
|
+
this.actions.set(this.installer.name, this.installer);
|
|
1526
|
+
this.actions.set(this.uninstaller.name, this.uninstaller);
|
|
1527
|
+
// And the observation ones: reading what happened is an action, so the surfaces generate
|
|
1528
|
+
// their tools and their commands from the same list as everything else.
|
|
1529
|
+
for (const reader of this.readers) this.actions.set(reader.name, reader);
|
|
1530
|
+
// And the ones of access: profiles, a grant changed or closed, the switch, and the explanation.
|
|
1531
|
+
for (const entry of this.accessActionList) this.actions.set(entry.name, entry);
|
|
1532
|
+
// A subscription installed while the host serves starts where the journal is now, not where
|
|
1533
|
+
// it is when the host next looks for work.
|
|
1534
|
+
if (this.journal !== undefined) this.placeSubscriptions(this.journal);
|
|
1535
|
+
this.requestPump();
|
|
1536
|
+
}
|
|
1537
|
+
|
|
1538
|
+
private requireJournal(): Journal {
|
|
1539
|
+
if (this.journal === undefined) throw new Error("the host is not serving");
|
|
1540
|
+
return this.journal;
|
|
1541
|
+
}
|
|
1542
|
+
|
|
1543
|
+
/** The last state record of an invocation, when it has one. */
|
|
1544
|
+
private lastState(
|
|
1545
|
+
journal: Journal,
|
|
1546
|
+
invocation: InvocationId,
|
|
1547
|
+
): { state: string; key: string | undefined; choices: string[] | undefined } | undefined {
|
|
1548
|
+
const rows = journal.find({
|
|
1549
|
+
type: CORE_TYPES.invocationState,
|
|
1550
|
+
field: "invocation",
|
|
1551
|
+
equals: invocation,
|
|
1552
|
+
});
|
|
1553
|
+
const data = StateData.safeParse(rows.at(-1)?.data);
|
|
1554
|
+
return data.success ? { state: data.data.state, key: data.data.key, choices: data.data.choices } : undefined;
|
|
1555
|
+
}
|
|
1556
|
+
|
|
1557
|
+
/**
|
|
1558
|
+
* The action the host registers for itself: answer a paused invocation.
|
|
1559
|
+
*
|
|
1560
|
+
* The answer is written as a record first, and then the invocation runs again with it in hand.
|
|
1561
|
+
*/
|
|
1562
|
+
private resolveAction(): AnyAction {
|
|
1563
|
+
return action(RESOLVE_ACTION, {
|
|
1564
|
+
description: "Answer a paused invocation: retry the step, skip it, or cancel the invocation.",
|
|
1565
|
+
input: ResolveInput,
|
|
1566
|
+
output: z.object({ resolved: z.boolean() }),
|
|
1567
|
+
// The answer is written as a record and the invocation runs again with it: the choice
|
|
1568
|
+
// stands whatever happens to the call, so it may be made again.
|
|
1569
|
+
recovery: "repeat",
|
|
1570
|
+
effect: "record",
|
|
1571
|
+
world: "niwa",
|
|
1572
|
+
run: async (input: z.infer<typeof ResolveInput>, ctx) => {
|
|
1573
|
+
const journal = this.requireJournal();
|
|
1574
|
+
// The invocation is named by its id, or by a unique start, end or short form of the id of one that is paused.
|
|
1575
|
+
const pausedIds = [...latestStates(journal)].filter(([, state]) => state === "paused").map(([id]) => String(id));
|
|
1576
|
+
// What a part of an id or a run would name is every paused invocation of the host: a client that is not the owner gives the whole id.
|
|
1577
|
+
if (input.run !== undefined || journal.get(recordId(input.invocation ?? "")) === undefined) requireOwner(ctx.caller, "names an invocation by a part of its id or by its run");
|
|
1578
|
+
const named =
|
|
1579
|
+
input.run === undefined
|
|
1580
|
+
? (resolveId(input.invocation ?? "", pausedIds, "paused invocation", shortInvocation) ?? input.invocation ?? "")
|
|
1581
|
+
: this.pausedOfRun(journal, input.run, pausedIds);
|
|
1582
|
+
const admitted = journal.get(recordId(named));
|
|
1583
|
+
const spec =
|
|
1584
|
+
admitted?.type === CORE_TYPES.invocationAdmitted
|
|
1585
|
+
? this.specOf(journal, admitted)
|
|
1586
|
+
: undefined;
|
|
1587
|
+
if (spec === undefined) throw new Error(`unknown invocation "${named}"`);
|
|
1588
|
+
const paused = this.lastState(journal, spec.invocation);
|
|
1589
|
+
if (paused?.state !== "paused") {
|
|
1590
|
+
throw new Error(`invocation "${named}" is not paused`);
|
|
1591
|
+
}
|
|
1592
|
+
// The step the answer is about: the one it names, or the one the invocation paused on.
|
|
1593
|
+
const keyName = input.key ?? paused.key;
|
|
1594
|
+
const key = keyName === undefined ? NO_STEP : stepKey(keyName);
|
|
1595
|
+
// Only what the pause offers (a wait is only cancelled, a pause on no step has no step to skip): the rule the
|
|
1596
|
+
// pause was written with, and the one a surface shows.
|
|
1597
|
+
const offered = offeredChoices(journal, spec.invocation, { choices: paused.choices, key });
|
|
1598
|
+
if (!offered.includes(input.choice)) {
|
|
1599
|
+
const intent = journal.get(attemptRecordId(spec.invocation, key, 0, "intent"));
|
|
1600
|
+
const waited = (intent?.data as { action?: unknown } | undefined)?.action === WAIT_ACTION;
|
|
1601
|
+
throw new Error(
|
|
1602
|
+
waited
|
|
1603
|
+
? `step ${key} is a wait: it can only be cancelled, not ${input.choice}`
|
|
1604
|
+
: `the pause of invocation "${named}" does not offer ${input.choice}: it offers ${offered.join(", ")}`,
|
|
1605
|
+
);
|
|
1606
|
+
}
|
|
1607
|
+
// The answer carries the attempt it answers, so it applies to that run and not to later ones.
|
|
1608
|
+
const attempt = attemptsOf(journal, spec.invocation, key) - 1;
|
|
1609
|
+
const records = [
|
|
1610
|
+
this.invocationRecord(spec, "res", CORE_TYPES.invocationResolved, {
|
|
1611
|
+
invocation: spec.invocation,
|
|
1612
|
+
key,
|
|
1613
|
+
choice: input.choice,
|
|
1614
|
+
attempt,
|
|
1615
|
+
}, ctx.caller),
|
|
1616
|
+
];
|
|
1617
|
+
if (input.choice === "cancel") {
|
|
1618
|
+
records.push(this.stateRecord(spec, "done", "cancelled"));
|
|
1619
|
+
}
|
|
1620
|
+
this.append(records);
|
|
1621
|
+
// Retry calls the step as a new attempt, skip continues without it.
|
|
1622
|
+
if (input.choice !== "cancel") this.schedule(spec);
|
|
1623
|
+
return { resolved: true };
|
|
1624
|
+
},
|
|
1625
|
+
});
|
|
1626
|
+
}
|
|
1627
|
+
|
|
1628
|
+
/**
|
|
1629
|
+
* The action the host registers for itself: cancel the steps of an invocation under some keys.
|
|
1630
|
+
*
|
|
1631
|
+
* The cancel is written as a record first, so it holds whatever process runs the invocation
|
|
1632
|
+
* later. Then the calls it holds that are in flight here are aborted, and an invocation that
|
|
1633
|
+
* waits runs again: a wait the cancel holds ends, and the code that made it goes on. The
|
|
1634
|
+
* invocation itself may cancel its own steps; any other caller is the owner.
|
|
1635
|
+
*/
|
|
1636
|
+
private cancelStepsAction(): AnyAction {
|
|
1637
|
+
return action(CANCEL_STEPS_ACTION, {
|
|
1638
|
+
description:
|
|
1639
|
+
"Cancel the steps of an invocation under some key prefixes: a step not called yet is not called, a call in flight is aborted, and each ends as cancelled.",
|
|
1640
|
+
input: CancelStepsInput,
|
|
1641
|
+
output: z.object({ aborted: z.number().int() }),
|
|
1642
|
+
// The cancel is written under the id of the operation: a call made again finds it and
|
|
1643
|
+
// writes nothing twice.
|
|
1644
|
+
recovery: "repeat",
|
|
1645
|
+
effect: "record",
|
|
1646
|
+
world: "niwa",
|
|
1647
|
+
run: async (input: z.infer<typeof CancelStepsInput>, ctx) => {
|
|
1648
|
+
const journal = this.requireJournal();
|
|
1649
|
+
const admitted = journal.get(recordId(input.invocation));
|
|
1650
|
+
const spec =
|
|
1651
|
+
admitted?.type === CORE_TYPES.invocationAdmitted ? this.specOf(journal, admitted) : undefined;
|
|
1652
|
+
if (spec === undefined) throw new Error(`unknown invocation "${input.invocation}"`);
|
|
1653
|
+
const own = ctx.caller.kind === "handler" && ctx.caller.invocation === spec.invocation;
|
|
1654
|
+
if (!own) requireOwner(ctx.caller, "cancels the steps of an invocation");
|
|
1655
|
+
const cancel = {
|
|
1656
|
+
invocation: spec.invocation,
|
|
1657
|
+
prefixes: input.prefixes,
|
|
1658
|
+
...(input.except === undefined || input.except.length === 0 ? {} : { except: input.except }),
|
|
1659
|
+
reason: input.reason,
|
|
1660
|
+
};
|
|
1661
|
+
const id = recordId(`sc:${ctx.operationId}`);
|
|
1662
|
+
if (journal.get(id) === undefined) {
|
|
1663
|
+
this.append([{ ...this.invocationRecord(spec, "sc", CORE_TYPES.stepCancelled, cancel, ctx.caller), id }]);
|
|
1664
|
+
}
|
|
1665
|
+
const aborted = abortSteps(cancel);
|
|
1666
|
+
// A waiting invocation runs again, so the waits the cancel holds end; one that is running now runs
|
|
1667
|
+
// again if it ends waiting, since it may wait on a step the cancel holds.
|
|
1668
|
+
const waiting = this.waiting.get(spec.invocation);
|
|
1669
|
+
if (waiting !== undefined) this.schedule(waiting.spec);
|
|
1670
|
+
else if (this.running.has(spec.invocation)) this.cancelledWhileRunning.add(spec.invocation);
|
|
1671
|
+
return { aborted };
|
|
1672
|
+
},
|
|
1673
|
+
});
|
|
1674
|
+
}
|
|
1675
|
+
|
|
1676
|
+
/**
|
|
1677
|
+
* The action the host registers for itself: move an unfinished invocation onto the version of
|
|
1678
|
+
* its plugin that is installed now.
|
|
1679
|
+
*
|
|
1680
|
+
* It is the explicit operation: nothing moves work except this call. The move is a record, so
|
|
1681
|
+
* a restart keeps it; the invocation then replays its recorded steps on the new code, and a
|
|
1682
|
+
* step the new code does not make the same way pauses it as a replay mismatch.
|
|
1683
|
+
*/
|
|
1684
|
+
private moveAction(): AnyAction {
|
|
1685
|
+
return action(MOVE_ACTION, {
|
|
1686
|
+
description:
|
|
1687
|
+
"Move an unfinished invocation onto the installed version of its plugin. Work is never moved by a restart.",
|
|
1688
|
+
input: MoveInput,
|
|
1689
|
+
output: z.object({ from: z.string(), to: z.string() }),
|
|
1690
|
+
// The record of the move is written under the id of the operation: a call made again
|
|
1691
|
+
// finds it and moves nothing twice.
|
|
1692
|
+
recovery: "repeat",
|
|
1693
|
+
effect: "record",
|
|
1694
|
+
world: "niwa",
|
|
1695
|
+
run: async (input: z.infer<typeof MoveInput>, ctx) => {
|
|
1696
|
+
const journal = this.requireJournal();
|
|
1697
|
+
const admitted = journal.get(recordId(input.invocation));
|
|
1698
|
+
const spec =
|
|
1699
|
+
admitted?.type === CORE_TYPES.invocationAdmitted ? this.specOf(journal, admitted) : undefined;
|
|
1700
|
+
if (spec === undefined) throw new Error(`unknown invocation "${input.invocation}"`);
|
|
1701
|
+
const id = recordId(`mv:${ctx.operationId}`);
|
|
1702
|
+
const done = journal.get(id);
|
|
1703
|
+
if (done !== undefined) {
|
|
1704
|
+
const data = z.object({ from: z.string(), to: z.string() }).parse(done.data);
|
|
1705
|
+
return { from: data.from, to: data.to };
|
|
1706
|
+
}
|
|
1707
|
+
if (this.lastState(journal, spec.invocation)?.state === "done") {
|
|
1708
|
+
throw new Error(`invocation "${input.invocation}" is done: there is nothing to move`);
|
|
1709
|
+
}
|
|
1710
|
+
const current = this.handlers.get(spec.handlerId);
|
|
1711
|
+
if (current === undefined) {
|
|
1712
|
+
throw new Error(`no installed plugin has the handler "${spec.handlerId}": there is nothing to move onto`);
|
|
1713
|
+
}
|
|
1714
|
+
if (current.version === spec.version) {
|
|
1715
|
+
throw new Error(`invocation "${input.invocation}" is already on version ${spec.version}`);
|
|
1716
|
+
}
|
|
1717
|
+
if (this.running.has(spec.invocation)) {
|
|
1718
|
+
throw new Error(`invocation "${input.invocation}" is running: move it when it waits or pauses`);
|
|
1719
|
+
}
|
|
1720
|
+
const move = { from: spec.version, to: current.version };
|
|
1721
|
+
this.append([
|
|
1722
|
+
{
|
|
1723
|
+
...this.invocationRecord(spec, "mv", CORE_TYPES.invocationMoved, { invocation: spec.invocation, ...move }, ctx.caller),
|
|
1724
|
+
id,
|
|
1725
|
+
},
|
|
1726
|
+
]);
|
|
1727
|
+
this.unpark(spec.invocation);
|
|
1728
|
+
this.schedule({ ...spec, version: current.version });
|
|
1729
|
+
return move;
|
|
1730
|
+
},
|
|
1731
|
+
});
|
|
1732
|
+
}
|
|
1733
|
+
|
|
1734
|
+
// --- serving ---------------------------------------------------------------
|
|
1735
|
+
|
|
1736
|
+
serve(): Promise<void> {
|
|
1737
|
+
this.serving ??= this.start().catch((error: unknown) => {
|
|
1738
|
+
this.serving = undefined;
|
|
1739
|
+
throw error;
|
|
1740
|
+
});
|
|
1741
|
+
return this.serving;
|
|
1742
|
+
}
|
|
1743
|
+
|
|
1744
|
+
private async start(): Promise<void> {
|
|
1745
|
+
if (this.closed) throw new Error("the host is closed");
|
|
1746
|
+
const path = socketPath(this.home);
|
|
1747
|
+
// The socket is checked before the journal is opened: a living host on this home is refused,
|
|
1748
|
+
// and taking the journal from it would be a take-over the owner did not ask for. An explicit
|
|
1749
|
+
// take-over skips the check: the old host learns it lost the journal from its next write.
|
|
1750
|
+
if (!this.takeover && (await isLiveSocket(path))) {
|
|
1751
|
+
throw new WriterBusy(`another host is listening on ${path}`);
|
|
1752
|
+
}
|
|
1753
|
+
const journal = openJournal(this.home, { takeover: this.takeover, clock: this.clock });
|
|
1754
|
+
this.journal = journal;
|
|
1755
|
+
try {
|
|
1756
|
+
journal.setGuards([...this.types.values()]);
|
|
1757
|
+
// The state is a projection of the journal: folded from it here, so a restart sees it.
|
|
1758
|
+
this.states.bind({ journal, append: (recs) => this.append(recs) });
|
|
1759
|
+
this.openDoors(journal);
|
|
1760
|
+
// Before anything loads a plugin file again: the copies of files no installation is made from are taken away.
|
|
1761
|
+
await removeStaleCopies(journal);
|
|
1762
|
+
for (const installation of currentInstallations(journal).values()) {
|
|
1763
|
+
this.checkModuleName(pluginName(installation.plugin));
|
|
1764
|
+
this.install(await restorePlugin(installation), { restoringVersion: installation.version });
|
|
1765
|
+
}
|
|
1766
|
+
this.requireProviders();
|
|
1767
|
+
this.positions.clear();
|
|
1768
|
+
this.kept.clear();
|
|
1769
|
+
this.active.clear();
|
|
1770
|
+
this.activeOf.clear();
|
|
1771
|
+
this.rebuild();
|
|
1772
|
+
this.resume(journal);
|
|
1773
|
+
this.pump(journal);
|
|
1774
|
+
rmSync(path, { force: true }); // the old holder's file: this host binds its own
|
|
1775
|
+
this.server = Bun.listen<Connection>({
|
|
1776
|
+
unix: path,
|
|
1777
|
+
socket: {
|
|
1778
|
+
open: (socket) => {
|
|
1779
|
+
const connection = new Connection(socket, ++this.connectionCount, (c, raw) => {
|
|
1780
|
+
void this.handleMessage(c, raw);
|
|
1781
|
+
});
|
|
1782
|
+
socket.data = connection;
|
|
1783
|
+
this.connections.add(connection);
|
|
1784
|
+
},
|
|
1785
|
+
data: (socket, chunk) => {
|
|
1786
|
+
socket.data.receiveBytes(chunk);
|
|
1787
|
+
},
|
|
1788
|
+
drain: (socket) => {
|
|
1789
|
+
socket.data.flush();
|
|
1790
|
+
},
|
|
1791
|
+
close: (socket) => {
|
|
1792
|
+
this.connections.delete(socket.data);
|
|
1793
|
+
socket.data.drop();
|
|
1794
|
+
},
|
|
1795
|
+
error: (socket) => {
|
|
1796
|
+
this.connections.delete(socket.data);
|
|
1797
|
+
socket.data.drop();
|
|
1798
|
+
},
|
|
1799
|
+
},
|
|
1800
|
+
});
|
|
1801
|
+
this.socketFile = socketIdentity(path);
|
|
1802
|
+
// Started last: a service that fails to start must not leave a host half-served, and what a
|
|
1803
|
+
// service writes lands in the journal that is open now.
|
|
1804
|
+
this.startServices();
|
|
1805
|
+
} catch (error) {
|
|
1806
|
+
// The host could not serve: the journal is given back, so the next host may take it over.
|
|
1807
|
+
journal.close();
|
|
1808
|
+
this.journal = undefined;
|
|
1809
|
+
this.doors = undefined;
|
|
1810
|
+
for (const name of this.plugins.keys()) if (!this.configured.has(name)) this.plugins.delete(name);
|
|
1811
|
+
this.rebuild();
|
|
1812
|
+
throw error;
|
|
1813
|
+
}
|
|
1814
|
+
}
|
|
1815
|
+
|
|
1816
|
+
/**
|
|
1817
|
+
* The tokens: folded from the journal, so a restart knows every token it made. The owner's
|
|
1818
|
+
* token is made on the first start and kept in the home for the owner's own tools; a missing
|
|
1819
|
+
* or unknown one is made again, and the old one stops working.
|
|
1820
|
+
*/
|
|
1821
|
+
private openDoors(journal: Journal): void {
|
|
1822
|
+
const doors = new Doors(loadHostKey(this.home));
|
|
1823
|
+
const types = [
|
|
1824
|
+
CORE_TYPES.accessIssued,
|
|
1825
|
+
CORE_TYPES.accessGranted,
|
|
1826
|
+
CORE_TYPES.accessClosed,
|
|
1827
|
+
CORE_TYPES.accessProfile,
|
|
1828
|
+
CORE_TYPES.accessSwitched,
|
|
1829
|
+
CORE_TYPES.accessAnswered,
|
|
1830
|
+
];
|
|
1831
|
+
// The table is what the records say, in the order they were written.
|
|
1832
|
+
for (const row of journal.since(seq(0), types)) doors.fold(row);
|
|
1833
|
+
this.doors = doors;
|
|
1834
|
+
const known = readOwnerToken(this.home);
|
|
1835
|
+
if (known !== undefined && doors.holderOf(known)?.kind === "owner") return;
|
|
1836
|
+
const secret = this.issue(OWNER, {});
|
|
1837
|
+
const path = `${this.home}/${OWNER_TOKEN_FILE}`;
|
|
1838
|
+
writeFileSync(path, `${secret}\n`, { mode: 0o600 });
|
|
1839
|
+
chmodSync(path, 0o600);
|
|
1840
|
+
}
|
|
1841
|
+
|
|
1842
|
+
private requireDoors(): Doors {
|
|
1843
|
+
if (this.doors === undefined) throw new Error("the host is not serving");
|
|
1844
|
+
return this.doors;
|
|
1845
|
+
}
|
|
1846
|
+
|
|
1847
|
+
/**
|
|
1848
|
+
* Make a token for a principal, keep its MAC in the journal, and give the token to the caller.
|
|
1849
|
+
* A principal that is given a grant has it recorded with the grant it came from.
|
|
1850
|
+
*/
|
|
1851
|
+
private issue(principal: Principal, opts: { grant?: Grant; parent?: Caller }): Token {
|
|
1852
|
+
const doors = this.requireDoors();
|
|
1853
|
+
if (opts.parent !== undefined) {
|
|
1854
|
+
const parent = this.access.standing(opts.parent);
|
|
1855
|
+
if (parent.kind === "closed") throw new DeniedError(`the parent's grant was closed: ${parent.reason}`);
|
|
1856
|
+
if (parent.kind === "off") throw new DeniedError("all access is switched off");
|
|
1857
|
+
}
|
|
1858
|
+
const secret = doors.fresh();
|
|
1859
|
+
const id = newRecordId("acc");
|
|
1860
|
+
const issued: NewRecord = {
|
|
1861
|
+
id,
|
|
1862
|
+
stream: streamId("access"),
|
|
1863
|
+
type: CORE_TYPES.accessIssued,
|
|
1864
|
+
schema: 1,
|
|
1865
|
+
data: { mac: doors.macOf(secret), principal },
|
|
1866
|
+
actor: { kind: "host" },
|
|
1867
|
+
cause: null,
|
|
1868
|
+
root: id,
|
|
1869
|
+
};
|
|
1870
|
+
const parent = opts.parent === undefined ? undefined : this.access.parentOf(opts.parent);
|
|
1871
|
+
const granted = opts.grant === undefined ? [] : [this.access.grantRecord(principal, opts.grant, parent)];
|
|
1872
|
+
if (this.append([issued, ...granted]).length === 0) throw new Error("the token was not recorded");
|
|
1873
|
+
return secret;
|
|
1874
|
+
}
|
|
1875
|
+
|
|
1876
|
+
/** The caller of a message of a connection: who its token says it is, and the grant that limits it. */
|
|
1877
|
+
private callerOf(connection: Connection): Caller {
|
|
1878
|
+
const caller: Caller = { kind: "client", id: connection.caller, principal: connection.principal };
|
|
1879
|
+
const grant = this.access.grantIdOf(caller);
|
|
1880
|
+
return grant === undefined ? caller : { ...caller, grant };
|
|
1881
|
+
}
|
|
1882
|
+
|
|
1883
|
+
/**
|
|
1884
|
+
* May this caller write this record type over the wire?
|
|
1885
|
+
*
|
|
1886
|
+
* An open type is anyone's. A closed one is written by the plugin that declares it, and by a
|
|
1887
|
+
* subject whose grant has an `emit:` rule for it. A subject whose grant is closed, or while the
|
|
1888
|
+
* switch is off, writes nothing. A type nobody declares is `UnknownType` when written.
|
|
1889
|
+
*/
|
|
1890
|
+
private permitEmit(caller: Caller, type: RecordTypeName): void {
|
|
1891
|
+
const standing = this.access.standing(caller);
|
|
1892
|
+
const principal = caller.kind === "client" ? caller.principal : undefined;
|
|
1893
|
+
const declared = this.declaredType(type);
|
|
1894
|
+
const owner = this.typeOwners.get(declared?.name ?? type);
|
|
1895
|
+
// A plugin writes its own types: over the wire as its principal, and from a handler of its own. A
|
|
1896
|
+
// handler id is the plugin's name, a "/" and a name with none, so the plugin is all before the last.
|
|
1897
|
+
const handler = caller.kind === "handler" ? String(caller.handler) : undefined;
|
|
1898
|
+
const writer = handler !== undefined ? handler.slice(0, handler.lastIndexOf("/")) : principal?.kind === "plugin" ? String(principal.id) : undefined;
|
|
1899
|
+
const own = writer !== undefined && writer === String(owner);
|
|
1900
|
+
const closed = `"${type}" is closed: only the "${owner}" plugin writes it`;
|
|
1901
|
+
let answer: Permit;
|
|
1902
|
+
if (standing.kind === "closed" || standing.kind === "off") {
|
|
1903
|
+
answer = permit(standing, "emit", type);
|
|
1904
|
+
} else if (declared?.providerOnly !== undefined) {
|
|
1905
|
+
answer = caller.kind === "handler" && own ? { allowed: true } : { allowed: false, reason: closed };
|
|
1906
|
+
} else if (declared === undefined || declared.open === true || own) {
|
|
1907
|
+
answer = { allowed: true };
|
|
1908
|
+
} else {
|
|
1909
|
+
const found = standing.kind === "limited" ? permit(standing, "emit", type) : undefined;
|
|
1910
|
+
answer =
|
|
1911
|
+
found === undefined
|
|
1912
|
+
? { allowed: false, reason: closed }
|
|
1913
|
+
: found.allowed
|
|
1914
|
+
? found
|
|
1915
|
+
: { ...found, reason: found.reason === "ask" ? "ask" : closed };
|
|
1916
|
+
}
|
|
1917
|
+
const decision = this.access.decided(caller, standing, "emit", type, answer);
|
|
1918
|
+
if (!answer.allowed) throw new DeniedError(answer.reason, this.detailsOf(answer, decision));
|
|
1919
|
+
}
|
|
1920
|
+
|
|
1921
|
+
/**
|
|
1922
|
+
* The question of a rule that asks, for a call a client makes at the door: an answer in
|
|
1923
|
+
* force settles it; else the plugin that asks for the host puts it to the owner and the call
|
|
1924
|
+
* waits. Nobody to ask, or a question that could not be asked, is no answer.
|
|
1925
|
+
*/
|
|
1926
|
+
private askOwner(): Ask {
|
|
1927
|
+
return async (question) => {
|
|
1928
|
+
if (this.access.answeredRun(question)) return "run";
|
|
1929
|
+
const asker = [...this.plugins.values()].reverse().find((entry) => entry.asker !== undefined)?.asker;
|
|
1930
|
+
if (asker === undefined) return "unanswered";
|
|
1931
|
+
let outcome: AskOutcome;
|
|
1932
|
+
try {
|
|
1933
|
+
outcome = await asker(question, timestamp(this.clock.now()));
|
|
1934
|
+
} catch {
|
|
1935
|
+
return "unanswered";
|
|
1936
|
+
}
|
|
1937
|
+
if (outcome !== "refused" && outcome !== "unanswered") this.access.answered(question, outcome);
|
|
1938
|
+
return outcome;
|
|
1939
|
+
};
|
|
1940
|
+
}
|
|
1941
|
+
|
|
1942
|
+
/**
|
|
1943
|
+
* One `verb` on one `name` of a caller, held to its grant: the decision is recorded, a refusal throws.
|
|
1944
|
+
* A call under a rule that asks puts the question to the owner as a call at the door does; an
|
|
1945
|
+
* emit or a read under such a rule is a denial.
|
|
1946
|
+
*/
|
|
1947
|
+
private async authorize(caller: Caller, verb: Verb, name: string, how?: AuthorizeHow): Promise<void> {
|
|
1948
|
+
const standing = this.access.standing(caller);
|
|
1949
|
+
const found = verb === "call" ? this.actionOf(actionName(name)) : undefined;
|
|
1950
|
+
const checked = found?.input.safeParse(how?.input);
|
|
1951
|
+
const input = checked?.success === true ? checked.data : how?.input;
|
|
1952
|
+
const target = found?.target === undefined || checked?.success !== true ? undefined : found.target(checked.data);
|
|
1953
|
+
// The class of this call when its input is known; else the most the action can be.
|
|
1954
|
+
const classed = found === undefined ? undefined : checked?.success === true ? await effectOfCall(found, checked.data) : { effect: found.effect };
|
|
1955
|
+
let answer: Permit =
|
|
1956
|
+
classed !== undefined && "refused" in classed
|
|
1957
|
+
? { allowed: false, reason: classed.refused }
|
|
1958
|
+
: permit(standing, verb, name, target, classed?.effect);
|
|
1959
|
+
if (!answer.allowed && answer.asks === true && how?.read === true) {
|
|
1960
|
+
answer = { ...answer, reason: `"${name}" asks the owner, and a read is not asked: it is denied` };
|
|
1961
|
+
} else if (verb === "call") {
|
|
1962
|
+
answer = await settleAsk(answer, {
|
|
1963
|
+
caller,
|
|
1964
|
+
name,
|
|
1965
|
+
input,
|
|
1966
|
+
ask: this.askOwner(),
|
|
1967
|
+
...(target === undefined ? {} : { target }),
|
|
1968
|
+
...(how?.reason === undefined ? {} : { reason: how.reason }),
|
|
1969
|
+
});
|
|
1970
|
+
}
|
|
1971
|
+
const decision = this.access.decided(caller, standing, verb, name, answer, {
|
|
1972
|
+
...(how?.step === undefined ? {} : { step: how.step }),
|
|
1973
|
+
...(how?.policy === undefined ? {} : { policy: how.policy }),
|
|
1974
|
+
});
|
|
1975
|
+
if (!answer.allowed) throw new DeniedError(answer.reason, this.detailsOf(answer, decision));
|
|
1976
|
+
}
|
|
1977
|
+
|
|
1978
|
+
private detailsOf(answer: Extract<Permit, { allowed: false }>, record: RecordId | undefined): DeniedDetails | undefined {
|
|
1979
|
+
if (answer.grant === undefined || answer.missing === undefined) return undefined;
|
|
1980
|
+
return { grant: answer.grant, missing: answer.missing, ...(record === undefined ? {} : { record }) };
|
|
1981
|
+
}
|
|
1982
|
+
|
|
1983
|
+
issueToken(principal: Principal, opts?: { grant?: Grant; parent?: Caller }): Token {
|
|
1984
|
+
return this.issue(principal, opts ?? {});
|
|
1985
|
+
}
|
|
1986
|
+
|
|
1987
|
+
/**
|
|
1988
|
+
* A trigger is waited for, so something has to produce it: a handler of a filtered type whose
|
|
1989
|
+
* record type no installed plugin declares would wait forever, and the host says so before it
|
|
1990
|
+
* serves. A plain type is not checked: its records may come from a client or another host.
|
|
1991
|
+
*/
|
|
1992
|
+
private requireProviders(excluding?: PluginName): void {
|
|
1993
|
+
const plugins = [...this.plugins].filter(([name]) => name !== excluding);
|
|
1994
|
+
const names = new Set(plugins.map(([name]) => String(name)));
|
|
1995
|
+
const actions = new Set([
|
|
1996
|
+
this.installer.name, this.uninstaller.name, this.resolver.name, this.mover.name, this.canceller.name,
|
|
1997
|
+
...this.readers.map((reader) => reader.name), ...this.accessActionList.map((entry) => entry.name),
|
|
1998
|
+
...plugins.flatMap(([, entry]) => entry.actions.map((declared) => declared.name)),
|
|
1999
|
+
]);
|
|
2000
|
+
// What a plugin offers is read by another: an offer to a reader that is not installed would be lost.
|
|
2001
|
+
for (const [name, entry] of plugins) {
|
|
2002
|
+
for (const { key } of entry.offers) {
|
|
2003
|
+
// The host reads the points that name it: no plugin has to be installed to read them.
|
|
2004
|
+
if (key.reader !== HOST_READER && !names.has(key.reader)) {
|
|
2005
|
+
throw new MissingReader(name, key.name, key.reader);
|
|
2006
|
+
}
|
|
2007
|
+
}
|
|
2008
|
+
}
|
|
2009
|
+
const declared = new Set<string>();
|
|
2010
|
+
for (const [, entry] of plugins) for (const type of entry.types) declared.add(type.name);
|
|
2011
|
+
let catalog: Set<ActionName> | undefined;
|
|
2012
|
+
for (const [name, entry] of plugins) {
|
|
2013
|
+
for (const handler of entry.handlers) {
|
|
2014
|
+
if (handler.trigger === undefined || declared.has(handler.type.name) || CORE_TYPE_NAMES.has(handler.type.name)) continue;
|
|
2015
|
+
throw new MissingProvider(name, handler.name, handler.type.name, handler.trigger.provider ?? handler.type.provider);
|
|
2016
|
+
}
|
|
2017
|
+
for (const needed of entry.needs.actions) {
|
|
2018
|
+
const action = actionName(needed);
|
|
2019
|
+
if (actions.has(action)) continue;
|
|
2020
|
+
// At startup and during install or removal, use the catalog of the plugin set being checked.
|
|
2021
|
+
catalog ??= new Set(this.catalogued()
|
|
2022
|
+
.filter(({ installed }) => installed.source.name !== excluding)
|
|
2023
|
+
.map(({ action }) => action.name));
|
|
2024
|
+
if (!catalog.has(action)) throw new MissingNeed(name, "action", needed);
|
|
2025
|
+
}
|
|
2026
|
+
for (const needed of entry.needs.types) {
|
|
2027
|
+
if (!declared.has(needed) && !CORE_TYPE_NAMES.has(needed)) throw new MissingNeed(name, "type", needed);
|
|
2028
|
+
}
|
|
2029
|
+
// What a handler needs from another plugin is checked for every handler, filtered or not.
|
|
2030
|
+
for (const handler of entry.handlers) {
|
|
2031
|
+
for (const needed of handler.requires) {
|
|
2032
|
+
if (declared.has(needed.name) || CORE_TYPE_NAMES.has(needed.name)) continue;
|
|
2033
|
+
throw new MissingProvider(name, handler.name, needed.name, needed.provider, "needs");
|
|
2034
|
+
}
|
|
2035
|
+
}
|
|
2036
|
+
}
|
|
2037
|
+
}
|
|
2038
|
+
|
|
2039
|
+
/** Run the invocations that were not finished when the host stopped. */
|
|
2040
|
+
private resume(journal: Journal): void {
|
|
2041
|
+
const states = latestStates(journal);
|
|
2042
|
+
for (const row of journal.find({ type: CORE_TYPES.invocationAdmitted })) {
|
|
2043
|
+
const state = states.get(row.id);
|
|
2044
|
+
if (state === "done") continue;
|
|
2045
|
+
const spec = this.specOf(journal, row);
|
|
2046
|
+
if (spec === undefined) continue;
|
|
2047
|
+
// A paused invocation is unfinished: it holds its place in its subscription until it is decided.
|
|
2048
|
+
this.hold(spec);
|
|
2049
|
+
if (state !== "paused") this.schedule(spec);
|
|
2050
|
+
}
|
|
2051
|
+
}
|
|
2052
|
+
|
|
2053
|
+
/** The spec of an invocation, read from its admitted record. */
|
|
2054
|
+
private specOf(
|
|
2055
|
+
journal: Journal,
|
|
2056
|
+
admitted: StoredRecord,
|
|
2057
|
+
known?: StoredRecord,
|
|
2058
|
+
): RunSpec | undefined {
|
|
2059
|
+
const data = AdmittedData.safeParse(admitted.data);
|
|
2060
|
+
if (!data.success) return undefined;
|
|
2061
|
+
const woken = known ?? journal.get(recordId(data.data.record));
|
|
2062
|
+
if (woken === undefined) return undefined;
|
|
2063
|
+
const handler = handlerIdOf(data.data.handler);
|
|
2064
|
+
const invocation = invocationId(handler, woken.id);
|
|
2065
|
+
// The version it was admitted on, unless the owner moved it since: the last move wins.
|
|
2066
|
+
const moved = MovedData.safeParse(
|
|
2067
|
+
journal.find({ type: CORE_TYPES.invocationMoved, field: "invocation", equals: invocation }).at(-1)?.data,
|
|
2068
|
+
);
|
|
2069
|
+
return {
|
|
2070
|
+
invocation,
|
|
2071
|
+
handlerId: handler,
|
|
2072
|
+
record: woken,
|
|
2073
|
+
version: pluginVersion(moved.success ? moved.data.to : data.data.pluginVersion),
|
|
2074
|
+
key: data.data.keyed?.key,
|
|
2075
|
+
};
|
|
2076
|
+
}
|
|
2077
|
+
|
|
2078
|
+
// --- admission -------------------------------------------------------------
|
|
2079
|
+
|
|
2080
|
+
/** Look for new work, once after the current step of the event loop. */
|
|
2081
|
+
private requestPump(): void {
|
|
2082
|
+
if (this.pumpQueued || this.journal === undefined) return;
|
|
2083
|
+
this.pumpQueued = true;
|
|
2084
|
+
queueMicrotask(() => {
|
|
2085
|
+
this.pumpQueued = false;
|
|
2086
|
+
const journal = this.journal;
|
|
2087
|
+
if (journal === undefined) return;
|
|
2088
|
+
try {
|
|
2089
|
+
this.pump(journal);
|
|
2090
|
+
} catch (error) {
|
|
2091
|
+
this.fail("admission", error);
|
|
2092
|
+
}
|
|
2093
|
+
});
|
|
2094
|
+
}
|
|
2095
|
+
|
|
2096
|
+
/**
|
|
2097
|
+
* Admit the records that no subscription has seen yet. Runs to the end without waiting.
|
|
2098
|
+
*
|
|
2099
|
+
* A subscription reads the records of its type after its position. A record it admits moves the
|
|
2100
|
+
* position in the same commit as the admission, which carries it. A record it passes over — the
|
|
2101
|
+
* filter does not hold, another version of the schema, a chain its own invocations caused — moves
|
|
2102
|
+
* the position too, by one position record for the stretch it passed with the reason of the last
|
|
2103
|
+
* one, so a restart does not read them again. A subscription that has as many unfinished
|
|
2104
|
+
* invocations as it may have stops before the next record it would admit. A keyed subscription
|
|
2105
|
+
* can admit records of other keys beyond a busy key, but keeps its position before the gap.
|
|
2106
|
+
* The admissions identify the records already served when it scans that range again.
|
|
2107
|
+
*/
|
|
2108
|
+
private pump(journal: Journal): void {
|
|
2109
|
+
this.readSubscribers(journal);
|
|
2110
|
+
for (const [id, entry] of this.handlers) {
|
|
2111
|
+
const subscribing = entry.subscribing;
|
|
2112
|
+
let after = this.positions.get(id) ?? this.loadPosition(journal, id, entry);
|
|
2113
|
+
if (entry.until !== undefined && after >= entry.until) continue;
|
|
2114
|
+
let passed: { seq: Seq; reason: PassReason } | undefined;
|
|
2115
|
+
let gap = false;
|
|
2116
|
+
for (const record of journal.query({ types: entry.types, from: after })) {
|
|
2117
|
+
if (entry.until !== undefined && record.seq > entry.until) break;
|
|
2118
|
+
// The positions of subscriptions are their own bookkeeping: no subscription is woken by one, and
|
|
2119
|
+
// passing over one writes nothing, or two subscriptions of the family would answer each other.
|
|
2120
|
+
if (record.type === CORE_TYPES.subscriptionPosition) {
|
|
2121
|
+
if (!gap) after = record.seq;
|
|
2122
|
+
continue;
|
|
2123
|
+
}
|
|
2124
|
+
const reason = journal.get(recordId(invocationId(id, record.id)))?.type === CORE_TYPES.invocationAdmitted
|
|
2125
|
+
? "already-admitted"
|
|
2126
|
+
: this.passOver(journal, id, entry, record);
|
|
2127
|
+
if (reason !== undefined) {
|
|
2128
|
+
if (!gap) {
|
|
2129
|
+
after = record.seq;
|
|
2130
|
+
passed = { seq: record.seq, reason };
|
|
2131
|
+
}
|
|
2132
|
+
continue;
|
|
2133
|
+
}
|
|
2134
|
+
const active = this.active.get(id);
|
|
2135
|
+
const concurrency = subscribing.concurrency;
|
|
2136
|
+
let key: SubscriptionKey | undefined;
|
|
2137
|
+
if (typeof concurrency === "number") {
|
|
2138
|
+
if ((active?.size ?? 0) >= concurrency) break;
|
|
2139
|
+
} else {
|
|
2140
|
+
// When switching from numeric concurrency, let the work with no recorded key finish.
|
|
2141
|
+
if (active?.keys.has(undefined)) break;
|
|
2142
|
+
try {
|
|
2143
|
+
const pinned = this.pinned.get(pinKey(id, entry.version));
|
|
2144
|
+
if (pinned === undefined) throw new Error("the subscription has no installed handler");
|
|
2145
|
+
const selected: unknown = concurrency.by(pinned.type.schema.parse(record.data));
|
|
2146
|
+
if (typeof selected !== "string" && !(typeof selected === "number" && Number.isFinite(selected))) {
|
|
2147
|
+
if (selected instanceof Promise) void selected.catch(() => {});
|
|
2148
|
+
throw new TypeError("concurrency.by must return a string or a finite number synchronously");
|
|
2149
|
+
}
|
|
2150
|
+
key = selected;
|
|
2151
|
+
} catch (error) {
|
|
2152
|
+
this.fail(`selecting the key for ${id} on ${record.id}`, error);
|
|
2153
|
+
break;
|
|
2154
|
+
}
|
|
2155
|
+
if (active?.keys.has(key)) {
|
|
2156
|
+
gap = true;
|
|
2157
|
+
continue;
|
|
2158
|
+
}
|
|
2159
|
+
}
|
|
2160
|
+
if (!gap) after = record.seq;
|
|
2161
|
+
const spec = this.admit(journal, id, entry.version, record, key === undefined ? undefined : { key, cursor: after });
|
|
2162
|
+
this.keep(id, after);
|
|
2163
|
+
if (spec !== undefined) {
|
|
2164
|
+
this.hold(spec);
|
|
2165
|
+
this.schedule(spec);
|
|
2166
|
+
}
|
|
2167
|
+
}
|
|
2168
|
+
this.positions.set(id, after);
|
|
2169
|
+
if (passed !== undefined && passed.seq > (this.kept.get(id) ?? seq(0))) this.writePosition(id, passed.seq, passed.reason);
|
|
2170
|
+
}
|
|
2171
|
+
}
|
|
2172
|
+
|
|
2173
|
+
/** Why a subscription does not admit a record of its type, or nothing when it admits it. */
|
|
2174
|
+
private passOver(
|
|
2175
|
+
journal: Journal,
|
|
2176
|
+
id: HandlerId,
|
|
2177
|
+
entry: Served,
|
|
2178
|
+
record: StoredRecord,
|
|
2179
|
+
): PassReason | undefined {
|
|
2180
|
+
// A record of another version of the type is not this handler's business: it is passed over and
|
|
2181
|
+
// stays readable, because the journal is the history of what happened.
|
|
2182
|
+
if (entry.schema !== undefined && record.schema !== entry.schema) return "schema";
|
|
2183
|
+
if (!entry.selectors.some((one) => matchesQuery(one, record))) return "filtered";
|
|
2184
|
+
const chain = this.ownChain(journal, id, record);
|
|
2185
|
+
if (chain.length > entry.subscribing.depth) {
|
|
2186
|
+
if (entry.subscribing.depth === 0) return "self";
|
|
2187
|
+
console.error(
|
|
2188
|
+
`niwa: ${id} is not woken by ${record.id}: its own invocations caused it ${String(chain.length)} times, past its depth ${String(entry.subscribing.depth)} (${chain.join(" <- ")})`,
|
|
2189
|
+
);
|
|
2190
|
+
return "reentry";
|
|
2191
|
+
}
|
|
2192
|
+
return undefined;
|
|
2193
|
+
}
|
|
2194
|
+
|
|
2195
|
+
/**
|
|
2196
|
+
* The records on a record's chain of causes, itself first, that the subscription's own invocations
|
|
2197
|
+
* wrote: what it would be woken by again if it were woken by this one. The writer is the actor: an
|
|
2198
|
+
* invocation writes as its handler, and so does an action it calls, even as another principal. The
|
|
2199
|
+
* cause alone cannot say it: every subscription that admitted a record is woken by the same one.
|
|
2200
|
+
*/
|
|
2201
|
+
private ownChain(journal: Journal, id: HandlerId, record: StoredRecord): RecordId[] {
|
|
2202
|
+
const own: RecordId[] = [];
|
|
2203
|
+
for (let row: StoredRecord | undefined = record; row !== undefined; row = row.cause === null ? undefined : journal.get(row.cause)) {
|
|
2204
|
+
if (row.actor.kind === "handler" && row.actor.handler === id) own.push(row.id);
|
|
2205
|
+
}
|
|
2206
|
+
return own;
|
|
2207
|
+
}
|
|
2208
|
+
|
|
2209
|
+
/** Count an invocation among the unfinished ones of its subscription. */
|
|
2210
|
+
private hold({ handlerId: id, invocation, key }: RunSpec): void {
|
|
2211
|
+
if (this.activeOf.has(invocation)) return;
|
|
2212
|
+
const active: ActiveSubscription = this.active.get(id) ?? { size: 0, keys: new Map() };
|
|
2213
|
+
active.size++;
|
|
2214
|
+
active.keys.set(key, (active.keys.get(key) ?? 0) + 1);
|
|
2215
|
+
this.active.set(id, active);
|
|
2216
|
+
this.activeOf.set(invocation, { id, key });
|
|
2217
|
+
}
|
|
2218
|
+
|
|
2219
|
+
/** An invocation is done: its place in its subscription is free, and the next record may start. */
|
|
2220
|
+
private release(invocation: InvocationId): void {
|
|
2221
|
+
const held = this.activeOf.get(invocation);
|
|
2222
|
+
if (held === undefined) return;
|
|
2223
|
+
this.activeOf.delete(invocation);
|
|
2224
|
+
const active = this.active.get(held.id)!;
|
|
2225
|
+
const count = active.keys.get(held.key)!;
|
|
2226
|
+
if (count === 1) active.keys.delete(held.key);
|
|
2227
|
+
else active.keys.set(held.key, count - 1);
|
|
2228
|
+
if (--active.size === 0) this.active.delete(held.id);
|
|
2229
|
+
this.requestPump();
|
|
2230
|
+
}
|
|
2231
|
+
|
|
2232
|
+
/** The position a subscription has kept in the journal moved to here. */
|
|
2233
|
+
private keep(id: HandlerId, at: Seq): void {
|
|
2234
|
+
if (at > (this.kept.get(id) ?? seq(0))) this.kept.set(id, at);
|
|
2235
|
+
}
|
|
2236
|
+
|
|
2237
|
+
/** Record that a subscription has looked up to a position, and why it admitted nothing on the way. */
|
|
2238
|
+
private writePosition(id: HandlerId, at: Seq, reason: PassReason): void {
|
|
2239
|
+
this.append([
|
|
2240
|
+
{
|
|
2241
|
+
id: newRecordId("pos"),
|
|
2242
|
+
stream: streamId(`subscription:${id}`),
|
|
2243
|
+
type: CORE_TYPES.subscriptionPosition,
|
|
2244
|
+
schema: 1,
|
|
2245
|
+
data: { subscription: id, seq: at, reason },
|
|
2246
|
+
actor: { kind: "host" },
|
|
2247
|
+
cause: null,
|
|
2248
|
+
root: recordId(`subscription:${id}`),
|
|
2249
|
+
},
|
|
2250
|
+
]);
|
|
2251
|
+
this.keep(id, at);
|
|
2252
|
+
}
|
|
2253
|
+
|
|
2254
|
+
/** Read the positions of the subscriptions, and place the new ones where they start. */
|
|
2255
|
+
private placeSubscriptions(journal: Journal): void {
|
|
2256
|
+
this.readSubscribers(journal);
|
|
2257
|
+
for (const [id, entry] of this.handlers) {
|
|
2258
|
+
if (!this.positions.has(id)) this.loadPosition(journal, id, entry);
|
|
2259
|
+
}
|
|
2260
|
+
}
|
|
2261
|
+
|
|
2262
|
+
/**
|
|
2263
|
+
* The subscriptions the plugins read from the journal, served as handlers are: each under the name
|
|
2264
|
+
* of its plugin, pinned on the plugin's version so an invocation it admitted runs after a restart.
|
|
2265
|
+
* One that is no longer read admits nothing more; what it admitted finishes.
|
|
2266
|
+
*/
|
|
2267
|
+
private readSubscribers(journal: Journal): void {
|
|
2268
|
+
for (const id of this.dynamic) this.handlers.delete(id);
|
|
2269
|
+
this.dynamic.clear();
|
|
2270
|
+
for (const [name, installed] of this.plugins) {
|
|
2271
|
+
for (const read of installed.subscribers) {
|
|
2272
|
+
let found: readonly Subscriber[];
|
|
2273
|
+
try {
|
|
2274
|
+
found = read();
|
|
2275
|
+
} catch (error) {
|
|
2276
|
+
this.fail(`reading the subscribers of "${name}"`, error);
|
|
2277
|
+
continue;
|
|
2278
|
+
}
|
|
2279
|
+
for (const one of found) {
|
|
2280
|
+
if (one.id.includes("/")) {
|
|
2281
|
+
this.fail(`reading the subscribers of "${name}"`, new TypeError(`a subscriber's id has no "/": "${one.id}"`));
|
|
2282
|
+
continue;
|
|
2283
|
+
}
|
|
2284
|
+
const id = handlerIdOf(`${name}/${one.id}`);
|
|
2285
|
+
if (this.handlers.has(id)) continue;
|
|
2286
|
+
let subscribing: Subscribing;
|
|
2287
|
+
let selectors: Selector[];
|
|
2288
|
+
try {
|
|
2289
|
+
subscribing = subscribingOf(`plugin "${name}", subscriber "${one.id}"`, {
|
|
2290
|
+
...(one.concurrency === undefined ? {} : { concurrency: one.concurrency }),
|
|
2291
|
+
});
|
|
2292
|
+
selectors = one.queries.map((query) => {
|
|
2293
|
+
// The position of a subscriber is its own (`from`, `until`): a query that carries one says two things.
|
|
2294
|
+
if ((query as RecordQuery).from !== undefined) throw new TypeError("a query of a subscriber has no position: the subscriber has its own");
|
|
2295
|
+
const { types, filter, stream } = resolveQuery(query);
|
|
2296
|
+
return { ...(types === undefined ? {} : { types }), ...(filter === undefined ? {} : { filter }), ...(stream === undefined ? {} : { stream }) };
|
|
2297
|
+
});
|
|
2298
|
+
} catch (error) {
|
|
2299
|
+
this.fail(`reading the subscribers of "${name}"`, new TypeError(`subscriber "${one.id}": ${error instanceof Error ? error.message : String(error)}`));
|
|
2300
|
+
continue;
|
|
2301
|
+
}
|
|
2302
|
+
this.handlers.set(id, {
|
|
2303
|
+
// A query that names no type wakes on every type: so does the subscriber.
|
|
2304
|
+
types: selectors.some((query) => query.types === undefined || query.types.length === 0) ? [] : [...new Set(selectors.flatMap((query) => query.types ?? []))],
|
|
2305
|
+
selectors,
|
|
2306
|
+
schema: undefined,
|
|
2307
|
+
version: installed.version,
|
|
2308
|
+
handler: one.handler,
|
|
2309
|
+
subscribing: { ...subscribing, from: seq(one.from) },
|
|
2310
|
+
...(one.until === undefined ? {} : { until: seq(one.until) }),
|
|
2311
|
+
});
|
|
2312
|
+
this.dynamic.add(id);
|
|
2313
|
+
this.pinned.set(pinKey(id, installed.version), {
|
|
2314
|
+
handler: one.handler,
|
|
2315
|
+
type: { kind: "record", name: recordTypeName(one.id), version: 1, schema: ANY_DATA },
|
|
2316
|
+
});
|
|
2317
|
+
}
|
|
2318
|
+
}
|
|
2319
|
+
}
|
|
2320
|
+
void journal;
|
|
2321
|
+
}
|
|
2322
|
+
|
|
2323
|
+
/**
|
|
2324
|
+
* Commit the admission of one record by one handler. When it was admitted before, on another
|
|
2325
|
+
* version, the committed one wins: the invocation runs on the version it was admitted on.
|
|
2326
|
+
*/
|
|
2327
|
+
private admit(
|
|
2328
|
+
journal: Journal,
|
|
2329
|
+
handler: HandlerId,
|
|
2330
|
+
version: PluginVersion,
|
|
2331
|
+
record: StoredRecord,
|
|
2332
|
+
keyed: { key: SubscriptionKey; cursor: Seq } | undefined,
|
|
2333
|
+
): RunSpec | undefined {
|
|
2334
|
+
const invocation = invocationId(handler, record.id);
|
|
2335
|
+
const admitted: NewRecord = {
|
|
2336
|
+
id: recordId(invocation),
|
|
2337
|
+
stream: streamId(`invocation:${invocation}`),
|
|
2338
|
+
type: CORE_TYPES.invocationAdmitted,
|
|
2339
|
+
schema: 1,
|
|
2340
|
+
data: {
|
|
2341
|
+
invocation,
|
|
2342
|
+
handler,
|
|
2343
|
+
record: record.id,
|
|
2344
|
+
recordSeq: record.seq,
|
|
2345
|
+
recordType: record.type,
|
|
2346
|
+
pluginVersion: version,
|
|
2347
|
+
...(keyed === undefined ? {} : { keyed }),
|
|
2348
|
+
},
|
|
2349
|
+
actor: { kind: "host" },
|
|
2350
|
+
cause: record.id,
|
|
2351
|
+
root: record.root,
|
|
2352
|
+
};
|
|
2353
|
+
let committed: StoredRecord | undefined;
|
|
2354
|
+
try {
|
|
2355
|
+
committed = this.append([admitted])[0];
|
|
2356
|
+
} catch (error) {
|
|
2357
|
+
if (!(error instanceof IntegrityError)) throw error;
|
|
2358
|
+
committed = journal.get(admitted.id);
|
|
2359
|
+
}
|
|
2360
|
+
return committed === undefined ? undefined : this.specOf(journal, committed, record);
|
|
2361
|
+
}
|
|
2362
|
+
|
|
2363
|
+
/**
|
|
2364
|
+
* The position of a subscription, from the journal: the farthest position it committed, through
|
|
2365
|
+
* a position record or an admission. A subscription with neither starts at the beginning,
|
|
2366
|
+
* or where the journal is now, written down once so a restart does not move it.
|
|
2367
|
+
*/
|
|
2368
|
+
private loadPosition(journal: Journal, id: HandlerId, entry: Served): Seq {
|
|
2369
|
+
const { types, subscribing: { from, concurrency } } = entry;
|
|
2370
|
+
let position = seq(0);
|
|
2371
|
+
let known = false;
|
|
2372
|
+
const last = PositionData.safeParse(
|
|
2373
|
+
journal.find({ type: CORE_TYPES.subscriptionPosition, field: "subscription", equals: id }).at(-1)?.data,
|
|
2374
|
+
);
|
|
2375
|
+
if (last.success) {
|
|
2376
|
+
position = seq(last.data.seq);
|
|
2377
|
+
known = true;
|
|
2378
|
+
}
|
|
2379
|
+
const rows = journal.find({ type: CORE_TYPES.invocationAdmitted, field: "handler", equals: id });
|
|
2380
|
+
for (const row of rows) {
|
|
2381
|
+
const data = AdmittedWithPosition.safeParse(row.data);
|
|
2382
|
+
if (!data.success) continue;
|
|
2383
|
+
if (!selectsType({ types }, data.data.recordType)) continue;
|
|
2384
|
+
known = true;
|
|
2385
|
+
const cursor = data.data.keyed?.cursor ?? data.data.recordSeq;
|
|
2386
|
+
if (cursor > position) position = seq(cursor);
|
|
2387
|
+
}
|
|
2388
|
+
if (!known && typeof from === "number") position = from;
|
|
2389
|
+
this.positions.set(id, position);
|
|
2390
|
+
this.keep(id, position);
|
|
2391
|
+
// A keyed subscription can encounter a gap before its first admission (a selector can fail).
|
|
2392
|
+
// Keep its starting position even then, so `now` does not skip that gap on restart.
|
|
2393
|
+
if (!known && (typeof concurrency !== "number" || (from === "now" && journal.query({ types }, 1).length > 0))) {
|
|
2394
|
+
if (from === "now") position = journal.last();
|
|
2395
|
+
this.positions.set(id, position);
|
|
2396
|
+
this.writePosition(id, position, "installed");
|
|
2397
|
+
}
|
|
2398
|
+
return position;
|
|
2399
|
+
}
|
|
2400
|
+
|
|
2401
|
+
// --- running ---------------------------------------------------------------
|
|
2402
|
+
|
|
2403
|
+
/** Run an invocation, or run it once more after the current run when it is running. */
|
|
2404
|
+
private schedule(spec: RunSpec, woken = false): void {
|
|
2405
|
+
const running = this.running.get(spec.invocation);
|
|
2406
|
+
if (running !== undefined) {
|
|
2407
|
+
// The run that follows is a wake only when everything that asked for it was one.
|
|
2408
|
+
running.woken = running.again ? running.woken && woken : woken;
|
|
2409
|
+
running.again = true;
|
|
2410
|
+
return;
|
|
2411
|
+
}
|
|
2412
|
+
const entry = { again: false, woken };
|
|
2413
|
+
this.running.set(spec.invocation, entry);
|
|
2414
|
+
void (async () => {
|
|
2415
|
+
// Not inside the call that scheduled it: that call may be in the middle of a commit.
|
|
2416
|
+
await Promise.resolve();
|
|
2417
|
+
try {
|
|
2418
|
+
do {
|
|
2419
|
+
entry.again = false;
|
|
2420
|
+
await this.execute(spec, entry.woken);
|
|
2421
|
+
} while (entry.again && this.journal !== undefined);
|
|
2422
|
+
} finally {
|
|
2423
|
+
this.running.delete(spec.invocation);
|
|
2424
|
+
}
|
|
2425
|
+
})();
|
|
2426
|
+
}
|
|
2427
|
+
|
|
2428
|
+
/** One run of an invocation. Never throws: what goes wrong is written down or reported. */
|
|
2429
|
+
private async execute(spec: RunSpec, woken: boolean): Promise<void> {
|
|
2430
|
+
const journal = this.journal;
|
|
2431
|
+
if (journal === undefined) return;
|
|
2432
|
+
this.unpark(spec.invocation);
|
|
2433
|
+
try {
|
|
2434
|
+
const pinned = this.pinned.get(pinKey(spec.handlerId, spec.version));
|
|
2435
|
+
if (pinned === undefined) {
|
|
2436
|
+
this.append([
|
|
2437
|
+
this.stateRecord(
|
|
2438
|
+
spec,
|
|
2439
|
+
"paused",
|
|
2440
|
+
`plugin version unavailable: version ${spec.version} of ${spec.handlerId} is not kept; move it onto the installed version with ${MOVE_ACTION}, or cancel it`,
|
|
2441
|
+
["cancel"],
|
|
2442
|
+
),
|
|
2443
|
+
]);
|
|
2444
|
+
return;
|
|
2445
|
+
}
|
|
2446
|
+
const before = journal.last();
|
|
2447
|
+
const result = await runInvocation(this.deps(journal), {
|
|
2448
|
+
id: spec.invocation,
|
|
2449
|
+
handlerId: spec.handlerId,
|
|
2450
|
+
record: spec.record,
|
|
2451
|
+
handler: pinned.handler,
|
|
2452
|
+
parse: (data: unknown) => pinned.type.schema.parse(data),
|
|
2453
|
+
woken,
|
|
2454
|
+
});
|
|
2455
|
+
if (result === "waiting") {
|
|
2456
|
+
if (this.cancelledWhileRunning.delete(spec.invocation)) this.schedule(spec);
|
|
2457
|
+
else this.park(journal, spec, before);
|
|
2458
|
+
} else this.cancelledWhileRunning.delete(spec.invocation);
|
|
2459
|
+
} catch (error) {
|
|
2460
|
+
if (this.journal === undefined) return; // the host is closed: nothing to say it to
|
|
2461
|
+
if (error instanceof LostOwnership) {
|
|
2462
|
+
this.fail(`running ${spec.invocation}`, error);
|
|
2463
|
+
return;
|
|
2464
|
+
}
|
|
2465
|
+
// Any other failure of the host is recorded as a pause, so an owner sees it.
|
|
2466
|
+
const reason = `host error: ${error instanceof Error ? error.message : String(error)}`;
|
|
2467
|
+
try {
|
|
2468
|
+
this.append([this.stateRecord(spec, "paused", reason)]);
|
|
2469
|
+
} catch (writeError) {
|
|
2470
|
+
this.fail(`recording the failure of ${spec.invocation}`, writeError);
|
|
2471
|
+
}
|
|
2472
|
+
}
|
|
2473
|
+
}
|
|
2474
|
+
|
|
2475
|
+
/**
|
|
2476
|
+
* An invocation suspended on a wait: remember what it waits for, so the record wakes it.
|
|
2477
|
+
* A record of that type committed while it was still running would find nobody waiting: it
|
|
2478
|
+
* is looked for here, in the same step, so no wake is lost.
|
|
2479
|
+
*
|
|
2480
|
+
* A wait may name one type or several: a wait for the first of several types is woken by any
|
|
2481
|
+
* of them.
|
|
2482
|
+
*/
|
|
2483
|
+
private park(journal: Journal, spec: RunSpec, before: Seq): void {
|
|
2484
|
+
const intents = journal.find({
|
|
2485
|
+
type: CORE_TYPES.stepIntent,
|
|
2486
|
+
field: "invocation",
|
|
2487
|
+
equals: spec.invocation,
|
|
2488
|
+
});
|
|
2489
|
+
// Every wait that has no outcome is open: the invocation may be suspended on several at
|
|
2490
|
+
// once (parallel steps that each wait), and a record that answers any of them must wake it.
|
|
2491
|
+
// Only the last one would lose the wake of the others: two asks in parallel wait for the same
|
|
2492
|
+
// type under different keys.
|
|
2493
|
+
const slots = new Map<string, WaitSlot>();
|
|
2494
|
+
for (const row of intents) {
|
|
2495
|
+
const data = IntentData.safeParse(row.data);
|
|
2496
|
+
if (!data.success || data.data.key === undefined) continue;
|
|
2497
|
+
const open = slotsOf(data.data);
|
|
2498
|
+
if (open.length === 0) continue;
|
|
2499
|
+
if (journal.get(attemptRecordId(spec.invocation, stepKey(data.data.key), 0, "outcome")) !== undefined) continue;
|
|
2500
|
+
for (const slot of open) slots.set(indexSlot(slot.type, slot.key), slot);
|
|
2501
|
+
}
|
|
2502
|
+
if (slots.size === 0) return;
|
|
2503
|
+
// A record that arrived while it ran wakes it only if it can match one of the waits.
|
|
2504
|
+
const arrived = [...slots.values()].some((slot) =>
|
|
2505
|
+
journal.find({ type: slot.type, after: before }).some((row) => admits(slot.key, row.data)),
|
|
2506
|
+
);
|
|
2507
|
+
if (arrived) {
|
|
2508
|
+
this.schedule(spec, true);
|
|
2509
|
+
return;
|
|
2510
|
+
}
|
|
2511
|
+
this.index(spec, [...slots.values()]);
|
|
2512
|
+
}
|
|
2513
|
+
|
|
2514
|
+
/**
|
|
2515
|
+
* A wait begun after its invocation was parked: a parallel branch of the handler that was still
|
|
2516
|
+
* going when another branch suspended it. The run has ended, so park() did not see this wait;
|
|
2517
|
+
* it is indexed here, or the record that answers it would wake nobody.
|
|
2518
|
+
*/
|
|
2519
|
+
private parkLate(record: StoredRecord): void {
|
|
2520
|
+
const data = IntentData.safeParse(record.data);
|
|
2521
|
+
if (!data.success || data.data.invocation === undefined) return;
|
|
2522
|
+
const waiting = this.waiting.get(data.data.invocation as InvocationId);
|
|
2523
|
+
if (waiting === undefined) return;
|
|
2524
|
+
this.index(waiting.spec, slotsOf(data.data));
|
|
2525
|
+
}
|
|
2526
|
+
|
|
2527
|
+
/** Put a waiting invocation in the index under the slots it waits on, besides those it has. */
|
|
2528
|
+
private index(spec: RunSpec, added: readonly WaitSlot[]): void {
|
|
2529
|
+
const had = this.waiting.get(spec.invocation)?.slots ?? [];
|
|
2530
|
+
const known = new Set(had.map((slot) => indexSlot(slot.type, slot.key)));
|
|
2531
|
+
// A slot listed twice (a wait for the same type twice) is indexed once: unpark undoes each slot
|
|
2532
|
+
// it holds, so the counts of the fields stay in step with the slots.
|
|
2533
|
+
const fresh = added.filter((slot) => {
|
|
2534
|
+
const name = indexSlot(slot.type, slot.key);
|
|
2535
|
+
if (known.has(name)) return false;
|
|
2536
|
+
known.add(name);
|
|
2537
|
+
return true;
|
|
2538
|
+
});
|
|
2539
|
+
this.waiting.set(spec.invocation, { slots: [...had, ...fresh], spec });
|
|
2540
|
+
for (const { type, key } of fresh) {
|
|
2541
|
+
const slot = indexSlot(type, key);
|
|
2542
|
+
const set = this.waitIndex.get(slot) ?? new Set<InvocationId>();
|
|
2543
|
+
set.add(spec.invocation);
|
|
2544
|
+
this.waitIndex.set(slot, set);
|
|
2545
|
+
if (key === undefined) continue;
|
|
2546
|
+
const fields = this.waitFields.get(type) ?? new Map<string, number>();
|
|
2547
|
+
fields.set(key.field, (fields.get(key.field) ?? 0) + 1);
|
|
2548
|
+
this.waitFields.set(type, fields);
|
|
2549
|
+
}
|
|
2550
|
+
}
|
|
2551
|
+
|
|
2552
|
+
/** Forget a waiting invocation: it is running, moved, or woken. */
|
|
2553
|
+
private unpark(invocation: InvocationId): void {
|
|
2554
|
+
const waiting = this.waiting.get(invocation);
|
|
2555
|
+
if (waiting === undefined) return;
|
|
2556
|
+
this.waiting.delete(invocation);
|
|
2557
|
+
for (const { type, key } of waiting.slots) {
|
|
2558
|
+
const slot = indexSlot(type, key);
|
|
2559
|
+
const set = this.waitIndex.get(slot);
|
|
2560
|
+
set?.delete(invocation);
|
|
2561
|
+
if (set?.size === 0) this.waitIndex.delete(slot);
|
|
2562
|
+
if (key === undefined) continue;
|
|
2563
|
+
const fields = this.waitFields.get(type);
|
|
2564
|
+
const left = (fields?.get(key.field) ?? 1) - 1;
|
|
2565
|
+
if (left > 0) fields?.set(key.field, left);
|
|
2566
|
+
else fields?.delete(key.field);
|
|
2567
|
+
if (fields?.size === 0) this.waitFields.delete(type);
|
|
2568
|
+
}
|
|
2569
|
+
}
|
|
2570
|
+
|
|
2571
|
+
/** The waiters a record can wake: those without a key on its type, and those whose key it carries. */
|
|
2572
|
+
private waitersOf(record: StoredRecord): InvocationId[] {
|
|
2573
|
+
const found = new Set<InvocationId>(this.waitIndex.get(indexSlot(record.type, undefined)));
|
|
2574
|
+
const data = record.data as Record<string, unknown> | null;
|
|
2575
|
+
for (const field of this.waitFields.get(record.type)?.keys() ?? []) {
|
|
2576
|
+
const value = data?.[field];
|
|
2577
|
+
if (typeof value !== "string") continue;
|
|
2578
|
+
for (const id of this.waitIndex.get(indexSlot(record.type, { field, equals: value })) ?? []) found.add(id);
|
|
2579
|
+
}
|
|
2580
|
+
return [...found];
|
|
2581
|
+
}
|
|
2582
|
+
|
|
2583
|
+
private invocationRecord(
|
|
2584
|
+
spec: RunSpec,
|
|
2585
|
+
prefix: string,
|
|
2586
|
+
type: RecordTypeName,
|
|
2587
|
+
data: object,
|
|
2588
|
+
actor: Caller = { kind: "host" },
|
|
2589
|
+
): NewRecord {
|
|
2590
|
+
return {
|
|
2591
|
+
id: newRecordId(prefix),
|
|
2592
|
+
stream: streamId(`invocation:${spec.invocation}`),
|
|
2593
|
+
type,
|
|
2594
|
+
schema: 1,
|
|
2595
|
+
data,
|
|
2596
|
+
actor,
|
|
2597
|
+
cause: spec.record.id,
|
|
2598
|
+
root: spec.record.root,
|
|
2599
|
+
};
|
|
2600
|
+
}
|
|
2601
|
+
|
|
2602
|
+
private stateRecord(spec: RunSpec, state: string, reason: string, choices?: string[]): NewRecord {
|
|
2603
|
+
return this.invocationRecord(spec, "st", CORE_TYPES.invocationState, {
|
|
2604
|
+
invocation: spec.invocation,
|
|
2605
|
+
state,
|
|
2606
|
+
reason,
|
|
2607
|
+
...(choices === undefined ? {} : { choices }),
|
|
2608
|
+
});
|
|
2609
|
+
}
|
|
2610
|
+
|
|
2611
|
+
private deps(journal: Journal): RunnerDeps {
|
|
2612
|
+
return {
|
|
2613
|
+
journal,
|
|
2614
|
+
artifacts: this.artifacts,
|
|
2615
|
+
now: () => this.clock.now(),
|
|
2616
|
+
append: (records) => this.append(records),
|
|
2617
|
+
appendAll: (entries, batch) => this.appendAll(entries, batch),
|
|
2618
|
+
resolveAction: (name) => this.resolveActionByName(name),
|
|
2619
|
+
interceptsOf: (name) => {
|
|
2620
|
+
try {
|
|
2621
|
+
return this.intercepts.get(actionName(name)) ?? NO_INTERCEPTS;
|
|
2622
|
+
} catch {
|
|
2623
|
+
return NO_INTERCEPTS; // not a valid name: no such action
|
|
2624
|
+
}
|
|
2625
|
+
},
|
|
2626
|
+
standingOf: (caller) => this.access.standing(caller),
|
|
2627
|
+
emit: async (action, caller, entries, batch, claim) => this.emitAs(action, caller, entries, batch, claim),
|
|
2628
|
+
admitEmit: (caller, name, data) => {
|
|
2629
|
+
const declared = this.declaredType(name);
|
|
2630
|
+
if (declared === undefined) throw new UnknownType(name);
|
|
2631
|
+
this.permitEmit(caller, name);
|
|
2632
|
+
const parsed = declared.schema.safeParse(data);
|
|
2633
|
+
if (!parsed.success) throw new ValidationError(`the data of "${name}" is not valid`, parsed.error.issues);
|
|
2634
|
+
return { data: parsed.data, version: declared.version };
|
|
2635
|
+
},
|
|
2636
|
+
};
|
|
2637
|
+
}
|
|
2638
|
+
|
|
2639
|
+
/** A failure nobody is waiting for: the journal was taken over, or it is told to the operator. */
|
|
2640
|
+
private fail(what: string, error: unknown): void {
|
|
2641
|
+
if (error instanceof LostOwnership) {
|
|
2642
|
+
// The journal was taken over: this host is no longer the writer and writes nothing more.
|
|
2643
|
+
console.error(`niwa: ${error.name}: lost the journal of ${this.home}: ${error.message}; this host stops`);
|
|
2644
|
+
void this.close();
|
|
2645
|
+
} else if (this.journal !== undefined) {
|
|
2646
|
+
console.error(`niwa: ${what} failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
2647
|
+
}
|
|
2648
|
+
}
|
|
2649
|
+
|
|
2650
|
+
// --- writing ---------------------------------------------------------------
|
|
2651
|
+
|
|
2652
|
+
/** Commit the records, then publish them. */
|
|
2653
|
+
private append(records: NewRecord[]): StoredRecord[] {
|
|
2654
|
+
return this.appendAll(records.map((record) => ({ record })));
|
|
2655
|
+
}
|
|
2656
|
+
|
|
2657
|
+
/** Commit the records with their links, then publish them. */
|
|
2658
|
+
private appendAll(entries: AppendEntry[], batch?: RecordId): StoredRecord[] {
|
|
2659
|
+
let committed: StoredRecord[];
|
|
2660
|
+
try {
|
|
2661
|
+
committed = this.requireJournal().appendAll(entries, batch);
|
|
2662
|
+
} catch (error) {
|
|
2663
|
+
if (error instanceof RecordRefused && error.newlyRecorded) this.publish([error.audit]);
|
|
2664
|
+
throw error;
|
|
2665
|
+
}
|
|
2666
|
+
// What a record of access says takes effect before anything that watches the journal reacts.
|
|
2667
|
+
for (const row of committed) if (ACCESS_TYPES.has(row.type)) this.doors?.fold(row);
|
|
2668
|
+
this.publish(committed);
|
|
2669
|
+
return committed;
|
|
2670
|
+
}
|
|
2671
|
+
|
|
2672
|
+
/**
|
|
2673
|
+
* Hand committed records to the observers, and wake the work that waits for them.
|
|
2674
|
+
*
|
|
2675
|
+
* Every record reaches the feeds before anything reacts: a reaction writes records of its own,
|
|
2676
|
+
* and those must not overtake the rest of this commit.
|
|
2677
|
+
*/
|
|
2678
|
+
private publish(records: StoredRecord[]): void {
|
|
2679
|
+
for (const wake of [...this.commitWaiters]) wake();
|
|
2680
|
+
for (const feed of this.feeds) {
|
|
2681
|
+
for (const record of records) feed.push(record);
|
|
2682
|
+
}
|
|
2683
|
+
for (const record of records) {
|
|
2684
|
+
if (record.type === CORE_TYPES.stepIntent) this.parkLate(record);
|
|
2685
|
+
if (record.type === CORE_TYPES.invocationState) {
|
|
2686
|
+
const state = StateData.safeParse(record.data);
|
|
2687
|
+
if (state.success && state.data.state === "done") this.release(state.data.invocation as InvocationId);
|
|
2688
|
+
}
|
|
2689
|
+
if (CORE_TYPE_NAMES.has(record.type)) {
|
|
2690
|
+
// A closed grant is the one core record that plugins react to: they stop what it covered.
|
|
2691
|
+
if (record.type === CORE_TYPES.accessClosed) this.requestPump();
|
|
2692
|
+
continue;
|
|
2693
|
+
}
|
|
2694
|
+
for (const invocation of this.waitersOf(record)) {
|
|
2695
|
+
const waiting = this.waiting.get(invocation);
|
|
2696
|
+
if (waiting === undefined) continue;
|
|
2697
|
+
this.unpark(invocation);
|
|
2698
|
+
this.schedule(waiting.spec, true);
|
|
2699
|
+
}
|
|
2700
|
+
this.requestPump();
|
|
2701
|
+
}
|
|
2702
|
+
}
|
|
2703
|
+
|
|
2704
|
+
// --- the public API --------------------------------------------------------
|
|
2705
|
+
|
|
2706
|
+
async emit<T>(type: RecordType<T>, data: T, opts?: EmitOptions): Promise<StoredRecord> {
|
|
2707
|
+
return this.write({ kind: "host" }, type.name, data, opts);
|
|
2708
|
+
}
|
|
2709
|
+
|
|
2710
|
+
async emitAll<const T extends readonly AnyType[]>(entries: EmitBatch<T, EmitOptions>): Promise<StoredRecord[]> {
|
|
2711
|
+
return this.appendAll(entries.map(({type, data, opts}) => this.externalEntry({kind: "host"}, type.name, data, opts)));
|
|
2712
|
+
}
|
|
2713
|
+
|
|
2714
|
+
async trace(id: RecordId): Promise<TracedRecord[]> {
|
|
2715
|
+
return trace(this.requireJournal(), id);
|
|
2716
|
+
}
|
|
2717
|
+
|
|
2718
|
+
async causes(id: RecordId): Promise<StoredRecord[]> {
|
|
2719
|
+
return causes(this.requireJournal(), id);
|
|
2720
|
+
}
|
|
2721
|
+
|
|
2722
|
+
async call<I, O, In = I>(target: ActionTarget<I, O, In>, input: NoInfer<In>, opts?: CallOptions): Promise<O> {
|
|
2723
|
+
return this.runAction({ kind: "host" }, target, input, false, opts?.reason);
|
|
2724
|
+
}
|
|
2725
|
+
|
|
2726
|
+
readonly records = {
|
|
2727
|
+
// The host reads its own journal: nothing stands between the call and the subscription, so it is ready as made.
|
|
2728
|
+
since: (query?: RecordQuery<any>): RecordFeed => Object.assign(this.subscribe(resolveQuery(query)), { ready: Promise.resolve() }),
|
|
2729
|
+
read: async (query?: RecordReadQuery<any>): Promise<StoredRecord[]> => this.readHistory(resolveQuery(query), query?.limit),
|
|
2730
|
+
};
|
|
2731
|
+
|
|
2732
|
+
/**
|
|
2733
|
+
* The history that answers a query, read once.
|
|
2734
|
+
*
|
|
2735
|
+
* The read is a plain question to the journal: the records that are committed now, in commit
|
|
2736
|
+
* order, and nothing that comes later. It ends by itself, so a reader never has to guess when
|
|
2737
|
+
* the history is read.
|
|
2738
|
+
*/
|
|
2739
|
+
private readHistory(query: ResolvedQuery, limit?: number): StoredRecord[] {
|
|
2740
|
+
const journal = this.requireJournal();
|
|
2741
|
+
if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
|
|
2742
|
+
throw new TypeError(`the limit of a read must be a positive integer, got ${String(limit)}`);
|
|
2743
|
+
}
|
|
2744
|
+
return journal.query(query, limit);
|
|
2745
|
+
}
|
|
2746
|
+
|
|
2747
|
+
/**
|
|
2748
|
+
* History after a position, then the live records, with no gap and no duplicate. The feed is
|
|
2749
|
+
* registered in the same step that reads the history, so nothing is committed in between.
|
|
2750
|
+
*/
|
|
2751
|
+
private async *subscribe(
|
|
2752
|
+
query: ResolvedQuery,
|
|
2753
|
+
owner?: Set<Feed>,
|
|
2754
|
+
): AsyncGenerator<StoredRecord, void, undefined> {
|
|
2755
|
+
const journal = this.requireJournal();
|
|
2756
|
+
const feed = new Feed(query);
|
|
2757
|
+
this.feeds.add(feed);
|
|
2758
|
+
owner?.add(feed);
|
|
2759
|
+
try {
|
|
2760
|
+
let cursor = query.from ?? seq(0);
|
|
2761
|
+
for (const record of journal.query(query)) {
|
|
2762
|
+
cursor = record.seq;
|
|
2763
|
+
yield record;
|
|
2764
|
+
}
|
|
2765
|
+
yield* feed.iterate(cursor);
|
|
2766
|
+
} finally {
|
|
2767
|
+
this.feeds.delete(feed);
|
|
2768
|
+
owner?.delete(feed);
|
|
2769
|
+
}
|
|
2770
|
+
}
|
|
2771
|
+
|
|
2772
|
+
/** What niwa is: the actions and record types the loaded plugins declared. */
|
|
2773
|
+
async describe(): Promise<Description> {
|
|
2774
|
+
return buildDescription({ actions: this.allActions(), types: this.types.values() });
|
|
2775
|
+
}
|
|
2776
|
+
|
|
2777
|
+
readonly live = {
|
|
2778
|
+
send: async (channel: string, frame: LiveFrame): Promise<void> => {
|
|
2779
|
+
this.liveBus.send(channelName(channel), frameFor(channel, frame));
|
|
2780
|
+
},
|
|
2781
|
+
subscribe: (channel: string): LiveSubscription => this.liveBus.subscribe(channelName(channel)).iterate(),
|
|
2782
|
+
};
|
|
2783
|
+
|
|
2784
|
+
/**
|
|
2785
|
+
* Write an external input: it starts its own chain.
|
|
2786
|
+
*
|
|
2787
|
+
* With an explicit id the write is idempotent: the same id with the same content returns the
|
|
2788
|
+
* record that is already committed, and the same id with different content is an integrity
|
|
2789
|
+
* error that writes nothing. Only a declared type is written: the core's own are not.
|
|
2790
|
+
*/
|
|
2791
|
+
private async write(
|
|
2792
|
+
caller: Caller,
|
|
2793
|
+
name: RecordTypeName,
|
|
2794
|
+
data: unknown,
|
|
2795
|
+
opts?: EmitOptions,
|
|
2796
|
+
): Promise<StoredRecord> {
|
|
2797
|
+
return this.appendAll([this.externalEntry(caller, name, data, opts)])[0]!;
|
|
2798
|
+
}
|
|
2799
|
+
|
|
2800
|
+
private writeOwned(own: readonly AnyType[], entries: EmitBatch<readonly AnyType[], EmitOptions>): StoredRecord[] {
|
|
2801
|
+
return this.appendAll(entries.map(({type, data, opts}) => {
|
|
2802
|
+
if (!own.some(declared => declared.name === type.name)) throw new UnknownType(type.name);
|
|
2803
|
+
return this.externalEntry({ kind: "host" }, type.name, data, opts);
|
|
2804
|
+
}));
|
|
2805
|
+
}
|
|
2806
|
+
|
|
2807
|
+
private externalEntry(caller: Caller, name: RecordTypeName, data: unknown, opts?: EmitOptions): AppendEntry {
|
|
2808
|
+
const declared = this.declaredType(name);
|
|
2809
|
+
if (declared === undefined) throw new UnknownType(name);
|
|
2810
|
+
const parsed = declared.schema.safeParse(data);
|
|
2811
|
+
if (!parsed.success) {
|
|
2812
|
+
throw new ValidationError(`the data of "${name}" is not valid`, parsed.error.issues);
|
|
2813
|
+
}
|
|
2814
|
+
const id = opts?.id === undefined ? newRecordId("rec") : recordId(opts.id);
|
|
2815
|
+
return {
|
|
2816
|
+
record: {id, stream: streamId(`input:${name}`), type: name, schema: declared.version,
|
|
2817
|
+
data: parsed.data, actor: caller, cause: null, root: id},
|
|
2818
|
+
links: opts?.links,
|
|
2819
|
+
};
|
|
2820
|
+
}
|
|
2821
|
+
|
|
2822
|
+
/**
|
|
2823
|
+
* The action of this host under this name, when there is one.
|
|
2824
|
+
*
|
|
2825
|
+
* A name nobody serves is nothing: the caller is told so instead of being given an action
|
|
2826
|
+
* that is not there.
|
|
2827
|
+
*/
|
|
2828
|
+
private resolveActionByName(name: string): AnyAction | undefined {
|
|
2829
|
+
try {
|
|
2830
|
+
return this.actionOf(actionName(name));
|
|
2831
|
+
} catch {
|
|
2832
|
+
return undefined; // not a valid name: no such action
|
|
2833
|
+
}
|
|
2834
|
+
}
|
|
2835
|
+
|
|
2836
|
+
/**
|
|
2837
|
+
* Write a record on behalf of a call.
|
|
2838
|
+
*
|
|
2839
|
+
* The record is written under the stream of the caller: a handler's write belongs to the
|
|
2840
|
+
* invocation it runs in, and a call outside an invocation starts a chain of its own. The
|
|
2841
|
+
* schema of the type is the one that was declared, so the data is checked before it is kept.
|
|
2842
|
+
*/
|
|
2843
|
+
private emitAs(
|
|
2844
|
+
action: ActionName, caller: Caller,
|
|
2845
|
+
entries: readonly { type: AnyType; data: unknown; place: Placement }[], batch?: RecordId, terminalClaimOf?: OperationId,
|
|
2846
|
+
): StoredRecord[] {
|
|
2847
|
+
const owned = this.typesOfAction(action);
|
|
2848
|
+
return this.appendAll(entries.map(({type, data, place}) => {
|
|
2849
|
+
const declared = this.declaredType(type.name);
|
|
2850
|
+
if (declared === undefined || !owned?.has(declared.name)) throw new UnknownType(type.name);
|
|
2851
|
+
const parsed = declared.schema.safeParse(data);
|
|
2852
|
+
if (!parsed.success) throw new ValidationError(`the data of "${type.name}" is not valid`, parsed.error.issues);
|
|
2853
|
+
const actor = declared.providerOnly === undefined ? caller : { ...caller, issuedBy: declared.providerOnly };
|
|
2854
|
+
return { record: { ...place, type: type.name, schema: declared.version, data: parsed.data, actor }, terminalClaimOf };
|
|
2855
|
+
}), batch);
|
|
2856
|
+
}
|
|
2857
|
+
|
|
2858
|
+
/** Call an action outside any invocation: not a step, not journaled. */
|
|
2859
|
+
private async runAction<I, O, In = I>(
|
|
2860
|
+
caller: Caller,
|
|
2861
|
+
target: ActionTarget<I, O, In>,
|
|
2862
|
+
input: NoInfer<In>,
|
|
2863
|
+
atDoor = false,
|
|
2864
|
+
reason?: string,
|
|
2865
|
+
made?: MadeUnder,
|
|
2866
|
+
): Promise<O> {
|
|
2867
|
+
const result = await this.outsideCall<I, O, In>(caller, target, input, atDoor, reason, made);
|
|
2868
|
+
switch (result.kind) {
|
|
2869
|
+
case "completed":
|
|
2870
|
+
return result.value;
|
|
2871
|
+
case "unknown-action":
|
|
2872
|
+
throw new UnknownAction(result.action);
|
|
2873
|
+
case "denied":
|
|
2874
|
+
throw new DeniedError(result.reason, result.denied);
|
|
2875
|
+
case "invalid-input":
|
|
2876
|
+
case "invalid-output":
|
|
2877
|
+
throw new ValidationError(result.message, result.issues);
|
|
2878
|
+
}
|
|
2879
|
+
}
|
|
2880
|
+
|
|
2881
|
+
/**
|
|
2882
|
+
* The call itself: the action runs, and what it ended with is here.
|
|
2883
|
+
*
|
|
2884
|
+
* `atDoor` is the call a client made over the socket: its grant decides it. What an action calls
|
|
2885
|
+
* inside itself is the plugin's own work and is not matched against the caller's grant again.
|
|
2886
|
+
*/
|
|
2887
|
+
private async outsideCall<I, O, In = I>(
|
|
2888
|
+
caller: Caller,
|
|
2889
|
+
target: ActionTarget<I, O, In>,
|
|
2890
|
+
input: NoInfer<In>,
|
|
2891
|
+
atDoor = false,
|
|
2892
|
+
reason?: string,
|
|
2893
|
+
made?: MadeUnder,
|
|
2894
|
+
): Promise<OutsideCall<O>> {
|
|
2895
|
+
const name = targetName(target);
|
|
2896
|
+
const found = this.actionOf(name);
|
|
2897
|
+
if (found === undefined) {
|
|
2898
|
+
// A subject that may not call a name is not told whether it exists.
|
|
2899
|
+
const standing = atDoor ? this.access.standing(caller) : undefined;
|
|
2900
|
+
const answer = standing === undefined ? undefined : permit(standing, "call", name);
|
|
2901
|
+
if (standing === undefined || answer === undefined || answer.allowed) return { kind: "unknown-action", action: name };
|
|
2902
|
+
const record = this.access.decided(caller, standing, "call", name, answer);
|
|
2903
|
+
const denied = this.detailsOf(answer, record);
|
|
2904
|
+
return { kind: "denied", reason: answer.reason, ...(denied === undefined ? {} : { denied }) };
|
|
2905
|
+
}
|
|
2906
|
+
// The same point every call passes through: the intercepts decide, and a call that was denied
|
|
2907
|
+
// is refused with the code "Denied".
|
|
2908
|
+
const standing = atDoor ? this.access.standing(caller) : undefined;
|
|
2909
|
+
const decision = await decide({
|
|
2910
|
+
intercepts: this.intercepts.get(name) ?? NO_INTERCEPTS,
|
|
2911
|
+
action: found,
|
|
2912
|
+
input,
|
|
2913
|
+
caller,
|
|
2914
|
+
...(standing === undefined ? {} : { standing, ask: this.askOwner() }),
|
|
2915
|
+
...(reason === undefined ? {} : { reason }),
|
|
2916
|
+
});
|
|
2917
|
+
// A subject a grant limits has every decision written down, whether it ran or not.
|
|
2918
|
+
const written =
|
|
2919
|
+
standing === undefined || decision.kind === "invalid"
|
|
2920
|
+
? undefined
|
|
2921
|
+
: this.access.decided(
|
|
2922
|
+
caller,
|
|
2923
|
+
standing,
|
|
2924
|
+
"call",
|
|
2925
|
+
name,
|
|
2926
|
+
decision.access ?? (decision.kind === "denied" ? { allowed: false, reason: decision.reason } : { allowed: true }),
|
|
2927
|
+
);
|
|
2928
|
+
if (decision.kind === "invalid") {
|
|
2929
|
+
return {
|
|
2930
|
+
kind: "invalid-input",
|
|
2931
|
+
// The wire carries only the message, so what the schema said goes in it: a caller that
|
|
2932
|
+
// is told only "not valid" cannot tell which field to fix.
|
|
2933
|
+
message: refusalMessage(name, decision.issues),
|
|
2934
|
+
issues: decision.issues,
|
|
2935
|
+
};
|
|
2936
|
+
}
|
|
2937
|
+
if (decision.kind === "denied") {
|
|
2938
|
+
const denied = decision.access === undefined ? undefined : this.detailsOf(decision.access, written);
|
|
2939
|
+
return { kind: "denied", reason: decision.reason, ...(denied === undefined ? {} : { denied }) };
|
|
2940
|
+
}
|
|
2941
|
+
// A call the client named runs under the operation id made from its name, and says it began.
|
|
2942
|
+
const operation = made?.operation ?? newOperationId();
|
|
2943
|
+
made?.began();
|
|
2944
|
+
let previous: Pick<StoredRecord, "id" | "root"> | undefined;
|
|
2945
|
+
const output = await found.run(decision.final, {
|
|
2946
|
+
operationId: operation,
|
|
2947
|
+
caller,
|
|
2948
|
+
...(decision.access?.allowed === true && decision.access.answered !== undefined ? { answered: decision.access.answered } : {}),
|
|
2949
|
+
// A call outside an invocation starts a chain of its own: the first record has no cause
|
|
2950
|
+
// and is its own root, and the later ones of the same call belong to it. Every record
|
|
2951
|
+
// after the first hangs on the one before it, so the trace down from the root reaches
|
|
2952
|
+
// all of them.
|
|
2953
|
+
...actionEmits(async (entries, batch) => {
|
|
2954
|
+
let tail = previous;
|
|
2955
|
+
const placed = entries.map(({type, data, ordinal}) => {
|
|
2956
|
+
const id = recordId(`${operation}/emit/${ordinal}`);
|
|
2957
|
+
const place: Placement = {id, stream: streamId(`input:${type.name}`), cause: tail?.id ?? null, root: tail?.root ?? id};
|
|
2958
|
+
tail = place;
|
|
2959
|
+
return {type, data, place};
|
|
2960
|
+
});
|
|
2961
|
+
try {
|
|
2962
|
+
const rows = this.emitAs(name, made?.actor ?? caller, placed, batch === undefined ? undefined : recordId(`${operation}/batch/${batch}`));
|
|
2963
|
+
previous = rows.at(-1) ?? previous;
|
|
2964
|
+
return rows;
|
|
2965
|
+
} catch (error) {
|
|
2966
|
+
if (error instanceof RecordRefused) previous = error.audit;
|
|
2967
|
+
throw error;
|
|
2968
|
+
}
|
|
2969
|
+
}),
|
|
2970
|
+
// A call outside an invocation has no invocation to suspend, so it cannot wait. The
|
|
2971
|
+
// answer is looked for and its absence is reported: the caller asked for something that
|
|
2972
|
+
// is not there, and that is said rather than waited for.
|
|
2973
|
+
wait: async <T>(type: RecordType<T>, query?: WaitQuery<T>): Promise<Waited<T>> => {
|
|
2974
|
+
const entry = { type, ...(query?.filter === undefined ? {} : { filter: query.filter }) };
|
|
2975
|
+
const found = findWaited(this.requireJournal(), [entry], query?.from ?? seq(0));
|
|
2976
|
+
if (found === undefined) throw new Error(`no record of "${type.name}" has arrived`);
|
|
2977
|
+
return { data: found.data as T, at: found.at };
|
|
2978
|
+
},
|
|
2979
|
+
// A call outside an invocation cannot wait either: the answer is looked for and its
|
|
2980
|
+
// absence is reported. The oldest record of the types that matches is the answer.
|
|
2981
|
+
waitAnyOf: async <Entries extends readonly WaitEntry<any>[]>(
|
|
2982
|
+
entries: Entries,
|
|
2983
|
+
opts?: { readonly from?: Seq },
|
|
2984
|
+
): Promise<AnyWaited<Entries[number]["type"]>> => {
|
|
2985
|
+
const found = findWaited(this.requireJournal(), entries, opts?.from ?? seq(0));
|
|
2986
|
+
if (found !== undefined) return found as AnyWaited<Entries[number]["type"]>;
|
|
2987
|
+
throw new Error(`no record of ${entries.map((entry) => `"${entry.type.name}"`).join(" or ")} has arrived`);
|
|
2988
|
+
},
|
|
2989
|
+
// A call made inside a call outside an invocation is a call outside an invocation too:
|
|
2990
|
+
// there is no invocation to record it in, so it goes through the same point as any other
|
|
2991
|
+
// call, with the same caller.
|
|
2992
|
+
step: this.outsideStep(caller),
|
|
2993
|
+
});
|
|
2994
|
+
const checked = found.output.safeParse(output);
|
|
2995
|
+
if (!checked.success) {
|
|
2996
|
+
return {
|
|
2997
|
+
kind: "invalid-output",
|
|
2998
|
+
message: `the output of "${name}" is not valid`,
|
|
2999
|
+
issues: checked.error.issues,
|
|
3000
|
+
};
|
|
3001
|
+
}
|
|
3002
|
+
return { kind: "completed", value: checked.data };
|
|
3003
|
+
}
|
|
3004
|
+
|
|
3005
|
+
/**
|
|
3006
|
+
* The step an action is given outside an invocation.
|
|
3007
|
+
*
|
|
3008
|
+
* There is no invocation to record the call in, so it is a direct call: it goes through the
|
|
3009
|
+
* same point as any other call, with the same caller, and it is not durable — as direct calls
|
|
3010
|
+
* are today. The records it writes hang on the record before it, as the records of any other
|
|
3011
|
+
* call outside an invocation do.
|
|
3012
|
+
*/
|
|
3013
|
+
private outsideStep(caller: Caller): ActionStep {
|
|
3014
|
+
const call = async <I, O, In = I>(
|
|
3015
|
+
target: ActionTarget<I, O, In>,
|
|
3016
|
+
input: NoInfer<In>,
|
|
3017
|
+
): Promise<O> => {
|
|
3018
|
+
const result = await this.outsideCall<I, O, In>(caller, target, input);
|
|
3019
|
+
switch (result.kind) {
|
|
3020
|
+
case "completed":
|
|
3021
|
+
return result.value;
|
|
3022
|
+
case "unknown-action":
|
|
3023
|
+
throw new UnknownAction(result.action);
|
|
3024
|
+
case "denied":
|
|
3025
|
+
throw new DeniedError(result.reason);
|
|
3026
|
+
case "invalid-input":
|
|
3027
|
+
case "invalid-output":
|
|
3028
|
+
throw new ValidationError(result.message, result.issues);
|
|
3029
|
+
}
|
|
3030
|
+
};
|
|
3031
|
+
return Object.assign(call, {
|
|
3032
|
+
outcome: async <I, O, In = I>(
|
|
3033
|
+
target: ActionTarget<I, O, In>,
|
|
3034
|
+
input: NoInfer<In>,
|
|
3035
|
+
): Promise<Outcome<O>> => {
|
|
3036
|
+
let result: Awaited<ReturnType<typeof this.outsideCall<I, O, In>>>;
|
|
3037
|
+
try {
|
|
3038
|
+
result = await this.outsideCall<I, O, In>(caller, target, input);
|
|
3039
|
+
} catch (error) {
|
|
3040
|
+
// An error the caller catches belongs to the code that called the action, here as in an
|
|
3041
|
+
// invocation.
|
|
3042
|
+
if (error instanceof CatchableError) throw error;
|
|
3043
|
+
// An action that throws is a failed outcome, as it is for a step inside an invocation:
|
|
3044
|
+
// the code asked for the outcome, not for an exception. It may have done something unless it
|
|
3045
|
+
// says it sent nothing.
|
|
3046
|
+
return { status: "failed", error: error instanceof Error ? error.message : String(error), effectPossible: effectPossibleAfter(error) };
|
|
3047
|
+
}
|
|
3048
|
+
switch (result.kind) {
|
|
3049
|
+
case "completed":
|
|
3050
|
+
return { status: "completed", value: result.value };
|
|
3051
|
+
case "denied":
|
|
3052
|
+
return { status: "denied", reason: result.reason };
|
|
3053
|
+
case "unknown-action":
|
|
3054
|
+
return {
|
|
3055
|
+
status: "failed",
|
|
3056
|
+
error: new UnknownAction(result.action).message,
|
|
3057
|
+
effectPossible: false,
|
|
3058
|
+
};
|
|
3059
|
+
// The body never started: nothing can have happened.
|
|
3060
|
+
case "invalid-input":
|
|
3061
|
+
return { status: "failed", error: result.message, effectPossible: false };
|
|
3062
|
+
// The body ran and its answer was refused: what it did may have happened.
|
|
3063
|
+
case "invalid-output":
|
|
3064
|
+
return { status: "failed", error: result.message, effectPossible: true };
|
|
3065
|
+
}
|
|
3066
|
+
},
|
|
3067
|
+
});
|
|
3068
|
+
}
|
|
3069
|
+
|
|
3070
|
+
async close(): Promise<void> {
|
|
3071
|
+
if (this.closed) return;
|
|
3072
|
+
this.closed = true;
|
|
3073
|
+
// A read that waits for a commit is let go: the host serves no more.
|
|
3074
|
+
for (const wake of [...this.commitWaiters]) wake();
|
|
3075
|
+
// Bun removes the socket path when a listener stops, so a listener is stopped only while
|
|
3076
|
+
// the file on the path is still this host's: after a take-over it is the new holder's.
|
|
3077
|
+
const owned = this.ownsSocketFile();
|
|
3078
|
+
if (owned) this.server?.stop(true);
|
|
3079
|
+
this.server = undefined;
|
|
3080
|
+
for (const connection of this.connections) connection.drop();
|
|
3081
|
+
this.connections.clear();
|
|
3082
|
+
for (const feed of this.feeds) feed.close();
|
|
3083
|
+
this.feeds.clear();
|
|
3084
|
+
this.liveBus.close();
|
|
3085
|
+
this.waiting.clear();
|
|
3086
|
+
this.waitIndex.clear();
|
|
3087
|
+
this.waitFields.clear();
|
|
3088
|
+
// The services stop before the journal closes: a service that is still writing must find the
|
|
3089
|
+
// journal open, and a service that writes after the close would fail for no good reason.
|
|
3090
|
+
for (const name of [...this.stoppers.keys()]) this.stopServicesOf(name);
|
|
3091
|
+
// A service that owns processes releases them asynchronously: the host waits for it, so no
|
|
3092
|
+
// child of the host outlives the host.
|
|
3093
|
+
while (this.stopping.length > 0) {
|
|
3094
|
+
await Promise.all(this.stopping.splice(0));
|
|
3095
|
+
}
|
|
3096
|
+
this.journal?.close();
|
|
3097
|
+
this.journal = undefined;
|
|
3098
|
+
this.doors = undefined;
|
|
3099
|
+
this.socketFile = undefined;
|
|
3100
|
+
}
|
|
3101
|
+
|
|
3102
|
+
/** Is the socket file on the path still the one this host bound? */
|
|
3103
|
+
private ownsSocketFile(): boolean {
|
|
3104
|
+
return this.socketFile !== undefined && socketIdentity(socketPath(this.home)) === this.socketFile;
|
|
3105
|
+
}
|
|
3106
|
+
|
|
3107
|
+
// --- the socket ------------------------------------------------------------
|
|
3108
|
+
|
|
3109
|
+
private async handleMessage(connection: Connection, raw: unknown): Promise<void> {
|
|
3110
|
+
let message;
|
|
3111
|
+
try {
|
|
3112
|
+
message = decodeClientMessage(raw);
|
|
3113
|
+
} catch (error) {
|
|
3114
|
+
const id = requestIdOf(raw);
|
|
3115
|
+
if (id !== undefined) refuse(connection, id, error);
|
|
3116
|
+
return;
|
|
3117
|
+
}
|
|
3118
|
+
const caller = this.callerOf(connection);
|
|
3119
|
+
switch (message.op) {
|
|
3120
|
+
case "hello":
|
|
3121
|
+
if (connection.greet(message.client, this.doors?.holderOf(message.token))) {
|
|
3122
|
+
connection.send({ id: message.id, ok: true, value: { client: connection.caller } });
|
|
3123
|
+
} else {
|
|
3124
|
+
refuse(connection, message.id, new Error("this connection said hello already"));
|
|
3125
|
+
}
|
|
3126
|
+
return;
|
|
3127
|
+
case "call": {
|
|
3128
|
+
const { action: target, input, operation } = message;
|
|
3129
|
+
return reply(connection, message.id, async () => {
|
|
3130
|
+
if (operation === undefined) return this.runAction(caller, target, input, true, message.reason);
|
|
3131
|
+
this.operations.requireNamed(connection.isNamed, operation);
|
|
3132
|
+
const recovery = this.actionOf(target)?.recovery;
|
|
3133
|
+
return await this.operations.once(caller, operation, target, input, recovery, (id, began, actor) =>
|
|
3134
|
+
this.runAction(caller, target, input, true, message.reason, { operation: id, began, actor }),
|
|
3135
|
+
);
|
|
3136
|
+
});
|
|
3137
|
+
}
|
|
3138
|
+
case "emit": {
|
|
3139
|
+
const { type, data, record, links } = message;
|
|
3140
|
+
return reply(connection, message.id, async () => {
|
|
3141
|
+
this.permitEmit(caller, type);
|
|
3142
|
+
return this.write(caller, type, data, { id: record, links });
|
|
3143
|
+
});
|
|
3144
|
+
}
|
|
3145
|
+
case "emitAll":
|
|
3146
|
+
return reply(connection, message.id, async () => this.appendAll(message.entries.map(({type, data, record, links}) => {
|
|
3147
|
+
this.permitEmit(caller, type);
|
|
3148
|
+
return this.externalEntry(caller, type, data, {id: record, links});
|
|
3149
|
+
})));
|
|
3150
|
+
case "trace":
|
|
3151
|
+
return reply(connection, message.id, async () => {
|
|
3152
|
+
await this.authorize(caller, "call", TRACE_ACTION);
|
|
3153
|
+
return this.trace(message.record);
|
|
3154
|
+
});
|
|
3155
|
+
case "causes":
|
|
3156
|
+
return reply(connection, message.id, async () => {
|
|
3157
|
+
await this.authorize(caller, "call", CAUSES_ACTION);
|
|
3158
|
+
return this.causes(message.record);
|
|
3159
|
+
});
|
|
3160
|
+
case "describe":
|
|
3161
|
+
return reply(connection, message.id, () => this.describe());
|
|
3162
|
+
case "live.send": {
|
|
3163
|
+
const { channel, data } = message;
|
|
3164
|
+
return reply(connection, message.id, async () => {
|
|
3165
|
+
this.liveBus.send(channel, { channel, data });
|
|
3166
|
+
return null;
|
|
3167
|
+
});
|
|
3168
|
+
}
|
|
3169
|
+
case "live.subscribe": {
|
|
3170
|
+
const { id, channel } = message;
|
|
3171
|
+
// Registered before the answer goes out: a frame sent right after it is not lost.
|
|
3172
|
+
const feed = this.liveBus.subscribe(channel);
|
|
3173
|
+
connection.liveFeeds.add(feed);
|
|
3174
|
+
connection.send({ id, ok: true, value: null });
|
|
3175
|
+
try {
|
|
3176
|
+
for await (const frame of feed.iterate()) {
|
|
3177
|
+
if (!connection.isOpen) break;
|
|
3178
|
+
connection.sendLive({ id, frame });
|
|
3179
|
+
}
|
|
3180
|
+
} finally {
|
|
3181
|
+
feed.close();
|
|
3182
|
+
connection.liveFeeds.delete(feed);
|
|
3183
|
+
}
|
|
3184
|
+
return;
|
|
3185
|
+
}
|
|
3186
|
+
case "read": {
|
|
3187
|
+
const { query, limit } = message;
|
|
3188
|
+
return reply(connection, message.id, async () => {
|
|
3189
|
+
await this.authorize(caller, "call", RECORDS_READ_ACTION);
|
|
3190
|
+
return this.readHistory(resolveQuery(query), limit);
|
|
3191
|
+
});
|
|
3192
|
+
}
|
|
3193
|
+
case "since": {
|
|
3194
|
+
const { id, query } = message;
|
|
3195
|
+
// The subscription is a read of the same journal: it is held to the same grant, and a
|
|
3196
|
+
// refusal is the first answer, before any record.
|
|
3197
|
+
try {
|
|
3198
|
+
await this.authorize(caller, "call", RECORDS_READ_ACTION);
|
|
3199
|
+
} catch (error) {
|
|
3200
|
+
refuse(connection, id, error);
|
|
3201
|
+
return;
|
|
3202
|
+
}
|
|
3203
|
+
connection.send({ id, ok: true, value: null });
|
|
3204
|
+
try {
|
|
3205
|
+
for await (const record of this.subscribe(resolveQuery(query), connection.feeds)) {
|
|
3206
|
+
if (!connection.isOpen) break;
|
|
3207
|
+
connection.send({ id, record });
|
|
3208
|
+
}
|
|
3209
|
+
} catch {
|
|
3210
|
+
connection.end();
|
|
3211
|
+
}
|
|
3212
|
+
return;
|
|
3213
|
+
}
|
|
3214
|
+
}
|
|
3215
|
+
}
|
|
3216
|
+
}
|
|
3217
|
+
|
|
3218
|
+
/** Answer a request with what the work gives, or say what went wrong. */
|
|
3219
|
+
async function reply(
|
|
3220
|
+
connection: Connection,
|
|
3221
|
+
id: number,
|
|
3222
|
+
work: () => Promise<unknown>,
|
|
3223
|
+
): Promise<void> {
|
|
3224
|
+
try {
|
|
3225
|
+
connection.send({ id, ok: true, value: await work() });
|
|
3226
|
+
} catch (error) {
|
|
3227
|
+
refuse(connection, id, error);
|
|
3228
|
+
}
|
|
3229
|
+
}
|
|
3230
|
+
|
|
3231
|
+
/** Tell the client that the request failed, and why. */
|
|
3232
|
+
function refuse(connection: Connection, id: number, error: unknown): void {
|
|
3233
|
+
connection.send({
|
|
3234
|
+
id,
|
|
3235
|
+
ok: false,
|
|
3236
|
+
error: error instanceof Error ? error.message : String(error),
|
|
3237
|
+
code: error instanceof Error ? error.name : undefined,
|
|
3238
|
+
...(error instanceof RecordRefused ? {refusal: {
|
|
3239
|
+
code: error.code, reason: error.reason, entity: error.entity, recordType: error.recordType, audit: error.audit,
|
|
3240
|
+
}} : {}),
|
|
3241
|
+
...(error instanceof DeniedError && error.denied !== undefined ? { denied: error.denied } : {}),
|
|
3242
|
+
});
|
|
3243
|
+
}
|
|
3244
|
+
|
|
3245
|
+
/** The host: create it with a home directory. */
|
|
3246
|
+
export function createNiwa(opts: HostOptions): Host {
|
|
3247
|
+
return new Niwa(opts);
|
|
3248
|
+
}
|
|
3249
|
+
|
|
3250
|
+
/**
|
|
3251
|
+
* The filter of a handler of a trigger: what the trigger holds and what the handler adds, both at once. A
|
|
3252
|
+
* path that the two give different values would wake the handler on no record, or on the ones the trigger
|
|
3253
|
+
* does not stand for, so it is refused.
|
|
3254
|
+
*/
|
|
3255
|
+
function combinedFilter(where: string, source: Trigger<any>, added: unknown): Readonly<Record<string, unknown>> {
|
|
3256
|
+
const own = source.filter as Readonly<Record<string, unknown>>;
|
|
3257
|
+
const extra = (added ?? {}) as Readonly<Record<string, unknown>>;
|
|
3258
|
+
for (const path of Object.keys(extra)) {
|
|
3259
|
+
if (Object.hasOwn(own, path) && stableJson(own[path]) !== stableJson(extra[path])) {
|
|
3260
|
+
throw new TypeError(
|
|
3261
|
+
`${where}: the filter has ${path} = ${stableJson(extra[path])}, but the trigger "${source.name}" holds ${path} = ${stableJson(own[path])}`,
|
|
3262
|
+
);
|
|
3263
|
+
}
|
|
3264
|
+
}
|
|
3265
|
+
return { ...own, ...extra };
|
|
3266
|
+
}
|
|
3267
|
+
|
|
3268
|
+
/** A value of an offer as text that is the same for the same code: a record type by its name and version, a function by its source. */
|
|
3269
|
+
function offerText(value: unknown): string {
|
|
3270
|
+
const plain = (one: unknown): unknown => {
|
|
3271
|
+
if (typeof one === "function") return `fn:${one.toString()}`;
|
|
3272
|
+
if (Array.isArray(one)) return one.map(plain);
|
|
3273
|
+
if (typeof one === "object" && one !== null) {
|
|
3274
|
+
const typed = one as { kind?: unknown; name?: unknown; version?: unknown };
|
|
3275
|
+
if (typed.kind === "record" && typeof typed.name === "string") return `record:${typed.name}@${String(typed.version)}`;
|
|
3276
|
+
return Object.fromEntries(Object.entries(one).map(([key, inner]) => [key, plain(inner)]));
|
|
3277
|
+
}
|
|
3278
|
+
return one;
|
|
3279
|
+
};
|
|
3280
|
+
return stableJson(plain(value));
|
|
3281
|
+
}
|
|
3282
|
+
|
|
3283
|
+
/** What a plugin offers at a point, in order, as one text: two versions that offer the same are the same here. */
|
|
3284
|
+
function offeredAt(installed: Installed, point: string): string {
|
|
3285
|
+
return offerText(installed.offers.filter((one) => one.key.name === point).map((one) => one.value));
|
|
3286
|
+
}
|
|
3287
|
+
|
|
3288
|
+
/** Does a value behave as a promise? */
|
|
3289
|
+
function isThenable(value: unknown): boolean {
|
|
3290
|
+
return (typeof value === "object" || typeof value === "function") && value !== null && typeof (value as { then?: unknown }).then === "function";
|
|
3291
|
+
}
|
|
3292
|
+
|
|
3293
|
+
/** `~` at the start of a home is the home of the user. */
|
|
3294
|
+
function expandHome(home: string): string {
|
|
3295
|
+
if (home === "~") return homedir();
|
|
3296
|
+
if (home.startsWith("~/")) return `${homedir()}${home.slice(1)}`;
|
|
3297
|
+
return home;
|
|
3298
|
+
}
|
|
3299
|
+
|
|
3300
|
+
/** The device and inode of the socket file on a path; undefined when there is none. */
|
|
3301
|
+
function socketIdentity(path: string): string | undefined {
|
|
3302
|
+
try {
|
|
3303
|
+
const info = statSync(path);
|
|
3304
|
+
return `${info.dev}:${info.ino}`;
|
|
3305
|
+
} catch {
|
|
3306
|
+
return undefined;
|
|
3307
|
+
}
|
|
3308
|
+
}
|
|
3309
|
+
|
|
3310
|
+
/** Is another host listening on this socket? */
|
|
3311
|
+
async function isLiveSocket(path: string): Promise<boolean> {
|
|
3312
|
+
let cancel: (() => void) | undefined;
|
|
3313
|
+
try {
|
|
3314
|
+
const socket = await Promise.race([
|
|
3315
|
+
Bun.connect({ unix: path, socket: { data: () => undefined } }),
|
|
3316
|
+
new Promise<never>((_resolve, reject) => {
|
|
3317
|
+
// The transport waits on the real clock: the probe is about the socket, not about the
|
|
3318
|
+
// domain time of the host, and a clock a test moves by hand must not hang it.
|
|
3319
|
+
cancel = TRANSPORT_CLOCK.schedule(Date.now() + 500, () => reject(new Error("timeout")));
|
|
3320
|
+
}),
|
|
3321
|
+
]);
|
|
3322
|
+
socket.end();
|
|
3323
|
+
return true;
|
|
3324
|
+
} catch {
|
|
3325
|
+
return false;
|
|
3326
|
+
} finally {
|
|
3327
|
+
cancel?.();
|
|
3328
|
+
}
|
|
3329
|
+
}
|
|
3330
|
+
|
|
3331
|
+
/** The most issues, and the most characters, a refusal message carries: keys the caller sent are echoed by the schema. */
|
|
3332
|
+
const REFUSAL_ISSUES_MAX = 8;
|
|
3333
|
+
const REFUSAL_TEXT_MAX = 600;
|
|
3334
|
+
|
|
3335
|
+
function refusalMessage(
|
|
3336
|
+
name: string,
|
|
3337
|
+
issues: ReadonlyArray<{ readonly path: ReadonlyArray<PropertyKey>; readonly message: string }>,
|
|
3338
|
+
): string {
|
|
3339
|
+
const lines = issues
|
|
3340
|
+
.slice(0, REFUSAL_ISSUES_MAX)
|
|
3341
|
+
.map((issue) => `${issue.path.length > 0 ? issue.path.map(String).join(".") : "<root>"}: ${issue.message}`);
|
|
3342
|
+
if (issues.length > REFUSAL_ISSUES_MAX) lines.push(`and ${issues.length - REFUSAL_ISSUES_MAX} more`);
|
|
3343
|
+
const text = lines.join("; ");
|
|
3344
|
+
const shown = text.length > REFUSAL_TEXT_MAX ? `${text.slice(0, REFUSAL_TEXT_MAX)}...` : text;
|
|
3345
|
+
return `the input of "${name}" is not valid: ${shown}`;
|
|
3346
|
+
}
|