@joystack/cli 0.0.0-stage → 0.1.43

package/lib/replay-list.mjs

@@ -0,0 +1,308 @@
+// `joystack replay list` — what each recorded session is, read off its files
+// without replaying anything: when it was played and for how long, who was in
+// it, which browsers measured it and on what device, and which code recorded
+// it (the engine version, the code fingerprint, and the build id with its
+// commit). These are the facts that decide which session a question is about,
+// and whether an export of it describes the game as it is now.
+//
+// And, for each browser that measured, how it went: how many frames were late
+// and where its worst stutter in play was, read off the performance track by
+// the rules the recorded-session method in the debugging docs defines — so a
+// session can be chosen without exporting every candidate. Why a stutter
+// happened stays a question for the exported tables.
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listRecordings, streamDir } from './replay-store.mjs';
+import { knownHeaderToken } from './replay-export.mjs';
+import { gameBuild } from './build-id.mjs';
+
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+const clean = (v, max = 80) => (typeof v === 'string' ? v.replace(CONTROL, '').slice(0, max) : null);
+const RECORDING_FILE = /^\d{6}\.json$/;
+const TRACK_FILE = /^perf\.([a-z0-9][a-z0-9-]{0,63})\.(\d{6})\.json$/;
+
+// Recording files can be copied in from anywhere, so only a plain file of a
+// size a segment can have is read: a link to a device or a pipe would hang
+// the list, and a huge file would stall it.
+const MAX_FILE_BYTES = 64 * 1024 * 1024;
+const readJson = (file) => {
+  try {
+    const st = lstatSync(file);
+    if (!st.isFile() || st.size > MAX_FILE_BYTES) return null;
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+// The largest time a Date can hold, in milliseconds either side of 1970.
+const MAX_DATE_MS = 8.64e15;
+const isoOf = (ms) => (Number.isFinite(ms) && Math.abs(ms) <= MAX_DATE_MS ? new Date(ms).toISOString() : null);
+const tickOf = (v) => (Number.isSafeInteger(v) ? v : null);
+
+/**
+ * A user agent as the device and browser a person would name: "iPhone, iOS
+ * 18.7, Safari 26.5", "Mac, Chrome 153". Unrecognised text is returned cut
+ * short and without control characters.
+ */
+export function shortDevice(ua) {
+  if (typeof ua !== 'string' || !ua) return null;
+  let device = null;
+  let m;
+  if ((m = /\((iPhone|iPad|iPod)[^)]*?OS (\d+)[_.](\d+)/.exec(ua))) device = `${m[1]}, iOS ${m[2]}.${m[3]}`;
+  else if ((m = /Android (\d+(?:\.\d+)?)/.exec(ua))) device = `Android ${m[1]}`;
+  else if (/Macintosh/.test(ua)) device = 'Mac';
+  else if (/Windows/.test(ua)) device = 'Windows';
+  else if (/Linux|X11/.test(ua)) device = 'Linux';
+  let browser = null;
+  if ((m = /Edg\/(\d+)/.exec(ua))) browser = `Edge ${m[1]}`;
+  else if ((m = /Firefox\/(\d+)/.exec(ua))) browser = `Firefox ${m[1]}`;
+  else if ((m = /(?:Chrome|CriOS)\/(\d+)/.exec(ua))) browser = `Chrome ${m[1]}`;
+  else if ((m = /Version\/(\d+(?:\.\d+)?).*Safari/.exec(ua))) browser = `Safari ${m[1]}`;
+  if (!device && !browser) return clean(ua, 60);
+  return [device, browser].filter(Boolean).join(', ');
+}
+
+// A stutter is late frames less than this far apart, in the measuring
+// browser's milliseconds.
+const STUTTER_GAP_MS = 500;
+// The first seconds after a page loads are always slow — shaders compile, the
+// world spawns — and a player sees that once, as loading. The worst stutter
+// reported is the worst one starting at or past this mark.
+const LOADING_S = 2;
+
+// The screen's refresh interval, read off the frames: the shortest interval
+// the browser drew at repeatedly, taken as the mean of every interval within
+// REFRESH_WINDOW_MS above it. "Repeatedly" is at least REFRESH_SHARE of the
+// frames and never fewer than REFRESH_MIN_FRAMES, so a few stray callbacks
+// close together do not set it, even in a recording of a few dozen frames
+// where one frame in a hundred rounds up to one. The window is
+// what keeps a clock of whole milliseconds (16, 17, 16, …) reading as one
+// refresh. A device that is slow for the whole session still draws its cheap
+// frames on the next refresh, which is why the median frame is not the screen's.
+const REFRESH_WINDOW_MS = 1.5;
+const REFRESH_SHARE = 0.01;
+const REFRESH_MIN_FRAMES = 3;
+function refreshInterval(xs) {
+  const v = xs.filter((x) => Number.isFinite(x) && x > 0).sort((a, b) => a - b);
+  if (!v.length) return null;
+  const need = Math.max(REFRESH_MIN_FRAMES, Math.ceil(v.length * REFRESH_SHARE));
+  let hi = 0;
+  let sum = 0;
+  for (let lo = 0; lo < v.length; lo++) {
+    while (hi < v.length && v[hi] <= v[lo] + REFRESH_WINDOW_MS) sum += v[hi++];
+    if (hi - lo >= need) return sum / (hi - lo);
+    sum -= v[lo];
+  }
+  return null;
+}
+const round = (x, places) => Math.round(x * 10 ** places) / 10 ** places;
+
+/**
+ * Per browser, how many of its frames were late and its worst stutter in
+ * play, from the perf table's frame rows. The rules are the debugging method's:
+ * a frame's work is its phases summed, never `wait_ms`; the budget is the
+ * screen's refresh interval (`refreshInterval`); a frame is late when its work passed the
+ * budget by more than a millisecond or its interval passed one and a half
+ * budgets; late frames less than half a second apart are one stutter, ranked
+ * by how far their frames ran over in all. A frame that ran no tick is placed
+ * at the last tick it had seen.
+ *
+ * @param {object[]} rows - perf table rows
+ * @param {{ startTick?: number, tickRate?: number|null }} clock - the session's
+ *   first tick and tick rate, which turn ticks into seconds of play
+ * @returns {{ conn: string, frames: number, late: number, budgetMs: number|null,
+ *   worstStutter: { fromS: number|null, toS: number|null, tickFrom: number|null, tickTo: number|null,
+ *     frames: number, overMs: number } | null }[]}
+ */
+export function lateFrames(rows, { startTick = 0, tickRate = null } = {}) {
+  const byConn = new Map();
+  for (const r of rows ?? []) {
+    if (r?.row !== 'frame' || typeof r.conn !== 'string' || !Number.isFinite(r.at_ms)) continue;
+    if (!byConn.has(r.conn)) byConn.set(r.conn, []);
+    byConn.get(r.conn).push(r);
+  }
+  const seconds = (tick) => (tick !== null && tickRate > 0 ? round((tick - startTick) / tickRate, 2) : null);
+  const out = [];
+  for (const [conn, frames] of byConn) {
+    frames.sort((a, b) => a.at_ms - b.at_ms);
+    const budget = refreshInterval(frames.map((f) => f.dt));
+    let tick = null;
+    let late = 0;
+    const stutters = [];
+    let cur = null;
+    for (const f of frames) {
+      if (Number.isFinite(f.tick_to)) tick = f.tick_to;
+      if (budget === null) continue;
+      const busy = ['tick_ms', 'present_ms', 'render_ms', 'sim_ms', 'other_ms'].reduce((n, k) => n + (Number.isFinite(f[k]) ? f[k] : 0), 0);
+      const dt = Number.isFinite(f.dt) ? f.dt : 0;
+      if (!(busy > budget + 1 || dt > 1.5 * budget)) continue;
+      late += 1;
+      if (!cur || f.at_ms - cur.lastAt > STUTTER_GAP_MS) {
+        cur = { tickFrom: null, tickTo: null, frames: 0, overMs: 0, lastAt: f.at_ms };
+        stutters.push(cur);
+      }
+      // The lowest and highest tick, as the method's min() and max() read
+      // them: a browser's ticks need not rise frame by frame.
+      if (tick !== null) {
+        cur.tickFrom = cur.tickFrom === null ? tick : Math.min(cur.tickFrom, tick);
+        cur.tickTo = cur.tickTo === null ? tick : Math.max(cur.tickTo, tick);
+      }
+      cur.frames += 1;
+      cur.overMs += Math.max(busy, dt) - budget;
+      cur.lastAt = f.at_ms;
+    }
+    let worst = null;
+    for (const st of stutters) {
+      const fromS = seconds(st.tickFrom);
+      if (fromS === null || fromS < LOADING_S) continue;
+      if (!worst || st.overMs > worst.overMs) worst = st;
+    }
+    out.push({
+      conn, frames: frames.length, late, budgetMs: budget === null ? null : round(budget, 1),
+      worstStutter: worst && {
+        fromS: seconds(worst.tickFrom), toS: seconds(worst.tickTo), tickFrom: worst.tickFrom, tickTo: worst.tickTo,
+        frames: worst.frames, overMs: round(worst.overMs, 1),
+      },
+    });
+  }
+  return out;
+}
+
+// The browsers that wrote a cost track, each described by the header of its
+// earliest segment (every segment of one browser carries the same device).
+function devicesOf(dir, names) {
+  const first = new Map();
+  for (const name of names) {
+    const m = TRACK_FILE.exec(name);
+    if (!m) continue;
+    const [, producer, seq] = m;
+    if (!first.has(producer) || seq < first.get(producer).seq) first.set(producer, { seq, name });
+  }
+  const out = [];
+  for (const [conn, { name }] of first) {
+    const d = readJson(join(dir, name))?.header?.device ?? {};
+    const vw = d.viewport?.width;
+    const vh = d.viewport?.height;
+    out.push({
+      conn,
+      device: shortDevice(d.userAgent),
+      cores: Number.isFinite(d.cores) ? d.cores : null,
+      touch: typeof d.touch === 'boolean' ? d.touch : null,
+      viewport: Number.isFinite(vw) && Number.isFinite(vh) ? `${vw}x${vh}` : null,
+      dpr: Number.isFinite(d.screenDpr) ? d.screenDpr : null,
+      automated: typeof d.automated === 'boolean' ? d.automated : null,
+    });
+  }
+  return out.sort((a, b) => (a.conn < b.conn ? -1 : a.conn > b.conn ? 1 : 0));
+}
+
+// How much of one session's performance track the list reads, in bytes of
+// segment files. A track is written by browsers — in multiplayer, other
+// people's — and can be copied in from anywhere, so the list reads a bounded
+// amount and keeps only the few numbers a late-frame count needs. An hour of
+// play on one device is well inside it; past it, the counts cover the start
+// of the track and say so.
+export const TRACK_BUDGET_BYTES = 128 * 1024 * 1024;
+
+const PHASES = ['tick', 'present', 'render', 'sim', 'other'];
+const finite = (v) => (Number.isFinite(v) ? v : null);
+
+// A session's frames, as the minimal rows `lateFrames` reads, in segment
+// order. Each browser is named by its segment files' names — the name the
+// device list uses — never by what a header inside claims.
+function trackFrames(dir, names, budgetBytes) {
+  const rows = [];
+  const cut = new Set();
+  let spent = 0;
+  // Segment by segment in time, every browser's first segment before any
+  // browser's second, so a budget that runs out cuts every browser at about
+  // the same moment rather than leaving the last one unread.
+  const files = names.map((n) => TRACK_FILE.exec(n)).filter(Boolean)
+    .sort((a, b) => (a[2] === b[2] ? (a[1] < b[1] ? -1 : 1) : a[2] < b[2] ? -1 : 1));
+  for (const [name, conn] of files) {
+    let size = 0;
+    try { size = lstatSync(join(dir, name)).size; } catch { continue; }
+    if (cut.size || spent + size > budgetBytes) {
+      // Past the budget nothing more is read, so every browser with a
+      // segment left is counted in part.
+      cut.add(conn);
+      continue;
+    }
+    spent += size;
+    const seg = readJson(join(dir, name));
+    for (const f of Array.isArray(seg?.frames) ? seg.frames : []) {
+      if (!f || typeof f !== 'object') continue;
+      const row = { row: 'frame', conn, at_ms: finite(f.at), dt: finite(f.dt),
+        tick_to: Array.isArray(f.ticks) && f.ticks.length === 2 ? finite(f.ticks[1]) : null };
+      for (const p of PHASES) row[`${p}_ms`] = finite(f[p]);
+      rows.push(row);
+    }
+  }
+  return { rows, cut };
+}
+
+// Who was in the room: named in a segment's header, or joined during it.
+function playersOf(dir, names) {
+  const conns = new Set();
+  let header = null;
+  for (const name of names.filter((n) => RECORDING_FILE.test(n)).sort()) {
+    const seg = readJson(join(dir, name));
+    if (!seg) continue;
+    header ??= seg.header ?? null;
+    const participants = seg.header?.participants;
+    if (participants && typeof participants === 'object') for (const key of Object.keys(participants)) conns.add(key);
+    for (const e of Array.isArray(seg.events) ? seg.events : []) {
+      if (e?.k === 'jn' && typeof e.connId === 'string') conns.add(e.connId);
+    }
+  }
+  return { players: conns.size, header };
+}
+
+/**
+ * Every recorded session in a game folder, newest first.
+ * @param {string} dir - the game folder
+ * @param {{ trackBudgetBytes?: number }} [opts] - how much of each session's
+ *   performance track to read
+ */
+export function listSessions(dir, { trackBudgetBytes = TRACK_BUDGET_BYTES } = {}) {
+  const recordings = listRecordings(dir);
+  if (!recordings.length) return [];
+  let current = null;
+  try { current = gameBuild(dir, { git: false }).id; } catch { /* not a folder of game files */ }
+  return recordings.map((r) => {
+    const sdir = streamDir(dir, r.stream);
+    let names = [];
+    try { names = readdirSync(sdir); } catch { /* removed while listing */ }
+    const { players, header } = playersOf(sdir, names);
+    const clock = { startTick: tickOf(r.startTick) ?? 0, tickRate: Number.isFinite(r.tickRate) ? r.tickRate : null };
+    const measured = devicesOf(sdir, names);
+    const track = measured.length ? trackFrames(sdir, names, trackBudgetBytes) : { rows: [], cut: new Set() };
+    const went = new Map(lateFrames(track.rows, clock).map((x) => [x.conn, x]));
+    const devices = measured.map((d) => {
+      const { conn: _, ...how } = went.get(d.conn) ?? { frames: 0, late: 0, budgetMs: null, worstStutter: null };
+      // True when the track went past what the list reads: the counts are of its start.
+      return { ...d, ...how, partial: track.cut.has(d.conn) };
+    });
+    const build = r.build?.id ?? null;
+    return {
+      stream: r.stream,
+      startedAt: isoOf(r.startedAt),
+      seconds: Number.isFinite(r.durationMs) ? Math.round(r.durationMs / 100) / 10 : null,
+      ticks: tickOf(r.startTick) != null && tickOf(r.endTick) != null ? [r.startTick, r.endTick] : null,
+      players,
+      measured: devices.length > 0,
+      devices,
+      watchable: r.watchable,
+      // A room served by `joystack dev` carries a placeholder where a published
+      // one carries its engine version; the dev server's stamp names it.
+      engine: knownHeaderToken(header?.engineVersion) ?? r.build?.engine ?? null,
+      code: knownHeaderToken(header?.codeFingerprint),
+      build,
+      commit: r.build?.git?.commit ?? null,
+      uncommitted: r.build?.git?.dirty ?? null,
+      buildIsCurrent: build && current ? build === current : null,
+      kept: r.kept,
+    };
+  });
+}