@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,632 @@
1
+ // A subscription of a plugin: where it starts, what it remembers across restarts, how many of its
2
+ // records run at once, and which records never wake it.
3
+
4
+ import { expect, test } from "bun:test";
5
+
6
+ import { CORE_TYPES, action, record, seq } from "@niwa-labs/core";
7
+ import type { ActionName, Handler, RecordType, StoredRecord } from "@niwa-labs/core";
8
+ import { createNiwa } from "@niwa-labs/host";
9
+ import { plugin } from "@niwa-labs/plugin";
10
+ import type { HandlerOptions, Plugin } from "@niwa-labs/plugin";
11
+ import { eventually, tempHome } from "@niwa-labs/testing";
12
+ import { z } from "zod";
13
+
14
+ const Item = record("sub-test.item", z.object({ n: z.number(), kind: z.string().optional() }));
15
+ const ItemV2 = record("sub-test.item", z.object({ n: z.number(), kind: z.string().optional() }), { version: 2 });
16
+ const Answer = record("sub-test.answer", z.object({ n: z.number() }));
17
+ const Echo = record("sub-test.echo", z.object({ n: z.number() }));
18
+
19
+ /** The plugin that declares the types and nothing else: what writes the records. */
20
+ const producer = (): Plugin => plugin("sub-producer", (api) => api.declare(Item, Answer));
21
+
22
+ /** A plugin with one handler of the items. */
23
+ function consumer(handler: Handler<{ n: number; kind?: string }>, opts: HandlerOptions = {}, type: RecordType<any> = Item): Plugin {
24
+ return plugin("sub-consumer", (api) => {
25
+ api.declare(Echo);
26
+ api.on(type, opts, handler);
27
+ });
28
+ }
29
+
30
+ type Host = ReturnType<typeof createNiwa>;
31
+
32
+ /** Serve a host on a home with these plugins. */
33
+ async function serving(home: string, plugins: Plugin[]): Promise<Host> {
34
+ const niwa = createNiwa({ home });
35
+ for (const one of plugins) niwa.use(one);
36
+ await niwa.serve();
37
+ return niwa;
38
+ }
39
+
40
+ const recordsOf = (niwa: Host, type?: string): Promise<StoredRecord[]> =>
41
+ niwa.records.read().then((rows) => (type === undefined ? rows : rows.filter((row) => row.type === type)));
42
+
43
+ const positionsOf = async (niwa: Host): Promise<Array<{ subscription: string; seq: number; reason: string }>> =>
44
+ (await recordsOf(niwa, CORE_TYPES.subscriptionPosition)).map((row) => row.data as { subscription: string; seq: number; reason: string });
45
+
46
+ const statesOf = async (niwa: Host): Promise<Array<{ invocation: string; state: string }>> =>
47
+ (await recordsOf(niwa, CORE_TYPES.invocationState)).map((row) => row.data as { invocation: string; state: string });
48
+
49
+ const admissionsOf = async (niwa: Host): Promise<string[]> =>
50
+ (await recordsOf(niwa, CORE_TYPES.invocationAdmitted)).map((row) => (row.data as { record: string }).record);
51
+
52
+ test("a new subscription starts at the position it was installed at", async () => {
53
+ const home = await tempHome();
54
+ try {
55
+ const before = await serving(home.path, [producer()]);
56
+ await before.emit(Item, { n: 1 });
57
+ await before.emit(Item, { n: 2 });
58
+ await before.close();
59
+
60
+ const seen: number[] = [];
61
+ const after = await serving(home.path, [producer(), consumer((data) => void seen.push(data.n))]);
62
+ await after.emit(Item, { n: 3 });
63
+ await eventually(() => seen.length > 0);
64
+ await Bun.sleep(50);
65
+ expect(seen).toEqual([3]);
66
+ expect((await positionsOf(after)).map((one) => one.reason)).toContain("installed");
67
+ await after.close();
68
+ } finally {
69
+ await home.cleanup();
70
+ }
71
+ });
72
+
73
+ test("a subscription that asks for the history starts at the beginning", async () => {
74
+ const home = await tempHome();
75
+ try {
76
+ const before = await serving(home.path, [producer()]);
77
+ await before.emit(Item, { n: 1 });
78
+ await before.close();
79
+ const seen: number[] = [];
80
+ const after = await serving(home.path, [producer(), consumer((data) => void seen.push(data.n), { from: "start" })]);
81
+ await eventually(() => seen.length === 1);
82
+ expect(seen).toEqual([1]);
83
+ await after.close();
84
+ } finally {
85
+ await home.cleanup();
86
+ }
87
+ });
88
+
89
+ test("a subscription resumes from its stored position, not from the moment the host starts again", async () => {
90
+ const home = await tempHome();
91
+ try {
92
+ const seen: number[] = [];
93
+ const first = await serving(home.path, [producer(), consumer((data) => void seen.push(data.n))]);
94
+ await first.emit(Item, { n: 1 });
95
+ await eventually(() => seen.length === 1);
96
+ await first.close();
97
+ // The records written while the subscription was not installed are still its records.
98
+ const away = await serving(home.path, [producer()]);
99
+ await away.emit(Item, { n: 2 });
100
+ await away.emit(Item, { n: 3 });
101
+ await away.close();
102
+ const again = await serving(home.path, [producer(), consumer((data) => void seen.push(data.n))]);
103
+ await eventually(() => seen.length === 3);
104
+ expect(seen).toEqual([1, 2, 3]);
105
+ await again.close();
106
+ } finally {
107
+ await home.cleanup();
108
+ }
109
+ });
110
+
111
+ test("a filtered record advances the position once, with its reason, and is not read again", async () => {
112
+ const home = await tempHome();
113
+ try {
114
+ const seen: number[] = [];
115
+ const first = await serving(home.path, [producer(), consumer((data) => void seen.push(data.n), { filter: { kind: "wanted" } })]);
116
+ await first.emit(Item, { n: 1, kind: "other" });
117
+ await first.emit(Item, { n: 2, kind: "other" });
118
+ await first.emit(Item, { n: 3, kind: "wanted" });
119
+ await eventually(() => seen.length === 1);
120
+ await first.emit(Item, { n: 4, kind: "other" });
121
+ await eventually(async () => (await positionsOf(first)).some((one) => one.reason === "filtered"));
122
+ expect(seen).toEqual([3]);
123
+ const filtered = (await positionsOf(first)).filter((one) => one.reason === "filtered");
124
+ const items = await recordsOf(first, Item.name);
125
+ expect(filtered.at(-1)?.seq).toBe(items.at(-1)?.seq);
126
+ await first.close();
127
+ } finally {
128
+ await home.cleanup();
129
+ }
130
+ });
131
+
132
+ test("records of another schema version advance the position with the reason schema", async () => {
133
+ const home = await tempHome();
134
+ try {
135
+ const old = await serving(home.path, [producer()]);
136
+ await old.emit(Item, { n: 1 });
137
+ await old.emit(Item, { n: 2 });
138
+ await old.close();
139
+ const seen: number[] = [];
140
+ const newer = await serving(home.path, [
141
+ plugin("sub-producer", (api) => api.declare(ItemV2, Answer)),
142
+ consumer((data) => void seen.push(data.n), { from: "start" }, ItemV2),
143
+ ]);
144
+ await eventually(async () => (await positionsOf(newer)).some((one) => one.reason === "schema"));
145
+ const written = (await positionsOf(newer)).filter((one) => one.reason === "schema").length;
146
+ await newer.emit(ItemV2, { n: 3 });
147
+ await eventually(() => seen.length === 1);
148
+ expect(seen).toEqual([3]);
149
+ // The tail of the old version is read past once, not again at every look for new work.
150
+ expect((await positionsOf(newer)).filter((one) => one.reason === "schema").length).toBe(written);
151
+ await newer.close();
152
+ } finally {
153
+ await home.cleanup();
154
+ }
155
+ });
156
+
157
+ test("no subscription is woken by the records of a position", async () => {
158
+ const home = await tempHome();
159
+ try {
160
+ const Positions = record("niwa.subscription.*", z.unknown());
161
+ let woken = 0;
162
+ const niwa = await serving(home.path, [
163
+ producer(),
164
+ consumer(() => undefined, { filter: { kind: "wanted" } }),
165
+ plugin("sub-watch-a", (api) => api.on(Positions, { from: "start" }, () => void woken++)),
166
+ plugin("sub-watch-b", (api) => api.on(Positions, { from: "start" }, () => void woken++)),
167
+ ]);
168
+ for (let n = 0; n < 3; n++) await niwa.emit(Item, { n, kind: "other" });
169
+ await eventually(async () => (await positionsOf(niwa)).some((one) => one.reason === "filtered"));
170
+ const count = (await recordsOf(niwa)).length;
171
+ await Bun.sleep(100);
172
+ expect(woken).toBe(0);
173
+ expect((await recordsOf(niwa)).length).toBe(count);
174
+ await niwa.close();
175
+ } finally {
176
+ await home.cleanup();
177
+ }
178
+ });
179
+
180
+ /**
181
+ * A handler that waits for the answer to its item, and the items it began, in order. A handler that
182
+ * is woken runs again from its start and replays its steps, so an item is counted once.
183
+ */
184
+ function waiter(began: number[]): Handler<{ n: number }> {
185
+ return async (data, step) => {
186
+ if (!began.includes(data.n)) began.push(data.n);
187
+ await step.wait(Answer, { filter: { n: data.n } });
188
+ };
189
+ }
190
+
191
+ test("one record at a time: a second record does not start while the first waits", async () => {
192
+ const home = await tempHome();
193
+ try {
194
+ const began: number[] = [];
195
+ const niwa = await serving(home.path, [producer(), consumer(waiter(began))]);
196
+ await niwa.emit(Item, { n: 1 });
197
+ await niwa.emit(Item, { n: 2 });
198
+ await eventually(() => began.length === 1);
199
+ await Bun.sleep(100);
200
+ expect(began).toEqual([1]);
201
+ await niwa.emit(Answer, { n: 1 });
202
+ await eventually(() => began.length === 2);
203
+ expect(began).toEqual([1, 2]);
204
+ await niwa.close();
205
+ } finally {
206
+ await home.cleanup();
207
+ }
208
+ });
209
+
210
+ test("one record at a time holds across a restart of the host", async () => {
211
+ const home = await tempHome();
212
+ try {
213
+ const began: number[] = [];
214
+ const first = await serving(home.path, [producer(), consumer(waiter(began))]);
215
+ await first.emit(Item, { n: 1 });
216
+ await first.emit(Item, { n: 2 });
217
+ await eventually(() => began.length === 1);
218
+ await first.close();
219
+ const again = await serving(home.path, [producer(), consumer(waiter(began))]);
220
+ await Bun.sleep(150);
221
+ // The first item is run again from its steps; the second still waits its turn.
222
+ expect(began).toEqual([1]);
223
+ await again.emit(Answer, { n: 1 });
224
+ await eventually(() => began.length === 2);
225
+ expect(began).toEqual([1, 2]);
226
+ await again.close();
227
+ } finally {
228
+ await home.cleanup();
229
+ }
230
+ });
231
+
232
+ test("a paused record holds the next one until the owner decides", async () => {
233
+ const home = await tempHome();
234
+ try {
235
+ const began: number[] = [];
236
+ const niwa = await serving(home.path, [
237
+ producer(),
238
+ consumer((data) => {
239
+ began.push(data.n);
240
+ if (data.n === 1) throw new Error("item one fails");
241
+ }),
242
+ ]);
243
+ await niwa.emit(Item, { n: 1 });
244
+ await niwa.emit(Item, { n: 2 });
245
+ await eventually(async () => (await statesOf(niwa)).some((one) => one.state === "paused"));
246
+ await Bun.sleep(100);
247
+ expect(began).toEqual([1]);
248
+ const paused = (await statesOf(niwa)).find((one) => one.state === "paused");
249
+ await niwa.call("niwa.invocation.resolve" as ActionName, { invocation: paused?.invocation, choice: "cancel" });
250
+ await eventually(() => began.length === 2);
251
+ expect(began).toEqual([1, 2]);
252
+ await niwa.close();
253
+ } finally {
254
+ await home.cleanup();
255
+ }
256
+ });
257
+
258
+ test("a subscription with room for two runs two records at once", async () => {
259
+ const home = await tempHome();
260
+ try {
261
+ const began: number[] = [];
262
+ const niwa = await serving(home.path, [producer(), consumer(waiter(began), { concurrency: 2 })]);
263
+ for (const n of [1, 2, 3]) await niwa.emit(Item, { n });
264
+ await eventually(() => began.length === 2);
265
+ await Bun.sleep(100);
266
+ expect(began).toEqual([1, 2]);
267
+ await niwa.emit(Answer, { n: 2 });
268
+ await eventually(() => began.length === 3);
269
+ await niwa.close();
270
+ } finally {
271
+ await home.cleanup();
272
+ }
273
+ });
274
+
275
+ test("a keyed subscription preserves order within a key and lets other keys pass", async () => {
276
+ const home = await tempHome();
277
+ const began: number[] = [];
278
+ const niwa = await serving(home.path, [
279
+ producer(),
280
+ plugin("sub-keyed", (api) => api.on(Item, { concurrency: { by: (data) => data.kind ?? "" } }, waiter(began))),
281
+ ]);
282
+ try {
283
+ const first = await niwa.emit(Item, { n: 1, kind: "a" });
284
+ const second = await niwa.emit(Item, { n: 2, kind: "a" });
285
+ const third = await niwa.emit(Item, { n: 3, kind: "a" });
286
+ const other = await niwa.emit(Item, { n: 4, kind: "b" });
287
+ await eventually(() => began.length === 2);
288
+ expect(began).toEqual([1, 4]);
289
+ expect(await admissionsOf(niwa)).toEqual([first.id, other.id]);
290
+
291
+ await niwa.emit(Answer, { n: 1 });
292
+ await eventually(() => began.length === 3);
293
+ expect(began).toEqual([1, 4, 2]);
294
+ expect(await admissionsOf(niwa)).toEqual([first.id, other.id, second.id]);
295
+
296
+ await niwa.emit(Answer, { n: 2 });
297
+ await eventually(() => began.length === 4);
298
+ expect(began).toEqual([1, 4, 2, 3]);
299
+ expect(await admissionsOf(niwa)).toEqual([first.id, other.id, second.id, third.id]);
300
+ } finally {
301
+ await niwa.close();
302
+ await home.cleanup();
303
+ }
304
+ });
305
+
306
+ test("a thrown handler keeps only its own key until the paused invocation is cancelled", async () => {
307
+ const home = await tempHome();
308
+ const began: number[] = [];
309
+ const niwa = await serving(home.path, [
310
+ producer(),
311
+ plugin("sub-keyed", (api) => {
312
+ api.on(Item, { concurrency: { by: (data) => data.kind ?? "" } }, (data) => {
313
+ began.push(data.n);
314
+ if (data.n === 1) throw new Error("item one fails");
315
+ });
316
+ }),
317
+ ]);
318
+ try {
319
+ await niwa.emit(Item, { n: 1, kind: "a" });
320
+ await niwa.emit(Item, { n: 2, kind: "a" });
321
+ await niwa.emit(Item, { n: 3, kind: "b" });
322
+ await eventually(() => began.length === 2);
323
+ expect(began).toEqual([1, 3]);
324
+ const paused = (await statesOf(niwa)).find((one) => one.state === "paused");
325
+ expect(paused).toBeDefined();
326
+ await niwa.call("niwa.invocation.resolve" as ActionName, { invocation: paused?.invocation, choice: "cancel" });
327
+ await eventually(() => began.length === 3);
328
+ expect(began).toEqual([1, 3, 2]);
329
+ } finally {
330
+ await niwa.close();
331
+ await home.cleanup();
332
+ }
333
+ });
334
+
335
+ test("restart preserves a keyed gap, replays the wait and skips completed admissions beyond it", async () => {
336
+ const home = await tempHome();
337
+ const selected: number[] = [];
338
+ const began: number[] = [];
339
+ const keyed = () => plugin("sub-keyed", (api) => {
340
+ api.declare(Echo);
341
+ api.on(Item, { concurrency: { by: (data) => {
342
+ selected.push(data.n);
343
+ return data.kind ?? "";
344
+ } } }, async (data, step) => {
345
+ began.push(data.n);
346
+ await step.emit(Echo, { n: data.n });
347
+ if (data.n === 1) await step.wait(Answer, { filter: { n: 1 } });
348
+ });
349
+ });
350
+ let niwa = await serving(home.path, [producer(), keyed()]);
351
+ try {
352
+ const first = await niwa.emit(Item, { n: 1, kind: "a" });
353
+ const second = await niwa.emit(Item, { n: 2, kind: "a" });
354
+ const third = await niwa.emit(Item, { n: 3, kind: "b" });
355
+ await eventually(async () => {
356
+ const states = await statesOf(niwa);
357
+ return states.some((one) => one.invocation.endsWith(first.id) && one.state === "waiting")
358
+ && states.some((one) => one.invocation.endsWith(third.id) && one.state === "done");
359
+ });
360
+ expect(await admissionsOf(niwa)).toEqual([first.id, third.id]);
361
+ expect(began).toEqual([1, 3]);
362
+ await niwa.close();
363
+
364
+ selected.length = 0;
365
+ began.length = 0;
366
+ niwa = await serving(home.path, [producer(), keyed()]);
367
+ const fourth = await niwa.emit(Item, { n: 4, kind: "b" });
368
+ await eventually(() => began.includes(4));
369
+ expect(began).toEqual([1, 4]);
370
+ expect([...new Set(selected)]).toEqual([2, 4]);
371
+ expect(await admissionsOf(niwa)).toEqual([first.id, third.id, fourth.id]);
372
+
373
+ await niwa.emit(Answer, { n: 1 });
374
+ await eventually(async () => (await statesOf(niwa)).some((one) => one.invocation.endsWith(second.id) && one.state === "done"));
375
+ expect(began).toEqual([1, 4, 1, 2]);
376
+ expect(await admissionsOf(niwa)).toEqual([first.id, third.id, fourth.id, second.id]);
377
+ expect((await recordsOf(niwa, Echo.name)).map((row) => row.data)).toEqual([1, 3, 4, 2].map((n) => ({ n })));
378
+ expect((await positionsOf(niwa)).at(-1)?.seq).toBe(fourth.seq);
379
+ await niwa.close();
380
+
381
+ niwa = await serving(home.path, [producer(), keyed()]);
382
+ const fifth = await niwa.emit(Item, { n: 5, kind: "a" });
383
+ await eventually(() => began.includes(5));
384
+ expect(began).toEqual([1, 4, 1, 2, 5]);
385
+ expect(await admissionsOf(niwa)).toEqual([first.id, third.id, fourth.id, second.id, fifth.id]);
386
+ } finally {
387
+ await niwa.close();
388
+ await home.cleanup();
389
+ }
390
+ });
391
+
392
+ test("keyed concurrency validates the declaration and does not consume a record on selector failure", async () => {
393
+ const home = await tempHome();
394
+ const errors: string[] = [];
395
+ const original = console.error;
396
+ console.error = (...args: unknown[]) => void errors.push(args.map(String).join(" "));
397
+ let niwa: Host | undefined;
398
+ try {
399
+ for (const concurrency of [0, 1.5, NaN, -Infinity, null, [], {}, { by: "kind" }]) {
400
+ expect(() => createNiwa({ home: home.path }).use(consumer(() => {}, { concurrency } as HandlerOptions))).toThrow(/concurrency/);
401
+ }
402
+ const failed: number[] = [];
403
+ const healthy: number[] = [];
404
+ const throwing = () => plugin("sub-throwing-selector", (api) => {
405
+ api.on(Item, { concurrency: { by: (data) => {
406
+ if (data.n === 1) throw new Error("missing entity");
407
+ return data.n === 2 ? Infinity : data.n;
408
+ } } }, (data) => void failed.push(data.n));
409
+ });
410
+ const fixed = () => plugin("sub-throwing-selector", (api) => {
411
+ api.on(Item, { concurrency: { by: (data) => data.n } }, (data) => void failed.push(data.n));
412
+ });
413
+ niwa = await serving(home.path, [producer(), throwing(), consumer((data) => void healthy.push(data.n))]);
414
+ const first = await niwa.emit(Item, { n: 1 });
415
+ await niwa.emit(Item, { n: 2 });
416
+ await eventually(() => healthy.length === 2);
417
+ expect(failed).toEqual([]);
418
+ expect(errors.some((line) => line.includes(first.id) && line.includes("missing entity"))).toBe(true);
419
+ await niwa.close();
420
+
421
+ niwa = await serving(home.path, [producer(), fixed()]);
422
+ await eventually(() => failed.length === 2);
423
+ expect(failed).toEqual([1, 2]);
424
+ await niwa.close();
425
+
426
+ niwa = await serving(home.path, [producer(), throwing()]);
427
+ const invalid = await niwa.emit(Item, { n: 2 });
428
+ await eventually(() => errors.some((line) => line.includes(invalid.id) && line.includes("finite number")));
429
+ expect(failed).toEqual([1, 2]);
430
+ } finally {
431
+ await niwa?.close();
432
+ console.error = original;
433
+ await home.cleanup();
434
+ }
435
+ });
436
+
437
+ test("a journal-derived subscriber applies its queries, bounds and keyed concurrency", async () => {
438
+ const home = await tempHome();
439
+ const began: number[] = [];
440
+ let niwa = await serving(home.path, [producer()]);
441
+ try {
442
+ await niwa.emit(Item, { n: 0, kind: "older" });
443
+ const marker = await niwa.emit(Answer, { n: 0 });
444
+ await niwa.emit(Item, { n: 1, kind: "wanted" });
445
+ await niwa.emit(Item, { n: 1, kind: "wanted" });
446
+ await niwa.emit(Item, { n: 2, kind: "ignored" });
447
+ const end = await niwa.emit(Item, { n: 3, kind: "wanted" });
448
+ await niwa.emit(Item, { n: 4, kind: "wanted" });
449
+ await niwa.close();
450
+
451
+ niwa = await serving(home.path, [producer(), plugin("sub-dynamic-keyed", (api) => {
452
+ api.subscribers(() => [{
453
+ id: "items",
454
+ queries: [{ type: Item, filter: { kind: "wanted" } }],
455
+ from: marker.seq,
456
+ until: end.seq,
457
+ concurrency: { by: (data) => Item.schema.parse(data).n },
458
+ handler: async (data, step) => {
459
+ const item = Item.schema.parse(data);
460
+ began.push(item.n);
461
+ await step.wait(Answer, { filter: { n: item.n } });
462
+ },
463
+ }]);
464
+ })]);
465
+ await eventually(() => began.length === 2);
466
+ expect(began).toEqual([1, 3]);
467
+ await niwa.emit(Answer, { n: 1 });
468
+ await eventually(async () => (await admissionsOf(niwa)).length === 3);
469
+ expect((await positionsOf(niwa)).at(-1)?.seq).toBe(end.seq);
470
+ } finally {
471
+ await niwa.close();
472
+ await home.cleanup();
473
+ }
474
+ });
475
+
476
+ test("busy keys under load leave room for a new key and drain their own queues in order", async () => {
477
+ const home = await tempHome();
478
+ const keys = Array.from({ length: 32 }, (_, n) => String(n));
479
+ const gates = new Map(keys.map((key) => [key, Promise.withResolvers<void>()]));
480
+ const occupied = new Set<string>();
481
+ const seen = new Map<string, number[]>();
482
+ const overlaps: string[] = [];
483
+ const niwa = await serving(home.path, [producer(), plugin("sub-keyed", (api) => {
484
+ api.on(Item, { concurrency: { by: (data) => data.kind ?? "" } }, async (data) => {
485
+ const key = data.kind ?? "";
486
+ if (occupied.has(key)) overlaps.push(key);
487
+ occupied.add(key);
488
+ const order = seen.get(key) ?? [];
489
+ order.push(data.n);
490
+ seen.set(key, order);
491
+ if (data.n === 1) await gates.get(key)?.promise;
492
+ occupied.delete(key);
493
+ });
494
+ })]);
495
+ try {
496
+ for (const n of [1, 2, 3]) {
497
+ for (const kind of keys) await niwa.emit(Item, { n, kind });
498
+ }
499
+ await niwa.emit(Item, { n: 4, kind: "fresh" });
500
+ await eventually(() => seen.has("fresh"));
501
+ expect(occupied.size).toBe(keys.length);
502
+ for (const key of keys) expect(seen.get(key)).toEqual([1]);
503
+
504
+ const released = keys.at(-1)!;
505
+ gates.get(released)!.resolve();
506
+ await eventually(() => seen.get(released)?.length === 3);
507
+ expect(occupied.size).toBe(keys.length - 1);
508
+ expect(seen.get(keys[0]!)).toEqual([1]);
509
+
510
+ for (const key of [...keys].reverse()) gates.get(key)!.resolve();
511
+ await eventually(() => keys.every((key) => seen.get(key)?.length === 3));
512
+ for (const key of keys) expect(seen.get(key)).toEqual([1, 2, 3]);
513
+ expect(overlaps).toEqual([]);
514
+ } finally {
515
+ for (const gate of gates.values()) gate.resolve();
516
+ await niwa.close();
517
+ await home.cleanup();
518
+ }
519
+ });
520
+
521
+ /** The plugin whose handler of the items writes an item itself, and the items it handled. */
522
+ function looping(seen: number[], opts: HandlerOptions = {}): Plugin {
523
+ return plugin("sub-loop", (api) => {
524
+ api.declare(Item, Answer);
525
+ api.on(Item, opts, async (data, step) => {
526
+ seen.push(data.n);
527
+ await step.emit(Item, { n: data.n + 1 });
528
+ });
529
+ });
530
+ }
531
+
532
+ test("a subscription is not woken by a record its own invocation caused", async () => {
533
+ const home = await tempHome();
534
+ try {
535
+ const seen: number[] = [];
536
+ const other: number[] = [];
537
+ const niwa = await serving(home.path, [
538
+ looping(seen),
539
+ plugin("sub-other", (api) => api.on(Item, { concurrency: Number.POSITIVE_INFINITY }, (data) => void other.push(data.n))),
540
+ ]);
541
+ await niwa.emit(Item, { n: 1 });
542
+ await eventually(() => other.length === 2);
543
+ await Bun.sleep(100);
544
+ // The other subscription sees the item the loop wrote; the loop does not see it.
545
+ expect(seen).toEqual([1]);
546
+ expect(other).toEqual([1, 2]);
547
+ await niwa.close();
548
+ } finally {
549
+ await home.cleanup();
550
+ }
551
+ });
552
+
553
+ test("a reentrant subscription is woken by its own records down to its depth, and says where it stopped", async () => {
554
+ const home = await tempHome();
555
+ const errors: string[] = [];
556
+ const original = console.error;
557
+ console.error = (...args: unknown[]) => void errors.push(args.map(String).join(" "));
558
+ try {
559
+ const seen: number[] = [];
560
+ const niwa = await serving(home.path, [looping(seen, { reentrant: { depth: 2 } })]);
561
+ await niwa.emit(Item, { n: 1 });
562
+ await eventually(() => seen.length === 3);
563
+ await eventually(async () => (await positionsOf(niwa)).some((one) => one.reason === "reentry"));
564
+ await Bun.sleep(100);
565
+ expect(seen).toEqual([1, 2, 3]);
566
+ expect(errors.some((line) => line.includes("sub-loop/sub-test.item") && line.includes("depth 2"))).toBe(true);
567
+ await niwa.close();
568
+ } finally {
569
+ console.error = original;
570
+ await home.cleanup();
571
+ }
572
+ });
573
+
574
+ test("a new subscription to a type the journal has no record of writes no position until there is one", async () => {
575
+ const home = await tempHome();
576
+ try {
577
+ const seen: number[] = [];
578
+ const niwa = await serving(home.path, [producer(), consumer((data) => void seen.push(data.n))]);
579
+ await niwa.emit(Answer, { n: 0 });
580
+ await Bun.sleep(50);
581
+ expect(await positionsOf(niwa)).toEqual([]);
582
+ await niwa.emit(Item, { n: 1 });
583
+ await eventually(() => seen.length === 1);
584
+ await niwa.close();
585
+ // After a restart it is not new: it goes on from what it admitted.
586
+ const again = await serving(home.path, [producer(), consumer((data) => void seen.push(data.n))]);
587
+ await again.emit(Item, { n: 2 });
588
+ await eventually(() => seen.length === 2);
589
+ expect(seen).toEqual([1, 2]);
590
+ expect(await positionsOf(again)).toEqual([]);
591
+ await again.close();
592
+ } finally {
593
+ await home.cleanup();
594
+ }
595
+ });
596
+
597
+ test("a subscription is not woken by a record its invocation caused through an action called as another principal", async () => {
598
+ const home = await tempHome();
599
+ try {
600
+ const seen: number[] = [];
601
+ const write = action("sub-test.write", {
602
+ description: "Write an item.",
603
+ input: z.object({ n: z.number() }),
604
+ output: z.object({}),
605
+ recovery: "repeat",
606
+ effect: "write",
607
+ run: async (input, ctx) => {
608
+ await ctx.emit(Item, { n: input.n });
609
+ return {};
610
+ },
611
+ });
612
+ const niwa = await serving(home.path, [
613
+ plugin("sub-loop", (api) => {
614
+ api.declare(Item, Answer);
615
+ api.action(write);
616
+ api.on(Item, async (data, step) => {
617
+ seen.push(data.n);
618
+ // The record is the action's, written as the principal: its actor is not the handler.
619
+ if (data.n < 5) await step(write, { n: data.n + 1 }, { as: { kind: "plugin", id: "sub-loop" as never } });
620
+ });
621
+ }),
622
+ ]);
623
+ await niwa.emit(Item, { n: 1 });
624
+ await eventually(() => seen.length >= 1);
625
+ await Bun.sleep(200);
626
+ expect(seen).toEqual([1]);
627
+ expect((await recordsOf(niwa, Item.name)).length).toBe(2);
628
+ await niwa.close();
629
+ } finally {
630
+ await home.cleanup();
631
+ }
632
+ });