@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,190 +0,0 @@
-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

@@ -1,74 +0,0 @@
-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

@@ -1,27 +0,0 @@
-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];
-}

package/src/shared/worker-daemon/functions/handle-read-ops.function.ts

@@ -1,236 +0,0 @@
-import {
-   encodeSearchParams,
-   encodeKbidList,
-   encodeIdentifierList,
-   encodeTypeFilterParam,
-   encodeRecallParams,
-   decodePagedSearchResult,
-   decodeSectionRecords,
-   decodeSectionRecordList,
-   decodeDocumentManifest,
-   decodeDocumentManifestList,
-   decodeComposeOutput,
-   decodeKeyValueText,
-   decodeRecallResult,
-} from '../../wasm-codec/index.ts';
-import type { HandlerContext } from '../typings/handler-context.interface.ts';
-import { IpcError } from '../classes/ipc-error.class.ts';
-import {
-   getWasmExport,
-   wasmAlloc,
-   wasmWrite,
-   wasmFree,
-   readReturnSlot,
-   callWasmSync,
-   callWasmZeroArg,
-} from './wasm-bridge.function.ts';
-
-/**
- * Handles `search` and `query` IPC methods.
- *
- * Encodes parameters, invokes the `worker_search` token pipeline,
- * waits synchronously for the result, and decodes the paged result.
- */
-export function handleSearch(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const query = (params['query'] as string | undefined) ?? '';
-   const mode = (params['mode'] as string | undefined) ?? 'and';
-   const limit = Number(params['limit'] ?? 20);
-   const offset = Number(params['offset'] ?? 0);
-   const encoded = encodeSearchParams(query, mode, limit, offset);
-
-   const searchFn = getWasmExport(ctx.modules, 'worker_search');
-   const ptr = wasmAlloc(ctx.modules, encoded.length);
-   wasmWrite(ctx.modules, ptr, encoded);
-   const token = searchFn(ptr, encoded.length) as number;
-   wasmFree(ctx.modules, ptr, encoded.length);
-
-   const statusFn = getWasmExport(ctx.modules, 'worker_result_status');
-   const status = statusFn(token) as number;
-   if (status === 3) {
-      getWasmExport(ctx.modules, 'worker_get_result')(token);
-      const errBytes = readReturnSlot(ctx.modules);
-      throw new IpcError(-32000, new TextDecoder().decode(errBytes));
-   }
-
-   const getResultFn = getWasmExport(ctx.modules, 'worker_get_result');
-   const rc = getResultFn(token) as number;
-   if (rc === -1) {
-      const errBytes = readReturnSlot(ctx.modules);
-      throw new IpcError(-32000, new TextDecoder().decode(errBytes));
-   }
-   return decodePagedSearchResult(readReturnSlot(ctx.modules));
-}
-
-/**
- * Handles the `get_result_status` IPC method.
- */
-export function handleResultStatus(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const token = Number(params['token'] ?? 0);
-   const fn = getWasmExport(ctx.modules, 'worker_result_status');
-   return { status: fn(token) as number };
-}
-
-/**
- * Handles the `get_result` IPC method.
- */
-export function handleGetResult(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const token = Number(params['token'] ?? 0);
-   const fn = getWasmExport(ctx.modules, 'worker_get_result');
-   const rc = fn(token) as number;
-   if (rc === -1) {
-      const errBytes = readReturnSlot(ctx.modules);
-      throw new IpcError(-32000, new TextDecoder().decode(errBytes));
-   }
-   return decodePagedSearchResult(readReturnSlot(ctx.modules));
-}
-
-/**
- * Handles the `readSections` IPC method.
- */
-export function handleReadSections(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const kbids = (params['kbids'] ?? []) as string[];
-   const encoded = encodeKbidList(kbids);
-   const bytes = callWasmSync(
-      ctx.modules,
-      'worker_read_sections',
-      encoded,
-   );
-   return decodeSectionRecords(bytes);
-}
-
-/**
- * Handles the `retrieveDocument` IPC method.
- */
-export function handleRetrieveDoc(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const docid = (params['docid'] as string | undefined) ?? '';
-   const encoded = new TextEncoder().encode(docid);
-   const bytes = callWasmSync(
-      ctx.modules,
-      'worker_retrieve_doc',
-      encoded,
-   );
-   return decodeDocumentManifest(bytes);
-}
-
-/**
- * Handles the `content` and `compose` IPC methods.
- */
-export function handleCompose(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const ids = (params['ids'] ?? []) as string[];
-   const encoded = encodeIdentifierList(ids);
-   const bytes = callWasmSync(ctx.modules, 'worker_compose', encoded);
-   const output = decodeComposeOutput(bytes);
-   return { data: output.markdown, total: Number(output.totalChars) };
-}
-
-/**
- * Handles the `integrityCheck` IPC method.
- */
-export function handleIntegrityCheck(ctx: HandlerContext): unknown {
-   callWasmZeroArg(ctx.modules, 'worker_check_integrity');
-   const bytes = readReturnSlot(ctx.modules);
-   return decodeKeyValueText(new TextDecoder().decode(bytes));
-}
-
-/**
- * Handles the `dbStatus` IPC method.
- */
-export function handleDbStatus(ctx: HandlerContext): unknown {
-   callWasmZeroArg(ctx.modules, 'worker_status');
-   const bytes = readReturnSlot(ctx.modules);
-   return decodeKeyValueText(new TextDecoder().decode(bytes));
-}
-
-/**
- * Handles the `listByType` IPC method.
- */
-export function handleListByType(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const typeStr = (params['sectionType'] as string | undefined) ?? '';
-   const encoded = encodeTypeFilterParam(typeStr);
-   const bytes = callWasmSync(
-      ctx.modules,
-      'worker_list_by_type',
-      encoded,
-   );
-   return decodeSectionRecordList(bytes);
-}
-
-/**
- * Handles the `listDocumentsByType` IPC method.
- */
-export function handleListDocsByType(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const typeStr = (params['docType'] as string | undefined) ?? '';
-   const encoded = encodeTypeFilterParam(typeStr);
-   const bytes = callWasmSync(
-      ctx.modules,
-      'worker_list_docs_by_type',
-      encoded,
-   );
-   return decodeDocumentManifestList(bytes);
-}
-
-/**
- * Handles the `recall` IPC method.
- */
-export function handleRecall(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const kbid =
-      typeof params['kbid'] === 'string' ? params['kbid'] : undefined;
-   const kbids = Array.isArray(params['kbids'])
-      ? (params['kbids'] as string[])
-      : undefined;
-   const depth = Number(params['depth'] ?? 0);
-   const encoded = encodeRecallParams({ kbid, kbids, depth });
-   const bytes = callWasmSync(ctx.modules, 'worker_recall', encoded);
-   return decodeRecallResult(bytes);
-}
-
-/**
- * Handles the `export` and `exportDb` IPC methods.
- */
-export function handleExport(
-   ctx: HandlerContext,
-   params: Record<string, unknown>,
-): unknown {
-   const targetPath =
-      (params['targetPath'] as string | undefined) ??
-      (params['path'] as string | undefined) ??
-      './kbdb-export/';
-   const encoded = new TextEncoder().encode(targetPath);
-   const start = Date.now();
-   const bytes = callWasmSync(ctx.modules, 'worker_export', encoded);
-   const elapsed = Date.now() - start;
-   const kv = decodeKeyValueText(new TextDecoder().decode(bytes));
-   return {
-      path: kv['path'] ?? targetPath,
-      sections_exported: Number(kv['sections_exported'] ?? 0),
-      documents_exported: Number(kv['documents_exported'] ?? 0),
-      elapsed_ms: elapsed,
-   };
-}