// 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: .`); 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/.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 ms = (v) => num(v) && v >= 0; 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; }) }, // ms: the worker's time for the call (mark, realm, update), not the wait behind other calls: the rate limit's measure. 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'], ms: [ms, 'opt'] }, // Neither modal nor err: the what-if opened nothing (a link that is gone, say); the page shows nothing new. 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'], ms: [ms, 'opt'] }, pulled: { t: str, nid: (v) => PID.test(v), epoch, v: nat, upd: [json('upd'), 'opt'], snap: [snapPart, 'opt'], subs: [subs, 'opt'], ms: [ms, '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 };