nixamp 0.47.1 → 0.48.0

package/dist/guide-vods.d.ts

@@ -0,0 +1,89 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type RoomBasis } from "./guide-rooms.ts";
+import type { GuideEntry } from "./station-guide.ts";
+export interface GuideVod {
+    id: string;
+    /** The file's play address, with its listen key. */
+    play: string;
+    name: string;
+    kind: "audio" | "video";
+    /** Seconds; 0 when its server did not know. */
+    duration: number;
+    basis: RoomBasis;
+    note: string;
+    /** The nixamp.com account that published it ("" for this server's owner). */
+    by: string;
+    publishedAt: number;
+}
+/** Files one member may have on the guide at once, and files on it in all. */
+export declare const VODS_PER_MEMBER = 25;
+export declare const VODS_MAX = 1000;
+/**
+ * A file's play address taken apart, or null when it is not one: https (http
+ * only for a loopback address, for tests), a library item, a key, nothing else.
+ */
+export declare function vodAddress(input: string): {
+    origin: string;
+    item: string;
+    key: string;
+    play: string;
+} | null;
+export declare const vodPage: (base: string, id: string) => string;
+export declare class VodStore {
+    private readonly file;
+    private vods;
+    constructor(file: string);
+    static fileFor(stateDir: string, port: number): string;
+    /** Newest first, the order the guide shows them. */
+    list(): GuideVod[];
+    get(id: string): GuideVod | undefined;
+    /** Publishes a file, or refreshes the one already published at that address (its link stays). */
+    put(vod: Omit<GuideVod, "id" | "publishedAt">): GuideVod;
+    remove(id: string): boolean;
+    private save;
+}
+export interface VodState {
+    name: string;
+    kind: "audio" | "video";
+    duration: number;
+    artist: string;
+}
+/** Asks a file's own server what it is: its library item, read with the same key. */
+export declare class VodProbe {
+    private readonly fetcher;
+    private readonly refuse;
+    private cache;
+    /** `refuse` names why an address may not be fetched from this machine, or "" (see RoomProbe). */
+    constructor(fetcher?: typeof fetch, refuse?: (link: string) => Promise<string>);
+    state(play: string, fresh?: boolean): Promise<VodState | null>;
+    private ask;
+}
+/** "1:02:03" or "4:05". */
+export declare function clock(seconds: number): string;
+/** The published files as guide cards, newest first; one whose server no longer has it says so. */
+export declare function vodEntries(store: VodStore, probe: VodProbe, base: string): Promise<GuideEntry[]>;
+/** One file as its page reads it: never who published it, always where it plays. */
+export declare function vodView(vod: GuideVod, base: string, state: VodState | null): Record<string, unknown>;
+export interface VodContext {
+    store: VodStore;
+    probe: VodProbe;
+    /** The page base for a file's link. */
+    base: string;
+    /** Whether the request holds this server's control key (or is its signed-in owner). */
+    canControl: boolean;
+    /** The nixamp.com account behind the request's session, or "". */
+    member: () => Promise<string>;
+    /** This server's own play address for one of its library items, for the owner publishing by id; "" when it has none. */
+    ownPlay?: (item: string) => string;
+    /** What this server's own library says of one of its items, so publishing it never asks itself over the network. */
+    ownState?: (item: string) => VodState | null;
+    json: (response: ServerResponse, status: number, body: unknown) => void;
+    /** The request body as text (server.ts readBody). */
+    readBody: (request: IncomingMessage) => Promise<unknown>;
+    /** Refused by the caller's rate limit, or null. */
+    throttle?: () => {
+        retryAfter: number;
+    } | null;
+}
+/** Answers /api/v1/guide/vods; false when the path is not one. */
+export declare function handleVods(request: IncomingMessage, response: ServerResponse, path: string, ctx: VodContext): Promise<boolean>;

package/dist/guide-vods.js

