@dikolab/kbdb 0.3.0 → 0.3.1

package/src/shared/worker-daemon/constants/wasm-method-map.constant.ts

@@ -0,0 +1,69 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+
+/**
+ * Maps incoming IPC method names to `kb-worker.wasm` export names.
+ *
+ * Both camelCase and snake_case variants of each method are
+ * included so that clients may use either convention.
+ */
+export const WASM_METHOD_MAP: Readonly<
+   Partial<Record<string, string>>
+> = {
+   search: 'worker_search',
+   addSection: 'worker_add_section',
+   add_section: 'worker_add_section',
+   updateSection: 'worker_update_section',
+   update_section: 'worker_update_section',
+   removeSection: 'worker_remove_section',
+   remove_section: 'worker_remove_section',
+   readSections: 'worker_read_sections',
+   read_sections: 'worker_read_sections',
+   groupSections: 'worker_group_sections',
+   group_sections: 'worker_group_sections',
+   removeGrouping: 'worker_remove_grouping',
+   remove_grouping: 'worker_remove_grouping',
+   retrieveDocument: 'worker_retrieve_doc',
+   retrieve_doc: 'worker_retrieve_doc',
+   content: 'worker_compose',
+   compose: 'worker_compose',
+   integrity_check: 'worker_check_integrity',
+   integrityCheck: 'worker_check_integrity',
+   gc: 'worker_garbage_collect',
+   rebuild_indexes: 'worker_rebuild_indexes',
+   rebuildIndexes: 'worker_rebuild_indexes',
+   init_directory: 'worker_init_directory',
+   initDirectory: 'worker_init_directory',
+   migrateDatabase: 'worker_migrate',
+   query: 'worker_query',
+   get_result_status: 'worker_result_status',
+   get_result: 'worker_get_result',
+   invalidate: 'worker_invalidate',
+   invalidate_all: 'worker_invalidate_all',
+   invalidateAll: 'worker_invalidate_all',
+   db_status: 'worker_status',
+   dbStatus: 'worker_status',
+   listByType: 'worker_list_by_type',
+   list_by_type: 'worker_list_by_type',
+   listDocumentsByType: 'worker_list_docs_by_type',
+   list_docs_by_type: 'worker_list_docs_by_type',
+   recall: 'worker_recall',
+   export: 'worker_export',
+   exportDb: 'worker_export',
+};
+
+/** Prefix shared by all IPC config-accessor method names. */
+export const CONFIG_PREFIX = 'config_';
+
+/**
+ * Maps config IPC key suffixes to `DaemonConfig` property names.
+ *
+ * A client sends `config_timeout_ms` to read `config.timeoutMs`.
+ */
+export const CONFIG_KEY_MAP: Readonly<
+   Partial<Record<string, keyof DaemonConfig>>
+> = {
+   timeout_ms: 'timeoutMs',
+   item_ttl_ms: 'itemTtlMs',
+   item_limit: 'itemLimit',
+   index_limit: 'indexLimit',
+};

package/src/shared/worker-daemon/functions/build-ipc-error-response.function.ts

@@ -0,0 +1,16 @@
+import type { IpcResponse } from '../typings/ipc-handler.interface.ts';
+
+/**
+ * Builds a JSON-RPC 2.0 error response object.
+ *
+ * @param id - request identifier to echo back in the response
+ * @param code - JSON-RPC error code
+ * @param message - human-readable error description
+ */
+export function buildIpcErrorResponse(
+   id: number | string,
+   code: number,
+   message: string,
+): IpcResponse {
+   return { jsonrpc: '2.0', id, error: { code, message } };
+}

