nixamp 0.1.0 → 0.3.0

package/src/channels.ts

@@ -0,0 +1,281 @@
+/**
+ * Several streams at once.
+ *
+ * A channel is one live source and everybody listening to it. Two or three
+ * devices can publish at the same time -- a phone, a desktop, a second window
+ * -- and each has its own audience, so a listener picks which one to hear.
+ *
+ * The fan-out is the point. One ffmpeg decodes a publisher's bytes once, and
+ * the MP3 it produces is written to every listener attached to that channel.
+ * A decode per listener would cost a CPU core each and, for a live stream,
+ * would not even agree with itself about what "now" is.
+ *
+ * A listener joining halfway through gets the stream from that moment, which is
+ * what live means. MP3 frames are self-describing, so a player finds the next
+ * frame boundary and carries on; there is nothing to catch up on.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import type { Readable } from "node:stream";
+
+/** Somewhere for a channel's audio to go. A response, in practice. */
+export interface Listener {
+  write(chunk: Buffer): boolean;
+  end(): void;
+}
+
+export interface ChannelInfo {
+  id: string;
+  /** What the publisher called itself. */
+  name: string;
+  /** The container it is sending, e.g. webm from a browser, flv over RTMP. */
+  format: string;
+  /** How it arrived. */
+  via: "http" | "rtmp";
+  startedAt: number;
+  bytes: number;
+  listeners: number;
+}
+
+/** A name that can sit in a URL and be read back in a list. */
+export function cleanId(value: unknown, fallback = "main"): string {
+  if (typeof value !== "string") return fallback;
+  const id = value.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+  return id.slice(0, 40) || fallback;
+}
+
+export interface ChannelOptions {
+  ffmpeg: string[];
+  onStart?: (info: ChannelInfo) => void;
+  onEnd?: (info: ChannelInfo) => void;
+}
+
+/**
+ * One live source, and its audience.
+ *
+ * Everything a listener is sent has been through ffmpeg, so a publisher cannot
+ * decide what bytes reach a browser by choosing what to send.
+ */
+export class Channel {
+  readonly listeners = new Set<Listener>();
+  private child: ChildProcess | null = null;
+  private closing = false;
+
+  constructor(
+    readonly info: ChannelInfo,
+    private readonly options: ChannelOptions,
+    private readonly onGone: (id: string) => void,
+  ) {}
+
+  start(format: string): void {
+    const [command, ...prefix] = this.options.ffmpeg as [string, ...string[]];
+    const child = spawn(
+      command,
+      [
+        ...prefix,
+        "-hide_banner",
+        "-loglevel", "error",
+        // Stated, because ffmpeg mis-probes a live unseekable pipe: it reads a
+        // few kilobytes, guesses, and guesses wrong.
+        "-f", format,
+        "-i", "pipe:0",
+        "-vn",
+        "-c:a", "libmp3lame",
+        "-b:a", "192k",
+        "-f", "mp3",
+        "pipe:1",
+      ],
+      { stdio: ["pipe", "pipe", "pipe"] },
+    );
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      this.info.bytes += chunk.byteLength;
+      this.send(chunk);
+    });
+    // A publisher that hangs up mid-write breaks the pipe, and an unhandled
+    // EPIPE takes the whole server with it.
+    child.stdin?.on("error", () => this.close());
+    child.stdout?.on("error", () => this.close());
+    child.on("error", () => this.close());
+    child.on("close", () => this.close());
+
+    this.child = child;
+    this.options.onStart?.(this.info);
+  }
+
+  /** Feed the source. */
+  write(chunk: Buffer): boolean {
+    return this.child?.stdin?.write(chunk) ?? false;
+  }
+
+  async pump(body: Readable): Promise<void> {
+    for await (const chunk of body) {
+      if (this.closing) return;
+      if (!this.write(chunk as Buffer)) {
+        await new Promise((done) => this.child?.stdin?.once("drain", done) ?? done(null));
+      }
+    }
+  }
+
+  /**
+   * Audio that is already in its final form, from a source we did not spawn.
+   * The bytes still only reach a listener after something decoded them; it was
+   * simply a different process that did it.
+   */
+  feed(chunk: Buffer): void {
+    this.info.bytes += chunk.byteLength;
+    this.send(chunk);
+  }
+
+  /** Write to everyone, and drop anybody whose socket has gone. */
+  private send(chunk: Buffer): void {
+    for (const listener of this.listeners) {
+      try {
+        listener.write(chunk);
+      } catch {
+        // One listener's broken socket is not the channel's problem.
+        this.listeners.delete(listener);
+      }
+    }
+    this.info.listeners = this.listeners.size;
+  }
+
+  listen(listener: Listener): () => void {
+    this.listeners.add(listener);
+    this.info.listeners = this.listeners.size;
+    return () => {
+      this.listeners.delete(listener);
+      this.info.listeners = this.listeners.size;
+    };
+  }
+
+  close(): void {
+    if (this.closing) return;
+    this.closing = true;
+    const child = this.child;
+    this.child = null;
+    try {
+      child?.stdin?.end();
+    } catch {
+      // Already broken, which is usually why we are here.
+    }
+    child?.kill("SIGKILL");
+    // Listeners are ended rather than left hanging on a stream that stopped.
+    for (const listener of this.listeners) {
+      try {
+        listener.end();
+      } catch {
+        // Gone already.
+      }
+    }
+    this.listeners.clear();
+    this.info.listeners = 0;
+    this.options.onEnd?.(this.info);
+    this.onGone(this.info.id);
+  }
+}
+
+/**
+ * Every channel currently live.
+ *
+ * A channel exists while somebody is publishing to it and disappears when they
+ * stop, so the list is what is actually on rather than what was once
+ * configured.
+ */
+export class Channels {
+  private readonly open = new Map<string, Channel>();
+
+  constructor(private readonly options: ChannelOptions) {}
+
+  list(): ChannelInfo[] {
+    return [...this.open.values()]
+      .map((channel) => channel.info)
+      .sort((a, b) => a.startedAt - b.startedAt);
+  }
+
+  get count(): number {
+    return this.open.size;
+  }
+
+  /** Total listeners across every channel. */
+  get listeners(): number {
+    let total = 0;
+    for (const channel of this.open.values()) total += channel.listeners.size;
+    return total;
+  }
+
+  has(id: string): boolean {
+    return this.open.has(id);
+  }
+
+  /**
+   * Claim a channel and start decoding into it. Null when that channel is
+   * already being published to: two publishers on one channel would be two
+   * songs at once, which is never what anybody meant. Publishing to a
+   * *different* channel is exactly what this class exists for.
+   */
+  publish(id: string, name: string, format: string, via: ChannelInfo["via"]): Channel | null {
+    if (this.open.has(id)) return null;
+    const channel = new Channel(
+      {
+        id,
+        name: name || "a device",
+        format,
+        via,
+        startedAt: Date.now(),
+        bytes: 0,
+        listeners: 0,
+      },
+      this.options,
+      (gone) => this.open.delete(gone),
+    );
+    this.open.set(id, channel);
+    channel.start(format);
+    return channel;
+  }
+
+  /** Attach a listener, or null when nothing is playing on that channel. */
+  listen(id: string, listener: Listener): (() => void) | null {
+    const channel = this.open.get(id);
+    return channel ? channel.listen(listener) : null;
+  }
+
+  /** Feed a channel that already exists, for a publisher sending chunks. */
+  writeTo(id: string, chunk: Buffer): boolean {
+    return this.open.get(id)?.write(chunk) ?? false;
+  }
+
+  /**
+   * A channel fed by audio somebody else is already decoding.
+   *
+   * An RTMP listener is an ffmpeg with a publisher on one end, and it produces
+   * MP3 on its own. Spawning a second ffmpeg to decode what the first one just
+   * decoded would double the work to arrive at the same bytes.
+   */
+  attach(id: string, name: string, format: string, via: ChannelInfo["via"]): Channel | null {
+    if (this.open.has(id)) return null;
+    const channel = new Channel(
+      { id, name: name || "a device", format, via, startedAt: Date.now(), bytes: 0, listeners: 0 },
+      this.options,
+      (gone) => this.open.delete(gone),
+    );
+    this.open.set(id, channel);
+    return channel;
+  }
+
+  stop(id: string): boolean {
+    const channel = this.open.get(id);
+    if (!channel) return false;
+    channel.close();
+    return true;
+  }
+
+  stopAll(): void {
+    for (const channel of [...this.open.values()]) channel.close();
+  }
+}
+
+/** A channel id nobody chose, for a publisher that did not name one. */
+export function generatedId(): string {
+  return `s${randomBytes(3).toString("hex")}`;
+}

