fascicle 0.16.4 → 0.17.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 (37) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/README.md +3 -2
  3. package/dist/AGENTS.md +69 -18
  4. package/dist/acp.d.ts +1 -1
  5. package/dist/acp.js +6 -1
  6. package/dist/acp.js.map +1 -1
  7. package/dist/agents.d.ts +1 -1
  8. package/dist/{engine-D1QMcyIG.js → engine-BMdRqWL2.js} +1018 -231
  9. package/dist/engine-BMdRqWL2.js.map +1 -0
  10. package/dist/index.d.ts +108 -16
  11. package/dist/index.js +225 -16
  12. package/dist/index.js.map +1 -1
  13. package/dist/{invoke-LbzZLZFw.js → invoke-BbJLQcLl.js} +62 -106
  14. package/dist/invoke-BbJLQcLl.js.map +1 -0
  15. package/dist/{leading_system-WhW76tRn.js → leading_system-DmNxhvzL.js} +45 -16
  16. package/dist/leading_system-DmNxhvzL.js.map +1 -0
  17. package/dist/mcp.d.ts +2 -1
  18. package/dist/mcp.js +6 -3
  19. package/dist/mcp.js.map +1 -1
  20. package/dist/otel.js +48 -3
  21. package/dist/otel.js.map +1 -1
  22. package/dist/testing.d.ts +77 -2
  23. package/dist/testing.js +202 -19
  24. package/dist/testing.js.map +1 -1
  25. package/dist/{types-Sw0oHW-_.d.ts → types-BNgAUQP1.d.ts} +170 -17
  26. package/dist/viewer-app/assets/index-9eVv6Mar.css +1 -0
  27. package/dist/viewer-app/assets/index-BkS2ZQu0.js +4 -0
  28. package/dist/viewer-app/index.html +2 -2
  29. package/dist/viewer.d.ts +37 -10
  30. package/dist/viewer.js +101 -46
  31. package/dist/viewer.js.map +1 -1
  32. package/package.json +1 -1
  33. package/dist/engine-D1QMcyIG.js.map +0 -1
  34. package/dist/invoke-LbzZLZFw.js.map +0 -1
  35. package/dist/leading_system-WhW76tRn.js.map +0 -1
  36. package/dist/viewer-app/assets/index-Cev83tcH.css +0 -1
  37. package/dist/viewer-app/assets/index-D8UmFVfR.js +0 -2
package/dist/viewer.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { o as ParsedTrajectoryEvent } from "./trajectory-BKGNxi7u.js";
2
- import { ServerResponse } from "node:http";
2
+ import { IncomingMessage, ServerResponse } from "node:http";
3
3
  //#region src/viewer/start_viewer.d.ts
4
4
  /**
5
5
  * `start_viewer` programmatic embed implementation.
@@ -64,10 +64,8 @@ type BroadcasterConfig = {
64
64
  export declare function create_broadcaster(config: BroadcasterConfig): Broadcaster;
65
65
  //#endregion
66
66
  //#region src/viewer/server.d.ts
67
- type ServerConfig = {
67
+ type ViewerHandlerConfig = {
68
68
  readonly broadcaster: Broadcaster;
69
- readonly host: string;
70
- readonly port: number;
71
69
  /**
72
70
  * Where the compiled canvas lives, defaulting to the bundled
73
71
  * `dist/viewer-app`. The tests point it at a fixture directory so the suite
@@ -86,22 +84,51 @@ type ServerConfig = {
86
84
  * viewer that only tails a file from taking posts.
87
85
  */
88
86
  readonly ingest?: boolean | undefined;
87
+ /**
88
+ * The path the handler is mounted under, such as `/viewer/abc`, which it
89
+ * takes off each request before routing it; default the root. A request
90
+ * for the bare path is redirected to it with a trailing slash, since the
91
+ * canvas resolves its assets and its API requests against the page.
92
+ */
93
+ readonly base_path?: string;
89
94
  readonly on_parse_error?: (err: unknown, line: string) => void;
90
95
  };
96
+ /**
97
+ * Answers one request and returns true, or returns false without touching
98
+ * the response when the request isn't one the viewer serves: outside its
99
+ * `base_path`, a route the API doesn't claim, or a file the canvas doesn't
100
+ * ship.
101
+ */
102
+ type ViewerHandler = (req: IncomingMessage, res: ServerResponse) => boolean;
103
+ type ServerConfig = Omit<ViewerHandlerConfig, 'base_path'> & {
104
+ readonly host: string;
105
+ readonly port: number;
106
+ };
91
107
  type ViewerServer = {
92
108
  readonly url: string;
93
109
  /** The port the socket bound, which differs from the requested one for `port: 0`. */
94
110
  readonly port: number;
95
111
  readonly close: () => Promise<void>;
96
112
  };
