funoteka 0.1.0

package/dist/api/cover.js

@@ -0,0 +1,304 @@
+import { createReadStream, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pickCover } from "../cover/pick.js";
+import { pictureInRegion } from "../cover/picture.js";
+import { parseId, required } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+import { album, albumPlacesOfArtist, artist, artistOwnFolders, embeddedCoverInFolder, fileFoldersOfAlbums, folder, picturesInFolder, root, song, } from "./meta.js";
+/**
+ * The cover a client shows beside a record.
+ *
+ * The protocol asks for one image by the id of whatever is on screen — an
+ * album, an artist, a song, a folder — so the id is a way of *asking*, not a
+ * statement about where the picture is. What this file does is turn each kind
+ * of id into the folders worth looking in, in the order worth looking, and hand
+ * the first picture found to the client.
+ *
+ * Only the folder's own pictures are considered. Descending into a subfolder
+ * looks tempting — the scans of a box often sit in a `Full scans` or `Artwork`
+ * directory — but those directories are where the *back*, the disc and the
+ * booklet live, and a rule that reached into one would as often answer with the
+ * back of the record as with its front. A folder that keeps its cover nowhere
+ * answers "no cover", and the client draws its own placeholder.
+ *
+ * Nothing is scaled. The protocol allows a `size`, and this server answers with
+ * the collection's own file whatever size was asked for: nothing in the runtime
+ * can decode an image, and the file the operator scanned is a truer answer than
+ * a resize made by guessing. A client that wants a thumbnail makes one.
+ */
+/** What an image file is, so the client knows what it is about to receive. */
+const IMAGE_TYPES = {
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    gif: 'image/gif',
+    bmp: 'image/bmp',
+    webp: 'image/webp',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+};
+export function imageContentType(ext) {
+    return IMAGE_TYPES[ext] ?? 'application/octet-stream';
+}
+/**
+ * The folders an id asks about, best first.
+ *
+ * Several, because the meta layer's answer is not always one folder: a song on
+ * no album still has the folder it sits in, and an album whose row names a file
+ * rather than a directory — what a loose download becomes — keeps its pictures
+ * in the folder that file is in. An artist is the one case where the list is
+ * genuinely long: it has no art of its own, so every one of its records offers
+ * what it has.
+ *
+ * The order is the caller's own and is kept, but it is not what decides first:
+ * these folders are a *set* to be ranked once, so the record that happens to
+ * come first does not answer for the artist — a record whose picture is named
+ * `front` does, wherever in the list it sits. The order decides only the case
+ * no name decides, and `foldersOfAlbums` preserves it for exactly that; a
+ * comment here once said the caller must not read the list as ordered at all,
+ * which the ranking below contradicts.
+ */
+function candidateFolders(db, id) {
+    const parsed = parseId(id);
+    if (parsed === undefined)
+        return [];
+    switch (parsed.kind) {
+        case 'al': {
+            const row = album(db, parsed.n);
+            return row === undefined ? [] : foldersOfAlbums(db, [row]);
+        }
+        case 'tr': {
+            const row = song(db, parsed.n);
+            if (row === undefined)
+                return [];
+            const own = { rootId: row.root_id, relPath: row.folder_rel_path };
+            if (row.album_id === null)
+                return [own];
+            const record = album(db, row.album_id);
+            return record === undefined
+                ? [own]
+                : distinct([{ rootId: record.root_id, relPath: record.rel_path }, own]);
+        }
+        case 'ar': {
+            const row = artist(db, parsed.n);
+            if (row === undefined)
+                return [];
+            // Through the same expansion an album gets, and for the same reason: a
+            // record whose row names a *file* — a flat rip, a `.ape` beside its cue —
+            // keeps its pictures in the folder that file is in, and an artist asking
+            // for art is asking about its records either way.
+            //
+            // Asked for the artist's records *together*, because the answer is a set:
+            // the folders of thirty records are one join, where asking each record on
+            // its own read that record's whole song list to learn the same thing. And
+            // asked for their *places* rather than for the records, because a cover is
+            // not about what a record holds — the genre and the running time this
+            // route never reads are built for every album in the collection before the
+            // artist's are picked out.
+            return foldersOfAlbums(db, albumPlacesOfArtist(db, row.id));
+        }
+        case 'fd': {
+            const row = folder(db, parsed.n);
+            return row === undefined ? [] : [{ rootId: row.root_id, relPath: row.rel_path }];
+        }
+        case 'ro': {
+            const row = root(db, parsed.n);
+            // A root is a folder like any other — `''` is the row that stands for it
+            // (`db/migrations/001_init.sql`) — so the pictures an operator dropped in
+            // their download folder are reachable the same way a record's are.
+            return row === undefined ? [] : [{ rootId: row.id, relPath: '' }];
+        }
+    }
+}
+/**
+ * The folders several records' pictures could be in, best first.
+ *
+ * The album's row is its folder by the identity rule, and the songs are where
+ * that stops being true: a flat rip whose every file became its own album names
+ * the file, not a directory (`.ape` beside its cue is the shape this collection
+ * has). Both are offered per record, the row's own first, so that a record keyed
+ * on a file still finds the folder the file sits in.
+ *
+ * The records are taken as many at once rather than one at a time, and the
+ * caller's own order is what the result is in — a record's row, then its files,
+ * then the next record's. That order is the tie-break when no picture's name
+ * says which side it is, so it is preserved rather than sorted.
+ */
+function foldersOfAlbums(db, records) {
+    const files = fileFoldersOfAlbums(db, records.map((row) => row.id));
+    return distinct(records.flatMap((row) => [
+        { rootId: row.root_id, relPath: row.rel_path },
+        ...(files.get(row.id) ?? []),
+    ]));
+}
+function distinct(folders) {
+    const seen = new Set();
+    return folders.filter(({ rootId, relPath }) => {
+        const key = `${rootId}\u0000${relPath}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** A picture sitting on disk, as the cover to serve. */
+function fileCover(picture) {
+    return { kind: 'file', rootPath: picture.root_path, relPath: picture.rel_path, ext: picture.ext };
+}
+/**
+ * The picture a single folder holds, or nothing when it holds none.
+ *
+ * One folder's own pictures ranked on their own — the reader `resolve` uses for
+ * its first question, which asks a folder named for the artist before it asks
+ * anything of the artist's records.
+ */
+function coverInFolder(db, { rootId, relPath }) {
+    const chosen = pickCover(picturesInFolder(db, rootId, relPath));
+    return chosen === undefined ? undefined : fileCover(chosen);
+}
+function resolve(db, id) {
+    // An artist's own folder answers for the artist, and only for the artist.
+    //
+    // It is asked apart from the ranking below rather than put at the front of
+    // its list, because "first among equals" would not decide anything: a folder
+    // named for the artist holds a `folder.jpg`, a record's folder holds a
+    // `front.jpg`, and `front` outranks `folder` — so an album cover would still
+    // have won the tie it was never party to. A picture of the artist is a fact
+    // about the artist, and where the collection states one it is the answer.
+    const asked = parseId(id);
+    if (asked !== undefined && asked.kind === 'ar') {
+        for (const where of artistOwnFolders(db, asked.n)) {
+            const own = coverInFolder(db, where);
+            if (own !== undefined)
+                return { picture: own, folders: [where] };
+        }
+    }
+    const folders = candidateFolders(db, id);
+    // Every folder's pictures as one set, ranked once — not "the first folder
+    // holding anything answers".
+    //
+    // A box keeps its front cover inside each disc and its paperwork in the box
+    // folder, and the folder that answers first is the box's: `Кинохроники` has an
+    // `info.png` at the top and `front.jpg` one level down, so the sheet about the
+    // release was served as its cover. Ranking across the folders lets a name that
+    // says `front` win wherever it is, and the folder order still decides when no
+    // name says anything — `pickCover` falls back to the first picture it was
+    // given, and the record's own folder is first in the list.
+    const pictures = folders.flatMap(({ rootId, relPath }) => picturesInFolder(db, rootId, relPath));
+    const chosen = pickCover(pictures);
+    if (chosen !== undefined) {
+        return { picture: fileCover(chosen), folders };
+    }
+    for (const { rootId, relPath } of folders) {
+        const embedded = embeddedCoverInFolder(db, rootId, relPath);
+        if (embedded === undefined)
+            continue;
+        // Two kinds of place, and the row says which. A picture the file carries as
+        // its own bytes is a range a client can be sent; one it carries base64'd
+        // inside a comment is a range that has to be read and parsed first — see
+        // `src/cover/picture.ts`.
+        const picture = embedded.kind === 'indirect'
+            ? {
+                kind: 'indirect',
+                rootPath: embedded.root_path,
+                relPath: embedded.rel_path,
+                container: embedded.container,
+                offset: embedded.offset,
+                length: embedded.length,
+            }
+            : {
+                kind: 'embedded',
+                rootPath: embedded.root_path,
+                relPath: embedded.rel_path,
+                mime: embedded.mime,
+                offset: embedded.offset,
+                length: embedded.length,
+            };
+        return { picture, folders };
+    }
+    return { picture: undefined, folders };
+}
+/**
+ * The route.
+ *
+ * Bytes, not an envelope, so it is a `BinaryRoute` like `stream` — but with one
+ * difference that matters: it knows the whole answer before the first header is
+ * written. An image is a file, and a file's size is known. So a refusal is
+ * always still a refusal the client can read, and the response is never a
+ * connection that ends without saying why.
+ */
+export async function coverArt(context, request, response) {
+    const id = required(context.query, 'id');
+    const { picture, folders } = resolve(context.db, id);
+    if (picture === undefined) {
+        // The folder is named when one was looked in, because "this record has no
+        // cover" and "there is no such record" are different things to go and fix,
+        // and the message is the only place a caller learns which happened. The
+        // folders come from the lookup that just failed rather than a second walk of
+        // the same ground.
+        const where = folders.map((f) => f.relPath || '/');
+        throw new ApiError(ERROR.notFound, where.length === 0
+            ? `No such id: ${id}`
+            : `No cover art for ${id}: ${where.join(', ')} holds no picture`);
+    }
+    const path = join(picture.rootPath, picture.relPath);
+    // The kind of place that is not a range. Its bytes have to be derived before
+    // anything can be promised about them — including whether there are any — so
+    // this is the one branch that is not a `readStream` over a slice.
+    if (picture.kind === 'indirect') {
+        const derived = pictureInRegion(path, picture.container, picture.offset, picture.length);
+        if (derived === null) {
+            // The row said a picture was there and it could not be derived: the file
+            // has changed since the scan, or its comment is damaged. Saying so is the
+            // same answer as having none, because that is what the client gets — but
+            // the message names the file, which is where to go and look.
+            throw new ApiError(ERROR.notFound, `No cover art for ${id}: the picture inside ${picture.relPath} could not be read`);
+        }
+        response.writeHead(200, {
+            'content-type': derived.mime,
+            'content-length': derived.data.length,
+        });
+        if (request.method === 'HEAD' || derived.data.length === 0) {
+            response.end();
+            return;
+        }
+        // Already in memory, so it goes out as it is: a stream over a buffer is a
+        // second copy of a picture that was just decoded into the first.
+        response.end(derived.data);
+        return;
+    }
+    // Where in that file the bytes are: the whole of it for a picture sitting
+    // beside the record, and a named range of it for one the record carries.
+    const [from, to, mime] = picture.kind === 'file'
+        ? [0, statSync(path).size - 1, imageContentType(picture.ext)]
+        : [picture.offset, picture.offset + picture.length - 1, picture.mime];
+    const length = to - from + 1;
+    response.writeHead(200, { 'content-type': mime, 'content-length': length });
+    // A HEAD asks what a GET would bring. Reading the file to throw the bytes
+    // away is the one thing the method exists to avoid.
+    if (request.method === 'HEAD' || length <= 0) {
+        response.end();
+        return;
+    }
+    await pipeRange(path, from, to, response);
+}
+/**
+ * The picture, as a stream that ends with the response.
+ *
+ * Bounded by the last byte the header already promised, and that bound is not
+ * decoration: `createReadStream(path)` alone reads until the file says it is
+ * over, so a picture replaced between the `statSync` above and this read would
+ * put more bytes on the wire than `Content-Length` declared and leave the
+ * connection out of step for whatever the client sent next. Measured on this
+ * repository: with the unbounded form the connection stayed open for three
+ * seconds after the last byte, which is how the difference was noticed at all —
+ * it looked exactly like a slow server.
+ */
+function pipeRange(path, from, to, response) {
+    return new Promise((resolve, reject) => {
+        const file = createReadStream(path, { start: from, end: to });
+        file.on('error', reject);
+        response.on('close', () => file.destroy());
+        file.pipe(response).on('finish', resolve).on('error', reject);
+    });
+}

package/dist/api/download.js

@@ -0,0 +1,112 @@
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { stretchOf } from "../stream/segment.js";
+import { contentType, trackId } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+import { song } from "./meta.js";
+import { serveBytes, serveSegment } from "./stream.js";
+/**
+ * The file itself, for a client that means to keep it.
+ *
+ * `stream`'s plainer sibling, and the difference is the whole of what this
+ * method is for: `stream` answers with something a client can *play* — a cue
+ * track cut out of an image, a re-encode of a format the client cannot read —
+ * and `download` answers with the original media data, "without transcoding or
+ * downsampling", which is what a client needs to put a record on a phone for a
+ * train. So there is one path here and no plan: the file the row names, sent as
+ * it is.
+ *
+ * **A song cut from a cue image is sent as its own frames, not as the image.**
+ * The first version of this handed back the whole file, on the reasoning that
+ * anything else would be "cutting" what the method promises to deliver whole —
+ * and that reasoning was wrong, in the way that matters: the saved file played
+ * from the top of the disc, so a client that asked for track nine got the wrong
+ * song in 510 MB, for 1 789 of this collection's 4 969 tracks (task:2864).
+ *
+ * Copying a frame range is not a transcode. Nothing is decoded, nothing is
+ * resampled, and `stream/segment.ts` calls that path lossless for the same
+ * reason `stream` uses it. What this method refuses is ffmpeg — so for the few
+ * images whose frames cannot be restated (ape, MP4) the segment is refused with
+ * a reason rather than served as something else, and the sender is told to ask
+ * `stream` or to take the image deliberately.
+ *
+ * The bytes and the ranging are `stream.ts`'s — `serveBytes` and `serveSegment`
+ * are the same functions the stream route uses, so seeking a download works for
+ * the same reason seeking a stream does and cannot drift away from it.
+ */
+export async function download(context, request, response) {
+    const id = trackId(context.query);
+    const row = song(context.db, id);
+    if (row === undefined)
+        throw new ApiError(ERROR.notFound, `No such song: ${id}`);
+    // The path is the meta layer's own, never the client's — the rule `stream.ts`
+    // states, and the reason neither of these can be talked into reading a file
+    // the scan never saw.
+    const path = join(row.root_path, row.rel_path);
+    // Asked here rather than left to `serveBytes`, which would find it out by
+    // throwing from `statSync`. The difference is the header below: a refusal is
+    // rendered into the same response, and an `attachment` beside "Internal
+    // error" is a client saving a refusal under a track's name.
+    if (!existsSync(path)) {
+        throw new ApiError(ERROR.notFound, `No such file on disk: ${row.rel_path}`);
+    }
+    // Set before `serveBytes` writes the head, which keeps what was set here:
+    // this is the method a client saves with, and a name is what makes a saved
+    // file recognisable.
+    // A whole file is saved under its own name; a stretch of one is saved under
+    // the song's, because that is what it is — `Tool - Undertow.flac` is a file
+    // somebody can find again, and `Tool - Undertow [61422-33010-2].flac` is a
+    // 510 MB disc they did not ask for.
+    response.setHeader('content-disposition', attachmentOf(row.segment_start_ms === null
+        ? basename(path)
+        : `${row.title ?? basename(path)}.${row.ext}`));
+    if (row.segment_start_ms !== null) {
+        // A song cut from an image is a stretch of it, and the stretch is what this
+        // method is asked for. `serveSegment` copies the frames — nothing is decoded
+        // and nothing is resampled, so it is the original data and not a transcode
+        // — and the one branch it is not allowed here is ffmpeg's, which would make
+        // the answer a different file from the one on disk.
+        // The stretch is the song's own, and there is no offset here to move it:
+        // download has no `timeOffset`, and the file a client asked to keep is the
+        // track, not a later part of it.
+        const stretch = stretchOf(row, null);
+        if (stretch.kind !== 'span') {
+            throw new ApiError(ERROR.generic, stretch.kind === 'refused' ? stretch.reason : 'This song is not a stretch of its file');
+        }
+        await serveSegment(context, row, path, request, response, {
+            times: stretch,
+            as: 'download',
+        });
+        return;
+    }
+    await serveBytes(path, contentType(row.ext), request, response);
+}
+/**
+ * A `Content-Disposition` a header can actually carry.
+ *
+ * **Two filenames, and the second is not decoration.** A header value is
+ * latin-1, and this collection's names are not: a folder called `Кино` would
+ * make `setHeader` throw and take the whole request down with it. So the plain
+ * `filename` is the name with everything outside ASCII replaced, and
+ * `filename*` carries the real one percent-encoded, which is what RFC 5987
+ * added and what every client that matters reads. A client that understands
+ * only the first gets a file it can still recognise; one that reads the second
+ * gets the name the file has.
+ */
+function attachmentOf(name) {
+    const safe = name.replace(/[^\x20-\x7e]/gu, '_').replace(/["\\]/gu, '_');
+    return `attachment; filename="${safe}"; filename*=UTF-8''${extValue(name)}`;
+}
+/**
+ * A string as RFC 5987's `ext-value`, which `encodeURIComponent` is not.
+ *
+ * The standard's `attr-char` leaves out `'`, `(`, `)`, `*` and `!` — and
+ * `encodeURIComponent` escapes none of the first four. `'` is the one that
+ * bites: it is the quote around the charset in `UTF-8''`, so a name like
+ * `Guns N' Roses (Live).flac` emitted an encoding whose own separator appears
+ * inside it, and a strict client drops the whole parameter and falls back to
+ * the ASCII stand-in.
+ */
+function extValue(name) {
+    return encodeURIComponent(name).replace(/['()*]/gu, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}

package/dist/api/envelope.js

@@ -0,0 +1,162 @@
+/**
+ * The Subsonic response envelope, and the two ways it is rendered.
+ *
+ * Every answer the API gives — a method's payload or an error — travels inside
+ * one `subsonic-response` object, and the client decides whether the call
+ * worked by reading `status` out of that object rather than by reading the HTTP
+ * status line. So the envelope is the one shape every route agrees on, and the
+ * one place a route can be wrong about the protocol while being right about its
+ * own data. It gets a module of its own for that reason.
+ *
+ * Rendering is generic, and deliberately so. In the protocol's XML a field is
+ * an attribute when it holds a value and a child element when it holds a record,
+ * which makes the two formats one answer seen twice — so a route hands over a
+ * plain object and neither chooses a format nor knows one is being chosen.
+ */
+/** The protocol version this server speaks. Clients refuse a server they outrank. */
+export const API_VERSION = '1.16.1';
+/**
+ * What this server is called, and which of its own versions this is.
+ *
+ * **Both are required of every answer, and neither is about the answer.**
+ * `type` is how a client adapts to what a server calling itself Subsonic
+ * actually supports; `serverVersion` is how it knows *to ask again which
+ * extensions exist* after a deployment — the spec is explicit that this is what
+ * the field is for. `version` above is the API version and answers a third
+ * question, so it stands in for neither.
+ *
+ * Pinned to `package.json` by a test rather than read from it at import: a
+ * constant that cannot drift silently is worth more here than a file read in a
+ * module every route depends on.
+ */
+export const SERVER_TYPE = 'funoteka';
+export const SERVER_VERSION = '0.1.0';
+/**
+ * The fields every answer carries, whatever the answer is.
+ *
+ * `openSubsonic` is the one that matters most and the least obvious: it is how
+ * a client learns that the extension list is worth asking for at all, and a
+ * server that answers `getOpenSubsonicExtensions` without it has called a
+ * client to a door the client cannot see.
+ */
+function identity() {
+    return { type: SERVER_TYPE, serverVersion: SERVER_VERSION, openSubsonic: true };
+}
+/** The one element every answer hangs from, in either format. */
+const ROOT = 'subsonic-response';
+const NAMESPACE = 'http://subsonic.org/restapi';
+/**
+ * The protocol's own error codes.
+ *
+ * Transcribed complete rather than trimmed to the ones routes use today: a code
+ * is a promise to the client about what went wrong, and the surest way to keep
+ * that promise is to pick from the standard's list instead of inventing a
+ * number that means something else to somebody's client.
+ */
+export const ERROR = {
+    generic: 0,
+    missingParameter: 10,
+    clientTooOld: 20,
+    serverTooOld: 30,
+    wrongCredentials: 40,
+    tokenAuthRefused: 41,
+    unsupportedAuthMechanism: 42,
+    conflictingAuthMechanisms: 43,
+    invalidApiKey: 44,
+    notAuthorized: 50,
+    trialOver: 60,
+    notFound: 70,
+};
+export function ok(payload = {}) {
+    return { status: 'ok', version: API_VERSION, ...identity(), ...payload };
+}
+export function failed(code, message) {
+    return { status: 'failed', version: API_VERSION, ...identity(), error: { code, message } };
+}
+/**
+ * A refusal a route decided on, on its way out.
+ *
+ * A route answers with the fields of a successful call, so the one thing it
+ * cannot do is answer with a failure — and a route is exactly where the reason
+ * for a failure is known: which parameter was missing, which id names nothing.
+ * Throwing carries the code and the message from where the reason is to the one
+ * place that renders envelopes.
+ */
+export class ApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ApiError';
+        this.code = code;
+    }
+}
+/** Anything but an explicit `f=json` is XML, which is what the protocol defaults to. */
+export function parseFormat(value) {
+    return value === 'json' ? 'json' : 'xml';
+}
+/**
+ * The envelope, rendered.
+ *
+ * Both formats wrap it in `subsonic-response` — that name is how a client finds
+ * the answer at all, in either — and only the XML carries a namespace, because
+ * a namespace is an XML device and the JSON form has nowhere to put one.
+ */
+export function render(envelope, format) {
+    return format === 'json'
+        ? {
+            contentType: 'application/json; charset=utf-8',
+            body: JSON.stringify({ [ROOT]: envelope }),
+        }
+        : { contentType: 'application/xml; charset=utf-8', body: toXml(envelope) };
+}
+function toXml(envelope) {
+    const fields = [['xmlns', NAMESPACE], ...Object.entries(envelope)];
+    return element(ROOT, fields);
+}
+function element(name, fields) {
+    const attributes = scalarFields(fields)
+        .map(([field, value]) => ` ${field}="${escape(String(value))}"`)
+        .join('');
+    const children = recordFields(fields)
+        .map(([field, value]) => 
+    // An array is the same field repeated. A record standing alone is one
+    // such field. A bare value in an array has no field to carry it, so the
+    // element holds the value itself — which is how a protocol that writes
+    // lyrics as element text is written.
+    asArray(value)
+        .map((item) => isRecord(item)
+        ? element(field, Object.entries(item))
+        : `<${field}>${escape(String(item))}</${field}>`)
+        .join(''))
+        .join('');
+    return children === ''
+        ? `<${name}${attributes}/>`
+        : `<${name}${attributes}>${children}</${name}>`;
+}
+/** The fields that hold a value, in the order they were given. Absent ones are dropped. */
+function scalarFields(fields) {
+    return fields.filter(([, value]) => !isRecord(value) && !Array.isArray(value) && value != null);
+}
+function recordFields(fields) {
+    return fields.filter(([, value]) => (isRecord(value) || Array.isArray(value)) && value != null);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * `&` first, or the ampersands an escape introduces would be escaped again.
+ *
+ * This is not decoration: the error message quotes the method name the client
+ * asked for, and that name comes off the wire. Unescaped, it would be a way to
+ * put arbitrary elements into a document the client parses as XML.
+ */
+function escape(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/dist/api/extensions.js

@@ -0,0 +1,43 @@
+/**
+ * The extensions this server implements, each with the endpoint that carries it.
+ *
+ * `transcoding` was deliberately absent until it was built, and the entry below
+ * is what that discipline looks like once it holds: the two endpoints exist, so
+ * the name does. A client that read the name before the code would call
+ * `getTranscodeDecision` and get "unknown method" from a server that had just
+ * told it the method existed — and nothing in the protocol lets it ask again or
+ * tell it whose fault that was.
+ */
+const EXTENSIONS = [
+    // getPlayQueueByIndex / savePlayQueueByIndex — the same queue, addressed by
+    // position rather than by id, because an id cannot say which of two identical
+    // entries is playing.
+    { name: 'indexBasedQueue', versions: [1] },
+    // reportPlayback — what a player says about a song it has just played, which
+    // is the history the server did not witness.
+    { name: 'playbackReport', versions: [1] },
+    // The `timeOffset` parameter on `stream` — `Transcode Offset`: start the
+    // answer later than the song does.
+    { name: 'transcodeOffset', versions: [1] },
+    // getTranscodeDecision / getTranscodeStream — a client states what it can play
+    // and is told what this server would do with a song, instead of naming a
+    // format and a ceiling and hoping. Over http only: the client's HLS profiles
+    // are skipped and answered with `canTranscode: false`, because this server
+    // produces no HLS (task:2896).
+    { name: 'transcoding', versions: [1] },
+    // `apiKey` as a whole credential, and the pair of promises the extension is:
+    // a key that arrives alone is accepted, and a server that accepts one offers
+    // a way to see the keys it holds and to take one back. The first half worked
+    // from the beginning and the second did not exist, which is why the name was
+    // withheld: the key lived in a variable in `start.cmd` and revoking it meant
+    // editing that file and restarting the daemon (task:2915).
+    //
+    // It is declared now because both halves are true — the registry and the two
+    // CLI verbs are `keys.ts` and `cli/keys.ts`. The environment's key is outside
+    // the registry on purpose and `list` says so; see the migration.
+    { name: 'apiKeyAuthentication', versions: [1] },
+];
+/** The answer to `getOpenSubsonicExtensions`, and the whole of it. */
+export function openSubsonicExtensions() {
+    return { openSubsonicExtensions: EXTENSIONS.map(({ name, versions }) => ({ name, versions })) };
+}