nixamp 0.29.1 → 0.30.1

package/dist/stations.js

@@ -0,0 +1,331 @@
+/**
+ * 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 const RIGHTS_BASES = ["owned", "permission", "licensed", "public-domain"];
+/** 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) {
+    return `station-${id}`;
+}
+/** The station a channel id belongs to, or "" for any other channel. */
+export function stationOfChannel(channelId) {
+    return channelId.startsWith("station-") ? channelId.slice("station-".length) : "";
+}
+function newId() {
+    // 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() {
+    return randomBytes(16).toString("base64url");
+}
+export function tokensMatch(offered, held) {
+    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, roots) {
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch {
+        return false;
+    }
+    return roots.some((root) => {
+        let base;
+        try {
+            base = realpathSync(root);
+        }
+        catch {
+            return false;
+        }
+        return real === base || real.startsWith(base.endsWith(sep) ? base : base + sep);
+    });
+}
+export class StationError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 400) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+function text(value, max, field) {
+    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 {
+    file;
+    io;
+    stations = new Map();
+    constructor(file, io = {
+        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);
+        },
+    }) {
+        this.file = file;
+        this.io = io;
+        const body = this.io.read(file);
+        if (body === null)
+            return;
+        try {
+            const parsed = JSON.parse(body);
+            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, port) {
+        return join(stateDir, `stations-${port}.json`);
+    }
+    save() {
+        this.io.write(this.file, `${JSON.stringify({ version: 1, stations: [...this.stations.values()] }, null, 2)}\n`);
+    }
+    list() {
+        return [...this.stations.values()].sort((a, b) => a.createdAt - b.createdAt);
+    }
+    get(id) {
+        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) {
+        if (key === "")
+            return undefined;
+        return [...this.stations.values()].find((one) => one.idempotencyKey === key);
+    }
+    create(input, items, owner, now = Date.now(), idempotencyKey = "") {
+        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 = {
+            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;
+    }
+    bitrateFrom(value) {
+        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, input, items, now = Date.now()) {
+        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) {
+        const had = this.stations.delete(id);
+        if (had)
+            this.save();
+        return had;
+    }
+    setDesired(id, desired, now = Date.now()) {
+        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, access, by, now = Date.now()) {
+        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)) {
+                throw new StationError("invalid_rights_basis", `the basis is one of ${RIGHTS_BASES.join(", ")}`);
+            }
+            station.rights = {
+                basis: basis,
+                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, now = Date.now()) {
+        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, file) {
+        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, file) {
+        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) {
+        const station = this.require(id);
+        station.failures = {};
+        this.save();
+        return station;
+    }
+    isExcluded(id, file) {
+        return (this.stations.get(id)?.failures[file] ?? 0) >= EXCLUDE_AFTER;
+    }
+    require(id) {
+        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, random = Math.random) {
+    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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.29.1",
+  "version": "0.30.1",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/channels.ts

@@ -1456,7 +1456,10 @@ export function rememberedChannels(dir: string, port: number): RememberedChannel
  */
 export function rememberedNow(channels: Channels): RememberedChannel[] {
   return channels.list()
-    .filter((one) => one.via === "pull" && one.source && !channels.isEphemeral(one.id))
+    // A station's channel is put back by its station, which knows whether it
+    // is still wanted; remembering it here too would bring back one its
+    // owner had stopped.
+    .filter((one) => one.via === "pull" && one.source && !channels.isEphemeral(one.id) && !one.id.startsWith("station-"))
     .map((one) => {
       const kept: RememberedChannel = { id: one.id, name: one.name, source: one.source as string };
       if (one.kind) kept.kind = one.kind;

package/src/directory.ts

@@ -154,6 +154,8 @@ export interface LineupEntry {
   kind: "audio" | "video";
   art: string;
   about: string;
+  /** A station's own listening page, on the same server; only for a station its owner listed. */
+  listen?: string;
 }
 
 const MAX_NAME = 60;
@@ -233,13 +235,13 @@ export function parseAnnouncement(input: unknown): Announcement | null {
         }
       : {}),
     ...(Array.isArray(record["lineup"])
-      ? { lineup: (record["lineup"] as unknown[]).map(parseLineupEntry).filter((one): one is LineupEntry => one !== null).slice(0, MAX_CHANNELS) }
+      ? { lineup: (record["lineup"] as unknown[]).map((one) => parseLineupEntry(one, listen.origin)).filter((one): one is LineupEntry => one !== null).slice(0, MAX_CHANNELS) }
       : {}),
   };
 }
 
 /** One lineup entry as a publisher sent it, cleaned, or null when it is not one. */
-export function parseLineupEntry(input: unknown): LineupEntry | null {
+export function parseLineupEntry(input: unknown, origin = ""): LineupEntry | null {
   if (typeof input !== "object" || input === null) return null;
   const record = input as Record<string, unknown>;
   const id = clean(record["id"], MAX_ID);
@@ -257,6 +259,12 @@ export function parseLineupEntry(input: unknown): LineupEntry | null {
     // page in a tag, and javascript: is a page in a tag that runs.
     art: publishable(art) !== null ? art : "",
     about: clean(record["about"], MAX_ABOUT),
+    // The same server as the listing, or nothing, like the audio address.
+    ...(() => {
+      const offered = typeof record["listen"] === "string" ? record["listen"].slice(0, MAX_ART) : "";
+      const parsed = offered && origin ? publishable(offered) : null;
+      return parsed !== null && parsed.origin === origin ? { listen: offered } : {};
+    })(),
   };
 }
 

package/src/main.ts

@@ -7,6 +7,7 @@ import { t as uiMessage, i18n, terminalUiLanguage, uiLanguage } from "./i18n.ts"
  *
  * ffmpeg decodes; we read every sample on its way to the speakers and draw it.
  */
+import { USAGE as STATION_USAGE } from "./station-usage.ts";
 import { createApp, themes, type BrailleCanvas, type Container, type KeyEvent, type Theme } from "@profullstack/hqtui";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
@@ -232,6 +233,7 @@ keeps serving its browser remote. One per user.
 
   nixamp attach   put the player back in front of it
   nixamp admin    who is connected, and re-stream to them
+  nixamp station  make a folder into a station others can join (see: nixamp station help)
 
 From inside the player, d hands the music to a daemon without stopping it.
 `,
@@ -394,6 +396,7 @@ q or d leaves; neither stops anything. \`nixamp daemon stop\` is what stops it.
 };
 
 export function helpFor(topic: string | undefined): string {
+  if (topic === "station" || topic === "stations") return STATION_USAGE;
   return (topic ? TOPICS[topic] : undefined) ?? HELP;
 }
 
@@ -553,6 +556,11 @@ export async function main(): Promise<void> {
     process.exitCode = await runDaemon(rest);
     return;
   }
+  if (first === "station" || first === "stations") {
+    const { station } = await import("./station-cli.ts");
+    process.exitCode = await station(rest);
+    return;
+  }
   if (first === "admin") {
     const { admin } = await import("./admin.ts");
     await admin(rest);