nixamp 0.7.0 → 0.7.1

package/dist/handles.d.ts

@@ -35,6 +35,15 @@ export declare class Handles {
     constructor(db: Queryable);
     private ensure;
     of(userId: string): Promise<string>;
+    /**
+     * Handles for a page of rows, in one query.
+     *
+     * A public listing names people, and naming them one query at a time is how a
+     * list of fifty becomes fifty round trips. Anyone without a handle is absent
+     * from the map rather than present as an empty string, so a caller decides
+     * what to show for somebody who never picked one.
+     */
+    many(userIds: string[]): Promise<Map<string, string>>;
     /** Who holds this handle, so a listing can name somebody without their address. */
     holder(handle: string): Promise<string>;
     /**

package/dist/handles.js

@@ -20,7 +20,9 @@ export function cleanHandle(value) {
     if (typeof value !== "string")
         return "";
     const wanted = value.trim().toLowerCase();
-    if (!/^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$/.test(wanted))
+    // Two characters minimum, thirty maximum: the trailing character is required,
+    // which is also what stops a handle ending in a hyphen.
+    if (!/^[a-z0-9][a-z0-9-]{0,28}[a-z0-9]$/.test(wanted))
         return "";
     // Doubled hyphens are how punycode marks an encoded label, so a handle with
     // one in it can collide with an internationalised domain.
@@ -67,6 +69,22 @@ export class Handles {
         const { rows } = await this.db.query(`SELECT handle FROM ${TABLE} WHERE user_id = $1`, [userId]);
         return rows[0] ? String(rows[0]["handle"] ?? "") : "";
     }
+    /**
+     * Handles for a page of rows, in one query.
+     *
+     * A public listing names people, and naming them one query at a time is how a
+     * list of fifty becomes fifty round trips. Anyone without a handle is absent
+     * from the map rather than present as an empty string, so a caller decides
+     * what to show for somebody who never picked one.
+     */
+    async many(userIds) {
+        const wanted = [...new Set(userIds.filter(Boolean))];
+        if (wanted.length === 0)
+            return new Map();
+        await this.ensure();
+        const { rows } = await this.db.query(`SELECT user_id, handle FROM ${TABLE} WHERE user_id = ANY($1)`, [wanted]);
+        return new Map(rows.map((row) => [String(row["user_id"] ?? ""), String(row["handle"] ?? "")]));
+    }
     /** Who holds this handle, so a listing can name somebody without their address. */
     async holder(handle) {
         const wanted = cleanHandle(handle);

package/dist/main.js

@@ -52,6 +52,7 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp logout / whoami        forget it, or check it
   nixamp token create|list|revoke  tokens for a machine that cannot sign in
   nixamp server list|add|remove  the machines you run, kept against your account
+  nixamp opendir list|add|remove  folders found on the web, published for everyone
   nixamp update [version]        re-run the installer, keeping your choices
   nixamp uninstall [--yes]       remove everything the installer created
 
@@ -292,6 +293,11 @@ export async function main() {
         process.exitCode = await login(first === "signup" ? [...rest, "--signup"] : rest);
         return;
     }
+    if (first === "opendir" || first === "opendirs") {
+        const { opendirs } = await import("./session.js");
+        process.exitCode = await opendirs(rest);
+        return;
+    }
     if (first === "server" || first === "servers") {
         const { servers } = await import("./session.js");
         process.exitCode = await servers(rest);

package/dist/opendirs.d.ts

@@ -0,0 +1,43 @@
+import type { Queryable } from "./follows.ts";
+export interface OpenDir {
+    id: string;
+    url: string;
+    name: string;
+    /** How many playable files were on the page when it was added. */
+    tracks: number;
+    /** The finder's public handle. Never their address. */
+    by: string;
+    createdAt: number;
+}
+/**
+ * The name to show for a folder nobody named.
+ *
+ * The last path segment, which for a folder of music is the album, written the
+ * way a person wrote it rather than the way a URL spells it.
+ */
+export declare function nameOfDir(url: string): string;
+export declare class OpenDirs {
+    private readonly db;
+    private ready;
+    constructor(db: Queryable);
+    private ensure;
+    /**
+     * The list, newest first, in pages.
+     *
+     * Keyset on the row's own creation time rather than an offset, because a list
+     * anybody may add to shifts under a reader who is paging through it, and an
+     * offset in a shifting list repeats and skips rows.
+     */
+    list(limit?: number, before?: number): Promise<{
+        rows: Omit<OpenDir, "by">[];
+        addedBy: string[];
+        next: number;
+    }>;
+    /**
+     * Publish one. `tracks` is what the finder's server actually saw on the page,
+     * so a row nobody can play never reaches the list.
+     */
+    add(userId: string, url: unknown, name: unknown, tracks: number): Promise<Omit<OpenDir, "by"> | null>;
+    /** Only the finder takes their own row down. */
+    remove(userId: string, id: string): Promise<boolean>;
+}

package/dist/opendirs.js

@@ -0,0 +1,133 @@
+/**
+ * Open directories somebody found, kept as a list anyone can read.
+ *
+ * Deliberately not the stream directory. That one lists what is playing right
+ * now: a heartbeat, a TTL, a room code, somebody at the other end. An open
+ * directory is the opposite in every one of those respects. It is always there,
+ * nobody is broadcasting it, and it is not the finder's to broadcast. Mixing
+ * the two would put "chovy is playing this, dial in" next to "here is a link
+ * to a stranger's file server" under one heading.
+ *
+ * Public to read and signed in to add, because a public list with nobody
+ * accountable for its rows is a public list of whatever anybody felt like
+ * putting there. What is shown against a row is the finder's handle, never the
+ * address they signed up with.
+ */
+import { randomBytes } from "node:crypto";
+import { cleanUrl } from "./servers.js";
+const TABLE = "nixamp_opendirs";
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    id          TEXT PRIMARY KEY,
+    url         TEXT NOT NULL,
+    name        TEXT NOT NULL DEFAULT '',
+    added_by    TEXT NOT NULL,
+    tracks      INTEGER NOT NULL DEFAULT 0,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS ${TABLE}_url ON ${TABLE} (url);
+  CREATE INDEX IF NOT EXISTS ${TABLE}_added ON ${TABLE} (created_at DESC);
+`;
+/**
+ * The name to show for a folder nobody named.
+ *
+ * The last path segment, which for a folder of music is the album, written the
+ * way a person wrote it rather than the way a URL spells it.
+ */
+export function nameOfDir(url) {
+    try {
+        const parts = new URL(url).pathname.split("/").filter(Boolean);
+        const last = parts[parts.length - 1];
+        return last ? decodeURIComponent(last).slice(0, 120) : new URL(url).host;
+    }
+    catch {
+        return "an open directory";
+    }
+}
+function asTime(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === "string") {
+        const at = Date.parse(value);
+        return Number.isNaN(at) ? 0 : at;
+    }
+    return typeof value === "number" ? value : 0;
+}
+export class OpenDirs {
+    db;
+    ready = null;
+    constructor(db) {
+        this.db = db;
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    /**
+     * The list, newest first, in pages.
+     *
+     * Keyset on the row's own creation time rather than an offset, because a list
+     * anybody may add to shifts under a reader who is paging through it, and an
+     * offset in a shifting list repeats and skips rows.
+     */
+    async list(limit = 50, before = 0) {
+        await this.ensure();
+        const size = Math.min(200, Math.max(1, limit));
+        const { rows } = await this.db.query(`SELECT id, url, name, added_by, tracks, created_at FROM ${TABLE}
+        ${before > 0 ? "WHERE created_at < $2" : ""}
+        ORDER BY created_at DESC LIMIT $1`, before > 0 ? [size + 1, new Date(before).toISOString()] : [size + 1]);
+        // One more than asked for, so "is there another page" is a fact rather
+        // than a guess from a full one.
+        const page = rows.slice(0, size);
+        return {
+            rows: page.map((row) => ({
+                id: String(row["id"] ?? ""),
+                url: String(row["url"] ?? ""),
+                name: String(row["name"] ?? ""),
+                tracks: Number(row["tracks"] ?? 0),
+                createdAt: asTime(row["created_at"]),
+            })),
+            addedBy: page.map((row) => String(row["added_by"] ?? "")),
+            next: rows.length > size ? asTime(page[page.length - 1]?.["created_at"]) : 0,
+        };
+    }
+    /**
+     * Publish one. `tracks` is what the finder's server actually saw on the page,
+     * so a row nobody can play never reaches the list.
+     */
+    async add(userId, url, name, tracks) {
+        const clean = typeof url === "string" ? url.trim() : "";
+        // Not cleanUrl's origin-only treatment: a folder is a path, and the path is
+        // the whole point of the row.
+        if (!/^https?:\/\//i.test(clean) || cleanUrl(clean) === "")
+            return null;
+        if (tracks <= 0)
+            return null;
+        await this.ensure();
+        const { rows } = await this.db.query(`INSERT INTO ${TABLE} (id, url, name, added_by, tracks) VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (url) DO UPDATE SET name = EXCLUDED.name, tracks = EXCLUDED.tracks
+       RETURNING id, url, name, tracks, created_at`, [
+            randomBytes(8).toString("hex"),
+            clean,
+            (typeof name === "string" && name.trim() ? name.trim() : nameOfDir(clean)).slice(0, 120),
+            userId,
+            Math.min(100_000, tracks),
+        ]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return {
+            id: String(row["id"] ?? ""),
+            url: String(row["url"] ?? ""),
+            name: String(row["name"] ?? ""),
+            tracks: Number(row["tracks"] ?? 0),
+            createdAt: asTime(row["created_at"]),
+        };
+    }
+    /** Only the finder takes their own row down. */
+    async remove(userId, id) {
+        await this.ensure();
+        const { rows } = await this.db.query(`DELETE FROM ${TABLE} WHERE id = $1 AND added_by = $2 RETURNING id`, [id, userId]);
+        return rows.length > 0;
+    }
+}

package/dist/server.d.ts

@@ -5,6 +5,7 @@ import { Ingest } from "./ingest.ts";
 import { Channels } from "./channels.ts";
 import { Accounts } from "./accounts.ts";
 import { Handles } from "./handles.ts";
+import { OpenDirs } from "./opendirs.ts";
 import { Servers } from "./servers.ts";
 import { SignIn } from "./oauth.ts";
 import { Owner } from "./owner.ts";
@@ -272,6 +273,8 @@ export interface HandlerOptions {
     servers?: Servers;
     /** The name other people see, which is never the address they signed up with. */
     handles?: Handles;
+    /** Open directories people have found, which anyone may read. */
+    openDirs?: OpenDirs;
     /** True when this instance is reached over https, for the cookie's Secure. */
     secureCookies?: boolean;
     /** A certificate and key in PEM, when this server is to speak https itself. */

package/dist/server.js

@@ -23,6 +23,7 @@ import { Channels, cleanId } from "./channels.js";
 import { RtmpListeners } from "./rtmp-in.js";
 import { Accounts, clearedCookie, sessionCookie, tokenFrom } from "./accounts.js";
 import { anonymousHandle, Handles } from "./handles.js";
+import { OpenDirs } from "./opendirs.js";
 import { Servers } from "./servers.js";
 import { DeviceGrants } from "./device.js";
 import { BAD_KEY_LIMIT, callerOf, Guard, SIGN_IN_LIMIT } from "./guard.js";
@@ -45,7 +46,7 @@ import { extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { detectTools, peaks, RATE, Stream, toMono, } from "./audio.js";
 import { Analyser, bandEdges, bands, decay } from "./fft.js";
-import { loadSource, loadTagged } from "./playlist.js";
+import { loadSource, loadTagged, readRemoteIndex } from "./playlist.js";
 import { emptySnapshot, parseCommand, } from "./protocol.js";
 const FFT_SIZE = 2048;
 export const SERVE_BAND_COUNT = 24;
@@ -558,6 +559,9 @@ export function isSignInPath(path) {
         path === "/api/v1/servers" ||
         path.startsWith("/api/v1/servers/") ||
         path === "/api/v1/me/handle" ||
+        // Public to read, so it must not be behind a share key either.
+        path === "/api/v1/opendirs" ||
+        path.startsWith("/api/v1/opendirs/") ||
         OAUTH_ROUTE.test(path));
 }
 function html(response, code, body) {
@@ -1216,6 +1220,74 @@ export function createHandler(engine, options) {
             response.end(JSON.stringify({ account: result.account, token }));
             return;
         }
+        // --- open directories somebody found -----------------------------------
+        //
+        // Its own list, not the stream directory: that one is what is playing now,
+        // with a heartbeat and a room code and somebody at the other end, and this
+        // one is a folder on the web that is always there and belongs to nobody
+        // here. Reading needs no account. Adding does, because a public list with
+        // nobody accountable for its rows is a list of whatever anyone felt like.
+        if ((path === "/api/v1/opendirs" || path.startsWith("/api/v1/opendirs/")) && options.openDirs) {
+            const dirs = options.openDirs;
+            if (path === "/api/v1/opendirs" && request.method === "GET") {
+                const limit = Number(url.searchParams.get("limit") ?? "50");
+                const before = Number(url.searchParams.get("before") ?? "0");
+                const page = await dirs.list(Number.isFinite(limit) ? limit : 50, Number.isFinite(before) ? before : 0);
+                const names = options.handles ? await options.handles.many(page.addedBy) : new Map();
+                json(response, 200, {
+                    opendirs: page.rows.map((row, at) => ({
+                        ...row,
+                        // A handle or nothing. The address that signed up is never here.
+                        by: names.get(page.addedBy[at] ?? "") ?? "",
+                    })),
+                    next: page.next,
+                });
+                return;
+            }
+            if (path === "/api/v1/opendirs" && request.method === "POST" && options.accounts) {
+                const who = await options.accounts.whoIs(tokenFrom(request.headers));
+                if (who === null) {
+                    json(response, 401, { error: "sign in to publish one" });
+                    return;
+                }
+                let body;
+                try {
+                    body = JSON.parse(await readBody(request));
+                }
+                catch {
+                    json(response, 400, { error: "bad JSON" });
+                    return;
+                }
+                // Read before publishing. A row nobody can play is worse than no row,
+                // and the count is the one fact a reader wants before clicking.
+                const listed = typeof body.url === "string" ? await readRemoteIndex(body.url) : [];
+                if (listed.length === 0) {
+                    json(response, 422, { error: "nothing playable was linked from that page" });
+                    return;
+                }
+                const made = await dirs.add(who.id, body.url, body.name, listed.length);
+                if (made === null) {
+                    json(response, 422, { error: "that needs an http or https address" });
+                    return;
+                }
+                const handle = options.handles ? await options.handles.of(who.id) : "";
+                json(response, 201, { opendir: { ...made, by: handle } });
+                return;
+            }
+            const dirId = path.slice("/api/v1/opendirs/".length);
+            if (dirId && request.method === "DELETE" && options.accounts) {
+                const who = await options.accounts.whoIs(tokenFrom(request.headers));
+                if (who === null) {
+                    json(response, 401, { error: "not signed in" });
+                    return;
+                }
+                const gone = await dirs.remove(who.id, dirId);
+                json(response, gone ? 200 : 404, gone ? { ok: true } : { error: "not yours, or not there" });
+                return;
+            }
+            json(response, 405, { error: "GET, POST or DELETE" });
+            return;
+        }
         // --- coming back from a provider ---------------------------------------
         //
         // /api/v1/<provider>/oauth/start sends a browser away, and .../callback is
@@ -2324,7 +2396,9 @@ export async function serve(argv, version = "0.1.0") {
                 // all: a browser already signed in can approve a terminal.
                 // The same pool the follows and reminders use: three small tables in
                 // one database do not want three sets of connections.
-                ...(pool ? { servers: new Servers(pool), handles: new Handles(pool) } : {}),
+                ...(pool
+                    ? { servers: new Servers(pool), handles: new Handles(pool), openDirs: new OpenDirs(pool) }
+                    : {}),
                 signIn: new SignIn(providersFrom(process.env), new DeviceGrants(), process.env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY),
             }
             : {}),

package/dist/session.d.ts

@@ -107,3 +107,11 @@ export declare function whoami(fetcher?: typeof fetch): Promise<number>;
  * the browser and in the desktop app.
  */
 export declare function servers(argv: string[], fetcher?: typeof fetch): Promise<number>;
+/**
+ * `nixamp opendir list|add|remove`, the public list of folders people found.
+ *
+ * Reading needs no account, which is why `list` works signed out. Adding needs
+ * one, because a public list with nobody accountable for its rows is a list of
+ * whatever anybody felt like putting there.
+ */
+export declare function opendirs(argv: string[], fetcher?: typeof fetch): Promise<number>;

package/dist/session.js

@@ -578,3 +578,89 @@ export async function servers(argv, fetcher = fetch) {
         return 69;
     }
 }
+/**
+ * `nixamp opendir list|add|remove`, the public list of folders people found.
+ *
+ * Reading needs no account, which is why `list` works signed out. Adding needs
+ * one, because a public list with nobody accountable for its rows is a list of
+ * whatever anybody felt like putting there.
+ */
+export async function opendirs(argv, fetcher = fetch) {
+    const [command = "list", ...rest] = argv;
+    const session = readSession();
+    const site = session?.site ?? DEFAULT_DIRECTORY;
+    const where = `${site}/api/v1/opendirs`;
+    const headers = {
+        "content-type": "application/json",
+        ...(session ? { authorization: `Bearer ${session.token}` } : {}),
+    };
+    const at = (flag) => {
+        const index = rest.indexOf(flag);
+        return index === -1 ? undefined : rest[index + 1];
+    };
+    try {
+        if (command === "list" || command === "ls") {
+            const answer = await fetcher(where, { headers });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok) {
+                console.error(`nixamp: ${body.error ?? `could not read the list (${answer.status})`}`);
+                return 1;
+            }
+            const rows = body.opendirs ?? [];
+            if (rows.length === 0) {
+                console.log("Nothing published yet. `nixamp opendir add <url>` puts one there.");
+                return 0;
+            }
+            const width = Math.max(...rows.map((row) => row.name.length));
+            for (const row of rows) {
+                const who = row.by ? ` by ${row.by}` : "";
+                console.log(`${row.id}  ${row.name.padEnd(width)}  ${row.tracks} tracks${who}`);
+                console.log(`  ${row.url}`);
+            }
+            return 0;
+        }
+        if (session === null) {
+            console.error("nixamp: sign in to publish or remove one. Try `nixamp login`.");
+            return 1;
+        }
+        if (command === "add" || command === "publish") {
+            const target = rest.find((a) => /^https?:\/\//.test(a)) ?? "";
+            if (!target) {
+                console.error("nixamp: which folder? Give the URL of a directory listing.");
+                return 64;
+            }
+            const answer = await fetcher(where, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ url: target, name: at("--name") ?? "" }),
+            });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok || !body.opendir) {
+                console.error(`nixamp: ${body.error ?? `could not publish it (${answer.status})`}`);
+                return 1;
+            }
+            console.log(`${body.opendir.id}  ${body.opendir.name}  ${body.opendir.tracks} tracks`);
+            return 0;
+        }
+        if (command === "remove" || command === "rm") {
+            const id = rest.find((a) => !a.startsWith("-")) ?? "";
+            if (!id) {
+                console.error("nixamp: which one? `nixamp opendir list` shows their ids.");
+                return 64;
+            }
+            const answer = await fetcher(`${where}/${encodeURIComponent(id)}`, { method: "DELETE", headers });
+            if (!answer.ok) {
+                console.error(`nixamp: ${answer.status === 404 ? "not yours, or not there" : "could not remove it"}`);
+                return 1;
+            }
+            console.log(`Removed ${id}.`);
+            return 0;
+        }
+        console.error(`nixamp: no such opendir command: ${command}`);
+        return 64;
+    }
+    catch (error) {
+        console.error(`nixamp: could not reach ${site}: ${error.message}`);
+        return 69;
+    }
+}

package/package.json

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

package/src/handles.ts

@@ -35,7 +35,9 @@ const SCHEMA = `
 export function cleanHandle(value: unknown): string {
   if (typeof value !== "string") return "";
   const wanted = value.trim().toLowerCase();
-  if (!/^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$/.test(wanted)) return "";
+  // Two characters minimum, thirty maximum: the trailing character is required,
+  // which is also what stops a handle ending in a hyphen.
+  if (!/^[a-z0-9][a-z0-9-]{0,28}[a-z0-9]$/.test(wanted)) return "";
   // Doubled hyphens are how punycode marks an encoded label, so a handle with
   // one in it can collide with an internationalised domain.
   return wanted.includes("--") ? "" : wanted;
@@ -85,6 +87,25 @@ export class Handles {
     return rows[0] ? String(rows[0]["handle"] ?? "") : "";
   }
 
+  /**
+   * Handles for a page of rows, in one query.
+   *
+   * A public listing names people, and naming them one query at a time is how a
+   * list of fifty becomes fifty round trips. Anyone without a handle is absent
+   * from the map rather than present as an empty string, so a caller decides
+   * what to show for somebody who never picked one.
+   */
+  async many(userIds: string[]): Promise<Map<string, string>> {
+    const wanted = [...new Set(userIds.filter(Boolean))];
+    if (wanted.length === 0) return new Map();
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `SELECT user_id, handle FROM ${TABLE} WHERE user_id = ANY($1)`,
+      [wanted],
+    );
+    return new Map(rows.map((row) => [String(row["user_id"] ?? ""), String(row["handle"] ?? "")]));
+  }
+
   /** Who holds this handle, so a listing can name somebody without their address. */
   async holder(handle: string): Promise<string> {
     const wanted = cleanHandle(handle);

package/src/main.ts

@@ -76,6 +76,7 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp logout / whoami        forget it, or check it
   nixamp token create|list|revoke  tokens for a machine that cannot sign in
   nixamp server list|add|remove  the machines you run, kept against your account
+  nixamp opendir list|add|remove  folders found on the web, published for everyone
   nixamp update [version]        re-run the installer, keeping your choices
   nixamp uninstall [--yes]       remove everything the installer created
 
@@ -326,6 +327,11 @@ export async function main(): Promise<void> {
     process.exitCode = await login(first === "signup" ? [...rest, "--signup"] : rest);
     return;
   }
+  if (first === "opendir" || first === "opendirs") {
+    const { opendirs } = await import("./session.ts");
+    process.exitCode = await opendirs(rest);
+    return;
+  }
   if (first === "server" || first === "servers") {
     const { servers } = await import("./session.ts");
     process.exitCode = await servers(rest);

package/src/opendirs.ts

@@ -0,0 +1,158 @@
+/**
+ * Open directories somebody found, kept as a list anyone can read.
+ *
+ * Deliberately not the stream directory. That one lists what is playing right
+ * now: a heartbeat, a TTL, a room code, somebody at the other end. An open
+ * directory is the opposite in every one of those respects. It is always there,
+ * nobody is broadcasting it, and it is not the finder's to broadcast. Mixing
+ * the two would put "chovy is playing this, dial in" next to "here is a link
+ * to a stranger's file server" under one heading.
+ *
+ * Public to read and signed in to add, because a public list with nobody
+ * accountable for its rows is a public list of whatever anybody felt like
+ * putting there. What is shown against a row is the finder's handle, never the
+ * address they signed up with.
+ */
+import { randomBytes } from "node:crypto";
+import type { Queryable } from "./follows.ts";
+import { cleanUrl } from "./servers.ts";
+
+const TABLE = "nixamp_opendirs";
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    id          TEXT PRIMARY KEY,
+    url         TEXT NOT NULL,
+    name        TEXT NOT NULL DEFAULT '',
+    added_by    TEXT NOT NULL,
+    tracks      INTEGER NOT NULL DEFAULT 0,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS ${TABLE}_url ON ${TABLE} (url);
+  CREATE INDEX IF NOT EXISTS ${TABLE}_added ON ${TABLE} (created_at DESC);
+`;
+
+export interface OpenDir {
+  id: string;
+  url: string;
+  name: string;
+  /** How many playable files were on the page when it was added. */
+  tracks: number;
+  /** The finder's public handle. Never their address. */
+  by: string;
+  createdAt: number;
+}
+
+/**
+ * The name to show for a folder nobody named.
+ *
+ * The last path segment, which for a folder of music is the album, written the
+ * way a person wrote it rather than the way a URL spells it.
+ */
+export function nameOfDir(url: string): string {
+  try {
+    const parts = new URL(url).pathname.split("/").filter(Boolean);
+    const last = parts[parts.length - 1];
+    return last ? decodeURIComponent(last).slice(0, 120) : new URL(url).host;
+  } catch {
+    return "an open directory";
+  }
+}
+
+function asTime(value: unknown): number {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "string") {
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? 0 : at;
+  }
+  return typeof value === "number" ? value : 0;
+}
+
+export class OpenDirs {
+  private ready: Promise<void> | null = null;
+
+  constructor(private readonly db: Queryable) {}
+
+  private async ensure(): Promise<void> {
+    this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+    await this.ready;
+  }
+
+  /**
+   * The list, newest first, in pages.
+   *
+   * Keyset on the row's own creation time rather than an offset, because a list
+   * anybody may add to shifts under a reader who is paging through it, and an
+   * offset in a shifting list repeats and skips rows.
+   */
+  async list(limit = 50, before = 0): Promise<{ rows: Omit<OpenDir, "by">[]; addedBy: string[]; next: number }> {
+    await this.ensure();
+    const size = Math.min(200, Math.max(1, limit));
+    const { rows } = await this.db.query(
+      `SELECT id, url, name, added_by, tracks, created_at FROM ${TABLE}
+        ${before > 0 ? "WHERE created_at < $2" : ""}
+        ORDER BY created_at DESC LIMIT $1`,
+      before > 0 ? [size + 1, new Date(before).toISOString()] : [size + 1],
+    );
+
+    // One more than asked for, so "is there another page" is a fact rather
+    // than a guess from a full one.
+    const page = rows.slice(0, size);
+    return {
+      rows: page.map((row) => ({
+        id: String(row["id"] ?? ""),
+        url: String(row["url"] ?? ""),
+        name: String(row["name"] ?? ""),
+        tracks: Number(row["tracks"] ?? 0),
+        createdAt: asTime(row["created_at"]),
+      })),
+      addedBy: page.map((row) => String(row["added_by"] ?? "")),
+      next: rows.length > size ? asTime(page[page.length - 1]?.["created_at"]) : 0,
+    };
+  }
+
+  /**
+   * Publish one. `tracks` is what the finder's server actually saw on the page,
+   * so a row nobody can play never reaches the list.
+   */
+  async add(userId: string, url: unknown, name: unknown, tracks: number): Promise<Omit<OpenDir, "by"> | null> {
+    const clean = typeof url === "string" ? url.trim() : "";
+    // Not cleanUrl's origin-only treatment: a folder is a path, and the path is
+    // the whole point of the row.
+    if (!/^https?:\/\//i.test(clean) || cleanUrl(clean) === "") return null;
+    if (tracks <= 0) return null;
+
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `INSERT INTO ${TABLE} (id, url, name, added_by, tracks) VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (url) DO UPDATE SET name = EXCLUDED.name, tracks = EXCLUDED.tracks
+       RETURNING id, url, name, tracks, created_at`,
+      [
+        randomBytes(8).toString("hex"),
+        clean,
+        (typeof name === "string" && name.trim() ? name.trim() : nameOfDir(clean)).slice(0, 120),
+        userId,
+        Math.min(100_000, tracks),
+      ],
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      id: String(row["id"] ?? ""),
+      url: String(row["url"] ?? ""),
+      name: String(row["name"] ?? ""),
+      tracks: Number(row["tracks"] ?? 0),
+      createdAt: asTime(row["created_at"]),
+    };
+  }
+
+  /** Only the finder takes their own row down. */
+  async remove(userId: string, id: string): Promise<boolean> {
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `DELETE FROM ${TABLE} WHERE id = $1 AND added_by = $2 RETURNING id`,
+      [id, userId],
+    );
+    return rows.length > 0;
+  }
+}

package/src/server.ts

@@ -30,6 +30,7 @@ import { Channels, cleanId } from "./channels.ts";
 import { RtmpListeners } from "./rtmp-in.ts";
 import { Accounts, clearedCookie, sessionCookie, tokenFrom } from "./accounts.ts";
 import { anonymousHandle, Handles } from "./handles.ts";
+import { OpenDirs } from "./opendirs.ts";
 import { Servers } from "./servers.ts";
 import { DeviceGrants } from "./device.ts";
 import { BAD_KEY_LIMIT, callerOf, Guard, SIGN_IN_LIMIT } from "./guard.ts";
@@ -82,7 +83,7 @@ import {
   type Tools, type Track,
 } from "./audio.ts";
 import { Analyser, bandEdges, bands, decay } from "./fft.ts";
-import { loadSource, loadTagged } from "./playlist.ts";
+import { loadSource, loadTagged, readRemoteIndex } from "./playlist.ts";
 import {
   emptySnapshot, parseCommand,
   type Command, type RemoteTrack, type Snapshot,
@@ -695,6 +696,9 @@ export function isSignInPath(path: string): boolean {
     path === "/api/v1/servers" ||
     path.startsWith("/api/v1/servers/") ||
     path === "/api/v1/me/handle" ||
+    // Public to read, so it must not be behind a share key either.
+    path === "/api/v1/opendirs" ||
+    path.startsWith("/api/v1/opendirs/") ||
     OAUTH_ROUTE.test(path)
   );
 }
@@ -783,6 +787,8 @@ export interface HandlerOptions {
   servers?: Servers;
   /** The name other people see, which is never the address they signed up with. */
   handles?: Handles;
+  /** Open directories people have found, which anyone may read. */
+  openDirs?: OpenDirs;
   /** True when this instance is reached over https, for the cookie's Secure. */
   secureCookies?: boolean;
   /** A certificate and key in PEM, when this server is to speak https itself. */
@@ -1495,6 +1501,79 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       return;
     }
 
+    // --- open directories somebody found -----------------------------------
+    //
+    // Its own list, not the stream directory: that one is what is playing now,
+    // with a heartbeat and a room code and somebody at the other end, and this
+    // one is a folder on the web that is always there and belongs to nobody
+    // here. Reading needs no account. Adding does, because a public list with
+    // nobody accountable for its rows is a list of whatever anyone felt like.
+    if ((path === "/api/v1/opendirs" || path.startsWith("/api/v1/opendirs/")) && options.openDirs) {
+      const dirs = options.openDirs;
+
+      if (path === "/api/v1/opendirs" && request.method === "GET") {
+        const limit = Number(url.searchParams.get("limit") ?? "50");
+        const before = Number(url.searchParams.get("before") ?? "0");
+        const page = await dirs.list(Number.isFinite(limit) ? limit : 50, Number.isFinite(before) ? before : 0);
+        const names = options.handles ? await options.handles.many(page.addedBy) : new Map<string, string>();
+        json(response, 200, {
+          opendirs: page.rows.map((row, at) => ({
+            ...row,
+            // A handle or nothing. The address that signed up is never here.
+            by: names.get(page.addedBy[at] ?? "") ?? "",
+          })),
+          next: page.next,
+        });
+        return;
+      }
+
+      if (path === "/api/v1/opendirs" && request.method === "POST" && options.accounts) {
+        const who = await options.accounts.whoIs(tokenFrom(request.headers));
+        if (who === null) {
+          json(response, 401, { error: "sign in to publish one" });
+          return;
+        }
+        let body: { url?: unknown; name?: unknown };
+        try {
+          body = JSON.parse(await readBody(request)) as typeof body;
+        } catch {
+          json(response, 400, { error: "bad JSON" });
+          return;
+        }
+
+        // Read before publishing. A row nobody can play is worse than no row,
+        // and the count is the one fact a reader wants before clicking.
+        const listed = typeof body.url === "string" ? await readRemoteIndex(body.url) : [];
+        if (listed.length === 0) {
+          json(response, 422, { error: "nothing playable was linked from that page" });
+          return;
+        }
+        const made = await dirs.add(who.id, body.url, body.name, listed.length);
+        if (made === null) {
+          json(response, 422, { error: "that needs an http or https address" });
+          return;
+        }
+        const handle = options.handles ? await options.handles.of(who.id) : "";
+        json(response, 201, { opendir: { ...made, by: handle } });
+        return;
+      }
+
+      const dirId = path.slice("/api/v1/opendirs/".length);
+      if (dirId && request.method === "DELETE" && options.accounts) {
+        const who = await options.accounts.whoIs(tokenFrom(request.headers));
+        if (who === null) {
+          json(response, 401, { error: "not signed in" });
+          return;
+        }
+        const gone = await dirs.remove(who.id, dirId);
+        json(response, gone ? 200 : 404, gone ? { ok: true } : { error: "not yours, or not there" });
+        return;
+      }
+
+      json(response, 405, { error: "GET, POST or DELETE" });
+      return;
+    }
+
     // --- coming back from a provider ---------------------------------------
     //
     // /api/v1/<provider>/oauth/start sends a browser away, and .../callback is
@@ -2678,7 +2757,9 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
           // all: a browser already signed in can approve a terminal.
           // The same pool the follows and reminders use: three small tables in
           // one database do not want three sets of connections.
-          ...(pool ? { servers: new Servers(pool), handles: new Handles(pool) } : {}),
+          ...(pool
+            ? { servers: new Servers(pool), handles: new Handles(pool), openDirs: new OpenDirs(pool) }
+            : {}),
           signIn: new SignIn(
             providersFrom(process.env),
             new DeviceGrants(),

package/src/session.ts

@@ -659,3 +659,103 @@ interface ServerRow {
   url: string;
   key: string;
 }
+
+/** One row of the public open-directory list, as the API sends it. */
+interface OpenDirRow {
+  id: string;
+  url: string;
+  name: string;
+  tracks: number;
+  by: string;
+}
+
+/**
+ * `nixamp opendir list|add|remove`, the public list of folders people found.
+ *
+ * Reading needs no account, which is why `list` works signed out. Adding needs
+ * one, because a public list with nobody accountable for its rows is a list of
+ * whatever anybody felt like putting there.
+ */
+export async function opendirs(argv: string[], fetcher: typeof fetch = fetch): Promise<number> {
+  const [command = "list", ...rest] = argv;
+  const session = readSession();
+  const site = session?.site ?? DEFAULT_DIRECTORY;
+  const where = `${site}/api/v1/opendirs`;
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    ...(session ? { authorization: `Bearer ${session.token}` } : {}),
+  };
+  const at = (flag: string): string | undefined => {
+    const index = rest.indexOf(flag);
+    return index === -1 ? undefined : rest[index + 1];
+  };
+
+  try {
+    if (command === "list" || command === "ls") {
+      const answer = await fetcher(where, { headers });
+      const body = (await answer.json().catch(() => ({}))) as { opendirs?: OpenDirRow[]; error?: string };
+      if (!answer.ok) {
+        console.error(`nixamp: ${body.error ?? `could not read the list (${answer.status})`}`);
+        return 1;
+      }
+      const rows = body.opendirs ?? [];
+      if (rows.length === 0) {
+        console.log("Nothing published yet. `nixamp opendir add <url>` puts one there.");
+        return 0;
+      }
+      const width = Math.max(...rows.map((row) => row.name.length));
+      for (const row of rows) {
+        const who = row.by ? ` by ${row.by}` : "";
+        console.log(`${row.id}  ${row.name.padEnd(width)}  ${row.tracks} tracks${who}`);
+        console.log(`  ${row.url}`);
+      }
+      return 0;
+    }
+
+    if (session === null) {
+      console.error("nixamp: sign in to publish or remove one. Try `nixamp login`.");
+      return 1;
+    }
+
+    if (command === "add" || command === "publish") {
+      const target = rest.find((a) => /^https?:\/\//.test(a)) ?? "";
+      if (!target) {
+        console.error("nixamp: which folder? Give the URL of a directory listing.");
+        return 64;
+      }
+      const answer = await fetcher(where, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ url: target, name: at("--name") ?? "" }),
+      });
+      const body = (await answer.json().catch(() => ({}))) as { opendir?: OpenDirRow; error?: string };
+      if (!answer.ok || !body.opendir) {
+        console.error(`nixamp: ${body.error ?? `could not publish it (${answer.status})`}`);
+        return 1;
+      }
+      console.log(`${body.opendir.id}  ${body.opendir.name}  ${body.opendir.tracks} tracks`);
+      return 0;
+    }
+
+    if (command === "remove" || command === "rm") {
+      const id = rest.find((a) => !a.startsWith("-")) ?? "";
+      if (!id) {
+        console.error("nixamp: which one? `nixamp opendir list` shows their ids.");
+        return 64;
+      }
+      const answer = await fetcher(`${where}/${encodeURIComponent(id)}`, { method: "DELETE", headers });
+      if (!answer.ok) {
+        console.error(`nixamp: ${answer.status === 404 ? "not yours, or not there" : "could not remove it"}`);
+        return 1;
+      }
+      console.log(`Removed ${id}.`);
+      return 0;
+    }
+
+    console.error(`nixamp: no such opendir command: ${command}`);
+    return 64;
+  } catch (error) {
+    console.error(`nixamp: could not reach ${site}: ${(error as Error).message}`);
+    return 69;
+  }
+}

package/web/dist/index.html

@@ -173,5 +173,6 @@
         <a href="https://github.com/profullstack/nixamp">github.com/profullstack/nixamp</a>
       </footer>
     </main>
+      <script data-site="f6b791a3-13e0-4212-a2c9-abafc3b7aff0" src="https://crawlproof.com/stats.js" async></script>
   </body>
 </html>

package/web/dist/sw.js

@@ -1,5 +1,5 @@
 /* nixamp service worker — generated, do not edit */
-const CACHE = "nixamp-1788945979682";
+const CACHE = "nixamp-1788946637747";
 const PRECACHE = [
   "/",
   "/apple-touch-icon.png",