seriesoftubes/tests/lib/mp-sim-shape.js
jvanvik 065c922287 Server-run play, part 2: the engine
The engine that runs every network of a server session (server-sim design,
section 4): each network in its own vm realm, realms in a small pool of
worker threads, a promise API for the session host. Nothing uses it yet;
the plain build and the game are unchanged (no file under src/).

- scripts/lib/mp-sim-realm.js: one network in a DONT_CONTEXTIFY realm
  running the plain page's game (never the MP page's client folder), with
  recording DOM stand-ins, no-op timers that count, and the srv... calls:
  load from a checkpoint (route memory seeded, then routed), begin a new
  network, marks and restores, the day as a page runs it, the action
  pipeline with drafts, arming, the sanitize gate and rollback, what-ifs
  that put S, R, the dice and uidN back, pulls with top-level key diffs,
  slim R and flow records on demand, fx captured and bounded, saves, cards.
- scripts/lib/mp-sim-worker.js: realms per session in one worker, days one
  network at a time with other messages between them, loads and unloads
  waiting for a session's day, time limits; a throw goes back to the mark
  in place, a timeout gets a fresh realm (new epoch) carrying the old R, a
  day is retried once and the network broken after a second failure.
- scripts/lib/mp-sim-engine.js: createEngine() with the fake engine's API,
  placement by realm count, every pending call rejected when its worker
  exits, a worker of its own after two exits in an hour; snapWith() joins
  the host's clock, roster and since to a realm's snapshot.
- Contract: a pulled snapshot is the realm's half (the host adds clock,
  roster, since); haptic fx carry milliseconds; the fake engine follows,
  with close() and snapWith(). The button crawl moved to tests/lib.
- Tests: realm vs jsdom byte for byte over 60 scenic big-network days with
  actions; restore; retry after a throw or a timeout; realm order; a timer
  audit and the gate over a sweep of sent buttons (SIM_LONG=1: a year and
  every button); captures, rollbacks, asks, selection reports, ordering,
  bounds, pollution, worker exits; the act tables against the game.

