nixamp 0.29.1 → 0.30.3

package/src/station-runner.ts

@@ -0,0 +1,244 @@
+/**
+ * Keeping stations on the air: start, stop, skip, and coming back after
+ * something went wrong.
+ *
+ * The runner owns the gap between what the owner asked for and what is
+ * happening. A station that should be running and is not is restarted with a
+ * growing delay (RECOVERY_DELAYS_MS), then tried every OFFLINE_RETRY_MS for as
+ * long as it is still wanted, so a disk that comes back or a file put back in
+ * place brings it back under the same id and link. A station its owner
+ * stopped is never restarted by anything here.
+ */
+import type { Channels, ChannelInfo, PullResume } from "./channels.ts";
+import {
+  EXCLUDE_AFTER, OFFLINE_RETRY_MS, RECOVERY_DELAYS_MS, StationError, channelOf, insideRoots, shuffled,
+  stationOfChannel, type Observed, type Station, type StationStore,
+} from "./stations.ts";
+
+export interface RunnerDeps {
+  store: StationStore;
+  channels: Channels;
+  /** Put a list of files on the air as this channel; false when it could not. */
+  pull: (channelId: string, name: string, files: string[], known: { rotation: NonNullable<PullResume["rotation"]>; audioBitrate: number }) => Promise<boolean>;
+  /** The folders a station's files have to be inside. */
+  roots: () => string[];
+  log?: (line: string) => void;
+  now?: () => number;
+}
+
+/** Something a listener is connected through, that can be ended. */
+export interface Ending {
+  end(): void;
+}
+
+/** A run shorter than this that ends badly does not reset the backoff. */
+const HEALTHY_RUN_MS = 60_000;
+
+export class StationRunner {
+  private attempts = new Map<string, number>();
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private startedAt = new Map<string, number>();
+  private stopping = new Set<string>();
+  private starting = new Set<string>();
+  private errors = new Map<string, string>();
+  private listening = new Map<string, Set<Ending>>();
+
+  constructor(private readonly deps: RunnerDeps) {}
+
+  private now(): number {
+    return this.deps.now?.() ?? Date.now();
+  }
+
+  private log(line: string): void {
+    this.deps.log?.(line);
+  }
+
+  /** The station's files that are still where they were, inside the library. */
+  playable(station: Station): string[] {
+    const roots = this.deps.roots();
+    return station.items.filter((file) => insideRoots(file, roots));
+  }
+
+  /** Wanted on, and put on. */
+  async start(id: string): Promise<Station> {
+    const station = this.deps.store.get(id);
+    if (!station) throw new StationError("not_found", "no such station", 404);
+    if (this.playable(station).length === 0) {
+      throw new StationError("nothing_playable", "none of this station's files can be found in the library", 409);
+    }
+    this.deps.store.setDesired(id, "running", this.now());
+    this.cancelRecovery(id);
+    this.attempts.delete(id);
+    await this.launch(id);
+    return this.deps.store.get(id)!;
+  }
+
+  /** Wanted off, and taken off. Stays off across restarts. */
+  stop(id: string): Station {
+    const station = this.deps.store.setDesired(id, "stopped", this.now());
+    this.cancelRecovery(id);
+    this.attempts.delete(id);
+    this.errors.delete(id);
+    const channelId = channelOf(id);
+    if (this.deps.channels.has(channelId)) {
+      this.stopping.add(channelId);
+      this.deps.channels.stop(channelId);
+    }
+    return station;
+  }
+
+  /** The next track, now. */
+  skip(id: string): void {
+    if (!this.deps.store.get(id)) throw new StationError("not_found", "no such station", 404);
+    if (!this.deps.channels.skip(channelOf(id))) throw new StationError("not_live", "the station is not playing", 409);
+  }
+
+  /** Stopped and forgotten. */
+  remove(id: string): void {
+    if (!this.deps.store.get(id)) throw new StationError("not_found", "no such station", 404);
+    this.stop(id);
+    this.revoke(id);
+    this.deps.store.remove(id);
+  }
+
+  /** Put back every station that was running when this server last stopped. */
+  restore(): void {
+    for (const station of this.deps.store.list()) {
+      if (station.desired !== "running") continue;
+      this.log(`  Putting station "${station.name}" back on the air.`);
+      void this.launch(station.id);
+    }
+  }
+
+  private async launch(id: string): Promise<boolean> {
+    const station = this.deps.store.get(id);
+    if (!station || station.desired !== "running") return false;
+    const channelId = channelOf(id);
+    if (this.deps.channels.has(channelId) || this.starting.has(id)) return true;
+    const files = this.playable(station);
+    if (files.length === 0) {
+      this.errors.set(id, "none of this station's files can be found in the library");
+      this.scheduleRecovery(id);
+      return false;
+    }
+    this.starting.add(id);
+    const store = this.deps.store;
+    try {
+      const ok = await this.deps.pull(channelId, station.name, files, {
+        audioBitrate: station.bitrate,
+        rotation: {
+          repeat: station.repeat,
+          passOver: true,
+          // Read at every pass, so turning shuffle on or off lands then.
+          order: (length) => (store.get(id)?.shuffle ? shuffled(length) : [...Array(length).keys()]),
+          // Read at every track, so an edit lands on the next one.
+          current: () => {
+            const now = store.get(id);
+            return now ? this.playable(now) : [];
+          },
+          excluded: (file) => store.isExcluded(id, file),
+          onFailure: ({ file, reason }) => {
+            this.errors.set(id, reason);
+            if (store.recordFailure(id, file)) {
+              this.log(`  Station "${station.name}": left out a file that failed ${EXCLUDE_AFTER} times.`);
+            }
+          },
+        },
+      });
+      if (!ok) {
+        this.errors.set(id, "the station could not start");
+        this.scheduleRecovery(id);
+        return false;
+      }
+      this.startedAt.set(id, this.now());
+      this.deps.channels.keep(channelId);
+      return true;
+    } catch (error) {
+      this.errors.set(id, error instanceof Error ? error.message : String(error));
+      this.scheduleRecovery(id);
+      return false;
+    } finally {
+      this.starting.delete(id);
+    }
+  }
+
+  /** Told by the server when any channel ends. */
+  onChannelEnd(info: ChannelInfo): void {
+    const id = stationOfChannel(info.id);
+    if (!id) return;
+    if (this.stopping.delete(info.id)) return;
+    const station = this.deps.store.get(id);
+    if (!station || station.desired !== "running") return;
+    // A list that is not repeated played through: that is the end of it,
+    // which is the owner's choice, not a failure.
+    if (info.ended && !station.repeat) {
+      this.deps.store.setDesired(id, "stopped", this.now());
+      this.errors.delete(id);
+      return;
+    }
+    const ran = this.now() - (this.startedAt.get(id) ?? 0);
+    if (ran >= HEALTHY_RUN_MS) this.attempts.delete(id);
+    this.errors.set(id, info.error || "the station stopped");
+    this.scheduleRecovery(id);
+  }
+
+  private scheduleRecovery(id: string): void {
+    if (this.timers.has(id)) return;
+    const attempt = this.attempts.get(id) ?? 0;
+    const delay = attempt < RECOVERY_DELAYS_MS.length ? RECOVERY_DELAYS_MS[attempt]! : OFFLINE_RETRY_MS;
+    this.attempts.set(id, attempt + 1);
+    const timer = setTimeout(() => {
+      this.timers.delete(id);
+      void this.launch(id);
+    }, delay);
+    timer.unref?.();
+    this.timers.set(id, timer);
+  }
+
+  private cancelRecovery(id: string): void {
+    const timer = this.timers.get(id);
+    if (timer) clearTimeout(timer);
+    this.timers.delete(id);
+  }
+
+  observed(id: string): Observed {
+    const station = this.deps.store.get(id);
+    if (!station) return "stopped";
+    if (station.desired === "stopped") return "stopped";
+    if (this.starting.has(id)) return "starting";
+    const info = this.deps.channels.info(channelOf(id));
+    if (info) return info.redials ? "recovering" : "live";
+    return (this.attempts.get(id) ?? 0) <= RECOVERY_DELAYS_MS.length && this.timers.has(id) ? "recovering" : "offline";
+  }
+
+  error(id: string): string {
+    return this.errors.get(id) ?? "";
+  }
+
+  /** A listener on a station's link, ended if the link is revoked. */
+  track(id: string, listener: Ending): () => void {
+    let set = this.listening.get(id);
+    if (!set) {
+      set = new Set();
+      this.listening.set(id, set);
+    }
+    set.add(listener);
+    return () => set!.delete(listener);
+  }
+
+  listeners(id: string): number {
+    return this.listening.get(id)?.size ?? 0;
+  }
+
+  /** Everybody listening through a link that no longer works is let go. */
+  revoke(id: string): number {
+    const set = this.listening.get(id);
+    if (!set) return 0;
+    const count = set.size;
+    for (const one of [...set]) {
+      try { one.end(); } catch { /* already gone */ }
+    }
+    set.clear();
+    return count;
+  }
+}