package/src/shared/worker-daemon/functions/check-catalog-version.function.ts

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DB_FORMAT_VERSION } from '../constants/daemon-defaults.constant.ts';
+import { parseCatalogVersion } from './parse-catalog-version.function.ts';
+
+/**
+ * Reads `catalog.toml` in `targetDir` and validates its version
+ * against `DB_FORMAT_VERSION`.
+ *
+ * @param targetDir - absolute path to the `.kbdb` directory
+ * @throws {Error} when the catalog cannot be read, is missing a
+ *   version, or the version is incompatible with the current engine
+ */
+export function checkCatalogVersion(targetDir: string): void {
+   const catalogPath = join(targetDir, 'catalog.toml');
+   let text: string;
+   try {
+      text = readFileSync(catalogPath, 'utf-8');
+   } catch {
+      throw new Error(
+         `cannot read database directory: ${targetDir}` +
+            ' -- permission denied',
+      );
+   }
+
+   const version = parseCatalogVersion(text);
+   if (version === null) {
+      throw new Error(
+         'database version 0 requires migration to version ' +
+            String(DB_FORMAT_VERSION) +
+            ' -- run `kbdb --migrate` before starting the daemon',
+      );
+   }
+
+   if (version > DB_FORMAT_VERSION) {
+      throw new Error(
+         'database version ' +
+            String(version) +
+            ' is newer than kbdb version ' +
+            String(DB_FORMAT_VERSION) +
+            ' -- upgrade kbdb to open this database',
+      );
+   }
+
+   if (version < DB_FORMAT_VERSION) {
+      throw new Error(
+         'database version ' +
+            String(version) +
+            ' requires migration to version ' +
+            String(DB_FORMAT_VERSION) +
+            ' -- run `kbdb --migrate` before starting the daemon',
+      );
+   }
+}

package/src/shared/worker-daemon/functions/check-preconditions.function.ts

@@ -0,0 +1,28 @@
+import { existsSync, accessSync, constants } from 'node:fs';
+import { checkCatalogVersion } from './check-catalog-version.function.ts';
+
+/**
+ * Validates startup preconditions for the worker daemon.
+ *
+ * Checks that `targetDir` exists, is readable and writable, and
+ * that `catalog.toml` reports a compatible format version.
+ *
+ * @param targetDir - absolute path to the `.kbdb` directory
+ * @throws {Error} when any precondition fails
+ */
+export function checkPreconditions(targetDir: string): void {
+   if (!existsSync(targetDir)) {
+      throw new Error(`database directory not found: ${targetDir}`);
+   }
+
+   try {
+      accessSync(targetDir, constants.R_OK | constants.W_OK);
+   } catch {
+      throw new Error(
+         `cannot access database directory: ${targetDir}` +
+            ' -- permission denied',
+      );
+   }
+
+   checkCatalogVersion(targetDir);
+}

package/src/shared/worker-daemon/functions/detect-stale-pid.function.ts

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { isProcessAlive } from '../../platform/functions/is-process-alive.function.ts';
+
+/**
+ * Checks whether a PID file contains a stale process ID.
+ *
+ * Reads the PID from the file and checks whether the process is
+ * still running using `process.kill(pid, 0)`. If the process is
+ * dead, or the PID is unparseable, removes the PID file and
+ * returns `true`. Returns `false` when the process is alive or
+ * the file does not exist.
+ *
+ * @param pidPath - absolute path to the PID file to inspect
+ * @returns `true` if the PID file is stale (process dead or
+ *   content invalid) and was removed; `false` if the process is
+ *   alive or the file does not exist
+ */
+export function detectStalePid(pidPath: string): boolean {
+   if (!existsSync(pidPath)) return false;
+
+   const pidStr = readFileSync(pidPath, 'utf-8').trim();
+   const pid = parseInt(pidStr, 10);
+   const isAlive = !isNaN(pid) && pid > 0 && isProcessAlive(pid);
+
+   if (isAlive) return false;
+
+   try {
+      unlinkSync(pidPath);
+   } catch {
+      // Best-effort removal; stale file is treated as detected
+   }
+   return true;
+}

package/src/shared/worker-daemon/functions/dispatch-request.function.ts

