@decentnetwork/beagle-service 0.0.0-stage → 0.2.0

package/dist/users.js

@@ -0,0 +1,429 @@
+import { addressOf, Hub, isThenable, isUserid, KeyedLock, msgOf } from "./util.js";
+export const DEFAULT_PROFILE_GATEWAY = "https://ens-gateway.beaglechat.workers.dev";
+const DAY_MS = 86_400_000;
+const TOUCH_EVERY_MS = 60_000;
+const MAX_FIELD_BYTES = 2000;
+const text = (v, max) => {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim();
+    return s && s.length <= max ? s : s ? s.slice(0, max) : null;
+};
+const isEmpty = (v) => v === undefined || v === null || (typeof v === "string" && v.trim() === "");
+/** Loose shape checks for the two field names nearly every site uses. A site
+ *  that needs more (a confirmation code, a country rule) adds `register.verify`. */
+function builtInCheck(field, value) {
+    if (field === "email") {
+        if (typeof value !== "string" || value.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
+            return "not-an-email";
+    }
+    if (field === "phone") {
+        if (typeof value !== "string" || !/^\+?[0-9][0-9 ().-]{4,30}$/.test(value))
+            return "not-a-phone-number";
+    }
+    return null;
+}
+export function createUsers(opts) {
+    const store = opts.store;
+    const now = opts.now ?? Date.now;
+    const log = opts.log ?? (() => { });
+    const required = [...new Set(opts.register?.required ?? [])];
+    const optional = [...new Set(opts.register?.optional ?? [])].filter((f) => !required.includes(f));
+    const verify = opts.register?.verify;
+    const visitor = opts.visitor ?? {};
+    const gapMs = (visitor.visitGapMinutes ?? 30) * 60_000;
+    const hub = new Hub(log);
+    const lock = new KeyedLock();
+    const lastTouch = new Map();
+    const iso = (t) => new Date(t).toISOString();
+    const blank = (userid) => ({
+        userid,
+        address: null,
+        name: null,
+        avatar: null,
+        punkId: null,
+        door: null,
+        status: "visitor",
+        profile: {},
+        firstSeen: null,
+        lastSeen: null,
+        visits: 0,
+        signIns: 0,
+    });
+    /** What the store handed back, as a record this library can work with. A
+     *  store may hold records that are older than the library, or that another
+     *  program wrote: all that is asked of one is that it is an object. Missing
+     *  fields get the value a new record would have; nothing is written. */
+    function normalise(raw, userid) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        const r = raw;
+        const u = { ...blank(typeof r.userid === "string" && r.userid ? r.userid : userid) };
+        for (const [k, v] of Object.entries(r))
+            if (v !== undefined && k !== "userid")
+                u[k] = v;
+        if (u.status !== "visitor" && u.status !== "registered" && u.status !== "blocked")
+            u.status = "visitor";
+        if (!u.profile || typeof u.profile !== "object" || Array.isArray(u.profile))
+            u.profile = {};
+        if (typeof u.visits !== "number" || !(u.visits >= 0))
+            u.visits = 0;
+        if (typeof u.signIns !== "number" || !(u.signIns >= 0))
+            u.signIns = 0;
+        if (typeof u.firstSeen !== "string" || Number.isNaN(Date.parse(u.firstSeen)))
+            u.firstSeen = null;
+        if (typeof u.lastSeen !== "string" || Number.isNaN(Date.parse(u.lastSeen)))
+            u.lastSeen = null;
+        return u;
+    }
+    /** The top-level fields in which `next` differs from `prev`. */
+    function changeOf(prev, next) {
+        const set = {};
+        const unset = [];
+        for (const [k, v] of Object.entries(next)) {
+            if (v === undefined)
+                continue;
+            if (!prev || JSON.stringify(prev[k]) !== JSON.stringify(v))
+                set[k] = v;
+        }
+        if (prev)
+            for (const k of Object.keys(prev))
+                if (next[k] === undefined && prev[k] !== undefined)
+                    unset.push(k);
+        return { prev, set, unset };
+    }
+    /** Read one record, let `step` decide, write what it decided. One at a time
+     *  per userid in this object; and with a store whose `get` and `put` are
+     *  synchronous, with nothing at all between the read and the write. The
+     *  store gets the changed fields beside the record, so it can leave alone
+     *  what somebody else wrote. */
+    function mutate(userid, step) {
+        const apply = (raw) => {
+            const prev = normalise(raw, userid);
+            const { next, out } = step(prev);
+            if (!next)
+                return out;
+            const done = store.put(next, changeOf(prev, next));
+            return isThenable(done) ? done.then(() => out) : out;
+        };
+        return lock.run(userid, () => {
+            const got = store.get(userid);
+            return isThenable(got) ? got.then(apply) : apply(got);
+        });
+    }
+    const missingOf = (profile) => required.filter((f) => isEmpty(profile?.[f]));
+    /** visitor or registered, from what the profile holds today. */
+    const statusFor = (user) => (missingOf(user.profile).length === 0 ? "registered" : "visitor");
+    function registration(user) {
+        const missing = user.status === "registered" ? [] : missingOf(user.profile);
+        const state = { status: user.status, required, optional, missing, due: false, refused: false };
+        if (user.status !== "visitor")
+            return state;
+        const t = now();
+        let over = false;
+        if (visitor.maxDays !== undefined && user.firstSeen) {
+            const deadline = Date.parse(user.firstSeen) + visitor.maxDays * DAY_MS;
+            state.deadline = iso(deadline);
+            if (t > deadline)
+                over = true;
+        }
+        if (visitor.maxVisits !== undefined) {
+            state.visitsLeft = Math.max(0, visitor.maxVisits - (user.visits || 0));
+            if ((user.visits || 0) > visitor.maxVisits)
+                over = true;
+        }
+        state.due = over;
+        state.refused = over && visitor.then === "refuse";
+        return state;
+    }
+    const get = async (userid) => normalise(await store.get(userid), userid);
+    async function list(filter) {
+        const all = [];
+        for (const raw of await store.list()) {
+            const u = typeof raw?.userid === "string" ? normalise(raw, raw.userid) : null;
+            if (u)
+                all.push(u);
+        }
+        return filter?.status ? all.filter((u) => u.status === filter.status) : all;
+    }
+    function emitLater(event, ...args) {
+        // Never awaited by the caller: a listener (the agent accepting a held
+        // request, a site sending a welcome) must not hold up the HTTP answer,
+        // and must be free to call back into this module.
+        void hub.emit(event, ...args);
+    }
+    async function recordSignIn(userid, hints = {}, info = {}) {
+        if (!isUserid(userid))
+            throw new TypeError("beagle-service: not a userid");
+        const t = now();
+        const { user, events } = await mutate(userid, (prev) => {
+            const events = [];
+            if (prev?.status === "blocked")
+                return { out: { user: prev, events } };
+            const next = { ...blank(userid), ...prev };
+            const first = !prev || !prev.firstSeen;
+            // A blank or malformed hint never replaces a value already held: the
+            // address above all cannot be asked for again.
+            const address = addressOf(userid, hints.address);
+            if (address)
+                next.address = address;
+            const name = text(hints.name, 128);
+            if (name)
+                next.name = name;
+            const avatar = typeof hints.avatar === "string" && hints.avatar.length <= 4096 ? hints.avatar.trim() : "";
+            if (avatar)
+                next.avatar = avatar;
+            if (typeof hints.punkId === "number" && Number.isInteger(hints.punkId) && hints.punkId >= 0 && hints.punkId < 1_000_000) {
+                next.punkId = hints.punkId;
+            }
+            if (info.door)
+                next.door = info.door.slice(0, 200);
+            const origin = typeof info.origin === "string" && info.origin ? info.origin.slice(0, 200) : null;
+            if (origin)
+                next.origin = origin;
+            next.firstSeen ??= iso(t);
+            if (!prev?.lastSeen || t - Date.parse(prev.lastSeen) > gapMs)
+                next.visits = (next.visits || 0) + 1;
+            next.lastSeen = iso(t);
+            next.signIns = (next.signIns || 0) + 1;
+            const was = prev?.status;
+            next.status = statusFor(next);
+            if (next.status === "registered")
+                next.registeredAt ??= iso(t);
+            events.push(() => emitLater("sign-in", next, { first, door: next.door, origin }));
+            if (next.status === "registered" && was !== "registered")
+                events.push(() => emitLater("registered", next));
+            return { next, out: { user: next, events } };
+        });
+        if (events.length)
+            lastTouch.set(userid, t);
+        for (const fire of events)
+            fire();
+        if (opts.importProfile && user.status !== "blocked")
+            void importProfile(userid).catch(() => { });
+        return user;
+    }
+    async function touch(userid) {
+        const t = now();
+        if (t - (lastTouch.get(userid) ?? 0) < TOUCH_EVERY_MS)
+            return get(userid);
+        return mutate(userid, (prev) => {
+            if (!prev || prev.status === "blocked")
+                return { out: prev };
+            lastTouch.set(userid, t);
+            // Another process, or another copy of this object, may have noted it.
+            if (prev.lastSeen && Math.abs(t - Date.parse(prev.lastSeen)) < TOUCH_EVERY_MS)
+                return { out: prev };
+            const next = { ...prev, lastSeen: iso(t) };
+            if (!prev.lastSeen || t - Date.parse(prev.lastSeen) > gapMs)
+                next.visits = (prev.visits || 0) + 1;
+            return { next, out: next };
+        });
+    }
+    async function update(userid, patch) {
+        if (patch.status === "blocked")
+            throw new TypeError("beagle-service: use users.block(userid, why) to block");
+        const { user, fire } = await mutate(userid, (prev) => {
+            if (!prev)
+                throw new Error(`beagle-service: no user ${userid}`);
+            if (prev.status === "blocked" && patch.status)
+                throw new TypeError("beagle-service: use users.unblock(userid) to unblock");
+            const next = {
+                ...prev,
+                ...patch,
+                userid: prev.userid,
+                profile: patch.profile ? { ...prev.profile, ...patch.profile } : prev.profile,
+            };
+            const fire = next.status === "registered" && prev.status !== "registered";
+            if (fire)
+                next.registeredAt ??= iso(now());
+            return { next, out: { user: next, fire } };
+        });
+        if (fire)
+            emitLater("registered", user);
+        return user;
+    }
+    async function register(userid, submitted) {
+        const current = await get(userid);
+        if (!current)
+            return { ok: false, error: "not-found" };
+        if (current.status === "blocked")
+            return { ok: false, error: "blocked" };
+        const body = submitted && typeof submitted === "object" ? submitted : {};
+        const errors = {};
+        const accepted = {};
+        // Checked outside the per-user lock: `verify` is the site's code and may
+        // be slow or call back into users.
+        for (const field of [...required, ...optional]) {
+            if (!Object.prototype.hasOwnProperty.call(body, field))
+                continue;
+            let value = body[field];
+            if (typeof value === "string")
+                value = value.trim();
+            if (isEmpty(value))
+                continue; // a required one is reported as missing below
+            let size = 0;
+            try {
+                size = Buffer.byteLength(JSON.stringify(value));
+            }
+            catch {
+                size = Infinity;
+            }
+            if (size > MAX_FIELD_BYTES) {
+                errors[field] = "too-long";
+                continue;
+            }
+            const bad = builtInCheck(field, value);
+            if (bad) {
+                errors[field] = bad;
+                continue;
+            }
+            if (verify) {
+                let verdict;
+                try {
+                    verdict = await verify(field, value, current, body);
+                }
+                catch (e) {
+                    log(`beagle-service: register.verify threw for "${field}": ${msgOf(e)}`);
+                    verdict = "could-not-verify";
+                }
+                if (verdict === false) {
+                    errors[field] = "not-accepted";
+                    continue;
+                }
+                if (typeof verdict === "string") {
+                    errors[field] = verdict;
+                    continue;
+                }
+                if (verdict && typeof verdict === "object")
+                    value = verdict.value;
+            }
+            accepted[field] = value;
+        }
+        const { result, fire } = await mutate(userid, (prev) => {
+            const no = (result) => ({ out: { result, fire: false } });
+            if (!prev)
+                return no({ ok: false, error: "not-found" });
+            if (prev.status === "blocked")
+                return no({ ok: false, error: "blocked" });
+            const profile = { ...prev.profile, ...accepted };
+            for (const f of missingOf(profile))
+                errors[f] ??= "required";
+            if (Object.keys(errors).length)
+                return no({ ok: false, error: "invalid-fields", fields: errors });
+            const next = { ...prev, profile, status: "registered" };
+            next.registeredAt ??= iso(now());
+            return { next, out: { result: { ok: true, user: next }, fire: prev.status !== "registered" } };
+        });
+        if (fire && result.ok)
+            emitLater("registered", result.user);
+        return result;
+    }
+    async function block(userid, why = "") {
+        if (!isUserid(userid))
+            throw new TypeError("beagle-service: not a userid");
+        const { user, fire } = await mutate(userid, (found) => {
+            const prev = found ?? blank(userid);
+            if (prev.status === "blocked")
+                return { out: { user: prev, fire: false } };
+            const t = now();
+            const next = {
+                ...prev,
+                status: "blocked",
+                blocked: { at: iso(t), why: String(why).slice(0, 1000), was: prev.status },
+                // Sessions issued up to now are dead for good, also after an unblock.
+                sessionsValidFrom: t + 1,
+            };
+            return { next, out: { user: next, fire: true } };
+        });
+        if (fire)
+            emitLater("blocked", user);
+        return user;
+    }
+    async function unblock(userid) {
+        const { user, fire } = await mutate(userid, (prev) => {
+            if (!prev || prev.status !== "blocked")
+                return { out: { user: prev, fire: false } };
+            const next = { ...prev, blocked: null, status: "visitor" };
+            next.status = prev.blocked?.was === "registered" || (prev.firstSeen && statusFor(next) === "registered") ? "registered" : "visitor";
+            return { next, out: { user: next, fire: true } };
+        });
+        if (fire && user)
+            emitLater("unblocked", user);
+        return user;
+    }
+    async function revokeSessions(userid) {
+        await mutate(userid, (prev) => (prev ? { next: { ...prev, sessionsValidFrom: now() + 1 }, out: undefined } : { out: undefined }));
+    }
+    // ── beagles.eth profile import ────────────────────────────────────────────
+    const gateway = (typeof opts.importProfile === "object" && opts.importProfile.gateway) || DEFAULT_PROFILE_GATEWAY;
+    const ttlMs = ((typeof opts.importProfile === "object" && opts.importProfile.ttlHours) || 24) * 3_600_000;
+    const noRecordUntil = new Map();
+    async function importProfile(userid) {
+        if (!isUserid(userid))
+            return null;
+        const t = now();
+        const user = await get(userid);
+        if (!user)
+            return null;
+        if (user.published?.fetchedAt && t - Date.parse(user.published.fetchedAt) < ttlMs)
+            return user.published;
+        if ((noRecordUntil.get(userid) ?? 0) > t)
+            return null;
+        const doFetch = opts.fetch ?? fetch;
+        let record;
+        try {
+            const r = await doFetch(`${gateway.replace(/\/+$/, "")}/getAddress/${userid}`, { signal: AbortSignal.timeout(5000) });
+            if (r.status === 404) {
+                noRecordUntil.set(userid, t + ttlMs);
+                return null;
+            }
+            if (!r.ok)
+                throw new Error(`HTTP ${r.status}`);
+            record = await r.json();
+        }
+        catch (e) {
+            log(`beagle-service: profile import for ${userid.slice(0, 8)} failed: ${msgOf(e)}`);
+            return null;
+        }
+        if (!record || typeof record !== "object" || typeof record.name !== "string") {
+            noRecordUntil.set(userid, t + ttlMs);
+            return null;
+        }
+        const texts = record.texts && typeof record.texts === "object" ? record.texts : {};
+        const published = { fetchedAt: iso(t) };
+        const put = (k, v, max) => {
+            const s = text(v, max);
+            if (s)
+                published[k] = s;
+        };
+        put("name", record.name, 255);
+        put("owner", record.owner, 128);
+        put("displayName", texts.displayName, 128);
+        put("description", texts.description, 1000);
+        put("avatar", texts.avatar, 2048);
+        put("url", texts.url, 2048);
+        const patch = { published };
+        // The record's address is a claim like the sign-in hint: used only when
+        // none is held, and only when it parses to this userid.
+        const address = addressOf(userid, texts.carrierAddress);
+        if (!user.address && address)
+            patch.address = address;
+        await update(userid, patch).catch(() => { });
+        return published;
+    }
+    return {
+        get,
+        list,
+        update,
+        block,
+        unblock,
+        revokeSessions,
+        register,
+        registration,
+        recordSignIn,
+        touch,
+        importProfile,
+        on: (event, cb) => hub.on(event, cb),
+    };
+}