@@ -0,0 +1,262 @@
+/**
+ * On demand: published files on the station guide.
+ *
+ * A live room plays wherever the room is now; a video on demand plays from
+ * its start, and a listener may seek. It is one library item of any nixamp
+ * server, at the address `https://host/api/v1/library/items/<id>/play?k=KEY`
+ * (library-routes.ts: the file itself when a browser takes it, else an MP4
+ * made on the way). A nixamp.com member publishes one with a rights basis, as
+ * a live room is published; the guide lists it under "On demand", and its
+ * short link, <watchBase>/vod/<id>, is the thing to share.
+ *
+ * Nothing here plays anything: the file's own server does, and this only asks
+ * it, now and then, whether the file is still there and what it is.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { ROOM_BASES } from "./guide-rooms.js";
+/** Files one member may have on the guide at once, and files on it in all. */
+export const VODS_PER_MEMBER = 25;
+export const VODS_MAX = 1000;
+const STATE_TTL_MS = 60_000;
+const PROBE_TIMEOUT_MS = 4_000;
+/**
+ * A file's play address taken apart, or null when it is not one: https (http
+ * only for a loopback address, for tests), a library item, a key, nothing else.
+ */
+export function vodAddress(input) {
+    let url;
+    try {
+        url = new URL(input.trim());
+    }
+    catch {
+        return null;
+    }
+    const loopback = url.hostname === "127.0.0.1" || url.hostname === "localhost";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
+        return null;
+    if (url.username || url.password || url.hash)
+        return null;
+    const item = /^\/api\/v1\/library\/items\/([0-9a-f]{16})\/(?:play|stream)\/?$/.exec(url.pathname);
+    if (!item)
+        return null;
+    const key = url.searchParams.get("k") ?? "";
+    if (!/^[A-Za-z0-9_-]{8,128}$/.test(key) || [...url.searchParams.keys()].some((name) => name !== "k"))
+        return null;
+    return { origin: url.origin, item: item[1], key, play: `${url.origin}/api/v1/library/items/${item[1]}/play?k=${key}` };
+}
+export const vodPage = (base, id) => `${base}/vod/${id}`;
+export class VodStore {
+    file;
+    vods = [];
+    constructor(file) {
+        this.file = file;
+        try {
+            if (existsSync(file)) {
+                const saved = JSON.parse(readFileSync(file, "utf8"));
+                this.vods = (saved.vods ?? []).filter((one) => vodAddress(one.play) !== null);
+            }
+        }
+        catch {
+            // Unreadable is empty; the next write replaces it.
+        }
+    }
+    static fileFor(stateDir, port) {
+        return join(stateDir, `guide-vods-${port}.json`);
+    }
+    /** Newest first, the order the guide shows them. */
+    list() {
+        return [...this.vods].sort((a, b) => b.publishedAt - a.publishedAt);
+    }
+    get(id) {
+        return this.vods.find((one) => one.id === id);
+    }
+    /** Publishes a file, or refreshes the one already published at that address (its link stays). */
+    put(vod) {
+        const existing = this.vods.find((one) => one.play === vod.play);
+        const saved = { ...vod, id: existing?.id ?? randomBytes(6).toString("base64url"), publishedAt: existing?.publishedAt ?? Date.now() };
+        this.vods = [...this.vods.filter((one) => one.play !== vod.play), saved];
+        this.save();
+        return saved;
+    }
+    remove(id) {
+        const before = this.vods.length;
+        this.vods = this.vods.filter((one) => one.id !== id);
+        if (this.vods.length === before)
+            return false;
+        this.save();
+        return true;
+    }
+    save() {
+        writeFileSync(`${this.file}.part`, `${JSON.stringify({ version: 1, vods: this.vods }, null, 2)}\n`);
+        renameSync(`${this.file}.part`, this.file);
+    }
+}
+/** Asks a file's own server what it is: its library item, read with the same key. */
+export class VodProbe {
+    fetcher;
+    refuse;
+    cache = new Map();
+    /** `refuse` names why an address may not be fetched from this machine, or "" (see RoomProbe). */
+    constructor(fetcher = fetch, refuse = async () => "") {
+        this.fetcher = fetcher;
+        this.refuse = refuse;
+    }
+    async state(play, fresh = false) {
+        const cached = this.cache.get(play);
+        if (!fresh && cached && Date.now() - cached.at < STATE_TTL_MS)
+            return cached.state;
+        const state = await this.ask(play).catch(() => null);
+        this.cache.set(play, { at: Date.now(), state });
+        if (this.cache.size > 2000)
+            this.cache.delete(this.cache.keys().next().value);
+        return state;
+    }
+    async ask(play) {
+        const address = vodAddress(play);
+        if (!address || (await this.refuse(address.play)) !== "")
+            return null;
+        const answer = await this.fetcher(`${address.origin}/api/v1/library/items/${address.item}?k=${address.key}`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS), redirect: "error" });
+        if (!answer.ok)
+            return null;
+        const item = (await answer.json()).item;
+        if (!item || item["state"] !== "ready")
+            return null;
+        const rel = String(item["rel"] ?? "");
+        const fallback = rel.split("/").pop()?.replace(/\.[^.]+$/, "") ?? address.item;
+        return {
+            name: String(item["title"] || fallback).slice(0, 160),
+            kind: item["video"] === true ? "video" : "audio",
+            duration: Number(item["duration"]) || 0,
+            artist: String(item["artist"] ?? "").slice(0, 160),
+        };
+    }
+}
+/** "1:02:03" or "4:05". */
+export function clock(seconds) {
+    const s = Math.max(0, Math.round(seconds));
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const pad = (n) => String(n).padStart(2, "0");
+    return h > 0 ? `${h}:${pad(m)}:${pad(s % 60)}` : `${m}:${pad(s % 60)}`;
+}
+/** The published files as guide cards, newest first; one whose server no longer has it says so. */
+export async function vodEntries(store, probe, base) {
+    return Promise.all(store.list().map(async (vod) => {
+        const state = await probe.state(vod.play);
+        return {
+            id: vod.id,
+            name: vod.name,
+            kind: state?.kind ?? vod.kind,
+            group: "vod",
+            state: state ? "vod" : "offline",
+            page: vodPage(base, vod.id),
+            nowPlaying: { title: clock(state?.duration || vod.duration), artist: state?.artist ?? "" },
+        };
+    }));
+}
+/** One file as its page reads it: never who published it, always where it plays. */
+export function vodView(vod, base, state) {
+    return {
+        id: vod.id,
+        name: vod.name,
+        kind: state?.kind ?? vod.kind,
+        duration: state?.duration || vod.duration,
+        artist: state?.artist ?? "",
+        note: vod.note,
+        basis: vod.basis,
+        publishedAt: vod.publishedAt,
+        available: state !== null,
+        play: vod.play,
+        page: vodPage(base, vod.id),
+    };
+}
+/** Answers /api/v1/guide/vods; false when the path is not one. */
+export async function handleVods(request, response, path, ctx) {
+    if (path !== "/api/v1/guide/vods" && !path.startsWith("/api/v1/guide/vods/"))
+        return false;
+    const method = request.method ?? "GET";
+    const one = /^\/api\/v1\/guide\/vods\/([A-Za-z0-9_-]{1,32})$/.exec(path);
+    if (method === "GET" || method === "HEAD") {
+        if (path === "/api/v1/guide/vods") {
+            ctx.json(response, 200, { vods: await vodEntries(ctx.store, ctx.probe, ctx.base) });
+            return true;
+        }
+        const vod = one ? ctx.store.get(one[1]) : undefined;
+        if (!vod) {
+            ctx.json(response, 404, { error: "no such video on this guide", code: "not_found" });
+            return true;
+        }
+        ctx.json(response, 200, { vod: vodView(vod, ctx.base, await ctx.probe.state(vod.play)) });
+        return true;
+    }
+    const by = ctx.canControl ? "" : await ctx.member();
+    if (!ctx.canControl && by === "") {
+        ctx.json(response, 401, { error: "sign in to nixamp.com to publish a video", code: "sign_in" });
+        return true;
+    }
+    const refused = ctx.throttle?.();
+    if (refused) {
+        response.setHeader("retry-after", String(refused.retryAfter));
+        ctx.json(response, 429, { error: "too many changes; wait a moment", code: "throttled" });
+        return true;
+    }
+    if (path === "/api/v1/guide/vods" && method === "POST") {
+        const raw = await ctx.readBody(request).catch(() => null);
+        const body = (typeof raw === "string" ? (() => { try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        } })() : raw);
+        // The owner may name one of this server's own items; everybody else hands over the address.
+        const own = ctx.canControl && typeof body?.item === "string" && /^[0-9a-f]{16}$/.test(body.item) && ctx.ownPlay ? ctx.ownPlay(body.item) : "";
+        const address = vodAddress(own || (typeof body?.play === "string" ? body.play : ""));
+        if (!address) {
+            ctx.json(response, 400, { error: "play must be a nixamp file's address: https://host/api/v1/library/items/<id>/play?k=KEY", code: "bad_address" });
+            return true;
+        }
+        const basis = ROOM_BASES.find((b) => b === body?.basis);
+        if (!basis || body?.agree !== true) {
+            ctx.json(response, 400, { error: "say why it may be shared (owned, permission, licensed, creative-commons or public-domain) and agree", code: "basis_required" });
+            return true;
+        }
+        const state = (own && ctx.ownState ? ctx.ownState(String(body?.item)) : null) ?? await ctx.probe.state(address.play, true);
+        if (!state) {
+            ctx.json(response, 404, { error: "that file is not in its server's library, or the key does not open it", code: "not_found" });
+            return true;
+        }
+        const all = ctx.store.list();
+        const taken = all.find((v) => v.play === address.play);
+        if (taken && taken.by !== by && !ctx.canControl) {
+            ctx.json(response, 409, { error: "somebody else published that file", code: "taken" });
+            return true;
+        }
+        if (by !== "" && all.filter((v) => v.by === by && v.play !== address.play).length >= VODS_PER_MEMBER) {
+            ctx.json(response, 409, { error: `a member may have ${VODS_PER_MEMBER} videos on the guide; take one off first`, code: "too_many" });
+            return true;
+        }
+        if (!taken && all.length >= VODS_MAX) {
+            ctx.json(response, 409, { error: "the guide is full", code: "full" });
+            return true;
+        }
+        const title = typeof body?.title === "string" ? body.title.trim().slice(0, 160) : "";
+        const note = typeof body?.note === "string" ? body.note.trim().slice(0, 300) : "";
+        const vod = ctx.store.put({ play: address.play, name: title || state.name, kind: state.kind, duration: state.duration, basis, note, by: taken?.by ?? by });
+        ctx.json(response, 200, { vod: vodView(vod, ctx.base, state), page: vodPage(ctx.base, vod.id) });
+        return true;
+    }
+    if (one && method === "DELETE") {
+        const vod = ctx.store.get(one[1]);
+        if (!vod || (!ctx.canControl && vod.by !== by)) {
+            ctx.json(response, 404, { error: "no such video of yours on the guide", code: "not_found" });
+            return true;
+        }
+        ctx.store.remove(vod.id);
+        ctx.json(response, 200, { removed: vod.id });
+        return true;
+    }
+    ctx.json(response, 405, { error: "method not allowed", code: "method_not_allowed" });
+    return true;
+}

