funoteka 0.1.0

package/dist/api/config-file.js

@@ -0,0 +1,202 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { PORT_SETTINGS, SETTINGS, isPort } from "./settings.js";
+/**
+ * The config file: a deployment's settings, written down where a person can
+ * read them.
+ *
+ * The environment is how a service manager hands a server its settings, and it
+ * stays the interface a deployed server is configured through. A file is for the
+ * two things the environment is bad at: settings a person has to *edit* (a
+ * twenty-variable `EnvironmentFile` is a file with extra steps), and settings
+ * that outlive one shell — a NAS where nobody remembers which session exported
+ * what. So the file is a layer between the defaults and the environment, and the
+ * environment keeps the last word. The order is stated in `config.ts`; this
+ * module is only the reading and the writing of it.
+ *
+ * A JSON object and not YAML, because this project has no dependencies and Node
+ * parses JSON natively. The vocabulary is the config's own field names
+ * (`settings.ts`), so the file and the admin API's `config` route speak one
+ * language.
+ *
+ * **Nothing here is silently forgiven.** A file that cannot be parsed, a key
+ * that does not exist, or a value of the wrong shape stops the command with a
+ * sentence naming the file and the key. The alternative is the failure this
+ * exists to prevent: a server that came up on its defaults beside a file it
+ * could not read, looking exactly like a server that was configured.
+ */
+/** Where the file is when nobody says otherwise: the directory the server runs in. */
+export const DEFAULT_CONFIG_FILE = 'funoteka.json';
+/**
+ * The two names a JSON object can carry that are *known* to mean nothing.
+ *
+ * JSON has no comments, and this is a file a person edits — `funoteka.json.example`
+ * is copy-safe because of these two lines, and an example that explained itself
+ * with a key the reader refused would fail on the first run of whoever copied
+ * it. They are not the unknown-key rule relaxed: an unknown key is still a
+ * refusal, and these are not unknown.
+ */
+const COMMENTS = new Set(['//', '#']);
+/** Which file this process reads, which is the one thing env alone decides. */
+export function configFilePath(env) {
+    return env.FUNOTEKA_CONFIG ?? DEFAULT_CONFIG_FILE;
+}
+/**
+ * Read a config file, or answer with nothing if there is no file there.
+ *
+ * Absent is not an error: most deployments name their settings in the
+ * environment and have no file at all, and refusing to start over a file nobody
+ * wrote would make the file mandatory by accident.
+ */
+export function readConfigFile(path) {
+    const parsed = parse(readOf(path), path);
+    const values = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (COMMENTS.has(key))
+            continue;
+        values[key] = validated(key, value, path);
+    }
+    return values;
+}
+/**
+ * Write settings into the file, and answer with what it now says.
+ *
+ * **The file is read as it is and written back with only these keys changed**,
+ * rather than being rebuilt from the config. That is what keeps a `//` comment
+ * where somebody put it, keeps the keys in the order they were written, and
+ * leaves alone any key this server does not know about — a route that rewrote
+ * the whole file from its own idea of the config would silently drop the note
+ * that explains the deployment to the next person.
+ *
+ * A value of `null` removes the key, which is how a setting written here is
+ * handed back to the environment and the defaults.
+ *
+ * Written through a temporary file and a rename: a process that dies mid-write
+ * leaves the old config or the new one, and never half of either — the file that
+ * a restart reads is the file that governs whether there *is* a restart.
+ */
+export function writeConfigFile(path, changes) {
+    const current = parse(readOf(path), path);
+    for (const [key, value] of Object.entries(changes)) {
+        if (value === null) {
+            delete current[key];
+            continue;
+        }
+        current[key] = validated(key, value, path);
+    }
+    const temp = `${path}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(current, null, 2)}\n`, existsSync(path) ? {} : { mode: 0o600 });
+        renameSync(temp, path);
+    }
+    catch (err) {
+        throw new Error(`${path} could not be written: ${err.message}`);
+    }
+    return readConfigFile(path);
+}
+/** The file's text, or an empty object's worth of nothing when there is no file. */
+function readOf(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return '{}';
+        throw new Error(`${path} could not be read: ${err.message}`);
+    }
+}
+function parse(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        // The parser's own sentence, quoted. It names the line and the character,
+        // which is the whole of what the person editing the file needs.
+        throw new Error(`${path} is not JSON: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${path} must be an object of settings — this is ${described(parsed)}`);
+    }
+    return parsed;
+}
+/** One key's value, or a refusal naming the file, the key and what it should be. */
+function validated(key, value, path) {
+    const kind = SETTINGS[key];
+    if (kind === undefined) {
+        throw new Error(`${path}: unknown key "${key}"${didYouMean(key)}`);
+    }
+    if (kind === 'number') {
+        if (typeof value !== 'number') {
+            throw new Error(`${path}: "${key}" must be a number, not ${described(value)}`);
+        }
+        // Ports are held to the range a socket accepts, and named as sockets in the
+        // refusal. Every other number here — an interval in minutes, an hour of the
+        // day — is the config's own to bound, and is checked where it is read.
+        if (PORT_SETTINGS.has(key) && !isPort(value)) {
+            throw new Error(`${path}: "${key}" is not a port number: ${value}`);
+        }
+        return value;
+    }
+    if (kind === 'string' && typeof value === 'string')
+        return value;
+    if (kind === 'boolean' && typeof value === 'boolean')
+        return value;
+    const wanted = kind === 'boolean' ? 'true or false' : 'a string';
+    throw new Error(`${path}: "${key}" must be ${wanted}, not ${described(value)}`);
+}
+/** What a JSON value is, in words, for a refusal that has to name it. */
+function described(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'a list';
+    const kind = typeof value;
+    if (kind === 'string')
+        return `the string ${JSON.stringify(value)}`;
+    if (kind === 'number' || kind === 'boolean')
+        return `the ${kind} ${String(value)}`;
+    if (kind === 'object')
+        return 'an object';
+    return kind;
+}
+/**
+ * The key they probably meant, when they meant one at all.
+ *
+ * A refusal that names the key is the whole point (see the top of this file),
+ * and the person reading it has usually made a typo rather than invented a
+ * setting: `prot` for `port`, `showjunk` for `showJunk`. One guessed neighbour
+ * turns "unknown key" into "unknown key, did you mean port" — and it is a guess,
+ * so it is offered as a question and never acted on.
+ */
+function didYouMean(key) {
+    let nearest;
+    let best = 3;
+    for (const known of Object.keys(SETTINGS)) {
+        const distance = editDistance(key.toLowerCase(), known.toLowerCase());
+        if (distance < best) {
+            best = distance;
+            nearest = known;
+        }
+    }
+    return nearest === undefined ? '' : ` — did you mean "${nearest}"?`;
+}
+/**
+ * How many single-character edits apart two words are — the Wagner–Fischer
+ * table, one row at a time.
+ *
+ * The `?? 0` on every read is for the compiler's `noUncheckedIndexedAccess` and
+ * never for the arithmetic: each index is inside its own row by construction,
+ * and a neighbour that were somehow absent could only make the distance
+ * larger — a worse guess at the key, never a wrong refusal.
+ */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, at) => at);
+    for (let i = 1; i <= a.length; i += 1) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            row[j] = Math.min((previous[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = row;
+    }
+    return previous[b.length] ?? 0;
+}

package/dist/api/config.js

@@ -0,0 +1,285 @@
+import { dirname, join } from 'node:path';
+import { DEFAULT_DB } from "../db/index.js";
+import { SECRET_SETTINGS, SETTINGS, isPort } from "./settings.js";
+/**
+ * The scan schedule, layered exactly as everything else is.
+ *
+ * `scanInterval` is in **minutes** and defaults to six hours. Zero — or anything
+ * below it — turns the timer off: a deployment that would rather scan from a
+ * cron job of its own says so with a number, and needs no second setting to say
+ * it with.
+ */
+export function loadScanConfig(env, file = {}) {
+    return scanConfig(reader(file, env));
+}
+function scanConfig(r) {
+    const interval = r.pick('scanInterval', 'FUNOTEKA_SCAN_INTERVAL');
+    const from = r.pick('scanQuietFrom', 'FUNOTEKA_SCAN_QUIET_FROM');
+    const to = r.pick('scanQuietTo', 'FUNOTEKA_SCAN_QUIET_TO');
+    return {
+        intervalMinutes: interval === undefined ? DEFAULT_SCAN_INTERVAL_MINUTES : wholeNumber(interval),
+        quietFrom: from === undefined ? DEFAULT_QUIET_FROM : hour(from),
+        quietTo: to === undefined ? DEFAULT_QUIET_TO : hour(to),
+        watch: offUnlessOn(r.pick('scanWatch', 'FUNOTEKA_SCAN_WATCH')?.value, false),
+    };
+}
+/** A number from whichever layer named it, or a refusal naming that layer. */
+function wholeNumber(picked) {
+    const value = Number(picked.value);
+    if (!Number.isInteger(value)) {
+        throw new Error(`${picked.source} is not a whole number: ${String(picked.value)}`);
+    }
+    return value;
+}
+/** An hour of the day, 0–23, or a refusal saying which setting was wrong. */
+function hour(picked) {
+    const value = wholeNumber(picked);
+    if (value < 0 || value > 23) {
+        throw new Error(`${picked.source} is not an hour of the day (0-23): ${value}`);
+    }
+    return value;
+}
+/**
+ * Subsonic's own port, so a client that guesses one guesses right, and above
+ * 1024 so the server does not need privileges it has no other use for.
+ */
+export const DEFAULT_PORT = 4533;
+/**
+ * The admin port: the Subsonic port plus one, because two ports that differ by
+ * one are one number to remember instead of two, and 4534 is not a port anything
+ * else claims.
+ */
+export const DEFAULT_ADMIN_PORT = 4534;
+/** Reachable from the phone on the sofa, which is the whole point of the server. */
+export const DEFAULT_HOST = '0.0.0.0';
+/** Six hours: often enough that a change is noticed the same day, rarely enough to be quiet. */
+export const DEFAULT_SCAN_INTERVAL_MINUTES = 360;
+/**
+ * The quiet hours: three in the morning to six.
+ *
+ * The hours a house is asleep in, and the reason they exist is that a scan is
+ * audible — it reads every file, and on a machine that is also somebody's
+ * desktop it is the difference between a library that keeps up and a library
+ * that stutters while they are working. `from === to` is no quiet hours at all.
+ */
+export const DEFAULT_QUIET_FROM = 3;
+export const DEFAULT_QUIET_TO = 6;
+/** Where to look for ffmpeg, which only the m4a and MP4 segments ever need. */
+export const DEFAULT_FFMPEG = 'ffmpeg';
+function reader(file, env) {
+    const sources = {};
+    return {
+        sources,
+        pick(key, envName, flag, flagName) {
+            if (flag !== undefined) {
+                sources[key] = 'flag';
+                return { value: flag, source: flagName ?? key };
+            }
+            const fromEnv = env[envName];
+            if (fromEnv !== undefined) {
+                sources[key] = 'environment';
+                return { value: fromEnv, source: envName };
+            }
+            const fromFile = file[key];
+            if (fromFile !== undefined) {
+                sources[key] = 'file';
+                return { value: fromFile, source: key };
+            }
+            return undefined;
+        },
+    };
+}
+function serverConfig(r, overrides) {
+    const dbPath = String(r.pick('dbPath', 'FUNOTEKA_DB', overrides.dbPath, '--db')?.value ?? DEFAULT_DB);
+    // Named together so the refusal below can say which of the three was wrong:
+    // the operator who mistyped a flag, the one who mistyped a unit file, and the
+    // one who mistyped the config file are looking in different places.
+    const port = r.pick('port', 'FUNOTEKA_PORT', overrides.port, '--port');
+    return {
+        dbPath,
+        host: String(r.pick('host', 'FUNOTEKA_HOST', overrides.host, '--host')?.value ?? DEFAULT_HOST),
+        port: port === undefined || port.value === ''
+            ? DEFAULT_PORT
+            : parsePort(String(port.value), port.source),
+        user: String(r.pick('user', 'FUNOTEKA_USER', overrides.user, '--user')?.value ?? ''),
+        password: String(r.pick('password', 'FUNOTEKA_PASSWORD', overrides.password, '--password')?.value ?? ''),
+        apiKey: String(r.pick('apiKey', 'FUNOTEKA_APIKEY', overrides.apiKey, '--apikey')?.value ?? ''),
+        ffmpeg: String(r.pick('ffmpeg', 'FUNOTEKA_FFMPEG', overrides.ffmpeg, '--ffmpeg')?.value ?? DEFAULT_FFMPEG),
+        cacheDir: String(r.pick('cacheDir', 'FUNOTEKA_CACHE', overrides.cacheDir, '--cache')?.value ??
+            join(dirname(dbPath), 'cache')),
+        logFile: String(r.pick('logFile', 'FUNOTEKA_LOG_FILE')?.value ?? ''),
+        logRequests: offUnlessOn(r.pick('logRequests', 'FUNOTEKA_LOG_REQUESTS')?.value, false),
+        cors: onUnlessOff(r.pick('cors', 'FUNOTEKA_CORS')?.value, true),
+        showJunk: offUnlessOn(r.pick('showJunk', 'FUNOTEKA_SHOW_JUNK')?.value, false),
+    };
+}
+function adminConfig(r) {
+    const port = r.pick('adminPort', 'FUNOTEKA_ADMIN_PORT');
+    const cert = String(r.pick('adminTlsCert', 'FUNOTEKA_ADMIN_TLS_CERT')?.value ?? '');
+    const key = String(r.pick('adminTlsKey', 'FUNOTEKA_ADMIN_TLS_KEY')?.value ?? '');
+    const token = String(r.pick('adminToken', 'FUNOTEKA_ADMIN_TOKEN')?.value ?? '');
+    // Both or neither. Half a TLS is not a weaker TLS — it is a server that would
+    // have to decide whether to answer in plaintext somebody who asked for a
+    // certificate, and there is no answer to that which is not a surprise.
+    if ((cert === '') !== (key === '')) {
+        const missing = cert === '' ? 'FUNOTEKA_ADMIN_TLS_CERT' : 'FUNOTEKA_ADMIN_TLS_KEY';
+        throw new Error(`${missing} is not set, and TLS needs both the certificate and its key`);
+    }
+    return {
+        port: port === undefined || port.value === ''
+            ? DEFAULT_ADMIN_PORT
+            : parsePort(String(port.value), port.source),
+        host: String(r.pick('adminHost', 'FUNOTEKA_ADMIN_HOST')?.value ?? DEFAULT_HOST),
+        // A template is not a secret — see `unexpanded`, and read the empty one the
+        // same way, because the contract's answer to "no token" is a surface that is
+        // off rather than a surface that is open.
+        token: unexpanded(token) ? '' : token,
+        allow: String(r.pick('adminAllow', 'FUNOTEKA_ADMIN_ALLOW')?.value ?? ''),
+        trustProxy: offUnlessOn(r.pick('adminTrustProxy', 'FUNOTEKA_ADMIN_TRUST_PROXY')?.value, false),
+        tls: cert === '' ? null : { cert, key },
+        supervised: onUnlessOff(r.pick('supervised', 'FUNOTEKA_SUPERVISED')?.value, false),
+    };
+}
+/**
+ * Every setting, in force and where from.
+ *
+ * This is what makes `config set` honest. The route reads the file, writes it,
+ * and then answers with this: what the file now says, what is actually in force,
+ * and which of the two the operator is looking at. A value written to the file
+ * that an environment variable overrides is a change that will not survive a
+ * restart either, and saying so is the whole difference between a control
+ * surface that works and one that only appears to.
+ */
+export function configReport(env, overrides = {}, file = {}) {
+    const r = reader(file, env);
+    const server = serverConfig(r, overrides);
+    const admin = adminConfig(r);
+    const scan = scanConfig(r);
+    // Spelled out rather than spread from the two objects: the field names of a
+    // config are not the names of its settings (`admin.token` is `adminToken`),
+    // and a list a reader can check against `settings.ts` at a glance is worth
+    // more here than the lines it saves. A setting missing from it is caught by
+    // the test that walks the vocabulary.
+    const values = {
+        dbPath: server.dbPath,
+        host: server.host,
+        port: server.port,
+        user: server.user,
+        password: server.password,
+        apiKey: server.apiKey,
+        ffmpeg: server.ffmpeg,
+        cacheDir: server.cacheDir,
+        logFile: server.logFile,
+        logRequests: server.logRequests,
+        cors: server.cors,
+        showJunk: server.showJunk,
+        adminPort: admin.port,
+        adminHost: admin.host,
+        adminToken: admin.token,
+        adminAllow: admin.allow,
+        adminTrustProxy: admin.trustProxy,
+        adminTlsCert: admin.tls?.cert ?? '',
+        adminTlsKey: admin.tls?.key ?? '',
+        supervised: admin.supervised,
+        scanInterval: scan.intervalMinutes,
+        scanQuietFrom: scan.quietFrom,
+        scanQuietTo: scan.quietTo,
+        scanWatch: scan.watch,
+    };
+    return Object.keys(SETTINGS).map((key) => ({
+        key,
+        value: SECRET_SETTINGS.has(key) ? null : (values[key] ?? null),
+        source: r.sources[key] ?? 'default',
+        secret: SECRET_SETTINGS.has(key),
+    }));
+}
+/** Whether a setting that is on unless it was turned off was turned off. */
+function isOff(value) {
+    return value !== undefined && ['0', 'false', 'no', 'off'].includes(value.toLowerCase());
+}
+/**
+ * Whether a setting was turned on.
+ *
+ * Absent is off, and so is anything that reads as a no — an operator who writes
+ * `FUNOTEKA_LOG_REQUESTS=0` means off, and one who writes `=1` means on. Any
+ * other value is taken as on, because a variable that was set at all was set on
+ * purpose and refusing to understand it would turn a working server into a
+ * silent one.
+ */
+function isOn(value) {
+    if (value === undefined || value === '')
+        return false;
+    return !['0', 'false', 'no', 'off'].includes(value.toLowerCase());
+}
+/**
+ * A setting that is off unless it was turned on, from whichever layer set it.
+ *
+ * The file gives a real boolean and the environment gives a word, and both are
+ * read here — a file is JSON, so `"logRequests": true` is a boolean and there is
+ * no reason to make its author write `"1"`.
+ */
+function offUnlessOn(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'boolean')
+        return value;
+    return isOn(String(value));
+}
+/** The same, for a setting that is on unless it was turned off. */
+function onUnlessOff(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'boolean')
+        return value;
+    return !isOff(String(value));
+}
+/**
+ * A value that is still a `${...}` placeholder was never expanded.
+ *
+ * **Nothing in this file's layering expands anything**, which is what makes the
+ * question worth asking: expansion belongs to whatever wraps the process, and
+ * the wrappers differ. Claude Code expands `${VAR}` in an `.mcp.json` — and,
+ * when the variable is *not* set, passes the text through untouched, so the
+ * literal `${FUNOTEKA_ADMIN_TOKEN}` arrives as the token. A template is not a
+ * value somebody chose; it is a value somebody meant to substitute, and both
+ * readings of it as a secret are bad. As the server's token it is a *published*
+ * string that anyone could present; as a client's it is a wrong-token attempt,
+ * and ten of those lock the address out for fifteen minutes. Reading it as no
+ * token at all is the only safe one, and it is the reading the contract already
+ * has for a token nobody set.
+ *
+ * A `$` and a `{` that are not adjacent are ordinary characters in a secret, so
+ * only `$` immediately followed by `{` counts.
+ */
+export function unexpanded(value) {
+    return value.includes('${');
+}
+/**
+ * The whole config, for a server about to listen.
+ *
+ * The two functions below are the same reading with different questions asked of
+ * it — `configReport` wants to know where each value came from as well as what
+ * it is — so the layering itself lives once, in `reader`, and each caller is a
+ * line.
+ */
+export function loadConfig(env, overrides = {}, file = {}) {
+    return serverConfig(reader(file, env), overrides);
+}
+/** What the admin listener is configured by, layered exactly as above. */
+export function loadAdminConfig(env, file = {}) {
+    return adminConfig(reader(file, env));
+}
+/**
+ * A port number, or a throw naming what could not be read as one.
+ *
+ * The range is the one a socket accepts, and 0 is inside it: it asks the kernel
+ * to pick a free port, which is what a test wants and what `serve` reports back
+ * as the port it actually bound.
+ */
+export function parsePort(value, source) {
+    const port = Number(value);
+    if (!isPort(port)) {
+        throw new Error(`${source} is not a port number: ${value}`);
+    }
+    return port;
+}