nixamp 0.6.1 → 0.7.0

package/dist/audio.d.ts

@@ -58,6 +58,20 @@ export declare function peaks(pcm: Float32Array): [number, number];
 /** Interleaved stereo down to mono, for the analyser. */
 export declare function toMono(pcm: Float32Array): Float32Array;
 export declare function formatTime(seconds: number): string;
+/**
+ * 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 declare function probeAsync(tools: Tools, path: string): Promise<Track>;
 /** 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. */
@@ -82,4 +96,13 @@ export declare 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 declare function videoArgs(codecs: Codecs): string[];
+export declare function videoArgs(codecs: Codecs, capKbps?: number): string[];
+/**
+ * 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 declare function widthFor(kbps: number): number;

package/dist/audio.js

@@ -204,6 +204,77 @@ export function formatTime(seconds) {
     const s = total % 60;
     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, path) {
+    const [cmd, ...rest] = tools.ffprobe;
+    const fallback = {
+        path,
+        title: path.split("/").pop() ?? path,
+        artist: "",
+        album: "",
+        duration: 0,
+    };
+    if (!cmd)
+        return fallback;
+    return new Promise((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) => {
+            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, fallback) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const tags = parsed.format?.tags ?? {};
+        const lower = {};
+        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;
+    }
+}
 /**
  * Ask ffprobe what the streams are, without holding the event loop.
  *
@@ -253,7 +324,11 @@ export async function codecsOf(tools, path) {
  * 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) {
+export function videoArgs(codecs, capKbps = 0) {
+    // 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";
@@ -269,3 +344,43 @@ export function videoArgs(codecs) {
         "-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) {
+    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) {
+    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/dist/handles.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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";
+/**
+ * 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 declare function cleanHandle(value: unknown): string;
+export declare function isReserved(handle: string): boolean;
+/**
+ * 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 declare function anonymousHandle(random: (size: number) => Uint8Array): string;
+export declare class Handles {
+    private readonly db;
+    private ready;
+    constructor(db: Queryable);
+    private ensure;
+    of(userId: string): Promise<string>;
+    /** Who holds this handle, so a listing can name somebody without their address. */
+    holder(handle: string): Promise<string>;
+    /**
+     * 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.
+     */
+    claim(userId: string, wanted: unknown): Promise<{
+        handle: string;
+        error: string;
+    }>;
+}

package/dist/handles.js

@@ -0,0 +1,99 @@
+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) {
+    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) {
+    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) {
+    const bytes = random(4);
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return `nixamp-${out}`;
+}
+export class Handles {
+    db;
+    ready = null;
+    constructor(db) {
+        this.db = db;
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    async of(userId) {
+        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) {
+        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, wanted) {
+        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/dist/invite.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare function isPhone(value: string): boolean;
+/** Looks like somewhere an email could arrive. */
+export declare function isEmail(value: string): boolean;
+/**
+ * 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 declare function inviteText(invite: Invite): string;
+/** The same thing as a subject line, for the surface that wants one. */
+export declare function inviteSubject(invite: Invite): string;
+/**
+ * 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 declare function watchLink(streamUrl: string, site: string): string;

package/dist/invite.js

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+/** Looks like a phone number rather than an address. */
+export function isPhone(value) {
+    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) {
+    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) {
+    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) {
+    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, site) {
+    const bare = streamUrl.replace(/\/+$/, "");
+    if (!bare.startsWith("https://"))
+        return bare;
+    return `${site.replace(/\/+$/, "")}/?url=${encodeURIComponent(bare)}`;
+}

package/dist/playlist.d.ts

@@ -10,6 +10,19 @@ export declare function findAudio(root: string): string[];
  * ffmpeg is left to do what it is good at.
  */
 export declare function readPlaylist(source: string): Promise<Entry[]>;
+/**
+ * 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 declare function readRemoteIndex(source: string, send?: typeof fetch): Promise<Entry[]>;
 /**
  * Everything `nixamp <thing>` can be handed: a directory, a file, a playlist,
  * or a URL to any of those.
@@ -38,5 +51,7 @@ export declare function loadPlaylist(tools: Tools, root: string, probeTags?: boo
  * ffprobe rather than for the whole library, and the tagging still finishes in
  * about the time it did.
  */
-export declare function loadTagged(tools: Tools, source: string): Promise<Track[]>;
+export declare 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>): Promise<Track[]>;
 export declare function displayName(track: Track): string;

package/dist/playlist.js

@@ -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 } from "./audio.js";
+import { probe, probeAsync } from "./audio.js";
 import { isHls, isPlaylistFile, isRemote, nameOf, parseM3u, parsePls, } from "./sources.js";
 export const AUDIO_EXTENSIONS = new Set([
     ".mp3", ".flac", ".ogg", ".oga", ".opus", ".m4a", ".aac",
@@ -81,6 +81,69 @@ export async function readPlaylist(source) {
     const entries = /\.pls$/i.test(source) ? parsePls(text, source) : parseM3u(text, source);
     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, send = fetch) {
+    let answer;
+    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 = [];
+    const seen = new Set();
+    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;
+        try {
+            // Relative to the page, which is how an index writes them.
+            url = new URL(href.replace(/&/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.
@@ -104,10 +167,19 @@ export async function loadSource(tools, source, probeTags = true) {
             ? { ...probe(tools, entry.source), title: entry.title || probe(tools, entry.source).title }
             : bare(entry));
     }
-    // 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))
+    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);
 }
 /**
@@ -135,15 +207,20 @@ export function loadPlaylist(tools, root, probeTags = true) {
  * ffprobe rather than for the whole library, and the tagging still finishes in
  * about the time it did.
  */
-export async function loadTagged(tools, source) {
+export async function loadTagged(tools, source, 
+/** Injected by the test, which must not depend on ffprobe being installed. */
+probeOne = probeAsync) {
     // 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 = [];
     for (const path of paths) {
-        tracks.push(probe(tools, path));
-        await new Promise((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;
 }

package/dist/server.d.ts

@@ -4,6 +4,7 @@ import { Broadcaster, type Destination, type EncoderSettings } from "./broadcast
 import { Ingest } from "./ingest.ts";
 import { Channels } from "./channels.ts";
 import { Accounts } from "./accounts.ts";
+import { Handles } from "./handles.ts";
 import { Servers } from "./servers.ts";
 import { SignIn } from "./oauth.ts";
 import { Owner } from "./owner.ts";
@@ -269,6 +270,8 @@ export interface HandlerOptions {
     signIn?: SignIn;
     /** The servers each account runs, on the instance that keeps accounts. */
     servers?: Servers;
+    /** The name other people see, which is never the address they signed up with. */
+    handles?: Handles;
     /** 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. */