@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,110 @@
1
+ // The host program for the scenario "declared values".
2
+ //
3
+ // "A declared action appears in the self-description with its schemas.
4
+ // Writing a record of an undeclared type is rejected. Reading a record of an unknown type
5
+ // returns it with its raw data and runs no handler."
6
+ //
7
+ // The plugin declares one record type, Note { text }, an action, and a handler on Note:
8
+ // the handler counts, so the test can tell that it ran from that it did not.
9
+ //
10
+ // A second plugin, "declared-values-extra", declares the type declared-values.extra. It exists so the test can unload
11
+ // one plugin and leave a type that no plugin declares any more, with a record of it already in
12
+ // the journal.
13
+ //
14
+ // The control actions let the test unload the extra plugin through the public API:
15
+ //
16
+ // "fixture.unload" — niwa.unload("declared-values-extra")
17
+ //
18
+ // The home directory comes from argv[2]. The test imports this file for the record types and
19
+ // the control action, so the host only starts when the file is run directly.
20
+
21
+ import { action, record } from "@niwa-labs/core";
22
+ import { createNiwa } from "@niwa-labs/host";
23
+ import { plugin } from "@niwa-labs/plugin";
24
+ import type { Host } from "@niwa-labs/host";
25
+ import { stubAction } from "@niwa-labs/testing";
26
+ import { z } from "zod";
27
+
28
+ /** The record type the plugin declares. */
29
+ export const Note = record("declared-values.note", z.object({ text: z.string() }), { open: true });
30
+
31
+ /** The shape of the input of the actions. */
32
+ const Text = z.object({ text: z.string() });
33
+
34
+ /** The shape of the output of the actions. */
35
+ const Ok = z.object({ ok: z.boolean() });
36
+
37
+ /** The host this program runs. */
38
+ let host: Host | undefined;
39
+
40
+ /** The action the plugin declares: it shows up in the self-description. */
41
+ export const shout = action("declared-values.shout", {
42
+ description: "Returns its input, upper-cased.",
43
+ input: Text,
44
+ output: Text,
45
+ recovery: "do-not-repeat",
46
+ effect: "write",
47
+ run: async (input) => ({ text: input.text.toUpperCase() }),
48
+ });
49
+
50
+ /** Unload the extra plugin. Its declarations go; the records it wrote stay. */
51
+ export const unloadExtra = action("declared-values.unload-extra", {
52
+ description: "Unload the plugin declared-values-extra.",
53
+ input: z.object({}),
54
+ output: Ok,
55
+ recovery: "repeat",
56
+ effect: "write",
57
+ run: async () => {
58
+ if (host === undefined) {
59
+ throw new Error("declared-values.unload-extra: the host is not running");
60
+ }
61
+ host.unload("declared-values-extra" as never);
62
+ return { ok: true };
63
+ },
64
+ });
65
+
66
+ /** The plugin of this scenario. It needs the home: the stub counts there. */
67
+ export function makePlugin(home: string) {
68
+ // The handler of Note: it counts, so the test knows it ran.
69
+ const handle = stubAction("declared-values-handle", {
70
+ home,
71
+ input: Text,
72
+ output: Ok,
73
+ recovery: "repeat",
74
+ effect: "write",
75
+ result: () => ({ ok: true }),
76
+ });
77
+
78
+ return plugin("declared-values", (api) => {
79
+ api.declare(Note);
80
+ api.action(shout);
81
+ api.action(handle);
82
+ api.action(unloadExtra);
83
+ api.on(Note, async (data, step) => {
84
+ await step(handle, { text: data.text });
85
+ });
86
+ });
87
+ }
88
+
89
+ /** The extra plugin: when it is unloaded, no plugin declares declared-values.extra any more. */
90
+ export const extra = plugin("declared-values-extra", (api) => {
91
+ api.declare(record("declared-values.extra", z.object({ text: z.string() }), { open: true }));
92
+ });
93
+
94
+ if (import.meta.main) {
95
+ const home = process.argv[2];
96
+ if (!home) {
97
+ console.error("usage: bun declared-values-host.ts <home>");
98
+ process.exit(2);
99
+ }
100
+
101
+ const niwa = createNiwa({ home });
102
+ host = niwa;
103
+ niwa.use(makePlugin(home));
104
+ niwa.use(extra);
105
+ await niwa.serve();
106
+
107
+ process.on("SIGTERM", () => {
108
+ void niwa.close().then(() => process.exit(0));
109
+ });
110
+ }
@@ -0,0 +1,112 @@
1
+ // The host program for the scenario "intercept order".
2
+ //
3
+ // "An adjust changes the input; a guard sees the changed
4
+ // input, not the requested one. A denial is recorded with its reason and with both
5
+ // inputs, and the action does not run. On a retry the guard is asked again."
6
+ //
7
+ // The plugin declares one record type, Start, and one action, "intercept-order.send". The
8
+ // action writes every call into a file and returns its input, so the check can see
9
+ // which calls reached the outside and with what.
10
+ //
11
+ // Two intercepts are registered on the action:
12
+ //
13
+ // - an adjust that puts "adjusted" where the request said "requested";
14
+ // - a guard that refuses the text "forbidden", the first time it is asked.
15
+ //
16
+ // The guard writes down every time it is asked, and what it saw, so the check can
17
+ // see that the guard was asked again on a retry and that it saw the adjusted input
18
+ // and not the requested one.
19
+ //
20
+ // The home directory comes from argv[2]. The test imports this file for the record
21
+ // type and the action, so the host only starts when the file is run directly.
22
+
23
+ import { appendFileSync } from "node:fs";
24
+ import { join } from "node:path";
25
+
26
+ import { action, deny, record } from "@niwa-labs/core";
27
+ import { createNiwa } from "@niwa-labs/host";
28
+ import { plugin } from "@niwa-labs/plugin";
29
+ import { z } from "zod";
30
+
31
+ /** The record the test writes: it wakes the handler. */
32
+ export const Start = record("intercept-order.start", z.object({}), { open: true });
33
+
34
+ /** The text the guard refuses. */
35
+ export const FORBIDDEN = "forbidden";
36
+
37
+ /** What the request asked for, and what the adjust put there instead. */
38
+ export const REQUESTED = "requested";
39
+ export const ADJUSTED = "adjusted";
40
+
41
+ /** The file the guard writes what it saw into. */
42
+ export const GUARD_LOG = "guards.log";
43
+
44
+ /** The file the action writes every call into. */
45
+ export const CALL_LOG = "calls.log";
46
+
47
+ /** The action of this scenario: it writes every call into a file and returns its input. */
48
+ export const Send = action("intercept-order.send", {
49
+ description: "Sends something, if the guard allows it.",
50
+ input: z.object({ text: z.string() }),
51
+ output: z.object({ text: z.string() }),
52
+ recovery: "repeat",
53
+ effect: "write",
54
+ run: (input, ctx) => {
55
+ appendFileSync(join(home(), CALL_LOG), `${input.text}:${ctx.operationId}\n`);
56
+ return { text: input.text };
57
+ },
58
+ });
59
+
60
+ /** The home this program was started with. */
61
+ function home(): string {
62
+ return process.argv[2] as string;
63
+ }
64
+
65
+ /** The plugin of this scenario. */
66
+ export function makePlugin() {
67
+ // The guard refuses the forbidden text only the first time it is asked: the retry
68
+ // asks it again, and this time it allows the call. So the check sees both that
69
+ // the guard was asked again and that the new attempt went through.
70
+ let refused = 0;
71
+
72
+ return plugin("intercept-order", (api) => {
73
+ api.declare(Start);
74
+ api.action(Send);
75
+
76
+ // The adjust: it changes the input the action is called with.
77
+ api.adjust(Send, (input) => ({
78
+ text: input.text === REQUESTED ? ADJUSTED : input.text,
79
+ }));
80
+
81
+ // The guard: it sees the changed input, and it refuses one text.
82
+ api.guard(Send, (input, ctx) => {
83
+ appendFileSync(join(home(), GUARD_LOG), `${input.text}:${ctx.caller.kind}\n`);
84
+ if (input.text !== FORBIDDEN) return;
85
+ refused += 1;
86
+ if (refused === 1) return deny("not tonight");
87
+ });
88
+
89
+ // The handler: it calls the action with a text the request asks for, and then
90
+ // with the text the guard refuses.
91
+ api.on(Start, async (_data, step) => {
92
+ await step(Send, { text: REQUESTED }, { key: "allowed" });
93
+ await step(Send, { text: FORBIDDEN }, { key: "refused" });
94
+ });
95
+ });
96
+ }
97
+
98
+ if (import.meta.main) {
99
+ const homeArg = process.argv[2];
100
+ if (!homeArg) {
101
+ console.error("usage: bun intercept-order-host.ts <home>");
102
+ process.exit(2);
103
+ }
104
+
105
+ const niwa = createNiwa({ home: homeArg });
106
+ niwa.use(makePlugin());
107
+ await niwa.serve();
108
+
109
+ process.on("SIGTERM", () => {
110
+ void niwa.close().then(() => process.exit(0));
111
+ });
112
+ }
@@ -0,0 +1,106 @@
1
+ // The host program for the intercept step.
2
+ //
3
+ // "An intercept that itself needs a call to the outside (asking
4
+ // a model which lessons apply) makes it as a step of the invocation that is calling the action.
5
+ // No transaction is held while it waits."
6
+ //
7
+ // The plugin declares one record type, Start, and two actions:
8
+ //
9
+ // - "send" — the action the guard is registered on; it blocks on the gate "g1";
10
+ // - "look" — the call to the outside the guard makes; it counts its calls.
11
+ //
12
+ // The guard of "send" calls "look" through `ctx.step`, the step function of the invocation that
13
+ // is calling "send". Outside an invocation there is no such step: the guard says so in the log
14
+ // and allows the call.
15
+ //
16
+ // The home directory comes from argv[2]. The test imports this file for the record type and the
17
+ // actions, so the host only starts when the file is run directly.
18
+
19
+ import { appendFileSync } from "node:fs";
20
+ import { join } from "node:path";
21
+
22
+ import { createNiwa } from "@niwa-labs/host";
23
+ import { plugin } from "@niwa-labs/plugin";
24
+ import { record } from "@niwa-labs/core";
25
+ import { stubAction } from "@niwa-labs/testing";
26
+ import { z } from "zod";
27
+
28
+ /** The record the test writes: it wakes the handler. */
29
+ export const Start = record("interceptstep.start", z.object({}), { open: true });
30
+
31
+ /** The file the guard writes what it saw into. */
32
+ export const GUARD_LOG = "guard.log";
33
+
34
+ /** The home this program was started with. */
35
+ function home(): string {
36
+ return process.argv[2] as string;
37
+ }
38
+
39
+ /** The actions of the plugin: they need the home, because they count and wait there. */
40
+ export function actionsOf(homePath: string) {
41
+ // The call to the outside the guard makes. It counts its calls, so the test can tell one call
42
+ // from a repeat.
43
+ const look = stubAction("look", {
44
+ home: homePath,
45
+ input: z.object({ q: z.string() }),
46
+ output: z.object({ answer: z.string() }),
47
+ recovery: "repeat",
48
+ effect: "write",
49
+ result: (input) => ({ answer: `answer:${input.q}` }),
50
+ });
51
+
52
+ // The action the guard is registered on. It blocks on the gate, so the host can be killed
53
+ // while the call to the outside is already recorded.
54
+ const send = stubAction("send", {
55
+ home: homePath,
56
+ input: z.object({ text: z.string() }),
57
+ output: z.object({ text: z.string() }),
58
+ recovery: "repeat",
59
+ effect: "write",
60
+ gate: "g1",
61
+ result: (input) => ({ text: input.text }),
62
+ });
63
+
64
+ return { look, send };
65
+ }
66
+
67
+ /** The plugin of the intercept step. It needs the home: the stubs count and wait there. */
68
+ export function makePlugin(homePath: string) {
69
+ const { look, send } = actionsOf(homePath);
70
+
71
+ return plugin("interceptstep", (api) => {
72
+ api.declare(Start);
73
+ api.action(look);
74
+ api.action(send);
75
+
76
+ // The guard: it needs a call to the outside, so it makes it as a step of the invocation
77
+ // that is calling the action.
78
+ api.guard(send, async (_input, ctx) => {
79
+ const step = ctx.step;
80
+ appendFileSync(join(homePath, GUARD_LOG), `${step === undefined ? "outside" : "inside"}\n`);
81
+ if (step === undefined) return;
82
+ await step(look, { q: "lessons" });
83
+ });
84
+
85
+ // The handler: it calls the action the guard is registered on.
86
+ api.on(Start, async (_data, step) => {
87
+ await step(send, { text: "hello" }, { key: "k" });
88
+ });
89
+ });
90
+ }
91
+
92
+ if (import.meta.main) {
93
+ const homeArg = process.argv[2];
94
+ if (!homeArg) {
95
+ console.error("usage: bun intercept-step-host.ts <home>");
96
+ process.exit(2);
97
+ }
98
+
99
+ const niwa = createNiwa({ home: homeArg });
100
+ niwa.use(makePlugin(homeArg));
101
+ await niwa.serve();
102
+
103
+ process.on("SIGTERM", () => {
104
+ void niwa.close().then(() => process.exit(0));
105
+ });
106
+ }
@@ -0,0 +1,81 @@
1
+ // The host program for the scenario "live frames".
2
+ //
3
+ // "Live frames do not appear in the journal. A subscriber that
4
+ // received none of them still receives the complete record."
5
+ //
6
+ // The plugin declares one record type, Message { text }, and a handler on it. The handler
7
+ // sends a live frame on the channel "chat" and then writes the complete message as a record:
8
+ // the frame is what the interface is showing right now, the record is what happened.
9
+ //
10
+ // The two actions let the test send a frame and read the journal through the public API:
11
+ //
12
+ // "live-frames.frame" — send a live frame on the channel "chat"
13
+ //
14
+ // The home directory comes from argv[2]. The test imports this file for the record types and
15
+ // the action, so the host only starts when the file is run directly.
16
+
17
+ import { action, record } from "@niwa-labs/core";
18
+ import { createNiwa } from "@niwa-labs/host";
19
+ import { plugin } from "@niwa-labs/plugin";
20
+ import { z } from "zod";
21
+
22
+ /** The complete message: the record the journal holds. */
23
+ export const Message = record("live-frames.message", z.object({ text: z.string() }), { open: true });
24
+
25
+ /** The channel the live frames travel on. */
26
+ export const CHANNEL = "chat";
27
+
28
+ /** The shape of the input of the action that sends a frame. */
29
+ const Text = z.object({ text: z.string() });
30
+
31
+ /** The shape of the output of that action. */
32
+ const Ok = z.object({ ok: z.boolean() });
33
+
34
+ /** Send a live frame on the channel. */
35
+ export const sendFrame = action("live-frames.frame", {
36
+ description: "Send a live frame on the channel chat.",
37
+ input: Text,
38
+ output: Ok,
39
+ recovery: "repeat",
40
+ effect: "write",
41
+ run: async (input) => {
42
+ // The frame is not a record: it is never written to the journal.
43
+ if (niwa === undefined) {
44
+ throw new Error("live-frames.frame: the host is not running");
45
+ }
46
+ await niwa.live.send(CHANNEL, { channel: CHANNEL, data: { partial: input.text } });
47
+ return { ok: true };
48
+ },
49
+ });
50
+
51
+ /** The host this program runs: the action needs it to send a frame. */
52
+ let niwa: ReturnType<typeof createNiwa> | undefined;
53
+
54
+ /** The plugin of this scenario. */
55
+ export function makePlugin() {
56
+ return plugin("live-frames", (api) => {
57
+ api.declare(Message);
58
+ api.action(sendFrame);
59
+ api.on(Message, async (data) => {
60
+ // The live frame: what an interface shows while the message is being written.
61
+ api.live(CHANNEL, { channel: CHANNEL, data: { partial: data.text } });
62
+ });
63
+ });
64
+ }
65
+
66
+ if (import.meta.main) {
67
+ const home = process.argv[2];
68
+ if (!home) {
69
+ console.error("usage: bun live-frames-host.ts <home>");
70
+ process.exit(2);
71
+ }
72
+
73
+ const host = createNiwa({ home });
74
+ niwa = host;
75
+ host.use(makePlugin());
76
+ await host.serve();
77
+
78
+ process.on("SIGTERM", () => {
79
+ void host.close().then(() => process.exit(0));
80
+ });
81
+ }
@@ -0,0 +1,78 @@
1
+ // The host program for the scenario "a long wait blocks nothing".
2
+ //
3
+ // "One invocation waits on a request. Write ten more matching
4
+ // records. All ten are handled while the first still waits."
5
+ //
6
+ // The plugin declares three record types and two handlers:
7
+ //
8
+ // on Ask { n } — wait for Answer { n } and nothing else
9
+ // on Job { n } — call the action "job", which is counted
10
+ //
11
+ // The wait is a step of its own, so the Ask invocation suspends: the journal shows
12
+ // its state as "waiting" and the host is free for everything else. The ten Job
13
+ // records are therefore handled while the Ask invocation is still waiting, and the
14
+ // answer that arrives later satisfies the wait and ends the invocation as done.
15
+ //
16
+ // The home directory comes from argv[2]. The test imports this file for the record
17
+ // types, so the host only starts when the file is run directly.
18
+
19
+ import { createNiwa } from "@niwa-labs/host";
20
+ import { plugin } from "@niwa-labs/plugin";
21
+ import { record } from "@niwa-labs/core";
22
+ import { stubAction } from "@niwa-labs/testing";
23
+ import { z } from "zod";
24
+
25
+ /** Wakes the handler that waits. */
26
+ export const Ask = record("long-wait.ask", z.object({ n: z.number() }), { open: true });
27
+
28
+ /** What the waiting handler waits for. */
29
+ export const Answer = record("long-wait.answer", z.object({ n: z.number() }), { open: true });
30
+
31
+ /** Wakes the handler that works while the other one waits. */
32
+ export const Job = record("long-wait.job", z.object({ n: z.number() }), { open: true });
33
+
34
+ /** The plugin of this scenario. It needs the home: the stub counts there. */
35
+ export function makePlugin(home: string) {
36
+ // The work itself. Every call is counted, so the test can tell "ten jobs handled"
37
+ // from "ten job records written".
38
+ const job = stubAction("job", {
39
+ home,
40
+ input: z.object({ n: z.number() }),
41
+ output: z.object({ n: z.number() }),
42
+ recovery: "repeat",
43
+ effect: "write",
44
+ result: (input) => input,
45
+ });
46
+
47
+ return plugin("long-wait", (api) => {
48
+ api.declare(Ask, Answer, Job);
49
+ api.action(job);
50
+
51
+ // The long wait: the invocation suspends here and waits for its answer. Each question waits for
52
+ // its own answer, so the subscription runs them all at once.
53
+ api.on(Ask, { concurrency: Number.POSITIVE_INFINITY }, async (data, step) => {
54
+ await step.wait(Answer, { filter: { n: data.n } });
55
+ });
56
+
57
+ // The work that goes on while the other invocation waits.
58
+ api.on(Job, async (data, step) => {
59
+ await step(job, { n: data.n });
60
+ });
61
+ });
62
+ }
63
+
64
+ if (import.meta.main) {
65
+ const home = process.argv[2];
66
+ if (!home) {
67
+ console.error("usage: bun long-wait-host.ts <home>");
68
+ process.exit(2);
69
+ }
70
+
71
+ const niwa = createNiwa({ home });
72
+ niwa.use(makePlugin(home));
73
+ await niwa.serve();
74
+
75
+ process.on("SIGTERM", () => {
76
+ void niwa.close().then(() => process.exit(0));
77
+ });
78
+ }
@@ -0,0 +1,120 @@
1
+ // The host program for the nested-wait check (a wait inside a nested call is waiting, not cut off).
2
+ //
3
+ // The plugin declares three record types, five actions and one handler:
4
+ //
5
+ // on Start { n, mode } — call "top" (a chain three calls deep) or "after" (a wait, then a call)
6
+ // "top" -> "middle" -> "waiter" each do-not-repeat
7
+ // "waiter" waits inside itself for Answer { n }
8
+ // "after" -> "waiter", then "slow" a repeatable action whose second call is cut off on a gate
9
+ //
10
+ // After a restart the chain is entered again as waiting: no call of it is judged by its recovery
11
+ // contract while the wait inside the deepest one is pending.
12
+ //
13
+ // The home directory comes from argv[2]. The test imports this file for the record types, so the
14
+ // host only starts when the file is run directly.
15
+
16
+ import { action, actionName, record } from "@niwa-labs/core";
17
+ import { createNiwa } from "@niwa-labs/host";
18
+ import { plugin } from "@niwa-labs/plugin";
19
+ import { stubAction } from "@niwa-labs/testing";
20
+ import { z } from "zod";
21
+
22
+ /** Wakes the handler. */
23
+ export const Start = record("nested-wait.start", z.object({ n: z.number(), mode: z.enum(["top", "after"]) }), { open: true });
24
+
25
+ /** What the waiter waits for. */
26
+ export const Answer = record("nested-wait.answer", z.object({ n: z.number() }), { open: true });
27
+
28
+ /** What the handler wrote down when the chain ended. */
29
+ export const Done = record("nested-wait.done", z.object({ n: z.number() }));
30
+
31
+ const Input = z.object({ n: z.number() });
32
+ const Output = z.object({ n: z.number() });
33
+
34
+ /** The plugin of the nested-wait check. It needs the home: the counters live there. */
35
+ export function makePlugin(home: string) {
36
+ const waiter = action("waiter", {
37
+ description: "A call that is not repeated if cut off and waits inside itself for its answer.",
38
+ input: Input,
39
+ output: Output,
40
+ recovery: "do-not-repeat",
41
+ effect: "write",
42
+ async run(input, ctx) {
43
+ return (await ctx.wait(Answer, { filter: { n: input.n } })).data;
44
+ },
45
+ });
46
+
47
+ const middle = action("middle", {
48
+ description: "A call that is not repeated if cut off and calls the waiter.",
49
+ input: Input,
50
+ output: Output,
51
+ recovery: "do-not-repeat",
52
+ effect: "write",
53
+ async run(input, ctx) {
54
+ return ctx.step(actionName("waiter"), input);
55
+ },
56
+ });
57
+
58
+ const top = action("top", {
59
+ description: "A call that is not repeated if cut off and calls the middle one.",
60
+ input: Input,
61
+ output: Output,
62
+ recovery: "do-not-repeat",
63
+ effect: "write",
64
+ async run(input, ctx) {
65
+ return ctx.step(actionName("middle"), input);
66
+ },
67
+ });
68
+
69
+ // Cut off on its gate, and it must not be repeated.
70
+ const slow = stubAction("slow", {
71
+ home,
72
+ input: Input,
73
+ output: z.number(),
74
+ recovery: "do-not-repeat",
75
+ effect: "write",
76
+ gate: "g-slow",
77
+ result: (input) => input.n,
78
+ });
79
+
80
+ const after = action("after", {
81
+ description: "Calls the waiter, and after its answer calls an action that is cut off.",
82
+ input: Input,
83
+ output: Output,
84
+ recovery: "repeat",
85
+ effect: "write",
86
+ async run(input, ctx) {
87
+ await ctx.step(actionName("waiter"), input);
88
+ return { n: await ctx.step(actionName("slow"), input) };
89
+ },
90
+ });
91
+
92
+ return plugin("nested-wait", (api) => {
93
+ api.declare(Start, Answer, Done);
94
+ api.action(waiter);
95
+ api.action(middle);
96
+ api.action(top);
97
+ api.action(slow);
98
+ api.action(after);
99
+ api.on(Start, async (data, step) => {
100
+ const answer = await step(data.mode === "top" ? top : after, { n: data.n });
101
+ await step.emit(Done, { n: answer.n });
102
+ });
103
+ });
104
+ }
105
+
106
+ if (import.meta.main) {
107
+ const home = process.argv[2];
108
+ if (!home) {
109
+ console.error("usage: bun nested-wait-host.ts <home>");
110
+ process.exit(2);
111
+ }
112
+
113
+ const niwa = createNiwa({ home });
114
+ niwa.use(makePlugin(home));
115
+ await niwa.serve();
116
+
117
+ process.on("SIGTERM", () => {
118
+ void niwa.close().then(() => process.exit(0));
119
+ });
120
+ }
@@ -0,0 +1,79 @@
1
+ // The host program for the scenario "a call that must not be repeated".
2
+ //
3
+ // The plugin declares the record Start { n }. Its handler has one step:
4
+ //
5
+ // await step(effect, { n }) // effect hits its counter, then blocks on the gate "g1"
6
+ //
7
+ // The action has the "do-not-repeat" recovery contract: after a call whose outcome is unknown,
8
+ // the effect may have happened, so the action must not be called again on its own.
9
+ //
10
+ // The test kills the host while the action is blocked, so the step has an intent and no
11
+ // outcome: the call was cut off. On restart the outcome is unknown, the invocation pauses, and
12
+ // the pause offers the owner three choices: retry, skip, cancel.
13
+ //
14
+ // The test then calls "niwa.invocation.resolve" over the client:
15
+ //
16
+ // retry — the step is called again, as a new attempt
17
+ // skip — the step is not called again, the code continues
18
+ //
19
+ // The home directory comes from argv[2]. The test imports this file for the Start record
20
+ // type, so the host only starts when the file is run directly.
21
+
22
+ import { createNiwa } from "@niwa-labs/host";
23
+ import { plugin } from "@niwa-labs/plugin";
24
+ import { record } from "@niwa-labs/core";
25
+ import { stubAction } from "@niwa-labs/testing";
26
+ import { z } from "zod";
27
+
28
+ export const Start = record("no-repeat-crash.start", z.object({ n: z.number() }), { open: true });
29
+
30
+ /** The plugin of this scenario. It needs the home: the stub counts and waits there. */
31
+ export function makePlugin(home: string) {
32
+ // The effect that must not be repeated.
33
+ const effect = stubAction("effect", {
34
+ home,
35
+ input: z.object({ n: z.number() }),
36
+ output: z.number(),
37
+ recovery: "do-not-repeat",
38
+ effect: "write",
39
+ gate: "g1",
40
+ result: (input) => input.n,
41
+ });
42
+
43
+ // What the handler does after the step, so a test can see the code continued.
44
+ const after = stubAction("after", {
45
+ home,
46
+ input: z.object({ n: z.number() }),
47
+ output: z.number(),
48
+ recovery: "repeat",
49
+ effect: "write",
50
+ result: (input) => input.n,
51
+ });
52
+
53
+ return plugin("no-repeat-crash", (api) => {
54
+ api.declare(Start);
55
+ api.action(effect);
56
+ api.action(after);
57
+ api.on(Start, async (data, step) => {
58
+ const value = await step(effect, { n: data.n });
59
+ // A skipped step gives no value: the code continues without it.
60
+ await step(after, { n: value ?? -1 });
61
+ });
62
+ });
63
+ }
64
+
65
+ if (import.meta.main) {
66
+ const home = process.argv[2];
67
+ if (!home) {
68
+ console.error("usage: bun no-repeat-crash-host.ts <home>");
69
+ process.exit(2);
70
+ }
71
+
72
+ const niwa = createNiwa({ home });
73
+ niwa.use(makePlugin(home));
74
+ await niwa.serve();
75
+
76
+ process.on("SIGTERM", () => {
77
+ void niwa.close().then(() => process.exit(0));
78
+ });
79
+ }