nixamp 0.7.41 → 0.9.3

package/dist/catalogs.d.ts

@@ -0,0 +1,100 @@
+export interface CatalogEntry {
+    /** Stable across refreshes: a hash of the source, so a link to it survives. */
+    id: string;
+    title: string;
+    group: string;
+    logo: string;
+    /** Where the bytes are. Never shown to a listener. */
+    source: string;
+    live: boolean;
+    /** Seconds, when the list said; 0 for live and for "did not say". */
+    duration: number;
+}
+export interface CatalogInfo {
+    id: string;
+    name: string;
+    /** Where the list is read from. Shown to administrators only. */
+    source: string;
+    addedAt: number;
+    refreshedAt: number;
+    entries: number;
+    live: number;
+    vod: number;
+    groups: number;
+    /** What went wrong the last time it was read, or "". */
+    error: string;
+}
+/** A list bigger than this is not a playlist, it is a mistake. */
+export declare const MAX_LIST_BYTES: number;
+/** How long to wait for a provider before giving up on the list. */
+export declare const FETCH_TIMEOUT_MS = 30000;
+/**
+ * Live, or on demand?
+ *
+ * The list rarely says outright. A stated length is a film; a file extension
+ * is a file; an Xtream-shaped URL says /movie/ or /series/ for on demand and
+ * /live/ for a channel; and a bare stream key, an .m3u8 or an .ts is a channel.
+ */
+export declare function isLiveEntry(source: string, duration: number): boolean;
+export declare function entryId(source: string): string;
+/**
+ * Parse an extended m3u: `#EXTINF:-1 tvg-name="CNN" group-title="News",CNN HD`
+ * decorates the URL on the next line, and `#EXTGRP:News` names the group for
+ * lists that write it that way instead.
+ */
+export declare function parseCatalog(text: string, base: string): CatalogEntry[];
+export interface Group {
+    name: string;
+    count: number;
+    live: number;
+    vod: number;
+}
+/** Read a list, from disk or over the network, within reason. */
+export declare function readCatalog(source: string, send?: typeof fetch): Promise<string>;
+/**
+ * The catalogs on one server, and their entries.
+ *
+ * The index is small and written whenever it changes; each catalog's entries
+ * are kept in their own file so a restart does not have to ask every provider
+ * again before anybody can browse.
+ */
+export declare class Catalogs {
+    private readonly dir;
+    private readonly port;
+    private readonly send;
+    private readonly stored;
+    private readonly entries;
+    constructor(dir: string, port: number, send?: typeof fetch);
+    /** What was here last time, without asking any provider yet. */
+    load(): void;
+    /** Read every catalog that has no entries on disk. For boot. */
+    warm(): Promise<void>;
+    private cachePath;
+    private save;
+    private info;
+    list(): CatalogInfo[];
+    get(id: string): CatalogInfo | null;
+    /** Add a list and read it. The name is what a person called it, or the list's own filename. */
+    add(source: string, name: string): Promise<CatalogInfo>;
+    /** Read the list again. The old entries stay if the provider is down. */
+    refresh(id: string): Promise<CatalogInfo | null>;
+    remove(id: string): boolean;
+    groups(id: string): Group[] | null;
+    /** A page of entries: in one group, or all of them, matching a search. */
+    entries_(id: string, query: {
+        group?: string;
+        q?: string;
+        offset?: number;
+        limit?: number;
+    }): {
+        total: number;
+        entries: CatalogEntry[];
+    } | null;
+    entry(id: string, entryId_: string): CatalogEntry | null;
+}
+/** What a listener is shown of an entry: everything but where the bytes are. */
+export declare function shownEntry(entry: CatalogEntry): Omit<CatalogEntry, "source">;
+/** What a listener is shown of a catalog: everything but where the list is. */
+export declare function shownCatalog(info: CatalogInfo, admin: boolean): Omit<CatalogInfo, "source"> & {
+    source?: string;
+};

package/dist/certs.d.ts

