funoteka 0.1.0

package/dist/api/router.js

@@ -0,0 +1,133 @@
+import { getStarred, getStarred2, setRating, star, unstar } from "./annotation.js";
+import { getArtistInfo2 } from "./artistinfo.js";
+import { createBookmark, deleteBookmark, getBookmarks } from "./bookmark.js";
+import { getAlbum, getAlbumList2, getArtist, getArtists, getIndexes, getMusicDirectory, getMusicFolders, getRandomSongs, getSong, } from "./browse.js";
+import { download } from "./download.js";
+import { coverArt } from "./cover.js";
+import { openSubsonicExtensions } from "./extensions.js";
+import { getGenres, getSongsByGenre } from "./genre.js";
+import { getNowPlaying, getPlayQueue, getPlayQueueByIndex, reportPlayback, savePlayQueue, savePlayQueueByIndex, scrobble, } from "./history.js";
+import { scanStatus } from "./meta.js";
+import { createPlaylist, deletePlaylist, getPlaylist, getPlaylists, updatePlaylist, } from "./playlist.js";
+import { search3 } from "./search.js";
+import { stream } from "./stream.js";
+import { STUBBED, STUBBED_BYTES, stubPayload, stubRefusal } from "./stubs.js";
+import { getTranscodeDecision, getTranscodeStream } from "./transcode.js";
+import { getUser, getUsers } from "./user.js";
+const ROUTES = new Map([
+    ['ping', () => ({})],
+    // What this server supports, which is the one answer a client may ask for
+    // without credentials — see `PUBLIC` in `server.ts`. It sits here rather than
+    // near the rest because it is not about the collection at all: it is about
+    // the build.
+    ['getopensubsonicextensions', () => openSubsonicExtensions()],
+    // A server that runs on your own hardware has no trial to expire and nothing
+    // to sell, so the license is always valid. The method exists because clients
+    // call it before anything else and take a refusal as "do not talk to me".
+    ['getlicense', () => ({ license: { valid: true } })],
+    ['getscanstatus', ({ db }) => ({ scanStatus: scanStatus(db) })],
+    ['getindexes', ({ db, query, visibility }) => getIndexes(db, query, visibility)],
+    ['getartists', ({ db, query, visibility, origin }) => getArtists(db, query, visibility, origin)],
+    ['getmusicfolders', ({ db }) => getMusicFolders(db)],
+    ['getartist', ({ db, query, visibility, origin }) => getArtist(db, query, visibility, origin)],
+    ['getartistinfo2', ({ db, query, origin }) => getArtistInfo2(db, query, origin)],
+    ['getalbum', ({ db, query }) => getAlbum(db, query)],
+    ['getalbumlist2', ({ db, query, visibility }) => getAlbumList2(db, query, visibility)],
+    ['getmusicdirectory', ({ db, query, visibility }) => getMusicDirectory(db, query, visibility)],
+    ['getsong', ({ db, query }) => getSong(db, query)],
+    ['getgenres', ({ db, visibility }) => getGenres(db, visibility)],
+    ['getsongsbygenre', ({ db, query, visibility }) => getSongsByGenre(db, query, visibility)],
+    ['search3', ({ db, query, visibility, origin }) => search3(db, query, visibility, origin)],
+    ['getuser', ({ db, config, query }) => getUser(db, config, query.get('username'))],
+    // The same record inside a list, which is what the protocol's plural asks for
+    // and what the operator asked for when the two answers disagreed (wiki:3640).
+    ['getusers', ({ db, config }) => getUsers(db, config)],
+    // Something to open the app on, and a place to come back to. The first is
+    // the one listing here whose answer is not the same twice.
+    ['getrandomsongs', ({ db, query, visibility }) => getRandomSongs(db, query, visibility)],
+    ['getbookmarks', ({ db, config }) => getBookmarks(db, config)],
+    ['createbookmark', ({ db, query }) => createBookmark(db, query)],
+    ['deletebookmark', ({ db, query }) => deleteBookmark(db, query)],
+    // The listener's marks: the rest of the writing surface, and the same kind of
+    // thing as a playlist — said about the music rather than read from it. The
+    // two listings read what the three above write, and they take the protocol's
+    // music-folder filter like every other listing here.
+    ['star', ({ db, query }) => star(db, query)],
+    ['unstar', ({ db, query }) => unstar(db, query)],
+    ['setrating', ({ db, query }) => setRating(db, query)],
+    ['getstarred', ({ db, query, origin }) => getStarred(db, query, origin)],
+    ['getstarred2', ({ db, query, origin }) => getStarred2(db, query, origin)],
+    // What the listener played, what is on, and the queue they left. The third
+    // part of their own layer, and the only one that is about *time*: the rows
+    // here say the collection was used, not what somebody thought of it.
+    ['scrobble', ({ db, query }) => scrobble(db, query)],
+    ['getnowplaying', ({ db, config }) => getNowPlaying(db, config)],
+    ['reportplayback', ({ db, query }) => reportPlayback(db, query)],
+    ['getplayqueue', ({ db, config }) => getPlayQueue(db, config)],
+    ['saveplayqueue', ({ db, query }) => savePlayQueue(db, query)],
+    // The `indexBasedQueue` extension, and the same queue: an id cannot say which
+    // of two identical entries is playing, and a position can.
+    ['getplayqueuebyindex', ({ db, config }) => getPlayQueueByIndex(db, config)],
+    ['saveplayqueuebyindex', ({ db, query }) => savePlayQueueByIndex(db, query)],
+    // The listener's playlists. Everything else here answers about a collection
+    // the scanner built; these answer about what the listener said of it, and
+    // three of the five write.
+    ['getplaylists', ({ db, config, query }) => getPlaylists(db, config, query)],
+    ['getplaylist', ({ db, config, query }) => getPlaylist(db, config, query)],
+    ['createplaylist', ({ db, config, query }) => createPlaylist(db, config, query)],
+    ['updateplaylist', ({ db, config, query }) => updatePlaylist(db, config, query)],
+    ['deleteplaylist', ({ db, query }) => deletePlaylist(db, query)],
+    // The `transcoding` extension, first half: what this server would do with a
+    // song for a client that has stated what it can play. Its other half answers
+    // with the stream itself and is a binary route below, because the bytes are
+    // `stream`'s own — see `transcode.ts`.
+    ['gettranscodedecision', (context) => getTranscodeDecision(context)],
+]);
+/**
+ * The route for a method name, if there is one.
+ *
+ * The lookup lowers the name: the protocol spells its methods in camelCase, and
+ * a server that answered only the exact spelling would fail a client over a
+ * difference no answer depends on.
+ */
+export function route(method) {
+    const name = method.toLowerCase();
+    const answered = ROUTES.get(name);
+    if (answered !== undefined)
+        return answered;
+    // What this server answers empty by form rather than refusing. Asked here
+    // instead of being listed beside the real routes so that `ROUTES` above stays
+    // what it reads as — the surface this server *fills* — and the two cannot be
+    // confused for each other by a reader counting entries. See `stubs.ts`.
+    if (STUBBED.has(name)) {
+        return ({ query }) => stubPayload(name, query) ?? {};
+    }
+    return undefined;
+}
+const BINARY = new Map([
+    ['stream', stream],
+    // The same bytes as `stream` and a different promise: `stream` answers with
+    // something a client can play, `download` with the file itself.
+    ['download', download],
+    ['getcoverart', coverArt],
+    // The other half of `transcoding`: the same bytes `stream` would send, chosen
+    // by the decision a client was handed rather than by parameters of its own.
+    ['gettranscodestream', getTranscodeStream],
+]);
+export function binaryRoute(method) {
+    const name = method.toLowerCase();
+    const answered = BINARY.get(name);
+    if (answered !== undefined)
+        return answered;
+    // The byte-answering stubs: three methods the protocol answers with an image,
+    // a caption file or a playlist, none of which this server can produce. The
+    // refusal is thrown rather than written, so it goes out through the one place
+    // that renders refusals — and before any header, which is the rule every
+    // binary route keeps.
+    const reason = STUBBED_BYTES.get(name);
+    if (reason === undefined)
+        return undefined;
+    return () => {
+        throw stubRefusal(reason);
+    };
+}

