fascicle 0.16.5 → 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.
- package/CHANGELOG.md +49 -0
- package/README.md +3 -2
- package/dist/AGENTS.md +69 -18
- package/dist/acp.d.ts +1 -1
- package/dist/acp.js +6 -1
- package/dist/acp.js.map +1 -1
- package/dist/agents.d.ts +1 -1
- package/dist/{engine-B6rIIM4J.js → engine-BMdRqWL2.js} +988 -218
- package/dist/engine-BMdRqWL2.js.map +1 -0
- package/dist/index.d.ts +108 -16
- package/dist/index.js +225 -16
- package/dist/index.js.map +1 -1
- package/dist/{invoke-LbzZLZFw.js → invoke-BbJLQcLl.js} +62 -106
- package/dist/invoke-BbJLQcLl.js.map +1 -0
- package/dist/{leading_system-WhW76tRn.js → leading_system-DmNxhvzL.js} +45 -16
- package/dist/leading_system-DmNxhvzL.js.map +1 -0
- package/dist/mcp.d.ts +2 -1
- package/dist/mcp.js +6 -3
- package/dist/mcp.js.map +1 -1
- package/dist/otel.js +48 -3
- package/dist/otel.js.map +1 -1
- package/dist/testing.d.ts +77 -2
- package/dist/testing.js +202 -19
- package/dist/testing.js.map +1 -1
- package/dist/{types-Sw0oHW-_.d.ts → types-BNgAUQP1.d.ts} +170 -17
- package/dist/viewer-app/assets/index-9eVv6Mar.css +1 -0
- package/dist/viewer-app/assets/index-BkS2ZQu0.js +4 -0
- package/dist/viewer-app/index.html +2 -2
- package/dist/viewer.d.ts +37 -10
- package/dist/viewer.js +101 -46
- package/dist/viewer.js.map +1 -1
- package/package.json +1 -1
- package/dist/engine-B6rIIM4J.js.map +0 -1
- package/dist/invoke-LbzZLZFw.js.map +0 -1
- package/dist/leading_system-WhW76tRn.js.map +0 -1
- package/dist/viewer-app/assets/index-Cev83tcH.css +0 -1
- 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
|
|
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
|
-
*
|
|
101
|
-
*
|
|
102
|
-
* with the bound URL and port and a `close` that shuts the socket
|
|
103
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
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
|
|
135
|
-
const { broadcaster,
|
|
136
|
-
const
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
|
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
|
-
|
|
163
|
-
|
|
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,
|
|
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
|
-
*
|
|
248
|
-
*
|
|
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
|
|
255
|
-
|
|
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
|
|
432
|
+
* app goes unanswered, for the caller's 404.
|
|
376
433
|
*/
|
|
377
|
-
function serve_app_asset(res,
|
|
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,
|
|
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
|