@niwa-labs/web 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.
@@ -0,0 +1,83 @@
1
+ // The feed is read whole and then followed, and neither waits for the journal to fall silent.
2
+ //
3
+ // 1. the list as it stands is what a read answers, however late the live subscription says anything
4
+ // 2. a followed feed starts with that list and goes on from its position, so no record is lost between the two
5
+ // 3. a steady stream of records still gets its lists out: they are sent while it runs, not after it ends
6
+
7
+ import { expect, test } from "bun:test";
8
+
9
+ import { recordId, recordTypeName, seq, streamId, timestamp } from "@niwa-labs/core";
10
+ import type { StoredRecord } from "@niwa-labs/core";
11
+ import type { NiwaApi } from "@niwa-labs/client";
12
+
13
+ import { followFeed, readFeed } from "../src/feed.ts";
14
+
15
+ function request(at: number, id: string): StoredRecord {
16
+ return {
17
+ id: recordId(`rec_${id}`),
18
+ seq: seq(at),
19
+ stream: streamId("main"),
20
+ type: recordTypeName("request.created"),
21
+ schema: 1,
22
+ data: { id, to: { kind: "owner" }, input: { kind: "choice", title: `Question ${id}`, options: [] } },
23
+ actor: { kind: "host" },
24
+ cause: null,
25
+ root: recordId(`rec_${id}`),
26
+ at: timestamp(at),
27
+ };
28
+ }
29
+
30
+ /** A journal that holds `history`, then says `live` one record at a time, `gap` milliseconds apart. */
31
+ function journal(history: StoredRecord[], live: StoredRecord[], gap: number): { api: NiwaApi; since: Array<number | undefined> } {
32
+ const since: Array<number | undefined> = [];
33
+ const api = {
34
+ records: {
35
+ read: async (query?: { from?: number }) => history.filter((record) => record.seq > (query?.from ?? 0)),
36
+ since: (query?: { from?: number }) => {
37
+ since.push(query?.from);
38
+ return (async function* () {
39
+ for (const record of live) {
40
+ await Bun.sleep(gap);
41
+ yield record;
42
+ }
43
+ await new Promise(() => undefined);
44
+ })();
45
+ },
46
+ },
47
+ } as unknown as NiwaApi;
48
+ return { api, since };
49
+ }
50
+
51
+ test("the feed as it stands does not wait for the live subscription to say anything", async () => {
52
+ const { api } = journal([request(1, "a")], [], 100);
53
+ const feed = await readFeed(api);
54
+ expect(feed.map((entry) => entry.id)).toEqual(["a"]);
55
+ });
56
+
57
+ test("a followed feed starts with the list as it stands and goes on from the last record it read", async () => {
58
+ const { api, since } = journal([request(1, "a"), request(2, "b")], [request(3, "c")], 10);
59
+ const lists: string[][] = [];
60
+ const followed = await followFeed(api, (entries) => lists.push(entries.map((entry) => entry.id)), () => undefined);
61
+ try {
62
+ expect(followed.entries.map((entry) => entry.id)).toEqual(["a", "b"]);
63
+ expect(since).toEqual([2]);
64
+ await Bun.sleep(150);
65
+ expect(lists).toEqual([["a", "b", "c"]]);
66
+ } finally {
67
+ followed.stop();
68
+ }
69
+ });
70
+
71
+ test("a steady stream of records gets its lists out while it runs", async () => {
72
+ const live = Array.from({ length: 60 }, (_, index) => request(index + 2, `r${String(index)}`));
73
+ const { api } = journal([request(1, "a")], live, 10);
74
+ const lists: number[] = [];
75
+ const followed = await followFeed(api, (entries) => lists.push(entries.length), () => undefined);
76
+ try {
77
+ await Bun.sleep(300);
78
+ expect(lists.length).toBeGreaterThanOrEqual(2);
79
+ expect(lists.at(-1)).toBeGreaterThan(lists[0] ?? 0);
80
+ } finally {
81
+ followed.stop();
82
+ }
83
+ });
@@ -0,0 +1,163 @@
1
+ // The feed: open requests and paused work are on the page, and answering from the page continues
2
+ // the waiting invocation.
3
+ //
4
+ // A real host process, a real web surface, and a real HTTP request:
5
+ //
6
+ // 1. the host is started, the web surface connects to it as the client "web"
7
+ // 2. a record is written that makes an invocation pause
8
+ // 3. the paused invocation is on the page: the feed names it and offers its choices
9
+ // 4. POST /resolve answers it — and the waiting invocation continues: the step runs again
10
+ // 5. the invocation is not on the feed any more
11
+ //
12
+ // The web surface is a client of the host: nothing is written into the journal by the surface
13
+ // itself, and the answer goes through the core's own action.
14
+
15
+ import { expect, test } from "bun:test";
16
+
17
+ import { spawnHost, tempHome, lastState, loginWeb, watch, webFetch, connectAsOwner } from "@niwa-labs/testing";
18
+ import type { WebServer } from "../src/index.ts";
19
+ import { serveWebPages } from "./fixtures/serve-web.ts";
20
+ import { callCount, Start } from "./fixtures/feed-host.ts";
21
+
22
+ const HOST_SCRIPT = new URL("./fixtures/feed-host.ts", import.meta.url).pathname;
23
+
24
+ /** The feed of the page, as the server answers it. */
25
+ interface FeedEntry {
26
+ kind: string;
27
+ id: string;
28
+ record: string;
29
+ text: string;
30
+ choices: string[];
31
+ }
32
+
33
+ /** Read the feed of the surface over HTTP. */
34
+ async function readFeed(url: string): Promise<FeedEntry[]> {
35
+ const response = await webFetch(`${url}/feed`);
36
+ expect(response.status).toBe(200);
37
+ return (await response.json()) as FeedEntry[];
38
+ }
39
+
40
+ test("the feed: a paused invocation is on the page, and answering it from the page continues it", async () => {
41
+ const home = await tempHome();
42
+ const host = spawnHost(HOST_SCRIPT, home.path);
43
+ let web: WebServer | undefined;
44
+ let observer: Awaited<ReturnType<typeof watch>> | undefined;
45
+
46
+ try {
47
+ await host.ready();
48
+ web = await serveWebPages({ home: home.path, port: 0, speaksFor: "owner" });
49
+ await loginWeb(web);
50
+ observer = await watch(home.path);
51
+
52
+ // The page itself is HTML, and it names the feed.
53
+ const page = await webFetch(web.url);
54
+ expect(page.status).toBe(200);
55
+ const html = await page.text();
56
+ expect(html).toContain("<!doctype html>");
57
+ expect(html).toContain("/events");
58
+
59
+ // A record that makes the invocation pause: the guard refuses the step.
60
+ const writer = await connectAsOwner(home.path);
61
+ await writer.emit(Start, { n: 7 });
62
+ await writer.close();
63
+
64
+ // The invocation is paused, and the feed says so: the page shows what waits for the owner.
65
+ await waitFor(async () => (await readFeed(web!.url)).length > 0, "the pause reaches the feed");
66
+ const feed = await readFeed(web.url);
67
+ const paused = feed.find((entry) => entry.kind === "paused");
68
+ expect(paused).toBeDefined();
69
+ expect(paused?.choices).toEqual(["retry", "skip", "cancel"]);
70
+ // The core names the pause by the step and what came of it.
71
+ expect(paused?.text).toContain("denied");
72
+ // The entry links to the record that says it waits.
73
+ expect(paused?.record).toStartWith("st_");
74
+
75
+ // The same list arrives over SSE, so the page follows the journal.
76
+ const stream = await webFetch(`${web.url}/events`);
77
+ expect(stream.headers.get("content-type")).toContain("text/event-stream");
78
+ const streamed = await firstEvent(stream);
79
+ expect(streamed.map((entry) => entry.id)).toEqual([paused?.id as string]);
80
+
81
+ // The answer is refused unless it is a JSON POST of the right shape.
82
+ const post = (body: string, headers: Record<string, string> = { "content-type": "application/json" }) =>
83
+ webFetch(`${web!.url}/resolve`, { method: "POST", headers, body });
84
+ expect((await webFetch(`${web.url}/resolve`)).status).toBe(405);
85
+ expect((await webFetch(`${web.url}/events`, { method: "POST" })).status).toBe(405);
86
+ expect((await post("{}", { "content-type": "text/plain" })).status).toBe(415);
87
+ expect((await post("not json")).status).toBe(400);
88
+ expect((await post("{}")).status).toBe(400);
89
+ expect((await post(JSON.stringify({ invocation: paused?.id, choice: "explode" }))).status).toBe(400);
90
+ expect((await post(JSON.stringify({ invocation: paused?.id, choice: "retry" }), {
91
+ "content-type": "application/json",
92
+ origin: "http://evil.example",
93
+ })).status).toBe(403);
94
+ expect((await webFetch(`${web.url}/answer`, { method: "POST", headers: { "content-type": "application/json" }, body: "{\"request\":\"r\"}" })).status).toBe(400);
95
+ // None of that answered anything: the invocation still waits and the step has not run.
96
+ expect((await readFeed(web!.url)).map((entry) => entry.id)).toEqual([paused?.id as string]);
97
+ expect(callCount(home.path)).toBe(0);
98
+
99
+ // Answering from the page continues the waiting invocation.
100
+ const answered = await webFetch(`${web.url}/resolve`, {
101
+ method: "POST",
102
+ headers: { "content-type": "application/json" },
103
+ body: JSON.stringify({ invocation: paused?.id, choice: "retry" }),
104
+ });
105
+ expect(answered.status).toBe(200);
106
+
107
+ // The step ran again: the work happened after the owner answered.
108
+ await waitFor(() => callCount(home.path) === 1, "the step runs again after the answer");
109
+ expect(callCount(home.path)).toBe(1);
110
+
111
+ // The invocation is not waiting any more, so it is not on the feed.
112
+ await waitFor(async () => (await readFeed(web!.url)).length === 0, "the feed is empty again");
113
+ expect(await readFeed(web.url)).toEqual([]);
114
+
115
+ // The answer went through the core's own action, which wrote its record.
116
+ const resolved = observer.seen.find((record) => record.type === "niwa.invocation.resolved");
117
+ expect(resolved).toBeDefined();
118
+
119
+ // Closing the surface ends the open stream and leaves nothing listening.
120
+ await web!.close();
121
+ expect(await drained(stream)).toBe(true);
122
+ await expect(webFetch(web.url)).rejects.toThrow();
123
+ } finally {
124
+ await web?.close();
125
+ await observer?.stop();
126
+ await host.kill().catch(() => {});
127
+ await home.cleanup();
128
+ }
129
+ }, 30_000);
130
+
131
+ /** The first list a stream sends. */
132
+ async function firstEvent(response: Response): Promise<FeedEntry[]> {
133
+ const reader = response.body!.getReader();
134
+ const decoder = new TextDecoder();
135
+ let buffer = "";
136
+ while (!buffer.includes("\n\n")) {
137
+ const chunk = await reader.read();
138
+ if (chunk.done) throw new Error("the stream ended before it sent the feed");
139
+ buffer += decoder.decode(chunk.value);
140
+ }
141
+ reader.releaseLock();
142
+ return JSON.parse(buffer.slice("data: ".length)) as FeedEntry[];
143
+ }
144
+
145
+ /** Whether the stream ends by itself within a moment. */
146
+ async function drained(response: Response): Promise<boolean> {
147
+ const reader = response.body!.getReader();
148
+ const end = new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 5_000));
149
+ const read = (async () => {
150
+ for (;;) if ((await reader.read()).done) return true;
151
+ })().catch(() => true);
152
+ return Promise.race([read, end]);
153
+ }
154
+
155
+ /** Wait until a condition holds; the message says what was waited for. */
156
+ async function waitFor(fn: () => boolean | Promise<boolean>, message: string): Promise<void> {
157
+ const until = Date.now() + 10_000;
158
+ for (;;) {
159
+ if (await fn()) return;
160
+ if (Date.now() > until) throw new Error(message);
161
+ await new Promise((resolve) => setTimeout(resolve, 50));
162
+ }
163
+ }
@@ -0,0 +1,86 @@
1
+ // The host program for the web feed test.
2
+ //
3
+ // The plugin declares one record type, Start, and one action, "feed.work". A guard refuses the
4
+ // action the first time it is called, so the invocation pauses and waits for the owner to decide.
5
+ //
6
+ // The refusal is deliberate and repeatable: the action writes what it was asked to do into a file
7
+ // in the home, so the test can see whether the step ran again after the owner answered, and how
8
+ // many times it ran.
9
+ //
10
+ // The home directory comes from argv[2].
11
+
12
+ import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
13
+ import { join } from "node:path";
14
+
15
+ import { action, deny, record } from "@niwa-labs/core";
16
+ import { createNiwa, plugin } from "@niwa-labs/testing";
17
+ import { z } from "zod";
18
+
19
+ /** The record the test writes: it wakes the handler. */
20
+ export const Start = record("feed.start", z.object({ n: z.number() }), { open: true });
21
+
22
+ /** The file the action writes every call into. */
23
+ export const CALL_LOG = "calls.log";
24
+
25
+ /** The file that says the guard has already refused once. */
26
+ export const REFUSED_MARKER = "refused.flag";
27
+
28
+ /** The home this program was started with. */
29
+ function home(): string {
30
+ return process.argv[2] as string;
31
+ }
32
+
33
+ /** How many calls the action has had. */
34
+ export function callCount(homePath: string): number {
35
+ const path = join(homePath, CALL_LOG);
36
+ if (!existsSync(path)) return 0;
37
+ return readFileSync(path, "utf8").split("\n").filter((line) => line.trim() !== "").length;
38
+ }
39
+
40
+ /** The action of this host: it writes every call into a file and returns its input. */
41
+ export const Work = action("feed.work", {
42
+ description: "Does the work of the host.",
43
+ input: z.object({ n: z.number() }),
44
+ output: z.object({ n: z.number() }),
45
+ recovery: "repeat",
46
+ effect: "write",
47
+ run: (input) => {
48
+ appendFileSync(join(home(), CALL_LOG), `${input.n}\n`);
49
+ return { n: input.n };
50
+ },
51
+ });
52
+
53
+ /** The plugin of this host. */
54
+ export function makePlugin() {
55
+ return plugin("feed", (api) => {
56
+ api.declare(Start);
57
+ api.action(Work);
58
+ // The first call is refused: the invocation pauses. The owner answers it from the page, and
59
+ // the invocation runs again with the choice in hand — and then the call is allowed.
60
+ api.guard(Work, () => {
61
+ const marker = join(home(), REFUSED_MARKER);
62
+ if (existsSync(marker)) return undefined;
63
+ writeFileSync(marker, "refused\n");
64
+ return deny("the work needs the owner to say yes");
65
+ });
66
+ api.on(Start, async (data, step) => {
67
+ await step(Work, { n: data.n });
68
+ });
69
+ });
70
+ }
71
+
72
+ if (import.meta.main) {
73
+ const home = process.argv[2];
74
+ if (!home) {
75
+ console.error("usage: bun feed-host.ts <home>");
76
+ process.exit(2);
77
+ }
78
+
79
+ const niwa = createNiwa({ home });
80
+ niwa.use(makePlugin());
81
+ await niwa.serve();
82
+
83
+ process.on("SIGTERM", () => {
84
+ void niwa.close().then(() => process.exit(0));
85
+ });
86
+ }
@@ -0,0 +1,58 @@
1
+ // Serves the web surface with small page renderers, for the tests that look at what the surface
2
+ // serves: a feed page that follows the event stream, and a trace page that links every record of
3
+ // a chain to its own page.
4
+
5
+ import { serveWeb } from "../../src/index.ts";
6
+ import type { Chain, ChainRecord, WebOptions, WebServer } from "../../src/index.ts";
7
+
8
+ function escapeHtml(value: string): string {
9
+ return value
10
+ .replaceAll("&", "&amp;")
11
+ .replaceAll("<", "&lt;")
12
+ .replaceAll(">", "&gt;")
13
+ .replaceAll('"', "&quot;")
14
+ .replaceAll("'", "&#39;");
15
+ }
16
+
17
+ function feedPage(): string {
18
+ return `<!doctype html>
19
+ <html lang="en">
20
+ <head><meta charset="utf-8"><title>niwa</title></head>
21
+ <body><script>new EventSource("/events");</script></body>
22
+ </html>
23
+ `;
24
+ }
25
+
26
+ function fields(value: unknown): string {
27
+ if (value === null || typeof value !== "object") return escapeHtml(String(value ?? "-"));
28
+ return `<dl>${Object.entries(value)
29
+ .map(([name, field]) => `<dt>${escapeHtml(name)}</dt><dd>${fields(field)}</dd>`)
30
+ .join("")}</dl>`;
31
+ }
32
+
33
+ function node(record: ChainRecord): string {
34
+ const link = (id: string): string => `<a href="/trace/${encodeURIComponent(id)}">${escapeHtml(id)}</a>`;
35
+ const cause = record.cause === null ? "none" : link(record.cause);
36
+ return `<div><a href="/trace/${encodeURIComponent(record.id)}">${escapeHtml(record.type)}</a>
37
+ <div>id ${escapeHtml(record.id)} by ${escapeHtml(record.actor)} cause ${cause} root ${link(record.root)}</div>
38
+ ${fields(record.data)}</div>`;
39
+ }
40
+
41
+ function tracePage(recordId: string, chain: Chain): string {
42
+ return `<!doctype html>
43
+ <html lang="en">
44
+ <head><meta charset="utf-8"><title>niwa ${escapeHtml(recordId)}</title></head>
45
+ <body>
46
+ <h1>trace of ${escapeHtml(recordId)}</h1>
47
+ <h2>What it depends on</h2>
48
+ ${chain.causes.map(node).join("")}
49
+ <h2>What grew from it</h2>
50
+ ${chain.trace.map(node).join("")}
51
+ </body>
52
+ </html>
53
+ `;
54
+ }
55
+
56
+ export function serveWebPages(options: Omit<WebOptions, "pages">): Promise<WebServer> {
57
+ return serveWeb({ ...options, pages: { feed: feedPage, trace: tracePage } });
58
+ }
@@ -0,0 +1,44 @@
1
+ // The host program for the web trace test.
2
+ //
3
+ // The plugin declares one record type, Start, and one result type, Done. The handler of Start
4
+ // writes a Done record with the step's own emit: the record belongs to the chain the handler was
5
+ // woken in, so the external input that started it is its cause.
6
+ //
7
+ // The home directory comes from argv[2].
8
+
9
+ import { record } from "@niwa-labs/core";
10
+ import { createNiwa, plugin } from "@niwa-labs/testing";
11
+ import { z } from "zod";
12
+
13
+ /** The external input: the test writes it, and the chain starts there. */
14
+ export const Start = record("why.start", z.object({ text: z.string() }), { open: true });
15
+
16
+ /** The result: what the handler produces, and what the trace page is opened for. */
17
+ export const Done = record("why.done", z.object({ text: z.string() }));
18
+
19
+ /** The plugin of this host. */
20
+ export function makePlugin() {
21
+ return plugin("why", (api) => {
22
+ api.declare(Start);
23
+ api.declare(Done);
24
+ api.on(Start, async (data, step) => {
25
+ await step.emit(Done, { text: `done: ${data.text}` });
26
+ });
27
+ });
28
+ }
29
+
30
+ if (import.meta.main) {
31
+ const home = process.argv[2];
32
+ if (!home) {
33
+ console.error("usage: bun why-host.ts <home>");
34
+ process.exit(2);
35
+ }
36
+
37
+ const niwa = createNiwa({ home });
38
+ niwa.use(makePlugin());
39
+ await niwa.serve();
40
+
41
+ process.on("SIGTERM", () => {
42
+ void niwa.close().then(() => process.exit(0));
43
+ });
44
+ }
@@ -0,0 +1,80 @@
1
+ // Each web surface is a host name of its own, so two of them open in one browser do not share a session.
2
+ //
3
+ // A browser keeps a cookie per host name and does not tell ports apart: two surfaces on 127.0.0.1 would replace each other's
4
+ // cookie, and any other service on that name would be sent it.
5
+ //
6
+ // 1. every instance has a name of its own under .localhost, and the cookie it gives names no domain
7
+ // 2. logging in to two instances, as a browser keeps cookies by host name, leaves both logged in
8
+ // 3. an instance answers to its own name only: not to another instance's, not to the bare loopback address
9
+
10
+ import { afterEach, expect, test } from "bun:test";
11
+
12
+ import { createNiwa, tempHome } from "@niwa-labs/testing";
13
+ import type { WebServer } from "../src/index.ts";
14
+
15
+ import { serveWebPages } from "./fixtures/serve-web.ts";
16
+
17
+ const cleanups: Array<() => Promise<void>> = [];
18
+ afterEach(async () => {
19
+ for (const cleanup of cleanups.splice(0).reverse()) await cleanup();
20
+ });
21
+
22
+ /** Two homes, each with its host and its web surface. */
23
+ async function two(): Promise<[WebServer, WebServer]> {
24
+ const surfaces: WebServer[] = [];
25
+ for (let index = 0; index < 2; index += 1) {
26
+ const home = await tempHome();
27
+ const host = createNiwa({ home: home.path });
28
+ await host.serve();
29
+ const web = await serveWebPages({ home: home.path, port: 0, speaksFor: "owner" });
30
+ cleanups.push(async () => {
31
+ await web.close();
32
+ await host.close();
33
+ await home.cleanup();
34
+ });
35
+ surfaces.push(web);
36
+ }
37
+ return [surfaces[0]!, surfaces[1]!];
38
+ }
39
+
40
+ /** The cookie a login link gives, as the `cookie` header of the next request. */
41
+ async function loginCookie(web: WebServer): Promise<{ header: string; setCookie: string }> {
42
+ const login = await fetch(web.loginUrl, { redirect: "manual" });
43
+ expect(login.status).toBe(302);
44
+ const setCookie = login.headers.get("set-cookie") ?? "";
45
+ return { header: setCookie.split(";")[0] ?? "", setCookie };
46
+ }
47
+
48
+ test("every instance has a host name of its own, and the cookie it gives is for that name alone", async () => {
49
+ const [first, second] = await two();
50
+ const names = [first, second].map((web) => new URL(web.url).hostname);
51
+ expect(names[0]).toEndWith(".localhost");
52
+ expect(names[1]).toEndWith(".localhost");
53
+ expect(names[0]).not.toBe(names[1]);
54
+ expect(new URL(first.loginUrl).hostname).toBe(names[0]!);
55
+
56
+ const { setCookie } = await loginCookie(first);
57
+ expect(setCookie).not.toMatch(/domain=/i);
58
+ expect(setCookie).toContain("Path=/");
59
+ });
60
+
61
+ test("two instances opened in one browser keep both sessions", async () => {
62
+ const [first, second] = await two();
63
+ // A browser keeps the cookies of a host name apart from those of every other name, whatever the port.
64
+ const jar = new Map<string, string>();
65
+ for (const web of [first, second]) jar.set(new URL(web.url).hostname, (await loginCookie(web)).header);
66
+ for (const web of [first, second]) {
67
+ const answer = await fetch(`${web.url}/feed`, { headers: { cookie: jar.get(new URL(web.url).hostname) ?? "" } });
68
+ expect(answer.status).toBe(200);
69
+ }
70
+ });
71
+
72
+ test("an instance answers to its own host name only", async () => {
73
+ const [first, second] = await two();
74
+ const { header } = await loginCookie(first);
75
+ expect((await fetch(`${first.url}/feed`, { headers: { cookie: header } })).status).toBe(200);
76
+ // The name of the other instance, and the bare address, reach the same port and are refused although the cookie is good.
77
+ const other = new URL(second.url).hostname;
78
+ expect((await fetch(`http://${other}:${String(first.port)}/feed`, { headers: { cookie: header } })).status).toBe(403);
79
+ expect((await fetch(`http://127.0.0.1:${String(first.port)}/feed`, { headers: { cookie: header } })).status).toBe(403);
80
+ });