@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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Niwa Labs contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,3 @@
1
- # Temporary Holding Version
1
+ # @niwa-labs/web
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The web surface: serves the cockpit and its client modules and forwards calls to the host.
package/package.json CHANGED
@@ -1,6 +1,17 @@
1
1
  {
2
2
  "name": "@niwa-labs/web",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./src/index.ts"
8
+ },
9
+ "dependencies": {
10
+ "@niwa-labs/client": "0.0.0",
11
+ "@niwa-labs/core": "0.0.0",
12
+ "zod": "^4.6.7"
13
+ },
14
+ "devDependencies": {
15
+ "@niwa-labs/testing": "0.0.0"
16
+ }
17
+ }
package/src/app.ts ADDED
@@ -0,0 +1,298 @@
1
+ /**
2
+ * The cockpit app as the web surface serves it: the built files of the app, and the client modules of the plugins.
3
+ *
4
+ * The surface knows no page of its own. It is given the folder of a built app and the import map the app's modules share,
5
+ * and serves the folder's files, the app's `index.html` for every address of the app, and each plugin module built for the
6
+ * browser from the source the host lists, under the hash the host lists.
7
+ */
8
+
9
+ import { createHash } from "node:crypto";
10
+ import { readFile, realpath, stat } from "node:fs/promises";
11
+ import { extname, isAbsolute, join, relative, sep } from "node:path";
12
+
13
+ import { CATALOG_ACTION, CatalogOutput } from "@niwa-labs/client";
14
+ import type { CatalogAnswer, NiwaApi } from "@niwa-labs/client";
15
+
16
+ /** The cockpit app: where it was built, and what a client module imports from it instead of carrying its own copy. */
17
+ export interface WebApp {
18
+ /** The folder of the built app: its `index.html` and the files that page names. */
19
+ readonly root: string;
20
+ /**
21
+ * The shared modules, by the name a client module imports them by, each with the address the app serves it at. They go
22
+ * into the import map of the page, and a client module is built with these names left as imports.
23
+ */
24
+ readonly imports: Readonly<Record<string, string>>;
25
+ }
26
+
27
+ const TYPES: Readonly<Record<string, string>> = {
28
+ ".html": "text/html; charset=utf-8",
29
+ ".js": "text/javascript; charset=utf-8",
30
+ ".mjs": "text/javascript; charset=utf-8",
31
+ ".css": "text/css; charset=utf-8",
32
+ ".json": "application/json; charset=utf-8",
33
+ ".map": "application/json; charset=utf-8",
34
+ ".svg": "image/svg+xml",
35
+ ".png": "image/png",
36
+ ".ico": "image/x-icon",
37
+ ".woff": "font/woff",
38
+ ".woff2": "font/woff2",
39
+ ".wasm": "application/wasm",
40
+ ".txt": "text/plain; charset=utf-8",
41
+ };
42
+
43
+ /** The content type of a file by its extension; plain bytes when the extension is not one the app has. */
44
+ export function typeOf(path: string): string {
45
+ return TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
46
+ }
47
+
48
+ /** Where the files of the app are asked for. */
49
+ export const ASSETS_PREFIX = "/assets/";
50
+
51
+ /** Where the client modules are asked for: `/modules/<id>/<hash>/index.js`. */
52
+ export const MODULES_PREFIX = "/modules/";
53
+
54
+ /**
55
+ * The file of the app a path names, or undefined when it names none: only regular files inside the folder, whichever links
56
+ * lie on the way. The folder and the file are both resolved to where they really are before the one is held to the other,
57
+ * and the path that comes back is the resolved one, so what is read is what was checked.
58
+ */
59
+ export async function assetFile(app: WebApp, path: string): Promise<string | undefined> {
60
+ let decoded: string;
61
+ try {
62
+ decoded = decodeURIComponent(path);
63
+ } catch {
64
+ return undefined;
65
+ }
66
+ if (decoded.includes("\0")) return undefined;
67
+ try {
68
+ const root = await realpath(app.root);
69
+ const file = await realpath(join(root, decoded));
70
+ const within = relative(root, file);
71
+ if (within === "" || isAbsolute(within) || within.split(sep)[0] === "..") return undefined;
72
+ return (await stat(file)).isFile() ? file : undefined;
73
+ } catch {
74
+ return undefined;
75
+ }
76
+ }
77
+
78
+ /** The import map of the page: the shared modules by name. */
79
+ export function importMapOf(app: WebApp): string {
80
+ return JSON.stringify({ imports: app.imports });
81
+ }
82
+
83
+ /** The hash a content security policy names an inline script by. */
84
+ export function scriptHash(content: string): string {
85
+ return `'sha256-${createHash("sha256").update(content).digest("base64")}'`;
86
+ }
87
+
88
+ /**
89
+ * The page of the app with the import map in it, and the hash of the map's script: the policy lets the page's own scripts
90
+ * and this one run, and no other inline script.
91
+ */
92
+ export async function pageOf(app: WebApp): Promise<{ html: string; hash: string }> {
93
+ const template = await readFile(join(app.root, "index.html"), "utf8");
94
+ const map = importMapOf(app);
95
+ const tag = `<script type="importmap">${map}</script>`;
96
+ // The map comes first: a module script that is already fetched when the map is read would not see it.
97
+ const html = /<head[^>]*>/i.test(template) ? template.replace(/<head[^>]*>/i, (head) => `${head}${tag}`) : `${tag}${template}`;
98
+ return { html, hash: scriptHash(map) };
99
+ }
100
+
101
+ /** A module of the catalogue as the browser is told of it. */
102
+ export interface ServedModule {
103
+ readonly id: string;
104
+ readonly package: string;
105
+ readonly version: string;
106
+ readonly entry: string;
107
+ /** The hash of the bytes the browser gets at `entry`; the hash the host lists when the module cannot be built. */
108
+ readonly hash: string;
109
+ readonly styles?: readonly string[];
110
+ }
111
+
112
+ /** The address of a module's code. The hash is a path segment, so the module's relative imports carry it too. */
113
+ export function moduleAddress(id: string, hash: string): string {
114
+ return `${MODULES_PREFIX}${id}/${hash}/index.js`;
115
+ }
116
+
117
+ /** The address of a stylesheet of a module; its own hash makes a changed sheet a new address. */
118
+ export function styleAddress(id: string, moduleHash: string, index: number, sheetHash: string): string {
119
+ return `${MODULES_PREFIX}${id}/${moduleHash}/style-${String(index)}-${sheetHash.slice(0, 12)}.css`;
120
+ }
121
+
122
+ /**
123
+ * What the host lists, as the browser is told of it when there is no app to build modules for: the addresses are the host's
124
+ * hashes of the sources, and nothing is served there.
125
+ */
126
+ export async function catalogueOf(api: NiwaApi): Promise<{ modules: ServedModule[] }> {
127
+ const listed = CatalogOutput.parse(await api.call(CATALOG_ACTION, {}));
128
+ return {
129
+ modules: listed.modules.map((module) => ({
130
+ id: module.id,
131
+ package: module.plugin,
132
+ version: module.version,
133
+ entry: moduleAddress(module.id, module.hash),
134
+ hash: module.hash,
135
+ ...(module.styles.length === 0
136
+ ? {}
137
+ : { styles: module.styles.map((sheet, index) => styleAddress(module.id, module.hash, index, sheet.hash)) }),
138
+ })),
139
+ };
140
+ }
141
+
142
+ /** What the surface holds of a module the host lists: the bytes it serves, or why there are none. */
143
+ interface HeldModule {
144
+ readonly served: ServedModule;
145
+ /** The code and the sheets as they are served, each under the hash of those bytes. */
146
+ readonly built?: { readonly code: string; readonly hash: string; readonly sheets: readonly Sheet[] };
147
+ /** Why the module could not be built; its address is then the host's hash of the source. */
148
+ readonly problem?: string;
149
+ }
150
+
151
+ interface Sheet {
152
+ readonly text: string;
153
+ readonly hash: string;
154
+ }
155
+
156
+ /** A file of a module as the browser asks for it: the code, or one of the sheets by position and hash prefix. */
157
+ export type ModuleFile = { readonly sheet?: undefined } | { readonly sheet: { readonly index: number; readonly hash: string } };
158
+
159
+ /** What a request for a module's file is answered with. */
160
+ export type ModuleAnswer = { readonly code: string } | { readonly css: string } | { readonly problem: string };
161
+
162
+ /**
163
+ * The client modules built for the browser. The address of a module and of each of its sheets is the hash of the bytes served
164
+ * there, never the hash of the source the host lists: the same source builds to other bytes when the modules the page shares
165
+ * change, and a browser that kept the old bytes under a name that did not change would run stale code. The bytes that were
166
+ * hashed are the bytes that are served; nothing is read again once the address is made.
167
+ */
168
+ export class ModuleBuilds {
169
+ /** Builds by the id and source hash the host lists, so one source is built once. */
170
+ readonly #builds = new Map<string, Promise<Built>>();
171
+ /** Sheets by the file and hash the host lists. */
172
+ readonly #sheets = new Map<string, Promise<Sheet>>();
173
+
174
+ /** The modules the host lists now, each as the browser is told of it. */
175
+ async catalogue(api: NiwaApi, app: WebApp): Promise<ServedModule[]> {
176
+ return (await this.#hold(api, app)).map((held) => held.served);
177
+ }
178
+
179
+ /**
180
+ * The file a module is served at under this id and hash, when the host lists such a module now and the hash is the one of
181
+ * its bytes (of its source, when it cannot be built). Undefined when nothing is served there, so nothing else is read.
182
+ */
183
+ async file(api: NiwaApi, app: WebApp, id: string, hash: string, file: ModuleFile): Promise<ModuleAnswer | undefined> {
184
+ const held = (await this.#hold(api, app)).find((module) => module.served.id === id && module.served.hash === hash);
185
+ if (held === undefined) return undefined;
186
+ if (held.built === undefined) return { problem: held.problem ?? "the module could not be built" };
187
+ if (file.sheet === undefined) return { code: held.built.code };
188
+ const sheet = held.built.sheets[file.sheet.index];
189
+ return sheet === undefined || !sheet.hash.startsWith(file.sheet.hash) ? undefined : { css: sheet.text };
190
+ }
191
+
192
+ async #hold(api: NiwaApi, app: WebApp): Promise<HeldModule[]> {
193
+ const listed = CatalogOutput.parse(await api.call(CATALOG_ACTION, {})).modules;
194
+ const held = await Promise.all(listed.map((module) => this.#holdOne(module, app)));
195
+ // What the host no longer lists is forgotten, so a changed module leaves nothing behind.
196
+ const builds = new Set(listed.map((module) => `${module.id}/${module.hash}`));
197
+ const sheets = new Set(listed.flatMap((module) => module.styles.map((sheet) => `${sheet.file}/${sheet.hash}`)));
198
+ for (const key of [...this.#builds.keys()]) if (!builds.has(key)) this.#builds.delete(key);
199
+ for (const key of [...this.#sheets.keys()]) if (!sheets.has(key)) this.#sheets.delete(key);
200
+ return held;
201
+ }
202
+
203
+ async #holdOne(module: CatalogAnswer["modules"][number], app: WebApp): Promise<HeldModule> {
204
+ const key = `${module.id}/${module.hash}`;
205
+ let build = this.#builds.get(key);
206
+ if (build === undefined) {
207
+ build = buildModule(module.entry, Object.keys(app.imports));
208
+ this.#builds.set(key, build);
209
+ // A failed build is tried again at the next request: a transient failure is not remembered.
210
+ void build.then((result) => {
211
+ if ("problem" in result) this.#builds.delete(key);
212
+ });
213
+ }
214
+ const built = await build;
215
+ const unbuilt = (problem: string): HeldModule => ({
216
+ served: { id: module.id, package: module.plugin, version: module.version, entry: moduleAddress(module.id, module.hash), hash: module.hash },
217
+ problem,
218
+ });
219
+ if ("problem" in built) return unbuilt(built.problem);
220
+ let sheets: Sheet[];
221
+ try {
222
+ sheets = await Promise.all(module.styles.map((sheet) => this.#sheet(sheet)));
223
+ } catch (error) {
224
+ return unbuilt(`a stylesheet could not be read: ${error instanceof Error ? error.message : String(error)}`);
225
+ }
226
+ return {
227
+ served: {
228
+ id: module.id,
229
+ package: module.plugin,
230
+ version: module.version,
231
+ entry: moduleAddress(module.id, built.hash),
232
+ hash: built.hash,
233
+ ...(sheets.length === 0 ? {} : { styles: sheets.map((sheet, index) => styleAddress(module.id, built.hash, index, sheet.hash)) }),
234
+ },
235
+ built: { code: built.code, hash: built.hash, sheets },
236
+ };
237
+ }
238
+
239
+ #sheet(listed: { readonly file: string; readonly hash: string }): Promise<Sheet> {
240
+ const key = `${listed.file}/${listed.hash}`;
241
+ let sheet = this.#sheets.get(key);
242
+ if (sheet === undefined) {
243
+ sheet = readFile(listed.file, "utf8").then((text) => ({ text, hash: createHash("sha256").update(text).digest("hex") }));
244
+ this.#sheets.set(key, sheet);
245
+ sheet.catch(() => this.#sheets.delete(key));
246
+ }
247
+ return sheet;
248
+ }
249
+ }
250
+
251
+ type Built = { code: string; hash: string } | { problem: string };
252
+
253
+ /** The package a specifier names: `react/jsx-runtime` is of `react`, `@niwa-labs/ui-kit/x` of `@niwa-labs/ui-kit`. */
254
+ function packageOf(specifier: string): string {
255
+ const parts = specifier.split("/");
256
+ return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? specifier);
257
+ }
258
+
259
+ /**
260
+ * Leave exactly the shared specifiers as imports. The page's import map names these and no others, so a specifier of a shared
261
+ * package that the map lacks would build and then fail in the browser; it is refused at the build instead. Bundling it would
262
+ * give the module a second copy of a package the page already has one of.
263
+ */
264
+ function sharedImports(shared: readonly string[]): Bun.BunPlugin {
265
+ const names = new Set(shared);
266
+ const packages = new Set(shared.map(packageOf));
267
+ return {
268
+ name: "niwa-shared-imports",
269
+ setup(build) {
270
+ build.onResolve({ filter: /^[^./]/ }, (args) => {
271
+ if (names.has(args.path)) return { path: args.path, external: true };
272
+ if (packages.has(packageOf(args.path))) {
273
+ throw new Error(`${args.path} is not shared by the cockpit: a module imports ${shared.filter((name) => packageOf(name) === packageOf(args.path)).join(", ")} of that package`);
274
+ }
275
+ return undefined;
276
+ });
277
+ },
278
+ };
279
+ }
280
+
281
+ /** Build one module for the browser. The shared modules stay imports, and the page's import map resolves them. */
282
+ async function buildModule(entry: string, shared: readonly string[]): Promise<Built> {
283
+ const result = await Bun.build({
284
+ throw: false,
285
+ entrypoints: [entry],
286
+ target: "browser",
287
+ format: "esm",
288
+ plugins: [sharedImports(shared)],
289
+ minify: true,
290
+ define: { "process.env.NODE_ENV": JSON.stringify("production") },
291
+ jsx: { runtime: "automatic", importSource: "react", development: false },
292
+ });
293
+ if (!result.success) return { problem: result.logs.map((log) => log.message).join("\n") };
294
+ const output = result.outputs.find((file) => file.kind === "entry-point") ?? result.outputs[0];
295
+ if (output === undefined) return { problem: "the build made no file" };
296
+ const code = await output.text();
297
+ return { code, hash: createHash("sha256").update(code).digest("hex") };
298
+ }
package/src/denial.ts ADDED
@@ -0,0 +1,13 @@
1
+ /**
2
+ * What a refusal by the host is, as the web surface tells it.
3
+ *
4
+ * The host refuses a call with the code `Denied`; the details of the grant that refused ride along when there is a grant to
5
+ * name, and are absent when there is none (the switch of access is off, for one). The code decides, not the details.
6
+ */
7
+
8
+ import { HostError } from "@niwa-labs/client";
9
+
10
+ /** Did the host refuse for a lack of permission? */
11
+ export function isDenied(error: unknown): error is HostError {
12
+ return error instanceof HostError && (error.code === "Denied" || error.denied !== undefined);
13
+ }
package/src/feed.ts ADDED
@@ -0,0 +1,215 @@
1
+ /**
2
+ * feed.ts — everything that waits for the owner, as one list.
3
+ *
4
+ * The list is computed from the journal, read through the observation API: a paused invocation
5
+ * and an open request are the same shape here. Every entry names the record it came from, so the
6
+ * page can link to it and the trace can start from it.
7
+ */
8
+
9
+ import { QuestionSchema, CORE_TYPES, recordTypeName, seq } from "@niwa-labs/core";
10
+ import type { Question, RecordId, StoredRecord } from "@niwa-labs/core";
11
+ import type { NiwaApi } from "@niwa-labs/client";
12
+
13
+ const REQUEST_CREATED = recordTypeName("request.created");
14
+ const SESSION_STARTED = recordTypeName("session.started");
15
+ const REQUEST_CLOSING = [
16
+ recordTypeName("request.answered"),
17
+ recordTypeName("request.cancelled"),
18
+ recordTypeName("request.expired"),
19
+ ];
20
+
21
+ /** Records that arrive in a burst are sent as one list once they settle. */
22
+ const SETTLE_MS = 50;
23
+
24
+ /** The choices an owner may take about a paused invocation. */
25
+ export type FeedChoice = "retry" | "skip" | "cancel";
26
+
27
+ /** One thing that waits for the owner. */
28
+ export interface FeedEntry {
29
+ readonly kind: "paused" | "request";
30
+ /** The id of the invocation or of the request. */
31
+ readonly id: string;
32
+ /** The record that says it waits. */
33
+ readonly record: RecordId;
34
+ /** The reason of the pause, or the question of the request. */
35
+ readonly text: string;
36
+ /** The choices the owner may take; empty for a request. */
37
+ readonly choices: readonly FeedChoice[];
38
+ /** The question of a request, whole: the page draws its options and its kind from it. */
39
+ readonly question?: Question;
40
+ /** The step the pause is about, when it paused on one. */
41
+ readonly key?: string;
42
+ /** The id niwa gave the session that asks, for a request a session niwa started put to the owner. */
43
+ readonly session?: string;
44
+ readonly at: number;
45
+ }
46
+
47
+ /** A field of record data, when it is a string. */
48
+ function field(data: unknown, name: string): string | undefined {
49
+ const value = (data as Record<string, unknown> | null)?.[name];
50
+ return typeof value === "string" ? value : undefined;
51
+ }
52
+
53
+ /**
54
+ * The feed of a journal prefix, in the order things appeared.
55
+ *
56
+ * An invocation waits while its latest state is "paused" and no answer was written after that
57
+ * state; one that paused again after an answer waits again. A request waits until a record
58
+ * closes it, and is on the feed only when it is addressed to the owner.
59
+ */
60
+ export function feedOf(records: readonly StoredRecord[]): FeedEntry[] {
61
+ const latestState = new Map<string, StoredRecord>();
62
+ const lastAnswer = new Map<string, number>();
63
+ const openedRequests = new Map<string, StoredRecord>();
64
+ const closedRequests = new Set<string>();
65
+ // The ids niwa gave the sessions it started, by their pair `<harness> <native>`.
66
+ const sessions = new Map<string, string>();
67
+
68
+ for (const record of records) {
69
+ const invocation = field(record.data, "invocation");
70
+ const request = field(record.data, "request") ?? field(record.data, "id");
71
+ if (record.type === CORE_TYPES.invocationState && invocation !== undefined) {
72
+ latestState.set(invocation, record);
73
+ } else if (record.type === CORE_TYPES.invocationResolved && invocation !== undefined) {
74
+ lastAnswer.set(invocation, record.seq);
75
+ } else if (record.type === REQUEST_CREATED && request !== undefined) {
76
+ openedRequests.set(request, record);
77
+ } else if (REQUEST_CLOSING.includes(record.type) && request !== undefined) {
78
+ closedRequests.add(request);
79
+ } else if (record.type === SESSION_STARTED) {
80
+ const session = field(record.data, "session");
81
+ const id = field(record.data, "id");
82
+ if (session !== undefined && id !== undefined) sessions.set(session, id);
83
+ }
84
+ }
85
+
86
+ const entries: FeedEntry[] = [];
87
+ for (const [invocation, record] of latestState) {
88
+ if (field(record.data, "state") !== "paused") continue;
89
+ if ((lastAnswer.get(invocation) ?? -1) > record.seq) continue;
90
+ const key = field(record.data, "key");
91
+ entries.push({
92
+ kind: "paused",
93
+ id: invocation,
94
+ record: record.id,
95
+ text: field(record.data, "reason") ?? "the invocation is paused",
96
+ choices: choicesOf((record.data as { choices?: unknown }).choices),
97
+ ...(key === undefined ? {} : { key }),
98
+ at: record.at,
99
+ });
100
+ }
101
+ for (const [id, record] of openedRequests) {
102
+ if (closedRequests.has(id)) continue;
103
+ if ((record.data as { to?: { kind?: unknown } } | null)?.to?.kind !== "owner") continue;
104
+ const asked = QuestionSchema.safeParse((record.data as { input?: unknown } | null)?.input);
105
+ const from = (record.data as { from?: { kind?: unknown; harness?: unknown; id?: unknown } } | null)?.from;
106
+ const session = from?.kind === "session" ? sessions.get(`${String(from.harness)} ${String(from.id)}`) : undefined;
107
+ entries.push({
108
+ kind: "request",
109
+ id,
110
+ record: record.id,
111
+ text: asked.success ? asked.data.title : (field(record.data, "question") ?? "a question"),
112
+ choices: [],
113
+ ...(asked.success ? { question: asked.data } : {}),
114
+ ...(session === undefined ? {} : { session }),
115
+ at: record.at,
116
+ });
117
+ }
118
+ return entries.sort((a, b) => a.at - b.at || a.id.localeCompare(b.id));
119
+ }
120
+
121
+ /** The choices of a paused state, keeping only the ones the core offers. */
122
+ function choicesOf(value: unknown): FeedChoice[] {
123
+ if (!Array.isArray(value)) return [];
124
+ return value.filter(
125
+ (choice): choice is FeedChoice => choice === "retry" || choice === "skip" || choice === "cancel",
126
+ );
127
+ }
128
+
129
+ /** The record types that can change the feed: the journal is read for these and no others. */
130
+ const FEED_TYPES = [
131
+ CORE_TYPES.invocationState,
132
+ CORE_TYPES.invocationResolved,
133
+ REQUEST_CREATED,
134
+ SESSION_STARTED,
135
+ ...REQUEST_CLOSING,
136
+ ];
137
+
138
+ /** How many records one read of the snapshot takes, so no answer grows with the journal. */
139
+ const SNAPSHOT_PAGE = 500;
140
+
141
+ /** The records that can change the feed as they are committed now, and the position of the last of them. */
142
+ async function snapshotOf(api: NiwaApi): Promise<{ records: StoredRecord[]; position: ReturnType<typeof seq> }> {
143
+ const records: StoredRecord[] = [];
144
+ let position = seq(0);
145
+ for (;;) {
146
+ const page = await api.records.read({ types: FEED_TYPES, from: position, limit: SNAPSHOT_PAGE });
147
+ records.push(...page);
148
+ position = page.at(-1)?.seq ?? position;
149
+ if (page.length < SNAPSHOT_PAGE) return { records, position };
150
+ }
151
+ }
152
+
153
+ /** A followed feed: the list as it stood when the follow began. `stop` closes the subscription. */
154
+ export interface FollowedFeed {
155
+ readonly entries: FeedEntry[];
156
+ stop(): void;
157
+ }
158
+
159
+ /**
160
+ * Follow the feed: the list as it is now, read whole, and then the whole list again after every change.
161
+ *
162
+ * The subscription goes on from the position of what was read, so no record is missed and none counted twice. A burst of
163
+ * records is sent as one list, at most once in `SETTLE_MS`, so a steady stream cannot hold the list back. `onEnd` is called
164
+ * when the journal can no longer be read. A journal that cannot be read to begin with is the rejection of this call.
165
+ */
166
+ export async function followFeed(
167
+ api: NiwaApi,
168
+ onFeed: (entries: FeedEntry[]) => void,
169
+ onEnd: (error?: unknown) => void,
170
+ ): Promise<FollowedFeed> {
171
+ const { records: relevant, position } = await snapshotOf(api);
172
+ const iterator = api.records.since({ types: FEED_TYPES, from: position })[Symbol.asyncIterator]();
173
+ let timer: ReturnType<typeof setTimeout> | undefined;
174
+ let stopped = false;
175
+
176
+ const schedule = (): void => {
177
+ if (timer !== undefined) return;
178
+ timer = setTimeout(() => {
179
+ timer = undefined;
180
+ if (!stopped) onFeed(feedOf(relevant));
181
+ }, SETTLE_MS);
182
+ };
183
+ const stop = (): void => {
184
+ if (stopped) return;
185
+ stopped = true;
186
+ clearTimeout(timer);
187
+ void iterator.return?.().catch(() => undefined);
188
+ };
189
+
190
+ void (async () => {
191
+ for (;;) {
192
+ const next = await iterator.next();
193
+ if (next.done === true) return;
194
+ relevant.push(next.value);
195
+ schedule();
196
+ }
197
+ })().then(
198
+ () => {
199
+ const wasStopped = stopped;
200
+ stop();
201
+ if (!wasStopped) onEnd();
202
+ },
203
+ (error: unknown) => {
204
+ const wasStopped = stopped;
205
+ stop();
206
+ if (!wasStopped) onEnd(error);
207
+ },
208
+ );
209
+ return { entries: feedOf(relevant), stop };
210
+ }
211
+
212
+ /** The feed as it is now. */
213
+ export async function readFeed(api: NiwaApi): Promise<FeedEntry[]> {
214
+ return feedOf((await snapshotOf(api)).records);
215
+ }