@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.
Files changed (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2 -2
  3. package/package.json +16 -4
  4. package/src/access-actions.ts +193 -0
  5. package/src/access-control.ts +333 -0
  6. package/src/call-operations.ts +176 -0
  7. package/src/cockpit-catalog.ts +99 -0
  8. package/src/describe.ts +55 -0
  9. package/src/doors.ts +272 -0
  10. package/src/host-types.ts +43 -0
  11. package/src/host.ts +3346 -0
  12. package/src/index.ts +10 -0
  13. package/src/plugin-install.ts +249 -0
  14. package/src/state.ts +261 -0
  15. package/src/stores.ts +131 -0
  16. package/test/abandon.test.ts +58 -0
  17. package/test/action-refusal-restart.test.ts +46 -0
  18. package/test/action-step.test.ts +363 -0
  19. package/test/action-wait-restart.test.ts +96 -0
  20. package/test/builtin-actions.test.ts +21 -0
  21. package/test/cancel-steps.test.ts +150 -0
  22. package/test/catch-up.test.ts +378 -0
  23. package/test/causes.test.ts +138 -0
  24. package/test/client.test.ts +190 -0
  25. package/test/cockpit-catalog.test.ts +118 -0
  26. package/test/crash-between-steps.test.ts +88 -0
  27. package/test/declared-values.test.ts +175 -0
  28. package/test/deep-nested-pause.test.ts +147 -0
  29. package/test/fixtures/action-step-host.ts +166 -0
  30. package/test/fixtures/action-wait-restart-host.ts +62 -0
  31. package/test/fixtures/catch-up-host.ts +91 -0
  32. package/test/fixtures/causes-host.ts +78 -0
  33. package/test/fixtures/client-host.ts +52 -0
  34. package/test/fixtures/crash-between-steps-host.ts +71 -0
  35. package/test/fixtures/declared-values-host.ts +110 -0
  36. package/test/fixtures/intercept-order-host.ts +112 -0
  37. package/test/fixtures/intercept-step-host.ts +106 -0
  38. package/test/fixtures/live-frames-host.ts +81 -0
  39. package/test/fixtures/long-wait-host.ts +78 -0
  40. package/test/fixtures/nested-wait-host.ts +120 -0
  41. package/test/fixtures/no-repeat-crash-host.ts +79 -0
  42. package/test/fixtures/plugin-replace-host.ts +176 -0
  43. package/test/fixtures/record-refusal-crash.ts +50 -0
  44. package/test/fixtures/recovery-contracts-host.ts +79 -0
  45. package/test/fixtures/repeated-write-host.ts +39 -0
  46. package/test/fixtures/replay-mismatch-host.ts +66 -0
  47. package/test/fixtures/single-writer-host.ts +113 -0
  48. package/test/fixtures/state-host.ts +118 -0
  49. package/test/fixtures/wait-restart-host.ts +82 -0
  50. package/test/guards.test.ts +448 -0
  51. package/test/handler-emit.test.ts +116 -0
  52. package/test/host.test.ts +114 -0
  53. package/test/intercept-adjust.test.ts +318 -0
  54. package/test/intercept-order.test.ts +276 -0
  55. package/test/intercept-step.test.ts +144 -0
  56. package/test/large-outcome.test.ts +60 -0
  57. package/test/live-frames.test.ts +150 -0
  58. package/test/live-ready.test.ts +61 -0
  59. package/test/long-wait.test.ts +168 -0
  60. package/test/nested-outcome.test.ts +75 -0
  61. package/test/nested-wait.test.ts +111 -0
  62. package/test/no-repeat-crash.test.ts +132 -0
  63. package/test/offer-replace.test.ts +39 -0
  64. package/test/plugin-async-setup.test.ts +22 -0
  65. package/test/plugin-copies.test.ts +87 -0
  66. package/test/plugin-emit.test.ts +43 -0
  67. package/test/plugin-install-failure.test.ts +121 -0
  68. package/test/plugin-install-hash.test.ts +57 -0
  69. package/test/plugin-needs.test.ts +80 -0
  70. package/test/plugin-replace.test.ts +225 -0
  71. package/test/plugin-uninstall.test.ts +70 -0
  72. package/test/plugin-version-copies.test.ts +53 -0
  73. package/test/plugin-version.test.ts +180 -0
  74. package/test/read-filter.test.ts +136 -0
  75. package/test/read-query.test.ts +92 -0
  76. package/test/record-admission.test.ts +294 -0
  77. package/test/recovery-contracts.test.ts +107 -0
  78. package/test/repeated-write.test.ts +119 -0
  79. package/test/replay-mismatch.test.ts +79 -0
  80. package/test/replay.test.ts +135 -0
  81. package/test/single-writer.test.ts +267 -0
  82. package/test/state.test.ts +246 -0
  83. package/test/step-by-name.test.ts +122 -0
  84. package/test/stores.test.ts +102 -0
  85. package/test/stream.test.ts +154 -0
  86. package/test/subscriber-stream.test.ts +71 -0
  87. package/test/subscribers.test.ts +101 -0
  88. package/test/subscriptions.test.ts +632 -0
  89. package/test/trace-call.test.ts +124 -0
  90. package/test/trigger-filter.test.ts +42 -0
  91. package/test/use-many.test.ts +151 -0
  92. package/test/wait-query.test.ts +117 -0
  93. package/test/wait-restart.test.ts +187 -0
  94. package/test/wire-read-access.test.ts +85 -0
  95. package/tsconfig.json +6 -0
package/src/index.ts ADDED
@@ -0,0 +1,10 @@
1
+ // The host entry: the host that serves plugins, and what only a host does.
2
+
3
+ export * from "./host.ts";
4
+ export * from "./state.ts";
5
+ export * from "./access-control.ts";
6
+ export * from "./access-actions.ts";
7
+ export * from "./doors.ts";
8
+ export * from "./plugin-install.ts";
9
+ export * from "./describe.ts";
10
+ export * from "./host-types.ts";
@@ -0,0 +1,249 @@
1
+ /**
2
+ * Installing a plugin from a file: `plugin.install@<name>`.
3
+ *
4
+ * One core action for the install and the replacement of a plugin module. The target of a call is
5
+ * the name of the plugin, so a grant can limit who may install which plugin (`plugin.install@rin/*`),
6
+ * and the file is pinned by its hash: the call may name the hash the file is expected to have, and
7
+ * the hash that was installed is written down.
8
+ */
9
+
10
+ import { createHash } from "node:crypto";
11
+ import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
12
+ import { dirname, extname, isAbsolute, join, resolve } from "node:path";
13
+
14
+ import { z } from "zod";
15
+
16
+ import { action, CORE_TYPES, NotSent, recordId, seq } from "@niwa-labs/core";
17
+ import { PLUGIN_INSTALL, PLUGIN_UNINSTALL, pluginName } from "@niwa-labs/plugin";
18
+ import type { Action, Caller, JournalReader } from "@niwa-labs/core";
19
+ import type { Plugin } from "@niwa-labs/plugin";
20
+
21
+ /** What was written down when a plugin was installed from a file. */
22
+ export const PluginInstalledData = z.object({
23
+ plugin: z.string().min(1),
24
+ version: z.string().min(1),
25
+ /** The file the plugin came from, as an absolute path. */
26
+ module: z.string().min(1),
27
+ /** The hash of that file: a restart can install exactly this code. */
28
+ hash: z.string().min(1),
29
+ });
30
+
31
+ /** One installation of a plugin from a file, as the journal holds it. */
32
+ export type PluginInstallation = z.infer<typeof PluginInstalledData>;
33
+
34
+ /** A plugin, as a module exports it. */
35
+ const PluginValue = z.custom<Plugin>(
36
+ (value) => typeof value === "object" && value !== null && "kind" in value && value.kind === "plugin",
37
+ { message: "a module that exports a plugin" },
38
+ );
39
+
40
+ /** The plugin a module exports and the hash of the file it came from. */
41
+ export interface LoadedPlugin {
42
+ readonly plugin: Plugin;
43
+ readonly hash: string;
44
+ }
45
+
46
+ /** The copy a module file is imported through: beside the file, named by its hash. */
47
+ function copyPathOf(module: string, hash: string): string {
48
+ return join(dirname(module), `.${hash}${extname(module)}`);
49
+ }
50
+
51
+ /** The name of a copy, whatever its extension: a dot, the sha256 in hex, and the extension of the file. */
52
+ const COPY_NAME = /^\.[0-9a-f]{64}(\.[^.]*)?$/;
53
+
54
+ /** The installations the journal holds, oldest first; a record that is not one is not read. */
55
+ function installationsIn(journal: JournalReader): PluginInstallation[] {
56
+ return journal.find({ type: CORE_TYPES.pluginInstalled }).flatMap((row) => {
57
+ const read = PluginInstalledData.safeParse(row.data);
58
+ return read.success ? [read.data] : [];
59
+ });
60
+ }
61
+
62
+ /** Remove a copy; a copy that cannot be removed stays, and nothing else fails for it. */
63
+ async function removeCopy(path: string): Promise<void> {
64
+ await rm(path, { force: true }).catch(() => undefined);
65
+ }
66
+
67
+ /** The currently installed modules, in their original registration order. */
68
+ export function currentInstallations(journal: JournalReader): Map<string, PluginInstallation> {
69
+ const current = new Map<string, PluginInstallation>();
70
+ for (const row of journal.since(seq(0), [CORE_TYPES.pluginInstalled, CORE_TYPES.pluginUninstalled])) {
71
+ if (row.type === CORE_TYPES.pluginInstalled) {
72
+ const data = PluginInstalledData.safeParse(row.data);
73
+ if (data.success) current.set(data.data.plugin, data.data);
74
+ } else {
75
+ const data = UninstallInput.safeParse(row.data);
76
+ if (data.success) current.delete(data.data.plugin);
77
+ }
78
+ }
79
+ return current;
80
+ }
81
+
82
+ /** What a plugin is installed from now, if it was installed from a file. */
83
+ export function installationOf(journal: JournalReader, plugin: string): PluginInstallation | undefined {
84
+ return currentInstallations(journal).get(plugin);
85
+ }
86
+
87
+ function keptCopies(journal: JournalReader): Set<string> {
88
+ return new Set([...currentInstallations(journal).values()].map((one) => copyPathOf(one.module, one.hash)));
89
+ }
90
+
91
+ /** Remove the copy an installation was made from, unless a current installation is made from it too. */
92
+ export async function removeCopyIfStale(journal: JournalReader, installation: PluginInstallation): Promise<void> {
93
+ const copy = copyPathOf(installation.module, installation.hash);
94
+ if (!keptCopies(journal).has(copy)) await removeCopy(copy);
95
+ }
96
+
97
+ /**
98
+ * Remove the copies no installation is made from any more.
99
+ *
100
+ * A host start looks beside every file a plugin was ever installed from, and takes away the copies
101
+ * (`.<hash><ext>`) that the current installations do not name. A copy that is wanted again is made
102
+ * again by the next load.
103
+ */
104
+ export async function removeStaleCopies(journal: JournalReader): Promise<void> {
105
+ const installations = installationsIn(journal);
106
+ const kept = keptCopies(journal);
107
+ for (const dir of new Set(installations.map((one) => dirname(one.module)))) {
108
+ const names = await readdir(dir).catch(() => []);
109
+ for (const name of names) {
110
+ const path = join(dir, name);
111
+ if (COPY_NAME.test(name) && !kept.has(path)) await removeCopy(path);
112
+ }
113
+ }
114
+ }
115
+
116
+ /**
117
+ * The plugin a module exports, with the hash of its file.
118
+ *
119
+ * The file is read once: the bytes that are hashed are the bytes that are imported, so a file that
120
+ * changes between the two cannot be installed under the hash of another. The import is of a copy
121
+ * addressed by that hash, beside the file so that its relative imports still resolve; Bun keeps a
122
+ * module under its whole specifier, so the same path would also give the code it loaded the first
123
+ * time. A relative path is taken from the working directory of the host.
124
+ *
125
+ * When a hash is expected, the bytes are checked against it first: a file that is not the approved
126
+ * one is refused before a copy of it is written and before any of its code runs.
127
+ */
128
+ export async function loadPluginModule(module: string, expected?: string): Promise<LoadedPlugin> {
129
+ const path = isAbsolute(module) ? module : resolve(process.cwd(), module);
130
+ const bytes = await readFile(path);
131
+ const hash = createHash("sha256").update(bytes).digest("hex");
132
+ if (expected !== undefined && hash !== expected) {
133
+ throw new NotSent(`${module} is not the file that was approved: it is ${hash}, the call has ${expected}`);
134
+ }
135
+ const copy = copyPathOf(path, hash);
136
+ const existing = await readCopy(copy, hash);
137
+ if (existing === undefined) {
138
+ // Written aside and renamed in: a load at the same time never imports half a file.
139
+ const aside = `${copy}.${crypto.randomUUID()}`;
140
+ try {
141
+ await writeFile(aside, bytes);
142
+ await rename(aside, copy);
143
+ } finally {
144
+ await rm(aside, { force: true });
145
+ }
146
+ }
147
+ return { plugin: await importPlugin(copy), hash };
148
+ }
149
+
150
+ async function importPlugin(file: string): Promise<Plugin> {
151
+ const loaded: { default?: unknown } = await import(file);
152
+ return PluginValue.parse(loaded.default);
153
+ }
154
+
155
+ /** Restore the installed bytes even when the original has been edited or removed. */
156
+ export async function restorePlugin(installation: PluginInstallation): Promise<Plugin> {
157
+ const { plugin, module, hash } = installation;
158
+ const copy = copyPathOf(module, hash);
159
+ const bytes = await readCopy(copy, hash);
160
+ const restored = bytes === undefined ? (await loadPluginModule(module, hash)).plugin : await importPlugin(copy);
161
+ if (restored.name !== plugin) throw new Error(`the installed file for "${plugin}" exports a different plugin`);
162
+ return restored;
163
+ }
164
+
165
+ async function readCopy(copy: string, hash: string): Promise<Buffer | undefined> {
166
+ const bytes = await readFile(copy).catch((error: NodeJS.ErrnoException) => {
167
+ if (error.code !== "ENOENT") throw error;
168
+ return undefined;
169
+ });
170
+ if (bytes !== undefined && createHash("sha256").update(bytes).digest("hex") !== hash) {
171
+ throw new Error(`plugin copy "${copy}" does not match its expected hash`);
172
+ }
173
+ return bytes;
174
+ }
175
+
176
+ /** What the action needs from the host. */
177
+ export interface PluginInstallDeps {
178
+ install(caller: Caller, plugin: Plugin, data: Omit<PluginInstallation, "version">, id: ReturnType<typeof recordId>): Promise<void>;
179
+ recorded(id: ReturnType<typeof recordId>): PluginInstallation | undefined;
180
+ check(plugin: string): void;
181
+ }
182
+
183
+ const Input = z.object({
184
+ /** The plugin the file is expected to export: the `@target` of the call. */
185
+ plugin: z.string().min(1),
186
+ /** The file that exports it. */
187
+ module: z.string().min(1),
188
+ /** The hash the file is expected to have: a file that changed since is refused. */
189
+ hash: z.string().min(1).optional(),
190
+ });
191
+
192
+ const Output = z.object({ plugin: z.string(), version: z.string(), hash: z.string() });
193
+
194
+ /** The action `plugin.install`. */
195
+ export function pluginInstallAction(deps: PluginInstallDeps): Action<z.infer<typeof Input>, z.infer<typeof Output>> {
196
+ return action(PLUGIN_INSTALL, {
197
+ description:
198
+ "Installs a plugin from a module file, or replaces the installed plugin of that name. The target is the plugin's name; the module has to export exactly that plugin, and, when a hash is given, to be the file with that hash.",
199
+ input: Input,
200
+ output: Output,
201
+ recovery: "repeat",
202
+ effect: "write",
203
+ world: "local",
204
+ target: (input) => input.plugin,
205
+ async run(input, ctx) {
206
+ const id = recordId(`${ctx.operationId}/installed`);
207
+ const done = deps.recorded(id);
208
+ if (done !== undefined) return done;
209
+ const named = pluginName(input.plugin);
210
+ deps.check(named);
211
+ const loaded = await loadPluginModule(input.module, input.hash);
212
+ if (loaded.plugin.name !== named) {
213
+ throw new Error(`${input.module} exports the plugin "${loaded.plugin.name}", not "${named}"`);
214
+ }
215
+ const module = isAbsolute(input.module) ? input.module : resolve(process.cwd(), input.module);
216
+ await deps.install(ctx.caller, loaded.plugin, { plugin: named, module, hash: loaded.hash }, id);
217
+ return { plugin: named, version: loaded.plugin.version, hash: loaded.hash };
218
+ },
219
+ });
220
+ }
221
+
222
+ const UninstallInput = z.object({ plugin: z.string().min(1), hash: z.string().regex(/^[a-f0-9]{64}$/) });
223
+
224
+ export function pluginUninstallAction(
225
+ journal: () => JournalReader,
226
+ remove: (caller: Caller, installation: PluginInstallation, id: ReturnType<typeof recordId>) => Promise<void>,
227
+ ) {
228
+ return action(PLUGIN_UNINSTALL, {
229
+ description: "Uninstalls a module-installed plugin at its current hash. Only the owner can uninstall.",
230
+ input: UninstallInput,
231
+ output: UninstallInput,
232
+ recovery: "repeat",
233
+ effect: "write",
234
+ world: "local",
235
+ target: (input) => input.plugin,
236
+ async run(input, ctx) {
237
+ if (ctx.caller.kind !== "client" || ctx.caller.principal?.kind !== "owner") throw new Error("only the owner can uninstall a plugin");
238
+ const name = pluginName(input.plugin);
239
+ const id = recordId(`${ctx.operationId}/uninstalled`);
240
+ const log = journal();
241
+ if (log.get(id) !== undefined) return input;
242
+ const installation = installationOf(log, name);
243
+ if (installation === undefined) throw new Error(`"${name}" is not installed from a module`);
244
+ if (installation.hash !== input.hash) throw new Error(`"${name}" no longer has the selected hash`);
245
+ await remove(ctx.caller, installation, id);
246
+ return input;
247
+ },
248
+ });
249
+ }
package/src/state.ts ADDED
@@ -0,0 +1,261 @@
1
+ /**
2
+ * Plugin state: values by key, owned by a plugin, changed by named operations.
3
+ *
4
+ * The rules this file keeps:
5
+ *
6
+ * - A change is one named operation: `update` reads, applies and commits in one synchronous turn,
7
+ * so two handlers cannot lose each other's updates.
8
+ * - Every change is a record, `niwa.state.changed` `{ plugin, name, op, value }`, where `value` is
9
+ * what the key holds after the change.
10
+ * - Inside an invocation a read is a record, `niwa.state.read`, under `${invocation}/state/${n}`;
11
+ * a replay returns that record's value, never today's.
12
+ * - Only the plugin that declared a key writes it: the handle is its only way in, and it refuses
13
+ * to run inside a handler of another plugin.
14
+ * - The current value is a projection folded from the journal when the host serves.
15
+ */
16
+
17
+ import { z } from "zod";
18
+
19
+ import { ValidationError, currentInvocation, CORE_TYPES, newRecordId, recordId, streamId } from "@niwa-labs/core";
20
+ import type { InvocationScope, Caller, Journal, NewRecord, PluginName, RecordId, StoredRecord } from "@niwa-labs/core";
21
+ import type { StateHandle } from "@niwa-labs/plugin";
22
+
23
+ /** How the store writes: the records are committed and published. */
24
+ type Append = (recs: NewRecord[]) => StoredRecord[];
25
+
26
+ /** The data of a state record: what the key holds, or held when it was read. */
27
+ const StateData = z.object({
28
+ plugin: z.string(),
29
+ name: z.string(),
30
+ op: z.string(),
31
+ value: z.unknown(),
32
+ });
33
+
34
+ /** What a plugin declared about one key of its state. */
35
+ interface Entry {
36
+ readonly schema: z.ZodType<unknown>;
37
+ /** The value before anything changed the key, and the value a take resets it to. */
38
+ readonly initial: unknown;
39
+ }
40
+
41
+ /** The key of a value inside a plugin: `${plugin}/${name}`. */
42
+ function stateKey(plugin: string, name: string): string {
43
+ return `${plugin}/${name}`;
44
+ }
45
+
46
+ /** A name is a key in the journal and the projection: not empty, no whitespace. */
47
+ function requireName(name: string): string {
48
+ if (typeof name !== "string" || name.trim().length === 0) {
49
+ throw new TypeError("the name of a state value must be a non-empty string");
50
+ }
51
+ if (/\s/.test(name)) {
52
+ throw new TypeError(`the name of a state value must not contain whitespace: ${JSON.stringify(name)}`);
53
+ }
54
+ return name;
55
+ }
56
+
57
+ /** The plugin a handler id belongs to: handler ids are `${plugin}/${name}`. */
58
+ function pluginOfHandler(handler: string): string {
59
+ return handler.slice(0, handler.lastIndexOf("/"));
60
+ }
61
+
62
+ /** Who changed a value: the handler that runs, or the host when nothing runs. */
63
+ function actorOf(scope: InvocationScope | undefined): Caller {
64
+ if (scope === undefined) return { kind: "host" };
65
+ return { kind: "handler", handler: scope.handler, invocation: scope.invocation };
66
+ }
67
+
68
+ /** The state of the plugins of one host. */
69
+ export class StateStore {
70
+ private journal: Journal | undefined;
71
+ private append: Append | undefined;
72
+ private readonly entries = new Map<string, Entry>();
73
+ /** The current value of every key: a projection of the journal, nothing more. */
74
+ private readonly values = new Map<string, unknown>();
75
+
76
+ /** Take the journal and the way to write, and fold the projection from the journal. */
77
+ bind(deps: { journal: Journal; append: Append }): void {
78
+ this.journal = deps.journal;
79
+ this.append = deps.append;
80
+ this.values.clear();
81
+ for (const record of deps.journal.find({ type: CORE_TYPES.stateChanged })) this.fold(record);
82
+ }
83
+
84
+ private fold(record: StoredRecord): void {
85
+ if (record.type !== CORE_TYPES.stateChanged) return;
86
+ const data = StateData.safeParse(record.data);
87
+ if (data.success) this.values.set(stateKey(data.data.plugin, data.data.name), data.data.value);
88
+ }
89
+
90
+ /** The keys declared now: what an install that fails puts back. */
91
+ declared(): ReadonlyMap<string, Entry> {
92
+ return new Map(this.entries);
93
+ }
94
+
95
+ /** Put the declared keys back as `declared` took them. */
96
+ restore(declared: ReadonlyMap<string, Entry>): void {
97
+ this.entries.clear();
98
+ for (const [key, entry] of declared) this.entries.set(key, entry);
99
+ }
100
+
101
+ /** Declare a key of a plugin's state and hand out its handle. */
102
+ define<T>(plugin: PluginName, name: string, schema: z.ZodType<T>, initial: T): StateHandle<T> {
103
+ const key = stateKey(plugin, requireName(name));
104
+ const parsed = schema.safeParse(initial);
105
+ if (!parsed.success) {
106
+ throw new ValidationError(`the initial value of the state "${key}" is not valid`, parsed.error.issues);
107
+ }
108
+ this.entries.set(key, { schema, initial: parsed.data });
109
+ return {
110
+ name,
111
+ get: () => this.read<T>(plugin, name),
112
+ set: (value) => this.change<T>(plugin, name, "set", () => value),
113
+ update: (fn) => this.change<T>(plugin, name, "update", fn),
114
+ take: () => this.take<T>(plugin, name),
115
+ };
116
+ }
117
+
118
+ /** Inside an invocation the read is recorded, and a replay returns the first read. */
119
+ private read<T>(plugin: PluginName, name: string): T {
120
+ const key = stateKey(plugin, name);
121
+ const entry = this.entryOf(key);
122
+ const scope = this.scopeFor(plugin);
123
+ if (scope === undefined) return this.current(key, entry) as T;
124
+
125
+ scope.reads += 1;
126
+ const id = recordId(`${scope.invocation}/state/${scope.reads}`);
127
+ const recorded = this.recorded(id, plugin, name);
128
+ if (recorded !== undefined) return recorded as T;
129
+
130
+ const value = this.current(key, entry);
131
+ this.commit([this.record(CORE_TYPES.stateRead, plugin, name, "get", value, scope, id)], scope);
132
+ return value as T;
133
+ }
134
+
135
+ /**
136
+ * One change: `next` runs on the current value and the result is committed in the same
137
+ * synchronous turn. Inside an invocation the change has a deterministic id, so a replay finds
138
+ * the change made the first time and does not make it again.
139
+ */
140
+ private change<T>(plugin: PluginName, name: string, op: "set" | "update", next: (current: T) => T): T {
141
+ const key = stateKey(plugin, name);
142
+ const entry = this.entryOf(key);
143
+ const scope = this.scopeFor(plugin);
144
+ const id = this.writeId(scope);
145
+ const recorded = this.recorded(id, plugin, name);
146
+ if (recorded !== undefined) return recorded as T;
147
+
148
+ const parsed = entry.schema.safeParse(next(this.current(key, entry) as T));
149
+ if (!parsed.success) {
150
+ throw new ValidationError(`the value of the state "${key}" is not valid`, parsed.error.issues);
151
+ }
152
+ this.commit([this.record(CORE_TYPES.stateChanged, plugin, name, op, parsed.data, scope, id)], scope);
153
+ return structuredClone(parsed.data) as T;
154
+ }
155
+
156
+ /**
157
+ * Return the value and reset the key to its initial one. The read and the reset are one commit,
158
+ * so a change that arrives meanwhile lands in the next batch, and a replay takes the same batch.
159
+ */
160
+ private take<T>(plugin: PluginName, name: string): T {
161
+ const key = stateKey(plugin, name);
162
+ const entry = this.entryOf(key);
163
+ const scope = this.scopeFor(plugin);
164
+ const current = this.current(key, entry);
165
+
166
+ if (scope === undefined) {
167
+ const id = newRecordId("st");
168
+ this.commit([this.record(CORE_TYPES.stateChanged, plugin, name, "take", entry.initial, undefined, id)]);
169
+ return current as T;
170
+ }
171
+
172
+ scope.reads += 1;
173
+ const readId = recordId(`${scope.invocation}/state/${scope.reads}`);
174
+ const recorded = this.recorded(readId, plugin, name);
175
+ if (recorded !== undefined) {
176
+ // The reset belongs to the same commit: its ordinal is consumed, as in the first run.
177
+ scope.writes += 1;
178
+ return recorded as T;
179
+ }
180
+
181
+ const changeId = this.writeId(scope);
182
+ this.commit([
183
+ this.record(CORE_TYPES.stateRead, plugin, name, "take", current, scope, readId),
184
+ this.record(CORE_TYPES.stateChanged, plugin, name, "take", entry.initial, scope, changeId),
185
+ ], scope);
186
+ return current as T;
187
+ }
188
+
189
+ private entryOf(key: string): Entry {
190
+ const entry = this.entries.get(key);
191
+ if (entry === undefined) throw new Error(`the state "${key}" was not declared`);
192
+ return entry;
193
+ }
194
+
195
+ /**
196
+ * The running invocation, if it may touch this plugin's state. A handler of another plugin
197
+ * cannot, and nor can code that outlives its invocation.
198
+ */
199
+ private scopeFor(plugin: PluginName): InvocationScope | undefined {
200
+ const scope = currentInvocation();
201
+ if (scope === undefined) return undefined;
202
+ if (scope.closed) {
203
+ throw new Error(`the invocation ${scope.invocation} has ended: its state cannot be touched`);
204
+ }
205
+ if (pluginOfHandler(scope.handler) !== plugin) {
206
+ throw new Error(`the state of "${plugin}" can only be touched by "${plugin}", not by ${scope.handler}`);
207
+ }
208
+ return scope;
209
+ }
210
+
211
+ /** A copy of the value: what a caller does to it must not reach the projection. */
212
+ private current(key: string, entry: Entry): unknown {
213
+ return structuredClone(this.values.has(key) ? this.values.get(key) : entry.initial);
214
+ }
215
+
216
+ /** The value of the record with this id, if the journal holds one for this key. */
217
+ private recorded(id: RecordId, plugin: PluginName, name: string): unknown {
218
+ const record = this.journal?.get(id);
219
+ if (record === undefined) return undefined;
220
+ const data = StateData.parse(record.data);
221
+ if (data.plugin !== plugin || data.name !== name) {
222
+ throw new Error(`replay diverged: ${id} holds "${data.plugin}/${data.name}", not "${plugin}/${name}"`);
223
+ }
224
+ return data.value;
225
+ }
226
+
227
+ /** The id of the next change of this invocation. */
228
+ private writeId(scope: InvocationScope | undefined): RecordId {
229
+ if (scope === undefined) return newRecordId("st");
230
+ scope.writes += 1;
231
+ return recordId(`${scope.invocation}/state/write/${scope.writes}`);
232
+ }
233
+
234
+ private record(
235
+ type: typeof CORE_TYPES.stateChanged | typeof CORE_TYPES.stateRead,
236
+ plugin: PluginName,
237
+ name: string,
238
+ op: string,
239
+ value: unknown,
240
+ scope: InvocationScope | undefined,
241
+ id: RecordId,
242
+ ): NewRecord {
243
+ return {
244
+ id,
245
+ stream: streamId(`plugin:${plugin}`),
246
+ type,
247
+ schema: 1,
248
+ data: { plugin, name, op, value },
249
+ actor: actorOf(scope),
250
+ cause: scope?.cause ?? null,
251
+ root: scope?.root ?? id,
252
+ };
253
+ }
254
+
255
+ /** Commit the records, then fold the committed changes into the projection. */
256
+ private commit(recs: NewRecord[], scope?: InvocationScope): void {
257
+ if (this.append === undefined) throw new Error("the state cannot be changed before the host is serving");
258
+ scope?.writing();
259
+ for (const record of this.append(recs)) this.fold(record);
260
+ }
261
+ }
package/src/stores.ts ADDED
@@ -0,0 +1,131 @@
1
+ /**
2
+ * The stores of a host: artifacts and secrets, under its home.
3
+ *
4
+ * An artifact is a file named by the SHA-256 of its bytes, under `<home>/artifacts`. Bytes are
5
+ * written to a partial file, flushed to disk, and moved to their name; the directory is flushed
6
+ * too. So a record that points at an artifact never points at one a crash could take, and the
7
+ * same bytes are the same file. Artifacts are never removed while the host keeps the journal that
8
+ * points at them.
9
+ *
10
+ * A secret is the owner's: the file `<home>/secrets/<name>`, readable by its owner alone, or the
11
+ * variable `NIWA_SECRET_<name>` of the host's environment. Every message here names the secret,
12
+ * never its value.
13
+ */
14
+
15
+ import { createHash, randomUUID } from "node:crypto";
16
+ import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
17
+ import { join } from "node:path";
18
+
19
+ import { ArtifactMissing, SecretRefusal } from "@niwa-labs/core";
20
+ import type { ArtifactRef, ArtifactStore, ArtifactWriter, SecretStore } from "@niwa-labs/core";
21
+
22
+ const DIGEST = /^sha256:[0-9a-f]{64}$/;
23
+
24
+ /** Flushes a directory, so a name made in it survives a crash. */
25
+ function syncDir(dir: string): void {
26
+ const fd = openSync(dir, "r");
27
+ try {
28
+ fsyncSync(fd);
29
+ } finally {
30
+ closeSync(fd);
31
+ }
32
+ }
33
+
34
+ /** The artifacts of the host whose home `home` gives. */
35
+ export function artifactStore(home: () => string): ArtifactStore {
36
+ const dir = (): string => join(home(), "artifacts");
37
+ const fileOf = (digest: string): string => {
38
+ if (!DIGEST.test(digest)) throw new TypeError(`not the digest of an artifact: ${JSON.stringify(digest)}`);
39
+ return join(dir(), digest.slice("sha256:".length));
40
+ };
41
+
42
+ const writer = (type: string): ArtifactWriter => {
43
+ if (type.length === 0) throw new TypeError("an artifact needs a media type");
44
+ const at = dir();
45
+ mkdirSync(at, { recursive: true, mode: 0o700 });
46
+ const temp = join(at, `.partial-${randomUUID()}`);
47
+ const fd = openSync(temp, "wx", 0o600);
48
+ const hasher = createHash("sha256");
49
+ let size = 0;
50
+ let open = true;
51
+ const close = (): void => {
52
+ if (!open) return;
53
+ open = false;
54
+ closeSync(fd);
55
+ };
56
+ return {
57
+ write(chunk) {
58
+ if (!open) throw new Error("the artifact is finished");
59
+ if (chunk.length === 0) return;
60
+ writeSync(fd, chunk);
61
+ hasher.update(chunk);
62
+ size += chunk.length;
63
+ },
64
+ finish() {
65
+ if (!open) throw new Error("the artifact is finished");
66
+ fsyncSync(fd);
67
+ close();
68
+ const ref: ArtifactRef = { digest: `sha256:${hasher.digest("hex")}`, size, type };
69
+ renameSync(temp, fileOf(ref.digest));
70
+ syncDir(at);
71
+ return ref;
72
+ },
73
+ discard() {
74
+ close();
75
+ rmSync(temp, { force: true });
76
+ },
77
+ };
78
+ };
79
+
80
+ return {
81
+ put(bytes, type) {
82
+ const out = writer(type);
83
+ try {
84
+ out.write(typeof bytes === "string" ? Buffer.from(bytes) : bytes);
85
+ return out.finish();
86
+ } catch (error) {
87
+ out.discard();
88
+ throw error;
89
+ }
90
+ },
91
+ writer,
92
+ read(ref) {
93
+ const path = fileOf(ref.digest);
94
+ if (!existsSync(path)) throw new ArtifactMissing(ref.digest);
95
+ return new Uint8Array(readFileSync(path));
96
+ },
97
+ };
98
+ }
99
+
100
+ /** The secrets of the host whose home `home` gives, with the environment they may also come from. */
101
+ export function secretStore(home: () => string, env: Readonly<Record<string, string | undefined>> = process.env): SecretStore {
102
+ const nonEmpty = (name: string, value: string): string => {
103
+ if (value.length === 0) throw new SecretRefusal("unknown-secret", `the secret "${name}" is empty`);
104
+ return value;
105
+ };
106
+ return {
107
+ get dir() {
108
+ return join(home(), "secrets");
109
+ },
110
+ resolve(name) {
111
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new SecretRefusal("unknown-secret", `"${name}" is not the name of a secret`);
112
+ const path = join(this.dir, name);
113
+ let mode: number | undefined;
114
+ try {
115
+ const stat = statSync(path);
116
+ if (stat.isFile()) mode = stat.mode;
117
+ } catch {
118
+ // Not a file: the environment may have it.
119
+ }
120
+ if (mode !== undefined) {
121
+ if ((mode & 0o077) !== 0) {
122
+ throw new SecretRefusal("unsafe-secret", `the file of the secret "${name}" must be readable by its owner alone (mode 0600)`);
123
+ }
124
+ return nonEmpty(name, readFileSync(path, "utf8").replace(/\r?\n$/, ""));
125
+ }
126
+ const fromEnv = env[`NIWA_SECRET_${name}`];
127
+ if (fromEnv !== undefined) return nonEmpty(name, fromEnv);
128
+ throw new SecretRefusal("unknown-secret", `no secret "${name}": ${path} does not exist and NIWA_SECRET_${name} is not set`);
129
+ },
130
+ };
131
+ }