nixamp 0.29.1 → 0.30.1

package/src/station-routes.ts

@@ -0,0 +1,301 @@
+/**
+ * /api/v1/stations: making, running and sharing stations.
+ *
+ * Two kinds of caller, kept apart. The owner -- the control key, or the
+ * nixamp.com account that owns this server -- manages: create, edit, start,
+ * stop, skip, share. A listener holds one station's link and may do three
+ * things with it: hear the stream, ask what is on, and fetch an .m3u for
+ * another player. A listener's link never opens the library, another station,
+ * or anything that changes what is playing.
+ *
+ * Errors carry a stable `code` beside the sentence, so the page, the CLI and
+ * an agent over MCP can each tell "rights_required" from "not_found" without
+ * reading English.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Channels } from "./channels.ts";
+import type { StationRunner } from "./station-runner.ts";
+import {
+  StationError, channelOf, tokensMatch, type OwnerStation, type PublicStation, type Station, type StationStore,
+} from "./stations.ts";
+
+/** The three things a station's link opens. */
+const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u)$/;
+
+/** Whether this path is one a station's own link may open, without the server's key. */
+export function isStationListenPath(path: string): boolean {
+  return LISTEN.test(path);
+}
+
+export interface StationContext {
+  store: StationStore;
+  runner: StationRunner;
+  channels: Channels;
+  /** Holds the control key, or is signed in as this server's owner. */
+  canControl: boolean;
+  /** The nixamp.com account asking, "" when it is the control key. */
+  account: string;
+  /** Files chosen by track index or by folder; null when neither was given. */
+  select: (body: { items?: unknown; folder?: unknown }) => string[] | null;
+  /** What the library knows about a file, for now playing. */
+  trackFor: (file: string) => { title: string; artist: string; album: string } | null;
+  /** This server's address as the asker reached it, for links. */
+  base: string;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  readBody: (request: IncomingMessage) => Promise<string>;
+  /** Headers every answer carries (CORS). */
+  headers: Record<string, string>;
+}
+
+function fail(ctx: StationContext, response: ServerResponse, error: unknown): void {
+  if (error instanceof StationError) {
+    ctx.json(response, error.status, { error: error.message, code: error.code });
+    return;
+  }
+  ctx.json(response, 500, { error: error instanceof Error ? error.message : String(error), code: "internal" });
+}
+
+function links(ctx: StationContext, station: Station): { page: string; stream: string; m3u: string; state: string } {
+  const query = `t=${encodeURIComponent(station.listenToken)}`;
+  const at = `${ctx.base}/api/v1/stations/${station.id}`;
+  return {
+    page: `${ctx.base}/station/${station.id}?${query}`,
+    stream: `${at}/stream?${query}`,
+    m3u: `${at}/listen.m3u?${query}`,
+    state: `${at}/state?${query}`,
+  };
+}
+
+/** The file on the air now, as the channel's own encoder last reported it. */
+function nowPlayingFile(ctx: StationContext, station: Station): string {
+  const info = ctx.channels.info(channelOf(station.id));
+  if (!info?.playlist?.length) return "";
+  return info.playlist[info.playlistAt ?? 0] ?? "";
+}
+
+export function publicView(ctx: StationContext, station: Station): PublicStation {
+  const state = ctx.runner.observed(station.id);
+  const file = state === "live" || state === "recovering" ? nowPlayingFile(ctx, station) : "";
+  const track = file ? ctx.trackFor(file) : null;
+  return {
+    id: station.id,
+    name: station.name,
+    description: station.description,
+    visibility: station.visibility,
+    state,
+    // Tags, or nothing: a bare file name is the owner's, not the public's.
+    nowPlaying: track && (track.title || track.artist) ? track : null,
+    format: state === "stopped" || state === "offline" ? null : { codec: "mp3", bitrateKbps: station.bitrate, sampleRate: 48_000, channels: 2 },
+    listeners: ctx.runner.listeners(station.id),
+  };
+}
+
+export function ownerView(ctx: StationContext, station: Station): OwnerStation & { links: ReturnType<typeof links>; nowPlaying: string } {
+  const { failures, idempotencyKey: _key, ...rest } = station;
+  return {
+    ...rest,
+    state: ctx.runner.observed(station.id),
+    excluded: Object.entries(failures).filter(([, count]) => count >= 3).map(([file]) => file),
+    listeners: ctx.runner.listeners(station.id),
+    error: ctx.runner.error(station.id),
+    links: links(ctx, station),
+    nowPlaying: nowPlayingFile(ctx, station),
+  };
+}
+
+/** Answers anything under /api/v1/stations; false when the path is not one. */
+export async function handleStations(
+  request: IncomingMessage,
+  response: ServerResponse,
+  path: string,
+  url: URL,
+  ctx: StationContext,
+): Promise<boolean> {
+  if (path !== "/api/v1/stations" && !path.startsWith("/api/v1/stations/")) return false;
+  const method = request.method ?? "GET";
+
+  const listen = LISTEN.exec(path);
+  if (listen) {
+    const station = ctx.store.get(listen[1]!);
+    const token = url.searchParams.get("t") ?? "";
+    // The same answer for "no such station" and "not with that link", so a
+    // link cannot be used to find out which stations exist.
+    const allowed = station !== undefined &&
+      (ctx.canControl || (station.visibility !== "private" && token !== "" && tokensMatch(token, station.listenToken)));
+    if (!station || !allowed) {
+      ctx.json(response, 404, { error: "no such station, or not with that link", code: "not_found" });
+      return true;
+    }
+    if (method !== "GET" && method !== "HEAD") {
+      ctx.json(response, 405, { error: "a station's link can listen, not drive", code: "method_not_allowed" });
+      return true;
+    }
+    const what = listen[2];
+    if (what === "state") {
+      ctx.json(response, 200, publicView(ctx, station));
+      return true;
+    }
+    if (what === "listen.m3u") {
+      const stream = links(ctx, station).stream;
+      response.writeHead(200, {
+        ...ctx.headers,
+        "content-type": "audio/x-mpegurl; charset=utf-8",
+        "content-disposition": `inline; filename="${station.id}.m3u"`,
+        "cache-control": "no-store",
+      });
+      response.end(`#EXTM3U\n#EXTINF:-1,${station.name.replace(/[\r\n]/g, " ")}\n${stream}\n`);
+      return true;
+    }
+    const channelId = channelOf(station.id);
+    if (!ctx.channels.has(channelId)) {
+      ctx.json(response, 503, { error: "the station is not on the air", code: "not_live", state: ctx.runner.observed(station.id) });
+      return true;
+    }
+    response.writeHead(200, { ...ctx.headers, "content-type": ctx.channels.contentType(channelId), "cache-control": "no-store" });
+    if (method === "HEAD") {
+      response.end();
+      return true;
+    }
+    const detach = ctx.channels.listen(channelId, response);
+    if (detach === null) {
+      response.end();
+      return true;
+    }
+    const untrack = ctx.runner.track(station.id, { end: () => response.destroy() });
+    const leave = (): void => {
+      detach();
+      untrack();
+    };
+    request.on("close", leave);
+    response.on("close", leave);
+    return true;
+  }
+
+  // Everything else is the owner's.
+  if (!ctx.canControl) {
+    ctx.json(response, 403, { error: "only this server's owner manages its stations", code: "forbidden" });
+    return true;
+  }
+
+  const body = async (): Promise<Record<string, unknown>> => {
+    if (method === "GET" || method === "DELETE") return {};
+    const raw = await ctx.readBody(request);
+    if (raw.trim() === "") return {};
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new StationError("bad_json", "the body is not JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new StationError("bad_json", "the body is not a JSON object");
+    return parsed as Record<string, unknown>;
+  };
+
+  try {
+    if (path === "/api/v1/stations") {
+      if (method === "GET") {
+        const all = ctx.store.list();
+        const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit")) || 50));
+        const offset = Math.max(0, Number(url.searchParams.get("offset")) || 0);
+        ctx.json(response, 200, { stations: all.slice(offset, offset + limit).map((one) => ownerView(ctx, one)), total: all.length, limit, offset });
+        return true;
+      }
+      if (method === "POST") {
+        const input = await body();
+        const key = String(request.headers["idempotency-key"] ?? input["idempotencyKey"] ?? "").trim();
+        const again = ctx.store.byIdempotencyKey(key);
+        if (again) {
+          ctx.json(response, 200, { station: ownerView(ctx, again), created: false });
+          return true;
+        }
+        const items = ctx.select(input);
+        if (items === null) throw new StationError("items_required", "choose files by track index (items) or a folder");
+        const station = ctx.store.create(input, items, ctx.account, Date.now(), key);
+        ctx.json(response, 201, { station: ownerView(ctx, station), created: true });
+        return true;
+      }
+      ctx.json(response, 405, { error: "GET or POST", code: "method_not_allowed" });
+      return true;
+    }
+
+    const match = /^\/api\/v1\/stations\/([a-z0-9]{10})(?:\/([a-z-]+))?$/.exec(path);
+    if (!match) {
+      ctx.json(response, 404, { error: "no such station", code: "not_found" });
+      return true;
+    }
+    const id = match[1]!;
+    const action = match[2];
+    const station = ctx.store.get(id);
+    if (!station) {
+      ctx.json(response, 404, { error: "no such station", code: "not_found" });
+      return true;
+    }
+
+    if (action === undefined) {
+      if (method === "GET") {
+        ctx.json(response, 200, { station: ownerView(ctx, station) });
+        return true;
+      }
+      if (method === "PATCH") {
+        const input = await body();
+        const items = ctx.select(input);
+        const updated = ctx.store.update(id, input, items);
+        ctx.json(response, 200, { station: ownerView(ctx, updated) });
+        return true;
+      }
+      if (method === "DELETE") {
+        ctx.runner.remove(id);
+        ctx.json(response, 200, { deleted: id });
+        return true;
+      }
+      ctx.json(response, 405, { error: "GET, PATCH or DELETE", code: "method_not_allowed" });
+      return true;
+    }
+
+    if (method !== "POST") {
+      ctx.json(response, 405, { error: "POST", code: "method_not_allowed" });
+      return true;
+    }
+    if (action === "start") {
+      const started = await ctx.runner.start(id);
+      ctx.json(response, 200, { station: ownerView(ctx, started) });
+      return true;
+    }
+    if (action === "stop") {
+      ctx.json(response, 200, { station: ownerView(ctx, ctx.runner.stop(id)) });
+      return true;
+    }
+    if (action === "skip") {
+      ctx.runner.skip(id);
+      ctx.json(response, 200, { station: ownerView(ctx, station) });
+      return true;
+    }
+    if (action === "retry") {
+      ctx.json(response, 200, { station: ownerView(ctx, ctx.store.clearFailures(id)) });
+      return true;
+    }
+    if (action === "rotate-link") {
+      const rotated = ctx.store.rotateToken(id);
+      const dropped = ctx.runner.revoke(id);
+      ctx.json(response, 200, { station: ownerView(ctx, rotated), dropped });
+      return true;
+    }
+    if (action === "access") {
+      const input = await body();
+      const rights = input["rights"];
+      const { station: changed, revoked } = ctx.store.setAccess(id, {
+        visibility: input["visibility"],
+        listed: input["listed"],
+        rights: typeof rights === "object" && rights !== null ? rights as { basis?: unknown; note?: unknown } : null,
+      }, ctx.account || "control-key");
+      const dropped = revoked ? ctx.runner.revoke(id) : 0;
+      ctx.json(response, 200, { station: ownerView(ctx, changed), dropped });
+      return true;
+    }
+    ctx.json(response, 404, { error: "no such action", code: "not_found" });
+    return true;
+  } catch (error) {
+    fail(ctx, response, error);
+    return true;
+  }
+}

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.`;