@@ -0,0 +1,190 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+import type { HandlerContext } from '../typings/handler-context.interface.ts';
+import { IpcError } from '../classes/ipc-error.class.ts';
+import {
+   WASM_METHOD_MAP,
+   CONFIG_PREFIX,
+} from '../constants/wasm-method-map.constant.ts';
+import {
+   handleSearch,
+   handleResultStatus,
+   handleGetResult,
+   handleReadSections,
+   handleRetrieveDoc,
+   handleCompose,
+   handleIntegrityCheck,
+   handleDbStatus,
+   handleListByType,
+   handleListDocsByType,
+   handleRecall,
+   handleExport,
+} from './handle-read-ops.function.ts';
+import {
+   handleAddSection,
+   handleUpdateSection,
+   handleRemoveSection,
+   handleGroupSections,
+   handleRemoveGrouping,
+   handleInitDirectory,
+   handleInvalidate,
+   handleInvalidateAll,
+   handleGc,
+   handleRebuild,
+} from './handle-write-ops.function.ts';
+import { handleCheckVersion } from './handle-check-version.function.ts';
+import { handleConfigMethod } from './handle-config-method.function.ts';
+import {
+   acquireWriteLock,
+   releaseWriteLock,
+} from './write-lock.function.ts';
+import type { WriteLockState } from '../typings/write-lock.interface.ts';
+import { callWasmSync } from './wasm-bridge.function.ts';
+
+/** Daemon status information returned by `status` and `idle_at`. */
+interface DaemonStatus {
+   /** Whether the daemon is currently serving connections. */
+   readonly status: 'busy' | 'idle';
+   /** Whether the startup integrity check passed. */
+   readonly integrityOk: boolean;
+   /** Integrity errors found at startup, if any. */
+   readonly integrityErrors: string[];
+   /** Unix timestamp (seconds) of the last completed request. */
+   readonly idleAt: number;
+}
+
+/**
+ * Dispatches an IPC method to its handler.
+ *
+ * Routes daemon-state methods inline and delegates WASM read/write
+ * operations to their respective handler functions. Write operations
+ * are serialised through the single-writer lock.
+ *
+ * @param method - IPC method name
+ * @param params - request parameters
+ * @param ctx - handler context (WASM modules, config, targetDir)
+ * @param daemonStatus - live daemon state read by the `status` method
+ * @param writeLock - shared write-lock state
+ */
+export async function dispatchRequest(
+   method: string,
+   params: Record<string, unknown>,
+   ctx: HandlerContext,
+   daemonStatus: DaemonStatus,
+   writeLock: WriteLockState,
+): Promise<unknown> {
+   if (method === 'status') {
+      return {
+         status: daemonStatus.status,
+         integrityOk: daemonStatus.integrityOk,
+         integrityErrors: daemonStatus.integrityErrors,
+      };
+   }
+   if (method === 'idle_at') return daemonStatus.idleAt;
+   if (method === 'checkVersion') {
+      return handleCheckVersion(params, ctx.targetDir);
+   }
+   if (method.startsWith(CONFIG_PREFIX)) {
+      return handleConfigMethod(method, ctx.config);
+   }
+
+   const wasmMethod = WASM_METHOD_MAP[method];
+   if (wasmMethod === undefined) {
+      throw new IpcError(-32601, `Method not found: ${method}`);
+   }
+   return dispatchWasm(method, wasmMethod, params, ctx, writeLock);
+}
+
+async function dispatchWasm(
+   method: string,
+   wasmExport: string,
+   params: Record<string, unknown>,
+   ctx: HandlerContext,
+   writeLock: WriteLockState,
+): Promise<unknown> {
+   // Read-only operations -- no write lock required.
+   if (method === 'search' || method === 'query') {
+      return handleSearch(ctx, params);
+   }
+   if (method === 'readSections' || method === 'read_sections') {
+      return handleReadSections(ctx, params);
+   }
+   if (method === 'retrieveDocument' || method === 'retrieve_doc') {
+      return handleRetrieveDoc(ctx, params);
+   }
+   if (method === 'content' || method === 'compose') {
+      return handleCompose(ctx, params);
+   }
+   if (method === 'integrityCheck' || method === 'integrity_check') {
+      return handleIntegrityCheck(ctx);
+   }
+   if (method === 'dbStatus' || method === 'db_status') {
+      return handleDbStatus(ctx);
+   }
+   if (method === 'get_result_status') {
+      return handleResultStatus(ctx, params);
+   }
+   if (method === 'get_result') {
+      return handleGetResult(ctx, params);
+   }
+   if (method === 'listByType' || method === 'list_by_type') {
+      return handleListByType(ctx, params);
+   }
+   if (
+      method === 'listDocumentsByType' ||
+      method === 'list_docs_by_type'
+   ) {
+      return handleListDocsByType(ctx, params);
+   }
+   if (method === 'recall') return handleRecall(ctx, params);
+   if (method === 'export' || method === 'exportDb') {
+      return handleExport(ctx, params);
+   }
+
+   // Write operations -- serialised through the single-writer lock.
+   await acquireWriteLock(writeLock);
+   try {
+      if (method === 'invalidate') return handleInvalidate(ctx, params);
+      if (method === 'invalidateAll' || method === 'invalidate_all') {
+         return handleInvalidateAll(ctx);
+      }
+      if (method === 'addSection' || method === 'add_section') {
+         return handleAddSection(ctx, params);
+      }
+      if (method === 'updateSection' || method === 'update_section') {
+         return handleUpdateSection(ctx, params);
+      }
+      if (method === 'removeSection' || method === 'remove_section') {
+         return handleRemoveSection(ctx, params);
+      }
+      if (method === 'groupSections' || method === 'group_sections') {
+         return handleGroupSections(ctx, params);
+      }
+      if (method === 'removeGrouping' || method === 'remove_grouping') {
+         return handleRemoveGrouping(ctx, params);
+      }
+      if (method === 'gc') return handleGc(ctx);
+      if (method === 'rebuildIndexes' || method === 'rebuild_indexes') {
+         return handleRebuild(ctx);
+      }
+      if (method === 'initDirectory' || method === 'init_directory') {
+         return handleInitDirectory(ctx, params);
+      }
+      if (method === 'migrateDatabase') {
+         throw new IpcError(
+            -32601,
+            'migrateDatabase is not yet supported',
+         );
+      }
+      return callWasmSync(ctx.modules, wasmExport, new Uint8Array(0));
+   } finally {
+      releaseWriteLock(writeLock);
+   }
+}
+
+/**
+ * Re-export `DaemonConfig` so callers can pass strongly-typed
+ * config without an extra import.
+ *
+ * @internal
+ */
+export type { DaemonConfig };