package/src/connections.ts

@@ -0,0 +1,158 @@
+/**
+ * Who is listening.
+ *
+ * A stream is a long-lived request, so the server can say exactly who is
+ * connected, to what, since when and how much has gone out. That is the whole
+ * point of the admin view: `ss -tn` tells you a socket exists, and nothing
+ * about which track is going down it.
+ */
+import type { IncomingMessage } from "node:http";
+import { classify } from "./share.ts";
+
+export type Kind = "stream" | "media" | "events" | "page";
+
+export interface Connection {
+  id: number;
+  kind: Kind;
+  /** The remote address, with an IPv4-mapped IPv6 prefix taken off. */
+  address: string;
+  /** Where that address lives: your network, tailscale, or the internet. */
+  network: "local" | "private" | "cgnat" | "public";
+  /** What is going down it, when we know. */
+  track: string;
+  /** Whatever the client called itself, trimmed to something printable. */
+  agent: string;
+  startedAt: number;
+  /**
+   * Bytes handed to the socket, which is not the same as bytes the listener
+   * has heard: the kernel buffers, and a slow client can be several seconds
+   * behind this number. It is the right figure for "is anything going out".
+   */
+  bytes: number;
+  /** Set when it ends, so the admin view can show what just finished. */
+  endedAt: number | null;
+}
+
+/** ::ffff:10.0.0.1 is 10.0.0.1 wearing a hat. */
+export function normaliseAddress(address: string | undefined): string {
+  if (!address) return "unknown";
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  return mapped?.[1] ?? address;
+}
+
+/** Loopback is not "your network"; it is this machine. */
+export function networkOf(address: string): Connection["network"] {
+  if (address === "127.0.0.1" || address === "::1" || address === "unknown") return "local";
+  if (!/^\d+\.\d+\.\d+\.\d+$/.test(address)) return "public";
+  return classify(address);
+}
+
+/**
+ * A user agent, cut to the part that identifies it. Browsers write a paragraph
+ * about every engine they have ever pretended to be.
+ */
+export function shortAgent(agent: string | undefined): string {
+  if (!agent) return "—";
+  const known = [
+    [/\bFirefox\/([\d.]+)/, "Firefox"],
+    [/\bEdg\/([\d.]+)/, "Edge"],
+    [/\bOPR\/([\d.]+)/, "Opera"],
+    [/\bChrome\/([\d.]+)/, "Chrome"],
+    [/\bVersion\/([\d.]+).*\bSafari\//, "Safari"],
+    [/\bVLC\/([\d.]+)/, "VLC"],
+    [/\bcurl\/([\d.]+)/, "curl"],
+    [/\bmpv\b/, "mpv"],
+    [/\bLavf\/([\d.]+)/, "ffmpeg"],
+  ] as const;
+  for (const [pattern, name] of known) {
+    const found = pattern.exec(agent);
+    if (found) return found[1] ? `${name} ${found[1].split(".")[0]}` : name;
+  }
+  return agent.slice(0, 24);
+}
+
+/**
+ * The live set. Finished connections are kept for a while, because "it stopped
+ * ten seconds ago" is the most useful thing an admin view can tell you when
+ * someone says the stream dropped.
+ */
+export class Connections {
+  private next = 1;
+  private readonly items = new Map<number, Connection>();
+  /** How many finished connections to remember. */
+  constructor(private readonly keep = 50) {}
+
+  open(request: IncomingMessage, kind: Kind, track: string): Connection {
+    const address = normaliseAddress(request.socket.remoteAddress);
+    const connection: Connection = {
+      id: this.next++,
+      kind,
+      address,
+      network: networkOf(address),
+      track,
+      agent: shortAgent(request.headers["user-agent"]),
+      startedAt: Date.now(),
+      bytes: 0,
+      endedAt: null,
+    };
+    this.items.set(connection.id, connection);
+    return connection;
+  }
+
+  close(id: number): void {
+    const found = this.items.get(id);
+    if (!found || found.endedAt !== null) return;
+    found.endedAt = Date.now();
+    this.prune();
+  }
+
+  add(id: number, bytes: number): void {
+    const found = this.items.get(id);
+    if (found) found.bytes += bytes;
+  }
+
+  /**
+   * Live first, oldest connection at the top; then the most recently finished.
+   *
+   * The id breaks ties because Date.now() has millisecond resolution and ten
+   * connections can easily end inside one, which left the order down to
+   * whatever the sort happened to do.
+   */
+  list(): Connection[] {
+    const all = [...this.items.values()];
+    const live = all
+      .filter((c) => c.endedAt === null)
+      .sort((a, b) => a.startedAt - b.startedAt || a.id - b.id);
+    const done = all
+      .filter((c) => c.endedAt !== null)
+      .sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0) || b.id - a.id);
+    return [...live, ...done];
+  }
+
+  /**
+   * Live connections that are actually hearing something. The state feed and
+   * the page are not listeners, and counting them would put a stream over the
+   * free allowance with nobody listening to it.
+   */
+  get listening(): number {
+    let count = 0;
+    for (const item of this.items.values()) {
+      if (item.endedAt === null && (item.kind === "stream" || item.kind === "media")) count++;
+    }
+    return count;
+  }
+
+  get active(): number {
+    let count = 0;
+    for (const item of this.items.values()) if (item.endedAt === null) count++;
+    return count;
+  }
+
+  /** Drop the oldest finished entries once there are more than we keep. */
+  private prune(): void {
+    const done = [...this.items.values()]
+      .filter((c) => c.endedAt !== null)
+      .sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0) || a.id - b.id);
+    for (const item of done.slice(0, Math.max(0, done.length - this.keep))) this.items.delete(item.id);
+  }
+}