package/dist/library-cli.js

@@ -183,6 +183,30 @@ export async function libraryTool(argv) {
                 console.error("nixamp library playlist new NAME [ITEM...] | show ID | add ID ITEM... | delete ID");
                 return 2;
             }
+            case "publish": {
+                // On demand on this server's guide (guide-vods.ts): the server builds the
+                // file's public address from its own public URL and listen key.
+                const [item] = rest;
+                const basis = flag(argv, "--basis");
+                if (!item || !basis) {
+                    console.error("nixamp library publish needs an item id and --basis owned|permission|licensed|creative-commons|public-domain");
+                    return 2;
+                }
+                return out(await call("POST", "/api/v1/guide/vods", { item, basis, agree: true, title: flag(argv, "--title") ?? "", note: flag(argv, "--note") ?? "" }), (body) => `on demand: ${String(body["page"])}`);
+            }
+            case "vods":
+                return out(await call("GET", "/api/v1/guide/vods"), (body) => {
+                    const vods = body["vods"] ?? [];
+                    return vods.length === 0 ? "nothing published on demand" : vods.map((one) => `${String(one["id"])}  ${String(one["name"])}  ${String(one["page"])}${one["state"] === "offline" ? "  [not answering]" : ""}`).join("\n");
+                });
+            case "unpublish": {
+                const [vod] = rest;
+                if (!vod) {
+                    console.error("nixamp library unpublish needs a video id (see nixamp library vods)");
+                    return 2;
+                }
+                return out(await call("DELETE", `/api/v1/guide/vods/${vod}`), (body) => `removed ${String(body["removed"])}`);
+            }
             default:
                 console.log(LIBRARY_USAGE);
                 return 2;