The gate found two keys the game writes in a shape a reload repairs (buyTE's
S.te, mkLeave's S.monkey): game fixes for the integrator, kept visible as a
todo test and a list in the audit.

Rebased onto the 3.3.0 merge (61e31c5): the engine itself needed no change. A
realm still routes in the game's own code (no route worker, no saves), the
route cache that now keeps list orders from day to day leaves a checkpoint and a
retry the same, and the capacity market and moved customers play in a realm as
on a page, under the strict gate. The tests needed three things: an old save's
first days earn the new traffic badges, which the unwatched network's snapshot
keeps; the restore test compares JSON text with sorted keys instead of a
deep-equal of two networks (a diff of gigabytes when they differ); and the crawl
opens the windows that move a customer, with a new test playing the market's and
the path moves' acts, 40 days of sales and a checkpoint against the page.
2026-11-09 19:30:38 +01:00

191 lines
15 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// The shapes of server-run play on the wire and between host and worker (the server-sim design, sections 4.2 and 5.3),
// checked: the session server's real output (its tests run every event they write through checkEvent) and the canned
// streams in tests/fixtures/mp-sim/ (the client's tests) must agree on them.
//
// checkEvent(e) problems with one stream event ([] when fine): snap, upd, sub, clock, roster, bye
// checkFx(f) problems with one effect entry, [kind, payload]
// checkWorker(m) problems with one worker → host reply: loaded, dayDone, actDone, askDone, pulled, subbed, saved,
// card, unloaded, err
//
// The epoch (5.10): the worker mints a new one at every realm load (a load, a begin, and the fresh realm it builds
// after a timeout, 4.2) and puts the realm's current one on every reply that carries versions: loaded, pulled, actDone,
// subbed. The host keeps the last one per network and writes it into every event's id (`id: <epoch>.<v>`); a reply with
// another epoch than the host holds means the realm was built again, so v started over and every page takes a snapshot.
// A network that did not load (loaded.err: its save failed, 4.7) has no realm, so no epoch, day or lost.
// A toast effect's k and a may be left out (toastPop's defaults: '' and []): a game call toast(html) has neither.
// parseSse(text) the events of an event-stream text: [{event, id, data (parsed)}], comments and heartbeats skipped
// fixture(name) tests/fixtures/mp-sim/<name>.json, parsed
'use strict';
const fs = require('node:fs');
const path = require('node:path');
const SPEEDS = [0, 0.5, 1, 2, 4, 8];
const PID = /^[a-z0-9]{8}$/, RID = /^[a-z0-9]{8,16}$/, EPOCH = /^[a-z0-9]{1,16}$/, CODE = /^[0-9A-HJKMNP-TV-Z]{6}$/;
// What slim R never carries (5.5): compute inputs, internals, and what goes on demand in sub events.
const R_NEVER = ['ef', 'fl', 'efp', 'flc', 'efg', 'egDesc', 'l2route', 'bbF', 'peered', 'cityBlocked'];
const FX_KINDS = ['toast', 'sfx', 'haptic', 'floater', 'track', 'pause', 'modal', 'badge', 'mk', 'told'];
const WHY = [null, 'empty', 'hold', 'slow', 'loading', 'vote'];
const BYE = ['gone', 'old', 'moved', 'slow', 'shutdown'];
const OUTCOMES = ['applied', 'no_effect', 'rejected', 'error', 'stopped'];
const UI_KEYS = ['sel', 'tab', 'left', 'confirm', 'closed', 'modal'];
const obj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
const int = (v) => Number.isInteger(v);
const nat = (v) => Number.isInteger(v) && v >= 0;
const num = (v) => typeof v === 'number' && Number.isFinite(v);
const str = (v) => typeof v === 'string';
const bool = (v) => typeof v === 'boolean';
// fields: {name: test | [test, 'opt']}; extra keys are problems too (a typo on one side is caught by the other).
function fields(o, spec, where, out, open = false) {
if (!obj(o)) { out.push(`${where}: not an object`); return; }
for (const [k, t] of Object.entries(spec)) {
const [f, opt] = Array.isArray(t) ? t : [t];
if (!(k in o) || o[k] === undefined) { if (!opt) out.push(`${where}.${k}: missing`); continue; }
const r = f(o[k], `${where}.${k}`, out);
if (r === false) out.push(`${where}.${k}: bad value ${JSON.stringify(o[k]).slice(0, 80)}`);
}
if (!open) for (const k of Object.keys(o)) if (!(k in spec)) out.push(`${where}.${k}: unknown field`);
}
const listOf = (t) => (v, w, out) => { if (!Array.isArray(v)) return false; v.forEach((x, i) => { if (t(x, `${w}[${i}]`, out) === false) out.push(`${w}[${i}]: bad value ${JSON.stringify(x).slice(0, 60)}`); }); return true; };
const mapOf = (kt, vt) => (v, w, out) => { if (!obj(v)) return false; for (const [k, x] of Object.entries(v)) { if (!kt(k)) out.push(`${w}: bad key ${k}`); if (vt(x, `${w}.${k}`, out) === false) out.push(`${w}.${k}: bad value ${JSON.stringify(x).slice(0, 60)}`); } return true; };
// Live S, as the server's realm holds it: what every page reads first (the full check is the game's own migrate()).
function liveS(S, w, out) {
if (!obj(S)) return false;
if (S.v !== 1 || !nat(S.day) || !num(S.cash) || !obj(S.pops) || !Array.isArray(S.links) || !Array.isArray(S.biz) || !obj(S.stats)) out.push(`${w}: not a game state (v, day, cash, pops, links, biz, stats)`);
if (!obj(S.mp) || !CODE.test(S.mp.code) || !PID.test(S.mp.pid) || S.mp.sim !== 1) out.push(`${w}.mp: not a server network (code, pid, sim:1)`);
if (S.mode !== 'normal') out.push(`${w}.mode: server networks are Normal games`);
return true;
}
function slimR(r, w, out) {
if (!obj(r)) return false;
for (const k of R_NEVER) if (k in r) out.push(`${w}.${k}: slim R never carries it`);
for (const k of ['served', 'demand', 'reach', 'revMo', 'costMo']) if (!num(r[k])) out.push(`${w}.${k}: missing or not a number`);
for (const k of ['load', 'useT', 'tNet', 'cityDem', 'citySrv']) if (!obj(r[k])) out.push(`${w}.${k}: missing`);
if (!Array.isArray(r.ddos)) out.push(`${w}.ddos: missing`);
else r.ddos.forEach((m, i) => { if (m.attack !== null && !str(m.attack)) out.push(`${w}.ddos[${i}].attack: an attack's id (or null)`); });
if (!Array.isArray(r.tTop8) || r.tTop8.length > 8 || !r.tTop8.every((x) => Array.isArray(x) && x.length === 2 && str(x[0]) && num(x[1]))) out.push(`${w}.tTop8: [[net, gbps]] × ≤ 8`);
if (obj(r.tNet)) for (const [id, m] of Object.entries(r.tNet)) if (!obj(m) || Object.keys(m).length > 4) out.push(`${w}.tNet.${id}: at most the top 4 networks`);
return true;
}
const sel = (v) => v === null || (obj(v) && (v.type === 'city' || v.type === 'link') && str(v.id) && Object.keys(v).length === 2);
function actUi(u, w, out) {
fields(u, { sel: [sel, 'opt'], tab: [(v) => v === null || str(v), 'opt'], left: [(v) => v === null || str(v), 'opt'], confirm: [(v) => v === null || str(v), 'opt'],
closed: [(v) => v === 1 || v === true, 'opt'], modal: [(v) => obj(v) && str(v.h) && str(v.c) && Object.keys(v).length === 2, 'opt'] }, w, out);
return true;
}
const actEntry = (a, w, out) => { fields(a, { rid: (v) => RID.test(v), dev: (v) => RID.test(v), ui: actUi }, w, out); return true; };
function checkFx(f, w = 'fx', out = []) {
if (!Array.isArray(f) || f.length !== 2 || !str(f[0])) { out.push(`${w}: an effect is [kind, payload]`); return out; }
const [k, p] = f;
const bad = () => out.push(`${w}: bad ${k} payload ${JSON.stringify(p).slice(0, 80)}`);
switch (k) {
case 'toast': fields(p, { h: str, k: [str, 'opt'], a: [listOf((x) => obj(x) && str(x.l) && str(x.act)), 'opt'], o: [(v) => v === null || obj(v), 'opt'], tick: [bool, 'opt'] }, `${w}.toast`, out); break;
case 'sfx': if (!str(p)) bad(); break;
// The game's haptic(ms) takes how long to buzz.
case 'haptic': if (!(num(p) && p >= 0)) bad(); break;
case 'floater': if (!Array.isArray(p) || p.length !== 4 || !num(p[0]) || !num(p[1]) || !str(p[2]) || !str(p[3])) bad(); break;
case 'track': if (!Array.isArray(p) || p.length !== 2 || !str(p[0]) || !(p[1] === undefined || p[1] === null || bool(p[1]))) bad(); break;
case 'pause': if (p !== 1) bad(); break;
case 'modal': if (!['win', 'lose', 'baron'].includes(p)) bad(); break;
case 'badge': if (!obj(p) || !str(p.id) || !(p.v === undefined || str(p.v))) bad(); break;
case 'mk': if (!obj(p) || !str(p.e)) bad(); break;
case 'told': break;
default: out.push(`${w}: unknown effect ${k}`);
}
return out;
}
const fxList = (v, w, out) => { if (!Array.isArray(v)) return false; v.forEach((f, i) => checkFx(f, `${w}[${i}]`, out)); return true; };
const CLOCK = { t: (v) => v === 'clock', speed: (v) => SPEEDS.includes(v), eff: (v) => num(v) && v >= 0, run: bool, why: (v) => WHY.includes(v),
votes: mapOf((k) => PID.test(k), (v) => v === null || SPEEDS.includes(v)), tally: mapOf((k) => SPEEDS.includes(+k), nat), need: (v) => int(v) && v >= 1,
active: listOf((v) => PID.test(v)), hold: listOf((v) => PID.test(v)), idle: listOf((v) => PID.test(v)), day: nat, last: (v) => SPEEDS.includes(v) && v > 0,
max: (v) => SPEEDS.includes(v) && v > 0,
// The calendar offset of every network of the session: its own S.day minus the session day (open question 1: "own
// date"). One field, so a shared date later only means all zeros.
off: mapOf((k) => PID.test(k), int) };
const PLAYER = { pid: (v) => PID.test(v), name: str, asn: nat, color: (v) => /^#[0-9a-f]{6}$/i.test(v), card: (v) => v === null || obj(v), seen: nat, joined: nat,
lost: [bool, 'opt'], broken: [bool, 'opt'] };
const ROSTER = { t: (v) => v === 'roster', code: (v) => CODE.test(v), title: str, preset: str, seed: int, created: nat,
players: listOf((p, w, out) => { fields(p, PLAYER, w, out); return true; }),
feed: listOf((f, w, out) => { fields(f, { k: str, pid: str, name: str, at: nat, text: [str, 'opt'] }, w, out); return true; }),
on: listOf((v) => PID.test(v)) };
/* A snapshot is made in two halves: the realm's (the network: S, r, keep, at its epoch and version) and the host's
(clock, roster, since: the session and this stream). A worker's pulled.snap is the realm's half as text; the engine's
snapWith() joins the host's to it (scripts/lib/mp-sim-engine.js). */
const SNAP_REALM = { t: str, epoch: (v) => EPOCH.test(v), v: nat, now: nat, S: liveS, r: slimR,
keep: (v, ww, o) => { if (!Array.isArray(v) || v.length > 32) return false; v.forEach((f, i) => { checkFx(f, `${ww}[${i}]`, o); if (f[0] !== 'badge' && f[0] !== 'modal') o.push(`${ww}[${i}]: keep holds only badge and modal`); }); return true; } };
const SNAP_HOST = { clock: (v, ww, o) => { fields(v, CLOCK, ww, o); return true; }, roster: (v, ww, o) => { fields(v, ROSTER, ww, o); return true; },
since: (v, ww, o) => { fields(v, { days: nat, again: nat }, ww, o); return true; } };
function checkEvent(e) {
const out = [];
if (!obj(e) || !str(e.t)) return ['an event is an object with t'];
const w = e.t;
if (e.t === 'snap') fields(e, { ...SNAP_REALM, ...SNAP_HOST }, w, out);
else if (e.t === 'upd') {
fields(e, { t: str, from: nat, v: nat, now: nat, day: nat, s: obj, del: [listOf(str), 'opt'], r: [slimR, 'opt'], fx: [fxList, 'opt'], acts: [listOf(actEntry), 'opt'] }, w, out);
if (nat(e.v) && nat(e.from) && e.v !== e.from + 1) out.push('upd: v is from + 1 (only a pull makes a version)');
if (obj(e.s) && Array.isArray(e.del)) for (const k of e.del) if (k in e.s) out.push(`upd: ${k} both changed and deleted`);
if (obj(e.s) && 'day' in e.s && e.s.day !== e.day) out.push('upd: day differs from s.day');
if (Array.isArray(e.fx) && e.fx.length > 60) out.push('upd: more than 60 effects');
} else if (e.t === 'sub') fields(e, { t: str, v: nat, ef: [obj, 'opt'], egd: [obj, 'opt'], pf: [obj, 'opt'] }, w, out);
else if (e.t === 'clock') fields(e, CLOCK, w, out);
else if (e.t === 'roster') fields(e, ROSTER, w, out);
else if (e.t === 'bye') fields(e, { t: str, why: (v) => BYE.includes(v) }, w, out);
else out.push(`unknown event ${e.t}`);
return out;
}
// Worker → host replies (4.2). Big payloads (an update, a snapshot) are JSON text, ready to write to every stream.
const json = (t) => (v, w, out) => { if (!str(v)) return false; let e; try { e = JSON.parse(v); } catch (x) { return false; } for (const p of checkEvent(e)) out.push(`${w}: ${p}`); if (e.t !== t) out.push(`${w}: not a ${t}`); return true; };
// The realm's half of a snapshot (above): the host's three fields come later, so here they are unknown.
const snapPart = (v, w, out) => { if (!str(v)) return false; let e; try { e = JSON.parse(v); } catch (x) { return false; } if (!obj(e) || e.t !== 'snap') { out.push(`${w}: not a snap`); return true; } fields(e, SNAP_REALM, w, out); return true; };
const subs = mapOf((k) => /^(link|peer):.{1,40}$/.test(k), (v) => obj(v));
const epoch = (v) => EPOCH.test(v);
const WORKER = {
// epoch, day and lost: required unless err says the network did not load (checkWorker).
loaded: { t: str, nid: (v) => PID.test(v), epoch: [epoch, 'opt'], day: [nat, 'opt'], lost: [bool, 'opt'], err: [str, 'opt'], saved: [(v, w, out) => { for (const p of checkWorker(v)) out.push(`${w}: ${p}`); return true; }, 'opt'] },
// A day that failed twice: err, retried, and day as it was before (the network is broken at its pre-day state, 4.3).
dayDone: { t: str, code: (v) => CODE.test(v), d: nat, nets: mapOf((k) => PID.test(k), (v, w, out) => { fields(v, { day: nat, lost: bool, pause: [bool, 'opt'], err: [str, 'opt'], retried: [bool, 'opt'], ms: (x) => num(x) && x >= 0 }, w, out); return true; }) },
actDone: { t: str, nid: (v) => PID.test(v), epoch, rid: (v) => RID.test(v), outcome: (v) => OUTCOMES.includes(v), why: [str, 'opt'], v: nat, upd: [(v, w, out) => v === null || json('upd')(v, w, out), 'opt'] },
askDone: { t: str, nid: (v) => PID.test(v), rid: (v) => RID.test(v), modal: [(v) => obj(v) && str(v.h) && str(v.c), 'opt'], ui: [obj, 'opt'], err: [str, 'opt'] },
pulled: { t: str, nid: (v) => PID.test(v), epoch, v: nat, upd: [json('upd'), 'opt'], snap: [snapPart, 'opt'], subs: [subs, 'opt'] },
subbed: { t: str, nid: (v) => PID.test(v), epoch, v: nat, subs },
saved: { t: str, nid: (v) => PID.test(v), txt: str, uidN: nat, rt: obj, day: nat, lost: bool },
card: { t: str, nid: (v) => PID.test(v), card: (v) => v === null || obj(v) },
unloaded: { t: str, code: (v) => CODE.test(v), nid: [(v) => PID.test(v), 'opt'] },
err: { t: str, code: (v) => CODE.test(v), nid: (v) => PID.test(v), rid: [(v) => RID.test(v), 'opt'], what: (v) => ['timeout', 'throw', 'oom', 'exit', 'load'].includes(v), msg: str },
};
function checkWorker(m) {
const out = [];
if (!obj(m) || !str(m.t) || !WORKER[m.t]) return [`unknown worker reply ${obj(m) ? m.t : typeof m}`];
fields(m, WORKER[m.t], m.t, out);
if (m.t === 'loaded' && m.err === undefined) for (const k of ['epoch', 'day', 'lost']) if (m[k] === undefined) out.push(`loaded.${k}: missing`);
if (m.t === 'loaded' && m.err !== undefined && m.saved !== undefined) out.push('loaded: a network that did not load has nothing saved');
if (m.t === 'pulled' && m.snap !== undefined && str(m.snap)) { try { const e = JSON.parse(m.snap); if (e.epoch !== m.epoch) out.push('pulled: the snapshot\'s epoch is not the realm\'s'); if (e.v !== m.v) out.push('pulled: the snapshot is not at the version pulled'); } catch (x) { /* reported above */ } }
return out;
}
function parseSse(text) {
const out = [];
for (const block of String(text).split('\n\n')) {
if (!block.trim()) continue;
let event = 'message', id, data = '';
for (const line of block.split('\n')) {
if (!line || line.startsWith(':')) continue;
const i = line.indexOf(':'), k = i < 0 ? line : line.slice(0, i), v = i < 0 ? '' : line.slice(i + 1).replace(/^ /, '');
if (k === 'event') event = v; else if (k === 'id') id = v; else if (k === 'data') data += (data ? '\n' : '') + v;
}
if (data) out.push({ event, id, data: JSON.parse(data) });
}
return out;
}
const DIR = path.join(__dirname, '..', 'fixtures', 'mp-sim');
const fixture = (name) => JSON.parse(fs.readFileSync(path.join(DIR, name + '.json'), 'utf8'));
const FIXTURES = ['snap', 'upd-day', 'upd-act', 'sub', 'clock', 'roster'];
module.exports = { checkEvent, checkFx, checkWorker, parseSse, fixture, FIXTURES, FX_KINDS, R_NEVER, SPEEDS };