funoteka 0.1.0

package/dist/api/annotation.js

@@ -0,0 +1,193 @@
+import * as annotations from "../annotation/store.js";
+import { withTransaction } from "../db/index.js";
+import { albumChild, albumId3, artistId3, childOf, confinedTo, ID, parseId } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+import { album, albumsById, artist, artistIdsInRoot, artistsById, songsByIds, song, } from "./meta.js";
+/**
+ * What the listener marked, in the protocol's shapes.
+ *
+ * The second set of routes that write — playlists are the first — and the same
+ * kind of thing: a statement about the music that no file states and no scan can
+ * rebuild. What it is *about*, though, is the collection, so a mark goes with
+ * the row it is on and nothing here has to clean up after a deleted record.
+ *
+ * The two halves of the protocol live here together: the methods that set the
+ * marks, and the listings that show them. A client that stars a song and one
+ * that draws a star are looking at the same row of the same table.
+ */
+/**
+ * The protocol's three prefixes, and what each of them marks.
+ *
+ * `id` — the parameter `star`, `unstar` and `setRating` all take — names a
+ * *subject*, and the protocol's own words for it are "the file (song) or folder
+ * (album/artist)": which of the three it is comes from the id itself, not from
+ * the parameter. The two named parameters beside it (`albumId`, `artistId`)
+ * exist for clients that would rather say it outright.
+ */
+const MARKS = { tr: 'track', al: 'album', ar: 'artist' };
+/**
+ * The subject an id names, or nothing — and the *row's* id, not the one asked
+ * with.
+ *
+ * That second half is the point of going through the model here rather than
+ * taking the id apart and keeping it: `album` resolves a record through its
+ * group, so a client that holds a box's second disc id — which is what every
+ * client did while the discs were the albums — is answered about the record,
+ * and the mark has to land on the row the listings read. `browse.ts` makes the
+ * same distinction for the same reason ("the record's own id, not the one that
+ * was asked with").
+ */
+function subjectOf(db, raw) {
+    const parsed = parseId(raw);
+    const kind = parsed === undefined ? undefined : MARKS[parsed.kind];
+    if (parsed === undefined || kind === undefined)
+        return null;
+    const found = kind === 'track'
+        ? song(db, parsed.n)
+        : kind === 'album'
+            ? album(db, parsed.n)
+            : artist(db, parsed.n);
+    return found === undefined ? null : { kind, id: found.id };
+}
+/**
+ * Every subject the request names, checked before anything is written.
+ *
+ * The protocol spells a batch as the parameter repeated — `id` once per song —
+ * and a client starring an album's worth of songs sends exactly that. Each is
+ * resolved against the model first, and the whole batch is written in one
+ * transaction after: a call naming one song that is not here changes nothing
+ * rather than half of what it named, and a call naming forty does not pay forty
+ * commits — measured on the live database, forty stars written one at a time
+ * held this single-threaded server for **2967 ms**, against 21 ms for the same
+ * forty inside one transaction.
+ */
+function mark(db, query, setting) {
+    const named = new Map();
+    // **The three parameters are read as one, and that is a decision.** The
+    // protocol distinguishes them — `id` for "a song, album or artist", `albumId`
+    // and `artistId` for clients that browse by tags — and this server's ids
+    // already say which kind they are, so the parameter a client chose adds
+    // nothing to the question. It used to be *enforced*, though: `albumId` had to
+    // name an album, and a client that put a track id there was refused with "No
+    // such album" — and refused as a whole call, so the track it named in `id` was
+    // never starred and its heart never appeared.
+    //
+    // That is measured, not imagined: Castafiore sends `id`, `albumId` and
+    // `artistId` all set to the same value, and starring from it did nothing at
+    // all. One id, one entry, whichever parameter carried it.
+    for (const name of ['id', 'albumId', 'artistId']) {
+        for (const raw of query.getAll(name)) {
+            if (raw === '')
+                continue;
+            const subject = subjectOf(db, raw);
+            if (subject === null)
+                throw new ApiError(ERROR.notFound, `No such id: ${raw}`);
+            named.set(`${subject.kind}:${subject.id}`, [subject.kind, subject.id]);
+        }
+    }
+    // A call that named nothing is refused rather than answered `ok`: a client
+    // that lost its id on the way has not marked anything, and telling it that it
+    // did leaves it showing a star nobody set.
+    if (named.size === 0) {
+        throw new ApiError(ERROR.missingParameter, 'Required parameter is missing: id');
+    }
+    withTransaction(db, () => {
+        for (const [kind, id] of named.values()) {
+            if (setting)
+                annotations.star(db, kind, id);
+            else
+                annotations.unstar(db, kind, id);
+        }
+    });
+}
+export function star(db, query) {
+    mark(db, query, true);
+    return {};
+}
+export function unstar(db, query) {
+    mark(db, query, false);
+    return {};
+}
+/**
+ * A rating from one to five — and nought, which is the protocol's way of saying
+ * there is none.
+ *
+ * Refused outside that range rather than clamped: a client that asked for seven
+ * has a bug, and storing five would tell it the number it sent was taken. The
+ * parameter is required, so a call that names no rating is refused by name
+ * rather than treated as zero — "set this to nothing" and "I forgot to say" are
+ * different requests, and only one of them should clear a rating.
+ *
+ * The subject is whatever `id` names, the same three kinds `star` takes: the
+ * documentation of this method says "file (song) or folder (album/artist)", and
+ * a rating a client can set but never read back would be a control that does
+ * nothing.
+ */
+export function setRating(db, query) {
+    const raw = query.get('rating');
+    if (raw === null || raw === '') {
+        throw new ApiError(ERROR.missingParameter, 'Required parameter is missing: rating');
+    }
+    const rating = Number(raw);
+    if (!Number.isInteger(rating) || rating < 0 || rating > 5) {
+        throw new ApiError(ERROR.generic, `rating is not a number from 0 to 5: ${raw}`);
+    }
+    const subject = subjectOf(db, query.get('id') ?? '');
+    if (subject === null) {
+        throw new ApiError(ERROR.notFound, `No such id: ${query.get('id') ?? ''}`);
+    }
+    annotations.setRating(db, subject.kind, subject.id, rating);
+    return {};
+}
+/**
+ * The starred songs, records and artists, from one music folder if a client
+ * asked for one.
+ *
+ * The folder is the protocol's own filter, and it is honoured the way every
+ * other listing in this API honours it — through `confinedTo`, which refuses a
+ * folder this server never handed out. A starred listing that accepted the
+ * parameter and answered from every folder would tell a client it was looking
+ * at one library while showing it another.
+ *
+ * Records are filtered by where they are, and songs by the root their file
+ * lives in. An artist is nobody's to place — one artist's records can sit in
+ * several folders — so they are kept when the folder asked about holds a record
+ * of theirs, which is the only sense in which an artist is in a folder.
+ */
+function starred(db, query, withSongs, origin) {
+    const rootId = confinedTo(db, query);
+    const songs = songsByIds(db, annotations.starredIds(db, 'track')).filter((row) => rootId === undefined || row.root_id === rootId);
+    const records = albumsById(db, annotations.starredIds(db, 'album')).filter((row) => rootId === undefined || row.root_id === rootId);
+    const performerIds = annotations.starredIds(db, 'artist');
+    const inRoot = rootId === undefined ? null : artistIdsInRoot(db, performerIds, rootId);
+    const performers = artistsById(db, inRoot === null ? performerIds : performerIds.filter((id) => inRoot.has(id)));
+    const child = (row) => childOf(row);
+    return withSongs
+        ? {
+            starred2: {
+                artist: performers.map((row) => artistId3(row, origin)),
+                album: records.map(albumId3),
+                song: songs.map(child),
+            },
+        }
+        : {
+            starred: {
+                // The v1 shapes: an `Artist` is a name and an id, and a record is a
+                // `Child`. The same three readings, told the older way.
+                artist: performers.map((row) => ({
+                    id: ID.artist(row.id),
+                    name: row.name,
+                    ...(row.starred_at === null ? {} : { starred: row.starred_at }),
+                    ...(row.rating === null ? {} : { userRating: row.rating }),
+                })),
+                album: records.map((row) => albumChild(row, ID.top)),
+                song: songs.map(child),
+            },
+        };
+}
+export function getStarred(db, query, origin) {
+    return starred(db, query, false, origin);
+}
+export function getStarred2(db, query, origin) {
+    return starred(db, query, true, origin);
+}

