@nano133/nanoterra 0.4.0 → 0.6.0

package/src/friends/adapters/firestore.ts

@@ -0,0 +1,197 @@
+// The friends store for a game on Firestore (the Admin SDK). The package has no Firebase dependency: the adapter uses the small interface below,
+// which the Admin SDK's `Firestore` fits. It reads and writes ONLY its three collections.
+//
+//   import { createFirestoreFriends } from "@nano133/nanoterra/friends/firestore";
+//   const friends = createFirestoreFriends(getFirestore());
+//
+// The data model (the three collection names can be changed):
+//   friend_edges/{pair}       { edge, a, b, players: [a, b], from, state, blockedBy, at, invite: { from, where, at } | null, rev }
+//   friend_presence/{player}  { player, where, lease, at }
+//   friend_prefs/{player}     { player, showOnline }
+// `{pair}` and `{player}` are SHA-256 hex digests (of "a\u0000b" and of the player's id), so any id makes a valid document id, and a pair has one
+// document: two requests at the same moment meet on it in their transactions. `edge` is a random id; the browser sees only that.
+// Indexes: the single-field indexes Firestore makes by itself are enough (`players` array-contains, `edge` ==).
+
+import { buildRows, checkPulse, friendsOf, hasPlayer, liveEdge, pairOf, planAccept, planBlock, planDecline, planInvite, planPulse, planRemove, planRequest, planUnblock, shownOthers, type EdgeRec, type Plan, type PresenceRec } from "../rules.js";
+import { FriendsError, type FriendView, type FriendsStore, type PlayerDirectory } from "../types.js";
+
+export type FriendsDocSnap = { exists: boolean; data(): Record<string, unknown> | undefined };
+export interface FriendsDocRef {
+  get(): Promise<FriendsDocSnap>;
+}
+export type FriendsQuerySnap = { docs: { id: string; ref: FriendsDocRef; data(): Record<string, unknown> }[] };
+export interface FriendsQuery {
+  where(field: string, op: "==" | "array-contains", value: unknown): FriendsQuery;
+  limit(n: number): FriendsQuery;
+  get(): Promise<FriendsQuerySnap>;
+}
+export interface FriendsCollection extends FriendsQuery {
+  doc(id: string): FriendsDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface FriendsTransaction {
+  get(ref: FriendsDocRef): Promise<FriendsDocSnap>;
+  get(query: FriendsQuery): Promise<FriendsQuerySnap>;
+  set(ref: FriendsDocRef, data: Record<string, unknown>): unknown;
+  delete(ref: FriendsDocRef): unknown;
+}
+export interface FriendsBatch {
+  set(ref: FriendsDocRef, data: Record<string, unknown>, options?: { merge?: boolean }): unknown;
+  delete(ref: FriendsDocRef): unknown;
+  commit(): Promise<unknown>;
+}
+export interface FirestoreFriendsLike {
+  collection(name: string): FriendsCollection;
+  runTransaction<T>(fn: (tx: FriendsTransaction) => Promise<T>): Promise<T>;
+  batch(): FriendsBatch;
+}
+
+/** How many edges of one player a read takes at most: the limit, the blocks by others and old requests fit under it. */
+export const FIRESTORE_FRIENDS_SCAN = 1000;
+
+async function sha256(text: string): Promise<string> {
+  const bytes = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+const text = (v: unknown, fallback = ""): string => (typeof v === "string" ? v : fallback);
+const num = (v: unknown, fallback = 0): number => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
+
+function recOf(d: Record<string, unknown>): EdgeRec {
+  const inv = d.invite as Record<string, unknown> | null | undefined;
+  const state = d.state === "friend" || d.state === "blocked" ? d.state : "pending";
+  return {
+    edge: text(d.edge),
+    a: text(d.a),
+    b: text(d.b),
+    from: text(d.from),
+    state,
+    blockedBy: Array.isArray(d.blockedBy) ? d.blockedBy.filter((x): x is string => typeof x === "string") : [],
+    at: num(d.at),
+    invite: inv && typeof inv.from === "string" && typeof inv.where === "string" && typeof inv.at === "number" ? { from: inv.from, where: inv.where, at: inv.at } : null,
+    rev: num(d.rev),
+  };
+}
+
+const dataOf = (r: EdgeRec): Record<string, unknown> => ({ edge: r.edge, a: r.a, b: r.b, players: [r.a, r.b], from: r.from, state: r.state, blockedBy: r.blockedBy, at: r.at, invite: r.invite, rev: r.rev });
+
+export function createFirestoreFriends(db: FirestoreFriendsLike, collections: { edges?: string; presence?: string; prefs?: string } = {}): FriendsStore {
+  const edges = () => db.collection(collections.edges ?? "friend_edges");
+  const presenceCol = () => db.collection(collections.presence ?? "friend_presence");
+  const prefsCol = () => db.collection(collections.prefs ?? "friend_prefs");
+  const pairRef = async (x: string, y: string) => {
+    const [a, b] = pairOf(x, y);
+    return edges().doc(await sha256(`${a}\u0000${b}`));
+  };
+  const playerRef = async (col: FriendsCollection, player: string) => col.doc(await sha256(player));
+  const ofPlayer = (player: string) => edges().where("players", "array-contains", player).limit(FIRESTORE_FRIENDS_SCAN);
+
+  /** Writes a plan in the transaction, on the pair's document. */
+  async function write(tx: FriendsTransaction, plan: Plan) {
+    if ("none" in plan) return;
+    const rec = "put" in plan ? plan.put : plan.drop;
+    const ref = await pairRef(rec.a, rec.b);
+    if ("put" in plan) tx.set(ref, dataOf(plan.put));
+    else tx.delete(ref);
+  }
+
+  /** An operation on an edge the browser named: the edge is found, then read again in the transaction on its pair's document. */
+  async function onEdge(player: string, edge: string, plan: (rec: EdgeRec | null) => Plan) {
+    const found = await edges().where("edge", "==", edge).limit(2).get();
+    const first = found.docs.map((d) => recOf(d.data())).find((r) => hasPlayer(r, player));
+    if (!first) {
+      plan(null);
+      return;
+    }
+    const ref = await pairRef(first.a, first.b);
+    await db.runTransaction(async (tx) => {
+      const snap = await tx.get(ref);
+      const now = snap.exists ? recOf(snap.data() ?? {}) : null;
+      // The pair's document holds another edge now (it was removed and asked again): the old edge is gone.
+      await write(tx, plan(now && now.edge === edge ? now : null));
+    });
+  }
+
+  const liveOf = (snap: FriendsQuerySnap, now: number) => snap.docs.map((d) => recOf(d.data())).filter((r) => liveEdge(r, now)).length;
+
+  return {
+    async view(player: string, directory: PlayerDirectory, now: number): Promise<FriendView> {
+      const recs = (await ofPlayer(player).get()).docs.map((d) => recOf(d.data())).filter((r) => hasPlayer(r, player));
+      const friends = friendsOf(player, recs, now);
+      const [mePref, pres, prefs, names] = await Promise.all([
+        (await playerRef(prefsCol(), player)).get(),
+        Promise.all(friends.map(async (f) => (await playerRef(presenceCol(), f)).get())),
+        Promise.all(friends.map(async (f) => (await playerRef(prefsCol(), f)).get())),
+        directory.names(shownOthers(player, recs, now)),
+      ]);
+      const presence = new Map<string, PresenceRec>();
+      pres.forEach((s, i) => {
+        const d = s.exists ? s.data() : undefined;
+        if (d && d.player === friends[i]) presence.set(friends[i], { player: friends[i], where: text(d.where), lease: text(d.lease), at: num(d.at) });
+      });
+      const shows = new Map<string, boolean>();
+      prefs.forEach((s, i) => {
+        const d = s.exists ? s.data() : undefined;
+        if (d && d.player === friends[i] && d.showOnline === false) shows.set(friends[i], false);
+      });
+      const mine = mePref.exists ? mePref.data() : undefined;
+      return { showOnline: mine?.showOnline !== false, people: buildRows(player, recs, now, names, presence, shows) };
+    },
+
+    async request(player, other, now) {
+      if (player === other) throw new FriendsError(400, "You cannot add yourself.");
+      const ref = await pairRef(player, other);
+      await db.runTransaction(async (tx) => {
+        const snap = await tx.get(ref);
+        const rec = snap.exists ? recOf(snap.data() ?? {}) : null;
+        // The counts are read in the transaction too (every read before the first write).
+        const plan = await planRequest(player, other, rec, now, async () => {
+          const [mine, theirs] = await Promise.all([tx.get(ofPlayer(player)), tx.get(ofPlayer(other))]);
+          return { mine: liveOf(mine, now), theirs: liveOf(theirs, now) };
+        });
+        await write(tx, plan);
+      });
+    },
+    accept: (player, edge, now) => onEdge(player, edge, (r) => planAccept(player, r, now)),
+    decline: (player, edge) => onEdge(player, edge, (r) => planDecline(player, r, Date.now())),
+    remove: (player, edge) => onEdge(player, edge, (r) => planRemove(player, r, Date.now())),
+    block: (player, edge, now) => onEdge(player, edge, (r) => planBlock(player, r, now)),
+    unblock: (player, edge, now) => onEdge(player, edge, (r) => planUnblock(player, r, now)),
+    invite: (player, edge, where, now) => onEdge(player, edge, (r) => planInvite(player, r, where, now)),
+
+    async pulse(player, where, lease, now) {
+      const p = checkPulse(where, lease);
+      const ref = await playerRef(presenceCol(), player);
+      await db.runTransaction(async (tx) => {
+        const snap = await tx.get(ref);
+        const d = snap.exists ? snap.data() : undefined;
+        const was = d ? { player, where: text(d.where), lease: text(d.lease), at: num(d.at) } : null;
+        const plan = planPulse(player, p.where, p.lease, was, now);
+        if ("put" in plan) tx.set(ref, { player, where: plan.put.where, lease: plan.put.lease, at: plan.put.at });
+        else if ("drop" in plan) tx.delete(ref);
+      });
+    },
+
+    async setShowOnline(player, on) {
+      const batch = db.batch();
+      batch.set(await playerRef(prefsCol(), player), { player, showOnline: Boolean(on) });
+      if (!on) batch.delete(await playerRef(presenceCol(), player));
+      await batch.commit();
+    },
+
+    async forget(player) {
+      const docs = (await ofPlayer(player).get()).docs.filter((d) => hasPlayer(recOf(d.data()), player));
+      const [pres, pref] = await Promise.all([(await playerRef(presenceCol(), player)).get(), (await playerRef(prefsCol(), player)).get()]);
+      const refs = docs.map((d) => d.ref);
+      if (pres.exists) refs.push(await playerRef(presenceCol(), player));
+      if (pref.exists) refs.push(await playerRef(prefsCol(), player));
+      // A batch holds at most 500 writes.
+      for (let i = 0; i < refs.length; i += 400) {
+        const batch = db.batch();
+        for (const ref of refs.slice(i, i + 400)) batch.delete(ref);
+        await batch.commit();
+      }
+      return refs.length;
+    },
+  };
+}

package/src/friends/conformance.ts

@@ -0,0 +1,260 @@
+// The conformance suite of the friends rules: a game that writes its own store (another database) runs it, and so proves that its store keeps
+// every rule the package's adapters keep. The package runs it on the memory store, D1 (on SQLite) and Firestore.
+//
+//   import { friendsStoreConformance } from "@nano133/nanoterra/friends/conformance";
+//   for (const c of friendsStoreConformance(async () => ({ store: myStore(), rows: () => countMyRows() }))) it(c.name, c.run);
+//
+// Each case gets a NEW, empty store from `make`. The suite names players with ids that it can find in a text (so it can prove that no view holds one)
+// and gives the store its own directory.
+
+import { FRIEND_INVITE_MS, FRIEND_LIMIT, FRIEND_LIVE_MS, FRIEND_REQUEST_MS, FriendsError, type FriendRow, type FriendView, type FriendsStore, type PlayerDirectory } from "./types.js";
+
+export type FriendsHarness = {
+  store: FriendsStore;
+  /** Every row the store keeps (edges, presence, prefs) as one text. `forget` must leave none that holds the player's id. */
+  dump(): Promise<string>;
+};
+
+export type FriendsConformanceCase = { name: string; run: () => Promise<void> };
+
+function check(ok: boolean, message: string): void {
+  if (!ok) throw new Error(message);
+}
+
+/** A player id the suite can find in any text. */
+const id = (n: string) => `player-id-${n}-7f3e`;
+const NAMES: Record<string, string> = {};
+const directory: PlayerDirectory = {
+  async byName(name) {
+    return Object.entries(NAMES).find(([, v]) => v === name)?.[0] ?? null;
+  },
+  async names(ids) {
+    return new Map(ids.filter((i) => NAMES[i]).map((i) => [i, NAMES[i]] as const));
+  },
+};
+for (const n of ["ann", "bob", "cyd", "dee"]) NAMES[id(n)] = n[0].toUpperCase() + n.slice(1);
+
+const ANN = id("ann");
+const BOB = id("bob");
+const CYD = id("cyd");
+
+async function rejects(p: Promise<unknown>, status: number, what: string): Promise<void> {
+  try {
+    await p;
+  } catch (e) {
+    check(e instanceof FriendsError, `${what}: expected a FriendsError, got ${String(e)}`);
+    check((e as FriendsError).status === status, `${what}: expected ${status}, got ${(e as FriendsError).status} (${(e as Error).message})`);
+    return;
+  }
+  throw new Error(`${what}: expected a refusal`);
+}
+
+export function friendsStoreConformance(make: () => Promise<FriendsHarness>): FriendsConformanceCase[] {
+  const cases: FriendsConformanceCase[] = [];
+  const add = (name: string, run: (h: FriendsHarness, now: number) => Promise<void>) => cases.push({ name, run: async () => run(await make(), Date.now()) });
+  const view = (h: FriendsHarness, who: string, now: number): Promise<FriendView> => h.store.view(who, directory, now);
+  const row = async (h: FriendsHarness, who: string, name: string, now: number): Promise<FriendRow | undefined> => (await view(h, who, now)).people.find((r) => r.name === name);
+  const friends = async (h: FriendsHarness, x: string, y: string, now: number) => {
+    await h.store.request(x, y, now);
+    await h.store.request(y, x, now + 1);
+  };
+
+  add("a request shows as outgoing to the sender and incoming to the other, with the other's name and no id", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const a = await row(h, ANN, "Bob", now);
+    const b = await row(h, BOB, "Ann", now);
+    check(a?.state === "outgoing" && b?.state === "incoming", `states: ${JSON.stringify([a, b])}`);
+    check(a!.edge === b!.edge && a!.edge.length >= 8, "the two rows name the same edge");
+    check(!a!.online && a!.where === null && a!.invite === null, "a request is not online and has no invite");
+  });
+
+  add("a request when the other already asked is an accept: both are friends, on one edge", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const a = (await view(h, ANN, now + 2)).people;
+    const b = (await view(h, BOB, now + 2)).people;
+    check(a.length === 1 && b.length === 1 && a[0].state === "friend" && b[0].state === "friend", `views: ${JSON.stringify([a, b])}`);
+  });
+
+  add("a request twice, or to a friend, changes nothing: one edge for the pair", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    await h.store.request(ANN, BOB, now + 1);
+    check((await view(h, ANN, now + 2)).people.length === 1, "one row after two requests");
+    await h.store.request(BOB, ANN, now + 3);
+    await h.store.request(ANN, BOB, now + 4);
+    const v = await view(h, ANN, now + 5);
+    check(v.people.length === 1 && v.people[0].state === "friend", `still one friend row: ${JSON.stringify(v)}`);
+  });
+
+  add("a player cannot ask themself", async (h, now) => {
+    await rejects(h.store.request(ANN, ANN, now), 400, "a request to self");
+  });
+
+  add("accept: only the player who was asked can accept; then both are friends", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now))!.edge;
+    await rejects(h.store.accept(ANN, edge, now + 1), 409, "the sender accepts their own request");
+    await h.store.accept(BOB, edge, now + 2);
+    check((await row(h, ANN, "Bob", now + 3))?.state === "friend", "Ann sees a friend");
+  });
+
+  add("decline takes the request away for both; the sender may also take it back", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    let edge = (await row(h, BOB, "Ann", now))!.edge;
+    await h.store.decline(BOB, edge);
+    check((await view(h, ANN, now + 1)).people.length === 0 && (await view(h, BOB, now + 1)).people.length === 0, "no rows after a decline");
+    await h.store.request(ANN, BOB, now + 2);
+    edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await h.store.decline(ANN, edge);
+    check((await view(h, BOB, now + 3)).people.length === 0, "no rows after the sender takes it back");
+  });
+
+  add("remove ends a friendship for both", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.remove(BOB, (await row(h, BOB, "Ann", now + 2))!.edge);
+    check((await view(h, ANN, now + 3)).people.length === 0 && (await view(h, BOB, now + 3)).people.length === 0, "no rows after remove");
+  });
+
+  add("a block wins: the blocker sees a blocked row, the other sees nothing, and neither can ask again", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.block(ANN, (await row(h, ANN, "Bob", now + 2))!.edge, now + 3);
+    check((await row(h, ANN, "Bob", now + 4))?.state === "blocked", "Ann sees Bob as blocked");
+    check((await view(h, BOB, now + 4)).people.length === 0, "Bob does not see Ann at all");
+    await rejects(h.store.request(BOB, ANN, now + 5), 409, "a request by the blocked player");
+    await rejects(h.store.request(ANN, BOB, now + 5), 409, "a request by the blocker");
+  });
+
+  add("the blocked player cannot use the old edge for anything", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, BOB, "Ann", now + 2))!.edge;
+    await h.store.block(ANN, edge, now + 3);
+    await rejects(h.store.accept(BOB, edge, now + 4), 404, "accept on a blocked edge");
+    await rejects(h.store.invite(BOB, edge, "Room 1", now + 4), 404, "invite on a blocked edge");
+    await rejects(h.store.remove(BOB, edge), 404, "remove on a blocked edge");
+    await rejects(h.store.unblock(BOB, edge, now + 4), 404, "unblock by the one who did not block");
+    check((await row(h, ANN, "Bob", now + 5))?.state === "blocked", "the block stands");
+  });
+
+  add("unblock leaves no edge (not friends again); only the player who blocked can unblock", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await h.store.block(ANN, edge, now + 3);
+    await h.store.unblock(ANN, edge, now + 4);
+    check((await view(h, ANN, now + 5)).people.length === 0 && (await view(h, BOB, now + 5)).people.length === 0, "no edge after unblock");
+    // Bob blocks this time: Ann sees nothing, so she cannot unblock his block.
+    await friends(h, ANN, BOB, now + 11);
+    const e3 = (await row(h, BOB, "Ann", now + 13))!.edge;
+    await h.store.block(BOB, e3, now + 14);
+    check((await view(h, ANN, now + 15)).people.length === 0, "Ann does not see Bob's block");
+    await rejects(h.store.unblock(ANN, e3, now + 16), 404, "Ann cannot unblock Bob's block");
+    await h.store.unblock(BOB, e3, now + 17);
+    check((await view(h, ANN, now + 18)).people.length === 0 && (await view(h, BOB, now + 18)).people.length === 0, "nothing left after Bob unblocks");
+  });
+
+  add(`a full list (${FRIEND_LIMIT} live rows) refuses a new request, both ways`, async (h, now) => {
+    for (let i = 0; i < FRIEND_LIMIT; i++) {
+      const other = id(`fan${i}`);
+      NAMES[other] = `Fan${i}`;
+      await h.store.request(other, ANN, now + i);
+    }
+    await rejects(h.store.request(ANN, BOB, now + FRIEND_LIMIT), 409, "Ann asks with a full list");
+    await rejects(h.store.request(CYD, ANN, now + FRIEND_LIMIT), 409, "Cyd asks Ann, whose list is full");
+    // An answer to one of the requests is not a new row: it is allowed.
+    const edge = (await row(h, ANN, "Fan0", now + FRIEND_LIMIT))!.edge;
+    await h.store.accept(ANN, edge, now + FRIEND_LIMIT + 1);
+  });
+
+  add("a request nobody answers goes after its time: not shown, not counted, and it may be sent again", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const later = now + FRIEND_REQUEST_MS + 1;
+    check((await view(h, ANN, later)).people.length === 0 && (await view(h, BOB, later)).people.length === 0, "the old request is gone");
+    await h.store.request(BOB, ANN, later);
+    const v = await view(h, ANN, later + 1);
+    check(v.people.length === 1 && v.people[0].state === "incoming", `a new request after the old one went: ${JSON.stringify(v)}`);
+  });
+
+  add("an invite works only between friends; the other sees it for its time, the sender does not", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now))!.edge;
+    await rejects(h.store.invite(ANN, edge, "Room 1", now + 1), 409, "an invite to a request");
+    await h.store.accept(BOB, edge, now + 2);
+    await h.store.invite(ANN, edge, "Room 1", now + 3);
+    const b = await row(h, BOB, "Ann", now + 4);
+    check(b?.invite?.where === "Room 1" && b.invite.at === now + 3, `Bob sees the invite: ${JSON.stringify(b)}`);
+    check((await row(h, ANN, "Bob", now + 4))?.invite === null, "Ann does not see her own invite");
+    check((await row(h, BOB, "Ann", now + 3 + FRIEND_INVITE_MS))?.invite === null, "the invite is gone after its time");
+  });
+
+  add("an invite's place is plain text: control characters go and it is cut to 64 characters; an empty one is refused", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await h.store.invite(ANN, edge, `  Lev\u0000el\n 3 ${"x".repeat(100)}`, now + 3);
+    const w = (await row(h, BOB, "Ann", now + 4))!.invite!.where;
+    check(!/[\u0000-\u001f]/.test(w) && Array.from(w).length <= 64 && w.startsWith("Level 3"), `the place: ${JSON.stringify(w)}`);
+    await rejects(h.store.invite(ANN, edge, " \n\t ", now + 5), 400, "an empty place");
+  });
+
+  add("online only within its time, only to friends, and only while the friend shows online", async (h, now) => {
+    await h.store.request(ANN, CYD, now);
+    await friends(h, ANN, BOB, now);
+    await h.store.pulse(BOB, "Room 2", "lease-bob-1", now + 2);
+    await h.store.pulse(CYD, "Room 3", "lease-cyd-1", now + 2);
+    const b = await row(h, ANN, "Bob", now + 3);
+    check(b?.online === true && b.where === "Room 2", `Bob is online: ${JSON.stringify(b)}`);
+    const c = await row(h, ANN, "Cyd", now + 3);
+    check(c?.online === false && c.where === null, "a player who is only asked is not shown online");
+    check((await row(h, ANN, "Bob", now + 2 + FRIEND_LIVE_MS))?.online === false, "a pulse is old after its time");
+    await h.store.pulse(BOB, "Room 2", "lease-bob-1", now + 4);
+    await h.store.setShowOnline(BOB, false);
+    const hidden = await row(h, ANN, "Bob", now + 5);
+    check(hidden?.online === false && hidden.where === null, "a friend who hides is not online");
+    check((await view(h, BOB, now + 5)).showOnline === false && (await view(h, ANN, now + 5)).showOnline === true, "each player's own choice");
+    await h.store.setShowOnline(BOB, true);
+    check((await row(h, ANN, "Bob", now + 6))?.online === false, "hiding cleared the old pulse");
+  });
+
+  add("presence: a tab that leaves clears only its own pulse, so an old tab cannot clear a new one", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.pulse(BOB, "Room 1", "lease-old-tab", now + 2);
+    await h.store.pulse(BOB, "Room 2", "lease-new-tab", now + 3);
+    await h.store.pulse(BOB, null, "lease-old-tab", now + 4);
+    check((await row(h, ANN, "Bob", now + 5))?.where === "Room 2", "the new tab's place stands");
+    await h.store.pulse(BOB, null, "lease-new-tab", now + 6);
+    check((await row(h, ANN, "Bob", now + 7))?.online === false, "the new tab left");
+    await rejects(h.store.pulse(BOB, "Room 1", "short", now + 8), 400, "a lease that is too short");
+  });
+
+  add("a player cannot use an edge of two other players", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await rejects(h.store.remove(CYD, edge), 404, "remove");
+    await rejects(h.store.block(CYD, edge, now + 3), 404, "block");
+    await rejects(h.store.invite(CYD, edge, "Room", now + 3), 404, "invite");
+    await rejects(h.store.accept(CYD, "no-such-edge-1", now + 3), 404, "an edge that does not exist");
+  });
+
+  add("no view holds a player id", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.request(CYD, ANN, now + 2);
+    await h.store.pulse(BOB, "Room 9", "lease-bob-9", now + 3);
+    await h.store.invite(BOB, (await row(h, BOB, "Ann", now + 3))!.edge, "Room 9", now + 4);
+    for (const who of [ANN, BOB, CYD]) {
+      const text = JSON.stringify(await view(h, who, now + 5));
+      check(!/player-id-/.test(text), `a view holds an id: ${text}`);
+    }
+  });
+
+  add("forget leaves nothing of the player: no edge, no presence, no choice; the others' lists lose them", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.request(CYD, ANN, now + 2);
+    await h.store.pulse(ANN, "Room", "lease-ann-1", now + 3);
+    await h.store.setShowOnline(ANN, false);
+    await h.store.pulse(BOB, "Room", "lease-bob-1", now + 3);
+    const n = await h.store.forget(ANN);
+    check(n >= 3, `forget said ${n}`);
+    check(!(await h.dump()).includes(ANN), "a row still holds the player's id");
+    check((await view(h, BOB, now + 4)).people.length === 0 && (await view(h, CYD, now + 4)).people.length === 0, "the others no longer see the player");
+    check((await h.dump()).includes(BOB), "the other players' own rows stay");
+  });
+
+  return cases;
+}

