Migrated to kiwix-serve

src/server.js

@@ -0,0 +1,219 @@
+'use strict';
+
+import {spawn, execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {decodeHtml, fromXml} from '@ztimson/utils';
+import {fuzzyMatch, weightedScore} from './utils.js';
+
+const execFileAsync = promisify(execFile);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_BIN_DIR = path.join(__dirname, '..', 'bin'); // npm package root/bin - where bin/install.js drops the kiwix-tools binaries
+const READY_TIMEOUT = 10_000;
+const READY_POLL_INTERVAL = 100;
+
+function findFreePort() {
+	return new Promise((resolve, reject) => {
+		const srv = net.createServer();
+		srv.on('error', reject);
+		srv.listen(0, () => {
+			const {port} = srv.address();
+			srv.close(() => resolve(port));
+		});
+	});
+}
+
+/** Owns a kiwix-serve process's full lifecycle: library.xml, start/stop/reload, content + search access. */
+export class KiwixServer {
+	#dir;
+	#host;
+	#port;
+	#binDir;
+	#libraryPath;
+	#child = null;
+
+	get port() { return this.#port; }
+	get running() { return !!this.#child; }
+	get baseUrl() { return this.#child ? `http://${this.#host}:${this.#port}` : null; }
+
+	/** @param {{port?: number, host?: string, binDir?: string}} [opts] port defaults to an auto-picked free port; host defaults to localhost-only; binDir defaults to the bundled ./bin next to this package. */
+	constructor(dir, {port, host = '127.0.0.1', binDir = DEFAULT_BIN_DIR} = {}) {
+		this.#dir = dir;
+		this.#host = host;
+		this.#port = port;
+		this.#binDir = binDir;
+		this.#libraryPath = path.join(dir, 'library.xml');
+	}
+
+	#assertRunning() {
+		if (!this.#child) throw new Error('KiwixServer is not running - call start() first');
+	}
+
+	#bin(name) {
+		return path.join(this.#binDir, process.platform === 'win32' ? `${name}.exe` : name);
+	}
+
+	/** Rebuilds library.xml from scratch by scanning `dir` for .zim files - a full rebuild is simpler and less bug-prone than tracking incremental add/remove. */
+	async #rebuildLibrary() {
+		await fs.promises.rm(this.#libraryPath, {force: true});
+		for (const f of await this.#zimFiles()) await execFileAsync(this.#bin('kiwix-manage'), [this.#libraryPath, 'add', path.join(this.#dir, f)]);
+	}
+
+	async #waitUntilReady() {
+		const deadline = Date.now() + READY_TIMEOUT;
+		while (Date.now() < deadline) {
+			try {
+				await fetch(`http://${this.#host}:${this.#port}/`);
+				return;
+			} catch {}
+			await new Promise(r => setTimeout(r, READY_POLL_INTERVAL));
+		}
+		throw new Error('kiwix-serve did not become ready in time');
+	}
+
+	async #zimFiles() {
+		return (await fs.promises.readdir(this.#dir).catch(() => [])).filter(f => f.endsWith('.zim'));
+	}
+
+	/** URL for a single asset, e.g. for pulling one html/image file when you already know the path (from search). */
+	contentUrl(book, pathInZim = '') {
+		this.#assertRunning();
+		return `${this.baseUrl}/content/${book}/${pathInZim}`;
+	}
+
+	/** Rebuilds library.xml and starts kiwix-serve. Resolves once the server is responding. */
+	async start() {
+		if (this.#child) return;
+		await fs.promises.mkdir(this.#dir, {recursive: true});
+		await this.#rebuildLibrary();
+		this.#port ??= await findFreePort();
+
+		this.#child = spawn(this.#bin('kiwix-serve'), ['--library', '-i', this.#host, '-p', String(this.#port), this.#libraryPath], {stdio: 'ignore'});
+		this.#child.on('exit', () => { this.#child = null; });
+
+		try {
+			await this.#waitUntilReady();
+		} catch (e) {
+			await this.stop();
+			throw e;
+		}
+	}
+
+	/** Gracefully stops kiwix-serve, if running. */
+	async stop() {
+		if (!this.#child) return;
+		const child = this.#child;
+		await new Promise(resolve => {
+			child.once('exit', resolve);
+			child.kill('SIGTERM');
+		});
+		this.#child = null;
+	}
+
+	async restart() {
+		await this.stop();
+		await this.start();
+	}
+
+	/** Rebuilds library.xml from disk and hot-reloads kiwix-serve via SIGHUP - no downtime/restart needed. */
+	async reload() {
+		if(!this.#child) return;
+		await this.restart();
+	}
+
+	/** Local catalog listing - same flat shape as the online catalog (catalog.js), plus a `file` field since these already live on disk. */
+	async list() {
+		this.#assertRunning();
+		const xml = await fs.promises.readFile(this.#libraryPath, 'utf8').catch(() => '');
+		const entries = fromXml(xml);
+		return (entries?.library?.book || []).map(e => {
+			const tags = e.tags.split(';');
+			const name = e.path.replaceAll('.zim', '');
+			return {
+				id: e.id,
+				title: e.title,
+				updated: new Date(e.date),
+				summary: e.description,
+				language: e.language,
+				name: e.name,
+				category: tags.find(t => t.startsWith('_category'))?.slice(10) || '',
+				tags,
+				mediaCount: +e.mediaCount || 0,
+				author: e.creator,
+				publisher: e.publisher,
+				articleCount: +e.articleCount || 0,
+				sizeMb: +(Number(e.size) / 1024).toFixed(1) || 0,
+				href: name,
+				icon: e.favicon,
+				viewer: `${this.baseUrl}/content/${name}`,
+			};
+		});
+	}
+
+	/** Splits a href ("zim/path/to/page") or a full content/viewer URL into {zim, path}. */
+	#splitHref(href) {
+		const clean = href.replace(`${this.baseUrl}/content/`, '').replace(/^\/+/, '');
+		const [zim, ...rest] = clean.split('/');
+		return {zim, path: rest.join('/')};
+	}
+
+	/** Builds a kiwix-serve content URL from a href (as returned by list()/search()), or from an already-built content/viewer URL. */
+	link(href) {
+		this.#assertRunning();
+		const {zim, path} = this.#splitHref(href);
+		return `${this.baseUrl}/content/${zim}${path ? '/' + path : ''}`;
+	}
+
+	/** Fetches a single asset's raw bytes straight from kiwix-serve. */
+	async raw(href) {
+		const res = await fetch(this.fetch(href));
+		if (!res.ok) return null;
+		return {mimetype: res.headers.get('content-type'), data: Buffer.from(await res.arrayBuffer())};
+	}
+
+	/**
+	 * Two-pass fulltext search across every local ZIM: xapian prefilter (kiwix-serve's
+	 * own index), then fuzzy-reranked by title so the strongest matches surface first.
+	 * Returns a flat array matching the catalog/list shape: {id, title, name, category, ..., href, score}
+	 */
+	async search(terms, limit = 20) {
+		this.#assertRunning();
+		const termList = String(terms).split(',').map(t => t.trim()).filter(Boolean);
+		if (!termList.length) return [];
+
+		const params = new URLSearchParams({pattern: termList.join(' '), format: 'xml', pageLength: String(limit)});
+		const res = await fetch(`${this.baseUrl}/search?${params}`);
+		if (!res.ok) return [];
+
+		const xml = await res.text();
+		let found = fromXml(xml);
+		found = found?.rss?.channel?.item || [];
+
+		const books = await this.list();
+		const bookMap = new Map(books.map(b => [b.title, b]));
+
+		const enriched = found.map(hit => {
+			const book = bookMap.get(hit.book.title);
+			if(!book) return null;
+			const prefix = `/content/${book.href}/`;
+			const page = hit.link.startsWith(prefix) ? hit.link.slice(prefix.length) : hit.link.replace(/^\/+/, '');
+			return {
+				id: book.id,
+				title: hit.title,
+				page,
+				name: book.name,
+				publisher: book.publisher,
+				href: `${book.href}/${page}`,
+				icon: book.icon,
+				viewer: this.baseUrl + hit.link,
+				summary: hit.description,
+				score: weightedScore(hit.title, termList) + weightedScore(hit.description, termList),
+			};
+		}).filter(hit => !!hit && hit.score > 0);
+
+		return enriched.toSorted((a, b) => b.score - a.score).slice(0, limit);
+	}
+}