package/dist/api/artistinfo.js

@@ -0,0 +1,140 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { biographyOf } from "../artist/nfo.js";
+import { decodeText } from "../text/encoding.js";
+import { ID, artistId3, artistImageUrlOf, confinedTo, parseId, required } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+import { artist, artistByKey, artistNfoIn, artistOwnFolders } from "./meta.js";
+import { virtualEntries, virtualNodes } from "./virtual.js";
+/**
+ * What a client is told about an artist, beyond the records they made.
+ *
+ * The protocol asks this in `getArtistInfo2`, whose usual sources are last.fm
+ * and MusicBrainz — services this server does not talk to, by design. What it
+ * answers with instead is what the collection already holds: the note the
+ * operator's library keeps in the folder named for the artist, the picture
+ * `getCoverArt` already serves, and the other artists that folder gathers.
+ *
+ * `lastFmUrl` is left out because there is nothing to put there: no file in
+ * this collection carries one, and a fabricated URL is a lie a client would
+ * render as a link.
+ *
+ * `musicBrainzId` is a different case, and this comment said otherwise until a
+ * review measured it. The id **is** on disk — in the same `artist.nfo` this
+ * file already reads for the biography, under `<musicbrainzartistid>`, e.g.
+ * `69ee3720-a7cb-4402-b48d-a02c366f2bcf` for The Cure. It is not returned
+ * because nobody has built the reader, which is a gap to fill rather than an
+ * impossibility to explain away. `elementText` in `src/artist/nfo.ts` reads it
+ * with the same pass that reads the biography.
+ */
+/** The route a picture is asked for by, which is where the URLs below point. */
+const COVER_ROUTE = '/rest/getCoverArt';
+/** How many related artists the protocol offers when a client does not say. */
+const DEFAULT_COUNT = 20;
+export function getArtistInfo2(db, query, origin) {
+    const raw = required(query, 'id');
+    const parsed = parseId(raw);
+    if (parsed === undefined || parsed.kind !== 'ar') {
+        throw new ApiError(ERROR.notFound, `No such id: ${raw}`);
+    }
+    const row = artist(db, parsed.n);
+    if (row === undefined)
+        throw new ApiError(ERROR.notFound, `No such id: ${raw}`);
+    // The picture is the one `getCoverArt` already serves for this artist, named
+    // as a URL because a URL is what the protocol asks for. One picture offered at
+    // three sizes: this collection keeps one, and a server that answered with
+    // three would be promising thumbnails it has never made. It is the same URL
+    // `artistImageUrl` carries — `artistImageUrlOf` is where it is built once,
+    // since two builders of one address is how two answers to one question start.
+    const picture = artistImageUrlOf(row.id, origin);
+    const biography = biographyOfArtist(db, row.id);
+    const related = relatedArtists(db, row, confinedTo(db, query), origin).slice(0, countOf(query));
+    return {
+        artistInfo2: {
+            ...(biography === null ? {} : { biography }),
+            smallImageUrl: picture,
+            mediumImageUrl: picture,
+            largeImageUrl: picture,
+            ...(related.length === 0 ? {} : { similarArtist: related }),
+        },
+    };
+}
+/** How many related artists to offer — the client's number, or the protocol's. */
+function countOf(query) {
+    const asked = Number(query.get('count'));
+    return Number.isFinite(asked) && asked > 0 ? Math.floor(asked) : DEFAULT_COUNT;
+}
+/**
+ * The note the collection keeps about an artist, or nothing.
+ *
+ * It lives in the folder named for them, so the folders are asked in the order
+ * `artistOwnFolders` gives: the one spelled exactly like the artist first, the
+ * shelves behind it only if it holds nothing.
+ *
+ * A note that cannot be read is passed over rather than thrown out of. A row
+ * can outlive its file — a folder moved between scans would leave one — and an
+ * artist with no readable note is an artist with no note, not a failed request.
+ * An earlier version of this comment named a folder in this collection as such
+ * a case; a review checked and all three `artist.nfo` rows have their file.
+ *
+ * `biographyOf` carries the same promise and used not to keep it: it threw on a
+ * numeric entity naming no XML character, and the throw left this function
+ * because only the read was guarded. Both halves are guarded now.
+ */
+function biographyOfArtist(db, artistId) {
+    for (const where of artistOwnFolders(db, artistId)) {
+        const file = artistNfoIn(db, where);
+        if (file === null)
+            continue;
+        let text;
+        try {
+            text = decodeText(readFileSync(join(file.rootPath, file.relPath))).text;
+        }
+        catch {
+            continue;
+        }
+        const biography = biographyOf(text);
+        if (biography !== null)
+            return biography;
+    }
+    return null;
+}
+/**
+ * The other artists this artist's folder gathers.
+ *
+ * Exactly the list that folder shows as drawers, and for the same reason: where
+ * a node credits more than one name, each of those names is somebody the
+ * collection knows, and the folder is where they are reachable from. That is
+ * what makes them the answer to "who else is here" — the question a client
+ * asking for similar artists is really asking, and the only version of it this
+ * library can answer from what it holds.
+ *
+ * An artist who owns no folder has no gathering and no related artists. That is
+ * not a claim that nobody resembles them; it is that the collection has nothing
+ * to say, and an empty list says it.
+ *
+ * The artist itself is left out. The count beside each of the others is what this
+ * drawer holds, which is not always what opening that artist would give. The two
+ * agree on this collection — every name a drawer gathers has all of its records
+ * in that drawer — and would part for an artist filed in two places. Counting
+ * each of them the way their own page does would be a query per name, on a route
+ * a client calls for every artist it draws; task:2838 records the difference.
+ */
+function relatedArtists(db, row, rootId, origin) {
+    const node = virtualNodes(db, rootId).find((one) => one.artistKey === row.name_key);
+    if (node === undefined)
+        return [];
+    const related = [];
+    const seen = new Set([row.name_key]);
+    for (const entry of virtualEntries(db, node)) {
+        const credit = entry.credit;
+        if (credit === null || seen.has(credit.artistKey))
+            continue;
+        seen.add(credit.artistKey);
+        const artistRow = artistByKey(db, credit.artistKey);
+        if (artistRow === undefined)
+            continue;
+        related.push(artistId3({ ...artistRow, album_count: credit.records.length }, origin));
+    }
+    return related;
+}

