nixamp 0.6.1 → 0.7.0

package/dist/server.js

@@ -12,6 +12,7 @@
 import { createReadStream, statSync } from "node:fs";
 import { createServer as createHttpServer } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
+import { randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
@@ -21,6 +22,7 @@ import { Ingest, normaliseFormat } from "./ingest.js";
 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 { Servers } from "./servers.js";
 import { DeviceGrants } from "./device.js";
 import { BAD_KEY_LIMIT, callerOf, Guard, SIGN_IN_LIMIT } from "./guard.js";
@@ -555,6 +557,7 @@ export function isSignInPath(path) {
         // rather than by a share key it has nothing to do with.
         path === "/api/v1/servers" ||
         path.startsWith("/api/v1/servers/") ||
+        path === "/api/v1/me/handle" ||
         OAUTH_ROUTE.test(path));
 }
 function html(response, code, body) {
@@ -994,6 +997,42 @@ export function createHandler(engine, options) {
                 json(response, 404, { error: "no such endpoint" });
                 return;
             }
+            // --- the name other people see ---------------------------------------
+            //
+            // Separate from the address on purpose. The address is a credential and
+            // a way to reach somebody; publishing it in a directory listing or an
+            // invite would be publishing what they log in with.
+            if (path === "/api/v1/me/handle" && options.handles) {
+                const handles = options.handles;
+                const who = await accounts.whoIs(tokenFrom(request.headers));
+                if (who === null) {
+                    json(response, 401, { error: "not signed in" });
+                    return;
+                }
+                if (request.method === "GET") {
+                    json(response, 200, { handle: await handles.of(who.id) });
+                    return;
+                }
+                if (request.method === "PUT" || request.method === "POST") {
+                    let body;
+                    try {
+                        body = JSON.parse(await readBody(request));
+                    }
+                    catch {
+                        json(response, 400, { error: "bad JSON" });
+                        return;
+                    }
+                    const claimed = await handles.claim(who.id, body.handle);
+                    if (claimed.error) {
+                        json(response, 409, { error: claimed.error });
+                        return;
+                    }
+                    json(response, 200, { handle: claimed.handle });
+                    return;
+                }
+                json(response, 405, { error: "GET or PUT" });
+                return;
+            }
             // --- the servers this account runs ----------------------------------
             //
             // Kept against the account rather than the machine, so the list reads the
@@ -1140,6 +1179,17 @@ export function createHandler(engine, options) {
             const result = signingUp
                 ? await accounts.signUp(body.email, body.password)
                 : await accounts.signIn(body.email, body.password);
+            // A handle asked for at sign-up, or one nobody has to think about. Never
+            // derived from the address: turning anthony@… into "anthony" is the leak
+            // this whole idea exists to avoid, and it is one nobody would notice
+            // until it was already in a directory listing.
+            if (signingUp && result.ok && result.account && options.handles) {
+                const asked = body.handle;
+                const claimed = await options.handles.claim(result.account.id, asked);
+                if (claimed.error) {
+                    await options.handles.claim(result.account.id, anonymousHandle((size) => randomBytes(size)));
+                }
+            }
             // Getting it right costs nothing: the counters only exist to stop people
             // who keep getting it wrong.
             if (result.ok)
@@ -1655,7 +1705,12 @@ export function createHandler(engine, options) {
             // to it raw is bytes it cannot play. Seeking is what this route is for
             // and transcoding gives it up, but an unseekable film beats a silent
             // one -- and the seekable formats are untouched.
-            if (playsInBrowser(file)) {
+            // A ceiling the caller asked for, because only the caller knows what its
+            // link can carry. Capped at both ends: nothing below 200k is watchable,
+            // and above 20 megabits the original was always the better answer.
+            const asked = Number(url.searchParams.get("kbps") ?? "");
+            const capKbps = Number.isFinite(asked) && asked > 0 ? Math.min(20_000, Math.max(200, asked)) : 0;
+            if (playsInBrowser(file) && capKbps === 0) {
                 sendFile(request, response, file);
             }
             else if (hasPicture(file)) {
@@ -1663,7 +1718,7 @@ export function createHandler(engine, options) {
                 // soundtrack over a blank panel; what ffprobe finds inside decides how
                 // little work it takes to keep the picture.
                 const codecs = await codecsOf({ ffmpeg: [], ffprobe: options.ffprobe ?? ["ffprobe"], play: null }, file);
-                pipeFfmpeg(request, response, file, options.ffmpeg ?? ["ffmpeg"], videoArgs(codecs), "video/mp4");
+                pipeFfmpeg(request, response, file, options.ffmpeg ?? ["ffmpeg"], videoArgs(codecs, capKbps), "video/mp4");
             }
             else {
                 transcode(request, response, file, options.ffmpeg ?? ["ffmpeg"]);
@@ -2269,7 +2324,7 @@ 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) } : {}),
+                ...(pool ? { servers: new Servers(pool), handles: new Handles(pool) } : {}),
                 signIn: new SignIn(providersFrom(process.env), new DeviceGrants(), process.env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY),
             }
             : {}),

package/package.json

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

package/src/audio.ts

@@ -232,6 +232,82 @@ export function formatTime(seconds: number): string {
   return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
 }
 
+/**
+ * The same tags, read without blocking anything.
+ *
+ * `probe` is spawnSync, and 0.5.5 tried to fix the tagging pass by yielding
+ * between files. That is not enough: each individual call still stops the
+ * process for as long as one ffprobe takes, and on a large file over a slow
+ * disk that is hundreds of milliseconds. Yield, block, yield, block, and a
+ * server delivers a stream in slivers -- measured at 357 KB/s on a machine
+ * whose disk reads at 6.5 MB/s and whose link runs at 1.4 Gbps.
+ *
+ * ffprobe still costs what it costs. It just costs it in a child process now,
+ * which is where that work belongs.
+ */
+export async function probeAsync(tools: Tools, path: string): Promise<Track> {
+  const [cmd, ...rest] = tools.ffprobe;
+  const fallback: Track = {
+    path,
+    title: path.split("/").pop() ?? path,
+    artist: "",
+    album: "",
+    duration: 0,
+  };
+  if (!cmd) return fallback;
+
+  return new Promise<Track>((done) => {
+    const child = spawn(
+      cmd,
+      [
+        ...rest,
+        "-v", "quiet", "-print_format", "json",
+        "-show_format", "-show_entries", "format_tags=title,artist,album",
+        path,
+      ],
+      { stdio: ["ignore", "pipe", "ignore"] },
+    );
+    let out = "";
+    // A file that will not answer must not hold a place in the queue for ever.
+    const giveUp = setTimeout(() => child.kill("SIGKILL"), 20_000);
+    giveUp.unref?.();
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (out.length < 4 * 1024 * 1024) out += chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      clearTimeout(giveUp);
+      done(fallback);
+    });
+    child.on("close", (code) => {
+      clearTimeout(giveUp);
+      if (code !== 0) return done(fallback);
+      done(readTags(out, fallback));
+    });
+  });
+}
+
+/** The tags out of ffprobe's JSON, or the filename when it said nothing useful. */
+function readTags(stdout: string, fallback: Track): Track {
+  try {
+    const parsed = JSON.parse(stdout) as {
+      format?: { duration?: string; tags?: Record<string, string> };
+    };
+    const tags = parsed.format?.tags ?? {};
+    const lower: Record<string, string> = {};
+    for (const [k, v] of Object.entries(tags)) lower[k.toLowerCase()] = v;
+    return {
+      path: fallback.path,
+      title: lower.title || fallback.title,
+      artist: lower.artist ?? "",
+      album: lower.album ?? "",
+      duration: Number(parsed.format?.duration ?? 0) || 0,
+    };
+  } catch {
+    return fallback;
+  }
+}
+
 /** What is actually inside a container, as opposed to what the name suggests. */
 export interface Codecs {
   /** e.g. "h264", "hevc", "vp9". Empty when there is no video stream. */
@@ -293,7 +369,11 @@ export async function codecsOf(tools: Tools, path: string): Promise<Codecs> {
  * would cost a core per viewer and look worse. So the streams decide, one part
  * at a time -- a film can have its video copied and only its DTS re-encoded.
  */
-export function videoArgs(codecs: Codecs): string[] {
+export function videoArgs(codecs: Codecs, capKbps = 0): string[] {
+  // A ceiling means re-encoding whatever is there, because you cannot cap the
+  // bitrate of a stream you are copying: copying is what "unchanged" means.
+  if (capKbps > 0) return cappedArgs(capKbps);
+
   // What a browser can play inside MP4 without help.
   const keepVideo = codecs.video === "h264";
   const keepAudio = codecs.audio === "aac" || codecs.audio === "mp3";
@@ -309,3 +389,42 @@ export function videoArgs(codecs: Codecs): string[] {
     "-movflags", "frag_keyframe+empty_moov+default_base_moof",
   ];
 }
+
+/**
+ * The width that suits a bitrate.
+ *
+ * 1080p squeezed into a megabit is worse than 360p at the same megabit: the
+ * encoder spends everything it has on detail it cannot afford and the result
+ * smears on every motion. Dropping the resolution with the bitrate is what
+ * makes a small stream watchable rather than merely small.
+ */
+export function widthFor(kbps: number): number {
+  if (kbps <= 800) return 640;
+  if (kbps <= 1800) return 854;
+  if (kbps <= 4000) return 1280;
+  return 1920;
+}
+
+/** Arguments for a stream that has to fit through a link of a known size. */
+function cappedArgs(kbps: number): string[] {
+  const audioKbps = kbps <= 800 ? 96 : 128;
+  const videoKbps = Math.max(200, kbps - audioKbps);
+  return [
+    "-c:v", "libx264",
+    "-preset", "veryfast",
+    "-pix_fmt", "yuv420p",
+    // -2 keeps the aspect ratio and an even height, which H.264 requires.
+    // The min() never enlarges: a 480p source asked for 720p stays 480p.
+    "-vf", `scale='min(${widthFor(kbps)},iw)':-2`,
+    "-b:v", `${videoKbps}k`,
+    // A ceiling rather than an average, because an average that spikes is a
+    // stall on a link this size. The buffer is one second of it.
+    "-maxrate", `${videoKbps}k`,
+    "-bufsize", `${videoKbps}k`,
+    "-c:a", "aac",
+    "-b:a", `${audioKbps}k`,
+    "-ac", "2",
+    "-f", "mp4",
+    "-movflags", "frag_keyframe+empty_moov+default_base_moof",
+  ];
+}

package/src/handles.ts

@@ -0,0 +1,120 @@
+/**
+ * The name other people see.
+ *
+ * An account is keyed on an email address, because that is what the auth module
+ * authenticates. An address is a credential and a way to reach somebody, and it
+ * is not a name: putting it in a directory listing, an invite or a subdomain
+ * publishes something the account holder gave us to log in with.
+ *
+ * So there are two names. The address stays private and does the linking, and a
+ * handle is the one that appears in front of strangers. They are never the same
+ * field and never travel in the same response.
+ */
+import type { Queryable } from "./follows.ts";
+
+const TABLE = "nixamp_handles";
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    user_id    TEXT PRIMARY KEY,
+    handle     TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS ${TABLE}_lower ON ${TABLE} (lower(handle));
+`;
+
+/**
+ * What a handle may be.
+ *
+ * It ends up in a URL, a subdomain and a text message, so it is the intersection
+ * of what all three tolerate: lowercase letters, digits and hyphens, not
+ * starting or ending with one. Two to thirty characters, because a subdomain
+ * label cannot exceed sixty-three and nobody types thirty.
+ */
+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 "";
+  // 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;
+}
+
+/**
+ * Names nobody may take, because a subdomain carrying one would impersonate the
+ * service or reach a machine we run.
+ */
+const RESERVED = new Set([
+  "www", "api", "admin", "root", "nixamp", "mail", "smtp", "imap", "ns1", "ns2",
+  "static", "cdn", "assets", "app", "dev", "staging", "test", "support", "help",
+  "status", "blog", "directory", "login", "signup", "account", "settings", "me",
+]);
+
+export function isReserved(handle: string): boolean {
+  return RESERVED.has(handle);
+}
+
+/**
+ * A handle for somebody who has not chosen one.
+ *
+ * Deliberately not derived from the address. "anthony@profullstack.com" turning
+ * into "anthony" is exactly the leak this whole file exists to avoid, and it
+ * would be a leak nobody noticed until it was already in a directory listing.
+ */
+export function anonymousHandle(random: (size: number) => Uint8Array): string {
+  const bytes = random(4);
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return `nixamp-${out}`;
+}
+
+export class Handles {
+  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;
+  }
+
+  async of(userId: string): Promise<string> {
+    await this.ensure();
+    const { rows } = await this.db.query(`SELECT handle FROM ${TABLE} WHERE user_id = $1`, [userId]);
+    return rows[0] ? String(rows[0]["handle"] ?? "") : "";
+  }
+
+  /** Who holds this handle, so a listing can name somebody without their address. */
+  async holder(handle: string): Promise<string> {
+    const wanted = cleanHandle(handle);
+    if (!wanted) return "";
+    await this.ensure();
+    const { rows } = await this.db.query(`SELECT user_id FROM ${TABLE} WHERE lower(handle) = $1`, [wanted]);
+    return rows[0] ? String(rows[0]["user_id"] ?? "") : "";
+  }
+
+  /**
+   * Claim one. Answers the reason it could not be taken rather than a boolean,
+   * because "that is already somebody's" and "that is not a name" are different
+   * things to tell a person.
+   */
+  async claim(userId: string, wanted: unknown): Promise<{ handle: string; error: string }> {
+    const handle = cleanHandle(wanted);
+    if (!handle) {
+      return { handle: "", error: "letters, digits and hyphens, 2 to 30 characters" };
+    }
+    if (isReserved(handle)) return { handle: "", error: "that one is reserved" };
+
+    await this.ensure();
+    const taken = await this.holder(handle);
+    if (taken && taken !== userId) return { handle: "", error: "somebody already has that one" };
+
+    await this.db.query(
+      `INSERT INTO ${TABLE} (user_id, handle) VALUES ($1, $2)
+       ON CONFLICT (user_id) DO UPDATE SET handle = EXCLUDED.handle, updated_at = NOW()`,
+      [userId, handle],
+    );
+    return { handle, error: "" };
+  }
+}

package/src/invite.ts

@@ -0,0 +1,74 @@
+/**
+ * Asking somebody to watch, when that somebody is not technical.
+ *
+ * A share link is a URL with a key in it, which is fine for the person who
+ * runs the server and useless as a thing to text your mother. An invite is the
+ * three ways in, written as a sentence: a link that opens a player, a phone
+ * number, and the code to key once it answers.
+ *
+ * The sender is signed in, because sending is an action with a cost: a text
+ * message is money and somebody's phone. The recipient signs in too, but only
+ * once and only at the far end of a single click, because a stream can ask to
+ * be paid for -- x402 starts charging past five listeners -- and there is
+ * nobody to charge without an account. The dial-in path is the exception and
+ * stays open to anybody, since a phone call cannot sign in to anything.
+ */
+
+/** Where the phone line answers, and what to key when it does. */
+export interface Invite {
+  /** What the stream is called, as the recipient will see it. */
+  name: string;
+  /** A link that opens a player on this stream, listen only. */
+  link: string;
+  /** The phone number, when this stream is one the line knows about. */
+  phone: string;
+  /** The six digits that reach this stream, when it has been published. */
+  code: string;
+}
+
+/** Looks like a phone number rather than an address. */
+export function isPhone(value: string): boolean {
+  return /^\+?[\d\s().-]{7,20}$/.test(value.trim()) && /\d{7}/.test(value.replace(/\D/g, ""));
+}
+
+/** Looks like somewhere an email could arrive. */
+export function isEmail(value: string): boolean {
+  return /^[^@\s]+@[^@\s.]+\.[^@\s]+$/.test(value.trim());
+}
+
+/**
+ * The message itself.
+ *
+ * Short, because it is going into a text message, and ordered by how likely
+ * each way in is to work for the person reading it. The link first: most
+ * people have a browser in their hand. The phone last, because it is the one
+ * that needs no browser at all and is therefore the fallback that never fails.
+ */
+export function inviteText(invite: Invite): string {
+  const lines = [`${invite.name} is streaming.`, "", `Watch: ${invite.link}`];
+  if (invite.phone && invite.code) {
+    lines.push("", `Or call ${invite.phone} and key ${invite.code} to listen.`);
+  }
+  return lines.join("\n");
+}
+
+/** The same thing as a subject line, for the surface that wants one. */
+export function inviteSubject(invite: Invite): string {
+  return `${invite.name} is streaming`;
+}
+
+/**
+ * A link that opens a player on this stream.
+ *
+ * Sent through nixamp.com when the stream is https, because that page is a
+ * player anybody can already open and reaches this stream with `?url=`. An
+ * http stream is sent as its own address instead: a browser refuses every
+ * request from an https page to an http one, so routing it through nixamp.com
+ * would produce a link that cannot work, which is worse than a plainer one
+ * that does.
+ */
+export function watchLink(streamUrl: string, site: string): string {
+  const bare = streamUrl.replace(/\/+$/, "");
+  if (!bare.startsWith("https://")) return bare;
+  return `${site.replace(/\/+$/, "")}/?url=${encodeURIComponent(bare)}`;
+}

package/src/playlist.ts

@@ -1,7 +1,7 @@
 /** The playlist: audio found on disk or named by a playlist, in a stable order. */
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { probe, type Tools, type Track } from "./audio.ts";
+import { probe, probeAsync, type Tools, type Track } from "./audio.ts";
 import {
   type Entry,
   isHls,
@@ -87,6 +87,64 @@ export async function readPlaylist(source: string): Promise<Entry[]> {
   return entries;
 }
 
+/**
+ * The audio linked from a directory listing a web server generated.
+ *
+ * A seedbox or a plain Apache with autoindex on serves a folder as an HTML page
+ * of relative links. Handed one of those, nixamp used to make a single track of
+ * the page itself and give it to ffmpeg, which is asked to decode HTML and says
+ * so in a way nobody reads. It is a folder; it should behave like one.
+ *
+ * Not recursive, deliberately: one page is one album, the subdirectory links are
+ * on it, and walking a stranger's whole tree from a text box is a different and
+ * much larger thing to ask for.
+ */
+export async function readRemoteIndex(source: string, send: typeof fetch = fetch): Promise<Entry[]> {
+  let answer: Response;
+  try {
+    answer = await send(source, {
+      redirect: "follow",
+      headers: { accept: "text/html,*/*" },
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch {
+    return [];
+  }
+  if (!answer.ok) return [];
+  // Anything that is not a page is the thing itself, and the caller plays it.
+  if (!/^text\/html/i.test(answer.headers.get("content-type") ?? "")) return [];
+
+  const html = await answer.text().catch(() => "");
+  const found: Entry[] = [];
+  const seen = new Set<string>();
+  for (const match of html.matchAll(/href\s*=\s*["']([^"']+)["']/gi)) {
+    const href = match[1];
+    // The sort links an index puts at the top of every column, and anchors.
+    if (!href || href.startsWith("?") || href.startsWith("#")) continue;
+    let url: URL;
+    try {
+      // Relative to the page, which is how an index writes them.
+      url = new URL(href.replace(/&amp;/g, "&"), source);
+    } catch {
+      continue;
+    }
+    if (!isAudio(url.pathname)) continue;
+    const link = url.toString();
+    if (seen.has(link)) continue;
+    seen.add(link);
+    found.push({
+      source: link,
+      // The name as a person wrote it, not as a URL spells it.
+      title: decodeURIComponent(url.pathname.split("/").pop() ?? link),
+      duration: 0,
+    });
+  }
+  // Server order is by whatever column the index sorted on; by name is what
+  // somebody handing over an album meant.
+  found.sort((a, b) => a.title.localeCompare(b.title, undefined, { numeric: true }));
+  return found;
+}
+
 /**
  * Everything `nixamp <thing>` can be handed: a directory, a file, a playlist,
  * or a URL to any of those.
@@ -112,9 +170,18 @@ export async function loadSource(tools: Tools, source: string, probeTags = true)
     );
   }
 
-  // A bare URL is one remote thing to play. Whether it is a song or a live
-  // stream is ffmpeg's problem, and it is good at it.
-  if (isRemote(source)) return [bare({ source, title: nameOf(source), duration: 0 })];
+  if (isRemote(source)) {
+    // A URL that names no file is probably a folder, and a folder served over
+    // http is a page of links. Asked only when it could be one: a stream URL
+    // must not pay for a fetch that will tell us nothing.
+    if (!isAudio(new URL(source).pathname)) {
+      const listed = await readRemoteIndex(source);
+      if (listed.length > 0) return listed.map(bare);
+    }
+    // A bare URL is one remote thing to play. Whether it is a song or a live
+    // stream is ffmpeg's problem, and it is good at it.
+    return [bare({ source, title: nameOf(source), duration: 0 })];
+  }
 
   return loadPlaylist(tools, source, probeTags);
 }
@@ -146,15 +213,23 @@ export function loadPlaylist(tools: Tools, root: string, probeTags = true): Trac
  * ffprobe rather than for the whole library, and the tagging still finishes in
  * about the time it did.
  */
-export async function loadTagged(tools: Tools, source: string): Promise<Track[]> {
+export async function loadTagged(
+  tools: Tools,
+  source: string,
+  /** Injected by the test, which must not depend on ffprobe being installed. */
+  probeOne: (tools: Tools, path: string) => Promise<Track> = probeAsync,
+): Promise<Track[]> {
   // A URL is one thing and is never probed; a playlist carries its own titles.
   if (isRemote(source) || isPlaylistFile(source)) return loadSource(tools, source, true);
 
   const paths = findAudio(source);
   const tracks: Track[] = [];
   for (const path of paths) {
-    tracks.push(probe(tools, path));
-    await new Promise<void>((done) => setImmediate(done));
+    // Awaiting a child process, not blocking on one. Yielding between files
+    // was not enough: each spawnSync still stopped everything for as long as
+    // one ffprobe took, which on a large file is long enough to strangle a
+    // stream being served at the same time.
+    tracks.push(await probeOne(tools, path));
   }
   return tracks;
 }