nixamp 0.2.0 → 0.4.0

package/src/directory.ts

@@ -0,0 +1,362 @@
+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";
+
+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 const ENDED_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** 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;
+}
+
+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: unknown, max: number): string {
+  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: string): URL | null {
+  let url: 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: unknown): Announcement | null {
+  if (typeof input !== "object" || input === null) return null;
+  const record = input as Record<string, unknown>;
+
+  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 {
+  private readonly items = new Map<string, Listing>();
+  /** Streams that stopped, so the phone line can say when. */
+  private readonly ended = new Map<string, Ended>();
+  private 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.
+   */
+  private mirror: { save: (item: Ended) => void; drop: (id: string) => void } | null = null;
+
+  /** Start echoing ended streams somewhere durable. */
+  persistTo(mirror: { save: (item: Ended) => void; drop: (id: string) => void }): void {
+    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: readonly Ended[]): void {
+    for (const item of items) {
+      if (!this.ended.has(item.id) && !this.items.has(item.id)) this.ended.set(item.id, item);
+    }
+  }
+
+  constructor(
+    private readonly ttl = TTL_MS,
+    private readonly now: () => number = Date.now,
+    /** Injected so a test can make a code predictable rather than guess it. */
+    private readonly randomCode: () => string = () =>
+      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.
+     */
+    private readonly onLive: (listing: Listing) => void = () => {},
+  ) {}
+
+  announce(announcement: Announcement, ownerId = ""): Listing {
+    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: 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: string): void {
+    const item = this.items.get(id);
+    if (item !== undefined) this.remember(item);
+    this.items.delete(id);
+  }
+
+  list(): Listing[] {
+    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: string): Listing | undefined {
+    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(): Ended[] {
+    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: string): string {
+    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: string): boolean {
+    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: string): Ended | undefined {
+    this.sweep();
+    return [...this.ended.values()].find((item) => item.code === code);
+  }
+
+  private endedByUrl(url: string): Ended | undefined {
+    return [...this.ended.values()].find((item) => item.url === url);
+  }
+
+  private remember(item: Listing): void {
+    const record: Ended = {
+      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. */
+  private freeCode(): string {
+    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. */
+  private sweep(): void {
+    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/src/durable.ts

@@ -0,0 +1,215 @@
+/**
+ * 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;
+}
+
+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 {
+  private ready: Promise<void> | null = null;
+
+  constructor(
+    private readonly db: Queryable,
+    private readonly onEvent: (message: string) => void = () => {},
+  ) {}
+
+  private async ensure(): Promise<void> {
+    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.
+   */
+  private async quietly(what: string, run: () => Promise<unknown>): Promise<void> {
+    try {
+      await this.ensure();
+      await run();
+    } catch (error) {
+      this.onEvent(`  ${what} did not persist: ${(error as Error).message}`);
+    }
+  }
+
+  async saveEnded(stream: StoredEnded): Promise<void> {
+    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: string): Promise<void> {
+    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: number): Promise<StoredEnded[]> {
+    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 as Error).message}`);
+      return [];
+    }
+  }
+
+  async addReminder(code: string, phone: string): Promise<void> {
+    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: string): Promise<string[]> {
+    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 as Error).message}`);
+      return [];
+    }
+  }
+
+  /** Everyone waiting, by code, to seed a process that has just started. */
+  async loadReminders(): Promise<Map<string, Set<string>>> {
+    const waiting = new Map<string, Set<string>>();
+    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<string>();
+        set.add(phone);
+        waiting.set(code, set);
+      }
+    } catch (error) {
+      this.onEvent(`  could not read reminders: ${(error as Error).message}`);
+    }
+    return waiting;
+  }
+
+  /** Forget what is too old to be worth telling anybody about. */
+  async sweep(endedBefore: number, remindersBefore: Date): Promise<void> {
+    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(),
+      ]);
+    });
+  }
+}