package/dist/api/audit.js

@@ -0,0 +1,32 @@
+import { appendFileSync } from 'node:fs';
+/** Where a deployment's audit lines go when nobody says otherwise. */
+export function auditPath(dbPath) {
+    return `${dbPath}.audit.jsonl`;
+}
+/**
+ * A writer for one audit file.
+ *
+ * **Appended synchronously**, which is the unusual choice and the deliberate
+ * one: these lines are rare (a person operating a server, not a client polling
+ * it), so the cost is nothing, and what it buys is that the line exists before
+ * the answer does. A buffered writer loses exactly the lines written just before
+ * a crash, which are the ones somebody will want.
+ *
+ * A file that cannot be written is said on stderr and reported in the answer
+ * rather than thrown: the mutation has already happened by the time this runs,
+ * and failing the request would describe it as not having happened. What the
+ * caller is owed is the truth about both halves — it was done, and it was not
+ * recorded.
+ */
+export function auditLog(path) {
+    return (entry) => {
+        try {
+            appendFileSync(path, `${JSON.stringify(entry)}\n`);
+            return true;
+        }
+        catch (err) {
+            process.stderr.write(`funoteka admin: could not write ${path} (${err.message})\n`);
+            return false;
+        }
+    };
+}

package/dist/api/auth.js