package/src/friends/handler.ts

@@ -0,0 +1,144 @@
+// The routes of the game's own friends list, on the Web `Request` and `Response` types (a Worker, Firebase Functions, Node).
+//
+//   GET  {base}   the player's view: { showOnline, people }
+//   POST {base}   one operation, { op, ... }:
+//                   request { name }                   (the name through the game's directory)
+//                   accept | decline | remove | block | unblock { edge }
+//                   invite { edge, where }
+//                   pulse { where (text, or null to leave), lease }
+//                   visibility { showOnline: boolean }
+//
+// The player is the game's own signed-in player (`player(request)`); a visitor who is not signed in gets 401. A POST must come from the game's own
+// page, and a read must not come from another page. Each player has 30 calls a minute. No answer ever holds a player id: a row names a player by
+// the directory's name and an opaque edge.
+
+import { fail, foreignOrigin, json, memoryLimiter, readLimited, sameOrigin } from "../admin/http.js";
+import { EDGE_PATTERN } from "./rules.js";
+import { FriendsError, type FriendsStore, type PlayerDirectory } from "./types.js";
+
+export type FriendsOp = "request" | "accept" | "decline" | "remove" | "block" | "unblock" | "invite" | "pulse" | "visibility";
+
+export type FriendsHandlerOptions = {
+  store: FriendsStore;
+  directory: PlayerDirectory;
+  /** The game's signed-in player of this request (its own id), or null. */
+  player(request: Request): Promise<string | null>;
+  /** Where the routes are. Default "/friends". */
+  base?: string;
+  /** A limiter: false means "too many". Default: a fixed window in memory, 30 calls a minute for each player. */
+  limit?: (key: string, limit: number, windowMs: number, now: number) => boolean | Promise<boolean>;
+  /** The time now in ms. Default Date.now. */
+  now?: () => number;
+  /** Told about a fault in the store or the directory. The player gets a plain 500 and never sees it. */
+  onError?: (e: unknown) => void;
+};
+
+export const FRIENDS_LIMITS = {
+  /** Calls of one player (reads and writes together). */
+  calls: { limit: 30, windowMs: 60_000 },
+  /** The biggest body of a POST. */
+  bodyMax: 1024,
+  /** The longest name a request may send. */
+  nameMax: 64,
+} as const;
+
+const sharedLimit = memoryLimiter();
+const OPS = new Set<FriendsOp>(["request", "accept", "decline", "remove", "block", "unblock", "invite", "pulse", "visibility"]);
+
+export function createFriendsHandler(options: FriendsHandlerOptions): { base: string; handle(request: Request): Promise<Response | null> } {
+  const base = options.base ?? "/friends";
+  if (!base.startsWith("/") || base.length < 2 || base.endsWith("/")) throw new Error('base must start with "/" and not end with "/", like "/friends"');
+  const now = options.now ?? (() => Date.now());
+  const limit = options.limit ?? sharedLimit;
+  const report = (e: unknown) => {
+    try {
+      options.onError?.(e);
+    } catch {
+      // nothing more can be done
+    }
+  };
+
+  async function run(req: Request, player: string, at: number): Promise<Response> {
+    if (req.method === "GET") return json(await options.store.view(player, options.directory, at));
+    const text = await readLimited(req, FRIENDS_LIMITS.bodyMax);
+    if (text === null) return fail(413, "That is too much to send.");
+    let body: Record<string, unknown>;
+    try {
+      const v: unknown = JSON.parse(text);
+      if (!v || typeof v !== "object" || Array.isArray(v)) return fail(400, "Send an object with an op.");
+      body = v as Record<string, unknown>;
+    } catch {
+      return fail(400, "Send JSON.");
+    }
+    const op = body.op as FriendsOp;
+    if (typeof op !== "string" || !OPS.has(op)) return fail(400, "Unknown op.");
+    const store = options.store;
+    const edge = (): string => {
+      if (typeof body.edge !== "string" || !EDGE_PATTERN.test(body.edge)) throw new FriendsError(400, "Choose a player on your list.");
+      return body.edge;
+    };
+    switch (op) {
+      case "request": {
+        const name = typeof body.name === "string" ? body.name.trim() : "";
+        if (!name || name.length > FRIENDS_LIMITS.nameMax) return fail(400, "Enter a player's name.");
+        const other = await options.directory.byName(name);
+        if (!other) return fail(404, "No player has that name.");
+        await store.request(player, other, at);
+        break;
+      }
+      case "accept":
+        await store.accept(player, edge(), at);
+        break;
+      case "decline":
+        await store.decline(player, edge());
+        break;
+      case "remove":
+        await store.remove(player, edge());
+        break;
+      case "block":
+        await store.block(player, edge(), at);
+        break;
+      case "unblock":
+        await store.unblock(player, edge(), at);
+        break;
+      case "invite":
+        await store.invite(player, edge(), typeof body.where === "string" ? body.where : "", at);
+        break;
+      case "pulse":
+        await store.pulse(player, body.where === null ? null : typeof body.where === "string" ? body.where : "", typeof body.lease === "string" ? body.lease : "", at);
+        // A pulse needs no list back: the panel reads the view on its own clock.
+        return json({ ok: true });
+      case "visibility":
+        if (typeof body.showOnline !== "boolean") return fail(400, "Send showOnline as true or false.");
+        await store.setShowOnline(player, body.showOnline);
+        break;
+    }
+    return json(await store.view(player, options.directory, now()));
+  }
+
+  async function handle(req: Request): Promise<Response | null> {
+    const url = new URL(req.url);
+    if (url.pathname !== base) return null;
+    try {
+      if (req.method !== "GET" && req.method !== "POST") return fail(405, "Not allowed.", {}, { Allow: "GET, POST" });
+      if (req.method === "POST" ? !sameOrigin(req) : foreignOrigin(req)) return fail(403, "This call must come from the game's own page.");
+      let player: string | null;
+      try {
+        player = await options.player(req);
+      } catch (e) {
+        report(e);
+        return fail(503, "The game's server could not check your sign-in. Try again.");
+      }
+      if (typeof player !== "string" || !player) return fail(401, "Sign in to see your friends.");
+      const at = now();
+      if (!(await limit(`${base}|friends|${player}`, FRIENDS_LIMITS.calls.limit, FRIENDS_LIMITS.calls.windowMs, at))) return fail(429, "Too many calls. Wait a minute.");
+      return await run(req, player, at);
+    } catch (e) {
+      if (e instanceof FriendsError) return fail(e.status, e.message);
+      report(e);
+      return fail(500, "The game's server could not do that. Try again.");
+    }
+  }
+
+  return { base, handle };
+}

