nixamp 0.2.0 → 0.4.0

package/dist/directory.js

@@ -0,0 +1,275 @@
+import { randomInt } from "node:crypto";
+/**
+ * The public directory.
+ *
+ * A nixamp that agrees to be listed announces itself to nixamp.com every so
+ * often and is forgotten when it stops. There is no database behind it: an
+ * entry lives for a few minutes and a heartbeat renews it, so a restart of the
+ * directory costs one heartbeat rather than a migration, and a stream that
+ * dies falls out of the list without anyone having to notice.
+ *
+ * What is published is the *listen* link. The control key never leaves the
+ * machine it was minted on.
+ */
+/** How long an entry survives without a heartbeat. */
+export const TTL_MS = 4 * 60 * 1000;
+/** How often a publisher renews. Comfortably inside the TTL. */
+export const HEARTBEAT_MS = 90 * 1000;
+export const DEFAULT_DIRECTORY = "https://nixamp.com";
+/** How long an ended stream is still worth telling a caller about. */
+export const ENDED_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_NAME = 60;
+const MAX_TRACK = 120;
+/** Trim and flatten, so one publisher cannot draw a box in someone's terminal. */
+export function clean(value, max) {
+    if (typeof value !== "string")
+        return "";
+    // Control characters include the escape that starts an ANSI sequence, and
+    // this text is rendered in a terminal as well as a browser.
+    return value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, max);
+}
+/**
+ * A URL we are willing to list. It has to be somewhere a browser can go, and
+ * it must not be a loopback or link-local address: those are only reachable
+ * from the machine that published them, so listing one is an entry nobody but
+ * the publisher can ever open.
+ */
+export function publishable(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return null;
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host === "::1" || host.endsWith(".localhost"))
+        return null;
+    if (/^127\./.test(host) || /^169\.254\./.test(host))
+        return null;
+    return url;
+}
+export function parseAnnouncement(input) {
+    if (typeof input !== "object" || input === null)
+        return null;
+    const record = input;
+    const url = typeof record["url"] === "string" ? record["url"] : "";
+    const listen = publishable(url);
+    if (listen === null)
+        return null;
+    // The audio address has to be the same server as the listen link. This one
+    // is played into a telephone call that somebody pays for by the minute, and
+    // an announcement that could name any address on the internet could point
+    // the phone line at any of them. Same origin, or we do not take it.
+    const offered = typeof record["audio"] === "string" ? record["audio"] : "";
+    const parsed = offered ? publishable(offered) : null;
+    const audio = parsed !== null && parsed.origin === listen.origin ? offered : "";
+    const name = clean(record["name"], MAX_NAME);
+    const tracks = Number(record["tracks"]);
+    return {
+        ...(typeof record["id"] === "string" ? { id: clean(record["id"], 40) } : {}),
+        name: name || "a nixamp",
+        url,
+        ...(audio ? { audio } : {}),
+        tracks: Number.isFinite(tracks) && tracks >= 0 ? Math.min(1_000_000, Math.floor(tracks)) : 0,
+        nowPlaying: clean(record["nowPlaying"], MAX_TRACK),
+    };
+}
+/**
+ * The registry. In memory on purpose: see the note at the top of the file.
+ * One entry per URL, so a publisher restarting does not leave a ghost of
+ * itself behind next to the entry that replaced it.
+ */
+export class Directory {
+    ttl;
+    now;
+    randomCode;
+    onLive;
+    items = new Map();
+    /** Streams that stopped, so the phone line can say when. */
+    ended = new Map();
+    sequence = 0;
+    /**
+     * Somewhere to echo the ended list, so it survives a restart.
+     *
+     * Attached after construction rather than taken as a constructor argument:
+     * this is a mirror, not a dependency, and the directory works exactly as it
+     * did without one.
+     */
+    mirror = null;
+    /** Start echoing ended streams somewhere durable. */
+    persistTo(mirror) {
+        this.mirror = mirror;
+    }
+    /**
+     * Put back what a previous process knew.
+     *
+     * Only fills gaps: anything already here was announced since we started and
+     * is newer than a row written before the restart.
+     */
+    seedEnded(items) {
+        for (const item of items) {
+            if (!this.ended.has(item.id) && !this.items.has(item.id))
+                this.ended.set(item.id, item);
+        }
+    }
+    constructor(ttl = TTL_MS, now = Date.now, 
+    /** Injected so a test can make a code predictable rather than guess it. */
+    randomCode = () => String(randomInt(0, 1_000_000)).padStart(6, "0"), 
+    /**
+     * Called when a stream starts, and only then.
+     *
+     * A publisher announces every ninety seconds for as long as it is up, so
+     * "announced" is not "went live" -- telling followers on every heartbeat
+     * would be telling them forty times an hour. This fires on the transition
+     * and not on the renewals that follow it.
+     */
+    onLive = () => { }) {
+        this.ttl = ttl;
+        this.now = now;
+        this.randomCode = randomCode;
+        this.onLive = onLive;
+    }
+    announce(announcement, ownerId = "") {
+        this.sweep();
+        const existing = [...this.items.values()].find((item) => item.url === announcement.url);
+        // A stream coming back after a gap keeps the code it had, so a caller who
+        // was told "call back later" can key the same six digits and get through.
+        const previously = existing ?? this.endedByUrl(announcement.url);
+        const id = previously?.id ?? `s${++this.sequence}${this.now().toString(36)}`;
+        const code = previously?.code ?? this.freeCode();
+        if (this.ended.has(id)) {
+            this.ended.delete(id);
+            this.mirror?.drop(id);
+        }
+        const listing = {
+            id,
+            code,
+            name: announcement.name,
+            // A returning stream keeps the owner it had, so a heartbeat that omits
+            // it cannot orphan a listing people are following.
+            ownerId: ownerId || existing?.ownerId || previously?.ownerId || "",
+            url: announcement.url,
+            // A heartbeat that omits it keeps what we had, the same as the owner: an
+            // older publisher renewing an entry should not blank the address the
+            // phone line is playing from.
+            audio: announcement.audio ?? existing?.audio ?? "",
+            tracks: announcement.tracks,
+            nowPlaying: announcement.nowPlaying,
+            updatedAt: this.now(),
+            // A stream that never stopped keeps its original start. One that did
+            // starts again now, because that is what a caller is being told about.
+            startedAt: existing?.startedAt ?? this.now(),
+        };
+        this.items.set(id, listing);
+        // The transition, not the heartbeat: existing means it was already live.
+        if (existing === undefined)
+            this.onLive(listing);
+        return listing;
+    }
+    withdraw(id) {
+        const item = this.items.get(id);
+        if (item !== undefined)
+            this.remember(item);
+        this.items.delete(id);
+    }
+    list() {
+        this.sweep();
+        return [...this.items.values()].sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+    }
+    /** The live stream on this code, if there is one. */
+    liveByCode(code) {
+        this.sweep();
+        return [...this.items.values()].find((item) => item.code === code);
+    }
+    /**
+     * Streams that stopped recently, most recent first.
+     *
+     * Kept for the phone line, which has to say when a stream ended -- but they
+     * answer a second question the live list cannot: who is there to follow.
+     * Following exists to hear about broadcasts you would otherwise miss, and a
+     * directory that only lists what is on can only be used to follow somebody
+     * during a broadcast you did not miss.
+     */
+    recentlyEnded() {
+        this.sweep();
+        const live = new Set([...this.items.values()].map((item) => item.id));
+        return [...this.ended.values()]
+            .filter((item) => !live.has(item.id))
+            .sort((a, b) => b.endedAt - a.endedAt);
+    }
+    /** The name last used by an account, live or recently ended. */
+    nameOf(ownerId) {
+        if (!ownerId)
+            return "";
+        this.sweep();
+        const live = [...this.items.values()].find((item) => item.ownerId === ownerId);
+        if (live)
+            return live.name;
+        const ended = [...this.ended.values()]
+            .filter((item) => item.ownerId === ownerId)
+            .sort((a, b) => b.endedAt - a.endedAt)[0];
+        return ended?.name ?? "";
+    }
+    /** Whether this account is streaming right now. */
+    isLive(ownerId) {
+        if (!ownerId)
+            return false;
+        this.sweep();
+        return [...this.items.values()].some((item) => item.ownerId === ownerId);
+    }
+    /** The stream that used to be on this code, if it stopped recently. */
+    endedByCode(code) {
+        this.sweep();
+        return [...this.ended.values()].find((item) => item.code === code);
+    }
+    endedByUrl(url) {
+        return [...this.ended.values()].find((item) => item.url === url);
+    }
+    remember(item) {
+        const record = {
+            id: item.id,
+            code: item.code,
+            name: item.name,
+            ownerId: item.ownerId,
+            url: item.url,
+            nowPlaying: item.nowPlaying,
+            startedAt: item.startedAt,
+            endedAt: item.updatedAt,
+        };
+        this.ended.set(item.id, record);
+        this.mirror?.save(record);
+    }
+    /** A code no live and no recently-ended stream is using. */
+    freeCode() {
+        for (let tries = 0; tries < 40; tries += 1) {
+            const code = this.randomCode();
+            if (code.length !== 6)
+                continue;
+            const taken = [...this.items.values()].some((i) => i.code === code) ||
+                [...this.ended.values()].some((i) => i.code === code);
+            if (!taken)
+                return code;
+        }
+        return "";
+    }
+    /** Forget anything that stopped renewing, keeping a note of when it did. */
+    sweep() {
+        const cutoff = this.now() - this.ttl;
+        for (const [id, item] of this.items) {
+            if (item.updatedAt < cutoff) {
+                this.remember(item);
+                this.items.delete(id);
+            }
+        }
+        const forget = this.now() - ENDED_TTL_MS;
+        for (const [id, item] of this.ended) {
+            if (item.endedAt < forget) {
+                this.ended.delete(id);
+                this.mirror?.drop(id);
+            }
+        }
+    }
+}