@@ -0,0 +1,145 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { ERROR } from "./envelope.js";
+export function authenticate(query, config, signedRoute = false, registered = () => false) {
+    const user = query.get('u');
+    const token = query.get('t');
+    const salt = query.get('s');
+    const password = query.get('p');
+    const apiKey = query.get('apiKey');
+    // **A signed link is a credential of its own**, and it is checked first
+    // because such a request carries no user at all — see `coverSignature`. Only
+    // the routes that hand links out accept one, and the caller says which.
+    //
+    // A signature that is *there* and does not hold is a refusal, not an absence:
+    // a client that sent one meant to be let in, and telling it that `u` is
+    // missing describes a request it did not make.
+    if (signedRoute && signatureOffered(query)) {
+        return signatureHolds(query, config) ? { ok: true } : refused();
+    }
+    // **A key is the whole credential, and it comes alone.** The extension's own
+    // words: "When an API key is provided, the client **must not** provide a `u`
+    // parameter; passing in `u` **must** be treated as an error 43" — and the same
+    // for the other mechanisms, which is what a conflicting set of parameters is.
+    //
+    // This server had it exactly the other way round: `u` was demanded before
+    // anything else, so the *only* form the specification allows was the one form
+    // that could not work, and the form it forbids was the one that did. Found by
+    // the operator bringing Symfonium up, which sent `apiKey` alone and was told
+    // that `u` was missing — and reported it as a server whose version it could
+    // not determine, since a refusal and an answer were one HTTP status here.
+    // That last part is no longer true of every route: `getTranscodeStream`
+    // answers a refusal with a status of its own, because its own page asks for
+    // one (`STATUS_REFUSALS` in `server.ts`, task:2913).
+    if (apiKey !== null) {
+        const alongside = [token !== null || salt !== null, password !== null].filter((yes) => yes).length;
+        if (user !== null || alongside > 0) {
+            return conflicting('apiKey arrives on its own — not with u, p, t or s');
+        }
+        // Two places a key may live, and both are checked. The environment's is the
+        // bootstrap credential and is checked first — it is the way in that survives
+        // a database; the registered ones are what a person can take back while the
+        // server runs (`keys.ts`). Neither is a fallback for the other.
+        const fromEnvironment = config.apiKey !== '' && sameSecret(apiKey, config.apiKey);
+        return fromEnvironment || registered(apiKey) ? { ok: true } : refused();
+    }
+    if (user === null)
+        return missing('u');
+    // A token is two parameters and counts as one way in, so that a client which
+    // sent `t`, `s` and `p` is seen as having offered two rather than three. The
+    // key is not counted here: it never reaches this far.
+    const offered = [token !== null || salt !== null, password !== null].filter((yes) => yes).length;
+    if (offered > 1)
+        return conflicting('Send one of p, or t with s — not both');
+    if (offered === 0)
+        return missing('p, t with s, or apiKey');
+    // The user is checked before the secret, and both refusals are the same one:
+    // a caller who guessed the user right learns nothing from the answer.
+    if (!sameSecret(user, config.user))
+        return refused();
+    if (password !== null) {
+        const offered = password.startsWith('enc:') ? decodeHex(password.slice(4)) : password;
+        if (offered === null)
+            return refused();
+        return config.password !== '' && sameSecret(offered, config.password) ? { ok: true } : refused();
+    }
+    // The token path. Half of it is not a partial credential, it is a request that
+    // did not finish arriving, which is a different failure from a wrong one.
+    if (token === null)
+        return missing('t');
+    if (salt === null)
+        return missing('s');
+    const expected = createHash('md5').update(`${config.password}${salt}`).digest('hex');
+    return config.password !== '' && sameSecret(token.toLowerCase(), expected) ? { ok: true } : refused();
+}
+function missing(name) {
+    return { ok: false, code: ERROR.missingParameter, message: `Required parameter is missing: ${name}` };
+}
+/** Two ways in at once, which the protocol gives a code of its own. */
+function conflicting(message) {
+    return { ok: false, code: ERROR.conflictingAuthMechanisms, message };
+}
+/**
+ * The secret every picture link is signed with, and what revocation means here.
+ *
+ * The server's own key, or its password where no key is configured — one of the
+ * two is always set, because a server with neither cannot be built at all.
+ * **Changing it revokes every link ever handed out**, which is the whole of what
+ * revoking a link needs to be: nothing is stored, so there is nothing else to
+ * take back.
+ */
+function signingSecret(config) {
+    return config.apiKey === '' ? config.password : config.apiKey;
+}
+/**
+ * The signature a client may present instead of credentials on `getCoverArt`.
+ *
+ * **The reason is measured, not assumed.** An image loader does not
+ * authenticate: the operator's Symfonium asks for an artist's picture with no
+ * `u`, `t` or `s` at all, so a server that guards that route the way it guards
+ * every other answers a refusal — and the client can only draw a placeholder
+ * over it. Navidrome arrived at the same answer for the same symptom and hands
+ * out a signed URL for artist art.
+ *
+ * It is signed over the id **and the route it is for**, so a link handed out for
+ * a picture cannot be replayed against another door: the id alone would let a
+ * signed cover link ask `getArtist` for the same id without credentials.
+ */
+export function coverSignature(id, config) {
+    return createHmac('sha256', signingSecret(config)).update(`cover:${id}`).digest('base64url');
+}
+/** Whether the request brought a signature at all, which is not whether it fits. */
+function signatureOffered(query) {
+    const given = query.get('sig');
+    return given !== null && given !== '';
+}
+/** Whether a request carries a signature this server issued for its own id. */
+function signatureHolds(query, config) {
+    const id = query.get('id');
+    const given = query.get('sig');
+    if (id === null || given === null || given === '')
+        return false;
+    return sameSecret(given, coverSignature(id, config));
+}
+function refused() {
+    return { ok: false, code: ERROR.wrongCredentials, message: 'Wrong username or password' };
+}
+/**
+ * Whether two secrets are the same, in a time that does not say how nearly.
+ *
+ * Both sides are hashed first so that the comparison is between two buffers of
+ * one length whatever was sent: `timingSafeEqual` refuses different lengths, and
+ * an early return on a length a stranger controls is the comparison leaking by
+ * another name. The hashing also means a password is never the thing compared.
+ */
+export function sameSecret(given, expected) {
+    return timingSafeEqual(hash(given), hash(expected));
+}
+function hash(value) {
+    return createHash('sha256').update(value).digest();
+}
+/** The password `enc:` carries, or null when what follows is not hex at all. */
+function decodeHex(value) {
+    if (value.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(value))
+        return null;
+    return Buffer.from(value, 'hex').toString('utf8');
+}

