@homie-rocks/studio 0.46.0 → 0.46.3

package/guides/game/SKILL.md

@@ -243,6 +243,11 @@ world or inventory, use Lasting worlds above. Ordinary match rooms expire after
   handle. Draw the character's name over its body and in the ranking (a declared command requests it; rules validate and keep it in the player entity), except on a kids server, where the others stay handles. Ember Vale does it.
 - Show who is playing (`saves.player.name`, guest or signed in) and a small "Keep my progress" button that calls
   `saves.signIn()`; the play page shows its passkey sheet. Pressing Play never needs an account.
+- A guest who signs in to an account that already has the same key: say how the two combine, once, in
+  `site/src/worker.mjs`: `mergeSaves({ '<id>': { saves: { coins: 'sum', 'best-level': 'larger', settings: 'newer' },
+  stats: { kills: 'sum' } } })` from `@homie-rocks/studio/worker` (or a function for an inventory). Server records
+  are joined without a rule; any other key with no rule reaches the game's `onConflict` (SAVES.md, "When a guest
+  signs in to their account").
 - Prove it: build, `npm run dev`, open `http://localhost:8787/<id>/play` (passkeys need `localhost`, not
   `127.0.0.1`), play, reload: the progress is still there. The whole guide is
   `node_modules/@homie-rocks/studio/saves/SAVES.md` (the limits, offline and conflicts, what is stored, privacy).

package/lib/build-identity.mjs

