@niwa-labs/host 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +2 -2
- package/package.json +16 -4
- package/src/access-actions.ts +193 -0
- package/src/access-control.ts +333 -0
- package/src/call-operations.ts +176 -0
- package/src/cockpit-catalog.ts +99 -0
- package/src/describe.ts +55 -0
- package/src/doors.ts +272 -0
- package/src/host-types.ts +43 -0
- package/src/host.ts +3346 -0
- package/src/index.ts +10 -0
- package/src/plugin-install.ts +249 -0
- package/src/state.ts +261 -0
- package/src/stores.ts +131 -0
- package/test/abandon.test.ts +58 -0
- package/test/action-refusal-restart.test.ts +46 -0
- package/test/action-step.test.ts +363 -0
- package/test/action-wait-restart.test.ts +96 -0
- package/test/builtin-actions.test.ts +21 -0
- package/test/cancel-steps.test.ts +150 -0
- package/test/catch-up.test.ts +378 -0
- package/test/causes.test.ts +138 -0
- package/test/client.test.ts +190 -0
- package/test/cockpit-catalog.test.ts +118 -0
- package/test/crash-between-steps.test.ts +88 -0
- package/test/declared-values.test.ts +175 -0
- package/test/deep-nested-pause.test.ts +147 -0
- package/test/fixtures/action-step-host.ts +166 -0
- package/test/fixtures/action-wait-restart-host.ts +62 -0
- package/test/fixtures/catch-up-host.ts +91 -0
- package/test/fixtures/causes-host.ts +78 -0
- package/test/fixtures/client-host.ts +52 -0
- package/test/fixtures/crash-between-steps-host.ts +71 -0
- package/test/fixtures/declared-values-host.ts +110 -0
- package/test/fixtures/intercept-order-host.ts +112 -0
- package/test/fixtures/intercept-step-host.ts +106 -0
- package/test/fixtures/live-frames-host.ts +81 -0
- package/test/fixtures/long-wait-host.ts +78 -0
- package/test/fixtures/nested-wait-host.ts +120 -0
- package/test/fixtures/no-repeat-crash-host.ts +79 -0
- package/test/fixtures/plugin-replace-host.ts +176 -0
- package/test/fixtures/record-refusal-crash.ts +50 -0
- package/test/fixtures/recovery-contracts-host.ts +79 -0
- package/test/fixtures/repeated-write-host.ts +39 -0
- package/test/fixtures/replay-mismatch-host.ts +66 -0
- package/test/fixtures/single-writer-host.ts +113 -0
- package/test/fixtures/state-host.ts +118 -0
- package/test/fixtures/wait-restart-host.ts +82 -0
- package/test/guards.test.ts +448 -0
- package/test/handler-emit.test.ts +116 -0
- package/test/host.test.ts +114 -0
- package/test/intercept-adjust.test.ts +318 -0
- package/test/intercept-order.test.ts +276 -0
- package/test/intercept-step.test.ts +144 -0
- package/test/large-outcome.test.ts +60 -0
- package/test/live-frames.test.ts +150 -0
- package/test/live-ready.test.ts +61 -0
- package/test/long-wait.test.ts +168 -0
- package/test/nested-outcome.test.ts +75 -0
- package/test/nested-wait.test.ts +111 -0
- package/test/no-repeat-crash.test.ts +132 -0
- package/test/offer-replace.test.ts +39 -0
- package/test/plugin-async-setup.test.ts +22 -0
- package/test/plugin-copies.test.ts +87 -0
- package/test/plugin-emit.test.ts +43 -0
- package/test/plugin-install-failure.test.ts +121 -0
- package/test/plugin-install-hash.test.ts +57 -0
- package/test/plugin-needs.test.ts +80 -0
- package/test/plugin-replace.test.ts +225 -0
- package/test/plugin-uninstall.test.ts +70 -0
- package/test/plugin-version-copies.test.ts +53 -0
- package/test/plugin-version.test.ts +180 -0
- package/test/read-filter.test.ts +136 -0
- package/test/read-query.test.ts +92 -0
- package/test/record-admission.test.ts +294 -0
- package/test/recovery-contracts.test.ts +107 -0
- package/test/repeated-write.test.ts +119 -0
- package/test/replay-mismatch.test.ts +79 -0
- package/test/replay.test.ts +135 -0
- package/test/single-writer.test.ts +267 -0
- package/test/state.test.ts +246 -0
- package/test/step-by-name.test.ts +122 -0
- package/test/stores.test.ts +102 -0
- package/test/stream.test.ts +154 -0
- package/test/subscriber-stream.test.ts +71 -0
- package/test/subscribers.test.ts +101 -0
- package/test/subscriptions.test.ts +632 -0
- package/test/trace-call.test.ts +124 -0
- package/test/trigger-filter.test.ts +42 -0
- package/test/use-many.test.ts +151 -0
- package/test/wait-query.test.ts +117 -0
- package/test/wait-restart.test.ts +187 -0
- package/test/wire-read-access.test.ts +85 -0
- package/tsconfig.json +6 -0
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
// The owner cancels the steps of an invocation under some keys: the call that is in flight is
|
|
2
|
+
// aborted, a waiting invocation runs again so its wait ends, and the rest of the handler goes on.
|
|
3
|
+
|
|
4
|
+
import { expect, test } from "bun:test";
|
|
5
|
+
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
|
|
8
|
+
import { CANCEL_STEPS_ACTION, StepCancelled, action, record } from "@niwa-labs/core";
|
|
9
|
+
import type { ActionName, StoredRecord } from "@niwa-labs/core";
|
|
10
|
+
import { createNiwa } from "@niwa-labs/host";
|
|
11
|
+
import { plugin } from "@niwa-labs/plugin";
|
|
12
|
+
import { eventually, tempHome } from "@niwa-labs/testing";
|
|
13
|
+
|
|
14
|
+
const Start = record("cancel.start", z.object({}));
|
|
15
|
+
const Never = record("cancel.never", z.object({ id: z.string() }));
|
|
16
|
+
|
|
17
|
+
test("cancelled steps end as cancelled: the call in flight is aborted and the wait of a waiting invocation ends", async () => {
|
|
18
|
+
const home = await tempHome();
|
|
19
|
+
const niwa = createNiwa({ home: home.path });
|
|
20
|
+
const ended: string[] = [];
|
|
21
|
+
let aborted = false;
|
|
22
|
+
niwa.use(
|
|
23
|
+
plugin("cancel", (api) => {
|
|
24
|
+
api.declare(Start, Never);
|
|
25
|
+
api.action(
|
|
26
|
+
action("cancel.long", {
|
|
27
|
+
description: "runs until it is aborted",
|
|
28
|
+
input: z.object({}),
|
|
29
|
+
output: z.object({}),
|
|
30
|
+
recovery: "do-not-repeat",
|
|
31
|
+
effect: "write",
|
|
32
|
+
run: (_input, ctx) =>
|
|
33
|
+
new Promise((_resolve, reject) => {
|
|
34
|
+
ctx.signal?.addEventListener("abort", () => {
|
|
35
|
+
aborted = true;
|
|
36
|
+
reject(new Error("aborted"));
|
|
37
|
+
});
|
|
38
|
+
}),
|
|
39
|
+
}),
|
|
40
|
+
);
|
|
41
|
+
api.on(Start, async (_data, step) => {
|
|
42
|
+
const branch = async (name: string, body: () => Promise<unknown>): Promise<void> => {
|
|
43
|
+
try {
|
|
44
|
+
await body();
|
|
45
|
+
ended.push(`${name}: done`);
|
|
46
|
+
} catch (error) {
|
|
47
|
+
if (!(error instanceof StepCancelled)) throw error;
|
|
48
|
+
ended.push(`${name}: ${error.reason}`);
|
|
49
|
+
}
|
|
50
|
+
};
|
|
51
|
+
await Promise.all([
|
|
52
|
+
branch("long", () => step("cancel.long" as ActionName, {}, { key: "a.call-1" })),
|
|
53
|
+
branch("wait", () => step.wait(Never, { key: "b.wait", filter: { id: "x" } })),
|
|
54
|
+
]);
|
|
55
|
+
await step.emit(Never, { id: "after" }, { key: "after" });
|
|
56
|
+
});
|
|
57
|
+
}),
|
|
58
|
+
);
|
|
59
|
+
await niwa.serve();
|
|
60
|
+
const records: StoredRecord[] = [];
|
|
61
|
+
void (async () => {
|
|
62
|
+
for await (const stored of niwa.records.since()) records.push(stored);
|
|
63
|
+
})();
|
|
64
|
+
try {
|
|
65
|
+
await niwa.emit(Start, {});
|
|
66
|
+
const invocation = () =>
|
|
67
|
+
(records.find((row) => row.type === "niwa.invocation.admitted" && (row.data as { handler: string }).handler.startsWith("cancel/"))?.data as
|
|
68
|
+
| { invocation: string }
|
|
69
|
+
| undefined)?.invocation;
|
|
70
|
+
const states = () =>
|
|
71
|
+
records.filter((row) => row.type === "niwa.invocation.state").map((row) => (row.data as { state: string }).state);
|
|
72
|
+
await eventually(() => states().includes("waiting"), 10_000, "the invocation should wait");
|
|
73
|
+
const id = invocation();
|
|
74
|
+
expect(id).toBeDefined();
|
|
75
|
+
|
|
76
|
+
await niwa.call(CANCEL_STEPS_ACTION, { invocation: id, prefixes: ["a", "b"], reason: "stopped by the owner" } as never);
|
|
77
|
+
await eventually(() => states().at(-1) === "done", 10_000, "the invocation should end");
|
|
78
|
+
expect(aborted).toBe(true);
|
|
79
|
+
expect([...new Set(ended)].sort()).toEqual(["long: stopped by the owner", "wait: stopped by the owner"]);
|
|
80
|
+
expect(records.some((row) => row.type === "cancel.never" && (row.data as { id: string }).id === "after")).toBe(true);
|
|
81
|
+
const outcomes = records
|
|
82
|
+
.filter((row) => row.type === "niwa.step.outcome")
|
|
83
|
+
.map((row) => row.data as { key: string; outcome: { status: string } })
|
|
84
|
+
.filter((row) => row.key === "a.call-1" || row.key === "b.wait")
|
|
85
|
+
.map((row) => row.outcome.status);
|
|
86
|
+
expect(outcomes).toEqual(["cancelled", "cancelled"]);
|
|
87
|
+
} finally {
|
|
88
|
+
await niwa.close();
|
|
89
|
+
await home.cleanup();
|
|
90
|
+
}
|
|
91
|
+
}, 30_000);
|
|
92
|
+
|
|
93
|
+
test("an invocation whose steps are cancelled while it runs runs again when it ends waiting on one of them", async () => {
|
|
94
|
+
const home = await tempHome();
|
|
95
|
+
const niwa = createNiwa({ home: home.path });
|
|
96
|
+
let release: () => void = () => undefined;
|
|
97
|
+
const released = new Promise<void>((resolve) => {
|
|
98
|
+
release = resolve;
|
|
99
|
+
});
|
|
100
|
+
const ends: string[] = [];
|
|
101
|
+
niwa.use(
|
|
102
|
+
plugin("cancel", (api) => {
|
|
103
|
+
api.declare(Start, Never);
|
|
104
|
+
api.action(
|
|
105
|
+
action("cancel.slow", {
|
|
106
|
+
description: "answers when the test releases it",
|
|
107
|
+
input: z.object({}),
|
|
108
|
+
output: z.object({}),
|
|
109
|
+
recovery: "repeat",
|
|
110
|
+
effect: "write",
|
|
111
|
+
run: async () => {
|
|
112
|
+
await released;
|
|
113
|
+
return {};
|
|
114
|
+
},
|
|
115
|
+
}),
|
|
116
|
+
);
|
|
117
|
+
api.on(Start, async (_data, step) => {
|
|
118
|
+
// The wait suspends at once, and the handler goes on with its slow step before it gives the suspend back.
|
|
119
|
+
const waited = step.wait(Never, { key: "b.wait", filter: { id: "x" } }).then(
|
|
120
|
+
() => "answered",
|
|
121
|
+
(error: unknown) => error,
|
|
122
|
+
);
|
|
123
|
+
await step("cancel.slow" as ActionName, {}, { key: "slow" });
|
|
124
|
+
const outcome = await waited;
|
|
125
|
+
if (outcome instanceof StepCancelled) {
|
|
126
|
+
ends.push(outcome.reason);
|
|
127
|
+
return;
|
|
128
|
+
}
|
|
129
|
+
throw outcome;
|
|
130
|
+
});
|
|
131
|
+
}),
|
|
132
|
+
);
|
|
133
|
+
await niwa.serve();
|
|
134
|
+
const records: StoredRecord[] = [];
|
|
135
|
+
void (async () => {
|
|
136
|
+
for await (const stored of niwa.records.since()) records.push(stored);
|
|
137
|
+
})();
|
|
138
|
+
try {
|
|
139
|
+
await niwa.emit(Start, {});
|
|
140
|
+
await eventually(() => records.some((row) => row.type === "niwa.step.intent" && (row.data as { key: string }).key === "b.wait"), 10_000, "the wait should begin");
|
|
141
|
+
const invocation = (records.find((row) => row.type === "niwa.invocation.admitted")?.data as { invocation: string }).invocation;
|
|
142
|
+
await niwa.call(CANCEL_STEPS_ACTION, { invocation, prefixes: ["b"], reason: "given up" } as never);
|
|
143
|
+
release();
|
|
144
|
+
await eventually(() => ends.length > 0, 10_000, "the invocation should run again and meet the cancel");
|
|
145
|
+
expect(ends).toEqual(["given up"]);
|
|
146
|
+
} finally {
|
|
147
|
+
await niwa.close();
|
|
148
|
+
await home.cleanup();
|
|
149
|
+
}
|
|
150
|
+
}, 30_000);
|
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
// Catching up.
|
|
2
|
+
//
|
|
3
|
+
// The scenario runs against real host processes (fixtures/catch-up-host.ts), in
|
|
4
|
+
// two variants chosen by argv[3]:
|
|
5
|
+
//
|
|
6
|
+
// 1. spawn the host in the variant "nohandler": the plugin declares the type
|
|
7
|
+
// Item, but no handler is installed
|
|
8
|
+
// 2. emit Item { n: 1 } … Item { n: 5 }; they are written and stay unhandled
|
|
9
|
+
// 3. stop the host — a clean shutdown
|
|
10
|
+
// 4. spawn the host in the variant "handler", whose handler asks for the
|
|
11
|
+
// history: it catches up with what the journal holds, and every item is handled — the action "seen" is called
|
|
12
|
+
// once per item, and the records the core writes for the outcomes carry
|
|
13
|
+
// the number of the item, so the order of the handling is visible
|
|
14
|
+
// 5. the five items were handled exactly once each, and in order
|
|
15
|
+
// 6. stop the host, spawn it again in the same variant: the counts stay at
|
|
16
|
+
// five — nothing is handled a second time
|
|
17
|
+
//
|
|
18
|
+
// The count is the count of real calls to the stub, and the order is read from
|
|
19
|
+
// the journal through records.since — the public way to read what happened.
|
|
20
|
+
//
|
|
21
|
+
// Only the public API is used: the entries of the packages and "@niwa-labs/testing".
|
|
22
|
+
|
|
23
|
+
import { expect, test } from "bun:test";
|
|
24
|
+
import { resolve } from "node:path";
|
|
25
|
+
import { fileURLToPath } from "node:url";
|
|
26
|
+
|
|
27
|
+
import { seq } from "@niwa-labs/core";
|
|
28
|
+
import type { StoredRecord } from "@niwa-labs/core";
|
|
29
|
+
import { counter, eventually, tempHome, connectAsOwner } from "@niwa-labs/testing";
|
|
30
|
+
import { z } from "zod";
|
|
31
|
+
|
|
32
|
+
import { Item } from "./fixtures/catch-up-host.ts";
|
|
33
|
+
|
|
34
|
+
const HOST_SCRIPT = fileURLToPath(new URL("./fixtures/catch-up-host.ts", import.meta.url));
|
|
35
|
+
|
|
36
|
+
/** The type the core writes when it admits an invocation. */
|
|
37
|
+
const ADMITTED_TYPE = "niwa.invocation.admitted";
|
|
38
|
+
|
|
39
|
+
/** The type the core writes for the outcome of a step. */
|
|
40
|
+
const OUTCOME_TYPE = "niwa.step.outcome";
|
|
41
|
+
|
|
42
|
+
/** The type the core writes for every change of an invocation's state. */
|
|
43
|
+
const STATE_TYPE = "niwa.invocation.state";
|
|
44
|
+
|
|
45
|
+
/** The handler of the items. */
|
|
46
|
+
const ITEM_HANDLER = "catch-up/catch-up.item";
|
|
47
|
+
|
|
48
|
+
/** From the beginning of the journal. */
|
|
49
|
+
const FROM_START = seq(0);
|
|
50
|
+
|
|
51
|
+
/** The data of a CORE.invocationAdmitted record. */
|
|
52
|
+
const Admitted = z.object({
|
|
53
|
+
invocation: z.string(),
|
|
54
|
+
handler: z.string(),
|
|
55
|
+
record: z.string(),
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
/** The data of a CORE.stepOutcome record: { invocation, key, outcome }. */
|
|
59
|
+
const StepOutcome = z.object({
|
|
60
|
+
invocation: z.string(),
|
|
61
|
+
key: z.string(),
|
|
62
|
+
outcome: z.object({
|
|
63
|
+
status: z.string(),
|
|
64
|
+
value: z.unknown().optional(),
|
|
65
|
+
}),
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
/** The data of a CORE.invocationState record: { invocation, state, reason? }. */
|
|
69
|
+
const InvocationState = z.object({
|
|
70
|
+
invocation: z.string(),
|
|
71
|
+
state: z.string(),
|
|
72
|
+
reason: z.string().optional(),
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
/** The number of an item, as the outcome of the "seen" step carries it. */
|
|
76
|
+
const Handled = z.object({ n: z.number() });
|
|
77
|
+
|
|
78
|
+
/** The data of an Item record: { n }. */
|
|
79
|
+
const ItemData = z.object({ n: z.number() });
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* The numbers of the items the journal holds, in the order the journal holds
|
|
83
|
+
* them: the items themselves, not their handling.
|
|
84
|
+
*/
|
|
85
|
+
function itemNumbers(records: StoredRecord[]): number[] {
|
|
86
|
+
const numbers: number[] = [];
|
|
87
|
+
for (const record of records) {
|
|
88
|
+
if (record.type !== Item.name) continue;
|
|
89
|
+
const parsed = ItemData.safeParse(record.data);
|
|
90
|
+
if (parsed.success) numbers.push(parsed.data.n);
|
|
91
|
+
}
|
|
92
|
+
return numbers;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* A host process of one variant.
|
|
97
|
+
*
|
|
98
|
+
* The variant is the third argument of the program, and the helper of
|
|
99
|
+
* `spawnHost` of "@niwa-labs/testing" passes the home only, so the check spawns the process itself.
|
|
100
|
+
*/
|
|
101
|
+
interface VariantHost {
|
|
102
|
+
readonly pid: number;
|
|
103
|
+
/** Resolves when the host accepts a connection on its socket. */
|
|
104
|
+
ready(): Promise<void>;
|
|
105
|
+
/** Stop the host: SIGTERM, and the host closes the journal itself. */
|
|
106
|
+
stop(): Promise<void>;
|
|
107
|
+
/** What the host printed, for the report of a failure. */
|
|
108
|
+
output(): string;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** Spawn the host program of one variant: `bun <script> <home> <variant>`. */
|
|
112
|
+
function spawnVariant(home: string, variant: string): VariantHost {
|
|
113
|
+
const child = Bun.spawn([process.execPath, HOST_SCRIPT, home, variant], {
|
|
114
|
+
cwd: resolve(HOST_SCRIPT, ".."),
|
|
115
|
+
stdout: "pipe",
|
|
116
|
+
stderr: "pipe",
|
|
117
|
+
env: process.env,
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
const chunks: string[] = [];
|
|
121
|
+
const collect = async (stream: ReadableStream<Uint8Array> | null): Promise<void> => {
|
|
122
|
+
if (stream === null) return;
|
|
123
|
+
const decoder = new TextDecoder();
|
|
124
|
+
try {
|
|
125
|
+
for await (const chunk of stream) chunks.push(decoder.decode(chunk, { stream: true }));
|
|
126
|
+
const tail = decoder.decode();
|
|
127
|
+
if (tail) chunks.push(tail);
|
|
128
|
+
} catch {
|
|
129
|
+
// The stream was closed with the process: what was read is what there is.
|
|
130
|
+
}
|
|
131
|
+
};
|
|
132
|
+
void collect(child.stdout);
|
|
133
|
+
void collect(child.stderr);
|
|
134
|
+
|
|
135
|
+
let gone = false;
|
|
136
|
+
void child.exited.then(() => {
|
|
137
|
+
gone = true;
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
return {
|
|
141
|
+
pid: child.pid,
|
|
142
|
+
async ready(): Promise<void> {
|
|
143
|
+
const deadline = Date.now() + 10_000;
|
|
144
|
+
for (;;) {
|
|
145
|
+
try {
|
|
146
|
+
const probe = await connectAsOwner(home);
|
|
147
|
+
await probe.close();
|
|
148
|
+
return;
|
|
149
|
+
} catch {
|
|
150
|
+
if (gone) {
|
|
151
|
+
throw new Error(
|
|
152
|
+
`the host process exited before it was ready.\n--- output ---\n${chunks.join("")}`,
|
|
153
|
+
);
|
|
154
|
+
}
|
|
155
|
+
if (Date.now() >= deadline) {
|
|
156
|
+
throw new Error(
|
|
157
|
+
`the host did not accept a connection within 10000 ms.\n--- output ---\n${chunks.join("")}`,
|
|
158
|
+
);
|
|
159
|
+
}
|
|
160
|
+
await new Promise((resolveWait) => setTimeout(resolveWait, 20));
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
},
|
|
164
|
+
async stop(): Promise<void> {
|
|
165
|
+
if (gone) {
|
|
166
|
+
await child.exited;
|
|
167
|
+
return;
|
|
168
|
+
}
|
|
169
|
+
child.kill("SIGTERM");
|
|
170
|
+
const exited = await Promise.race([
|
|
171
|
+
child.exited.then(() => true),
|
|
172
|
+
new Promise<boolean>((resolveWait) => setTimeout(() => resolveWait(false), 5_000)),
|
|
173
|
+
]);
|
|
174
|
+
if (!exited) child.kill("SIGKILL");
|
|
175
|
+
await child.exited;
|
|
176
|
+
},
|
|
177
|
+
output(): string {
|
|
178
|
+
return chunks.join("");
|
|
179
|
+
},
|
|
180
|
+
};
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** The invocations the host admitted, in the order the journal holds them. */
|
|
184
|
+
function admittedInvocations(records: StoredRecord[]): string[] {
|
|
185
|
+
const invocations: string[] = [];
|
|
186
|
+
for (const record of records) {
|
|
187
|
+
if (record.type !== ADMITTED_TYPE) continue;
|
|
188
|
+
const parsed = Admitted.safeParse(record.data);
|
|
189
|
+
if (parsed.success && parsed.data.handler === ITEM_HANDLER) invocations.push(parsed.data.invocation);
|
|
190
|
+
}
|
|
191
|
+
return invocations;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* The numbers of the items that were handled, in the order the outcomes were
|
|
196
|
+
* written: that is the order the handler worked in.
|
|
197
|
+
*/
|
|
198
|
+
function handledNumbers(records: StoredRecord[]): number[] {
|
|
199
|
+
const numbers: number[] = [];
|
|
200
|
+
for (const record of records) {
|
|
201
|
+
if (record.type !== OUTCOME_TYPE) continue;
|
|
202
|
+
const parsed = StepOutcome.safeParse(record.data);
|
|
203
|
+
if (!parsed.success) continue;
|
|
204
|
+
if (parsed.data.outcome.status !== "completed") continue;
|
|
205
|
+
const value = Handled.safeParse(parsed.data.outcome.value);
|
|
206
|
+
if (value.success) numbers.push(value.data.n);
|
|
207
|
+
}
|
|
208
|
+
return numbers;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* The latest state of every invocation the journal holds.
|
|
213
|
+
*
|
|
214
|
+
* A catch-up that went wrong would show here: an invocation that ended as
|
|
215
|
+
* "paused" or is still "running" was not handled.
|
|
216
|
+
*/
|
|
217
|
+
function latestStates(records: StoredRecord[]): Map<string, string> {
|
|
218
|
+
const states = new Map<string, string>();
|
|
219
|
+
for (const record of records) {
|
|
220
|
+
if (record.type !== STATE_TYPE) continue;
|
|
221
|
+
const parsed = InvocationState.safeParse(record.data);
|
|
222
|
+
if (parsed.success) states.set(parsed.data.invocation, parsed.data.state);
|
|
223
|
+
}
|
|
224
|
+
return states;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
test("catching up: the items are handled exactly once and in order, and a restart handles nothing twice", async () => {
|
|
228
|
+
const home = await tempHome();
|
|
229
|
+
const homePath = home.path;
|
|
230
|
+
const clients: Array<{ close(): Promise<void> }> = [];
|
|
231
|
+
const hosts: VariantHost[] = [];
|
|
232
|
+
|
|
233
|
+
try {
|
|
234
|
+
// 1. A host without the handler: it receives the items and does not handle
|
|
235
|
+
// them.
|
|
236
|
+
const writer = spawnVariant(homePath, "nohandler");
|
|
237
|
+
hosts.push(writer);
|
|
238
|
+
await writer.ready();
|
|
239
|
+
|
|
240
|
+
const client = await connectAsOwner(homePath);
|
|
241
|
+
clients.push(client);
|
|
242
|
+
const reader = await connectAsOwner(homePath);
|
|
243
|
+
clients.push(reader);
|
|
244
|
+
const before: StoredRecord[] = [];
|
|
245
|
+
const readBefore = (async () => {
|
|
246
|
+
for await (const record of reader.records.since()) {
|
|
247
|
+
before.push(record);
|
|
248
|
+
}
|
|
249
|
+
})().catch(() => {});
|
|
250
|
+
|
|
251
|
+
// 2. Five items, written while nobody handles them.
|
|
252
|
+
for (const n of [1, 2, 3, 4, 5]) {
|
|
253
|
+
await client.emit(Item, { n });
|
|
254
|
+
}
|
|
255
|
+
expect(counter(homePath, "seen").count()).toBe(0);
|
|
256
|
+
|
|
257
|
+
// The items are in the journal, and nothing handled them: the host without
|
|
258
|
+
// the handler admitted no invocation at all.
|
|
259
|
+
await eventually(
|
|
260
|
+
() => itemNumbers(before).length === 5,
|
|
261
|
+
15_000,
|
|
262
|
+
"the five items should be in the journal",
|
|
263
|
+
);
|
|
264
|
+
expect(itemNumbers(before)).toEqual([1, 2, 3, 4, 5]);
|
|
265
|
+
expect(admittedInvocations(before).length).toBe(0);
|
|
266
|
+
expect(handledNumbers(before).length).toBe(0);
|
|
267
|
+
expect(counter(homePath, "seen").count()).toBe(0);
|
|
268
|
+
|
|
269
|
+
// 3. The host is stopped — a clean shutdown, not a crash.
|
|
270
|
+
await writer.stop();
|
|
271
|
+
await client.close().catch(() => {});
|
|
272
|
+
await reader.close().catch(() => {});
|
|
273
|
+
await readBefore;
|
|
274
|
+
|
|
275
|
+
// 4. The host with the handler starts and catches up with the journal.
|
|
276
|
+
const catcher = spawnVariant(homePath, "handler");
|
|
277
|
+
hosts.push(catcher);
|
|
278
|
+
await catcher.ready();
|
|
279
|
+
|
|
280
|
+
const observer = await connectAsOwner(homePath);
|
|
281
|
+
clients.push(observer);
|
|
282
|
+
const seen: StoredRecord[] = [];
|
|
283
|
+
const watch = (async () => {
|
|
284
|
+
for await (const record of observer.records.since()) {
|
|
285
|
+
seen.push(record);
|
|
286
|
+
}
|
|
287
|
+
})().catch(() => {});
|
|
288
|
+
|
|
289
|
+
// 5. Every item is handled, exactly once.
|
|
290
|
+
await eventually(
|
|
291
|
+
() => counter(homePath, "seen").count() === 5,
|
|
292
|
+
15_000,
|
|
293
|
+
"the five items should have been handled by the host with the handler",
|
|
294
|
+
);
|
|
295
|
+
|
|
296
|
+
expect(counter(homePath, "seen").count()).toBe(5);
|
|
297
|
+
|
|
298
|
+
// The observer reads the journal: it sees the admissions and the outcomes.
|
|
299
|
+
await eventually(
|
|
300
|
+
() => admittedInvocations(seen).length === 5,
|
|
301
|
+
15_000,
|
|
302
|
+
"the observer should have read the five admissions from the journal",
|
|
303
|
+
);
|
|
304
|
+
|
|
305
|
+
// One invocation per item: the handler was admitted five times, not more.
|
|
306
|
+
const invocations = admittedInvocations(seen);
|
|
307
|
+
expect(invocations.length).toBe(5);
|
|
308
|
+
expect(new Set(invocations).size).toBe(5);
|
|
309
|
+
|
|
310
|
+
// Each item was handled exactly once, and the items were handled in order.
|
|
311
|
+
await eventually(
|
|
312
|
+
() => handledNumbers(seen).length === 5,
|
|
313
|
+
15_000,
|
|
314
|
+
"the observer should have read the five outcomes from the journal",
|
|
315
|
+
);
|
|
316
|
+
const numbers = handledNumbers(seen);
|
|
317
|
+
expect(numbers).toEqual([1, 2, 3, 4, 5]);
|
|
318
|
+
|
|
319
|
+
// Every invocation ended as done: none of them paused or hung. The state record follows the
|
|
320
|
+
// outcome, so it is waited for.
|
|
321
|
+
await eventually(
|
|
322
|
+
() => invocations.every((invocation) => latestStates(seen).get(invocation) === "done"),
|
|
323
|
+
15_000,
|
|
324
|
+
"every invocation should have ended as done",
|
|
325
|
+
);
|
|
326
|
+
|
|
327
|
+
// 6. A restart handles nothing a second time: the counts stay at five.
|
|
328
|
+
await catcher.stop();
|
|
329
|
+
await observer.close().catch(() => {});
|
|
330
|
+
await watch;
|
|
331
|
+
|
|
332
|
+
const restarted = spawnVariant(homePath, "handler");
|
|
333
|
+
hosts.push(restarted);
|
|
334
|
+
await restarted.ready();
|
|
335
|
+
|
|
336
|
+
// The restarted host had time to catch up, and it had nothing to do.
|
|
337
|
+
await new Promise((resolveWait) => setTimeout(resolveWait, 1_000));
|
|
338
|
+
|
|
339
|
+
expect(counter(homePath, "seen").count()).toBe(5);
|
|
340
|
+
|
|
341
|
+
const afterRestart = await connectAsOwner(homePath);
|
|
342
|
+
clients.push(afterRestart);
|
|
343
|
+
const again: StoredRecord[] = [];
|
|
344
|
+
const watchAgain = (async () => {
|
|
345
|
+
for await (const record of afterRestart.records.since()) {
|
|
346
|
+
again.push(record);
|
|
347
|
+
}
|
|
348
|
+
})().catch(() => {});
|
|
349
|
+
|
|
350
|
+
// The journal holds the same five admissions and the same five outcomes:
|
|
351
|
+
// the restart handled nothing a second time.
|
|
352
|
+
await eventually(
|
|
353
|
+
() => admittedInvocations(again).length === 5 && handledNumbers(again).length === 5,
|
|
354
|
+
15_000,
|
|
355
|
+
"the reader should have read the journal after the restart",
|
|
356
|
+
);
|
|
357
|
+
expect(admittedInvocations(again).length).toBe(5);
|
|
358
|
+
expect(handledNumbers(again)).toEqual([1, 2, 3, 4, 5]);
|
|
359
|
+
expect(counter(homePath, "seen").count()).toBe(5);
|
|
360
|
+
|
|
361
|
+
// The restart added no state of its own: the five invocations kept the
|
|
362
|
+
// state they had, and no sixth one was admitted.
|
|
363
|
+
const afterStates = latestStates(again);
|
|
364
|
+
for (const invocation of admittedInvocations(again)) {
|
|
365
|
+
expect(afterStates.get(invocation)).toBe("done");
|
|
366
|
+
}
|
|
367
|
+
await afterRestart.close().catch(() => {});
|
|
368
|
+
await watchAgain;
|
|
369
|
+
} finally {
|
|
370
|
+
for (const client of clients) {
|
|
371
|
+
await client.close().catch(() => {});
|
|
372
|
+
}
|
|
373
|
+
for (const host of hosts) {
|
|
374
|
+
await host.stop().catch(() => {});
|
|
375
|
+
}
|
|
376
|
+
await home.cleanup();
|
|
377
|
+
}
|
|
378
|
+
}, 60_000);
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
// Causes.
|
|
2
|
+
//
|
|
3
|
+
// The scenario runs against a real host process (fixtures/causes-host.ts):
|
|
4
|
+
//
|
|
5
|
+
// 1. spawn the host, connect a client, emit Seed { n: 1 }
|
|
6
|
+
// 2. the handler writes two reports and one merged result with step.emit
|
|
7
|
+
// 3. the reports and the merged result have the seed as their cause and the
|
|
8
|
+
// seed's root as their root; the actor is the handler
|
|
9
|
+
// 4. the trace down from the root lists everything that grew from it: the
|
|
10
|
+
// two reports and the merged result, each record once, with its depth
|
|
11
|
+
// 5. the merged result depends on three inputs: the seed, the first report
|
|
12
|
+
// and the second report. It is reachable from each of the three — up
|
|
13
|
+
// through `causes` and down through `trace`.
|
|
14
|
+
//
|
|
15
|
+
// Only the public API is used: the entries of the packages and "@niwa-labs/testing".
|
|
16
|
+
|
|
17
|
+
import { expect, test } from "bun:test";
|
|
18
|
+
|
|
19
|
+
import { connect } from "@niwa-labs/client";
|
|
20
|
+
import { seq } from "@niwa-labs/core";
|
|
21
|
+
import type { StoredRecord } from "@niwa-labs/core";
|
|
22
|
+
import { eventually, spawnHost, tempHome, connectAsOwner } from "@niwa-labs/testing";
|
|
23
|
+
|
|
24
|
+
import { Done, Merged, Report, Seed } from "./fixtures/causes-host.ts";
|
|
25
|
+
import { fileURLToPath } from "node:url";
|
|
26
|
+
|
|
27
|
+
const HOST_SCRIPT = fileURLToPath(new URL("./fixtures/causes-host.ts", import.meta.url));
|
|
28
|
+
|
|
29
|
+
/** From the beginning of the journal. */
|
|
30
|
+
const FROM_START = seq(0);
|
|
31
|
+
|
|
32
|
+
/** The type of every record the handler wrote. */
|
|
33
|
+
function recordsOfType(records: StoredRecord[], type: string): StoredRecord[] {
|
|
34
|
+
return records.filter((record) => record.type === type);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
test("causes: a record written in a handler has the waking record as its cause, the trace from the root lists what grew from it, and a merged result is reachable from each of its three inputs", async () => {
|
|
38
|
+
const home = await tempHome();
|
|
39
|
+
const homePath = home.path;
|
|
40
|
+
let host: ReturnType<typeof spawnHost> | undefined;
|
|
41
|
+
|
|
42
|
+
try {
|
|
43
|
+
// 1. The host and a client.
|
|
44
|
+
host = spawnHost(HOST_SCRIPT, homePath);
|
|
45
|
+
await host.ready();
|
|
46
|
+
const client = await connectAsOwner(homePath);
|
|
47
|
+
|
|
48
|
+
// The observer reads the journal from the beginning.
|
|
49
|
+
const watcher = await connectAsOwner(homePath);
|
|
50
|
+
const seen: StoredRecord[] = [];
|
|
51
|
+
const watch = (async () => {
|
|
52
|
+
for await (const record of watcher.records.since()) {
|
|
53
|
+
seen.push(record);
|
|
54
|
+
}
|
|
55
|
+
})().catch(() => {});
|
|
56
|
+
|
|
57
|
+
// 2. The original input. It is the root of its own chain.
|
|
58
|
+
const seed = await client.emit(Seed, { n: 1 });
|
|
59
|
+
expect(seed.root).toBe(seed.id);
|
|
60
|
+
expect(seed.cause).toBeNull();
|
|
61
|
+
|
|
62
|
+
// The handler runs and writes its records.
|
|
63
|
+
await eventually(
|
|
64
|
+
() => recordsOfType(seen, Done.name).length === 1,
|
|
65
|
+
10_000,
|
|
66
|
+
"the handlers should write the merged result and the record after it",
|
|
67
|
+
);
|
|
68
|
+
|
|
69
|
+
const reports = recordsOfType(seen, Report.name);
|
|
70
|
+
const merged = recordsOfType(seen, Merged.name)[0];
|
|
71
|
+
expect(reports.length).toBe(2);
|
|
72
|
+
expect(merged).toBeDefined();
|
|
73
|
+
|
|
74
|
+
// 3. Every record written in the handler has the waking record as its
|
|
75
|
+
// cause, the root of the waking record as its root, and the handler as
|
|
76
|
+
// its actor.
|
|
77
|
+
for (const record of [...reports, merged!]) {
|
|
78
|
+
expect(record.cause).toBe(seed.id);
|
|
79
|
+
expect(record.root).toBe(seed.id);
|
|
80
|
+
expect(record.actor.kind).toBe("handler");
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// The record written by the handler of the merged result: the cause is the record that
|
|
84
|
+
// woke it, the root is still the original input — cause and root differ here.
|
|
85
|
+
const done = recordsOfType(seen, Done.name)[0];
|
|
86
|
+
expect(done?.cause).toBe(merged!.id);
|
|
87
|
+
expect(done?.root).toBe(seed.id);
|
|
88
|
+
expect(done?.actor.kind).toBe("handler");
|
|
89
|
+
|
|
90
|
+
// 4. The trace down from the root lists everything that grew from it.
|
|
91
|
+
const traced = await client.trace(seed.id);
|
|
92
|
+
const tracedTypes = traced.map((record) => record.type);
|
|
93
|
+
|
|
94
|
+
expect(tracedTypes).toContain(Report.name);
|
|
95
|
+
expect(tracedTypes).toContain(Merged.name);
|
|
96
|
+
expect(traced.filter((record) => record.type === Report.name).length).toBe(2);
|
|
97
|
+
expect(traced.filter((record) => record.type === Merged.name).length).toBe(1);
|
|
98
|
+
expect(traced.filter((record) => record.type === Done.name).length).toBe(1);
|
|
99
|
+
|
|
100
|
+
// Each record is listed once, and the depth says how far down it is.
|
|
101
|
+
expect(new Set(traced.map((record) => record.id)).size).toBe(traced.length);
|
|
102
|
+
expect(traced[0]?.id).toBe(seed.id);
|
|
103
|
+
expect(traced[0]?.depth).toBe(0);
|
|
104
|
+
for (const record of traced) {
|
|
105
|
+
if (record.id === seed.id) continue;
|
|
106
|
+
expect(record.depth).toBeGreaterThanOrEqual(record.id === done!.id ? 2 : 1);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
// The trace from the root reaches the merged result.
|
|
110
|
+
expect(traced.some((record) => record.id === merged!.id)).toBe(true);
|
|
111
|
+
|
|
112
|
+
// 5. The merged result depends on three inputs: the seed, the first report
|
|
113
|
+
// and the second report. It is reachable from each of them.
|
|
114
|
+
//
|
|
115
|
+
// "Reachable from" is answered by the two directions of the chain: the
|
|
116
|
+
// trace walks down from an input to what grew from it, and the causes of
|
|
117
|
+
// the merged result walk up to what it depends on.
|
|
118
|
+
const inputs = [seed.id, reports[0]!.id, reports[1]!.id];
|
|
119
|
+
for (const input of inputs) {
|
|
120
|
+
// Down from the input: the trace reaches the merged result.
|
|
121
|
+
const trace = await client.trace(input);
|
|
122
|
+
expect(trace.map((record) => record.id)).toContain(merged!.id);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// Up from the merged result: all three inputs are among its causes.
|
|
126
|
+
const causesOfMerged = await client.causes(merged!.id);
|
|
127
|
+
for (const input of inputs) {
|
|
128
|
+
expect(causesOfMerged.map((record) => record.id)).toContain(input);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
await client.close().catch(() => {});
|
|
132
|
+
await watcher.close().catch(() => {});
|
|
133
|
+
await watch;
|
|
134
|
+
} finally {
|
|
135
|
+
await host?.kill().catch(() => {});
|
|
136
|
+
await home.cleanup();
|
|
137
|
+
}
|
|
138
|
+
}, 30_000);
|