Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_net/lens/js/writer.js

30.9 KiB, 17 runs

created by r1870400018:65634, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1// writer.js -- the browser half of the debug lens: a durable outbox of small self-describing
2// events, drained through a send function the app supplies.
3//
4// Extracted from Daimond's `www/js/debugshare.js` (2026-10-02) so that Daimond and Oxegen share
5// one writer. It keeps Daimond's behaviour exactly, and everything the app alone knows is a
6// parameter: where state is kept, how a post is made, who the device is, which names and strings
7// are secret, which extra lane of rows drains behind the events. The Settings flag, the snapshot
8// and telemetry lanes, the beat and the screen stay in the app.
9//
10// THE ENVELOPE. Every event is one row, `{ ts, tag: 'ev <kind>', data: <JSON, 360 bytes at most> }`,
11// and its JSON begins `{ v, d, n, b, t }`: schema version, a short device id, a PERSISTED per-device
12// sequence number, the build id, and the wall clock. `n` makes redelivery idempotent for the
13// reader. `fe2o3_net::lens::Row` writes the same envelope in Rust and `lens::Sink` stores the row.
14//
15// THE OUTBOX. Rows are held in memory and in `storage` (5,000 at most, the oldest dropped with one
16// `feed.drop` naming how many). A row leaves only when a post is known to have landed, so an
17// outage, a reload or a killed tab loses nothing. A failed post backs the next attempt off,
18// doubling to five minutes.
19//
20// ONE POST CLOCK. The receiving sink refuses a second post inside its floor (two seconds in
21// Daimond's gateway). `lastPostAt` is stamped by every post of every lane, persisted, and
22// consulted by every drain that starts, so the gap holds across lanes and across a reload. A 429
23// that arrives anyway doubles the gap and is announced once per burst as `feed.throttled`.
24//
25// SELF-PROTECTION. Every entry point is wrapped. An exception inside the feed queues one
26// `feed.fault` and turns collection off for the session, and the drainer keeps running so the
27// fault itself reaches the sink. The caller's own code path continues: the app never breaks
28// because the feed did.
29//
30// NO GLOBALS. The writer touches no `window`, `document`, `localStorage` or `fetch` that it was not
31// handed in `cfg.host`, which is what lets one module serve a page, a test and a worker.
32import {
33 byteLen,
34 clipChars,
35 createRedactor,
36 createScrubber,
37 soundText,
38} from './redact.js';
39
40export {
41 SECRET_RE,
42 SECRET_RE_LOOSE,
43 byteLen,
44 clipChars,
45 createRedactor,
46 createRunGuard,
47 createScrubber,
48 fingerprint,
49 scrubDeep,
50 scrubText,
51 secretName,
52 soundText,
53} from './redact.js';
54
55// ── The caps ─────────────────────────────────────────────────────────
56
57// Mirrored from Daimond's gateway handler with a margin, so a post is never refused for size and
58// a row is never clipped mid-payload. A caller overrides any of them through `cfg.caps`.
59const CAPS = {
60 maxEventBytes: 360, // an event's JSON; the sink's field cap is 400
61 maxRowsPost: 400, // rows in one post; the sink refuses past 1,000
62 maxBodyBytes: 200 * 1024, // one post's body; the sink refuses past 256 KiB
63 outboxCap: 5000, // events held before the oldest are dropped
64 gapMs: 3000, // the minimum gap between ANY two posts, all lanes
65 backoffMaxMs: 300000, // the ceiling on repeated-failure backoff
66 persistMs: 250, // trailing debounce on writing the outbox out
67 errorsPerMin: 20, // error-capture rate cap, with a `dropped` count
68 errWindowMs: 60000,
69 consolePerMin: 60, // distinct console lines admitted per window
70 consoleWindowMs: 60000,
71 consoleDedupeMs: 60000, // an identical (level, message) inside this is one event
72 maxMsgChars: 200, // an error or console message, clipped
73 maxSrcChars: 60, // and where it came from
74 maxDevChars: 12, // envelope fields are bounded so they never crowd out the payload
75 maxBuildChars: 24,
76 unloadGraceMs: 2000, // a status 0 this soon after pagehide is an abandoned call
77};
78
79const LEVELS = ['log', 'info', 'debug', 'warn', 'error'];
80
81// A message that looks like it carries a secret VALUE. A name sitting against a value, or a
82// provider-key-shaped run, is treated as live; a message that merely mentions a token is not.
83const SECRET_TEXT_RE = /(?:api[_-]?key|token|secret|passphrase|password|master[_-]?key|mnemonic|private[_-]?key|salt|sealed|wrapped)["'\s]*[:=]/i;
84const SECRET_SHAPE_RE = /\b(?:sk|pk|ghp|xox[abps])[-_][A-Za-z0-9_-]{12,}/;
85
86const ENVELOPE = { v: 1, d: 1, n: 1, b: 1, t: 1 };
87
88/// Does this console message look like it carries a secret value?
89export function looksSecret(msg) {
90 return SECRET_TEXT_RE.test(msg) || SECRET_SHAPE_RE.test(msg);
91}
92
93/// Creates a writer. `cfg`:
94///
95/// host `{ storage, setTimeout, clearTimeout, console, now, document, Error }`, each defaulting to
96/// the global of that name where one exists. `storage` is `getItem`/`setItem`.
97/// keys `{ outbox, seq, postAt }`, the storage key names.
98/// device `() -> string`, the device id (clipped to 12 characters in the envelope).
99/// build `() -> string`, the build id (24 characters).
100/// enabled `() -> bool`, the gate; while it answers false nothing is collected or sent.
101/// send `(rows, { device }) -> Promise`, how one post is made. It may resolve a Response-like
102/// `{ ok, status }`, a bare `{ status }`, or nothing (delivered); a rejection is a failure.
103/// redact a `createRedactor` value, applied to every event before it is cut.
104/// scrub a `createScrubber` value, applied to free text before it is cut.
105/// extra `(kind) -> object | null`, fields added after the envelope for that kind.
106/// lane `{ pending() -> bool, next() -> rows }`, a second lane drained after the outbox, on the
107/// same post clock. Its posts may be lost without harm: the next one replaces them.
108/// ownPath the path of the feed's own endpoint, which `noteFetchFail` never reports.
109/// skipFrames substrings of stack frames that are the capture's own, skipped when naming a source.
110/// after `(kind, payload)`, run inside the guard after an accepted event.
111/// onFault `(error)`, run when the feed faults, so the app can stop its own timers.
112/// caps overrides for any entry of `CAPS`.
113export function createWriter(cfg) {
114 cfg = cfg || {};
115 const host = cfg.host || {};
116 const caps = Object.assign({}, CAPS, cfg.caps || {});
117 const keys = Object.assign({ outbox: 'lens-outbox', seq: 'lens-seq', postAt: 'lens-lastpost' }, cfg.keys || {});
118 const redactor = cfg.redact || createRedactor();
119 const scrub = cfg.scrub || createScrubber();
120 const storage = host.storage !== undefined ? host.storage : (typeof localStorage !== 'undefined' ? localStorage : null);
121 const setT = host.setTimeout || (typeof setTimeout !== 'undefined' ? setTimeout : null);
122 const clearT = host.clearTimeout || (typeof clearTimeout !== 'undefined' ? clearTimeout : function () {});
123 const now = host.now || Date.now;
124 let doc = host.document !== undefined ? host.document : (typeof document !== 'undefined' ? document : null);
125 const skip = (cfg.skipFrames || []).concat(['writer.js']);
126 const gate = typeof cfg.enabled === 'function' ? cfg.enabled : function () { return true; };
127
128 // ── State ──
129 let outbox = [];
130 let persistTimer = null;
131 let failStreak = 0; // consecutive failed event posts, for the backoff
132 let dropOwed = 0; // events overflowed but not yet reported by feed.drop
133 let dropping = false; // re-entry guard: a feed.drop must not recurse
134 let feedOff = false; // the feed threw; collection is off for this session
135 let draining = false;
136 let errWindowAt = 0, errCount = 0, errDropped = 0;
137 // The console lane: what is held for dedupe, what this window admitted, what it dropped.
138 let conHeld = {};
139 let conWindowAt = 0, conCount = 0, conDropped = 0;
140 let conTimer = null;
141 let inConsole = false, conFlushing = false;
142 // The post clock, and what the sink has said about it.
143 let lastPostAt = ms(read(keys.postAt));
144 let throttleStreak = 0, throttledCount = 0, postFailCount = 0, throttleBurst = false;
145 let pagehideAt = 0;
146
147 // ── Storage, guarded ──
148 function read(k) { try { return storage ? storage.getItem(k) : null; } catch (e) { return null; } }
149 function write(k, v) { try { if (storage) storage.setItem(k, v); } catch (e) { /* a flag nobody misses */ } }
150
151 // A plain positive-millisecond number, or 0. Bignum-safe: a stamp that went through a sink can
152 // arrive as an object with `toNumber`.
153 function ms(v) {
154 const n = (v && typeof v.toNumber === 'function') ? v.toNumber() : Number(v);
155 return (isFinite(n) && n > 0) ? n : 0;
156 }
157
158 // ── Text ──
159
160 // A string clipped to `n` characters. THE SCRUB HAPPENS BEFORE THE CUT: a cut destroys the very
161 // shape the scrubber matches on, so a key beginning at character 190 of a line would otherwise
162 // reach the egress seam as a prefix too short for any rule to know and every reader still can.
163 // ANSI colouring (fe2o3's `err!` wraps a wasm-side error in it) is stripped as noise. A lone half of a
164 // surrogate pair in the text (a message cut by the caller, a truncated read) becomes U+FFFD before the
165 // cut, since JSON would write it as an escape that the peer's strict reader refuses.
166 function clip(s, n) {
167 const v = scrub.text(String(s == null ? '' : s))
168 .replace(/\u001b\[[0-9;]*m/g, '')
169 .replace(/\[[0-9]{1,2}(;[0-9]{1,2})*m/g, '')
170 .replace(/\s+/g, ' ')
171 .trim();
172 return clipChars(soundText(v), n);
173 }
174
175 function device() { try { return String((cfg.device && cfg.device()) || ''); } catch (e) { return ''; } }
176 function build() { try { return String((cfg.build && cfg.build()) || ''); } catch (e) { return ''; } }
177 function shortDevice() { return clip(device(), caps.maxDevChars); }
178 function buildTag() { return clip(build() || '', caps.maxBuildChars); }
179
180 // JSON, or a throw. Deliberately not swallowed: a payload that will not serialise is a fault.
181 function str(o) { return JSON.stringify(o); }
182
183 /// The event's JSON, cut to `maxEventBytes`. The LARGEST string field goes first and only far
184 /// enough to fit, so a short tool name survives a long error message being trimmed; `tr:1` marks
185 /// that something was cut. The envelope is never sacrificed: an event with no payload left still
186 /// says which device, which build and where in the sequence it sits.
187 function fit(obj) {
188 // THE EGRESS SEAM. Nothing reaches the wire as an `ev` row except through here, so a payload
189 // is scrubbed once, at full length, BEFORE the trimming loop below cuts it.
190 obj = scrub.deep(obj);
191 let s = str(obj);
192 const max = caps.maxEventBytes;
193 if (byteLen(s) <= max) return s;
194 const o = {};
195 Object.keys(obj).forEach(function (k) { o[k] = obj[k]; });
196 o.tr = 1;
197 for (let guard = 0; guard < 32; guard++) {
198 s = str(o);
199 const over = byteLen(s) - max;
200 if (over <= 0) return s;
201 let bigK = '', bigN = 0;
202 Object.keys(o).forEach(function (k) {
203 if (ENVELOPE[k] === 1 || k === 'tr') return;
204 // Only strings are candidates, so a capability triple of booleans is never trimmed.
205 if (typeof o[k] !== 'string') return;
206 const n = byteLen(o[k]);
207 if (n > bigN) { bigN = n; bigK = k; }
208 });
209 if (!bigK) break;
210 // Characters, not bytes: a multi-byte string loses at least `over` bytes this way, never
211 // fewer, so the loop always converges. `clipChars` gives up one more unit where the cut
212 // falls inside a pair, which only removes more, and leaves no half to be written as an escape.
213 const keep = o[bigK].length - over - 1;
214 if (keep > 0) o[bigK] = clipChars(o[bigK], keep);
215 else delete o[bigK];
216 }
217 s = str(o);
218 if (byteLen(s) <= max) return s;
219 // Nothing left but the envelope, and it is still worth sending.
220 return str({ v: o.v, d: o.d, n: o.n, b: o.b, t: o.t, tr: 1 });
221 }
222
223 // ── The outbox ──
224
225 // The next sequence number for this device, persisted BEFORE the event is queued. Monotonic
226 // across reloads, so a redelivered post is harmless: the reader keys on `(device, n)`.
227 function nextSeq() {
228 let n = 0;
229 try { n = parseInt(read(keys.seq) || '0', 10) || 0; } catch (e) { n = 0; }
230 n = (n > 0 ? n : 0) + 1;
231 write(keys.seq, String(n));
232 return n;
233 }
234
235 // The outbox as the last session left it. A parse failure yields an empty queue rather than a
236 // throw: a corrupt outbox must not stop the app booting. Only well-formed rows survive.
237 function loadOutbox() {
238 let rows = [];
239 try { rows = JSON.parse(read(keys.outbox) || '[]') || []; } catch (e) { rows = []; }
240 if (!Array.isArray(rows)) return [];
241 return rows.filter(function (r) {
242 return r && typeof r.tag === 'string' && typeof r.data === 'string';
243 }).slice(-caps.outboxCap).map(function (r) {
244 return { ts: ms(r.ts) || now(), tag: r.tag, data: r.data };
245 });
246 }
247 outbox = loadOutbox();
248
249 function persistNow() {
250 try { if (persistTimer) clearT(persistTimer); } catch (e) { /* no timer */ }
251 persistTimer = null;
252 try { if (storage) storage.setItem(keys.outbox, JSON.stringify(outbox)); }
253 catch (e) {
254 // Quota. Half an outbox that persists beats a whole one that does not: the oldest half
255 // goes, the same rule the overflow cap follows, AND IT IS COUNTED, so a reader who sees a
256 // run of missing sequence numbers can tell a full device from a sink losing them.
257 const cut = Math.ceil(outbox.length / 2);
258 try {
259 outbox.splice(0, cut);
260 storage.setItem(keys.outbox, JSON.stringify(outbox));
261 } catch (e2) { /* memory-only from here; the queue still drains */ }
262 if (cut > 0 && !dropping) {
263 dropping = true;
264 try { emit('feed.drop', { count: cut, why: 'quota' }); }
265 catch (e3) { /* a drop that cannot be reported is still a drop */ }
266 finally { dropping = false; }
267 }
268 }
269 }
270
271 // A trailing debounce, so a burst of three hundred events costs one serialisation. What it
272 // loses in the window would have been REDELIVERED, not dropped, since `n` makes a repeat idempotent.
273 function persistSoon() {
274 if (persistTimer) return;
275 try { persistTimer = setT(persistNow, caps.persistMs); }
276 catch (e) { persistNow(); }
277 }
278
279 // Append one finished row and kick the drainer. Overflow drops the OLDEST (a live device's
280 // recent history is what a reader wants) and records the count in one `feed.drop`.
281 function pushRow(tag, data) {
282 outbox.push({ ts: now(), tag: tag, data: data });
283 if (outbox.length > caps.outboxCap) {
284 const cut = outbox.length - caps.outboxCap;
285 outbox.splice(0, cut);
286 dropOwed += cut;
287 if (!dropping) {
288 dropping = true;
289 try { emit('feed.drop', { count: dropOwed }); dropOwed = 0; }
290 finally { dropping = false; }
291 }
292 }
293 persistSoon();
294 if (gate()) drain();
295 }
296
297 // ── Events ──
298
299 // Build, redact, fit and queue one event. The envelope wins over a payload key of the same
300 // name, so a caller cannot overwrite `n` or `t` by accident. Throws on a payload that will not
301 // serialise; only `event` calls this from outside.
302 function emit(kind, payload) {
303 const ev = { v: 1, d: shortDevice(), n: nextSeq(), b: buildTag(), t: now() };
304 const more = cfg.extra ? cfg.extra(kind) : null;
305 if (more && typeof more === 'object') {
306 Object.keys(more).forEach(function (k) { if (ENVELOPE[k] !== 1 && more[k] !== undefined) ev[k] = more[k]; });
307 }
308 if (payload && typeof payload === 'object') {
309 Object.keys(payload).forEach(function (k) {
310 if (ENVELOPE[k] === 1) return;
311 if (payload[k] === undefined) return;
312 ev[k] = payload[k];
313 });
314 }
315 pushRow('ev ' + kind, fit(redactor.value(ev)));
316 return true;
317 }
318
319 /// THE ONE SEAM. A no-op when the gate is shut or the feed has faulted; never throws into its
320 /// caller.
321 function event(kind, payload) {
322 if (!gate() || feedOff || !kind) return false;
323 try {
324 const ok = emit(kind, payload);
325 if (cfg.after) cfg.after(kind, payload);
326 return ok;
327 } catch (e) { fault(e); return false; }
328 }
329
330 // The feed itself threw. One `feed.fault` is queued and collection stops for the session, but
331 // the DRAINER is left running so the fault reaches the sink rather than sitting in a queue
332 // nobody empties. Idempotent: a second fault says nothing, since the first already did.
333 function fault(e) {
334 if (feedOff) return;
335 feedOff = true;
336 try { if (cfg.onFault) cfg.onFault(e); } catch (e2) { /* the hook is not worth a second fault */ }
337 try {
338 const row = {
339 v: 1, d: shortDevice(), n: nextSeq(), b: buildTag(), t: now(),
340 msg: clip((e && e.message) || e || 'feed fault', caps.maxMsgChars),
341 };
342 pushRow('ev feed.fault', fit(redactor.value(row)));
343 } catch (e2) { /* a feed that cannot report its own fault is simply off */ }
344 }
345
346 // ── Errors and the console ──
347
348 // One argument of a console call as a short string. Only primitives and an Error's `message`
349 // are read: the name-based redactor cannot see into a stringified object, so an object is named
350 // and never unpacked.
351 function argWord(a) {
352 try {
353 if (a == null) return String(a);
354 if (typeof a === 'string') return a;
355 if (typeof a === 'number' || typeof a === 'boolean') return String(a);
356 if (a.message) return String(a.message);
357 if (Array.isArray(a)) return '[array:' + a.length + ']';
358 return '[' + ((a.constructor && a.constructor.name) || 'object') + ']';
359 } catch (e) { return '[unreadable]'; }
360 }
361
362 function noteError(msg, where) {
363 if (!gate() || feedOff) return;
364 const t = now();
365 if (t - errWindowAt >= caps.errWindowMs) { errWindowAt = t; errCount = 0; }
366 if (errCount >= caps.errorsPerMin) { errDropped += 1; return; }
367 errCount += 1;
368 const p = { msg: clip(msg, caps.maxMsgChars) };
369 if (where) p.at = clip(where, 80);
370 if (errDropped) { p.dropped = errDropped; errDropped = 0; }
371 event('error', p);
372 }
373
374 // `file:line` for the frame that logged, from a thrown-away stack, only for a line actually
375 // being ADMITTED, so the cost is bounded by `consolePerMin`. Empty where there is no usable stack.
376 function stackSrc() {
377 let st = '';
378 // The host's own `Error` is read at call time, so a host with no usable stack can say so.
379 try { const E = host.Error || Error; st = (new E()).stack || ''; } catch (e) { return ''; }
380 const lines = String(st).split('\n');
381 for (let i = 0; i < lines.length && i < 12; i++) {
382 if (skip.some(function (s) { return lines[i].indexOf(s) !== -1; })) continue;
383 const m = /([A-Za-z0-9_.-]+\.(?:js|mjs)):(\d+)(?::\d+)?/.exec(lines[i]);
384 if (m) return clip(m[1] + ':' + m[2], caps.maxSrcChars);
385 }
386 return '';
387 }
388
389 // Where a console line came from: the stack frame where there is one, else the bracketed
390 // prefix the app puts on its own logs (`[sync]`), the next most useful thing to sort by.
391 function srcOf(args) {
392 const src = stackSrc();
393 if (src) return src;
394 try {
395 const a0 = (args && args.length) ? args[0] : '';
396 if (typeof a0 === 'string') {
397 const m = /^\s*(\[[^\]]{1,40}\])/.exec(a0);
398 if (m) return clip(m[1], caps.maxSrcChars);
399 }
400 } catch (e) { /* an argument that will not be read has no source */ }
401 return '';
402 }
403
404 // Emit every held line whose dedupe window has closed, or all of them when `force` is set (what
405 // a beat and `pagehide` do, so nothing waits in memory for a repeat that never comes). Guarded,
406 // because `event` reaches `drain` and anything down there that logs would re-enter mid-walk.
407 function flushConsole(t, force) {
408 if (typeof t === 'boolean') { force = t; t = 0; }
409 if (conFlushing) return;
410 conFlushing = true;
411 try {
412 t = t || now();
413 const ks = Object.keys(conHeld);
414 for (let i = 0; i < ks.length; i++) {
415 const h = conHeld[ks[i]];
416 if (!force && (t - h.at) < caps.consoleDedupeMs) continue;
417 delete conHeld[ks[i]];
418 const p = { lvl: h.lvl, msg: h.msg };
419 if (h.src) p.src = h.src;
420 if (h.x > 1) p.x = h.x; // the whole window in one row
421 event('console', p);
422 }
423 } finally { conFlushing = false; }
424 }
425
426 function scheduleConsoleFlush() {
427 if (conTimer) return;
428 try {
429 conTimer = setT(function () {
430 conTimer = null;
431 try { flushConsole(now(), true); } catch (e) { fault(e); }
432 }, caps.consoleDedupeMs);
433 } catch (e) { /* no timer: the app's beat and `pagehide` still flush */ }
434 }
435
436 // One console call. A repeat of a held line costs a counter; a new line costs an entry, a stack
437 // sample and one of the window's slots. Over the cap the line is counted into `conDropped`.
438 function noteConsole(lvl, args) {
439 if (!gate() || feedOff) return;
440 const t = now();
441 flushConsole(t);
442 let msg = '';
443 try {
444 const parts = [];
445 for (let i = 0; i < args.length && i < 4; i++) parts.push(argWord(args[i]));
446 msg = clip(parts.join(' '), caps.maxMsgChars);
447 } catch (e) { return; }
448 if (!msg) return;
449 // `clip` has taken the VALUES out by content, which keeps the line readable. These stay
450 // behind it for the cases a content rule cannot reach: a name against a value too short to
451 // have a shape (`api_key: hunter2`), and whatever the caller's string test calls secret.
452 if (looksSecret(msg)) msg = redactor.fingerprint(msg);
453 else {
454 const hit = redactor.text(msg);
455 if (hit) msg = hit;
456 }
457 const key = lvl + '|' + msg;
458 const held = conHeld[key];
459 if (held) { held.x += 1; return; }
460 if (t - conWindowAt >= caps.consoleWindowMs) { conWindowAt = t; conCount = 0; }
461 if (conCount >= caps.consolePerMin) { conDropped += 1; return; }
462 conCount += 1;
463 conHeld[key] = { lvl: lvl, msg: msg, src: srcOf(args), at: t, x: 1 };
464 scheduleConsoleFlush();
465 }
466
467 /// A gateway call that did not answer 2xx, or threw. Path, status and elapsed ms only, NEVER the
468 /// request body. The feed's own posts are not failures: a 429 on our own endpoint is feed
469 /// health, and a `fetch.fail` about it would be the feed describing itself to itself. An
470 /// ABORTED request (a status 0 while the page is going away) is marked rather than dropped.
471 function noteFetchFail(path, status, lapsed, err) {
472 if (!gate() || feedOff) return;
473 const clean = String(path || '').split('?')[0];
474 if (cfg.ownPath && clean === cfg.ownPath) return;
475 const p = { path: clip(clean, 64), status: status | 0, ms: lapsed | 0 };
476 if (err) p.err = clip(err, 120);
477 if (!p.status && unloading()) p.aborted = 1;
478 event('fetch.fail', p);
479 }
480
481 // Is the page on its way out? Hidden, or it said `pagehide` within the grace window.
482 function unloading() {
483 try { if (doc && doc.visibilityState === 'hidden') return true; } catch (e) { /* no document */ }
484 return !!(pagehideAt && (now() - pagehideAt) < caps.unloadGraceMs);
485 }
486
487 /// Wraps every console method on `c`: the original runs first and unconditionally, then the
488 /// line is captured. `error` keeps its `error` event as well as its `console` one: the first is
489 /// the rate-capped fault trail a reader scans first, the second the transcript of what was
490 /// printed. One re-entry guard serves all five levels, since anything below that logs would
491 /// otherwise call straight back in.
492 function captureConsole(c) {
493 c = c || host.console;
494 if (!c) return;
495 LEVELS.forEach(function (lvl) {
496 const orig = c[lvl];
497 if (typeof orig !== 'function' || orig._lens) return;
498 const wrapped = function () {
499 try { orig.apply(c, arguments); } catch (e) { /* the app's own logging comes first */ }
500 if (inConsole) return;
501 inConsole = true;
502 try {
503 noteConsole(lvl, arguments);
504 if (lvl === 'error') {
505 const parts = [];
506 for (let i = 0; i < arguments.length && i < 4; i++) parts.push(argWord(arguments[i]));
507 noteError(parts.join(' '), 'console.error');
508 }
509 } catch (e) { /* never from the app's own logging */ }
510 inConsole = false;
511 };
512 wrapped._lens = true;
513 c[lvl] = wrapped;
514 });
515 }
516
517 /// Hooks an uncaught error and an unhandled rejection on `win`, both inert while the gate is shut.
518 function captureErrors(win) {
519 try {
520 win.addEventListener('error', function (e) {
521 try {
522 let where = '';
523 if (e && e.filename) where = String(e.filename).replace(/^https?:\/\/[^/]+/, '') + ':' + (e.lineno || 0);
524 noteError((e && e.message) || 'error', where);
525 } catch (e2) { fault(e2); }
526 });
527 } catch (e) { /* no window */ }
528 try {
529 win.addEventListener('unhandledrejection', function (e) {
530 try {
531 const r = e && e.reason;
532 noteError((r && r.message) || argWord(r) || 'rejection', 'unhandledrejection');
533 } catch (e2) { fault(e2); }
534 });
535 } catch (e) { /* no window */ }
536 }
537
538 /// The outbox is written on a trailing debounce, so the page going away is the one moment it
539 /// must be written NOW. It is also the moment a request in flight is about to fail for no
540 /// reason, so the time is remembered for `noteFetchFail`. `d` is the document, for visibility.
541 function captureLifecycle(win, d) {
542 if (d !== undefined) doc = d;
543 try {
544 win.addEventListener('pagehide', function () {
545 pagehideAt = now();
546 try { flushConsole(now(), true); } catch (e) { /* best effort */ }
547 try { persistNow(); } catch (e) { /* best effort */ }
548 });
549 win.addEventListener('visibilitychange', function () {
550 try {
551 if (doc && doc.visibilityState !== 'hidden') return;
552 try { flushConsole(now(), true); } catch (e) { /* best effort */ }
553 persistNow();
554 } catch (e) { /* best effort */ }
555 });
556 } catch (e) { /* no window */ }
557 }
558
559 // ── The post clock and the drain ──
560
561 function gapMs() {
562 const wait = caps.gapMs * Math.pow(2, throttleStreak);
563 return wait > caps.backoffMaxMs ? caps.backoffMaxMs : wait;
564 }
565
566 function backoffMs(n) {
567 if (n != null) failStreak = n;
568 const k = failStreak > 0 ? failStreak : 1;
569 const wait = gapMs() * Math.pow(2, k - 1);
570 return wait > caps.backoffMaxMs ? caps.backoffMaxMs : wait;
571 }
572
573 function gapLeft() {
574 if (!lastPostAt) return 0;
575 const left = (lastPostAt + gapMs()) - now();
576 return left > 0 ? left : 0;
577 }
578
579 // One post's worth of events from the FRONT of the outbox, never splitting one, bounded by both
580 // the row cap and the body cap.
581 function eventBatch() {
582 const out = [];
583 let bytes = 0;
584 for (let i = 0; i < outbox.length && out.length < caps.maxRowsPost; i++) {
585 const r = outbox[i];
586 const rowBytes = r.tag.length + r.data.length + 48; // JSON overhead per row
587 if (out.length && (bytes + rowBytes) > caps.maxBodyBytes) break;
588 out.push({ ts: r.ts, tag: r.tag, data: r.data });
589 bytes += rowBytes;
590 }
591 return out;
592 }
593
594 /// The body a sink such as `fe2o3_net::lens::Sink::post` takes: `{ v: 1, device, rows }`.
595 function postBody(rows) {
596 return JSON.stringify({ v: 1, device: device(), rows: rows });
597 }
598
599 // What one post's answer means for the clock: a 429 doubles the gap and is announced once per
600 // burst, any other failure is counted, and a post that landed clears both. The counters do not
601 // overlap, so a beat's `throttled` and `postFail` read as the two separate things they are.
602 function settle(ok, status) {
603 if (ok) {
604 throttleStreak = 0;
605 throttleBurst = false;
606 } else if (status === 429) {
607 throttledCount += 1;
608 throttleStreak += 1;
609 if (!throttleBurst) {
610 throttleBurst = true;
611 try { event('feed.throttled', { n: throttledCount, gap: gapMs() }); }
612 catch (e) { /* the announcement is not worth a fault */ }
613 }
614 } else {
615 postFailCount += 1;
616 }
617 return { ok: ok, status: status };
618 }
619
620 /// Makes one post through the caller's `send`. The promise resolves to `{ ok, status }`: whether
621 /// the post LANDED, which a second lane ignores and the event lane depends on. A thrown send and
622 /// a non-2xx answer are the same thing here, and both mean "still ours".
623 function post(rows) {
624 // Stamped BEFORE the request, not after it: the sink's window starts when the post arrives,
625 // and a slow reply must not buy a second one.
626 lastPostAt = now();
627 write(keys.postAt, String(lastPostAt));
628 let p;
629 try { p = Promise.resolve(cfg.send(rows, { device: device() })); }
630 catch (e) { return Promise.resolve(settle(false, 0)); }
631 return p.then(function (r) {
632 // A send that resolves nothing counts as delivered: the alternative is an outbox that
633 // never empties.
634 if (!r) return settle(true, 0);
635 const status = r.status | 0;
636 if (typeof r.ok === 'boolean') return settle(r.ok, status);
637 return settle(!(status >= 400), status);
638 }, function () { return settle(false, 0); });
639 }
640
641 function pending() {
642 if (!gate()) return false;
643 return outbox.length > 0 || !!(cfg.lane && cfg.lane.pending());
644 }
645
646 /// Drains the outbox one batch every `gapMs`, then the caller's lane, so the sink's rate floor is
647 /// never met. Stops the moment the gate shuts. A drain entered any way but by its own pacing
648 /// timer first asks the post clock what is owed: the old drainer paced itself perfectly while it
649 /// ran and asked nothing when it started again, which is how a boot restore drew a 429.
650 function drain() {
651 if (draining) return;
652 draining = true;
653 step(false);
654
655 function step(paced) {
656 if (!pending()) { draining = false; return; }
657 if (!paced) {
658 const owed = gapLeft();
659 if (owed > 0) { setT(function () { step(true); }, owed); return; }
660 }
661 // EVENTS FIRST, and they are the only DURABLE lane: the rows stay in the outbox until the
662 // post is known to have landed, so an outage costs a retry and not the events that explain
663 // it. The batch is spliced off by LENGTH, never by identity: nothing else removes from the
664 // front.
665 if (outbox.length) {
666 const batch = eventBatch();
667 post(batch).then(function (res) {
668 let wait = gapMs();
669 if (res.ok) {
670 outbox.splice(0, batch.length);
671 failStreak = 0;
672 persistNow();
673 } else {
674 failStreak += 1;
675 wait = backoffMs();
676 }
677 if (!pending()) { draining = false; return; }
678 setT(function () { step(true); }, wait);
679 });
680 return;
681 }
682 const rows = cfg.lane ? cfg.lane.next() : null;
683 if (!rows) { draining = false; return; }
684 post(rows).then(function () {
685 if (!pending()) { draining = false; return; }
686 setT(function () { step(true); }, gapMs());
687 });
688 }
689 }
690
691 /// The gate has shut: nothing more may leave this device, so the outbox and everything held for
692 /// the console are dropped, and the failure counters start again. The post clock is kept.
693 function reset() {
694 outbox = [];
695 failStreak = 0;
696 dropOwed = 0;
697 conHeld = {};
698 conDropped = 0;
699 try { if (conTimer) clearT(conTimer); } catch (e) { /* no timer */ }
700 conTimer = null;
701 persistNow();
702 }
703
704 return {
705 event: event,
706 fault: fault,
707 pushRow: pushRow,
708 post: post,
709 postBody: postBody,
710 drain: drain,
711 reset: reset,
712 persistNow: persistNow,
713 noteError: noteError,
714 noteConsole: function (lvl, args) { noteConsole(lvl, args || []); },
715 flushConsole: flushConsole,
716 noteFetchFail: noteFetchFail,
717 captureConsole: captureConsole,
718 captureErrors: captureErrors,
719 captureLifecycle: captureLifecycle,
720 clip: clip,
721 fit: fit,
722 eventBatch: eventBatch,
723 outbox: function () { return outbox.slice(); },
724 depth: function () { return outbox.length; },
725 ok: function () { return !feedOff; },
726 device: device,
727 gapMs: gapMs,
728 gapLeft: gapLeft,
729 backoffMs: backoffMs,
730 takeConsoleDropped: function () { const n = conDropped; conDropped = 0; return n; },
731 health: function () {
732 return { throttled: throttledCount, postFail: postFailCount, cdrop: conDropped, gap: gapMs(), lastPostAt: lastPostAt };
733 },
734 };
735}