@@ -0,0 +1,112 @@
+import type { DnsZone } from "./dns.ts";
+import type { Queryable } from "./follows.ts";
+export interface Issued {
+    /** PEM, the full chain. */
+    cert: string;
+    /** PEM. */
+    key: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+/** Where a DNS-01 challenge gets written, and unwritten. */
+export interface Challenge {
+    set(host: string, value: string): Promise<void>;
+    clear(host: string, value: string): Promise<void>;
+}
+/** Something that turns a list of names into a certificate. ACME, in production. */
+export interface Issuer {
+    issue(names: string[], challenge: Challenge): Promise<Issued>;
+}
+export interface AcmeIssuerOptions {
+    /** acme.directory.letsencrypt.production, or .staging while trying things out. */
+    directoryUrl: string;
+    /** The account contact Let's Encrypt writes to about expiry. */
+    email: string;
+    /** The account's private key, PEM. Kept by the caller; see Certs.accountKey. */
+    accountKey: () => Promise<string>;
+    /**
+     * How long to wait after writing the TXT before letting the CA look for it.
+     * A registrar's API answers at once; the world's resolvers do not.
+     */
+    propagationMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** A minute is what Porkbun's 600-second floor tends to cost in practice. */
+export declare const DEFAULT_PROPAGATION_MS = 60000;
+/** Renew inside the last thirty days, which is what Let's Encrypt recommends. */
+export declare const RENEW_BEFORE_MS: number;
+/** A failed order is worth trying again, but not every time somebody asks. */
+export declare const RETRY_AFTER_MS: number;
+/**
+ * Let's Encrypt, through acme-client, by DNS-01 only: a wildcard cannot be
+ * proved any other way, and the zone is the one thing nixamp.com does hold.
+ */
+export declare class AcmeIssuer implements Issuer {
+    private readonly options;
+    constructor(options: AcmeIssuerOptions);
+    issue(names: string[], challenge: Challenge): Promise<Issued>;
+}
+export type CertState = {
+    status: "ready";
+    cert: string;
+    key: string;
+    expiresAt: number;
+    renewing: boolean;
+} | {
+    status: "issuing";
+    since: number;
+} | {
+    status: "failed";
+    error: string;
+    at: number;
+} | {
+    status: "none";
+};
+export interface CertsOptions {
+    renewBeforeMs?: number;
+    retryAfterMs?: number;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/**
+ * The certificates, one per handle, and the work of getting them.
+ *
+ * The rows are the truth and survive a restart; what is in flight lives in
+ * memory, because nixamp.com is one process and an order interrupted by a
+ * deploy is simply started again when next asked for.
+ */
+export declare class Certs {
+    private readonly db;
+    private readonly zone;
+    private readonly issuer;
+    private ready;
+    private readonly work;
+    private readonly renewBeforeMs;
+    private readonly retryAfterMs;
+    private readonly now;
+    private readonly log;
+    constructor(db: Queryable, zone: DnsZone, issuer: Issuer, options?: CertsOptions);
+    private ensure;
+    /**
+     * The ACME account key, made once and kept. Losing it would not lose any
+     * certificate, but every renewal would register a new account, and Let's
+     * Encrypt rate-limits those too.
+     */
+    accountKey(): Promise<string>;
+    /** The names one handle's certificate covers: every server it has, and the handle itself. */
+    namesFor(handle: string): string[];
+    private stored;
+    /**
+     * A handle's certificate, or what is being done about the lack of one.
+     *
+     * Never blocks on the CA. With nothing stored, or something failed long
+     * enough ago to be worth another go, an order starts in the background and
+     * the answer is "issuing". With one stored that is near its end, the answer
+     * is still the old one -- it is valid -- and a renewal starts alongside.
+     */
+    forHandle(handle: string): Promise<CertState>;
+    /** Order in the background, and remember how it went. */
+    private begin;
+    /** For tests and shutdown: whatever order is in flight for a handle. */
+    settle(handle: string): Promise<void>;
+}

package/dist/certs.js

@@ -0,0 +1,217 @@
+/**
+ * Certificates: one wildcard per handle, issued and renewed by nixamp.com.
+ *
+ * A server that has been given `server2.chovy.nixamp.com` still answers over
+ * plain http until it has a certificate, and getting one by hand is exactly
+ * the manual step this exists to remove. So nixamp.com, which already holds
+ * the zone, does the whole thing: it orders `*.chovy.nixamp.com` and
+ * `chovy.nixamp.com` from Let's Encrypt, answers the DNS-01 challenge by
+ * writing the `_acme-challenge` TXT record itself, keeps the result in the
+ * database, renews it when it gets close to expiry, and hands cert and key
+ * to that account's servers over the authenticated API.
+ *
+ * One wildcard per handle, not one certificate per server. Let's Encrypt
+ * rate-limits per registered domain -- nixamp.com, for all of us -- and every
+ * server an account starts is covered by the wildcard it already has.
+ *
+ * The ACME dance takes minutes, mostly waiting for DNS to propagate, so it is
+ * never done inside a request. `forHandle` starts it in the background and
+ * answers "issuing"; the server asks again in a while.
+ */
+import acme from "acme-client";
+/** A minute is what Porkbun's 600-second floor tends to cost in practice. */
+export const DEFAULT_PROPAGATION_MS = 60_000;
+/** Renew inside the last thirty days, which is what Let's Encrypt recommends. */
+export const RENEW_BEFORE_MS = 30 * 24 * 60 * 60 * 1000;
+/** A failed order is worth trying again, but not every time somebody asks. */
+export const RETRY_AFTER_MS = 60 * 60 * 1000;
+const wait = (ms) => new Promise((done) => setTimeout(done, ms));
+/**
+ * Let's Encrypt, through acme-client, by DNS-01 only: a wildcard cannot be
+ * proved any other way, and the zone is the one thing nixamp.com does hold.
+ */
+export class AcmeIssuer {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async issue(names, challenge) {
+        const [first, ...rest] = names;
+        if (!first)
+            throw new Error("nothing to issue a certificate for");
+        const propagationMs = this.options.propagationMs ?? DEFAULT_PROPAGATION_MS;
+        const sleep = this.options.sleep ?? wait;
+        const client = new acme.Client({
+            directoryUrl: this.options.directoryUrl,
+            accountKey: await this.options.accountKey(),
+        });
+        // A fresh key per certificate. Reusing the account key for the
+        // certificate would make one leak two.
+        const [key, csr] = await acme.crypto.createCsr({ commonName: first, altNames: [first, ...rest] });
+        const cert = await client.auto({
+            csr,
+            email: this.options.email,
+            termsOfServiceAgreed: true,
+            challengePriority: ["dns-01"],
+            // acme-client would otherwise resolve the TXT itself before telling the
+            // CA to, and from wherever nixamp.com runs that lookup can lag the CA's.
+            skipChallengeVerification: true,
+            challengeCreateFn: async (authz, _challenge, keyAuthorization) => {
+                await challenge.set(`_acme-challenge.${authz.identifier.value}`, keyAuthorization);
+                await sleep(propagationMs);
+            },
+            challengeRemoveFn: async (authz, _challenge, keyAuthorization) => {
+                await challenge.clear(`_acme-challenge.${authz.identifier.value}`, keyAuthorization);
+            },
+        });
+        const info = acme.crypto.readCertificateInfo(cert);
+        return { cert, key: key.toString(), expiresAt: info.notAfter.getTime() };
+    }
+}
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS certs (
+    handle      TEXT PRIMARY KEY,
+    cert        TEXT NOT NULL,
+    key         TEXT NOT NULL,
+    expires_at  TIMESTAMPTZ NOT NULL,
+    issued_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+  );
+  CREATE TABLE IF NOT EXISTS acme_account (
+    id       INTEGER PRIMARY KEY,
+    key_pem  TEXT NOT NULL
+  );
+`;
+/**
+ * The certificates, one per handle, and the work of getting them.
+ *
+ * The rows are the truth and survive a restart; what is in flight lives in
+ * memory, because nixamp.com is one process and an order interrupted by a
+ * deploy is simply started again when next asked for.
+ */
+export class Certs {
+    db;
+    zone;
+    issuer;
+    ready = null;
+    work = new Map();
+    renewBeforeMs;
+    retryAfterMs;
+    now;
+    log;
+    constructor(db, zone, issuer, options = {}) {
+        this.db = db;
+        this.zone = zone;
+        this.issuer = issuer;
+        this.renewBeforeMs = options.renewBeforeMs ?? RENEW_BEFORE_MS;
+        this.retryAfterMs = options.retryAfterMs ?? RETRY_AFTER_MS;
+        this.now = options.now ?? Date.now;
+        this.log = options.log ?? (() => undefined);
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    /**
+     * The ACME account key, made once and kept. Losing it would not lose any
+     * certificate, but every renewal would register a new account, and Let's
+     * Encrypt rate-limits those too.
+     */
+    async accountKey() {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT key_pem FROM acme_account WHERE id = 1");
+        const kept = rows[0]?.["key_pem"];
+        if (typeof kept === "string" && kept !== "")
+            return kept;
+        const made = (await acme.crypto.createPrivateKey()).toString();
+        await this.db.query("INSERT INTO acme_account (id, key_pem) VALUES (1, $1) ON CONFLICT (id) DO NOTHING", [made]);
+        // Somebody else may have won the race to insert; theirs is the account now.
+        const again = await this.db.query("SELECT key_pem FROM acme_account WHERE id = 1");
+        const winner = again.rows[0]?.["key_pem"];
+        return typeof winner === "string" && winner !== "" ? winner : made;
+    }
+    /** The names one handle's certificate covers: every server it has, and the handle itself. */
+    namesFor(handle) {
+        return [`*.${handle}.${this.zone.zone}`, `${handle}.${this.zone.zone}`];
+    }
+    async stored(handle) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT cert, key, expires_at FROM certs WHERE handle = $1", [handle]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        const cert = row["cert"];
+        const key = row["key"];
+        const expires = row["expires_at"];
+        if (typeof cert !== "string" || typeof key !== "string")
+            return null;
+        const expiresAt = expires instanceof Date ? expires.getTime() : new Date(String(expires)).getTime();
+        if (!Number.isFinite(expiresAt))
+            return null;
+        return { cert, key, expiresAt };
+    }
+    /**
+     * A handle's certificate, or what is being done about the lack of one.
+     *
+     * Never blocks on the CA. With nothing stored, or something failed long
+     * enough ago to be worth another go, an order starts in the background and
+     * the answer is "issuing". With one stored that is near its end, the answer
+     * is still the old one -- it is valid -- and a renewal starts alongside.
+     */
+    async forHandle(handle) {
+        const kept = await this.stored(handle);
+        const inFlight = this.work.get(handle);
+        if (kept && kept.expiresAt > this.now()) {
+            const renewing = kept.expiresAt - this.now() < this.renewBeforeMs;
+            if (renewing && !(inFlight?.kind === "issuing"))
+                this.begin(handle, "renewal");
+            return {
+                status: "ready",
+                cert: kept.cert,
+                key: kept.key,
+                expiresAt: kept.expiresAt,
+                renewing: renewing || inFlight?.kind === "issuing",
+            };
+        }
+        if (inFlight?.kind === "issuing")
+            return { status: "issuing", since: inFlight.since };
+        if (inFlight?.kind === "failed" && this.now() - inFlight.at < this.retryAfterMs) {
+            return { status: "failed", error: inFlight.error, at: inFlight.at };
+        }
+        const started = this.begin(handle, kept ? "replacement of an expired certificate" : "first certificate");
+        return { status: "issuing", since: started.since };
+    }
+    /** Order in the background, and remember how it went. */
+    begin(handle, why) {
+        const since = this.now();
+        const names = this.namesFor(handle);
+        this.log(`  Ordering a certificate for ${names.join(" and ")} (${why}).`);
+        const done = this.issuer
+            .issue(names, {
+            set: (host, value) => this.zone.add(host, "TXT", value, 600),
+            clear: (host, value) => this.zone.remove(host, "TXT", value),
+        })
+            .then(async (issued) => {
+            await this.ensure();
+            await this.db.query(`INSERT INTO certs (handle, cert, key, expires_at, issued_at) VALUES ($1, $2, $3, $4, now())
+           ON CONFLICT (handle) DO UPDATE SET cert = EXCLUDED.cert, key = EXCLUDED.key,
+             expires_at = EXCLUDED.expires_at, issued_at = now()`, [handle, issued.cert, issued.key, new Date(issued.expiresAt).toISOString()]);
+            const days = Math.max(0, Math.round((issued.expiresAt - this.now()) / (24 * 60 * 60 * 1000)));
+            this.log(`  Certificate for *.${handle}.${this.zone.zone} issued, good for ${days} days.`);
+            this.work.delete(handle);
+        })
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            this.log(`  Certificate for *.${handle}.${this.zone.zone} failed: ${message}`);
+            this.work.set(handle, { kind: "failed", error: message, at: this.now() });
+        });
+        const work = { kind: "issuing", since, done };
+        this.work.set(handle, work);
+        return work;
+    }
+    /** For tests and shutdown: whatever order is in flight for a handle. */
+    async settle(handle) {
+        const inFlight = this.work.get(handle);
+        if (inFlight?.kind === "issuing")
+            await inFlight.done;
+    }
+}

package/dist/channels.d.ts

@@ -40,6 +40,8 @@ export declare const GIVE_UP = 5;
  * channel that is quiet for half a minute is not being quiet, it is dead.
  */
 export declare const STALL = 30000;
+/** How long an on-demand channel stays up with nobody watching. */
+export declare const IDLE = 60000;
 /**
  * How much of the recent stream a newcomer is handed. About six seconds of
  * 720p television, and a couple of seconds of 192k MP3: enough to play
@@ -53,6 +55,8 @@ export interface ChannelOptions {
     ffmpeg: string[];
     onStart?: (info: ChannelInfo) => void;
     onEnd?: (info: ChannelInfo) => void;
+    /** How long an on-demand channel outlives its last viewer. Tests shorten it. */
+    idleMs?: number;
 }
 /**
  * One live source, and its audience.
@@ -90,6 +94,13 @@ export declare class Channel {
      */
     private recent;
     private recentBytes;
+    /**
+     * Started for whoever asked and stopped when nobody is left. A catalog
+     * channel is one of thousands; keeping every one that was ever clicked
+     * running would be a decoder per click, for ever.
+     */
+    ephemeral: boolean;
+    private idle;
     constructor(info: ChannelInfo, options: ChannelOptions, onGone: (id: string) => void);
     start(format: string): void;
     /**
@@ -162,6 +173,8 @@ export declare class Channel {
     /** Write to everyone, and drop anybody whose socket has gone. */
     private send;
     listen(listener: Listener): () => void;
+    /** Nobody is watching an on-demand channel: give it a minute, then stop. */
+    private idleOut;
     close(): void;
 }
 /**
@@ -203,6 +216,10 @@ export declare class Channels {
     restart(id: string): boolean;
     /** Whether a channel is one we fetch ourselves, and so can start over. */
     pulled(id: string): boolean;
+    /** Mark a channel as on demand: it stops itself a minute after its last viewer leaves. */
+    ephemeral(id: string): void;
+    /** How many on-demand channels are up, for a ceiling on decoders. */
+    get ephemeralCount(): number;
     /** What a listener should be told this channel is. */
     contentType(id: string): string;
     /** Attach a listener, or null when nothing is playing on that channel. */

package/dist/channels.js

@@ -31,6 +31,8 @@ export const GIVE_UP = 5;
  * channel that is quiet for half a minute is not being quiet, it is dead.
  */
 export const STALL = 30_000;
+/** How long an on-demand channel stays up with nobody watching. */
+export const IDLE = 60_000;
 /** How much of what ffmpeg said to keep, for the last line when it dies. */
 const TAIL = 2000;
 /**
@@ -111,6 +113,13 @@ export class Channel {
      */
     recent = [];
     recentBytes = 0;
+    /**
+     * Started for whoever asked and stopped when nobody is left. A catalog
+     * channel is one of thousands; keeping every one that was ever clicked
+     * running would be a decoder per click, for ever.
+     */
+    ephemeral = false;
+    idle = null;
     constructor(info, options, onGone) {
         this.info = info;
         this.options = options;
@@ -418,11 +427,27 @@ export class Channel {
         }
         this.listeners.add(listener);
         this.info.listeners = this.listeners.size;
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = null;
         return () => {
             this.listeners.delete(listener);
             this.info.listeners = this.listeners.size;
+            if (this.ephemeral && this.listeners.size === 0)
+                this.idleOut();
         };
     }
+    /** Nobody is watching an on-demand channel: give it a minute, then stop. */
+    idleOut() {
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = setTimeout(() => {
+            this.idle = null;
+            if (this.ephemeral && this.listeners.size === 0)
+                this.close();
+        }, this.options.idleMs ?? IDLE);
+        this.idle.unref?.();
+    }
     close() {
         if (this.closing)
             return;
@@ -434,6 +459,9 @@ export class Channel {
         if (this.watchdog)
             clearTimeout(this.watchdog);
         this.watchdog = null;
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = null;
         const said = lastLine(this.stderr);
         if (said && !this.info.error)
             this.info.error = said;
@@ -551,6 +579,23 @@ export class Channels {
     pulled(id) {
         return this.open.get(id)?.info.via === "pull";
     }
+    /** Mark a channel as on demand: it stops itself a minute after its last viewer leaves. */
+    ephemeral(id) {
+        const channel = this.open.get(id);
+        if (!channel)
+            return;
+        channel.ephemeral = true;
+        if (channel.listeners.size === 0)
+            channel.listen({ write: () => true, end: () => undefined })();
+    }
+    /** How many on-demand channels are up, for a ceiling on decoders. */
+    get ephemeralCount() {
+        let total = 0;
+        for (const channel of this.open.values())
+            if (channel.ephemeral)
+                total += 1;
+        return total;
+    }
     /** What a listener should be told this channel is. */
     contentType(id) {
         return this.open.get(id)?.info.kind === "video" ? "video/mp4" : "audio/mpeg";

package/dist/directory.d.ts

@@ -51,6 +51,14 @@ export interface Listing {
      * an older nixamp that only knows about `url`.
      */
     audio: string;
+    /**
+     * The link that administers the server, as the publisher announced it.
+     *
+     * Kept so the owner can open their own machine as its administrator from
+     * the directory, and handed out to nobody else: the listing route strips it
+     * for anyone but the account that owns the listing.
+     */
+    admin: string;
     tracks: number;
     nowPlaying: string;
     /**
@@ -96,6 +104,8 @@ export interface Announcement {
     url: string;
     /** Where the audio actually is. See `Listing.audio`. */
     audio?: string;
+    /** The admin share link, same origin as `url`. Kept for the owner alone. */
+    admin?: string;
     tracks: number;
     nowPlaying: string;
     /** Absent from an older publisher, which is read as "unknown, say playing". */

package/dist/directory.js

@@ -68,6 +68,10 @@ export function parseAnnouncement(input) {
     const offered = typeof record["audio"] === "string" ? record["audio"] : "";
     const parsed = offered ? publishable(offered) : null;
     const audio = parsed !== null && parsed.origin === listen.origin ? offered : "";
+    // The admin link is held to the same rule: it names this server or nothing.
+    const adminOffered = typeof record["admin"] === "string" ? record["admin"] : "";
+    const adminParsed = adminOffered ? publishable(adminOffered) : null;
+    const admin = adminParsed !== null && adminParsed.origin === listen.origin ? adminOffered : "";
     const name = clean(record["name"], MAX_NAME);
     const tracks = Number(record["tracks"]);
     return {
@@ -75,6 +79,7 @@ export function parseAnnouncement(input) {
         name: name || "a nixamp",
         url,
         ...(audio ? { audio } : {}),
+        ...(admin ? { admin } : {}),
         tracks: Number.isFinite(tracks) && tracks >= 0 ? Math.min(1_000_000, Math.floor(tracks)) : 0,
         nowPlaying: clean(record["nowPlaying"], MAX_TRACK),
         ...(typeof record["playing"] === "boolean" ? { playing: record["playing"] } : {}),
@@ -167,6 +172,7 @@ export class Directory {
             // older publisher renewing an entry should not blank the address the
             // phone line is playing from.
             audio: announcement.audio ?? existing?.audio ?? "",
+            admin: announcement.admin ?? existing?.admin ?? "",
             tracks: announcement.tracks,
             nowPlaying: announcement.nowPlaying,
             // An older publisher says nothing about either; "playing" keeps what a

package/dist/dns.d.ts

@@ -0,0 +1,63 @@
+export type RecordType = "A" | "AAAA" | "TXT";
+export interface DnsRecord {
+    id: string;
+    /** The full hostname, e.g. "server2.chovy.nixamp.com". */
+    host: string;
+    type: RecordType;
+    content: string;
+    ttl: number;
+}
+export interface DnsZone {
+    /** The apex this zone answers for: "nixamp.com". */
+    readonly zone: string;
+    list(host: string, type: RecordType): Promise<DnsRecord[]>;
+    /** Afterwards exactly one record of that host and type exists, with this content. */
+    set(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    /** One more. An ACME order for a wildcard and its apex wants two TXT at once. */
+    add(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    /** All of host and type, or only those whose content matches. */
+    remove(host: string, type: RecordType, content?: string): Promise<void>;
+}
+/** 2026, not 1998: an address is either family, and both are first class. */
+export declare function isIPv4(value: unknown): boolean;
+export declare function isIPv6(value: unknown): boolean;
+/** Porkbun's floor. Anything lower is silently raised, so it is raised here, loudly. */
+export declare const MIN_TTL = 600;
+/**
+ * A zone kept in memory. For tests, and for a nixamp started without registrar
+ * keys, where a name can be handed out and simply will not resolve -- which the
+ * operator is told about elsewhere, rather than crashing here.
+ */
+export declare class MemoryZone implements DnsZone {
+    readonly zone: string;
+    readonly records: DnsRecord[];
+    private sequence;
+    constructor(zone: string);
+    list(host: string, type: RecordType): Promise<DnsRecord[]>;
+    set(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    add(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    remove(host: string, type: RecordType, content?: string): Promise<void>;
+}
+/**
+ * Porkbun's v3 DNS API.
+ *
+ * Every call is a POST carrying both halves of the key in the body -- the
+ * field is `secretapikey`, which the API itself names as the usual mistake --
+ * and the subdomain is the host with the zone taken off: "server2.chovy" for
+ * "server2.chovy.nixamp.com", and nothing at all for the apex.
+ */
+export declare class Porkbun implements DnsZone {
+    readonly zone: string;
+    private readonly apiKey;
+    private readonly secretApiKey;
+    private readonly send;
+    private readonly base;
+    constructor(zone: string, apiKey: string, secretApiKey: string, send?: typeof fetch, base?: string);
+    /** The part before the zone, or "" for the zone itself. */
+    private sub;
+    private call;
+    list(host: string, type: RecordType): Promise<DnsRecord[]>;
+    add(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    set(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    remove(host: string, type: RecordType, content?: string): Promise<void>;
+}