package/dist/util.d.ts

@@ -0,0 +1,48 @@
+/** Write JSON so a crash leaves either the old file or the new one, never half
+ *  of one: write a sibling temp file, fsync it, rename it over the target. */
+export declare function atomicWriteJson(file: string, value: unknown, mode?: number): void;
+/** Read a JSON file. A missing file is the fallback; a file that is there but
+ *  does not parse throws, because treating it as empty would let the next
+ *  write replace real data with nothing. */
+export declare function readJsonFile<T>(file: string, fallback: T): T;
+/** One JSON object in one file, shared by every store instance and every
+ *  process that opens it (a server and the operator's command beside it, or a
+ *  module a bundler evaluated twice). A read looks at the file's identity
+ *  first and loads it again when another writer replaced it; a change is made
+ *  under a lock file, on the copy that is on disk at that moment, and written
+ *  with a rename. All of it is synchronous: no other code of this process runs
+ *  between the read and the write. */
+export declare class SharedJsonFile<T extends Record<string, any>> {
+    #private;
+    constructor(file: string);
+    /** The current content. Do not change it; use `update`. */
+    read(): T;
+    /** Change the content. `change` gets what is on disk now and says whether
+     *  it has to be written. */
+    update<R>(change: (value: T) => {
+        write: boolean;
+        result: R;
+    }): R;
+}
+export declare const isThenable: <T>(v: T | PromiseLike<T>) => v is PromiseLike<T>;
+/** A userid is the base58 of a 32-byte public key. */
+export declare function isUserid(v: unknown): v is string;
+/** The address when it is a well-formed Carrier address of `userid`, else null.
+ *  An address is not signed at sign-in, so the only thing that can be checked
+ *  is that it parses (key, nospam, checksum) and names the key that signed. */
+export declare function addressOf(userid: string, address: unknown): string | null;
+export declare const msgOf: (e: unknown) => string;
+export type Logger = (message: string) => void;
+/** A minimal typed event hub; a listener that throws never breaks the emitter. */
+export declare class Hub<Events extends Record<string, unknown[]>> {
+    #private;
+    constructor(log?: Logger);
+    on<K extends keyof Events>(event: K, cb: (...args: Events[K]) => unknown): () => void;
+    /** Runs listeners in registration order and waits for each. */
+    emit<K extends keyof Events>(event: K, ...args: Events[K]): Promise<void>;
+}
+/** Run jobs for the same key one after another. */
+export declare class KeyedLock {
+    #private;
+    run<T>(key: string, job: () => T | PromiseLike<T>): Promise<T>;
+}

