fascicle 0.15.0 → 0.16.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 +114 -0
- package/README.md +8 -8
- package/dist/acp.d.ts +9 -2
- package/dist/acp.js +1538 -1472
- package/dist/acp.js.map +1 -1
- package/dist/{adapters-DNnzeLxr.js → adapters-CDUzZlby.js} +35 -13
- package/dist/adapters-CDUzZlby.js.map +1 -0
- package/dist/adapters.d.ts +8 -1
- package/dist/adapters.js +1 -1
- package/dist/agents.d.ts +1 -1
- package/dist/agents.js +15 -8
- package/dist/agents.js.map +1 -1
- package/dist/bin/fascicle-viewer.js +4 -1
- package/dist/console-CdB4pcFO.js +37 -0
- package/dist/console-CdB4pcFO.js.map +1 -0
- package/dist/{core-CDrz0NM1.js → core-CErsxGF6.js} +246 -147
- package/dist/core-CErsxGF6.js.map +1 -0
- package/dist/diagram_bin.js +2 -2
- package/dist/diagram_bin.js.map +1 -1
- package/dist/{engine-ha9xmgwE.js → engine-CR8q2IqV.js} +173 -67
- package/dist/engine-CR8q2IqV.js.map +1 -0
- package/dist/index.d.ts +529 -73
- package/dist/index.js +440 -137
- package/dist/index.js.map +1 -1
- package/dist/{invoke-px31fffH.js → invoke-COaeZ-vy.js} +6 -5
- package/dist/invoke-COaeZ-vy.js.map +1 -0
- package/dist/{json_schema_to_standard-BTWD0J6p.js → json_schema_to_standard-C4F4lXHE.js} +9 -12
- package/dist/json_schema_to_standard-C4F4lXHE.js.map +1 -0
- package/dist/{leading_system-DfJLqpGi.js → leading_system-PoHzNHuV.js} +28 -8
- package/dist/leading_system-PoHzNHuV.js.map +1 -0
- package/dist/mcp.d.ts +3 -2
- package/dist/mcp.js +8 -4
- package/dist/mcp.js.map +1 -1
- package/dist/otel.js +10 -10
- package/dist/otel.js.map +1 -1
- package/dist/{search-CA_OqFeW.js → search-CpCJYMUm.js} +53 -6
- package/dist/search-CpCJYMUm.js.map +1 -0
- package/dist/search_worker.js +1 -1
- package/dist/stdio.js +7 -3
- package/dist/stdio.js.map +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -3
- package/dist/testing.js.map +1 -1
- package/dist/{trajectory-Bm-mOtqw.d.ts → trajectory-BKGNxi7u.d.ts} +10 -9
- package/dist/{trajectory-BI-mrVFT.js → trajectory-DeURWIhj.js} +6 -5
- package/dist/trajectory-DeURWIhj.js.map +1 -0
- package/dist/{types-De-TVQxS.d.ts → types-Sw0oHW-_.d.ts} +6 -7
- package/dist/ui.d.ts +2 -1
- package/dist/ui.js +8 -1
- package/dist/ui.js.map +1 -1
- package/dist/viewer-app/assets/index-BYF5Dp7d.js +2 -0
- package/dist/viewer-app/index.html +2 -1
- package/dist/viewer.d.ts +26 -12
- package/dist/viewer.js +282 -63
- package/dist/viewer.js.map +1 -1
- package/package.json +4 -4
- package/dist/adapters-DNnzeLxr.js.map +0 -1
- package/dist/core-CDrz0NM1.js.map +0 -1
- package/dist/engine-ha9xmgwE.js.map +0 -1
- package/dist/invoke-px31fffH.js.map +0 -1
- package/dist/json_schema_to_standard-BTWD0J6p.js.map +0 -1
- package/dist/leading_system-DfJLqpGi.js.map +0 -1
- package/dist/search-CA_OqFeW.js.map +0 -1
- package/dist/trajectory-BI-mrVFT.js.map +0 -1
- package/dist/viewer-app/assets/index-Fnh5HKSU.js +0 -2
package/dist/viewer.js
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
|
-
import "./core-
|
|
2
|
-
import { l as parse_trajectory_event } from "./trajectory-
|
|
1
|
+
import "./core-CErsxGF6.js";
|
|
2
|
+
import { l as parse_trajectory_event } from "./trajectory-DeURWIhj.js";
|
|
3
3
|
import { open, stat } from "node:fs/promises";
|
|
4
|
-
import { dirname, extname, resolve, sep } from "node:path";
|
|
4
|
+
import { basename, dirname, extname, resolve, sep } from "node:path";
|
|
5
5
|
import { createReadStream, existsSync, statSync, watch } from "node:fs";
|
|
6
6
|
import { spawn } from "node:child_process";
|
|
7
|
+
import { pipeline } from "node:stream";
|
|
7
8
|
import { fileURLToPath } from "node:url";
|
|
8
9
|
import { createServer } from "node:http";
|
|
10
|
+
import { isIPv6 } from "node:net";
|
|
9
11
|
import { parseArgs } from "node:util";
|
|
10
12
|
//#region src/viewer/broadcast.ts
|
|
11
13
|
/**
|
|
@@ -72,7 +74,12 @@ function create_broadcaster(config) {
|
|
|
72
74
|
* on disk. A client folds `/api/trajectory` for the whole run and then follows
|
|
73
75
|
* `/api/events`, which replays anything past the cursor it names and streams
|
|
74
76
|
* new events live. The ring is bounded memory by design, so history older than
|
|
75
|
-
* it is served from the file the tail already reads
|
|
77
|
+
* it is served from the file the tail already reads.
|
|
78
|
+
*
|
|
79
|
+
* A server bound to a loopback name answers only requests whose `Host` names
|
|
80
|
+
* loopback too, so a web page can't reach it by rebinding a domain of its own
|
|
81
|
+
* to 127.0.0.1. Ingest is mounted unless the config turns it off, reads only
|
|
82
|
+
* `application/x-ndjson`, and refuses a body past 8 MB.
|
|
76
83
|
*/
|
|
77
84
|
const SSE_HEARTBEAT_MS = 15e3;
|
|
78
85
|
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
@@ -100,16 +107,37 @@ const CONTENT_TYPES = {
|
|
|
100
107
|
};
|
|
101
108
|
const FALLBACK_CONTENT_TYPE = "application/octet-stream";
|
|
102
109
|
/**
|
|
110
|
+
* The names that keep the viewer on this machine. A server bound to one of
|
|
111
|
+
* them answers only a request whose `Host` names one of them as well.
|
|
112
|
+
*/
|
|
113
|
+
const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
|
|
114
|
+
"localhost",
|
|
115
|
+
"127.0.0.1",
|
|
116
|
+
"::1"
|
|
117
|
+
]);
|
|
118
|
+
/** The one content type `/api/ingest` reads, which is what `http_logger` sends. */
|
|
119
|
+
const NDJSON = "application/x-ndjson";
|
|
120
|
+
/**
|
|
121
|
+
* The most bytes one ingest body may carry. `http_logger` posts a single
|
|
122
|
+
* event per request, so only a runaway or hostile client comes near it.
|
|
123
|
+
*/
|
|
124
|
+
const INGEST_LIMIT_BYTES = 8e6;
|
|
125
|
+
/**
|
|
103
126
|
* Starts the HTTP server and resolves once it is listening.
|
|
104
127
|
*
|
|
105
|
-
* Wires the
|
|
106
|
-
* app's static files to a single request handler, and resolves
|
|
107
|
-
* URL and a `close` that shuts the socket down. The
|
|
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
|
|
108
132
|
* first and exactly, so no file the canvas ships can ever shadow one.
|
|
109
133
|
*/
|
|
110
134
|
function start_server(config) {
|
|
111
|
-
const { broadcaster, host, port, app_dir, trajectory_path, on_parse_error } = config;
|
|
135
|
+
const { broadcaster, host, port, app_dir, trajectory_path, ingest = true, on_parse_error } = config;
|
|
112
136
|
const handler = (req, res) => {
|
|
137
|
+
if (!host_allowed(host, req.headers.host)) {
|
|
138
|
+
send_forbidden_host(res, host);
|
|
139
|
+
return;
|
|
140
|
+
}
|
|
113
141
|
const route = resolve_route(req, host, port);
|
|
114
142
|
if (route === "GET /api/health") {
|
|
115
143
|
send_json(res, 200, { ok: true });
|
|
@@ -127,7 +155,7 @@ function start_server(config) {
|
|
|
127
155
|
handle_sse(req, res, broadcaster);
|
|
128
156
|
return;
|
|
129
157
|
}
|
|
130
|
-
if (route === "POST /api/ingest") {
|
|
158
|
+
if (ingest && route === "POST /api/ingest") {
|
|
131
159
|
handle_ingest(req, res, broadcaster, on_parse_error);
|
|
132
160
|
return;
|
|
133
161
|
}
|
|
@@ -142,8 +170,10 @@ function start_server(config) {
|
|
|
142
170
|
http_server.once("error", res_err);
|
|
143
171
|
http_server.listen(port, host, () => {
|
|
144
172
|
http_server.removeListener("error", res_err);
|
|
173
|
+
const bound_port = bound_port_of(http_server.address(), port);
|
|
145
174
|
res_ok({
|
|
146
|
-
url: `http://${host
|
|
175
|
+
url: `http://${format_authority(host, bound_port)}`,
|
|
176
|
+
port: bound_port,
|
|
147
177
|
close: () => close_server(http_server)
|
|
148
178
|
});
|
|
149
179
|
});
|
|
@@ -161,6 +191,57 @@ function bound_port_of(addr, fallback) {
|
|
|
161
191
|
return addr !== null && typeof addr === "object" && "port" in addr ? addr.port : fallback;
|
|
162
192
|
}
|
|
163
193
|
/**
|
|
194
|
+
* Joins a host and port into a URL authority, bracketing an IPv6 literal.
|
|
195
|
+
*
|
|
196
|
+
* `http://::1:4242` is not a URL; `http://[::1]:4242` is. A hostname or IPv4
|
|
197
|
+
* address passes through untouched.
|
|
198
|
+
*/
|
|
199
|
+
function format_authority(host, port) {
|
|
200
|
+
return `${isIPv6(host) ? `[${host}]` : host}:${port}`;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Whether `host` is a loopback name, which keeps a server bound to it on this
|
|
204
|
+
* machine.
|
|
205
|
+
*/
|
|
206
|
+
function is_loopback_host(host) {
|
|
207
|
+
return LOOPBACK_HOSTS.has(host);
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* The hostname a `Host` header names, lowercased, with an IPv6 literal's
|
|
211
|
+
* brackets and any port taken off.
|
|
212
|
+
*/
|
|
213
|
+
function host_name(header) {
|
|
214
|
+
const host = header.toLowerCase();
|
|
215
|
+
if (host.startsWith("[")) return host.slice(1, host.indexOf("]"));
|
|
216
|
+
const colon = host.indexOf(":");
|
|
217
|
+
return colon === -1 ? host : host.slice(0, colon);
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* Whether a server bound to `bound` answers a request whose `Host` header is
|
|
221
|
+
* `header`.
|
|
222
|
+
*
|
|
223
|
+
* Bound to a loopback name, it answers only a `Host` that names loopback too,
|
|
224
|
+
* whatever the port, because a page that rebinds a domain of its own to
|
|
225
|
+
* 127.0.0.1 still sends that domain, and would otherwise read every prompt and
|
|
226
|
+
* output in the trajectory. A request with no `Host` is refused as well. Bound
|
|
227
|
+
* anywhere else, it checks nothing: whoever can reach it can read it, which
|
|
228
|
+
* is what the CLI warns about before it binds.
|
|
229
|
+
*/
|
|
230
|
+
function host_allowed(bound, header) {
|
|
231
|
+
if (!is_loopback_host(bound)) return true;
|
|
232
|
+
return header !== void 0 && is_loopback_host(host_name(header));
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* Writes the 403 for a request whose `Host` a loopback-bound server won't
|
|
236
|
+
* answer, naming the names it will.
|
|
237
|
+
*/
|
|
238
|
+
function send_forbidden_host(res, bound) {
|
|
239
|
+
send_json(res, 403, {
|
|
240
|
+
error: "forbidden_host",
|
|
241
|
+
message: `this viewer is bound to ${bound} and answers only a Host of localhost, 127.0.0.1, or ::1; open it by one of those names`
|
|
242
|
+
});
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
164
245
|
* Builds a `"METHOD /path"` route key from a request.
|
|
165
246
|
*
|
|
166
247
|
* Resolves the path against the client's `Host` header when it parses, and
|
|
@@ -177,7 +258,7 @@ function resolve_route(req, host, port) {
|
|
|
177
258
|
if (header !== void 0) try {
|
|
178
259
|
return `${method} ${new URL(path, `http://${header}`).pathname}`;
|
|
179
260
|
} catch {}
|
|
180
|
-
return `${method} ${new URL(path, `http://${host
|
|
261
|
+
return `${method} ${new URL(path, `http://${format_authority(host, port)}`).pathname}`;
|
|
181
262
|
}
|
|
182
263
|
/**
|
|
183
264
|
* Closes the HTTP server and resolves once every connection is torn down.
|
|
@@ -211,7 +292,7 @@ function send_not_found(res, route) {
|
|
|
211
292
|
/**
|
|
212
293
|
* Handles `GET /api/trajectory` by streaming the whole run history as NDJSON,
|
|
213
294
|
* one event per line, so the client folds the full run before it follows the
|
|
214
|
-
* live tail
|
|
295
|
+
* live tail.
|
|
215
296
|
*
|
|
216
297
|
* The tailed file is the source of truth: its bytes stream straight through,
|
|
217
298
|
* which keeps memory bounded no matter how long the run grew, and a finished
|
|
@@ -230,7 +311,7 @@ function serve_trajectory(res, broadcaster, trajectory_path) {
|
|
|
230
311
|
res.setHeader(CURSOR_HEADER, String(ring.at(-1)?.id ?? 0));
|
|
231
312
|
if (trajectory_path !== void 0) {
|
|
232
313
|
if (stat_file(trajectory_path) !== null) {
|
|
233
|
-
|
|
314
|
+
stream_file(res, trajectory_path);
|
|
234
315
|
return;
|
|
235
316
|
}
|
|
236
317
|
}
|
|
@@ -311,7 +392,20 @@ function serve_app_asset(res, route, override) {
|
|
|
311
392
|
res.setHeader("content-type", CONTENT_TYPES[extname(file)] ?? FALLBACK_CONTENT_TYPE);
|
|
312
393
|
res.setHeader("cache-control", "no-store");
|
|
313
394
|
res.setHeader("content-length", String(stats.size));
|
|
314
|
-
|
|
395
|
+
stream_file(res, file);
|
|
396
|
+
}
|
|
397
|
+
/**
|
|
398
|
+
* Streams a file as the response body, dropping the connection if the read
|
|
399
|
+
* fails.
|
|
400
|
+
*
|
|
401
|
+
* A file can pass `stat_file` and still refuse to open (mode 000 answers
|
|
402
|
+
* EACCES), and a bare `pipe` leaves that stream error unhandled, which ends the
|
|
403
|
+
* process. `pipeline` handles it by destroying both ends, so the client sees a
|
|
404
|
+
* dropped connection and the server keeps serving. It also closes the file when
|
|
405
|
+
* a client leaves mid-stream.
|
|
406
|
+
*/
|
|
407
|
+
function stream_file(res, path) {
|
|
408
|
+
pipeline(createReadStream(path), res, () => {});
|
|
315
409
|
}
|
|
316
410
|
/**
|
|
317
411
|
* Handles `GET /api/events` by turning the connection into an SSE stream.
|
|
@@ -383,15 +477,62 @@ function write_event(res, id, event) {
|
|
|
383
477
|
res.write(`id: ${id}\nevent: trajectory\ndata: ${JSON.stringify(event)}\n\n`);
|
|
384
478
|
}
|
|
385
479
|
/**
|
|
480
|
+
* Whether a `content-type` header names NDJSON, whatever its case and its
|
|
481
|
+
* parameters, so `application/x-ndjson; charset=utf-8` counts.
|
|
482
|
+
*/
|
|
483
|
+
function is_ndjson(header) {
|
|
484
|
+
if (header === void 0) return false;
|
|
485
|
+
const semicolon = header.indexOf(";");
|
|
486
|
+
return (semicolon === -1 ? header : header.slice(0, semicolon)).trim().toLowerCase() === NDJSON;
|
|
487
|
+
}
|
|
488
|
+
/**
|
|
489
|
+
* Writes the 413 for an ingest body past the limit, closing the connection so
|
|
490
|
+
* the rest of the body is never read.
|
|
491
|
+
*/
|
|
492
|
+
function send_too_large(res) {
|
|
493
|
+
res.setHeader("connection", "close");
|
|
494
|
+
send_json(res, 413, {
|
|
495
|
+
error: "payload_too_large",
|
|
496
|
+
message: `an ingest body holds at most ${INGEST_LIMIT_BYTES} bytes; post the events in smaller batches`
|
|
497
|
+
});
|
|
498
|
+
}
|
|
499
|
+
/**
|
|
500
|
+
* Answers an ingest request that won't be read, before any of its body is:
|
|
501
|
+
* a 415 for a body that isn't NDJSON, and a 413 for one whose declared length
|
|
502
|
+
* runs past the limit. Returns whether it answered.
|
|
503
|
+
*
|
|
504
|
+
* Requiring the content type is what keeps a web page out: a page can post a
|
|
505
|
+
* `text/plain` body to any origin without a preflight, but not an NDJSON one.
|
|
506
|
+
*/
|
|
507
|
+
function refuse_ingest(req, res) {
|
|
508
|
+
if (!is_ndjson(req.headers["content-type"])) {
|
|
509
|
+
send_json(res, 415, {
|
|
510
|
+
error: "unsupported_media_type",
|
|
511
|
+
message: `post trajectory events as ${NDJSON}, one JSON event to a line`
|
|
512
|
+
});
|
|
513
|
+
return true;
|
|
514
|
+
}
|
|
515
|
+
if (Number(req.headers["content-length"]) > INGEST_LIMIT_BYTES) {
|
|
516
|
+
send_too_large(res);
|
|
517
|
+
return true;
|
|
518
|
+
}
|
|
519
|
+
return false;
|
|
520
|
+
}
|
|
521
|
+
/**
|
|
386
522
|
* Handles `POST /api/ingest`: parses newline-delimited trajectory events
|
|
387
523
|
* from the request body and feeds valid ones into the broadcaster.
|
|
388
524
|
*
|
|
389
525
|
* Reports how many lines were accepted vs rejected in the response body;
|
|
390
526
|
* a malformed line is skipped and reported via `on_parse_error`, not
|
|
391
|
-
* treated as a fatal request error.
|
|
527
|
+
* treated as a fatal request error. A body sent without a length is counted
|
|
528
|
+
* as it streams, and one that runs past the limit gets its 413 there, after
|
|
529
|
+
* the lines before that point have gone out. Once a request is answered,
|
|
530
|
+
* nothing more it sends is read or reported.
|
|
392
531
|
*/
|
|
393
532
|
function handle_ingest(req, res, broadcaster, on_parse_error) {
|
|
533
|
+
if (refuse_ingest(req, res)) return;
|
|
394
534
|
let buf = "";
|
|
535
|
+
let received = 0;
|
|
395
536
|
let accepted = 0;
|
|
396
537
|
let rejected = 0;
|
|
397
538
|
const consume_line = (line) => {
|
|
@@ -415,6 +556,12 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
|
|
|
415
556
|
};
|
|
416
557
|
req.setEncoding("utf8");
|
|
417
558
|
req.on("data", (chunk) => {
|
|
559
|
+
if (res.writableEnded) return;
|
|
560
|
+
received += Buffer.byteLength(chunk);
|
|
561
|
+
if (received > INGEST_LIMIT_BYTES) {
|
|
562
|
+
send_too_large(res);
|
|
563
|
+
return;
|
|
564
|
+
}
|
|
418
565
|
buf += chunk;
|
|
419
566
|
let nl = buf.indexOf("\n");
|
|
420
567
|
while (nl !== -1) {
|
|
@@ -424,6 +571,7 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
|
|
|
424
571
|
}
|
|
425
572
|
});
|
|
426
573
|
req.on("end", () => {
|
|
574
|
+
if (res.writableEnded) return;
|
|
427
575
|
if (buf.length > 0) consume_line(buf);
|
|
428
576
|
send_json(res, 200, {
|
|
429
577
|
accepted,
|
|
@@ -431,6 +579,7 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
|
|
|
431
579
|
});
|
|
432
580
|
});
|
|
433
581
|
req.on("error", (err) => {
|
|
582
|
+
if (res.writableEnded) return;
|
|
434
583
|
if (on_parse_error) on_parse_error(err, "");
|
|
435
584
|
send_json(res, 400, { error: "bad_request" });
|
|
436
585
|
});
|
|
@@ -440,41 +589,70 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
|
|
|
440
589
|
/**
|
|
441
590
|
* JSONL file tailer.
|
|
442
591
|
*
|
|
443
|
-
*
|
|
444
|
-
* complete line. Handles
|
|
592
|
+
* Follows a path for appends and emits one parsed trajectory event per
|
|
593
|
+
* complete line. Handles these pathological cases:
|
|
445
594
|
*
|
|
446
|
-
* -
|
|
447
|
-
*
|
|
595
|
+
* - A file that doesn't exist yet: a missing file is a wait, not an
|
|
596
|
+
* error. The tail reads it from its first line once it appears.
|
|
597
|
+
* - Rotation: a file renamed away and recreated under the same name is a
|
|
598
|
+
* new inode, so the tail starts the new file from its first line rather
|
|
599
|
+
* than at the old file's offset.
|
|
600
|
+
* - Truncation: a stat shorter than the current offset means the file
|
|
601
|
+
* shrank in place. Reset offset to 0 and re-stream.
|
|
448
602
|
* - Partial last line: if the trailing chunk has no `\n`, buffer it and
|
|
449
603
|
* wait. Never parse a half-written line.
|
|
450
604
|
* - Schema failures: a line that fails `parse_trajectory_event` is
|
|
451
605
|
* dropped and surfaced to `on_parse_error`. The stream keeps going.
|
|
452
606
|
*
|
|
453
|
-
*
|
|
454
|
-
*
|
|
455
|
-
*
|
|
456
|
-
*
|
|
457
|
-
*
|
|
458
|
-
*
|
|
607
|
+
* Two fs.watch watchers drive the reads. A watch on the file itself carries
|
|
608
|
+
* every append, but it follows the file's inode, so it can't see a file
|
|
609
|
+
* appear and after a rename it reports on the old one. So while the file is
|
|
610
|
+
* missing, and from the moment that watch reports a rename, a second watch
|
|
611
|
+
* on the parent directory waits for the file's name, and the first pass that
|
|
612
|
+
* finds a file there moves the file watch onto it and drops the directory
|
|
613
|
+
* watch. Appends never ride the directory watch, because macOS serves a
|
|
614
|
+
* directory through FSEvents, whose stream starts asynchronously and drops
|
|
615
|
+
* what happens before it is live, while a file watch is kqueue's and holds
|
|
616
|
+
* from the moment it is made. Reads are serialized, and change events that arrive mid-read are coalesced
|
|
617
|
+
* into one extra pass rather than dropped, so a burst of appends never starts
|
|
618
|
+
* overlapping reads. Each pass re-stats and re-reads from the saved offset,
|
|
619
|
+
* which also covers platforms where fs.watch misses some append
|
|
620
|
+
* notifications: the next successful change event catches the file up
|
|
621
|
+
* regardless.
|
|
459
622
|
*/
|
|
460
623
|
/**
|
|
624
|
+
* True for the error a stat or an open throws when nothing is at the path,
|
|
625
|
+
* which the tail reads as waiting for the file rather than as a failure.
|
|
626
|
+
*/
|
|
627
|
+
function is_missing(err) {
|
|
628
|
+
return Reflect.get(Object(err), "code") === "ENOENT";
|
|
629
|
+
}
|
|
630
|
+
/**
|
|
461
631
|
* Starts tailing `path` and returns a handle to stop or drain it.
|
|
462
632
|
*
|
|
463
633
|
* Watches the file with `fs.watch` and re-reads from the last known offset
|
|
464
634
|
* on every change, buffering an incomplete trailing line until the rest
|
|
465
|
-
* arrives.
|
|
466
|
-
*
|
|
467
|
-
*
|
|
635
|
+
* arrives. A missing file is waited for through a watch on its directory,
|
|
636
|
+
* and a new file at the path (a different inode) is read from its first
|
|
637
|
+
* line. Overlapping change events are coalesced: a read already in flight
|
|
638
|
+
* absorbs any events that fire while it runs instead of starting a second
|
|
639
|
+
* concurrent read.
|
|
468
640
|
*/
|
|
469
641
|
function start_tail(config) {
|
|
470
642
|
const { path, on_event, on_parse_error, on_io_error } = config;
|
|
643
|
+
const name = basename(path);
|
|
644
|
+
let inode = null;
|
|
471
645
|
let offset = 0;
|
|
472
646
|
let buffer = "";
|
|
473
647
|
let busy = false;
|
|
474
648
|
let pending = false;
|
|
475
649
|
let closed = false;
|
|
476
|
-
let
|
|
650
|
+
let file_watcher = null;
|
|
651
|
+
let dir_watcher = null;
|
|
477
652
|
let last_drain = Promise.resolve();
|
|
653
|
+
const report = (err) => {
|
|
654
|
+
if (on_io_error && !is_missing(err)) on_io_error(err);
|
|
655
|
+
};
|
|
478
656
|
const handle_line = (line) => {
|
|
479
657
|
if (line.length === 0) return;
|
|
480
658
|
let parsed;
|
|
@@ -491,30 +669,70 @@ function start_tail(config) {
|
|
|
491
669
|
}
|
|
492
670
|
on_event(result.data);
|
|
493
671
|
};
|
|
494
|
-
const
|
|
672
|
+
const watch$1 = (target, listener) => {
|
|
673
|
+
if (closed) return null;
|
|
674
|
+
try {
|
|
675
|
+
return watch(target, { persistent: true }, listener);
|
|
676
|
+
} catch (err) {
|
|
677
|
+
if (on_io_error) on_io_error(err);
|
|
678
|
+
return null;
|
|
679
|
+
}
|
|
680
|
+
};
|
|
681
|
+
const await_file = () => {
|
|
682
|
+
if (dir_watcher !== null) return;
|
|
683
|
+
dir_watcher = watch$1(dirname(path), (_event, filename) => {
|
|
684
|
+
if (filename === null || filename === name) schedule();
|
|
685
|
+
});
|
|
686
|
+
if (dir_watcher !== null) schedule();
|
|
687
|
+
};
|
|
688
|
+
const adopt = (ino) => {
|
|
689
|
+
inode = ino;
|
|
690
|
+
offset = 0;
|
|
691
|
+
buffer = "";
|
|
692
|
+
file_watcher?.close();
|
|
693
|
+
file_watcher = watch$1(path, (event) => {
|
|
694
|
+
if (event === "rename") await_file();
|
|
695
|
+
schedule();
|
|
696
|
+
});
|
|
697
|
+
dir_watcher?.close();
|
|
698
|
+
dir_watcher = null;
|
|
699
|
+
};
|
|
700
|
+
const locate = async () => {
|
|
495
701
|
let st;
|
|
496
702
|
try {
|
|
497
703
|
st = await stat(path);
|
|
498
704
|
} catch (err) {
|
|
499
|
-
if (
|
|
500
|
-
|
|
705
|
+
if (is_missing(err)) {
|
|
706
|
+
inode = null;
|
|
707
|
+
await_file();
|
|
708
|
+
}
|
|
709
|
+
report(err);
|
|
710
|
+
return null;
|
|
501
711
|
}
|
|
502
|
-
if (st.
|
|
712
|
+
if (st.ino !== inode) adopt(st.ino);
|
|
713
|
+
else if (st.size < offset) {
|
|
503
714
|
offset = 0;
|
|
504
715
|
buffer = "";
|
|
505
716
|
}
|
|
506
|
-
|
|
717
|
+
return st.size;
|
|
718
|
+
};
|
|
719
|
+
const read_more = async () => {
|
|
720
|
+
const size = await locate();
|
|
721
|
+
if (size === null || size === offset) return;
|
|
507
722
|
const fh = await open(path, "r").catch((err) => {
|
|
508
|
-
|
|
723
|
+
report(err);
|
|
509
724
|
return null;
|
|
510
725
|
});
|
|
511
726
|
if (!fh) return;
|
|
512
727
|
try {
|
|
513
|
-
const length =
|
|
728
|
+
const length = size - offset;
|
|
514
729
|
const buf = Buffer.alloc(length);
|
|
515
730
|
const { bytesRead } = await fh.read(buf, 0, length, offset);
|
|
516
731
|
offset += bytesRead;
|
|
517
732
|
buffer += buf.subarray(0, bytesRead).toString("utf8");
|
|
733
|
+
} catch (err) {
|
|
734
|
+
report(err);
|
|
735
|
+
return;
|
|
518
736
|
} finally {
|
|
519
737
|
await fh.close();
|
|
520
738
|
}
|
|
@@ -547,19 +765,12 @@ function start_tail(config) {
|
|
|
547
765
|
})();
|
|
548
766
|
};
|
|
549
767
|
schedule();
|
|
550
|
-
try {
|
|
551
|
-
watcher = watch(path, { persistent: true }, () => {
|
|
552
|
-
schedule();
|
|
553
|
-
});
|
|
554
|
-
} catch (err) {
|
|
555
|
-
if (on_io_error) on_io_error(err);
|
|
556
|
-
}
|
|
557
768
|
const stop = () => {
|
|
558
769
|
closed = true;
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
770
|
+
file_watcher?.close();
|
|
771
|
+
file_watcher = null;
|
|
772
|
+
dir_watcher?.close();
|
|
773
|
+
dir_watcher = null;
|
|
563
774
|
};
|
|
564
775
|
const drain = async () => {
|
|
565
776
|
schedule();
|
|
@@ -583,8 +794,9 @@ function start_tail(config) {
|
|
|
583
794
|
* Starts the viewer: brings up the HTTP/SSE server and, if `options.path`
|
|
584
795
|
* is set, a file tail that feeds the same broadcaster.
|
|
585
796
|
*
|
|
586
|
-
* Defaults to `127.0.0.1:4242` with a 1000-event ring buffer.
|
|
587
|
-
*
|
|
797
|
+
* Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. SSE is always
|
|
798
|
+
* available, HTTP ingest is on unless `ingest` is false, and tailing is opt-in
|
|
799
|
+
* via `path`.
|
|
588
800
|
*/
|
|
589
801
|
async function start_viewer(options = {}) {
|
|
590
802
|
const host = options.host ?? "127.0.0.1";
|
|
@@ -597,6 +809,7 @@ async function start_viewer(options = {}) {
|
|
|
597
809
|
broadcaster,
|
|
598
810
|
host,
|
|
599
811
|
port,
|
|
812
|
+
ingest: options.ingest,
|
|
600
813
|
...options.path !== void 0 ? { trajectory_path: options.path } : {},
|
|
601
814
|
...options.on_parse_error ? { on_parse_error: options.on_parse_error } : {}
|
|
602
815
|
});
|
|
@@ -615,15 +828,15 @@ async function start_viewer(options = {}) {
|
|
|
615
828
|
* Combines the server and optional tail into a single `ViewerHandle`.
|
|
616
829
|
*
|
|
617
830
|
* `close` stops the tail first, then closes the server, mirroring the
|
|
618
|
-
* startup order (server first, tail second) in reverse. The port is
|
|
619
|
-
*
|
|
831
|
+
* startup order (server first, tail second) in reverse. The port is the one
|
|
832
|
+
* the server reports binding rather than the requested `port` option, since
|
|
620
833
|
* a caller that passes `0` gets whatever port the OS actually bound.
|
|
621
834
|
*/
|
|
622
835
|
function wrap_handle(server, tail, host) {
|
|
623
836
|
return {
|
|
624
837
|
url: server.url,
|
|
625
838
|
host,
|
|
626
|
-
port:
|
|
839
|
+
port: server.port,
|
|
627
840
|
close: async () => {
|
|
628
841
|
if (tail) tail.stop();
|
|
629
842
|
await server.close();
|
|
@@ -641,9 +854,13 @@ function wrap_handle(server, tail, host) {
|
|
|
641
854
|
*
|
|
642
855
|
* Flags: --port <n> --host <h> --buffer <n> --no-open --help
|
|
643
856
|
*
|
|
857
|
+
* `POST /api/ingest` is mounted only under `--listen`, so a viewer that only
|
|
858
|
+
* tails a file takes no posts from anything.
|
|
859
|
+
*
|
|
644
860
|
* Defaults bind 127.0.0.1:4242 and open the user's default browser. SIGINT
|
|
645
861
|
* shuts everything down cleanly. The CLI body is exposed as `run_viewer_cli`
|
|
646
|
-
* so the
|
|
862
|
+
* so the `fascicle-viewer` bin shim can drive it from the bundled
|
|
863
|
+
* `dist/viewer.js`.
|
|
647
864
|
*/
|
|
648
865
|
const HELP = `\
|
|
649
866
|
fascicle-viewer — minimal in-repo dashboard for fascicle trajectory streams.
|
|
@@ -654,8 +871,9 @@ Usage:
|
|
|
654
871
|
fascicle-viewer <path> --listen both producers feed the same broadcaster
|
|
655
872
|
|
|
656
873
|
Options:
|
|
874
|
+
--listen accept HTTP push on /api/ingest (off unless set)
|
|
657
875
|
--port <n> port (default 4242)
|
|
658
|
-
--host <h> bind host (default 127.0.0.1;
|
|
876
|
+
--host <h> bind host (default 127.0.0.1; a non-loopback host warns)
|
|
659
877
|
--buffer <n> ring-buffer size (default 1000)
|
|
660
878
|
--no-open do not open the browser
|
|
661
879
|
--help show this message
|
|
@@ -705,8 +923,8 @@ function parse(argv) {
|
|
|
705
923
|
process.stdout.write(HELP);
|
|
706
924
|
process.exit(0);
|
|
707
925
|
}
|
|
708
|
-
const port_raw = values.port
|
|
709
|
-
const buffer_raw = values.buffer
|
|
926
|
+
const port_raw = values.port;
|
|
927
|
+
const buffer_raw = values.buffer;
|
|
710
928
|
const port = Number.parseInt(port_raw, 10);
|
|
711
929
|
const buffer = Number.parseInt(buffer_raw, 10);
|
|
712
930
|
if (!Number.isFinite(port) || port <= 0) {
|
|
@@ -718,7 +936,7 @@ function parse(argv) {
|
|
|
718
936
|
process.exit(2);
|
|
719
937
|
}
|
|
720
938
|
const path = positionals[0];
|
|
721
|
-
const listen = values.listen
|
|
939
|
+
const listen = values.listen;
|
|
722
940
|
if (path === void 0 && !listen) {
|
|
723
941
|
process.stderr.write("fascicle-viewer: a <path> is required unless --listen is set\n");
|
|
724
942
|
process.stderr.write(HELP);
|
|
@@ -726,11 +944,11 @@ function parse(argv) {
|
|
|
726
944
|
}
|
|
727
945
|
return {
|
|
728
946
|
...path !== void 0 ? { path } : {},
|
|
729
|
-
host: values.host
|
|
947
|
+
host: values.host,
|
|
730
948
|
port,
|
|
731
949
|
buffer,
|
|
732
950
|
listen,
|
|
733
|
-
open: !values["no-open"] &&
|
|
951
|
+
open: !values["no-open"] && values.open
|
|
734
952
|
};
|
|
735
953
|
}
|
|
736
954
|
/**
|
|
@@ -761,19 +979,20 @@ function open_browser(url) {
|
|
|
761
979
|
* CLI entry point: parses argv, starts the viewer, and wires shutdown.
|
|
762
980
|
*
|
|
763
981
|
* Warns but proceeds when the tailed path does not exist yet or when the
|
|
764
|
-
* bind host is
|
|
982
|
+
* bind host is not loopback (the dashboard has no auth). Optionally opens the
|
|
765
983
|
* browser, then installs SIGINT/SIGTERM handlers that close the viewer
|
|
766
984
|
* before exiting.
|
|
767
985
|
*/
|
|
768
986
|
async function run_viewer_cli(argv) {
|
|
769
987
|
const args = parse(argv);
|
|
770
|
-
if (args.path !== void 0 && !existsSync(args.path)) process.stderr.write(`fascicle-viewer: warning: ${args.path} does not exist yet
|
|
771
|
-
if (args.host
|
|
988
|
+
if (args.path !== void 0 && !existsSync(args.path)) process.stderr.write(`fascicle-viewer: warning: ${args.path} does not exist yet, so the viewer will read it from its first line once it is created\n`);
|
|
989
|
+
if (!is_loopback_host(args.host)) process.stderr.write(`fascicle-viewer: warning: binding ${args.host} reaches beyond this machine, and the dashboard has no auth, so anyone who can reach it reads your trajectory stream; pass --host 127.0.0.1 to keep it local\n`);
|
|
772
990
|
const handle = await start_viewer({
|
|
773
991
|
...args.path !== void 0 ? { path: args.path } : {},
|
|
774
992
|
host: args.host,
|
|
775
993
|
port: args.port,
|
|
776
994
|
buffer: args.buffer,
|
|
995
|
+
ingest: args.listen,
|
|
777
996
|
on_parse_error: (err, line) => {
|
|
778
997
|
const preview = line.length > 120 ? `${line.slice(0, 120)}…` : line;
|
|
779
998
|
process.stderr.write(`fascicle-viewer: skipped malformed line: ${preview}\n ${describe_error(err)}\n`);
|
|
@@ -783,7 +1002,7 @@ async function run_viewer_cli(argv) {
|
|
|
783
1002
|
}
|
|
784
1003
|
});
|
|
785
1004
|
if (args.path !== void 0) process.stderr.write(`fascicle-viewer: watching ${args.path}\n`);
|
|
786
|
-
if (args.listen
|
|
1005
|
+
if (args.listen) process.stderr.write(`fascicle-viewer: listening for HTTP push on ${handle.url}/api/ingest\n`);
|
|
787
1006
|
process.stderr.write(`fascicle-viewer: viewer at ${handle.url}\n`);
|
|
788
1007
|
if (args.open) open_browser(handle.url);
|
|
789
1008
|
const shutdown = async () => {
|