seriesoftubes/tests/lib/mp-sim-shape.js
jvanvik d1e127da67 Server-run play, part 1: game prerequisites and shared contracts
Groundwork for running multiplayer games on the session server; nothing
of it is switched on yet, and the plain build is unchanged.

- A new network in two halves (beginState/beginShow), the coach split into
  tutAdvance/coachDom, toastPop split out of toast, bootNotes() for the
  once-per-load toasts, the five text actions take their text as an
  argument, and srvOn() with its two checks in the loop.
- Live state is what a reload makes of it (migrate() is a no-op on it):
  new POPs, ports, PNIs, customers, attacks, dark fiber and the intern's
  notes are written in their saved shape; a 365-day test proves it.
- pniAll and bstdApply check the quote the sheet showed (bstdApply by its
  plan, within 1% for the daily hardware drift; utilityKit too).
- assemble({mp}) leaves src/game/98-server-play/ and its CSS out of every
  page but a multiplayer build's, which also gets a SIM_ID build id.
- Contracts for the server, protocol and browser parts: the action tables
  and envelope check (scripts/lib/mp-sim-acts.js), event fixtures, a shape
  checker, a fake engine, and load({mp:true}) in the test harness.
- route-fuzz judges both pages with one migrate(), so reload repairs of
  the base no longer count as divergences.
2026-11-07 10:26:06 +01:00

183 lines
14 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': case 'haptic': if (!str(p)) 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)) };
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, { t: str, epoch: (v) => EPOCH.test(v), v: nat, now: nat, S: liveS, r: slimR,
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; },
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; } }, 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; };
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: [json('snap'), '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'); } 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 };