nixamp 0.3.0 → 0.4.1

package/dist/directory.d.ts

@@ -18,19 +18,76 @@ export declare const DEFAULT_DIRECTORY = "https://nixamp.com";
 export interface Listing {
     /** Assigned by the directory, so a publisher cannot claim someone else's. */
     id: string;
+    /**
+     * A six-digit code for this stream, stable across the whole run.
+     *
+     * This is what somebody keys into the phone line. It has to be short enough
+     * to read out and survive being remembered, which the id is not.
+     */
+    code: string;
     name: string;
+    /**
+     * The account that announced it.
+     *
+     * Set from the signed-in publisher, never from the announcement body -- a
+     * stream that could name its own owner could name somebody else's, and
+     * followers would be told about a broadcast that person is not making.
+     */
+    ownerId: string;
     /** The listen link, which is what a browser opens. */
     url: string;
+    /**
+     * The same stream as bytes, for something that is not a browser.
+     *
+     * `url` is a share link: it answers 302, sets a cookie and redirects to the
+     * player page. That is exactly right for a person and useless to anything
+     * that cannot hold a cookie -- the phone line hands this address to Telnyx
+     * to play into a call, and Telnyx fetches it once, anonymously, and expects
+     * audio back. Handed the share link it gets a 401 in JSON and the caller
+     * hears silence after being told the stream is about to start.
+     *
+     * So a publisher announces both: the link a person opens, and the address
+     * that answers with audio/mpeg to a plain GET. Empty when the publisher is
+     * an older nixamp that only knows about `url`.
+     */
+    audio: string;
     tracks: number;
     nowPlaying: string;
     /** Set by the directory from the request, never by the publisher. */
     updatedAt: number;
+    /** When this stream first announced itself: the "started at" a caller hears. */
+    startedAt: number;
 }
+/**
+ * A stream that has stopped, kept for a while after it fell out of the list.
+ *
+ * The directory proper forgets a stream the moment it stops renewing, which is
+ * right for a list of what is on -- but it means there is nobody left to say
+ * *when* it ended, and "call back later" with no time in it is not worth
+ * saying. So an ended stream leaves this behind: enough to answer the phone
+ * truthfully, and nothing anybody could listen to.
+ */
+export interface Ended {
+    id: string;
+    code: string;
+    name: string;
+    ownerId: string;
+    /** Kept so a stream returning on the same url is recognised as the same one. */
+    url: string;
+    nowPlaying: string;
+    startedAt: number;
+    /** The last heartbeat we saw, which is as close to "ended" as we can know. */
+    endedAt: number;
+}
+/** How long an ended stream is still worth telling a caller about. */
+export declare const ENDED_TTL_MS: number;
 /** What a publisher sends. Everything else about a listing is ours to decide. */
 export interface Announcement {
     id?: string;
     name: string;
     url: string;
+    /** Where the audio actually is. See `Listing.audio`. */
+    audio?: string;
     tracks: number;
     nowPlaying: string;
 }
@@ -52,12 +109,78 @@ export declare function parseAnnouncement(input: unknown): Announcement | null;
 export declare class Directory {
     private readonly ttl;
     private readonly now;
+    /** Injected so a test can make a code predictable rather than guess it. */
+    private readonly randomCode;
+    /**
+     * 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.
+     */
+    private readonly onLive;
     private readonly items;
+    /** Streams that stopped, so the phone line can say when. */
+    private readonly ended;
     private sequence;
-    constructor(ttl?: number, now?: () => number);
-    announce(announcement: Announcement): Listing;
+    /**
+     * 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.
+     */
+    private mirror;
+    /** Start echoing ended streams somewhere durable. */
+    persistTo(mirror: {
+        save: (item: Ended) => void;
+        drop: (id: string) => void;
+    }): void;
+    /**
+     * 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: readonly Ended[]): void;
+    constructor(ttl?: number, now?: () => number, 
+    /** Injected so a test can make a code predictable rather than guess it. */
+    randomCode?: () => string, 
+    /**
+     * 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?: (listing: Listing) => void);
+    announce(announcement: Announcement, ownerId?: string): Listing;
     withdraw(id: string): void;
     list(): Listing[];
-    /** Forget anything that stopped renewing. */
+    /** The live stream on this code, if there is one. */
+    liveByCode(code: string): Listing | undefined;
+    /**
+     * 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(): Ended[];
+    /** The name last used by an account, live or recently ended. */
+    nameOf(ownerId: string): string;
+    /** Whether this account is streaming right now. */
+    isLive(ownerId: string): boolean;
+    /** The stream that used to be on this code, if it stopped recently. */
+    endedByCode(code: string): Ended | undefined;
+    private endedByUrl;
+    private remember;
+    /** A code no live and no recently-ended stream is using. */
+    private freeCode;
+    /** Forget anything that stopped renewing, keeping a note of when it did. */
     private sweep;
 }

package/dist/directory.js

@@ -1,3 +1,4 @@
+import { randomInt } from "node:crypto";
 /**
  * The public directory.
  *
@@ -15,6 +16,8 @@ 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. */
@@ -53,14 +56,23 @@ export function parseAnnouncement(input) {
         return null;
     const record = input;
     const url = typeof record["url"] === "string" ? record["url"] : "";
-    if (publishable(url) === null)
+    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),
     };
@@ -73,39 +85,191 @@ export function parseAnnouncement(input) {
 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;
-    constructor(ttl = TTL_MS, now = Date.now) {
+    /**
+     * 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) {
+    announce(announcement, ownerId = "") {
         this.sweep();
         const existing = [...this.items.values()].find((item) => item.url === announcement.url);
-        const id = existing?.id ?? `s${++this.sequence}${this.now().toString(36)}`;
+        // 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));
     }
-    /** Forget anything that stopped renewing. */
+    /** 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)
+        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(),
+            ]);
+        });
+    }
+}