package/src/shared/worker-daemon/functions/handle-check-version.function.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DB_FORMAT_VERSION } from '../constants/daemon-defaults.constant.ts';
+import { parseCatalogVersion } from './parse-catalog-version.function.ts';
+
+/** Payload returned by the `checkVersion` IPC method. */
+interface VersionCheckResult {
+   /** Compatibility status string. */
+   readonly status: string;
+   /** Format version stored in the catalog. */
+   readonly currentVersion: number;
+   /** Format version required by the current engine. */
+   readonly requiredVersion: number;
+}
+
+/**
+ * Handles the `checkVersion` IPC method.
+ *
+ * Reads `catalog.toml` at `targetPath` and compares its format
+ * version to `DB_FORMAT_VERSION`. Returns a result object without
+ * making any modifications.
+ *
+ * @param targetPath - absolute path to the `.kbdb` directory to
+ *   inspect; falls back to `defaultDir` when not provided in params
+ * @param defaultDir - fallback directory when `params.targetPath`
+ *   is absent
+ */
+export function handleCheckVersion(
+   params: Record<string, unknown>,
+   defaultDir: string,
+): VersionCheckResult {
+   const targetPath =
+      typeof params['targetPath'] === 'string'
+         ? params['targetPath']
+         : defaultDir;
+   const catalogPath = join(targetPath, 'catalog.toml');
+   let text: string;
+   try {
+      text = readFileSync(catalogPath, 'utf-8');
+   } catch {
+      return {
+         status: 'needs_migration',
+         currentVersion: 0,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   const version = parseCatalogVersion(text);
+   if (version === null) {
+      return {
+         status: 'needs_migration',
+         currentVersion: 0,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   if (version > DB_FORMAT_VERSION) {
+      return {
+         status: 'too_new',
+         currentVersion: version,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   if (version < DB_FORMAT_VERSION) {
+      return {
+         status: 'needs_migration',
+         currentVersion: version,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   return {
+      status: 'compatible',
+      currentVersion: version,
+      requiredVersion: DB_FORMAT_VERSION,
+   };
+}

package/src/shared/worker-daemon/functions/handle-config-method.function.ts

@@ -0,0 +1,27 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+import { IpcError } from '../classes/ipc-error.class.ts';
+import {
+   CONFIG_PREFIX,
+   CONFIG_KEY_MAP,
+} from '../constants/wasm-method-map.constant.ts';
+
+/**
+ * Handles `config_{key}` IPC methods by returning the corresponding
+ * `DaemonConfig` field value.
+ *
+ * @param method - the full method name, e.g. `config_timeout_ms`
+ * @param config - parsed daemon configuration
+ * @throws {IpcError} with code `-32601` when the key suffix is not
+ *   in `CONFIG_KEY_MAP`
+ */
+export function handleConfigMethod(
+   method: string,
+   config: DaemonConfig,
+): unknown {
+   const key = method.slice(CONFIG_PREFIX.length);
+   const prop = CONFIG_KEY_MAP[key];
+   if (prop === undefined) {
+      throw new IpcError(-32601, `Method not found: ${method}`);
+   }
+   return config[prop];
+}