package/dist/api/scanner.js

@@ -0,0 +1,163 @@
+import { spawn } from 'node:child_process';
+export function scanner(deps) {
+    let child = null;
+    let mode = 'incremental';
+    let startedAt = '';
+    let cancelling = false;
+    const finish = () => {
+        child = null;
+        cancelling = false;
+    };
+    return {
+        start(next) {
+            if (child !== null) {
+                return { ok: false, reason: `a scan is already running (pid ${child.pid ?? '?'})` };
+            }
+            // **A run the database still calls `running` is a run in the way**, whoever
+            // started it. Two scans on one file do not corrupt it — SQLite sees to
+            // that — but they read the whole collection twice and each reports half of
+            // what happened, and the operator asked for one. `cancel` is the way out
+            // of a row whose process is gone, and it says when it is settling one.
+            const last = newest(deps.db);
+            if (last?.status === 'running') {
+                return {
+                    ok: false,
+                    reason: `run ${last.id} is still recorded as running (started ${last.started_at}). ` +
+                        'If its process is gone, POST /scan/cancel settles it',
+                };
+            }
+            // **A scan with nothing to read is refused here rather than spawned.**
+            // The child would exit with a usage error — `scan needs at least one root`
+            // — and this end would have logged "scanning" about it, which is a line
+            // that says the opposite of what happened. Found on a live server whose
+            // engine started before any root was configured.
+            const roots = deps.roots();
+            if (roots.length === 0) {
+                return { ok: false, reason: 'no roots are configured — POST /roots adds one' };
+            }
+            const { file, args } = deps.command(next);
+            mode = next;
+            startedAt = new Date().toISOString();
+            cancelling = false;
+            const started = spawn(file, args, {
+                // The scanner's own narration goes where this server's goes: the log a
+                // deployment already collects. Piped and re-emitted, a child's output
+                // arrives in the server's process and can be lost with it; inherited, it
+                // is written by the process that produced it.
+                stdio: ['ignore', 'inherit', 'inherit'],
+                windowsHide: true,
+            });
+            child = started;
+            started.once('exit', () => {
+                // The row is left as the run settled it — `ok` or `failed`, written by
+                // the scanner itself. Only a cancellation has to be written from here,
+                // because the process was killed before it could say so.
+                if (cancelling)
+                    settleCancelled(deps.db, startedAt);
+                finish();
+            });
+            started.once('error', finish);
+            return { ok: true, pid: started.pid ?? 0 };
+        },
+        status() {
+            return {
+                running: child === null || child.pid === undefined
+                    ? null
+                    : { pid: child.pid, mode, startedAt, cancelling },
+                last: asRow(newest(deps.db)),
+            };
+        },
+        cancel() {
+            // A child of this process is killed first, and it is killed whether or not
+            // its run has already recorded its end: a process that has finished its
+            // work and has not exited yet is still a process, and the handle is ours.
+            // (Measured on a live server: a run over 2400 files finished in 353 ms and
+            // its child was still there a second later. Killing it was right; the row
+            // it had already settled is left alone by `settleCancelled`.)
+            if (child !== null) {
+                cancelling = true;
+                // Killed rather than asked to stop, and on Windows there is no choice: a
+                // signal has no handler to reach. Safe here for the same reason it is
+                // safe for the server: the meta layer is SQLite in WAL, built to survive
+                // a writer that stops mid-write, and the stages rebuild their own rows
+                // from the present — which is what makes a half-finished run something
+                // the next one repairs rather than something that has to be undone.
+                child.kill();
+                return { ok: true, settled: null };
+            }
+            // Nothing of ours is running, so what is left to stop is a *row* — one a
+            // process that has since gone left `running`, which is a server restarted
+            // mid-scan or a scan killed with the machine. Settling it is the whole of
+            // what cancel can mean here, and saying which of the two it did is the
+            // difference between "stopped" and "marked as stopped".
+            const last = newest(deps.db);
+            if (last?.status !== 'running')
+                return { ok: false, reason: 'no scan is running' };
+            settleCancelled(deps.db, last.started_at);
+            return { ok: true, settled: last.id };
+        },
+        history(limit) {
+            const rows = deps.db
+                .prepare('SELECT id, started_at, finished_at, status, roots_json FROM scan_run ORDER BY id DESC LIMIT ?')
+                .all(limit);
+            return rows.map((row) => ({
+                id: row.id,
+                startedAt: row.started_at,
+                finishedAt: row.finished_at,
+                status: row.status,
+                roots: parseRoots(row.roots_json),
+            }));
+        },
+    };
+}
+/**
+ * The newest run, which is the one a question about "the scan" is about.
+ *
+ * Read from the database rather than remembered from this process's own child,
+ * because a scan outlives a restart of the server: a server that has just come
+ * up has no handle to a walk that is still going, and reporting "nothing is
+ * running" beside a row that says otherwise would be two answers to one
+ * question.
+ */
+function newest(db) {
+    return (db
+        .prepare('SELECT id, started_at, finished_at, status, roots_json FROM scan_run ORDER BY id DESC LIMIT 1')
+        .get() ?? null);
+}
+/** A run row as the surface reports it, or nothing when there is no row. */
+function asRow(row) {
+    if (row === null)
+        return null;
+    return {
+        id: row.id,
+        startedAt: row.started_at,
+        finishedAt: row.finished_at,
+        status: row.status,
+        roots: parseRoots(row.roots_json),
+    };
+}
+/**
+ * Write down that a run was stopped.
+ *
+ * `cancelled` is a fourth value in a column whose comment names three — the
+ * alternative was leaving the row `running` for ever, which is worse in every
+ * direction: `getScanStatus` would keep telling every client that a scan is on,
+ * and `start` would refuse to start one. Readers that ask `=== 'running'` read
+ * it as not running, which is what it is.
+ *
+ * The row is found by the time the run started rather than by its id, because
+ * the id is the scanner's to create and this process never saw it: a run started
+ * after this one cannot be the one being settled.
+ */
+function settleCancelled(db, since) {
+    db.prepare("UPDATE scan_run SET status = 'cancelled', finished_at = ? WHERE status = 'running' AND started_at >= ?").run(new Date().toISOString(), since);
+}
+export function parseRoots(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed.filter((one) => typeof one === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/api/search.js

@@ -0,0 +1,82 @@
+import { matchExpression } from "../search/query.js";
+import { albumsById, artistsById, root, searchAlbumIds, searchArtistIds, searchSongs, } from "./meta.js";
+import { albumId3, artistId3, childOf, confinedTo, parseId } from "./browse.js";
+import { ApiError, ERROR } from "./envelope.js";
+/**
+ * The library, searched.
+ *
+ * Three sections answer one query — artists, albums and songs — and they do not
+ * answer it the same way. An artist and an album are *found through* the songs
+ * that match, so a query for a title answers with the record it is on and who
+ * made it, which is what a client showing a search result actually needs: the
+ * user typed a song and is being offered a place to play it from.
+ *
+ * The counts are small on purpose and the protocol's own default is kept. A
+ * client shows a handful of each and asks again with an offset when the user
+ * scrolls, so a server that answered with everything would put the library on
+ * the wire to have nineteen twentieths of it thrown away.
+ */
+/**
+ * The protocol's default page, per section.
+ *
+ * Its own number and not the listing route's ten: a search is the one call a
+ * client makes on every keystroke, and the two methods were given different
+ * defaults by the protocol for that reason.
+ */
+const DEFAULT_COUNT = 20;
+/** The ceiling a client cannot raise, so one call cannot ask for the collection. */
+const MAX_COUNT = 500;
+function count(query, name) {
+    const raw = query.get(name);
+    if (raw === null || raw === '')
+        return DEFAULT_COUNT;
+    const value = Number(raw);
+    if (!Number.isInteger(value)) {
+        throw new ApiError(ERROR.generic, `${name} is not a whole number: ${raw}`);
+    }
+    // Zero is a page of no rows and not a missing page: `songCount=0` is a client
+    // asking for artists only, and clamping it up to one — which is what the
+    // listing route does with its own page size — answers with a song nobody
+    // asked for.
+    return Math.min(Math.max(value, 0), MAX_COUNT);
+}
+function offset(query, name) {
+    const raw = query.get(name);
+    if (raw === null || raw === '')
+        return 0;
+    const value = Number(raw);
+    if (!Number.isInteger(value)) {
+        throw new ApiError(ERROR.generic, `${name} is not a whole number: ${raw}`);
+    }
+    return Math.max(value, 0);
+}
+export function search3(db, query, visibility, origin) {
+    const rootId = confinedTo(db, query);
+    // The protocol calls `query` required, and the empty one is the exception that
+    // matters: a client's first sync asks `search3?query=` and expects the library
+    // back. So a missing query and an empty one are the same request, and both
+    // mean "everything" — see `SearchPage`.
+    const words = matchExpression(query.get('query') ?? '');
+    const page = (prefix) => ({
+        match: words,
+        size: count(query, `${prefix}Count`),
+        offset: offset(query, `${prefix}Offset`),
+        ...(rootId === undefined ? {} : { rootId }),
+        visibility,
+    });
+    return {
+        searchResult3: {
+            // The sections are always present, empty ones included: a client that
+            // reads a missing section and an empty one differently would otherwise
+            // have to guess which this server meant.
+            // Each section resolves its whole page in one query. Asking per id was a
+            // separate execution of the album select — which carries the genre window
+            // table — for every row returned, so a page of 250 cost about two seconds.
+            // The sections were never slow to *find* their rows; they were slow to
+            // look them up one at a time.
+            artist: artistsById(db, searchArtistIds(db, page('artist'))).map((row) => artistId3(row, origin)),
+            album: albumsById(db, searchAlbumIds(db, page('album'))).map(albumId3),
+            song: searchSongs(db, page('song')).map((row) => childOf(row)),
+        },
+    };
+}