nixamp 0.29.1 → 0.30.1

package/dist/station-runner.js

@@ -0,0 +1,219 @@
+import { EXCLUDE_AFTER, OFFLINE_RETRY_MS, RECOVERY_DELAYS_MS, StationError, channelOf, insideRoots, shuffled, stationOfChannel, } from "./stations.js";
+/** A run shorter than this that ends badly does not reset the backoff. */
+const HEALTHY_RUN_MS = 60_000;
+export class StationRunner {
+    deps;
+    attempts = new Map();
+    timers = new Map();
+    startedAt = new Map();
+    stopping = new Set();
+    starting = new Set();
+    errors = new Map();
+    listening = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
+    }
+    log(line) {
+        this.deps.log?.(line);
+    }
+    /** The station's files that are still where they were, inside the library. */
+    playable(station) {
+        const roots = this.deps.roots();
+        return station.items.filter((file) => insideRoots(file, roots));
+    }
+    /** Wanted on, and put on. */
+    async start(id) {
+        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) {
+        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) {
+        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) {
+        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() {
+        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);
+        }
+    }
+    async launch(id) {
+        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) {
+        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);
+    }
+    scheduleRecovery(id) {
+        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);
+    }
+    cancelRecovery(id) {
+        const timer = this.timers.get(id);
+        if (timer)
+            clearTimeout(timer);
+        this.timers.delete(id);
+    }
+    observed(id) {
+        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) {
+        return this.errors.get(id) ?? "";
+    }
+    /** A listener on a station's link, ended if the link is revoked. */
+    track(id, listener) {
+        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) {
+        return this.listening.get(id)?.size ?? 0;
+    }
+    /** Everybody listening through a link that no longer works is let go. */
+    revoke(id) {
+        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/dist/station-usage.d.ts

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

package/dist/station-usage.js

@@ -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/dist/stations.d.ts

@@ -0,0 +1,148 @@
+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 declare const RIGHTS_BASES: readonly RightsBasis[];
+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 declare const EXCLUDE_AFTER = 3;
+export declare const DEFAULT_BITRATE = 128;
+export declare const BITRATES: number[];
+/** A station's channel id. */
+export declare function channelOf(id: string): string;
+/** The station a channel id belongs to, or "" for any other channel. */
+export declare function stationOfChannel(channelId: string): string;
+export declare function tokensMatch(offered: string, held: string): boolean;
+/** A path inside one of these roots, after symlinks: never outside the library. */
+export declare function insideRoots(path: string, roots: string[]): boolean;
+export declare class StationError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+export interface StationInput {
+    name?: unknown;
+    description?: unknown;
+    items?: unknown;
+    shuffle?: unknown;
+    repeat?: unknown;
+    bitrate?: unknown;
+}
+/** The stations of one server, kept in one file beside its keys. */
+export declare class StationStore {
+    private readonly file;
+    private readonly io;
+    private stations;
+    constructor(file: string, io?: {
+        read: (path: string) => string | null;
+        write: (path: string, body: string) => void;
+    });
+    static fileFor(stateDir: string, port: number): string;
+    private save;
+    list(): Station[];
+    get(id: string): Station | undefined;
+    /** New, and always private, stopped and unlisted (RAD-02). */
+    /** The station a create with this key already made. */
+    byIdempotencyKey(key: string): Station | undefined;
+    create(input: StationInput, items: string[], owner: string, now?: number, idempotencyKey?: string): Station;
+    private bitrateFrom;
+    /** Name, words, files and rotation. Who may listen is changed by publish/unpublish. */
+    update(id: string, input: StationInput, items: string[] | null, now?: number): Station;
+    remove(id: string): boolean;
+    setDesired(id: string, desired: Desired, now?: number): 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?: number): {
+        station: Station;
+        revoked: boolean;
+    };
+    /** A new listen link; every earlier one stops working. */
+    rotateToken(id: string, now?: number): Station;
+    /** One more failure in a row for this file; true when it is now left out. */
+    recordFailure(id: string, file: string): boolean;
+    /** Played through: its failures are forgotten. */
+    recordSuccess(id: string, file: string): void;
+    /** Every left-out file tried again (the owner's "retry"). */
+    clearFailures(id: string): Station;
+    isExcluded(id: string, file: string): boolean;
+    private require;
+}
+/** A station-wide shuffle: one order for everybody, Fisher-Yates. */
+export declare function shuffled(length: number, random?: () => number): number[];
+/**
+ * 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 declare const RECOVERY_DELAYS_MS: number[];
+export declare const OFFLINE_RETRY_MS: number;
+/** 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;
+}