package/dist/durable.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The two pieces of state that were promises, and were only in memory.
+ *
+ * Most of nixamp is deliberately ephemeral. The directory is a four-minute TTL
+ * and a heartbeat, because a stream that stops is a stream nobody is hearing,
+ * and a restart costs one heartbeat rather than a migration. That reasoning is
+ * right for what is on. It is wrong for two things that outlived their stream
+ * on purpose:
+ *
+ *   A caller who pressed 1 was told "we will text you when they are live
+ *   again". That subscription lived in a Map, so a deploy dropped it and the
+ *   text never came -- and nothing anywhere said so. A promise made on a phone
+ *   call and quietly forgotten is worse than never offering it.
+ *
+ *   A stream that ended is what the phone line reads back ("ended at 9:27 PM
+ *   Pacific") and what the directory offers to follow when nobody is on. After
+ *   a deploy the code a caller had been told to key would find nothing and
+ *   open an empty room instead.
+ *
+ * This is a mirror rather than a replacement. The in-memory maps stay exactly
+ * as they were -- so every caller stays synchronous and every existing test
+ * still describes the same object -- and each write is echoed here, with the
+ * contents read back once at boot. The cost of that choice is that two
+ * instances would each hold their own copy; nixamp.com runs one, and a second
+ * would need this to become the source of truth rather than the mirror.
+ */
+import type { Queryable } from "./follows.ts";
+export interface StoredEnded {
+    id: string;
+    code: string;
+    name: string;
+    ownerId: string;
+    url: string;
+    nowPlaying: string;
+    startedAt: number;
+    endedAt: number;
+}
+export declare class Durable {
+    private readonly db;
+    private readonly onEvent;
+    private ready;
+    constructor(db: Queryable, onEvent?: (message: string) => void);
+    private ensure;
+    /**
+     * Nothing here is worth taking a request down for.
+     *
+     * These are all mirror writes: the in-memory copy is what the request is
+     * answered from, so a database that is briefly unreachable should cost the
+     * durability and not the feature.
+     */
+    private quietly;
+    saveEnded(stream: StoredEnded): Promise<void>;
+    /** A stream that came back, or one old enough to forget. */
+    dropEnded(id: string): Promise<void>;
+    /** What ended since `since`, oldest first so replaying it rebuilds the order. */
+    loadEnded(since: number): Promise<StoredEnded[]>;
+    addReminder(code: string, phone: string): Promise<void>;
+    /**
+     * Take everyone waiting on a code, and stop them waiting, in one statement.
+     *
+     * `DELETE ... RETURNING` rather than a select and then a delete: the rows
+     * come back as they are removed, so two goings-live at once cannot both read
+     * the same list and text everybody twice.
+     */
+    takeReminders(code: string): Promise<string[]>;
+    /** Everyone waiting, by code, to seed a process that has just started. */
+    loadReminders(): Promise<Map<string, Set<string>>>;
+    /** Forget what is too old to be worth telling anybody about. */
+    sweep(endedBefore: number, remindersBefore: Date): Promise<void>;
+}

package/dist/durable.js

@@ -0,0 +1,156 @@
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ended_streams (
+    id           TEXT PRIMARY KEY,
+    code         TEXT NOT NULL,
+    name         TEXT NOT NULL DEFAULT '',
+    owner_id     TEXT NOT NULL DEFAULT '',
+    url          TEXT NOT NULL DEFAULT '',
+    now_playing  TEXT NOT NULL DEFAULT '',
+    started_at   BIGINT NOT NULL,
+    ended_at     BIGINT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS ended_streams_code ON ended_streams (code);
+
+  CREATE TABLE IF NOT EXISTS stream_reminders (
+    code        TEXT NOT NULL,
+    phone       TEXT NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (code, phone)
+  );
+`;
+export class Durable {
+    db;
+    onEvent;
+    ready = null;
+    constructor(db, onEvent = () => { }) {
+        this.db = db;
+        this.onEvent = onEvent;
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    /**
+     * Nothing here is worth taking a request down for.
+     *
+     * These are all mirror writes: the in-memory copy is what the request is
+     * answered from, so a database that is briefly unreachable should cost the
+     * durability and not the feature.
+     */
+    async quietly(what, run) {
+        try {
+            await this.ensure();
+            await run();
+        }
+        catch (error) {
+            this.onEvent(`  ${what} did not persist: ${error.message}`);
+        }
+    }
+    async saveEnded(stream) {
+        await this.quietly("an ended stream", () => this.db.query(`INSERT INTO ended_streams
+           (id, code, name, owner_id, url, now_playing, started_at, ended_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+         ON CONFLICT (id) DO UPDATE
+           SET code = EXCLUDED.code,
+               name = EXCLUDED.name,
+               owner_id = EXCLUDED.owner_id,
+               url = EXCLUDED.url,
+               now_playing = EXCLUDED.now_playing,
+               started_at = EXCLUDED.started_at,
+               ended_at = EXCLUDED.ended_at`, [
+            stream.id,
+            stream.code,
+            stream.name,
+            stream.ownerId,
+            stream.url,
+            stream.nowPlaying,
+            stream.startedAt,
+            stream.endedAt,
+        ]));
+    }
+    /** A stream that came back, or one old enough to forget. */
+    async dropEnded(id) {
+        await this.quietly("dropping an ended stream", () => this.db.query("DELETE FROM ended_streams WHERE id = $1", [id]));
+    }
+    /** What ended since `since`, oldest first so replaying it rebuilds the order. */
+    async loadEnded(since) {
+        try {
+            await this.ensure();
+            const { rows } = await this.db.query("SELECT * FROM ended_streams WHERE ended_at >= $1 ORDER BY ended_at", [since]);
+            return rows.map((r) => ({
+                id: String(r["id"] ?? ""),
+                code: String(r["code"] ?? ""),
+                name: String(r["name"] ?? ""),
+                ownerId: String(r["owner_id"] ?? ""),
+                url: String(r["url"] ?? ""),
+                nowPlaying: String(r["now_playing"] ?? ""),
+                // BIGINT comes back as a string from pg, which sorts and compares
+                // nothing like a number.
+                startedAt: Number(r["started_at"] ?? 0),
+                endedAt: Number(r["ended_at"] ?? 0),
+            }));
+        }
+        catch (error) {
+            this.onEvent(`  could not read ended streams: ${error.message}`);
+            return [];
+        }
+    }
+    async addReminder(code, phone) {
+        if (!code || !phone)
+            return;
+        await this.quietly("a reminder", () => this.db.query(`INSERT INTO stream_reminders (code, phone) VALUES ($1, $2)
+         ON CONFLICT DO NOTHING`, [code, phone]));
+    }
+    /**
+     * Take everyone waiting on a code, and stop them waiting, in one statement.
+     *
+     * `DELETE ... RETURNING` rather than a select and then a delete: the rows
+     * come back as they are removed, so two goings-live at once cannot both read
+     * the same list and text everybody twice.
+     */
+    async takeReminders(code) {
+        if (!code)
+            return [];
+        try {
+            await this.ensure();
+            const { rows } = await this.db.query("DELETE FROM stream_reminders WHERE code = $1 RETURNING phone", [code]);
+            return rows.map((r) => String(r["phone"] ?? "")).filter(Boolean);
+        }
+        catch (error) {
+            this.onEvent(`  could not take reminders: ${error.message}`);
+            return [];
+        }
+    }
+    /** Everyone waiting, by code, to seed a process that has just started. */
+    async loadReminders() {
+        const waiting = new Map();
+        try {
+            await this.ensure();
+            const { rows } = await this.db.query("SELECT code, phone FROM stream_reminders", []);
+            for (const row of rows) {
+                const code = String(row["code"] ?? "");
+                const phone = String(row["phone"] ?? "");
+                if (!code || !phone)
+                    continue;
+                const set = waiting.get(code) ?? new Set();
+                set.add(phone);
+                waiting.set(code, set);
+            }
+        }
+        catch (error) {
+            this.onEvent(`  could not read reminders: ${error.message}`);
+        }
+        return waiting;
+    }
+    /** Forget what is too old to be worth telling anybody about. */
+    async sweep(endedBefore, remindersBefore) {
+        await this.quietly("sweeping", async () => {
+            await this.db.query("DELETE FROM ended_streams WHERE ended_at < $1", [endedBefore]);
+            // A reminder nobody has collected in a month is somebody who has long
+            // since stopped expecting a text.
+            await this.db.query("DELETE FROM stream_reminders WHERE created_at < $1", [
+                remindersBefore.toISOString(),
+            ]);
+        });
+    }
+}

package/dist/follows.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Following a broadcaster, and where to reach the people who do.
+ *
+ * The phone line got here first, and its reminder is a different thing: you
+ * key a code, press 1, and are told once when that particular stream comes
+ * back. It is per-stream, one-shot, and tied to the handset you called from.
+ * That is right for somebody who dialled a number, and useless for somebody
+ * who wants to know whenever a person they like goes live, on whatever device
+ * they happen to be holding.
+ *
+ * So a follow is account to account, and delivery is a set of addresses rather
+ * than a phone number: an email, a phone if they gave one, and any number of
+ * browsers that have granted permission. One person with a laptop, a phone and
+ * a desktop app is three push subscriptions and one account.
+ *
+ * Unlike the rest of nixamp this is durable. The directory can afford to be a
+ * four-minute TTL because a stream that stops is a stream nobody is listening
+ * to; a follow has to outlive the stream by definition -- the whole point is
+ * to be told about a broadcast that is not happening yet.
+ *
+ * The query function is injected rather than a Pool being constructed here, so
+ * a test can describe a database instead of running one.
+ */
+/** The slice of `pg` this needs. Postgres in production, a fake in tests. */
+export interface Queryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/** A browser, desktop app or phone that has granted notification permission. */
+export interface PushTarget {
+    endpoint: string;
+    p256dh: string;
+    auth: string;
+}
+/** Everywhere one follower can be reached. */
+export interface Reachable {
+    accountId: string;
+    email: string;
+    /** E.164, if they gave one. Empty when they never did. */
+    phone: string;
+    /** Whether each channel is on. A follower who wants none is still a follower. */
+    wantsEmail: boolean;
+    wantsSms: boolean;
+    wantsWeb: boolean;
+    push: PushTarget[];
+}
+/** E.164, or nothing. A number we cannot dial is not a number worth storing. */
+export declare function phoneFrom(value: unknown): string;
+export declare class Follows {
+    private readonly db;
+    private ready;
+    constructor(db: Queryable);
+    /** Make the tables, once per process, on first use. */
+    private ensure;
+    follow(followerId: string, streamerId: string): Promise<boolean>;
+    unfollow(followerId: string, streamerId: string): Promise<void>;
+    /** Who this account follows. */
+    following(followerId: string): Promise<string[]>;
+    isFollowing(followerId: string, streamerId: string): Promise<boolean>;
+    followerCount(streamerId: string): Promise<number>;
+    /** Remember a browser that has granted permission. */
+    addPush(accountId: string, target: PushTarget): Promise<void>;
+    /**
+     * Forget a browser.
+     *
+     * Called when somebody turns notifications off, and again when a push is
+     * rejected as gone: a subscription outlives the browser that made it, and
+     * pushing to a dead endpoint forever is how a table becomes mostly rubbish.
+     */
+    removePush(endpoint: string): Promise<void>;
+    setPrefs(accountId: string, prefs: {
+        phone?: string;
+        wantsEmail?: boolean;
+        wantsSms?: boolean;
+        wantsWeb?: boolean;
+    }): Promise<void>;
+    prefs(accountId: string): Promise<{
+        phone: string;
+        wantsEmail: boolean;
+        wantsSms: boolean;
+        wantsWeb: boolean;
+    }>;
+    /**
+     * Everyone following this broadcaster, and every way to reach them.
+     *
+     * One query rather than one per follower. A broadcaster with a thousand
+     * followers going live should not be a thousand round trips while the
+     * publisher's heartbeat waits on the response.
+     */
+    audience(streamerId: string): Promise<Reachable[]>;
+}