@homie-rocks/studio 0.46.2 → 0.46.3

package/saves/SAVES.md

@@ -64,8 +64,8 @@ landing. Pressing Play never needs an account.
   security key. No password, no email. A guest who makes an account keeps everything: it is the same player.
 - **Another device**: "Sign in" with the same passkey. The device's own passkey sync carries it (iCloud Keychain,
   Google Password Manager, a password manager), or the browser offers a phone's QR code. The same saves are there.
-  A guest who signs in to an account they already have keeps the account's saves, and anything only the guest had
-  (keys, stats, memorials the account lacks) moves over.
+  A guest who signs in to an account they already have loses nothing: what only the guest had (keys, stats,
+  memorials) moves over, and a key both have is combined ("When a guest signs in to their account", below).
 - **Recovery**: add another passkey on another device or a security key (`/account/`). A **recovery email** is
   offered only when the studio has a mail sender: a Cloudflare Email Service binding named `PLAYER_MAIL`
   (`"send_email": [{ "name": "PLAYER_MAIL" }]` in wrangler.jsonc; Email Sending needs the Workers paid plan and a
@@ -130,6 +130,82 @@ an old offline copy of a dead hero is a conflict with the wipe, and the wipe win
 
 A write is atomic **per key**, not across keys: keep one character in one key.
 
+## When a guest signs in to their account
+
+Somebody plays as a guest, then signs in to the account they made on another device. Both players have saves.
+Whatever only the guest had moves to the account as it is (keys, stats, memorials), and the guest is gone. For a
+key **both** have, the game says how the two combine, once, when the studio's Worker loads
+(`site/src/worker.mjs`):
+
+```js
+import { mergeSaves } from '@homie-rocks/studio/worker';
+
+mergeSaves({
+  'night-run': {
+    saves: {
+      'server:career-v1': { union: 'matches', by: 'id', order: 'endedAt', keep: 100 },
+      settings: 'newer', 'best-level': 'larger', coins: 'sum', 'slot-*': 'account',
+      inventory: (guest, account, ctx) => ({ items: [...new Set([...account.items, ...guest.items])] }),
+    },
+    stats: { kills: 'sum', level: 'larger', 'best-time': 'smaller' },
+  },
+});
+```
+
+A name is the exact key, or a prefix ending in `*`. The exact key beats a prefix; a longer prefix beats a shorter
+one. A rule that is none of the ones below throws when the Worker loads, naming it.
+
+| A save's rule | The account ends with |
+| --- | --- |
+| `'account'`, `'guest'` | that side's value. |
+| `'newer'` | the one written last (a tie: the account's). |
+| `'larger'`, `'smaller'` | the larger or smaller of two numbers. `{ rule: 'larger', by: 'level' }` compares that number in two objects and keeps the whole object. |
+| `'sum'` | two numbers added; or two objects with every number they share added, and for anything else the account's (the guest's where the account has none). |
+| `{ union: 'matches', by: 'id', order: 'endedAt', keep: 100 }` | the account's object with that list joined to the guest's by `by` (on the same id, the account's entry), newest `order` first, cut to `keep`. `order` and `keep` are optional; `'union'` alone is exactly the rule shown. A joined list too large for a save loses entries from its end until it fits. |
+| `(guest, account, ctx) => value` | what the game's own function returns, run on the server. It may be async. `ctx` is `{ game, key, guest: { updatedAt, version }, account: { updatedAt, version } }`. |
+
+A stat's rule is `'sum'`, `'larger'`, `'smaller'`, `'guest'` or `'account'`.
+
+**With no rule**, and whenever a rule cannot apply (two values that are not numbers to compare, a function that
+throws, returns nothing, or returns more than a save holds), the default applies. It never fails the sign-in:
+
+1. Equal values: nothing to do.
+2. Two values of the **record shape** the room server writes (`{ matches: [{ id, … }] }`, every `id` a text):
+   joined by id, newest first. For a `server:` key the newest 100 are kept, the record's own bound; only the server
+   can write such a key, so nothing else could combine the two. A key the browser wrote that happens to have this
+   shape is joined the same way and not cut (it is cut only if it would not fit a save). Declare `'account'` for a
+   key of that shape that must not be joined.
+3. Anything else: the account's value stays, and the guest's is **handed back** to the browser that signed in. The
+   play page raises it as an ordinary conflict, `mine` the guest's value and `theirs` the account's: a game with
+   `onConflict` keeps or merges it, and its answer is written on top; without `onConflict` the account's stays and
+   the game hears `conflict` with `kept: 'theirs'`. A stat keeps the account's number.
+
+The sign-in answers with what happened, beside `adoptedGuest: true`:
+
+```js
+adopted: {
+  merged: [{ game, key, rule, took }],      // took: 'merged', 'guest' or 'account' (a rule chose it)
+  moved: 3,                                 // keys only the guest had
+  kept: [{ game, key, value }],             // case 3; `rule` and `error` when a declared rule could not apply
+  stats: { merged: [{ game, name, rule }], kept: [{ game, name, value }] },
+}
+```
+
+`kept` carries at most 256 KiB of values; past that a key is named with `truncated: true` and the play page uses
+its own copy of the guest's value. A sign-in on `/account/` has no game to ask, so there the account's simply stays.
+
+It happens **exactly once**, in the one database transaction of the sign-in. If a room writes a record to either
+player between the read and that transaction, the transaction fails whole, and it is read and tried again; after
+four tries the account keeps every key both have and the answer says `fallback: true`. A round that ended a moment
+before the sign-in writes its record a moment after, under the guest's id: the guest leaves a forwarding row
+(`saves`, game `''`, key `server:moved`) and the record follows it to the account.
+
+**What is new and what is a fix.** `mergeSaves` and its rules are opt-in: a studio that declares nothing has the
+results it always had for every key and stat (the account's stays). Two things changed for everyone, both fixes:
+server records are joined (a guest's verified matches used to vanish), and a value the account did not take is
+handed back instead of dropped. A merged value larger than 64 KiB falls to the default; a merge never counts
+against a game's 256 KiB.
+
 ## The hall of the fallen: a hardcore recipe
 
 ```ts
@@ -182,6 +258,10 @@ Migration `site/migrations/0004_players.sql` (deploy applies it; an older studio
 | `player_emails` | a recovery email, only if the player added one | |
 | `saves`, `player_stats`, `memorials` | what the game saved | anything the game did not |
 
+A guest who signed in to their account leaves two small rows in `saves` under game `''`: `server:moved` under the
+guest's id (the account's id and when) and `server:from:<guest>` under the account's. They are in no export and no
+count, and they are deleted with the account.
+
 - **The player** sees all of it at `/account/`, downloads it as one JSON file (`/api/player/export`), and deletes
   it all (`/api/player/delete`): their passkeys, sessions, saves, stats, memorials and email, and their large
   saves in R2. The page tells them to remove the passkey from their device too, and tells the device itself where
@@ -227,7 +307,7 @@ Same origin only (a POST must come from this site's own pages, as JSON). For ref
 | --- | --- |
 | `GET /api/player/me` | the signed-in player, the features (`accounts`, `email`), the limits |
 | `POST /api/player/signup/options`, `POST /api/player/signup` | make an account, or add a passkey to this browser's guest or account |
-| `POST /api/player/signin/options`, `POST /api/player/signin` | sign in with a passkey (discoverable: no name typed) |
+| `POST /api/player/signin/options`, `POST /api/player/signin` | sign in with a passkey (discoverable: no name typed): `{ ok, player, adoptedGuest, adopted? }` |
 | `POST /api/player/signout`, `POST /api/player/name`, `GET /api/player/passkeys`, `POST /api/player/passkeys/remove` | |
 | `GET /api/player/export`, `POST /api/player/delete` (`{ "confirm": "delete" }`) | everything, and nothing |
 | `GET /api/player/saves/<game>[?values=1]`, `GET /api/player/saves/<game>/<key>` | read |

package/saves/saves.ts

@@ -54,6 +54,8 @@ export interface SavesOptions {
    * Another device saved a key since this one's copy (this browser was offline, or two devices played at once).
    * Return the value to keep (merge them, or return `mine`), or `undefined` for the cloud's (the default: a stale
    * offline copy never overwrites newer progress, so a hardcore character cannot come back from the dead).
+   * It is also asked when a guest signs in to an account that has the same key with another value and no
+   * `mergeSaves` rule combined them on the server: `mine` is the guest's value, `theirs` the account's.
    */
   onConflict?: (c: Conflict) => unknown | Promise<unknown>;
   /** Tests and custom shells: where messages go (default: the parent frame) and the shell's answer window. */

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.46.2","sha256":"335192af92b18b0857b7a32abc28017670a609737ef888a592f78e75561d16f0"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.46.3","sha256":"b36c0a219e734a32d419796f59d6965723849e1f462c75211468524c7b165266"});

package/worker/index.mjs

@@ -143,6 +143,8 @@ export { usePlayers } from './office.mjs';
 export { countVisit } from './stats.mjs';
 /** Players and cloud saves (saves/SAVES.md): `players.list`, `players.get`, `players.isOwner`… for the back office. */
 export { players, cleanName } from './players.mjs';
+/** How a guest's saves combine with the account's when they sign in (saves/SAVES.md): the studio's Worker calls it once, at load. */
+export { mergeSaves } from './saves.mjs';
 
 const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const POST_SLUG = /^[a-z0-9][a-z0-9-]{0,79}$/;

package/worker/players.mjs

@@ -28,7 +28,7 @@ import { toolIdentity } from './tool-identity.mjs';
 import { handleFor } from './room.mjs';
 import { isAiName } from './agents.mjs';
 import { cookieValue } from './stats.mjs';
-import { adoptStatements, bumpPlayerStats, dropPlayerData, fall, fallenList, getSave, listSaves, playerData, readPlayerStats, SAVE_LIMITS, savesSummary, wipeSaves, writeSaves } from './saves.mjs';
+import { adoptGuest, bumpPlayerStats, dropPlayerData, fall, fallenList, getSave, listSaves, playerData, readPlayerStats, SAVE_LIMITS, savesSummary, wipeSaves, writeSaves } from './saves.mjs';
 import { bytesToB64url, randomToken, sha256Hex, verifyAssertion, verifyRegistration } from './webauthn.mjs';
 import { ACCOUNT_JS, accountPage } from './account-page.mjs';
 import { adoptShopStatements, migrated as shopMigrated, forgetPlayerShop, livePurchases, shopDataOf } from './shop-store.mjs';
@@ -693,21 +693,19 @@ async function apiRoute(request, env, ctx, url, parts, { catalogueOf, read, f })
       session.statement,
     ];
     let adopted = null;
-    if (current && current.player.id !== key.player) {
-      writes.push(env.DB.prepare('DELETE FROM player_sessions WHERE hash = ?1').bind(current.hash));
-      // A guest signing in to their account: what only the guest had moves over, then the guest is gone.
-      if (current.player.guest) {
-        adopted = await adoptStatements(env, current.player.id, key.player);
-        writes.push(...adopted.statements, ...(await adoptShopStatements(env, current.player.id, key.player)),
-          env.DB.prepare('DELETE FROM player_sessions WHERE player = ?1').bind(current.player.id),
-          env.DB.prepare('DELETE FROM player_challenges WHERE player = ?1').bind(current.player.id),
-          env.DB.prepare('DELETE FROM players WHERE id = ?1 AND guest = 1').bind(current.player.id));
-      }
-    }
-    await env.DB.batch(writes);
-    if (adopted) await adopted.after();
+    if (current && current.player.id !== key.player) writes.push(env.DB.prepare('DELETE FROM player_sessions WHERE hash = ?1').bind(current.hash));
+    if (current && current.player.id !== key.player && current.player.guest) {
+      // A guest signing in to their account: what only the guest had moves over, what both have is combined by the
+      // game's rules (mergeSaves), then the guest is gone. One batch; read and tried again if a room wrote in between.
+      const guest = current.player.id;
+      const shop = await adoptShopStatements(env, guest, key.player);
+      adopted = await adoptGuest(env, guest, key.player, (statements) => [...writes, ...statements, ...shop,
+        env.DB.prepare('DELETE FROM player_sessions WHERE player = ?1').bind(guest),
+        env.DB.prepare('DELETE FROM player_challenges WHERE player = ?1').bind(guest),
+        env.DB.prepare('DELETE FROM players WHERE id = ?1 AND guest = 1').bind(guest)]);
+    } else await env.DB.batch(writes);
     const player = { id: key.player, name: key.name, named: Number(key.named) === 1, guest: false, owner: Number(key.owner) === 1, since: Number(key.created_at) };
-    return withCookies(json({ ok: true, player: await meOf(env, player), adoptedGuest: Boolean(adopted) }), [session.cookie]);
+    return withCookies(json({ ok: true, player: await meOf(env, player), adoptedGuest: Boolean(adopted), ...(adopted ? { adopted } : {}) }), [session.cookie]);
   }
 
   /* ---------------- a recovery email, signed out: the link in the mail is the proof */

package/worker/room.mjs

@@ -452,7 +452,8 @@ export class NetRoom {
         this.stats.evs += 1;
         const out = { t: 'ev', from: Number.isInteger(m.from) ? m.from : null, k: kind, d: m.d ?? null };
         const line = JSON.stringify(out);
-        if (Number.isInteger(m.to)) { for (const o of this.live()) if (o.seat === m.to) this.sendText(o.conn, line); return; }
+        // `to: -1` (0.46.3): everyone with no seat, a watcher. An effect with an audience reaches them whole.
+        if (Number.isInteger(m.to)) { for (const o of this.live()) if (m.to === -1 ? o.seat === null : o.seat === m.to) this.sendText(o.conn, line); return; }
         for (const o of this.live()) if (!this.lite(o) || this.liteHears(kind)) this.sendText(o.conn, line);
         return;
       }
@@ -460,6 +461,25 @@ export class NetRoom {
     }
   }
 
+  /**
+   * One measurement of a connection's round trip (0.46.3), and what the rules are told: a LOW PERCENTILE of the last ten
+   * seconds of them. A measurement is never shorter than the real round trip, so the low end of a window is close to
+   * it and one slow answer does not raise it; a window, so a connection that really got slower or faster is followed.
+   * A client can still pretend to be slower by answering late every time: what that buys is bounded by the game's
+   * `room.rewindSeconds`, and with acknowledgements on the input frames it has to send its input late as well.
+   */
+  latencySample(c, ms, now) {
+    if (!(ms >= 0 && ms <= 10000)) return;
+    const w = (c.rttWindow ??= []);
+    w.push([now, ms]);
+    while (w.length > 256 || (w.length > 1 && w[0][0] < now - 10000)) w.shift();
+    const sorted = w.map((x) => x[1]).sort((a, b) => a - b);
+    const low = sorted[Math.floor((sorted.length - 1) * 0.1)];
+    if (c.measuredRtt !== undefined && Math.abs(low - c.measuredRtt) < 2 && now - (c.rttToldAt ?? 0) < 1000) return;
+    c.measuredRtt = low; c.rttToldAt = now;
+    if (c.seat !== null) this.toServer({ t: 'latency', seat: c.seat, ms: low });
+  }
+
   /** A snapshot from the host (a browser's socket `c`, or the server: `c` null), kept for joiners and fanned out. */
   hostSnap(c, m, now, text = null) {
     // The server's stamp is this relay's own clock; a browser's is its estimate of it, and is checked.
@@ -468,6 +488,7 @@ export class NetRoom {
     // Revision 10: a rules game's snapshot names the room's epoch.
     if ((!c || this.rules && c.rules) && Number.isFinite(m.e)) snap.e = m.e;
     this.lastSnap = snap;
+    if (!c) { const sentAt = (this.snapAt ??= new Map()); sentAt.set(snap.k, now); if (sentAt.size > 128) sentAt.delete(sentAt.keys().next().value); }
     if (c) c.lastSnapAt = now;
     this.stats.snaps += 1;
     this.snapTimes.push(now);
@@ -870,6 +891,9 @@ export class NetRoom {
         if (this.server) {
           if (!Array.isArray(m.s)) return;
           this.stats.ins += 1;
+          // 0.46.3: the frame names the newest snapshot this browser had when it sent it (`g`). From when that snapshot
+          // left here to when this input arrived is this connection's round trip, measured on the input's own path.
+          if (Number.isInteger(m.g)) { c.inBand = true; const sent = this.snapAt?.get(m.g); if (sent !== undefined) this.latencySample(c, now - sent, now); }
           this.toServer({ t: 'in', from: c.seat, e: Number(m.e) || 0, k: Number(m.k) || 0, s: m.s.slice(0, 64), r: Number(m.r) || 0 });
           return;
         }
@@ -909,7 +933,7 @@ export class NetRoom {
         const recipients = isHost && this.rules && c.rules ? this.live() : this.others(c);
         if (isHost) {
           if (typeof m.to === 'string') { const o = this.clients.get(m.to); if (o && o.helloed && (o !== c || (this.rules && c.rules))) this.send(o, out); }
-          else if (Number.isInteger(m.to)) { for (const o of recipients) if (o.seat === m.to) this.send(o, out); }
+          else if (Number.isInteger(m.to)) { for (const o of recipients) if (m.to === -1 ? o.seat === null : o.seat === m.to) this.send(o, out); }
           // An agent with no game client hears only what is addressed to its seat (the lite feed), and the party's lines.
           else for (const o of recipients) { if (!this.lite(o) || this.liteHears(kind)) this.send(o, out); }
         } else {
@@ -958,7 +982,8 @@ export class NetRoom {
       case 'probeAck': {
         if (c.probe && m.n === c.probe.n) {
           const ms = now - c.probe.at; c.probe = null;
-          if(ms>=0 && ms<=10000){ c.measuredRtt=Math.min(c.measuredRtt??Infinity,ms); if(c.seat!==null)this.toServer({t:'latency',seat:c.seat,ms:c.measuredRtt}); }
+          // A browser that acknowledges on its input frames is measured there; this separate answer is for one that does not.
+          if(ms>=0 && ms<=10000 && !c.inBand) this.latencySample(c, ms, now);
         }
         return;
       }

package/worker/saves-shell.mjs

@@ -321,6 +321,25 @@ export const SAVES_SHELL_JS = `${PASSKEY_JS}
     });
   }
 
+  /**
+   * This browser's guest signed in to an account that had some of the same keys with other values, and no rule of
+   * the game's combined them on the server (mergeSaves): the account's stayed, and the sign-in answered with the
+   * guest's. Each is an ordinary conflict, the guest's value (mine) against the account's (theirs), so a game with
+   * onConflict keeps or merges it. Never a server: key: a browser cannot write one.
+   */
+  function keptByAccount(adopted, guestCopy) {
+    var asked = [];
+    ((adopted && adopted.kept) || []).forEach(function (k) {
+      var key = String(k.key);
+      if (k.game !== GAME || key.indexOf('server:') === 0 || !KEY.test(key)) return;
+      var mine = k.value !== undefined ? k.value : guestCopy[key];
+      if (mine === undefined || mine === null) return;
+      var c = S.cache[key];
+      asked.push(resolve(key, { op: 'set', v: mine }, { value: c ? c.v : null, version: c ? c.ver : 0 }, false));
+    });
+    if (asked.length) Promise.all(asked).then(function () { flush(); });
+  }
+
   addEventListener('online', function () { online(true); S.backoff = 0; flush(); });
   addEventListener('offline', function () { online(false); });
   document.addEventListener('visibilitychange', function () { if (document.visibilityState === 'hidden') flush(true); });
@@ -385,9 +404,10 @@ export const SAVES_SHELL_JS = `${PASSKEY_JS}
     };
     inn.onclick = function () {
       busy(true); said.className = 'said'; said.textContent = 'Follow your device…';
-      flush().then(function () { return P.signIn(); }).then(function (r) {
+      var guestCopy = {};
+      flush().then(function () { guestCopy = snapshot(); return P.signIn(); }).then(function (r) {
         setPlayer({ id: r.player.id, name: r.player.name, guest: false, owner: r.player.owner }, false);
-        return refresh().then(function () { tell('player', { player: me(), cache: snapshot() }); close(); });
+        return refresh().then(function () { tell('player', { player: me(), cache: snapshot() }); close(); keptByAccount(r.adopted, guestCopy); });
       }).catch(function (e) { said.className = 'said bad'; said.textContent = e && e.name ? P.said(e) : (e && e.message) || 'That did not work.'; busy(false); P.prime('in', '/api/player/signin/options'); });
     };
   }