@nano133/nanoterra 0.4.0 → 0.6.0

package/dist/friends/adapters/d1.js

@@ -0,0 +1,131 @@
+// The friends store for a game on Cloudflare D1. The tables are in ./d1.sql (the package ships it: "@nano133/nanoterra/friends/d1.sql"); add it to
+// the game's migrations. It reads and writes ONLY friend_edges, friend_presence and friend_prefs.
+//
+//   import { createD1Friends } from "@nano133/nanoterra/friends/d1";
+//   const friends = createD1Friends(env.DB);
+//
+// D1 has no transaction that reads and then writes, so each write is ONE statement that holds its own check: a change of an edge says which `rev`
+// it read (a row that changed in between is not written, and the player is asked to try again), and a new edge is written only while both players
+// have room (the count is in the same statement) and the pair has no row yet (UNIQUE (a, b)).
+import { buildRows, checkPulse, pairOf, planAccept, planBlock, planDecline, planInvite, planRemove, planRequest, planUnblock, shownOthers } from "../rules.js";
+import { FRIEND_LIMIT, FRIEND_REQUEST_MS, FriendsError } from "../types.js";
+const COLS = "edge, a, b, from_player, state, blocked_by, at, invite_from, invite_where, invite_at, rev";
+function recOf(r) {
+    let blockedBy = [];
+    try {
+        const v = JSON.parse(r.blocked_by);
+        if (Array.isArray(v))
+            blockedBy = v.filter((x) => typeof x === "string");
+    }
+    catch {
+        blockedBy = [];
+    }
+    const state = r.state === "friend" || r.state === "blocked" ? r.state : "pending";
+    const invite = typeof r.invite_from === "string" && typeof r.invite_where === "string" && typeof r.invite_at === "number" ? { from: r.invite_from, where: r.invite_where, at: Number(r.invite_at) } : null;
+    return { edge: r.edge, a: r.a, b: r.b, from: r.from_player, state, blockedBy, at: Number(r.at), invite, rev: Number(r.rev) };
+}
+const CHANGED = "That changed just now. Try again.";
+export function createD1Friends(db) {
+    const changes = (res) => Number(res?.meta?.changes ?? 0);
+    const byEdge = async (edge) => {
+        const r = await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE edge = ?`).bind(edge).first();
+        return r ? recOf(r) : null;
+    };
+    const byPair = async (x, y) => {
+        const [a, b] = pairOf(x, y);
+        const r = await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE a = ? AND b = ?`).bind(a, b).first();
+        return r ? recOf(r) : null;
+    };
+    /** Live edges of a player, as SQL (?1 the player, ?2 the oldest request time that still counts). */
+    const LIVE_COUNT = "(SELECT COUNT(*) FROM friend_edges WHERE (a = ?1 OR b = ?1) AND (state != 'pending' OR at > ?2))";
+    const liveCount = async (player, now) => Number((await db.prepare(`SELECT ${LIVE_COUNT} AS n`).bind(player, now - FRIEND_REQUEST_MS).first())?.n ?? 0);
+    async function apply(plan, prev, now) {
+        if ("none" in plan)
+            return;
+        if ("drop" in plan) {
+            if (changes(await db.prepare("DELETE FROM friend_edges WHERE edge = ? AND rev = ?").bind(plan.drop.edge, plan.drop.rev).run()) !== 1)
+                throw new FriendsError(409, CHANGED);
+            return;
+        }
+        const r = plan.put;
+        const inv = r.invite;
+        if (prev && prev.edge === r.edge) {
+            const res = await db
+                .prepare("UPDATE friend_edges SET from_player = ?, state = ?, blocked_by = ?, at = ?, invite_from = ?, invite_where = ?, invite_at = ?, rev = ? WHERE edge = ? AND rev = ?")
+                .bind(r.from, r.state, JSON.stringify(r.blockedBy), r.at, inv?.from ?? null, inv?.where ?? null, inv?.at ?? null, r.rev, r.edge, prev.rev)
+                .run();
+            if (changes(res) !== 1)
+                throw new FriendsError(409, CHANGED);
+            return;
+        }
+        // A new edge: only while both players have room, in the same statement (the pair's UNIQUE (a, b) refuses a second row).
+        const cut = now - FRIEND_REQUEST_MS;
+        const other = r.from === r.a ? r.b : r.a;
+        const sql = `INSERT INTO friend_edges (${COLS}) SELECT ?3, ?4, ?5, ?6, ?7, ?8, ?9, NULL, NULL, NULL, ?10 ` +
+            `WHERE (SELECT COUNT(*) FROM friend_edges WHERE (a = ?1 OR b = ?1) AND (state != 'pending' OR at > ?11)) < ?12 ` +
+            `AND (SELECT COUNT(*) FROM friend_edges WHERE (a = ?2 OR b = ?2) AND (state != 'pending' OR at > ?11)) < ?12 ` +
+            `ON CONFLICT (a, b) DO NOTHING`;
+        const res = await db.prepare(sql).bind(r.from, other, r.edge, r.a, r.b, r.from, r.state, JSON.stringify(r.blockedBy), r.at, r.rev, cut, FRIEND_LIMIT).run();
+        if (changes(res) !== 1)
+            throw new FriendsError(409, CHANGED);
+    }
+    async function onEdge(_player, edge, plan, now) {
+        const rec = await byEdge(edge);
+        await apply(plan(rec), rec, now);
+    }
+    return {
+        async view(player, directory, now) {
+            const recs = (await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE a = ?1 OR b = ?1`).bind(player).all()).results.map(recOf);
+            // The presence and the choice of the player's friends, in one statement each (a friend's id is the other side of a friend edge).
+            const OTHER = "CASE WHEN e.a = ?1 THEN e.b ELSE e.a END";
+            const pres = (await db
+                .prepare(`SELECT p.player, p.place, p.lease, p.at FROM friend_edges e JOIN friend_presence p ON p.player = ${OTHER} WHERE (e.a = ?1 OR e.b = ?1) AND e.state = 'friend'`)
+                .bind(player)
+                .all()).results;
+            const hidden = (await db.prepare(`SELECT f.player FROM friend_edges e JOIN friend_prefs f ON f.player = ${OTHER} WHERE (e.a = ?1 OR e.b = ?1) AND e.state = 'friend' AND f.show_online = 0`).bind(player).all()).results;
+            const me = await db.prepare("SELECT show_online FROM friend_prefs WHERE player = ?").bind(player).first();
+            const names = await directory.names(shownOthers(player, recs, now));
+            const presence = new Map(pres.map((p) => [p.player, { player: p.player, where: p.place, lease: p.lease, at: Number(p.at) }]));
+            const shows = new Map(hidden.map((x) => [x.player, false]));
+            return { showOnline: !me || Number(me.show_online) !== 0, people: buildRows(player, recs, now, names, presence, shows) };
+        },
+        async request(player, other, now) {
+            const rec = await byPair(player, other);
+            const plan = await planRequest(player, other, rec, now, async () => ({ mine: await liveCount(player, now), theirs: await liveCount(other, now) }));
+            // A request that went stale is still the pair's row: it is changed in place (its count is the one just read).
+            await apply(plan, rec, now);
+        },
+        accept: (player, edge, now) => onEdge(player, edge, (r) => planAccept(player, r, now), now),
+        decline: (player, edge) => onEdge(player, edge, (r) => planDecline(player, r, Date.now()), Date.now()),
+        remove: (player, edge) => onEdge(player, edge, (r) => planRemove(player, r, Date.now()), Date.now()),
+        block: (player, edge, now) => onEdge(player, edge, (r) => planBlock(player, r, now), now),
+        unblock: (player, edge, now) => onEdge(player, edge, (r) => planUnblock(player, r, now), now),
+        invite: (player, edge, where, now) => onEdge(player, edge, (r) => planInvite(player, r, where, now), now),
+        async pulse(player, where, lease, now) {
+            const p = checkPulse(where, lease);
+            if (p.where !== null) {
+                await db
+                    .prepare("INSERT INTO friend_presence (player, place, lease, at) VALUES (?, ?, ?, ?) ON CONFLICT (player) DO UPDATE SET place = excluded.place, lease = excluded.lease, at = excluded.at")
+                    .bind(player, p.where, p.lease, now)
+                    .run();
+                return;
+            }
+            // Leaving: only the tab that holds the row may clear it (planPulse's rule, in the statement).
+            await db.prepare("DELETE FROM friend_presence WHERE player = ? AND lease = ?").bind(player, p.lease).run();
+        },
+        async setShowOnline(player, on) {
+            const stmts = [db.prepare("INSERT INTO friend_prefs (player, show_online) VALUES (?, ?) ON CONFLICT (player) DO UPDATE SET show_online = excluded.show_online").bind(player, on ? 1 : 0)];
+            if (!on)
+                stmts.push(db.prepare("DELETE FROM friend_presence WHERE player = ?").bind(player));
+            await db.batch(stmts);
+        },
+        async forget(player) {
+            const done = await db.batch([
+                db.prepare("DELETE FROM friend_edges WHERE a = ?1 OR b = ?1").bind(player),
+                db.prepare("DELETE FROM friend_presence WHERE player = ?").bind(player),
+                db.prepare("DELETE FROM friend_prefs WHERE player = ?").bind(player),
+            ]);
+            return done.reduce((n, r) => n + changes(r), 0);
+        },
+    };
+}

package/dist/friends/adapters/firestore.d.ts

@@ -0,0 +1,49 @@
+import { type FriendsStore } 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 declare const FIRESTORE_FRIENDS_SCAN = 1000;
+export declare function createFirestoreFriends(db: FirestoreFriendsLike, collections?: {
+    edges?: string;
+    presence?: string;
+    prefs?: string;
+}): FriendsStore;

package/dist/friends/adapters/firestore.js

@@ -0,0 +1,163 @@
+// 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 } from "../rules.js";
+import { FriendsError } from "../types.js";
+/** 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) {
+    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, fallback = "") => (typeof v === "string" ? v : fallback);
+const num = (v, fallback = 0) => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
+function recOf(d) {
+    const inv = d.invite;
+    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) => 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) => ({ 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, collections = {}) {
+    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, y) => {
+        const [a, b] = pairOf(x, y);
+        return edges().doc(await sha256(`${a}\u0000${b}`));
+    };
+    const playerRef = async (col, player) => col.doc(await sha256(player));
+    const ofPlayer = (player) => 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, 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, edge, 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, now) => snap.docs.map((d) => recOf(d.data())).filter((r) => liveEdge(r, now)).length;
+    return {
+        async view(player, directory, now) {
+            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();
+            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();
+            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/dist/friends/conformance.d.ts

@@ -0,0 +1,11 @@
+import { type FriendsStore } 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>;
+};
+export declare function friendsStoreConformance(make: () => Promise<FriendsHarness>): FriendsConformanceCase[];

package/dist/friends/conformance.js

@@ -0,0 +1,229 @@
+// 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 } from "./types.js";
+function check(ok, message) {
+    if (!ok)
+        throw new Error(message);
+}
+/** A player id the suite can find in any text. */
+const id = (n) => `player-id-${n}-7f3e`;
+const NAMES = {};
+const directory = {
+    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]]));
+    },
+};
+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, status, what) {
+    try {
+        await p;
+    }
+    catch (e) {
+        check(e instanceof FriendsError, `${what}: expected a FriendsError, got ${String(e)}`);
+        check(e.status === status, `${what}: expected ${status}, got ${e.status} (${e.message})`);
+        return;
+    }
+    throw new Error(`${what}: expected a refusal`);
+}
+export function friendsStoreConformance(make) {
+    const cases = [];
+    const add = (name, run) => cases.push({ name, run: async () => run(await make(), Date.now()) });
+    const view = (h, who, now) => h.store.view(who, directory, now);
+    const row = async (h, who, name, now) => (await view(h, who, now)).people.find((r) => r.name === name);
+    const friends = async (h, x, y, now) => {
+        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/dist/friends/handler.d.ts

@@ -0,0 +1,31 @@
+import { 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 declare const FRIENDS_LIMITS: {
+    /** Calls of one player (reads and writes together). */
+    readonly calls: {
+        readonly limit: 30;
+        readonly windowMs: 60000;
+    };
+    /** The biggest body of a POST. */
+    readonly bodyMax: 1024;
+    /** The longest name a request may send. */
+    readonly nameMax: 64;
+};
+export declare function createFriendsHandler(options: FriendsHandlerOptions): {
+    base: string;
+    handle(request: Request): Promise<Response | null>;
+};