package/dist/util.js

@@ -0,0 +1,208 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { base58ToBytes, carrierIdFromAddress } from "@decentnetwork/peer";
+/** Write JSON so a crash leaves either the old file or the new one, never half
+ *  of one: write a sibling temp file, fsync it, rename it over the target. */
+export function atomicWriteJson(file, value, mode = 0o600) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    const fd = openSync(tmp, "w", mode);
+    try {
+        writeSync(fd, JSON.stringify(value, null, 2));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, file);
+}
+/** Read a JSON file. A missing file is the fallback; a file that is there but
+ *  does not parse throws, because treating it as empty would let the next
+ *  write replace real data with nothing. */
+export function readJsonFile(file, fallback) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return fallback;
+        throw e;
+    }
+    if (raw.trim() === "")
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`beagle-service: ${file} is not valid JSON (${e.message}); fix or move it before starting`);
+    }
+}
+const LOCK_STALE_MS = 5_000;
+const LOCK_WAIT_MS = 3_000;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+/** One JSON object in one file, shared by every store instance and every
+ *  process that opens it (a server and the operator's command beside it, or a
+ *  module a bundler evaluated twice). A read looks at the file's identity
+ *  first and loads it again when another writer replaced it; a change is made
+ *  under a lock file, on the copy that is on disk at that moment, and written
+ *  with a rename. All of it is synchronous: no other code of this process runs
+ *  between the read and the write. */
+export class SharedJsonFile {
+    #file;
+    #value;
+    #seen = "";
+    constructor(file) {
+        this.#file = file;
+        this.#load();
+    }
+    #identity() {
+        try {
+            const s = statSync(this.#file);
+            return `${s.ino}:${s.size}:${s.mtimeMs}`;
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return "";
+            throw e;
+        }
+    }
+    #load() {
+        const seen = this.#identity();
+        // A null prototype: a key such as "__proto__" is a key like any other.
+        this.#value = Object.assign(Object.create(null), readJsonFile(this.#file, {}));
+        this.#seen = seen;
+    }
+    /** The current content. Do not change it; use `update`. */
+    read() {
+        if (this.#identity() !== this.#seen)
+            this.#load();
+        return this.#value;
+    }
+    /** Change the content. `change` gets what is on disk now and says whether
+     *  it has to be written. */
+    update(change) {
+        mkdirSync(dirname(this.#file), { recursive: true });
+        const lock = `${this.#file}.lock`;
+        const waitUntil = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
+            try {
+                closeSync(openSync(lock, "wx", 0o600));
+                break;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                let age = 0;
+                try {
+                    age = Date.now() - statSync(lock).mtimeMs;
+                }
+                catch {
+                    continue; // released in between
+                }
+                // A writer holds the lock for a few milliseconds. One this old was
+                // left by a process that died while holding it.
+                if (age > LOCK_STALE_MS || Date.now() > waitUntil) {
+                    try {
+                        unlinkSync(lock);
+                    }
+                    catch {
+                        /* someone else removed it */
+                    }
+                    continue;
+                }
+                Atomics.wait(sleepCell, 0, 0, 5);
+            }
+        }
+        try {
+            const value = this.read();
+            const { write, result } = change(value);
+            if (write) {
+                atomicWriteJson(this.#file, value);
+                this.#seen = this.#identity();
+            }
+            return result;
+        }
+        catch (e) {
+            // `change` may have altered the copy in memory before it threw.
+            this.#seen = "\0";
+            throw e;
+        }
+        finally {
+            try {
+                unlinkSync(lock);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+}
+export const isThenable = (v) => !!v && typeof v.then === "function";
+/** A userid is the base58 of a 32-byte public key. */
+export function isUserid(v) {
+    if (typeof v !== "string" || v.length < 32 || v.length > 64)
+        return false;
+    try {
+        return base58ToBytes(v).length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/** The address when it is a well-formed Carrier address of `userid`, else null.
+ *  An address is not signed at sign-in, so the only thing that can be checked
+ *  is that it parses (key, nospam, checksum) and names the key that signed. */
+export function addressOf(userid, address) {
+    if (typeof address !== "string" || address.length < 40 || address.length > 80)
+        return null;
+    try {
+        return carrierIdFromAddress(address) === userid ? address : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const msgOf = (e) => e?.message ?? String(e);
+/** A minimal typed event hub; a listener that throws never breaks the emitter. */
+export class Hub {
+    #listeners = new Map();
+    #log;
+    constructor(log = () => { }) {
+        this.#log = log;
+    }
+    on(event, cb) {
+        let set = this.#listeners.get(event);
+        if (!set)
+            this.#listeners.set(event, (set = new Set()));
+        set.add(cb);
+        return () => set.delete(cb);
+    }
+    /** Runs listeners in registration order and waits for each. */
+    async emit(event, ...args) {
+        for (const cb of [...(this.#listeners.get(event) ?? [])]) {
+            try {
+                await cb(...args);
+            }
+            catch (e) {
+                this.#log(`beagle-service: a "${String(event)}" listener threw: ${msgOf(e)}`);
+            }
+        }
+    }
+}
+/** Run jobs for the same key one after another. */
+export class KeyedLock {
+    #tails = new Map();
+    run(key, job) {
+        const prev = this.#tails.get(key) ?? Promise.resolve();
+        const next = prev.then(job, job);
+        const tail = next.catch(() => { });
+        this.#tails.set(key, tail);
+        void tail.then(() => {
+            if (this.#tails.get(key) === tail)
+                this.#tails.delete(key);
+        });
+        return next;
+    }
+}