113
+ /**
114
+ * Builds the viewer's request handler: the five API routes (health, snapshot,
115
+ * trajectory, SSE, ingest) and the compiled app's static files, for a host to
116
+ * mount on a `node:http` server of its own, or on any framework that hands
117
+ * over the raw request and response.
118
+ *
119
+ * The API routes are matched first and exactly, so no file the canvas ships
120
+ * can ever shadow one. The handler checks no `Host`, so a host that mounts it
121
+ * decides who may reach it, behind its own auth. `start_server` puts the
122
+ * loopback check in front of it.
123
+ */
124
+ export declare function create_viewer_handler(config: ViewerHandlerConfig): ViewerHandler;
97
125
  /**
98
126
  * Starts the HTTP server and resolves once it is listening.
99
127
  *
100
- * Wires the five API routes (health, snapshot, trajectory, SSE, ingest) plus
101
- * the compiled app's static files to a single request handler, and resolves
102
- * with the bound URL and port and a `close` that shuts the socket down. The
103
- * `Host` check runs before anything else, then the API routes are matched
104
- * first and exactly, so no file the canvas ships can ever shadow one.
128
+ * Mounts `create_viewer_handler` at the root behind the `Host` check, answers
129
+ * a JSON 404 naming the route for anything the handler doesn't serve, and
130
+ * resolves with the bound URL and port and a `close` that shuts the socket
131
+ * down.
105
132
  */
106
133
  export declare function start_server(config: ServerConfig): Promise<ViewerServer>;
107
134
  //#endregion
@@ -140,5 +167,5 @@ export declare function start_tail(config: TailConfig): Tail;
140
167
  */
141
168
  export declare function run_viewer_cli(argv: readonly string[]): Promise<void>;
142
169
  //#endregion
143
- export type { BroadcastEvent, Broadcaster, BroadcasterConfig, ServerConfig, StartViewerOptions, Subscriber, Tail, TailConfig, ViewerHandle, ViewerServer };
170
+ export type { BroadcastEvent, Broadcaster, BroadcasterConfig, ServerConfig, StartViewerOptions, Subscriber, Tail, TailConfig, ViewerHandle, ViewerHandler, ViewerHandlerConfig, ViewerServer };
144
171
  //# sourceMappingURL=viewer.d.ts.map
