@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
@@ -0,0 +1,114 @@
1
+ // The rules of the host that no scenario check covers directly: who may write what, who a client
2
+ // is, that a waiting invocation holds nobody back, and that only a paused one can be answered.
3
+
4
+ import { expect, test } from "bun:test";
5
+
6
+ import { action, principalOf, record, seq, UnknownType } from "@niwa-labs/core";
7
+ import { connect } from "@niwa-labs/client";
8
+ import { createNiwa } from "@niwa-labs/host";
9
+ import { plugin } from "@niwa-labs/plugin";
10
+ import type { Caller, StoredRecord } from "@niwa-labs/core";
11
+ import type { Host } from "@niwa-labs/host";
12
+ import { eventually, tempHome } from "@niwa-labs/testing";
13
+ import { z } from "zod";
14
+
15
+ const Job = record("host.job", z.object({ n: z.number(), wait: z.boolean() }));
16
+ const Gate = record("host.gate", z.object({}));
17
+ const Seen = record("host.seen", z.object({ n: z.number() }));
18
+
19
+ const whoami = action("host.whoami", {
20
+ description: "Returns the caller the host bound to this call.",
21
+ input: z.object({}),
22
+ output: z.object({ caller: z.string() }),
23
+ recovery: "repeat",
24
+ effect: "write",
25
+ run: async (_input, ctx) => ({ caller: callerName(ctx.caller) }),
26
+ });
27
+
28
+ function callerName(caller: Caller): string {
29
+ return caller.kind === "client" ? caller.id : caller.kind;
30
+ }
31
+
32
+ const jobs = plugin("host-rules", (api) => {
33
+ api.declare(Job, Gate, Seen);
34
+ api.action(whoami);
35
+ // A job that waits for the gate holds no other job.
36
+ api.on(Job, { concurrency: Number.POSITIVE_INFINITY }, async (job, step) => {
37
+ if (job.wait) await step.wait(Gate);
38
+ await step.emit(Seen, { n: job.n });
39
+ });
40
+ });
41
+
42
+ async function withHost(run: (host: Host, home: string) => Promise<void>): Promise<void> {
43
+ const home = await tempHome();
44
+ const host = createNiwa({ home: home.path });
45
+ host.use(jobs);
46
+ await host.serve();
47
+ try {
48
+ await run(host, home.path);
49
+ } finally {
50
+ await host.close();
51
+ await home.cleanup();
52
+ }
53
+ }
54
+
55
+ async function collect(host: Host, kind: string, count: number): Promise<StoredRecord[]> {
56
+ const found: StoredRecord[] = [];
57
+ for await (const rec of host.records.since()) {
58
+ if (rec.type === kind) found.push(rec);
59
+ if (found.length === count) break;
60
+ }
61
+ return found;
62
+ }
63
+
64
+ test("the host refuses to write a type of the core: only the core writes those", async () => {
65
+ await withHost(async (host) => {
66
+ const forged = record("niwa.invocation.state", z.unknown());
67
+ await expect(host.emit(forged, { invocation: "x", state: "done" })).rejects.toBeInstanceOf(
68
+ UnknownType,
69
+ );
70
+ });
71
+ });
72
+
73
+ test("a client is named by the host: two clients with one label are two callers", async () => {
74
+ await withHost(async (host, home) => {
75
+ // A client the host issued a token with no grant: nothing limits it, and its label is only a name.
76
+ const plain = host.issueToken(principalOf("client", "same"));
77
+ const a = await connect({ home, id: "same", token: plain });
78
+ const b = await connect({ home, id: "same", token: plain });
79
+ const first = await a.call(whoami, {});
80
+ const second = await b.call(whoami, {});
81
+ expect(first.caller).toStartWith("same#");
82
+ expect(second.caller).toStartWith("same#");
83
+ expect(second.caller).not.toBe(first.caller);
84
+ await a.close();
85
+ await b.close();
86
+ });
87
+ });
88
+
89
+ test("a waiting invocation holds nobody back, and its answer wakes it", async () => {
90
+ await withHost(async (host) => {
91
+ await host.emit(Job, { n: 1, wait: true });
92
+ await host.emit(Job, { n: 2, wait: false });
93
+ const early = await collect(host, "host.seen", 1);
94
+ expect(early.map((rec) => rec.data)).toEqual([{ n: 2 }]);
95
+ await host.emit(Gate, {});
96
+ const all = await collect(host, "host.seen", 2);
97
+ expect(all.map((rec) => rec.data)).toEqual([{ n: 2 }, { n: 1 }]);
98
+ });
99
+ });
100
+
101
+ test("only a paused invocation can be answered", async () => {
102
+ await withHost(async (host) => {
103
+ const job = await host.emit(Job, { n: 1, wait: false });
104
+ await eventually(async () => (await collect(host, "host.seen", 1)).length === 1, 5000, "done");
105
+ const admitted = (await host.trace(job.id)).find((rec) => rec.type === "niwa.invocation.admitted");
106
+ expect(admitted).toBeDefined();
107
+ await expect(
108
+ host.call("niwa.invocation.resolve" as never, {
109
+ invocation: admitted?.id,
110
+ choice: "cancel",
111
+ } as never),
112
+ ).rejects.toThrow("is not paused");
113
+ });
114
+ });
@@ -0,0 +1,318 @@
1
+ // The adjusts of an intercept.
2
+ //
3
+ // The order is the contract: the requested input is validated; adjusts run in registration
4
+ // order; the resulting input is validated again; guards run against that final input.
5
+ //
6
+ // The second validation is not a formality. An adjust that changes the input in place — or that
7
+ // returns the very object it was given — has changed it, whether it says so or not. Each adjust
8
+ // gets its own deep copy of the input, so an adjust that changes its copy in place cannot change
9
+ // what the decision records as the requested input.
10
+
11
+ import { expect, test } from "bun:test";
12
+
13
+ import { action, CORE_TYPES, record, seq } from "@niwa-labs/core";
14
+ import { createNiwa } from "@niwa-labs/host";
15
+ import { plugin } from "@niwa-labs/plugin";
16
+ import type { StoredRecord } from "@niwa-labs/core";
17
+ import { eventually, tempHome } from "@niwa-labs/testing";
18
+ import { z } from "zod";
19
+
20
+ import { decide, newIntercepts } from "@niwa-labs/core/journal";
21
+
22
+ const CALLER = { kind: "host" } as const;
23
+
24
+ /** The runs of the action below: how many times its body was called. */
25
+ const runs: number[] = [];
26
+
27
+ /** The inputs the action below was called with. */
28
+ const seen: Array<{ n: number }> = [];
29
+
30
+ const Take = action("adjust.take", {
31
+ description: "Takes a number that is not negative.",
32
+ input: z.object({ n: z.number().int().min(0) }),
33
+ output: z.object({ n: z.number() }),
34
+ recovery: "repeat",
35
+ effect: "write",
36
+ run: (input) => {
37
+ runs.push(input.n);
38
+ seen.push(input);
39
+ return input;
40
+ },
41
+ });
42
+
43
+ const Start = record("adjust.start", z.object({}));
44
+ const Note = record("adjust.note", z.object({ status: z.string() }));
45
+
46
+ /** A host with a plugin, and the records it wrote. */
47
+ async function hosted(setup: Parameters<typeof plugin>[1]) {
48
+ const home = await tempHome();
49
+ const niwa = createNiwa({ home: home.path });
50
+ niwa.use(plugin("adjust", setup));
51
+ await niwa.serve();
52
+ const written: StoredRecord[] = [];
53
+ const watching = (async () => {
54
+ for await (const rec of niwa.records.since()) written.push(rec);
55
+ })().catch(() => undefined);
56
+ return {
57
+ niwa,
58
+ home: home.path,
59
+ records: (): StoredRecord[] => written,
60
+ close: async () => {
61
+ await niwa.close();
62
+ await watching;
63
+ await home.cleanup();
64
+ },
65
+ };
66
+ }
67
+
68
+ test("(a) an adjust that changes the input in place is refused: the input is validated again", async () => {
69
+ const intercepts = newIntercepts();
70
+ let guards = 0;
71
+ intercepts.adjusts.push((input: { n: number }) => {
72
+ input.n = -5;
73
+ });
74
+ intercepts.guards.push(() => {
75
+ guards += 1;
76
+ });
77
+
78
+ const decision = await decide({ intercepts, action: Take, input: { n: 1 }, caller: CALLER });
79
+
80
+ // The input was validated again, and it did not fit: the call is refused.
81
+ expect(decision.kind).toBe("invalid");
82
+ if (decision.kind !== "invalid") return;
83
+ expect(decision.which).toBe("final");
84
+ expect(decision.final).toEqual({ n: -5 });
85
+ // The guard is asked about a valid input, so it was not asked at all.
86
+ expect(guards).toBe(0);
87
+ // The action did not run.
88
+ expect(runs).toEqual([]);
89
+ });
90
+
91
+ test("(b) an adjust that returns the very object it changed in place is refused as well", async () => {
92
+ const intercepts = newIntercepts();
93
+ let guards = 0;
94
+ intercepts.adjusts.push((input: { n: number }) => {
95
+ input.n = -5;
96
+ return input;
97
+ });
98
+ intercepts.guards.push(() => {
99
+ guards += 1;
100
+ });
101
+
102
+ const decision = await decide({ intercepts, action: Take, input: { n: 1 }, caller: CALLER });
103
+
104
+ expect(decision.kind).toBe("invalid");
105
+ if (decision.kind !== "invalid") return;
106
+ expect(decision.which).toBe("final");
107
+ expect(decision.final).toEqual({ n: -5 });
108
+ expect(guards).toBe(0);
109
+ expect(runs).toEqual([]);
110
+ });
111
+
112
+ test("(c) an adjust that adds a key has it stripped before the action runs", async () => {
113
+ const intercepts = newIntercepts();
114
+ intercepts.adjusts.push((input: { n: number }) => ({ ...input, extra: "smuggled" }));
115
+
116
+ const decision = await decide({ intercepts, action: Take, input: { n: 1 }, caller: CALLER });
117
+
118
+ expect(decision.kind).toBe("allowed");
119
+ if (decision.kind !== "allowed") return;
120
+ // The schema is the one the action was called with: a field it does not have is not there.
121
+ expect(decision.final).toEqual({ n: 1 });
122
+ expect(Object.hasOwn(decision.final, "extra")).toBe(false);
123
+ });
124
+
125
+ test("(d) inside an invocation, a call an adjust broke in place ends as failed", async () => {
126
+ const h = await hosted((api) => {
127
+ api.declare(Start, Note);
128
+ api.action(Take);
129
+ api.adjust(Take, (input) => {
130
+ input.n = -5;
131
+ return undefined;
132
+ });
133
+ api.on(Start, async (_data, step) => {
134
+ const outcome = await step.outcome(Take, { n: 1 });
135
+ await step.emit(Note, { status: outcome.status });
136
+ });
137
+ });
138
+ try {
139
+ await h.niwa.emit(Start, {});
140
+ await eventually(
141
+ () => h.records().some((rec) => rec.type === Note.name),
142
+ 10_000,
143
+ "the invocation should have ended the step",
144
+ );
145
+ const note = h.records().find((rec) => rec.type === Note.name);
146
+ expect(Note.schema.parse(note?.data).status).toBe("failed");
147
+ // The outcome says the adjusted input did not fit its schema.
148
+ const outcome = h.records().find((rec) => rec.type === CORE_TYPES.stepOutcome);
149
+ const error = (outcome?.data as { outcome: { error?: string } }).outcome.error ?? "";
150
+ expect(error).toContain("does not match its schema");
151
+ // The action did not run.
152
+ expect(runs).toEqual([]);
153
+ } finally {
154
+ await h.close();
155
+ }
156
+ });
157
+
158
+ test("(e) the recorded decision holds the requested input as it was asked for", async () => {
159
+ const h = await hosted((api) => {
160
+ api.declare(Start, Note);
161
+ api.action(Take);
162
+ // The adjust changes the input in place, to a value that is still valid.
163
+ api.adjust(Take, (input) => {
164
+ input.n = 2;
165
+ return undefined;
166
+ });
167
+ api.on(Start, async (_data, step) => {
168
+ const outcome = await step.outcome(Take, { n: 1 });
169
+ await step.emit(Note, { status: outcome.status });
170
+ });
171
+ });
172
+ try {
173
+ await h.niwa.emit(Start, {});
174
+ await eventually(
175
+ () => h.records().some((rec) => rec.type === CORE_TYPES.stepDecision),
176
+ 10_000,
177
+ "the decision should be recorded",
178
+ );
179
+ const decision = h.records().find((rec) => rec.type === CORE_TYPES.stepDecision);
180
+ const data = decision?.data as { requested: { n: number }; final: { n: number } };
181
+ // The requested input is the one the caller asked for: the adjust's change is not in it.
182
+ expect(data.requested).toEqual({ n: 1 });
183
+ expect(data.final).toEqual({ n: 2 });
184
+ // The action ran with the changed input.
185
+ expect(runs).toEqual([2]);
186
+ } finally {
187
+ await h.close();
188
+ }
189
+ });
190
+
191
+ test("each adjust gets its own copy, and the adjusts are a pipeline over the input", async () => {
192
+ const intercepts = newIntercepts();
193
+ const seenByAdjusts: number[] = [];
194
+ intercepts.adjusts.push((input: { n: number }) => {
195
+ seenByAdjusts.push(input.n);
196
+ input.n = 2;
197
+ });
198
+ intercepts.adjusts.push((input: { n: number }) => {
199
+ seenByAdjusts.push(input.n);
200
+ input.n = 3;
201
+ });
202
+
203
+ const decision = await decide({ intercepts, action: Take, input: { n: 1 }, caller: CALLER });
204
+
205
+ // The adjusts run in registration order, each on what the one before it left.
206
+ expect(seenByAdjusts).toEqual([1, 2]);
207
+ expect(decision.kind).toBe("allowed");
208
+ if (decision.kind !== "allowed") return;
209
+ // The requested input is still the one the caller asked for: no adjust changed it.
210
+ expect(decision.requested).toEqual({ n: 1 });
211
+ expect(decision.final).toEqual({ n: 3 });
212
+ });
213
+
214
+ test("an adjust that changes the input in place does not change what is recorded as requested", async () => {
215
+ const intercepts = newIntercepts();
216
+ intercepts.adjusts.push((input: { n: number }) => {
217
+ input.n = 2;
218
+ });
219
+
220
+ const decision = await decide({ intercepts, action: Take, input: { n: 1 }, caller: CALLER });
221
+
222
+ expect(decision.kind).toBe("allowed");
223
+ if (decision.kind !== "allowed") return;
224
+ // The copy the adjust changed is not the one the decision holds as the requested input.
225
+ expect(decision.requested).toEqual({ n: 1 });
226
+ expect(decision.final).toEqual({ n: 2 });
227
+ });
228
+
229
+ /** An action whose input holds a value that cannot be copied: a function, like a question's schema. */
230
+ const Holding = action("adjust.holding", {
231
+ description: "Takes a number and something that cannot be cloned.",
232
+ input: z.object({ n: z.number().int().min(0), held: z.custom<() => number>((v) => typeof v === "function") }),
233
+ output: z.object({ n: z.number() }),
234
+ recovery: "repeat",
235
+ effect: "write",
236
+ run: (input) => ({ n: input.n }),
237
+ });
238
+
239
+ test("an input that holds a value that cannot be cloned: a valid change in place stays out of requested", async () => {
240
+ const intercepts = newIntercepts();
241
+ intercepts.adjusts.push((input: { n: number }) => {
242
+ input.n = 2;
243
+ });
244
+ const held = () => 7;
245
+
246
+ const decision = await decide({ intercepts, action: Holding, input: { n: 1, held }, caller: CALLER });
247
+
248
+ expect(decision.kind).toBe("allowed");
249
+ if (decision.kind !== "allowed") return;
250
+ // The plain fields are copied although one field is not clonable.
251
+ expect(decision.requested.n).toBe(1);
252
+ expect(decision.final.n).toBe(2);
253
+ // The value that cannot be copied is passed on as it is.
254
+ expect(decision.final.held).toBe(held);
255
+ expect(decision.requested.held).toBe(held);
256
+ });
257
+
258
+ test("an input that holds a value that cannot be cloned: a change in place is still validated", async () => {
259
+ const intercepts = newIntercepts();
260
+ let guards = 0;
261
+ intercepts.adjusts.push((input: { n: number }) => {
262
+ input.n = -5;
263
+ });
264
+ intercepts.guards.push(() => {
265
+ guards += 1;
266
+ });
267
+
268
+ const decision = await decide({ intercepts, action: Holding, input: { n: 1, held: () => 7 }, caller: CALLER });
269
+
270
+ expect(decision.kind).toBe("invalid");
271
+ if (decision.kind !== "invalid") return;
272
+ expect(decision.which).toBe("final");
273
+ expect((decision.requested as { n: number }).n).toBe(1);
274
+ expect(guards).toBe(0);
275
+ });
276
+
277
+ test("an instance of a class keeps its class, and nested plain data is copied around it", async () => {
278
+ class Box {
279
+ constructor(readonly n: number) {}
280
+ }
281
+ const Nested = action("adjust.nested", {
282
+ description: "Takes a box and a list.",
283
+ input: z.object({ box: z.instanceof(Box), list: z.array(z.object({ n: z.number() })) }),
284
+ output: z.object({ ok: z.boolean() }),
285
+ recovery: "repeat",
286
+ effect: "write",
287
+ run: () => ({ ok: true }),
288
+ });
289
+ const intercepts = newIntercepts();
290
+ intercepts.adjusts.push((input: { box: Box; list: Array<{ n: number }> }) => {
291
+ input.list[0]!.n = 9;
292
+ });
293
+ const box = new Box(1);
294
+
295
+ const decision = await decide({ intercepts, action: Nested, input: { box, list: [{ n: 1 }] }, caller: CALLER });
296
+
297
+ expect(decision.kind).toBe("allowed");
298
+ if (decision.kind !== "allowed") return;
299
+ expect(decision.final.box).toBe(box);
300
+ expect(decision.final.list).toEqual([{ n: 9 }]);
301
+ expect(decision.requested.list).toEqual([{ n: 1 }]);
302
+ });
303
+
304
+ test("with no adjust, a schema whose output is not its input is not made to parse its own output", async () => {
305
+ const Length = action("adjust.length", {
306
+ description: "Takes text, and works with its length.",
307
+ input: z.string().transform((text) => text.length),
308
+ output: z.object({ n: z.number() }),
309
+ recovery: "repeat",
310
+ effect: "write",
311
+ run: (n) => ({ n }),
312
+ });
313
+ const decision = await decide({ intercepts: newIntercepts(), action: Length, input: "four", caller: CALLER });
314
+
315
+ expect(decision.kind).toBe("allowed");
316
+ if (decision.kind !== "allowed") return;
317
+ expect(decision.final).toBe(4);
318
+ });