package/src/daemon.ts

@@ -0,0 +1,193 @@
+/**
+ * Daemon mode.
+ *
+ * `nixamp serve` holds a terminal. A server you leave running should not, and
+ * you should be able to walk away and come back to it, which means something on
+ * disk has to remember where it is and what key it minted. That file is the
+ * whole of the daemon: a pid to signal and enough to reconnect.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface DaemonState {
+  pid: number;
+  host: string;
+  port: number;
+  /** The share key, so `nixamp admin` can talk to it without being told. */
+  key: string | null;
+  source: string;
+  startedAt: number;
+  /** Where its output went, for when it died and you want to know why. */
+  log: string;
+}
+
+/** XDG, with the usual fallback. One daemon per user, which is one too few for nobody. */
+export function stateDir(): string {
+  const base = process.env["XDG_STATE_HOME"] || join(homedir(), ".local", "state");
+  return join(base, "nixamp");
+}
+
+export function statePath(): string {
+  return join(stateDir(), "daemon.json");
+}
+
+export function logPath(): string {
+  return join(stateDir(), "daemon.log");
+}
+
+export function readState(): DaemonState | null {
+  try {
+    return JSON.parse(readFileSync(statePath(), "utf8")) as DaemonState;
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(state: DaemonState): void {
+  mkdirSync(dirname(statePath()), { recursive: true });
+  writeFileSync(statePath(), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+export function clearState(): void {
+  rmSync(statePath(), { force: true });
+}
+
+/**
+ * Signal 0 asks "could I signal this?" without sending anything. A pid file
+ * outlives the process that wrote it often enough that trusting one is how you
+ * end up reporting a daemon that has been dead since Tuesday.
+ */
+export function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means it exists and belongs to someone else, which is still alive.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** The daemon as far as anyone asking is concerned. */
+export function status(): { running: boolean; state: DaemonState | null } {
+  const state = readState();
+  if (state === null) return { running: false, state: null };
+  return { running: alive(state.pid), state };
+}
+
+/** The URL an admin client should talk to. */
+export function daemonUrl(state: DaemonState): string {
+  const host = state.host === "0.0.0.0" || state.host === "::" ? "127.0.0.1" : state.host;
+  return `http://${host.includes(":") ? `[${host}]` : host}:${state.port}`;
+}
+
+/**
+ * Start one, detached, and wait until it is actually answering before saying
+ * it started. Reporting success and leaving the user to discover a crash in a
+ * log file is the thing this is meant to avoid.
+ */
+export async function start(argv: string[], entry: string): Promise<DaemonState> {
+  const existing = status();
+  if (existing.running && existing.state) {
+    throw new Error(`nixamp: a daemon is already running (pid ${existing.state.pid}). Stop it first.`);
+  }
+
+  mkdirSync(stateDir(), { recursive: true });
+  const log = logPath();
+  const out = openSync(log, "a");
+
+  const child = spawn(process.execPath, [entry, "serve", ...argv, "--announce"], {
+    detached: true,
+    stdio: ["ignore", out, out],
+    env: { ...process.env, NIXAMP_DAEMON: "1" },
+  });
+  child.unref();
+  if (child.pid === undefined) throw new Error("nixamp: could not start the daemon");
+
+  // The server prints one JSON line when it is listening, because guessing how
+  // long a start takes is how a flaky `daemon start` is written.
+  const announced = await waitForAnnounce(log, 15_000);
+  if (announced === null) {
+    try {
+      process.kill(child.pid, "SIGTERM");
+    } catch {
+      // Already gone, which is the more likely reason we are here.
+    }
+    throw new Error(`nixamp: the daemon did not start. See ${log}`);
+  }
+
+  const state: DaemonState = { ...announced, pid: child.pid, startedAt: Date.now(), log };
+  writeState(state);
+  return state;
+}
+
+/** Poll the log for the announce line. */
+async function waitForAnnounce(
+  log: string,
+  timeoutMs: number,
+): Promise<Omit<DaemonState, "pid" | "startedAt" | "log"> | null> {
+  const deadline = Date.now() + timeoutMs;
+  const from = existsSync(log) ? readFileSync(log, "utf8").length : 0;
+  while (Date.now() < deadline) {
+    await new Promise((done) => setTimeout(done, 100));
+    let text: string;
+    try {
+      text = readFileSync(log, "utf8").slice(from);
+    } catch {
+      continue;
+    }
+    for (const line of text.split("\n")) {
+      if (!line.startsWith("{")) continue;
+      try {
+        const parsed = JSON.parse(line) as { nixamp?: string } & Record<string, unknown>;
+        if (parsed["nixamp"] === "listening") {
+          return {
+            host: String(parsed["host"]),
+            port: Number(parsed["port"]),
+            key: (parsed["key"] as string | null) ?? null,
+            source: String(parsed["source"]),
+          };
+        }
+      } catch {
+        // A partial line: it will be complete on the next pass.
+      }
+    }
+  }
+  return null;
+}
+
+/** Stop it, and wait for it to actually be gone. */
+export async function stop(timeoutMs = 5000): Promise<boolean> {
+  const { running, state } = status();
+  if (!state) return false;
+  if (!running) {
+    clearState();
+    return false;
+  }
+
+  try {
+    process.kill(state.pid, "SIGTERM");
+  } catch {
+    clearState();
+    return false;
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!alive(state.pid)) {
+      clearState();
+      return true;
+    }
+    await new Promise((done) => setTimeout(done, 100));
+  }
+
+  // It ignored SIGTERM. ffmpeg children make that more likely than it sounds.
+  try {
+    process.kill(state.pid, "SIGKILL");
+  } catch {
+    // Gone between the check and the signal.
+  }
+  clearState();
+  return true;
+}