package/src/station-usage.ts

@@ -0,0 +1,20 @@
+/** `nixamp station` usage, apart so `nixamp help station` does not load the client. */
+export const USAGE = `nixamp station — make a collection into a station
+
+  nixamp station list
+  nixamp station create --name NAME (--folder PATH | --items 0,1,2) [--shuffle] [--no-repeat] [--bitrate 128]
+  nixamp station show ID
+  nixamp station status ID
+  nixamp station start ID
+  nixamp station stop ID
+  nixamp station skip ID
+  nixamp station retry ID          try every left-out file again
+  nixamp station publish ID --basis owned|permission|licensed|public-domain [--note TEXT] [--unlisted] [--no-list]
+  nixamp station unpublish ID [--private]
+  nixamp station link ID [--rotate]
+  nixamp station delete ID
+
+  --json        machine-readable output
+  --url, --key  another server, as with \`nixamp admin\`
+
+A new station is private and stopped. Starting it does not publish it.`;

package/src/stations.ts

@@ -0,0 +1,407 @@
+/**
+ * Stations: a collection turned into a program that keeps playing.
+ *
+ * A channel is a running decoder, named for what it plays, and gone when it
+ * stops. A station is the thing a person made and named: which files, in what
+ * rotation, who may hear it, and whether it should be on. Its id is random
+ * and never changes, so its link survives a rename, a restart, a moved file
+ * and a renderer that died; the channel it plays through (`station-<id>`) is
+ * only how it happens to be delivered right now.
+ *
+ * Two states, kept apart. `desired` is what the owner asked for and is
+ * written down; a station deliberately stopped stays stopped after a restart,
+ * and one left running comes back. `observed` is what is actually happening
+ * and is never written down, because it is only true now.
+ *
+ * Who may listen is the station's own business, not the server's. A new
+ * station is private, stopped and unlisted. Its listen token opens its stream,
+ * its now-playing and its picture, and nothing of the library behind it.
+ * Listing it in the public directory is a separate choice from making it
+ * public, and making it public asks first on what basis it may be broadcast.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+
+export type Visibility = "private" | "unlisted" | "public";
+export type Desired = "running" | "stopped";
+export type Observed = "stopped" | "starting" | "live" | "recovering" | "offline";
+
+/** Why the owner may broadcast this publicly. A declaration, not a clearance. */
+export type RightsBasis = "owned" | "permission" | "licensed" | "public-domain";
+export const RIGHTS_BASES: readonly RightsBasis[] = ["owned", "permission", "licensed", "public-domain"];
+
+export interface Rights {
+  basis: RightsBasis;
+  note: string;
+  declaredAt: number;
+  declaredBy: string;
+}
+
+export interface Station {
+  id: string;
+  name: string;
+  description: string;
+  /** Files on this machine, absolute, in the station's own order. */
+  items: string[];
+  shuffle: boolean;
+  repeat: boolean;
+  visibility: Visibility;
+  /** In the public directory. Only a public station can be. */
+  listed: boolean;
+  desired: Desired;
+  /** Opens this station's stream and nothing else. Rotated to revoke a link. */
+  listenToken: string;
+  /** Audio bitrate of the station's rendition, in kbps. */
+  bitrate: number;
+  rights: Rights | null;
+  /** nixamp.com account that made it, "" when made with the control key. */
+  owner: string;
+  /** Files that would not play, and how many times in a row. */
+  failures: Record<string, number>;
+  /** What the caller said made this one, so asking twice makes it once. */
+  idempotencyKey: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Times an item may fail in a row before rotation leaves it out. */
+export const EXCLUDE_AFTER = 3;
+export const DEFAULT_BITRATE = 128;
+export const BITRATES = [64, 96, 128, 160, 192, 256, 320];
+const MAX_ITEMS = 20_000;
+const MAX_NAME = 120;
+const MAX_DESCRIPTION = 500;
+
+/** A station's channel id. */
+export function channelOf(id: string): string {
+  return `station-${id}`;
+}
+
+/** The station a channel id belongs to, or "" for any other channel. */
+export function stationOfChannel(channelId: string): string {
+  return channelId.startsWith("station-") ? channelId.slice("station-".length) : "";
+}
+
+function newId(): string {
+  // Ten characters of base32: short enough to read out, far too many to guess.
+  const alphabet = "abcdefghijkmnpqrstuvwxyz23456789";
+  return [...randomBytes(10)].map((byte) => alphabet[byte % alphabet.length]).join("");
+}
+
+function newToken(): string {
+  return randomBytes(16).toString("base64url");
+}
+
+export function tokensMatch(offered: string, held: string): boolean {
+  const a = Buffer.from(offered);
+  const b = Buffer.from(held);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/** A path inside one of these roots, after symlinks: never outside the library. */
+export function insideRoots(path: string, roots: string[]): boolean {
+  let real: string;
+  try {
+    real = realpathSync(path);
+  } catch {
+    return false;
+  }
+  return roots.some((root) => {
+    let base: string;
+    try {
+      base = realpathSync(root);
+    } catch {
+      return false;
+    }
+    return real === base || real.startsWith(base.endsWith(sep) ? base : base + sep);
+  });
+}
+
+export class StationError extends Error {
+  constructor(readonly code: string, message: string, readonly status = 400) {
+    super(message);
+  }
+}
+
+export interface StationInput {
+  name?: unknown;
+  description?: unknown;
+  items?: unknown;
+  shuffle?: unknown;
+  repeat?: unknown;
+  bitrate?: unknown;
+}
+
+function text(value: unknown, max: number, field: string): string {
+  if (typeof value !== "string") throw new StationError("invalid_" + field, `${field} must be text`);
+  return value.trim().replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, max);
+}
+
+/** The stations of one server, kept in one file beside its keys. */
+export class StationStore {
+  private stations = new Map<string, Station>();
+
+  constructor(
+    private readonly file: string,
+    private readonly io: { read: (path: string) => string | null; write: (path: string, body: string) => void } = {
+      read: (path) => { try { return readFileSync(path, "utf8"); } catch { return null; } },
+      write: (path, body) => {
+        mkdirSync(dirname(path), { recursive: true });
+        const temporary = `${path}.${process.pid}.tmp`;
+        writeFileSync(temporary, body, { mode: 0o600 });
+        renameSync(temporary, path);
+      },
+    },
+  ) {
+    const body = this.io.read(file);
+    if (body === null) return;
+    try {
+      const parsed = JSON.parse(body) as { stations?: Station[] };
+      for (const one of parsed.stations ?? []) {
+        if (one && typeof one.id === "string" && Array.isArray(one.items)) {
+          this.stations.set(one.id, {
+            ...one,
+            failures: one.failures ?? {},
+            bitrate: one.bitrate ?? DEFAULT_BITRATE,
+            rights: one.rights ?? null,
+            owner: one.owner ?? "",
+            description: one.description ?? "",
+            idempotencyKey: one.idempotencyKey ?? "",
+          });
+        }
+      }
+    } catch {
+      // A file that cannot be read is not a reason to refuse to serve. It is
+      // left where it is, and the next write replaces it.
+    }
+  }
+
+  static fileFor(stateDir: string, port: number): string {
+    return join(stateDir, `stations-${port}.json`);
+  }
+
+  private save(): void {
+    this.io.write(this.file, `${JSON.stringify({ version: 1, stations: [...this.stations.values()] }, null, 2)}\n`);
+  }
+
+  list(): Station[] {
+    return [...this.stations.values()].sort((a, b) => a.createdAt - b.createdAt);
+  }
+
+  get(id: string): Station | undefined {
+    return this.stations.get(id);
+  }
+
+  /** New, and always private, stopped and unlisted (RAD-02). */
+  /** The station a create with this key already made. */
+  byIdempotencyKey(key: string): Station | undefined {
+    if (key === "") return undefined;
+    return [...this.stations.values()].find((one) => one.idempotencyKey === key);
+  }
+
+  create(input: StationInput, items: string[], owner: string, now = Date.now(), idempotencyKey = ""): Station {
+    const name = text(input.name ?? "", MAX_NAME, "name");
+    if (name === "") throw new StationError("name_required", "a station needs a name");
+    if (items.length === 0) throw new StationError("empty_station", "choose at least one file that plays");
+    if (items.length > MAX_ITEMS) throw new StationError("too_many_items", `a station holds at most ${MAX_ITEMS} files`);
+    const station: Station = {
+      id: newId(),
+      name,
+      description: input.description === undefined ? "" : text(input.description, MAX_DESCRIPTION, "description"),
+      items,
+      shuffle: input.shuffle === true,
+      repeat: input.repeat !== false,
+      visibility: "private",
+      listed: false,
+      desired: "stopped",
+      listenToken: newToken(),
+      bitrate: this.bitrateFrom(input.bitrate),
+      rights: null,
+      owner,
+      failures: {},
+      idempotencyKey: idempotencyKey.slice(0, 200),
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.stations.set(station.id, station);
+    this.save();
+    return station;
+  }
+
+  private bitrateFrom(value: unknown): number {
+    if (value === undefined) return DEFAULT_BITRATE;
+    if (typeof value !== "number" || !BITRATES.includes(value)) {
+      throw new StationError("invalid_bitrate", `bitrate is one of ${BITRATES.join(", ")} kbps`);
+    }
+    return value;
+  }
+
+  /** Name, words, files and rotation. Who may listen is changed by publish/unpublish. */
+  update(id: string, input: StationInput, items: string[] | null, now = Date.now()): Station {
+    const station = this.require(id);
+    if (input.name !== undefined) {
+      const name = text(input.name, MAX_NAME, "name");
+      if (name === "") throw new StationError("name_required", "a station needs a name");
+      station.name = name;
+    }
+    if (input.description !== undefined) station.description = text(input.description, MAX_DESCRIPTION, "description");
+    if (input.shuffle !== undefined) station.shuffle = input.shuffle === true;
+    if (input.repeat !== undefined) station.repeat = input.repeat !== false;
+    if (input.bitrate !== undefined) station.bitrate = this.bitrateFrom(input.bitrate);
+    if (items !== null) {
+      if (items.length === 0) throw new StationError("empty_station", "a station needs at least one file that plays");
+      if (items.length > MAX_ITEMS) throw new StationError("too_many_items", `a station holds at most ${MAX_ITEMS} files`);
+      station.items = items;
+      // A file taken out and put back is given another chance.
+      station.failures = Object.fromEntries(Object.entries(station.failures).filter(([file]) => items.includes(file)));
+    }
+    station.updatedAt = now;
+    this.save();
+    return station;
+  }
+
+  remove(id: string): boolean {
+    const had = this.stations.delete(id);
+    if (had) this.save();
+    return had;
+  }
+
+  setDesired(id: string, desired: Desired, now = Date.now()): Station {
+    const station = this.require(id);
+    station.desired = desired;
+    station.updatedAt = now;
+    this.save();
+    return station;
+  }
+
+  /**
+   * Who may hear it, and whether the directory lists it. Public needs a
+   * declared basis; listed needs public. Going private mints a new token, so
+   * every link handed out before stops working, and the caller drops the
+   * listeners who used one.
+   */
+  setAccess(
+    id: string,
+    access: { visibility?: unknown; listed?: unknown; rights?: { basis?: unknown; note?: unknown } | null },
+    by: string,
+    now = Date.now(),
+  ): { station: Station; revoked: boolean } {
+    const station = this.require(id);
+    const visibility = access.visibility === undefined ? station.visibility : access.visibility;
+    if (visibility !== "private" && visibility !== "unlisted" && visibility !== "public") {
+      throw new StationError("invalid_visibility", "visibility is private, unlisted or public");
+    }
+    let listed = access.listed === undefined ? station.listed : access.listed === true;
+    if (visibility !== "public") listed = false;
+    if (access.rights) {
+      const basis = access.rights.basis;
+      if (typeof basis !== "string" || !RIGHTS_BASES.includes(basis as RightsBasis)) {
+        throw new StationError("invalid_rights_basis", `the basis is one of ${RIGHTS_BASES.join(", ")}`);
+      }
+      station.rights = {
+        basis: basis as RightsBasis,
+        note: access.rights.note === undefined ? "" : text(access.rights.note, MAX_DESCRIPTION, "note"),
+        declaredAt: now,
+        declaredBy: by,
+      };
+    }
+    if (visibility === "public" && station.rights === null) {
+      throw new StationError(
+        "rights_required",
+        "before a station is public, say on what basis it may be broadcast: owned, permission, licensed or public-domain",
+        409,
+      );
+    }
+    const revoked = visibility === "private" && station.visibility !== "private";
+    station.visibility = visibility;
+    station.listed = listed;
+    if (revoked) station.listenToken = newToken();
+    station.updatedAt = now;
+    this.save();
+    return { station, revoked };
+  }
+
+  /** A new listen link; every earlier one stops working. */
+  rotateToken(id: string, now = Date.now()): Station {
+    const station = this.require(id);
+    station.listenToken = newToken();
+    station.updatedAt = now;
+    this.save();
+    return station;
+  }
+
+  /** One more failure in a row for this file; true when it is now left out. */
+  recordFailure(id: string, file: string): boolean {
+    const station = this.stations.get(id);
+    if (!station) return false;
+    const count = (station.failures[file] ?? 0) + 1;
+    station.failures[file] = count;
+    this.save();
+    return count === EXCLUDE_AFTER;
+  }
+
+  /** Played through: its failures are forgotten. */
+  recordSuccess(id: string, file: string): void {
+    const station = this.stations.get(id);
+    if (!station || station.failures[file] === undefined) return;
+    delete station.failures[file];
+    this.save();
+  }
+
+  /** Every left-out file tried again (the owner's "retry"). */
+  clearFailures(id: string): Station {
+    const station = this.require(id);
+    station.failures = {};
+    this.save();
+    return station;
+  }
+
+  isExcluded(id: string, file: string): boolean {
+    return (this.stations.get(id)?.failures[file] ?? 0) >= EXCLUDE_AFTER;
+  }
+
+  private require(id: string): Station {
+    const station = this.stations.get(id);
+    if (!station) throw new StationError("not_found", "no such station", 404);
+    return station;
+  }
+}
+
+/** A station-wide shuffle: one order for everybody, Fisher-Yates. */
+export function shuffled(length: number, random: () => number = Math.random): number[] {
+  const order = [...Array(length).keys()];
+  for (let index = order.length - 1; index > 0; index--) {
+    const other = Math.floor(random() * (index + 1));
+    [order[index], order[other]] = [order[other]!, order[index]!];
+  }
+  return order;
+}
+
+/**
+ * Restart after an unexpected end: 2 s, doubling, at most a minute apart.
+ * After the last of these the station is offline but still wanted, and is
+ * tried again every OFFLINE_RETRY_MS so a source that comes back is found.
+ */
+export const RECOVERY_DELAYS_MS = [2_000, 4_000, 8_000, 16_000, 32_000, 60_000];
+export const OFFLINE_RETRY_MS = 5 * 60_000;
+
+/** What a listener with the link may see. Never a path, never a token. */
+export interface PublicStation {
+  id: string;
+  name: string;
+  description: string;
+  visibility: Visibility;
+  state: Observed;
+  nowPlaying: { title: string; artist: string; album: string } | null;
+  format: { codec: string; bitrateKbps: number; sampleRate: number; channels: number } | null;
+  listeners: number;
+}
+
+/** What the owner sees: everything but the files' contents. */
+export interface OwnerStation extends Omit<Station, "failures" | "idempotencyKey"> {
+  state: Observed;
+  excluded: string[];
+  listeners: number;
+  error: string;
+}