@delali/narsil 0.2.3-next.34 → 0.2.3-next.36

package/dist/server.mjs

@@ -1,5 +1,6 @@
-import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-EMI63EXP.mjs';
-export { ServerErrorCodes } from './chunk-EMI63EXP.mjs';
+import { validateIndexName } from './chunk-WU2UZEVD.mjs';
+import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-GB2IIJJG.mjs';
+export { ServerErrorCodes } from './chunk-GB2IIJJG.mjs';
 import { randomUUID } from 'crypto';
 
 // src/server/capabilities.ts
@@ -117,6 +118,8 @@ var STATUS_BY_CODE = {
   CONTROLLER_NOT_ACTIVE: 503,
   NODE_ALREADY_JOINED: 409,
   NODE_NOT_JOINED: 503,
+  NODE_NOT_READY: 503,
+  NODE_NOT_CONTROLLER: 503,
   NODE_BOOTSTRAP_FAILED: 503,
   COORDINATOR_DEPENDENCY_MISSING: 500,
   SNAPSHOT_SYNC_UNAUTHORIZED: 403,
@@ -649,6 +652,79 @@ function createCapabilitiesHandler() {
   return { report };
 }
 
+// src/server/handlers/cluster.ts
+function requireCluster(deps) {
+  if (deps.cluster === void 0) {
+    throw new NarsilError(
+      ErrorCodes.CLUSTER_OPERATION_UNSUPPORTED,
+      "This server fronts a single engine, so it reports no cluster",
+      {}
+    );
+  }
+  return deps.cluster;
+}
+function describeNode(cluster) {
+  return { ...cluster.getNodeInfo(), readiness: cluster.getReadiness(), isController: cluster.isControllerActive() };
+}
+function malformedIndexName(indexName) {
+  try {
+    validateIndexName(indexName);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+function createClusterHandlers(deps) {
+  async function topology(ctx) {
+    try {
+      const cluster = requireCluster(deps);
+      const [nodes, controllerNodeId] = await Promise.all([cluster.listNodes(), cluster.getControllerNodeId()]);
+      respondJson(ctx, {
+        node: describeNode(cluster),
+        controllerNodeId,
+        nodes: nodes.map((node) => ({ nodeId: node.nodeId, address: node.address, roles: [...node.roles] }))
+      });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function allocation(ctx) {
+    try {
+      const cluster = requireCluster(deps);
+      const indexName = ctx.params[0] ?? "";
+      const malformed = malformedIndexName(indexName);
+      if (malformed !== null) {
+        badRequest(ctx.res, malformed, { indexName });
+        return;
+      }
+      const table = await cluster.getAllocation(indexName);
+      if (table === null) {
+        respondJson(ctx, { indexName, allocated: false, version: null, partitions: [] });
+        return;
+      }
+      const partitions = [];
+      for (const [partitionId, assignment] of table.assignments) {
+        partitions.push({
+          partitionId,
+          state: assignment.state,
+          primary: assignment.primary,
+          primaryTerm: assignment.primaryTerm,
+          commitPoint: assignment.commitPoint,
+          replicas: [...assignment.replicas],
+          inSyncSet: [...assignment.inSyncSet],
+          lastHolders: [...assignment.lastHolders ?? []],
+          unassignedReason: assignment.unassignedReason ?? null
+        });
+      }
+      partitions.sort((left, right) => left.partitionId - right.partitionId);
+      respondJson(ctx, { indexName, allocated: partitions.length > 0, version: table.version, partitions });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  return { topology, allocation };
+}
+
 // src/server/handlers/documents.ts
 function createDocumentHandlers(deps) {
   const { engine, limits } = deps;
@@ -804,11 +880,25 @@ function createHealthHandlers(deps) {
     respondJson(ctx, { status: "ok" });
   }
   function readyz(ctx) {
-    if (deps.isReady()) {
-      respondJson(ctx, { status: "ready" });
-    } else {
-      respondJson(ctx, { status: "unavailable" }, 503);
+    const cluster = deps.cluster;
+    if (cluster === void 0) {
+      if (deps.isReady()) {
+        respondJson(ctx, { status: "ready" });
+      } else {
+        respondJson(ctx, { status: "unavailable" }, 503);
+      }
+      return;
     }
+    const readiness = cluster.getReadiness();
+    const ready = deps.isReady() && readiness === "SERVING";
+    respondJson(
+      ctx,
+      {
+        status: ready ? "ready" : "unavailable",
+        cluster: describeNode(cluster)
+      },
+      ready ? 200 : 503
+    );
   }
   return { livez, readyz };
 }
@@ -1576,7 +1666,8 @@ var NarsilHttpServer = class {
       tasks: new TaskRegistry(taskStore, instanceId, limits.maxConcurrentTasks),
       limits,
       isReady: () => this.ready,
-      build: resolveBuild(options.build)
+      build: resolveBuild(options.build),
+      cluster: options.cluster
     };
   }
   async listen() {
@@ -1622,6 +1713,7 @@ var NarsilHttpServer = class {
     const search = createSearchHandlers(this.deps);
     const admin = createAdminHandlers(this.deps);
     const health = createHealthHandlers(this.deps);
+    const cluster = createClusterHandlers(this.deps);
     const version = createVersionHandler(this.deps);
     const capabilities = createCapabilitiesHandler();
     const importNdjson = createImportHandler(this.deps);
@@ -1641,6 +1733,7 @@ var NarsilHttpServer = class {
     app.get("/health", json(health.livez, { maxBytes: 0, skipHooks: true }));
     app.get("/version", json(version.report, { maxBytes: 0, skipHooks: true }));
     app.get("/capabilities", json(capabilities.report, { maxBytes: 0, skipHooks: true }));
+    app.get("/cluster", json(cluster.topology, { maxBytes: 0 }));
     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 }));
@@ -1650,6 +1743,7 @@ var NarsilHttpServer = class {
     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.get("/indexes/:name/cluster", json(cluster.allocation, { 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 }));

package/dist/{types-BhdINMtE.d.ts → types-B5Tsaalz.d.ts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './schema-emTQfEiX.js';
+import { S as SchemaDefinition } from './schema-ZRbk8BgH.js';
 
 /**
  * What a node does in a cluster. A node may hold several roles at once.
@@ -20,6 +20,19 @@ type NodeRole = 'data' | 'coordinator' | 'controller';
  * @public
  */
 type PartitionState = 'UNASSIGNED' | 'INITIALISING' | 'ACTIVE' | 'MIGRATING' | 'DECOMMISSIONING';
+/**
+ * Why a partition stays `UNASSIGNED` after the controller has asked its last holders for a copy.
+ *
+ * `HOLDER_OFFLINE` means a last holder has yet to register again, so the controller is still waiting for it.
+ * `HOLDER_UNREACHABLE` means a registered holder left the request unanswered or answered with a payload the
+ * controller could not read. `HOLDER_IDENTITY_MISMATCH` means a holder answered under a different index identity,
+ * so its copy holds the documents of an earlier index of the same name, or it keeps no copy of that name at all.
+ * `HOLDER_WITHOUT_DATA` means every holder answered under the coordinator's identity with a list that left the
+ * partition out.
+ *
+ * @public
+ */
+type UnassignedReason = 'HOLDER_OFFLINE' | 'HOLDER_UNREACHABLE' | 'HOLDER_IDENTITY_MISMATCH' | 'HOLDER_WITHOUT_DATA';
 /**
  * What one node has to offer, which the allocator weighs when it places
  * partitions.
@@ -67,12 +80,16 @@ interface PartitionAssignment {
     replicas: string[];
     /** These replicas are current enough to be promoted, which is the set a failover picks from. */
     inSyncSet: string[];
+    /** These nodes still hold a copy of a partition no node serves, and the field stays until the partition is `ACTIVE`. */
+    lastHolders?: string[];
     /** This says where the partition stands in its move between nodes. */
     state: PartitionState;
     /** This rises each time the primary changes, which is what makes a stale primary's writes detectable. */
     primaryTerm: number;
     /** The primary has acknowledged every sequence number up to here, so every in-sync replica holds them. */
     commitPoint: number;
+    /** Why the partition stays `UNASSIGNED`, which the controller records each time it asks the last holders. */
+    unassignedReason?: UnassignedReason;
 }
 /**
  * How one index's partitions are spread across the cluster.
@@ -323,4 +340,4 @@ interface ClusterCoordinator {
     shutdown(): Promise<void>;
 }
 
-export type { AllocationTable as A, ClusterCoordinator as C, NodeRole as N, PartitionAssignment as P, SchemaEvent as S, NodeCapacity as a, AllocationConstraints as b, AllocationEvent as c, NodeEvent as d, NodeRegistration as e, PartitionState as f };
+export type { AllocationTable as A, ClusterCoordinator as C, NodeRole as N, PartitionAssignment as P, SchemaEvent as S, UnassignedReason as U, NodeRegistration as a, NodeCapacity as b, AllocationConstraints as c, AllocationEvent as d, NodeEvent as e, PartitionState as f };

package/dist/workers/entry.mjs

@@ -1,5 +1,5 @@
 import { isValidWorkerAction } from '../chunk-WTONLDU3.mjs';
-import { NarsilError, ErrorCodes } from '../chunk-EMI63EXP.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-GB2IIJJG.mjs';
 
 // src/workers/action-handler.ts
 function buildErrorResponse(requestId, code, message) {
@@ -55,7 +55,7 @@ async function setup() {
   } catch {
     parentPort = null;
   }
-  const { createDirectExecutor } = await import('../direct-executor-YARCDMJF.mjs');
+  const { createDirectExecutor } = await import('../direct-executor-MSJEVPZU.mjs');
   const handleAction = createActionHandler(createDirectExecutor());
   if (parentPort) {
     const port = parentPort;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delali/narsil",
-  "version": "0.2.3-next.34",
+  "version": "0.2.3-next.36",
   "type": "module",
   "description": "A distributed full-text search engine with cross-language portable binary format.",
   "author": "Delali (https://sondelali.com)",