package/dist/api/bookmark.js

@@ -0,0 +1,108 @@
+import { bookmark, bookmarks, unbookmark } from "../bookmark/store.js";
+import { childOf, required, trackId } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+import { song, songsByIds } from "./meta.js";
+/**
+ * Where the listener stopped, in the protocol's shape.
+ *
+ * The smallest of the listener's own routes and the only one with a single
+ * number in it: a bookmark is a song and a position inside it, and everything
+ * else in the answer is either the song itself or when the mark was made.
+ *
+ * One place per song, which is the protocol's rule and the schema's — see
+ * `bookmark/store.ts` for what that costs and why it is worth it.
+ */
+/**
+ * The mark, as the protocol spells it.
+ *
+ * The entry carries the position a second time, as `bookmarkPosition`. That is
+ * not redundancy to trim: the inner field is on the `Child`, and the `Child` is
+ * what a client draws a resume mark from in a list of songs — a client reading
+ * only `position` would have to know that the song beside it is the one it
+ * belongs to.
+ */
+function markOf(row, entry, config) {
+    return {
+        entry: { ...entry, bookmarkPosition: row.positionMs },
+        position: row.positionMs,
+        username: config.user,
+        // Absent rather than empty when the listener wrote none: a comment of `""`
+        // is a comment whose text is nothing, and a client that draws one draws an
+        // empty line under every bookmark nobody annotated.
+        ...(row.comment === null ? {} : { comment: row.comment }),
+        created: row.createdAt,
+        changed: row.changedAt,
+    };
+}
+export function getBookmarks(db, config) {
+    const rows = bookmarks(db);
+    const songs = songsByIds(db, rows.map((row) => row.trackId));
+    const byId = new Map(songs.map((row) => [row.id, row]));
+    const list = rows.flatMap((row) => {
+        const found = byId.get(row.trackId);
+        return found === undefined ? [] : [markOf(row, childOf(found), config)];
+    });
+    return { bookmarks: { bookmark: list } };
+}
+/**
+ * The position, in milliseconds, which the protocol requires.
+ *
+ * Refused when absent rather than read as zero: nought is the beginning of the
+ * song, which is a bookmark nobody means, and a client that forgot the
+ * parameter should be told it forgot rather than handed a mark at the start.
+ */
+function positionIn(query) {
+    const raw = required(query, 'position');
+    const position = Number(raw);
+    if (!Number.isInteger(position) || position < 0) {
+        throw new ApiError(ERROR.generic, `position is not a position: ${raw}`);
+    }
+    return position;
+}
+/**
+ * Put a mark on a song, or move the one that is there.
+ *
+ * A song this server does not hold is refused by name — `song` answers nothing
+ * for an id that names no row — because a bookmark on a song that is not here is
+ * a mark a client would never be shown again.
+ */
+export function createBookmark(db, query) {
+    // The budget this is held to is the hundred milliseconds a person notices, and
+    // measured on the live database it is **64–70 ms** — which is the *commit*,
+    // not the row: `star` and `unstar` pay 23–101 ms for one annotation written
+    // the same way, so this is what the live file costs, not what this route adds.
+    // On one thread that is every other client waiting out the write.
+    //
+    const id = trackId(query);
+    const row = song(db, id);
+    if (row === undefined)
+        throw new ApiError(ERROR.notFound, `No such song: ${id}`);
+    const comment = query.get('comment');
+    bookmark(db, row.id, positionIn(query), comment === null || comment === '' ? null : comment, new Date().toISOString());
+    return {};
+}
+/**
+ * Take the mark off a song.
+ *
+ * An id that names no row is refused, and one that names a song nobody
+ * bookmarked is not: the first is a client asking about a song this server does
+ * not have, and the second is a client tidying up — the state it asked for is
+ * the state it gets, and refusing would tell it off for succeeding. The
+ * asymmetry is deliberate and it is between a *song* and a *mark*: a song this
+ * server does not have is a question it cannot answer, and a mark that is not
+ * there is the answer already.
+ *
+ * **Which of the two paths a measurement lands on is worth saying**, because
+ * they are twenty times apart: the delete that removes nothing is **3–6 ms**
+ * (no write happens) and the one that removes a mark is **84–87 ms** (a commit
+ * does). A stand that probed the no-op would report this route as far cheaper
+ * than a client experiences it.
+ */
+export function deleteBookmark(db, query) {
+    const id = trackId(query);
+    const row = song(db, id);
+    if (row === undefined)
+        throw new ApiError(ERROR.notFound, `No such song: ${id}`);
+    unbookmark(db, row.id);
+    return {};
+}