package/dist/library-routes.d.ts

@@ -26,6 +26,8 @@ export interface LibraryContext {
     /** Tell the player about tags that changed. */
     retag: (tracks: Track[]) => void;
     sendFile: (request: IncomingMessage, response: ServerResponse, file: string, cache: string) => void;
+    /** The file as a browser plays it (server.ts playFile): the bytes when it can, MP4 or MP3 when not. */
+    play?: (request: IncomingMessage, response: ServerResponse, file: string) => Promise<void>;
     json: (response: ServerResponse, status: number, body: unknown) => void;
     readBody: (request: IncomingMessage) => Promise<string>;
 }

package/dist/library-routes.js

@@ -214,12 +214,12 @@ export async function handleLibrary(request, response, path, url, ctx) {
             ctx.json(response, 200, index.browse(kind, { q: text("q"), limit: number("limit"), offset: number("offset") }));
             return true;
         }
-        const itemMatch = /^\/api\/v1\/library\/items\/([0-9a-f]{16})(?:\/(stream))?$/.exec(path);
+        const itemMatch = /^\/api\/v1\/library\/items\/([0-9a-f]{16})(?:\/(stream|play))?$/.exec(path);
         if (itemMatch) {
             const item = index.item(itemMatch[1]);
             if (!item)
                 return fail(404, "not_found", "no such item");
-            if (itemMatch[2] === "stream") {
+            if (itemMatch[2] === "stream" || itemMatch[2] === "play") {
                 if (method !== "GET" && method !== "HEAD")
                     return fail(405, "method_not_allowed", "GET");
                 if (item.state !== "ready")
@@ -227,6 +227,11 @@ export async function handleLibrary(request, response, path, url, ctx) {
                 const source = index.source(item.sourceId);
                 if (!source?.enabled)
                     return fail(409, "source_disabled", "that item's source is turned off");
+                // On demand: what a VOD link plays, from the start and seekable when the browser takes the file as it is.
+                if (itemMatch[2] === "play" && ctx.play) {
+                    await ctx.play(request, response, item.path);
+                    return true;
+                }
                 // Private: a browser may keep it, a shared cache may not.
                 ctx.sendFile(request, response, item.path, "private, max-age=3600");
                 return true;

package/dist/library-usage.d.ts

@@ -1,3 +1,3 @@
 /** `nixamp library` subcommands and usage, apart so help does not load the client. */
 export declare const LIBRARY_COMMANDS: Set<string>;
-export declare const LIBRARY_USAGE = "nixamp library \u2014 what this server has, indexed\n\n  nixamp library PATH                 the folder the daemon serves (set once)\n  nixamp library status               items by state, sources, last scans\n  nixamp library sources\n  nixamp library add PATH             index another folder (inside your home, not hidden)\n  nixamp library scan [SOURCE] [--force] [--wait]\n  nixamp library search WORDS [--artist A] [--album A] [--state failed] [--limit 20]\n  nixamp library show ITEM\n  nixamp library fix ITEM --title T [--artist A] [--album A] [--genre G] [--track N] [--year N]\n  nixamp library remove SOURCE        forget a folder; its files are not touched\n  nixamp library playlists\n  nixamp library playlist new NAME [ITEM...]\n  nixamp library playlist show|delete PLAYLIST\n  nixamp library playlist add PLAYLIST ITEM...\n\n  --json        machine-readable output\n  --url, --key  another server, as with `nixamp admin`";
+export declare const LIBRARY_USAGE = "nixamp library \u2014 what this server has, indexed\n\n  nixamp library PATH                 the folder the daemon serves (set once)\n  nixamp library status               items by state, sources, last scans\n  nixamp library sources\n  nixamp library add PATH             index another folder (inside your home, not hidden)\n  nixamp library scan [SOURCE] [--force] [--wait]\n  nixamp library search WORDS [--artist A] [--album A] [--state failed] [--limit 20]\n  nixamp library show ITEM\n  nixamp library fix ITEM --title T [--artist A] [--album A] [--genre G] [--track N] [--year N]\n  nixamp library remove SOURCE        forget a folder; its files are not touched\n  nixamp library playlists\n  nixamp library playlist new NAME [ITEM...]\n  nixamp library playlist show|delete PLAYLIST\n  nixamp library playlist add PLAYLIST ITEM...\n  nixamp library publish ITEM --basis B [--title T] [--note N]\n                                      on demand on live.streaming: a link that plays it from the start\n                                      (B: owned, permission, licensed, creative-commons, public-domain)\n  nixamp library vods                 what is published on demand, with each link\n  nixamp library unpublish VOD        take one off\n\n  --json        machine-readable output\n  --url, --key  another server, as with `nixamp admin`";

package/dist/library-usage.js

@@ -1,5 +1,5 @@
 /** `nixamp library` subcommands and usage, apart so help does not load the client. */
-export const LIBRARY_COMMANDS = new Set(["status", "sources", "add", "scan", "search", "show", "fix", "remove", "playlists", "playlist"]);
+export const LIBRARY_COMMANDS = new Set(["status", "sources", "add", "scan", "search", "show", "fix", "remove", "playlists", "playlist", "publish", "vods", "unpublish"]);
 export const LIBRARY_USAGE = `nixamp library — what this server has, indexed
 
   nixamp library PATH                 the folder the daemon serves (set once)
@@ -15,6 +15,11 @@ export const LIBRARY_USAGE = `nixamp library — what this server has, indexed
   nixamp library playlist new NAME [ITEM...]
   nixamp library playlist show|delete PLAYLIST
   nixamp library playlist add PLAYLIST ITEM...
+  nixamp library publish ITEM --basis B [--title T] [--note N]
+                                      on demand on live.streaming: a link that plays it from the start
+                                      (B: owned, permission, licensed, creative-commons, public-domain)
+  nixamp library vods                 what is published on demand, with each link
+  nixamp library unpublish VOD        take one off
 
   --json        machine-readable output
   --url, --key  another server, as with \`nixamp admin\``;

package/dist/server.d.ts

@@ -28,6 +28,7 @@ import { AiRadio } from "./ai-radio.ts";
 import { ListenerShares } from "./listener-shares.ts";
 import { Support, SupportSubscriptions } from "./support.ts";
 import { RoomProbe, RoomStore } from "./guide-rooms.ts";
+import { VodProbe, VodStore } from "./guide-vods.ts";
 import { PeerGuides } from "./station-guide.ts";
 import { StationRunner } from "./station-runner.ts";
 import { StationStore, type Station } from "./stations.ts";
@@ -622,6 +623,11 @@ export interface HandlerOptions {
             store: RoomStore;
             probe: RoomProbe;
         };
+        /** Files members published to this guide to play on demand, and how to ask a file's server about it. */
+        vods?: {
+            store: VodStore;
+            probe: VodProbe;
+        };
     };
     web: string | null;
     /** Branded clients on this same backend, keyed by an explicitly configured host. */