@delali/narsil 0.1.6 → 0.1.8

package/dist/server.mjs

@@ -0,0 +1,1185 @@
+import { NarsilError, ErrorCodes } from './chunk-ALB35PRQ.mjs';
+import { randomUUID } from 'crypto';
+
+// src/server/cors.ts
+function resolveCors(cors) {
+  if (!cors) return null;
+  if (cors === true) {
+    return { origin: "*", methods: "GET, POST, PUT, PATCH, DELETE, OPTIONS", headers: "Content-Type, Authorization" };
+  }
+  return {
+    origin: cors.origin ?? "*",
+    methods: cors.methods?.join(", ") ?? "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+    headers: cors.headers?.join(", ") ?? "Content-Type, Authorization"
+  };
+}
+function matchOrigin(cors, requestOrigin) {
+  if (cors.origin === "*") return "*";
+  if (typeof cors.origin === "string") return cors.origin;
+  return cors.origin.includes(requestOrigin) ? requestOrigin : null;
+}
+function writeCorsOrigin(res, cors, requestOrigin) {
+  const allowed = matchOrigin(cors, requestOrigin);
+  if (!allowed) return;
+  res.writeHeader("Access-Control-Allow-Origin", allowed);
+  if (allowed !== "*") res.writeHeader("Vary", "Origin");
+}
+function corsWriter(cors) {
+  return (res, req) => writeCorsOrigin(res, cors, req.getHeader("origin"));
+}
+
+// src/server/errors.ts
+var ServerErrorCodes = {
+  INVALID_REQUEST: "INVALID_REQUEST",
+  INVALID_JSON: "INVALID_JSON",
+  EMPTY_BODY: "EMPTY_BODY",
+  PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+  UNSUPPORTED_MEDIA_TYPE: "UNSUPPORTED_MEDIA_TYPE",
+  NOT_FOUND: "NOT_FOUND",
+  TASK_NOT_FOUND: "TASK_NOT_FOUND",
+  TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS",
+  HOOK_ERROR: "HOOK_ERROR",
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  REQUEST_ABORTED: "REQUEST_ABORTED"
+};
+var STATUS_BY_CODE = {
+  SCHEMA_INVALID_TYPE: 400,
+  SCHEMA_MISSING_FIELD: 400,
+  SCHEMA_DEPTH_EXCEEDED: 400,
+  SCHEMA_INVALID_VECTOR_DIMENSION: 400,
+  SCHEMA_INVALID_GEOPOINT: 400,
+  DOC_VALIDATION_FAILED: 400,
+  DOC_MISSING_REQUIRED_FIELD: 400,
+  SEARCH_INVALID_FIELD: 400,
+  SEARCH_INVALID_VECTOR_SIZE: 400,
+  VECTOR_DIMENSION_MISMATCH: 400,
+  SEARCH_INVALID_FILTER: 400,
+  SEARCH_INVALID_MODE: 400,
+  SEARCH_INVALID_CURSOR: 400,
+  LANGUAGE_NOT_SUPPORTED: 400,
+  CONFIG_INVALID: 400,
+  EMBEDDING_DIMENSION_MISMATCH: 400,
+  EMBEDDING_NO_SOURCE: 400,
+  EMBEDDING_CONFIG_INVALID: 400,
+  INDEX_NOT_FOUND: 404,
+  DOC_NOT_FOUND: 404,
+  INDEX_ALREADY_EXISTS: 409,
+  DOC_ALREADY_EXISTS: 409,
+  PARTITION_REBALANCING_BACKPRESSURE: 409,
+  PARTITION_CAPACITY_EXCEEDED: 409,
+  WORKER_BUSY: 429,
+  PARTITION_CORRUPTED: 503,
+  WORKER_CRASHED: 503,
+  WORKER_TIMEOUT: 503,
+  PERSISTENCE_SAVE_FAILED: 503,
+  PERSISTENCE_LOAD_FAILED: 503,
+  PERSISTENCE_DELETE_FAILED: 503,
+  PERSISTENCE_CRC_MISMATCH: 503,
+  PERSISTENCE_WAL_CORRUPT: 503,
+  PERSISTENCE_FSYNC_FAILED: 503,
+  EMBEDDING_FAILED: 503,
+  QUERY_ROUTING_FAILED: 503,
+  QUERY_PARTIAL_FAILURE: 503,
+  QUERY_NODE_TIMEOUT: 503,
+  QUERY_NO_ACTIVE_REPLICA: 503
+};
+function httpStatusForNarsilError(code) {
+  return STATUS_BY_CODE[code] ?? 500;
+}
+function serializeNarsilError(err) {
+  const hasDetails = err.details && Object.keys(err.details).length > 0;
+  return hasDetails ? { code: err.code, message: err.message, details: err.details } : { code: err.code, message: err.message };
+}
+function toHttpError(err) {
+  if (err instanceof NarsilError) {
+    return { status: httpStatusForNarsilError(err.code), body: serializeNarsilError(err) };
+  }
+  return {
+    status: 500,
+    body: { code: ServerErrorCodes.INTERNAL_ERROR, message: "An unexpected error occurred" }
+  };
+}
+
+// src/server/response.ts
+var STATUS_TEXT = {
+  200: "200 OK",
+  201: "201 Created",
+  202: "202 Accepted",
+  204: "204 No Content",
+  400: "400 Bad Request",
+  401: "401 Unauthorized",
+  403: "403 Forbidden",
+  404: "404 Not Found",
+  405: "405 Method Not Allowed",
+  409: "409 Conflict",
+  413: "413 Payload Too Large",
+  415: "415 Unsupported Media Type",
+  429: "429 Too Many Requests",
+  500: "500 Internal Server Error",
+  503: "503 Service Unavailable"
+};
+function statusLine(status) {
+  return STATUS_TEXT[status] ?? `${status}`;
+}
+function sendJson(res, data, status = 200) {
+  const payload = JSON.stringify(data);
+  res.cork(() => {
+    res.writeStatus(statusLine(status)).writeHeader("Content-Type", "application/json").end(payload);
+  });
+}
+function sendError(res, status, code, message, details) {
+  const body = { error: details ? { code, message, details } : { code, message } };
+  const payload = JSON.stringify(body);
+  res.cork(() => {
+    res.writeStatus(statusLine(status)).writeHeader("Content-Type", "application/json").end(payload);
+  });
+}
+function sendBinary(res, data, status = 200) {
+  res.cork(() => {
+    res.writeStatus(statusLine(status)).writeHeader("Content-Type", "application/octet-stream").end(data);
+  });
+}
+
+// src/server/handler-utils.ts
+function parseJson(ctx) {
+  const raw = ctx.rawBody;
+  if (!raw || raw.length === 0) {
+    sendError(ctx.res, 400, ServerErrorCodes.EMPTY_BODY, "Request body is empty");
+    return void 0;
+  }
+  try {
+    return JSON.parse(raw.toString("utf8"));
+  } catch {
+    sendError(ctx.res, 400, ServerErrorCodes.INVALID_JSON, "Request body is not valid JSON");
+    return void 0;
+  }
+}
+function parseJsonOptional(ctx) {
+  const raw = ctx.rawBody;
+  if (!raw || raw.length === 0) return {};
+  try {
+    return JSON.parse(raw.toString("utf8"));
+  } catch {
+    sendError(ctx.res, 400, ServerErrorCodes.INVALID_JSON, "Request body is not valid JSON");
+    return void 0;
+  }
+}
+function respondError(ctx, err) {
+  if (ctx.abort.aborted) return;
+  const { status, body } = toHttpError(err);
+  sendError(ctx.res, status, body.code, body.message, body.details);
+}
+function respondJson(ctx, data, status = 200) {
+  if (ctx.abort.aborted) return;
+  sendJson(ctx.res, data, status);
+}
+function badRequest(res, message, details) {
+  sendError(res, 400, ServerErrorCodes.INVALID_REQUEST, message, details);
+}
+function serializeBatchResult(result) {
+  return {
+    succeeded: result.succeeded,
+    failed: result.failed.map((f) => ({
+      docId: f.docId,
+      error: f.error instanceof NarsilError ? serializeNarsilError(f.error) : { code: "INTERNAL_ERROR", message: String(f.error) }
+    }))
+  };
+}
+
+// src/server/handlers/admin.ts
+function taskResponse(record) {
+  return { taskId: record.id, type: record.type, status: record.status };
+}
+function createAdminHandlers(deps) {
+  const { engine, tasks } = deps;
+  async function checkpoint(ctx) {
+    try {
+      await engine.checkpoint(ctx.params[0]);
+      respondJson(ctx, { ok: true });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function snapshot(ctx) {
+    try {
+      const bytes = await engine.snapshot(ctx.params[0]);
+      if (ctx.abort.aborted) return;
+      sendBinary(ctx.res, bytes);
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  function vectorMaintenance(ctx) {
+    try {
+      respondJson(ctx, { fields: engine.vectorMaintenanceStatus(ctx.params[0]) });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function compact(ctx) {
+    const body = parseJsonOptional(ctx);
+    if (!body) return;
+    try {
+      await engine.compactVectors(ctx.params[0], body.field);
+      respondJson(ctx, { ok: true });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function partitionConfig(ctx) {
+    const body = parseJsonOptional(ctx);
+    if (!body) return;
+    try {
+      await engine.updatePartitionConfig(ctx.params[0], body);
+      respondJson(ctx, { ok: true });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function memory(ctx) {
+    try {
+      respondJson(ctx, await engine.getMemoryStats());
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  function requireIndexExists(name) {
+    engine.getStats(name);
+  }
+  async function optimize(ctx) {
+    const body = parseJsonOptional(ctx);
+    if (!body) return;
+    const name = ctx.params[0];
+    try {
+      requireIndexExists(name);
+    } catch (err) {
+      respondError(ctx, err);
+      return;
+    }
+    const record = await tasks.start("optimizeVectors", name, () => engine.optimizeVectors(name, body.field));
+    respondJson(ctx, taskResponse(record), 202);
+  }
+  async function rebalance(ctx) {
+    const body = parseJsonOptional(ctx);
+    if (!body) return;
+    const target = body.targetPartitionCount;
+    if (typeof target !== "number" || !Number.isInteger(target) || target <= 0) {
+      badRequest(ctx.res, 'Field "targetPartitionCount" is required and must be a positive integer');
+      return;
+    }
+    const name = ctx.params[0];
+    try {
+      requireIndexExists(name);
+    } catch (err) {
+      respondError(ctx, err);
+      return;
+    }
+    const record = await tasks.start("rebalance", name, () => engine.rebalance(name, target));
+    respondJson(ctx, taskResponse(record), 202);
+  }
+  async function restore(ctx) {
+    const raw = ctx.rawBody;
+    if (!raw || raw.length === 0) {
+      sendError(ctx.res, 400, ServerErrorCodes.EMPTY_BODY, "Request body is empty");
+      return;
+    }
+    const name = ctx.params[0];
+    const bytes = new Uint8Array(raw);
+    const record = await tasks.start("restore", name, () => engine.restore(name, bytes));
+    respondJson(ctx, taskResponse(record), 202);
+  }
+  async function getTask(ctx) {
+    const record = await tasks.get(ctx.params[0]);
+    if (!record) {
+      sendError(ctx.res, 404, ServerErrorCodes.TASK_NOT_FOUND, `Task "${ctx.params[0]}" not found`);
+      return;
+    }
+    respondJson(ctx, record);
+  }
+  async function listTasks(ctx) {
+    respondJson(ctx, { tasks: await tasks.list() });
+  }
+  return {
+    checkpoint,
+    snapshot,
+    vectorMaintenance,
+    compact,
+    partitionConfig,
+    memory,
+    optimize,
+    rebalance,
+    restore,
+    getTask,
+    listTasks
+  };
+}
+
+// src/server/handlers/documents.ts
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function createDocumentHandlers(deps) {
+  const { engine } = deps;
+  async function insert(ctx) {
+    const body = parseJson(ctx);
+    if (!body) return;
+    if (!isPlainObject(body.document)) {
+      badRequest(ctx.res, 'Field "document" is required and must be an object');
+      return;
+    }
+    try {
+      const id = await engine.insert(ctx.params[0], body.document, body.id, body.options);
+      respondJson(ctx, { id }, 201);
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function get(ctx) {
+    try {
+      const document = await engine.get(ctx.params[0], ctx.params[1]);
+      if (document === void 0) {
+        respondError(ctx, indexDocNotFound(ctx.params[1]));
+        return;
+      }
+      respondJson(ctx, { document });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function exists(ctx) {
+    try {
+      respondJson(ctx, { exists: await engine.has(ctx.params[0], ctx.params[1]) });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function put(ctx) {
+    const body = parseJson(ctx);
+    if (!body) return;
+    if (!isPlainObject(body.document)) {
+      badRequest(ctx.res, 'Field "document" is required and must be an object');
+      return;
+    }
+    const [name, id] = ctx.params;
+    try {
+      if (await engine.has(name, id)) {
+        await engine.update(name, id, body.document);
+        respondJson(ctx, { id, created: false });
+      } else {
+        const created = await engine.insert(name, body.document, id);
+        respondJson(ctx, { id: created, created: true }, 201);
+      }
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function patch(ctx) {
+    const body = parseJson(ctx);
+    if (!body) return;
+    if (!isPlainObject(body.document)) {
+      badRequest(ctx.res, 'Field "document" is required and must be an object');
+      return;
+    }
+    try {
+      await engine.update(ctx.params[0], ctx.params[1], body.document);
+      respondJson(ctx, { id: ctx.params[1] });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function remove(ctx) {
+    try {
+      await engine.remove(ctx.params[0], ctx.params[1]);
+      respondJson(ctx, { id: ctx.params[1], removed: true });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function count(ctx) {
+    try {
+      respondJson(ctx, { count: await engine.countDocuments(ctx.params[0]) });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function multiGet(ctx) {
+    const body = parseJson(ctx);
+    if (!body) return;
+    if (!Array.isArray(body.docIds)) {
+      badRequest(ctx.res, 'Field "docIds" is required and must be an array of strings');
+      return;
+    }
+    try {
+      const found = await engine.getMultiple(ctx.params[0], body.docIds);
+      const documents = {};
+      for (const [id, doc] of found) documents[id] = doc;
+      respondJson(ctx, { documents });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function batch(ctx) {
+    const body = parseJson(ctx);
+    if (!body) return;
+    const action = body.action ?? "insert";
+    try {
+      if (action === "insert") {
+        if (!Array.isArray(body.documents)) {
+          badRequest(ctx.res, 'Batch insert requires a "documents" array');
+          return;
+        }
+        respondJson(ctx, serializeBatchResult(await engine.insertBatch(ctx.params[0], body.documents, body.options)));
+      } else if (action === "update") {
+        if (!Array.isArray(body.updates)) {
+          badRequest(ctx.res, 'Batch update requires an "updates" array');
+          return;
+        }
+        respondJson(ctx, serializeBatchResult(await engine.updateBatch(ctx.params[0], body.updates)));
+      } else if (action === "delete") {
+        if (!Array.isArray(body.docIds)) {
+          badRequest(ctx.res, 'Batch delete requires a "docIds" array');
+          return;
+        }
+        respondJson(ctx, serializeBatchResult(await engine.removeBatch(ctx.params[0], body.docIds)));
+      } else {
+        badRequest(ctx.res, 'Field "action" must be one of "insert", "update", or "delete"');
+      }
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  return { insert, get, exists, put, patch, remove, count, multiGet, batch };
+}
+function indexDocNotFound(docId) {
+  return new NarsilError(ErrorCodes.DOC_NOT_FOUND, `Document "${docId}" not found`, { docId });
+}
+
+// src/server/handlers/health.ts
+function createHealthHandlers(deps) {
+  function livez(ctx) {
+    respondJson(ctx, { status: "ok" });
+  }
+  function readyz(ctx) {
+    if (deps.isReady()) {
+      respondJson(ctx, { status: "ready" });
+    } else {
+      respondJson(ctx, { status: "unavailable" }, 503);
+    }
+  }
+  return { livez, readyz };
+}
+
+// src/server/ndjson.ts
+var NEWLINE = 10;
+var CARRIAGE_RETURN = 13;
+var NdjsonLineTooLongError = class extends Error {
+  constructor(lineNumber) {
+    super(`NDJSON line ${lineNumber} exceeds the configured per-line size limit`);
+    this.lineNumber = lineNumber;
+    this.name = "NdjsonLineTooLongError";
+  }
+};
+function* iterateNdjson(buffer, maxLineBytes) {
+  let start = 0;
+  let lineNumber = 0;
+  const length = buffer.length;
+  while (start < length) {
+    let end = buffer.indexOf(NEWLINE, start);
+    if (end === -1) end = length;
+    if (end - start > maxLineBytes) throw new NdjsonLineTooLongError(lineNumber + 1);
+    let contentEnd = end;
+    if (contentEnd > start && buffer[contentEnd - 1] === CARRIAGE_RETURN) contentEnd--;
+    if (contentEnd > start) {
+      lineNumber++;
+      yield { lineNumber, text: buffer.toString("utf8", start, contentEnd) };
+    }
+    start = end + 1;
+  }
+}
+
+// src/server/handlers/import.ts
+function yieldToEventLoop() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function createImportHandler(deps) {
+  const { engine, limits } = deps;
+  return async function importNdjson(ctx) {
+    const raw = ctx.rawBody;
+    if (!raw || raw.length === 0) {
+      sendError(ctx.res, 400, ServerErrorCodes.EMPTY_BODY, "Request body is empty");
+      return;
+    }
+    const name = ctx.params[0];
+    const errors = [];
+    let indexed = 0;
+    let pending = [];
+    const flush = async () => {
+      if (pending.length === 0) return true;
+      const documents = pending.map((p) => p.document);
+      try {
+        const result = await engine.insertBatch(name, documents);
+        indexed += result.succeeded.length;
+        for (const failure of result.failed) {
+          const serialized = failure.error instanceof NarsilError ? serializeNarsilError(failure.error) : { code: "INTERNAL_ERROR", message: String(failure.error) };
+          errors.push({ docId: failure.docId, code: serialized.code, message: serialized.message });
+        }
+        pending = [];
+        return true;
+      } catch (err) {
+        respondError(ctx, err);
+        return false;
+      }
+    };
+    try {
+      for (const { lineNumber, text } of iterateNdjson(raw, limits.maxLineBytes)) {
+        let parsed;
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          errors.push({ line: lineNumber, code: ServerErrorCodes.INVALID_JSON, message: "Line is not valid JSON" });
+          continue;
+        }
+        if (!isPlainObject2(parsed)) {
+          errors.push({
+            line: lineNumber,
+            code: ServerErrorCodes.INVALID_REQUEST,
+            message: "Line is not a JSON object"
+          });
+          continue;
+        }
+        pending.push({ document: parsed, line: lineNumber });
+        if (pending.length >= limits.importBatchSize) {
+          if (!await flush()) return;
+          if (ctx.abort.aborted) return;
+          await yieldToEventLoop();
+          if (ctx.abort.aborted) return;
+        }
+      }
+    } catch (err) {
+      if (err instanceof NdjsonLineTooLongError) {
+        sendError(ctx.res, 413, ServerErrorCodes.PAYLOAD_TOO_LARGE, err.message, { line: err.lineNumber });
+        return;
+      }
+      respondError(ctx, err);
+      return;
+    }
+    if (!await flush()) return;
+    if (ctx.abort.aborted) return;
+    respondJson(ctx, { indexed, failed: errors.length, errors });
+  };
+}
+
+// src/server/config-mapping.ts
+function mapHttpIndexConfig(http, adapters) {
+  if (typeof http !== "object" || http === null) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "Index config must be an object");
+  }
+  if (typeof http.schema !== "object" || http.schema === null || Array.isArray(http.schema)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, 'Index config requires a "schema" object');
+  }
+  const config = { schema: http.schema };
+  if (http.language !== void 0) config.language = http.language;
+  if (http.partitions !== void 0) config.partitions = http.partitions;
+  if (http.defaultScoring !== void 0) config.defaultScoring = http.defaultScoring;
+  if (http.bm25 !== void 0) config.bm25 = http.bm25;
+  if (http.trackPositions !== void 0) config.trackPositions = http.trackPositions;
+  if (http.vectorPromotion !== void 0) config.vectorPromotion = http.vectorPromotion;
+  if (http.strict !== void 0) config.strict = http.strict;
+  if (http.required !== void 0) config.required = http.required;
+  if (http.stopWords !== void 0) {
+    if (!Array.isArray(http.stopWords) || http.stopWords.some((w) => typeof w !== "string")) {
+      throw new NarsilError(ErrorCodes.CONFIG_INVALID, 'Field "stopWords" must be an array of strings');
+    }
+    config.stopWords = new Set(http.stopWords);
+  }
+  if (http.embedding !== void 0) {
+    config.embedding = mapEmbedding(http.embedding, adapters);
+  }
+  return config;
+}
+function mapEmbedding(embedding, adapters) {
+  if (typeof embedding !== "object" || embedding === null) {
+    throw new NarsilError(ErrorCodes.EMBEDDING_CONFIG_INVALID, 'Field "embedding" must be an object');
+  }
+  if (typeof embedding.fields !== "object" || embedding.fields === null) {
+    throw new NarsilError(ErrorCodes.EMBEDDING_CONFIG_INVALID, 'Field "embedding.fields" is required');
+  }
+  const mapped = { fields: embedding.fields };
+  if (embedding.adapter !== void 0) {
+    const adapter = adapters[embedding.adapter];
+    if (!adapter) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_CONFIG_INVALID,
+        `Embedding adapter "${embedding.adapter}" is not registered on this server`,
+        { available: Object.keys(adapters) }
+      );
+    }
+    mapped.adapter = adapter;
+  }
+  return mapped;
+}
+
+// src/server/handlers/indexes.ts
+function createIndexHandlers(deps) {
+  const { engine, adapters } = deps;
+  async function create(ctx) {
+    const body = parseJson(ctx);
+    if (!body) return;
+    if (typeof body.name !== "string" || body.name.length === 0) {
+      badRequest(ctx.res, 'Field "name" is required and must be a non-empty string');
+      return;
+    }
+    if (typeof body.config !== "object" || body.config === null) {
+      badRequest(ctx.res, 'Field "config" is required and must be an object');
+      return;
+    }
+    try {
+      const config = mapHttpIndexConfig(body.config, adapters);
+      await engine.createIndex(body.name, config);
+      respondJson(ctx, { name: body.name }, 201);
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  function list(ctx) {
+    try {
+      respondJson(ctx, { indexes: engine.listIndexes() });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function drop(ctx) {
+    try {
+      await engine.dropIndex(ctx.params[0]);
+      respondJson(ctx, { name: ctx.params[0], dropped: true });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  function stats(ctx) {
+    try {
+      respondJson(ctx, engine.getStats(ctx.params[0]));
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  function partitions(ctx) {
+    try {
+      respondJson(ctx, { partitions: engine.getPartitionStats(ctx.params[0]) });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function clear(ctx) {
+    try {
+      await engine.clear(ctx.params[0]);
+      respondJson(ctx, { name: ctx.params[0], cleared: true });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  return { create, list, drop, stats, partitions, clear };
+}
+
+// src/server/handlers/search.ts
+function rejectsCustomReducer(ctx, params) {
+  if (params.group && typeof params.group === "object" && "reduce" in params.group) {
+    badRequest(
+      ctx.res,
+      'Custom group reducers are not available over HTTP; use "group.fields" and "group.maxPerGroup" only'
+    );
+    return true;
+  }
+  return false;
+}
+function createSearchHandlers(deps) {
+  const { engine } = deps;
+  async function search(ctx) {
+    const params = parseJson(ctx);
+    if (!params) return;
+    if (rejectsCustomReducer(ctx, params)) return;
+    try {
+      respondJson(ctx, await engine.query(ctx.params[0], params));
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function preflight(ctx) {
+    const params = parseJson(ctx);
+    if (!params) return;
+    if (rejectsCustomReducer(ctx, params)) return;
+    try {
+      respondJson(ctx, await engine.preflight(ctx.params[0], params));
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function suggest(ctx) {
+    const params = parseJson(ctx);
+    if (!params) return;
+    if (typeof params.prefix !== "string") {
+      badRequest(ctx.res, 'Field "prefix" is required and must be a string');
+      return;
+    }
+    try {
+      respondJson(ctx, await engine.suggest(ctx.params[0], params));
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  return { search, preflight, suggest };
+}
+
+// src/server/handlers/version.ts
+function createVersionHandler(deps) {
+  function report(ctx) {
+    respondJson(ctx, { name: "narsil", ...deps.build });
+  }
+  return { report };
+}
+
+// src/server/request.ts
+function initAbortHandler(res) {
+  const listeners = [];
+  let aborted = false;
+  res.onAborted(() => {
+    aborted = true;
+    for (const fn of listeners) fn();
+  });
+  return {
+    get aborted() {
+      return aborted;
+    },
+    onAbort(fn) {
+      if (aborted) fn();
+      else listeners.push(fn);
+    }
+  };
+}
+function readBody(res, maxBytes, abort) {
+  return new Promise((resolve, reject) => {
+    if (abort.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    let done = false;
+    let total = 0;
+    const chunks = [];
+    abort.onAbort(() => {
+      if (done) return;
+      done = true;
+      reject(new Error("aborted"));
+    });
+    res.onData((chunk, isLast) => {
+      if (done || abort.aborted) return;
+      total += chunk.byteLength;
+      if (total > maxBytes) {
+        done = true;
+        if (!abort.aborted) {
+          sendError(res, 413, ServerErrorCodes.PAYLOAD_TOO_LARGE, "Request body exceeds the configured size limit");
+        }
+        reject(new Error("payload too large"));
+        return;
+      }
+      chunks.push(Buffer.from(new Uint8Array(chunk)));
+      if (isLast) {
+        done = true;
+        resolve(Buffer.concat(chunks));
+      }
+    });
+  });
+}
+var ConcurrencyGate = class {
+  constructor(max) {
+    this.max = max;
+  }
+  inFlight = 0;
+  tryAcquire() {
+    if (this.max <= 0) return true;
+    if (this.inFlight >= this.max) return false;
+    this.inFlight++;
+    return true;
+  }
+  release() {
+    if (this.max <= 0) return;
+    if (this.inFlight > 0) this.inFlight--;
+  }
+};
+function isDenial(value) {
+  return typeof value === "object" && value !== null && "status" in value;
+}
+async function runHook(res, ctx, hook) {
+  try {
+    const result = await hook(ctx);
+    if (isDenial(result)) {
+      sendError(res, result.status, result.code, result.message);
+      return false;
+    }
+    return true;
+  } catch {
+    sendError(res, 500, ServerErrorCodes.HOOK_ERROR, "The onRequest hook threw an error");
+    return false;
+  }
+}
+function createRouteRunner(deps) {
+  const gate = new ConcurrencyGate(deps.maxConcurrentRequests);
+  const { onRequest, writeCors } = deps;
+  return (handler, opts) => {
+    const paramCount = opts.paramCount ?? 0;
+    const needsBody = opts.needsBody ?? false;
+    const useHook = Boolean(onRequest) && !opts.skipHooks;
+    const gated = !opts.skipHooks;
+    return (res, req) => {
+      const params = [];
+      for (let i = 0; i < paramCount; i++) params.push(req.getParameter(i) ?? "");
+      const query = new URLSearchParams(req.getQuery() ?? "");
+      const contentType = req.getHeader("content-type");
+      let hookCtx = null;
+      if (useHook) {
+        const headers = {};
+        req.forEach((key, value) => {
+          headers[key] = value;
+        });
+        hookCtx = {
+          method: req.getMethod(),
+          path: req.getUrl(),
+          headers,
+          remoteAddress: Buffer.from(res.getRemoteAddressAsText()).toString()
+        };
+      }
+      if (writeCors) writeCors(res, req);
+      const abort = initAbortHandler(res);
+      const bodyPromise = needsBody ? readBody(res, opts.maxBytes, abort) : Promise.resolve(null);
+      const hookPromise = hookCtx && onRequest ? runHook(res, hookCtx, onRequest) : Promise.resolve(true);
+      Promise.all([bodyPromise, hookPromise]).then(async ([rawBody, allowed]) => {
+        if (abort.aborted || !allowed) return;
+        if (gated && !gate.tryAcquire()) {
+          sendError(res, 503, ServerErrorCodes.TOO_MANY_REQUESTS, "The server is at capacity; retry shortly");
+          return;
+        }
+        try {
+          await handler({ res, params, query, contentType, rawBody, abort });
+        } catch (err) {
+          if (!abort.aborted) {
+            sendError(res, 500, ServerErrorCodes.INTERNAL_ERROR, "An unexpected error occurred");
+          }
+        } finally {
+          if (gated) gate.release();
+        }
+      }).catch(() => {
+      });
+    };
+  };
+}
+
+// src/server/runtime.ts
+var cached = null;
+async function loadUWebSockets() {
+  if (cached) return cached;
+  try {
+    const mod = await import('uWebSockets.js');
+    const resolved = typeof mod.App === "function" ? mod : mod.default;
+    if (!resolved || typeof resolved.App !== "function") {
+      throw new Error("uWebSockets.js did not expose an App factory");
+    }
+    cached = resolved;
+    return resolved;
+  } catch (err) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      "The `uWebSockets.js` package is required to run the Narsil HTTP server. Install it with `pnpm add github:uNetworking/uWebSockets.js#v20.58.0` (or the npm or yarn equivalent).",
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+}
+
+// src/server/task-store.ts
+var DEFAULT_MAX_RETAINED = 1e3;
+var InMemoryTaskStore = class {
+  constructor(maxRetained = DEFAULT_MAX_RETAINED) {
+    this.maxRetained = maxRetained;
+  }
+  records = /* @__PURE__ */ new Map();
+  async set(record) {
+    this.records.set(record.id, { ...record });
+    this.prune();
+  }
+  async get(id) {
+    const record = this.records.get(id);
+    return record ? { ...record } : null;
+  }
+  async list() {
+    return [...this.records.values()].map((record) => ({ ...record }));
+  }
+  async delete(id) {
+    this.records.delete(id);
+  }
+  prune() {
+    if (this.records.size <= this.maxRetained) return;
+    for (const [id, record] of this.records) {
+      if (this.records.size <= this.maxRetained) break;
+      if (record.status === "succeeded" || record.status === "failed") this.records.delete(id);
+    }
+  }
+};
+var RUNNING_TTL_MS = 24 * 60 * 60 * 1e3;
+var TERMINAL_TTL_MS = 60 * 60 * 1e3;
+var TaskRegistry = class {
+  constructor(store, instanceId) {
+    this.store = store;
+    this.instanceId = instanceId;
+  }
+  /** Records a task as running and drives `op` to completion in the background.
+   * Returns the record once it is persisted so the caller can respond 202. */
+  async start(type, indexName, op) {
+    const now = Date.now();
+    const record = {
+      id: randomUUID(),
+      type,
+      indexName,
+      owner: this.instanceId,
+      status: "running",
+      createdAt: now,
+      startedAt: now
+    };
+    await this.store.set(record, RUNNING_TTL_MS);
+    void this.drive(record, op);
+    return record;
+  }
+  get(id) {
+    return this.store.get(id);
+  }
+  list() {
+    return this.store.list();
+  }
+  /** Fails this instance's previously-running tasks after a restart. A task can
+   * only be advanced by the process that owns it, so its own running tasks from
+   * a prior life are dead and must not keep showing a stale running status. This
+   * is effective only with a stable instanceId; with the default random id it
+   * finds none of its own prior tasks, which is also correct for the in-memory
+   * default (which starts empty). */
+  async reconcile() {
+    let records;
+    try {
+      records = await this.store.list();
+    } catch {
+      return;
+    }
+    for (const record of records) {
+      if (record.owner !== this.instanceId) continue;
+      if (record.status !== "running" && record.status !== "queued") continue;
+      const failed = {
+        ...record,
+        status: "failed",
+        completedAt: Date.now(),
+        error: { code: "TASK_INTERRUPTED", message: "The server restarted while this task was running" }
+      };
+      try {
+        await this.store.set(failed, TERMINAL_TTL_MS);
+      } catch {
+      }
+    }
+  }
+  async drive(record, op) {
+    const result = { ...record };
+    try {
+      await op();
+      result.status = "succeeded";
+    } catch (err) {
+      result.status = "failed";
+      result.error = err instanceof NarsilError ? serializeNarsilError(err) : { code: "INTERNAL_ERROR", message: "The operation failed" };
+    }
+    result.completedAt = Date.now();
+    try {
+      await this.store.set(result, TERMINAL_TTL_MS);
+    } catch {
+    }
+  }
+};
+
+// src/server/create-server.ts
+var MB = 1024 * 1024;
+function resolveLimits(limits) {
+  return {
+    maxBodyBytes: limits?.maxBodyBytes ?? 16 * MB,
+    maxImportBytes: limits?.maxImportBytes ?? 100 * MB,
+    maxLineBytes: limits?.maxLineBytes ?? 4 * MB,
+    importBatchSize: limits?.importBatchSize ?? 1e3,
+    maxConcurrentRequests: limits?.maxConcurrentRequests ?? 0
+  };
+}
+function resolveBuild(build) {
+  return {
+    version: build?.version ?? null,
+    gitSha: build?.gitSha ?? null,
+    dirty: build?.dirty ?? false
+  };
+}
+function isLoopback(host) {
+  return host === "127.0.0.1" || host === "::1" || host === "localhost" || host.startsWith("127.");
+}
+function assertSecureBinding(host, options) {
+  if (isLoopback(host) || options.onRequest || options.allowInsecure) return;
+  throw new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `Refusing to start: bound to a non-loopback address ("${host}") with no onRequest auth hook. The server exposes destructive admin endpoints (restore, drop, clear, rebalance, optimize). Resolve one of: (1) set options.onRequest to authenticate requests, (2) bind to 127.0.0.1, or (3) set options.allowInsecure: true if this address is on a trusted private network.`,
+    { host }
+  );
+}
+var NarsilHttpServer = class {
+  host;
+  port;
+  options;
+  deps;
+  uws = null;
+  listenSocket = null;
+  ready = false;
+  constructor(engine, options = {}) {
+    this.host = options.host ?? "127.0.0.1";
+    this.port = options.port ?? 9876;
+    this.options = options;
+    const adapters = options.embeddingAdapters ?? {};
+    const taskStore = options.taskStore ?? new InMemoryTaskStore();
+    const instanceId = options.instanceId ?? randomUUID();
+    this.deps = {
+      engine,
+      tasks: new TaskRegistry(taskStore, instanceId),
+      adapters,
+      limits: resolveLimits(options.limits),
+      isReady: () => this.ready,
+      build: resolveBuild(options.build)
+    };
+  }
+  async listen() {
+    assertSecureBinding(this.host, this.options);
+    const uws = await loadUWebSockets();
+    this.uws = uws;
+    const app = uws.App();
+    this.registerRoutes(app);
+    await new Promise((resolve, reject) => {
+      app.listen(this.host, this.port, (socket) => {
+        if (socket) {
+          this.listenSocket = socket;
+          resolve();
+        } else {
+          reject(new Error(`Failed to listen on ${this.host}:${this.port}`));
+        }
+      });
+    });
+    await this.deps.tasks.reconcile();
+    this.ready = true;
+  }
+  async close() {
+    this.ready = false;
+    if (this.listenSocket && this.uws) {
+      this.uws.us_listen_socket_close(this.listenSocket);
+      this.listenSocket = null;
+    }
+  }
+  get listeningPort() {
+    if (!this.listenSocket || !this.uws) return -1;
+    return this.uws.us_socket_local_port(this.listenSocket);
+  }
+  registerRoutes(app) {
+    const cors = resolveCors(this.options.cors);
+    const run = createRouteRunner({
+      onRequest: this.options.onRequest,
+      maxConcurrentRequests: this.deps.limits.maxConcurrentRequests,
+      writeCors: cors ? corsWriter(cors) : void 0
+    });
+    const { maxBodyBytes, maxImportBytes } = this.deps.limits;
+    const idx = createIndexHandlers(this.deps);
+    const doc = createDocumentHandlers(this.deps);
+    const search = createSearchHandlers(this.deps);
+    const admin = createAdminHandlers(this.deps);
+    const health = createHealthHandlers(this.deps);
+    const version = createVersionHandler(this.deps);
+    const importNdjson = createImportHandler(this.deps);
+    const json = (handler, opts) => run(handler, opts);
+    if (cors) {
+      app.options("/*", (res, req) => {
+        const origin = req.getHeader("origin");
+        res.cork(() => {
+          res.writeStatus("204 No Content");
+          writeCorsOrigin(res, cors, origin);
+          res.writeHeader("Access-Control-Allow-Methods", cors.methods).writeHeader("Access-Control-Allow-Headers", cors.headers).writeHeader("Access-Control-Max-Age", "86400").endWithoutBody();
+        });
+      });
+    }
+    app.get("/livez", json(health.livez, { maxBytes: 0, skipHooks: true }));
+    app.get("/readyz", json(health.readyz, { maxBytes: 0, skipHooks: true }));
+    app.get("/health", json(health.livez, { maxBytes: 0, skipHooks: true }));
+    app.get("/version", json(version.report, { maxBytes: 0, skipHooks: true }));
+    app.get("/stats/memory", json(admin.memory, { maxBytes: 0 }));
+    app.get("/tasks", json(admin.listTasks, { maxBytes: 0 }));
+    app.get("/tasks/:id", json(admin.getTask, { paramCount: 1, maxBytes: 0 }));
+    app.post("/indexes", json(idx.create, { needsBody: true, maxBytes: maxBodyBytes }));
+    app.get("/indexes", json(idx.list, { maxBytes: 0 }));
+    app.del("/indexes/:name", json(idx.drop, { paramCount: 1, maxBytes: 0 }));
+    app.get("/indexes/:name/stats", json(idx.stats, { paramCount: 1, maxBytes: 0 }));
+    app.get("/indexes/:name/partitions", json(idx.partitions, { paramCount: 1, maxBytes: 0 }));
+    app.post("/indexes/:name/_clear", json(idx.clear, { paramCount: 1, maxBytes: 0 }));
+    app.get("/indexes/:name/count", json(doc.count, { paramCount: 1, maxBytes: 0 }));
+    app.post("/indexes/:name/documents", json(doc.insert, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes }));
+    app.post(
+      "/indexes/:name/documents/_batch",
+      json(doc.batch, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.post(
+      "/indexes/:name/documents/_multi-get",
+      json(doc.multiGet, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.post(
+      "/indexes/:name/documents/_import",
+      json(importNdjson, { paramCount: 1, needsBody: true, maxBytes: maxImportBytes })
+    );
+    app.get("/indexes/:name/documents/:id", json(doc.get, { paramCount: 2, maxBytes: 0 }));
+    app.get("/indexes/:name/documents/:id/_exists", json(doc.exists, { paramCount: 2, maxBytes: 0 }));
+    app.put("/indexes/:name/documents/:id", json(doc.put, { paramCount: 2, needsBody: true, maxBytes: maxBodyBytes }));
+    app.patch(
+      "/indexes/:name/documents/:id",
+      json(doc.patch, { paramCount: 2, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.del("/indexes/:name/documents/:id", json(doc.remove, { paramCount: 2, maxBytes: 0 }));
+    app.post("/indexes/:name/search", json(search.search, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes }));
+    app.post(
+      "/indexes/:name/search/preflight",
+      json(search.preflight, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.post("/indexes/:name/suggest", json(search.suggest, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes }));
+    app.post("/indexes/:name/_checkpoint", json(admin.checkpoint, { paramCount: 1, maxBytes: 0 }));
+    app.get("/indexes/:name/snapshot", json(admin.snapshot, { paramCount: 1, maxBytes: 0 }));
+    app.get("/indexes/:name/vector-maintenance", json(admin.vectorMaintenance, { paramCount: 1, maxBytes: 0 }));
+    app.post(
+      "/indexes/:name/vectors/_compact",
+      json(admin.compact, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.post(
+      "/indexes/:name/vectors/_optimize",
+      json(admin.optimize, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.post(
+      "/indexes/:name/_rebalance",
+      json(admin.rebalance, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.post(
+      "/indexes/:name/partition-config",
+      json(admin.partitionConfig, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
+    app.post(
+      "/indexes/:name/restore",
+      json(admin.restore, { paramCount: 1, needsBody: true, maxBytes: maxImportBytes })
+    );
+    app.any("/*", (res) => {
+      sendError(res, 404, ServerErrorCodes.NOT_FOUND, "Route not found");
+    });
+  }
+};
+function createServer(engine, options) {
+  return new NarsilHttpServer(engine, options);
+}
+
+export { InMemoryTaskStore, ServerErrorCodes, createServer, httpStatusForNarsilError };