package/src/friends/index.ts

@@ -0,0 +1,17 @@
+// "@nano133/nanoterra/friends": the friends list of a game's OWN players (the setting "The game's own" of the admin's Game card). No database, no
+// cookie, no Nanoterra account: the game gives its store, its directory of players and its signed-in player.
+//
+//   createFriendsHandler   the routes (GET the view, POST an op), on Request and Response
+//   createMemoryFriends    a store in memory, for tests
+//   (the adapters are "/friends/d1" and "/friends/firestore", the conformance suite "/friends/conformance", the browser panel "/friends/panel")
+//
+// Nanoterra's own friends list (the setting "Nanoterra") is not here: the panel holds the nano133 window for it, and the friends stay on nano133.
+
+export { FRIEND_INVITE_MS, FRIEND_LIMIT, FRIEND_LIVE_MS, FRIEND_REQUEST_MS, FRIEND_WHERE_MAX, FriendsError } from "./types.js";
+export type { FriendRow, FriendState, FriendView, FriendsStore, PlayerDirectory } from "./types.js";
+export { FRIENDS_LIMITS, createFriendsHandler } from "./handler.js";
+export type { FriendsHandlerOptions, FriendsOp } from "./handler.js";
+export { createMemoryFriends } from "./memory.js";
+export type { MemoryFriends } from "./memory.js";
+export { EDGE_PATTERN, LEASE_PATTERN, cleanWhere } from "./rules.js";
+export type { EdgeRec, PresenceRec } from "./rules.js";