package/dist/viewer.js CHANGED
@@ -80,6 +80,10 @@ function create_broadcaster(config) {
80
80
  * loopback too, so a web page can't reach it by rebinding a domain of its own
81
81
  * to 127.0.0.1. Ingest is mounted unless the config turns it off, reads only
82
82
  * `application/x-ndjson`, and refuses a body past 8 MB.
83
+ *
84
+ * The routes live in `create_viewer_handler`, which a host can mount under a
85
+ * path of its own on a server of its own. `start_server` is that handler on a
86
+ * socket, behind the `Host` check, with a 404 for whatever it doesn't serve.
83
87
  */
84
88
  const SSE_HEARTBEAT_MS = 15e3;
85
89
  const HERE = dirname(fileURLToPath(import.meta.url));
@@ -123,47 +127,109 @@ const NDJSON = "application/x-ndjson";
123
127
  */
124
128
  const INGEST_LIMIT_BYTES = 8e6;
125
129
  /**
126
- * Starts the HTTP server and resolves once it is listening.
130
+ * The base a request target is parsed against to read its path. A path never
131
+ * depends on the authority it's parsed against, so a fixed one serves every
132
+ * request, whatever `Host` it names or leaves out.
133
+ */
134
+ const ROUTE_BASE = "http://localhost";
135
+ /**
136
+ * Builds the viewer's request handler: the five API routes (health, snapshot,
137
+ * trajectory, SSE, ingest) and the compiled app's static files, for a host to
138
+ * mount on a `node:http` server of its own, or on any framework that hands
139
+ * over the raw request and response.
127
140
  *
128
- * Wires the five API routes (health, snapshot, trajectory, SSE, ingest) plus
129
- * the compiled app's static files to a single request handler, and resolves
130
- * with the bound URL and port and a `close` that shuts the socket down. The
131
- * `Host` check runs before anything else, then the API routes are matched
132
- * first and exactly, so no file the canvas ships can ever shadow one.
141
+ * The API routes are matched first and exactly, so no file the canvas ships
142
+ * can ever shadow one. The handler checks no `Host`, so a host that mounts it
143
+ * decides who may reach it, behind its own auth. `start_server` puts the
144
+ * loopback check in front of it.
133
145
  */
134
- function start_server(config) {
135
- const { broadcaster, host, port, app_dir, trajectory_path, ingest = true, on_parse_error } = config;
136
- const handler = (req, res) => {
137
- if (!host_allowed(host, req.headers.host)) {
138
- send_forbidden_host(res, host);
139
- return;
146
+ function create_viewer_handler(config) {
147
+ const { broadcaster, app_dir, trajectory_path, ingest = true, on_parse_error } = config;
148
+ const base_path = normalize_base_path(config.base_path);
149
+ return (req, res) => {
150
+ const method = req.method ?? "GET";
151
+ const target = new URL(req.url ?? "/", ROUTE_BASE);
152
+ if (target.pathname === base_path) {
153
+ if (method !== "GET") return false;
154
+ redirect_to_slash(res, base_path, target.search);
155
+ return true;
140
156
  }
141
- const route = resolve_route(req, host, port);
157
+ const path = path_under(target.pathname, base_path);
158
+ if (path === void 0) return false;
159
+ const route = `${method} ${path}`;
142
160
  if (route === "GET /api/health") {
143
161
  send_json(res, 200, { ok: true });
144
- return;
162
+ return true;
145
163
  }
146
164
  if (route === "GET /api/snapshot") {
147
165
  send_json(res, 200, { events: broadcaster.snapshot() });
148
- return;
166
+ return true;
149
167
  }
150
168
  if (route === "GET /api/trajectory") {
151
169
  serve_trajectory(res, broadcaster, trajectory_path);
152
- return;
170
+ return true;
153
171
  }
154
172
  if (route === "GET /api/events") {
155
173
  handle_sse(req, res, broadcaster);
156
- return;
174
+ return true;
157
175
  }
158
176
  if (ingest && route === "POST /api/ingest") {
159
177
  handle_ingest(req, res, broadcaster, on_parse_error);
160
- return;
178
+ return true;
161
179
  }
162
- if (route.startsWith("GET /")) {
163
- serve_app_asset(res, route, app_dir);
180
+ return route.startsWith("GET /") && serve_app_asset(res, path, app_dir);
181
+ };
182
+ }
183
+ /**
184
+ * A base path with its trailing slash taken off, so `/viewer/abc/` and
185
+ * `/viewer/abc` mount the same way, and the root reads as `''`.
186
+ *
187
+ * Throws on a path that doesn't start with a slash, which no request path
188
+ * could ever fall under.
189
+ */
190
+ function normalize_base_path(base_path) {
191
+ if (base_path === void 0) return "";
192
+ if (!base_path.startsWith("/")) throw new TypeError(`viewer base_path must start with a slash; got ${JSON.stringify(base_path)}`);
193
+ return base_path.replace(/\/$/, "");
194
+ }
195
+ /**
196
+ * The part of a request path under `base_path`, starting with its slash, or
197
+ * undefined when the request falls outside it. `/viewer/abcd` is outside
198
+ * `/viewer/abc`, and every path is under the root's `''`.
199
+ */
200
+ function path_under(pathname, base_path) {
201
+ return pathname.startsWith(`${base_path}/`) ? pathname.slice(base_path.length) : void 0;
202
+ }
203
+ /**
204
+ * Redirects a request for the bare base path to the same path with a trailing
205
+ * slash, which is what the canvas resolves its relative URLs against.
206
+ *
207
+ * The `Location` names only the last segment, which a browser resolves
208
+ * against the path it asked for, so the redirect still lands when another
209
+ * proxy in front of the host has taken a prefix of its own off.
210
+ */
211
+ function redirect_to_slash(res, base_path, search) {
212
+ res.statusCode = 308;
213
+ res.setHeader("location", `${base_path.slice(base_path.lastIndexOf("/") + 1)}/${search}`);
214
+ res.end();
215
+ }
216
+ /**
217
+ * Starts the HTTP server and resolves once it is listening.
218
+ *
219
+ * Mounts `create_viewer_handler` at the root behind the `Host` check, answers
220
+ * a JSON 404 naming the route for anything the handler doesn't serve, and
221
+ * resolves with the bound URL and port and a `close` that shuts the socket
222
+ * down.
223
+ */
224
+ function start_server(config) {
225
+ const { host, port } = config;
226
+ const viewer = create_viewer_handler(config);
227
+ const handler = (req, res) => {
228
+ if (!host_allowed(host, req.headers.host)) {
229
+ send_forbidden_host(res, host);
164
230
  return;
165
231
  }
166
- send_not_found(res, route);
232
+ if (!viewer(req, res)) send_not_found(res, resolve_route(req));
167
233
  };
168
234
  const http_server = createServer(handler);
169
235
  return new Promise((res_ok, res_err) => {
@@ -242,23 +308,13 @@ function send_forbidden_host(res, bound) {
242
308
  });
243
309
  }
244
310
  /**
245
- * Builds a `"METHOD /path"` route key from a request.
311
+ * Builds a `"METHOD /path"` route key from a request, the key a 404 names.
246
312
  *
247
- * Resolves the path against the client's `Host` header when it parses, and
248
- * against the server's own `host`/`port` otherwise. A header can be present yet
249
- * malformed (`'in valid'`), which `??` cannot catch because it is neither null
250
- * nor undefined; fed to `new URL` it throws. Trying the header inside a
251
- * try/catch and falling back to the server's authority keeps route resolution
252
- * total for any header a client sends.
313
+ * The path is read against a fixed base rather than the client's `Host`, which
314
+ * can be absent or malformed and changes no path either way.
253
315
  */
254
- function resolve_route(req, host, port) {
255
- const method = req.method ?? "GET";
256
- const path = req.url ?? "/";
257
- const header = req.headers.host;
258
- if (header !== void 0) try {
259
- return `${method} ${new URL(path, `http://${header}`).pathname}`;
260
- } catch {}
261
- return `${method} ${new URL(path, `http://${format_authority(host, port)}`).pathname}`;
316
+ function resolve_route(req) {
317
+ return `${req.method ?? "GET"} ${new URL(req.url ?? "/", ROUTE_BASE).pathname}`;
262
318
  }
263
319
  /**
264
320
  * Closes the HTTP server and resolves once every connection is torn down.
@@ -368,31 +424,30 @@ function resolve_app_file(dir, url_path) {
368
424
  return file === dir ? resolve(dir, "index.html") : file;
369
425
  }
370
426
  /**
371
- * Streams one file of the compiled canvas as the response body.
427
+ * Streams one file of the compiled canvas as the response body, returning
428
+ * whether it answered.
372
429
  *
373
430
  * A missing app directory is a 500 naming the build step, because the server
374
431
  * is fine and the operator forgot to compile; a missing file inside a present
375
- * app is an ordinary 404.
432
+ * app goes unanswered, for the caller's 404.
376
433
  */
377
- function serve_app_asset(res, route, override) {
434
+ function serve_app_asset(res, path, override) {
378
435
  const dir = resolve_app_dir(override);
379
436
  if (dir === null) {
380
437
  res.statusCode = 500;
381
438
  res.setHeader("content-type", "text/plain");
382
439
  res.end("viewer app not built; run `pnpm build`");
383
- return;
440
+ return true;
384
441
  }
385
- const file = resolve_app_file(dir, route.slice(route.indexOf(" ") + 1));
442
+ const file = resolve_app_file(dir, path);
386
443
  const stats = file === null ? null : stat_file(file);
387
- if (file === null || stats === null) {
388
- send_not_found(res, route);
389
- return;
390
- }
444
+ if (file === null || stats === null) return false;
391
445
  res.statusCode = 200;
392
446
  res.setHeader("content-type", CONTENT_TYPES[extname(file)] ?? FALLBACK_CONTENT_TYPE);
393
447
  res.setHeader("cache-control", "no-store");
394
448
  res.setHeader("content-length", String(stats.size));
395
449
  stream_file(res, file);
450
+ return true;
396
451
  }
397
452
  /**
398
453
  * Streams a file as the response body, dropping the connection if the read
@@ -1095,6 +1150,6 @@ if (process.argv[1] !== void 0 && process.argv[1] === fileURLToPath(import.meta.
1095
1150
  process.exit(1);
1096
1151
  });
1097
1152
  //#endregion
1098
- export { create_broadcaster, run_viewer_cli, start_server, start_tail, start_viewer };
1153
+ export { create_broadcaster, create_viewer_handler, run_viewer_cli, start_server, start_tail, start_viewer };
1099
1154
 
1100
1155
  //# sourceMappingURL=viewer.js.map