@@ -0,0 +1,43 @@
+/** Content identity of the runtime, independent of a studio's package pin or git commit. */
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+const root = fileURLToPath(new URL('../', import.meta.url));
+export function runtimeIdentity() {
+  const hash = createHash('sha256');
+  function walk(dir) {
+    for (const entry of readdirSync(join(root, dir), {
+      withFileTypes: true
+    }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const path = dir + '/' + entry.name;
+      if (entry.isDirectory()) walk(path);
+      else if (/\.(mjs|ts|json)$/.test(path) && path !== 'worker/build-id.mjs')
+        hash
+          .update(path + '\0')
+          .update(readFileSync(join(root, path)))
+          .update('\0');
+    }
+  }
+  for (const dir of ['worker', 'rules', 'netplay']) walk(dir);
+  return {
+    version: JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+      .version,
+    sha256: hash.digest('hex')
+  };
+}
+export function stampRuntime(check = false) {
+  const text =
+      '// Generated by lib/build-identity.mjs; identifies the bundled runtime sources.\nexport const STUDIO_BUILD = Object.freeze(' +
+      JSON.stringify(runtimeIdentity()) +
+      ');\n',
+    path = join(root, 'worker/build-id.mjs');
+  if (check) {
+    if (readFileSync(path, 'utf8') !== text)
+      throw Error(
+        'Runtime identity is stale: node packages/studio/lib/build-identity.mjs --write'
+      );
+  } else writeFileSync(path, text);
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+  stampRuntime(process.argv.includes('--check'));

package/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import { roomLayout } from '../worker/gate.mjs';
 import {workerEntry} from './worker-build.mjs';
 import { seatCount } from '../worker/seats.mjs';
 import { refreshWorkerConfig } from './worker-config.mjs';
@@ -175,9 +176,12 @@ export async function zonePlan(root, opts = {}) {
  */
 export function hostedUse({ seats = 8, inputHz = 20 } = {}) {
   const requests = Math.round((seats * (inputHz * 3600 + 1800)) / 20);
-  const gbSeconds = 0.128 * 3600;
+  const layout = roomLayout(seats);
+  // A room behind Gates: the room, its Gates, and the object that keeps its diagnostics.
+  const objects = 1 + (layout.gates > 1 ? layout.gates + 1 : 0);
+  const gbSeconds = 0.128 * 3600 * objects;
   const pct = (n, of) => (n / of < 0.001 ? 'under 0.1%' : `${Math.round((n / of) * 1000) / 10}%`);
-  return { seats, requests, gbSeconds, rows: 12, share: { requests: pct(requests, 100_000), gbSeconds: pct(gbSeconds, 13_000), rows: pct(12, 100_000) } };
+  return { seats, requests, gbSeconds, objects, layout, requestBasis: 'player input and ping only; relay frames, receipts, HTTP, saves and Lobby are additional', rows: 12, share: { requests: pct(requests, 100_000), gbSeconds: pct(gbSeconds, 13_000), rows: pct(12, 100_000) } };
 }
 
 /** What `deploy` will create and what it costs, from studio.json alone. It calls nothing. */
@@ -197,18 +201,16 @@ export function deployPlan(root) {
   return {
     ok: true, command: 'deploy plan', studio: studio.name, account: cf.accountId ?? null,
     cloudflare: [
-      { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`), plan: 'Workers Free' },
-      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
-      { kind: 'Durable Object', name: 'Table', what: hosted.length ? `one per public room: the netplay relay (seats, snapshots), and for ${hosted.map((h) => h.id).join(', ')} the game's own rules, which run here and nowhere else` : 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
-      ...hosted.map((h) => ({ kind: 'Game rules', name: h.id, what: `the rules of ${h.name} run on Cloudflare, in each room's Table, not in a player's browser. An hour of play in one full room (${h.seats} players) uses about ${h.share.requests} of the free plan's 100,000 requests a day, ${h.share.gbSeconds} of its 13,000 GB-seconds of running time and ${h.share.rows} of its 100,000 rows written. A room with nobody in it uses nothing. Out of requests, every room of every game stops until 00:00 UTC; the Workers Paid plan removes the three allowances`, state: 'in the Worker', plan: 'Workers Free' })),
-      { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
+      { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`) },
+      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`) },
+      { kind: 'Durable Object', name: 'Table', what: hosted.length ? `one per public room: the netplay relay (seats, snapshots), and for ${hosted.map((h) => h.id).join(', ')} the game's own rules, which run here and nowhere else` : 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker' },
+      ...hosted.map((h) => ({ kind: 'Game rules', name: h.id, what: `One full ${h.seats}-player room activates ${h.objects} objects (${h.layout.gates > 1 ? `${h.layout.gates} Gates, the room and its diagnostics` : 'the room'}): approximately ${h.gbSeconds} GB-seconds/hour before Lobby activity. Player input/ping alone contributes ${h.requests} request units/hour; relay frames and receipts, HTTP and storage are additional. Occupancy, batching and account usage determine the bill.`, state: 'in the Worker' })),
+      { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker' },
       storage
         ? { kind: 'R2 bucket', name: storage, what: 'the studio\'s big media: songs and videos over the size studio.json media.r2Over names (1 MiB unless set) or that git leaves out, uploaded and checked by SHA-256 before the site stops carrying them, served at their same addresses', state: 'exists (this studio made it)', plan: 'R2 (payment method on the account; 10 GB-month free)' }
         : { kind: 'R2 bucket', name: null, what: 'none: a new studio needs no storage. `homie-studio storage add` adds it later, for large media only', state: 'not created', plan: null },
     ],
-    cost: storage
-      ? `Free on Cloudflare's Workers Free plan. ${R2_COST} Beyond the free tier Cloudflare bills the account directly.`
-      : 'Free: everything above is on Cloudflare\'s Workers Free plan, which needs no payment method. Its daily limits (100,000 Worker requests; D1 5 million rows read and 100,000 written) reset at 00:00 UTC; past them requests fail until the reset, nothing is charged.',
+    cost: 'Account subscription not queried. Cloudflare bills usage under the account’s current plan; estimates are not a billing quote.',
     login: 'One approval: `npx wrangler login` opens Cloudflare in the person\'s browser (a free account works; a new one verifies its email address first).',
     address: `https://${cf.worker}.<the account's workers.dev subdomain>.workers.dev`,
     directory: {
@@ -299,7 +301,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
     const account = who.accounts.find((a) => a.id === accountId)?.name ?? 'the signed-in account';
     announced.push(
       `First deploy of ${studio.name} to the Cloudflare account "${account}". It creates: the Worker ${cf.worker} (the site and its rooms), the D1 database ${cf.d1} (rounds, and the studio's own stats: counts for the owner, never a visitor's identity), and the Durable Objects Table and Lobby (SQLite-backed).`,
-      'Cost: free, on the Workers Free plan; no payment method, no R2 (storage for large media is `homie-studio storage add`, later, only if wanted).',
+      'Account subscription not queried; usage is billed under the account’s current Cloudflare plan.',
       `The directory (${homie || studio.homie?.directory || 'https://homie.rocks'}) will store the site's address and claim, the studio's name, and each game's name, blurb and Play link.`,
     );
     for (const line of announced) log(line);

package/lib/crowd-cloud.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * One crowd step played from inside Cloudflare, through the in-Cloudflare probe (lib/crowd-probe/README.md).
+ *
+ *   node lib/crowd-cloud.mjs --probe <probe address> --key <PROBE_KEY> --url <studio> --n 300
+ *        [--seconds 150] [--room <name>] [--out <dir>] [--ramp-ms 50] [--game crowd-circuit]
+ *
+ * It opens a request to the probe for every five players, holds them open for the step, and writes report.json in
+ * the shape crowd-load.mjs writes (what applies: there is no browser and no home connection in this one).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Tally } from './crowd-probe/client.mjs';
+
+const pick = (sorted, q) => (sorted.length ? sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * q))] : null);
+
+/** Every probe request's last line, added up into one report. */
+export function cloudReport({ origin, room, n, seconds, started, measureAt, endAt, finals, failures = [], toolkit = null }) {
+  const players = finals.flatMap((f) => f.players), tallies = { ack: new Tally(), gaps: new Tally(), loops: new Tally() };
+  for (const f of finals) for (const key of Object.keys(tallies)) tallies[key].merge(f.tallies?.[key]);
+  const of = (key) => players.map((p) => p[key]).filter(Number.isFinite).sort((a, b) => a - b);
+  const range = (key) => { const a = of(key); return { count: a.length, min: a[0] ?? null, median: pick(a, 0.5), p50: pick(a, 0.5), max: a.at(-1) ?? null }; };
+  const sum = (key) => players.reduce((a, p) => a + (p[key] ?? 0), 0), leads = of('lead');
+  const errors = new Map();
+  for (const p of players) { for (const text of p.errors ?? []) errors.set(text, (errors.get(text) ?? 0) + 1); if (p.closed && p.closed[1] !== 'probe step complete') { const text = `close: ${p.closed[0]} ${p.closed[1]}`; errors.set(text, (errors.get(text) ?? 0) + 1); } }
+  for (const text of failures) errors.set(text, (errors.get(text) ?? 0) + 1);
+  const joined = players.filter((p) => p.firstStateMs !== null).length, measured = Math.max(0, (endAt - measureAt) / 1000);
+  return {
+    generator: 'cloudflare', colos: [...new Set(finals.map((f) => f.colo).filter(Boolean))],
+    started: new Date(started).toISOString(), measurementStarted: new Date(measureAt).toISOString(), ended: new Date(endAt).toISOString(),
+    origin, room, n, total: n, simulated: n, chromePlayers: 0, toolkit, requestedSeconds: seconds, measuredSeconds: measured, stopReason: finals.length ? null : 'no probe answered',
+    joined, connectedAtEnd: players.filter((p) => p.firstStateMs !== null && (!p.closed || p.closed[1] === 'probe step complete')).length,
+    disconnects: players.filter((p) => p.closed && p.closed[1] !== 'probe step complete').length,
+    firstStateMs: (() => { const a = of('firstStateMs'); return { count: a.length, p50: pick(a, 0.5), p95: pick(a, 0.95), p99: pick(a, 0.99), max: a.at(-1) ?? null }; })(),
+    inputAckMs: tallies.ack.json(), receiveGapMs: tallies.gaps.json(),
+    // From the tick a player held when it stamped an input to the tick that input reached the rules.
+    inputLoopMs: tallies.loops.json(),
+    tickHz: range('tickHz'), deliveredHz: range('deliveredHz'),
+    payload: { upBytes: sum('upBytes'), downBytes: sum('downBytes'), inputFrames: sum('inputs'), downFrames: sum('frames'), wireDownBytes: 0, compressedSockets: 0 },
+    // Sockets that never leave Cloudflare are not compressed and cross no home connection.
+    compression: { offered: false, sockets: 0, of: players.length, ratio: null },
+    inputLead: { ticksMedian: pick(leads, 0.5), ticksMax: leads.at(-1) ?? null, lateShare: sum('reports') ? Math.round(sum('late') / sum('reports') * 1000) / 1000 : null },
+    driver: { requests: finals.length, failedRequests: failures.length, workerLoopP99Ms: [], peakTimerLagMs: finals.map((f) => f.worstTimerLagMs) },
+    errors: [...errors].map(([text, count]) => ({ text, count })),
+    players,
+  };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const opts = {};
+  for (let i = 2; i < process.argv.length; i += 2) { if (!process.argv[i].startsWith('--') || process.argv[i + 1] === undefined) throw Error('Use --key value'); opts[process.argv[i].slice(2)] = process.argv[i + 1]; }
+  const probe = String(opts.probe ?? '').replace(/\/$/, ''), key = opts.key, origin = new URL(opts.url).origin, n = Number(opts.n ?? 50), seconds = Number(opts.seconds ?? 150);
+  const rampMs = Number(opts['ramp-ms'] ?? 50), game = opts.game ?? 'crowd-circuit', room = opts.room ?? `cloud-${n}-${Date.now().toString(36)}`, out = resolve(opts.out ?? `reports/crowd-circuit/${room}`);
+  if (!probe || !key || !Number.isInteger(n) || n < 1 || n > 1000 || !(seconds >= 1 && seconds <= 600)) throw Error('--probe, --key, --url, --n 1..1000, --seconds 1..600');
+  await mkdir(out, { recursive: true });
+  const hello = await fetch(`${probe}/hello`, { headers: { 'x-probe-key': key }, signal: AbortSignal.timeout(15000) });
+  if (!hello.ok) throw Error(`The probe did not answer (${hello.status}): is it deployed, and is the key its PROBE_KEY?`);
+  let toolkit = null;
+  try { toolkit = (await (await fetch(`${origin}/.well-known/homie-studio.json?probe=${Date.now()}`, { signal: AbortSignal.timeout(15000) })).json()).toolkit ?? null; } catch { /* reported as null */ }
+  // Every request is told the same moments: when its players join (one every ramp-ms), when to start measuring
+  // (fifteen seconds after the last has joined) and when to stop.
+  const started = Date.now(), joinAt = started + 5000, measureAt = joinAt + n * rampMs + 15000, endAt = measureAt + seconds * 1000;
+  console.log(JSON.stringify({ phase: 'start', generator: 'cloudflare', origin, room, n, seconds, requests: Math.ceil(n / 5), toolkit }));
+  const finals = [], failures = []; let lastNote = 0; const progress = new Map();
+  await Promise.all(Array.from({ length: Math.ceil(n / 5) }, async (_, r) => {
+    const from = r * 5, count = Math.min(5, n - from);
+    try {
+      const res = await fetch(`${probe}/play?origin=${encodeURIComponent(origin)}&game=${encodeURIComponent(game)}&room=${encodeURIComponent(room)}&from=${from}&count=${count}&joinAt=${joinAt}&rampMs=${rampMs}&measureAt=${measureAt}&endAt=${endAt}`, { headers: { 'x-probe-key': key }, signal: AbortSignal.timeout(endAt - Date.now() + 60000) });
+      if (!res.ok || !res.body) throw Error(`probe HTTP ${res.status}`);
+      let text = '', final = null;
+      for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) {
+        text += chunk;
+        for (let at = text.indexOf('\n'); at >= 0; at = text.indexOf('\n')) {
+          const row = JSON.parse(text.slice(0, at)); text = text.slice(at + 1);
+          if (row.t === 'final') final = row; else if (row.t === 'failed') throw Error(row.error); else if (row.t === 'sample') progress.set(from, row);
+        }
+        if (Date.now() - lastNote > 10000) { lastNote = Date.now(); const rows = [...progress.values()]; console.log(JSON.stringify({ phase: rows.some((x) => x.measuring) ? 'steady' : 'ramp', joined: rows.reduce((a, x) => a + x.joined, 0), open: rows.reduce((a, x) => a + x.open, 0) })); }
+      }
+      if (!final) throw Error('the probe ended without its report');
+      finals.push(final);
+    } catch (error) { failures.push(`probe request ${from}: ${String(error?.message ?? error).slice(0, 160)}`); }
+  }));
+  const report = cloudReport({ origin, room, n, seconds, started, measureAt, endAt, finals, failures, toolkit });
+  await writeFile(`${out}/report.json`, JSON.stringify(report, null, 2));
+  console.log(JSON.stringify({ phase: 'done', out: `${out}/report.json`, joined: report.joined, connectedAtEnd: report.connectedAtEnd, ack: report.inputAckMs, loop: report.inputLoopMs, deliveredHz: report.deliveredHz, lead: report.inputLead, failedRequests: failures.length }));
+  if (!finals.length) process.exitCode = 1;
+}

package/lib/crowd-diagnostics.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/** Authenticated, bounded capture, including named QA rooms absent from office lists. */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { withKey } from './office.mjs';
+const opts = {};
+for (let i = 2; i < process.argv.length; i += 2) {
+  if (!process.argv[i].startsWith('--') || !process.argv[i + 1])
+    throw Error('Use --key value');
+  opts[process.argv[i].slice(2)] = process.argv[i + 1];
+}
+const room = opts.room,
+  game = opts.game ?? 'crowd-circuit',
+  seconds = Number(opts.seconds ?? 300),
+  out = resolve(opts.out ?? 'diagnostics.jsonl');
+if (
+  !/^[A-Za-z0-9_-]{1,32}$/.test(room ?? '') ||
+  !Number.isFinite(seconds) ||
+  seconds < 1 ||
+  seconds > 3600
+)
+  throw Error('--room is required; --seconds 1..3600');
+await mkdir(dirname(out), { recursive: true });
+let stopped = false;
+for (const s of ['SIGINT', 'SIGTERM']) process.on(s, () => (stopped = true));
+const result = await withKey(
+  resolve(opts.root ?? process.cwd()),
+  opts.url,
+  async (call) => {
+    const end = Date.now() + seconds * 1000;
+    while (!stopped && Date.now() < end) {
+      const start = Date.now();
+      let r;
+      try {
+        r = await call(
+          `/_studio/api/room?game=${encodeURIComponent(game)}&room=${encodeURIComponent(room)}`
+        );
+      } catch (error) {
+        r = { ok: false, error: String(error?.message ?? error) };
+      }
+      const f = r.facts;
+      // The endpoint answers from the room's diagnostics object: a second's
+      // facts from the room (tick rate, input transit) and from each Gate
+      // (frames written per player, world age, pacing), with the copy's age.
+      await appendFile(
+        out,
+        JSON.stringify({
+          at: Date.now(),
+          requestMs: Date.now() - start,
+          status: r.status,
+          ok: r.ok,
+          toolkit: f?.toolkit,
+          room: f?.room,
+          counts: f?.counts,
+          ticks: f?.ticks,
+          tickRate: f?.tickRate,
+          inputTransitMs: f?.inputTransitMs,
+          transport: f?.transport,
+          gates: f?.gates,
+          durability: f?.durability,
+          diagnostics: f?.diagnostics,
+          error: r.error
+        }) + '\n'
+      );
+      // A failed poll is evidence, not the end of the capture. Authentication
+      // errors are also retained; withKey renews and revokes its one key.
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+    return { ok: true };
+  }
+);
+console.log(JSON.stringify({ out, ...result }));
+if (!result.ok) process.exitCode = 1;