@delali/narsil 0.1.7 → 0.1.8

package/dist/{chunk-I24SGLFS.mjs → chunk-TW6BXTOL.mjs}

@@ -328,7 +328,11 @@ var stopWords = /* @__PURE__ */ new Set([
 var english = {
   name: "english",
   stemmer: stemWord,
-  stopWords
+  stopWords,
+  tokenizer: {
+    splitPattern: /[^\p{L}\p{N}_']+/u,
+    stripPossessive: true
+  }
 };
 
 export { english };

package/dist/chunk-WISGW24C.mjs

@@ -0,0 +1,455 @@
+import { NarsilError, ErrorCodes } from './chunk-ALB35PRQ.mjs';
+import { decode, encode } from '@msgpack/msgpack';
+
+// src/distribution/coordinator/etcd/leases.ts
+var LeaseManager = class {
+  leases = /* @__PURE__ */ new Map();
+  track(key, lease, nodeId) {
+    this.leases.set(key, { lease, nodeId, key });
+  }
+  get(key) {
+    return this.leases.get(key);
+  }
+  getByNodeId(key, nodeId) {
+    const entry = this.leases.get(key);
+    if (entry === void 0 || entry.nodeId !== nodeId) {
+      return void 0;
+    }
+    return entry;
+  }
+  remove(key) {
+    const entry = this.leases.get(key);
+    if (entry !== void 0) {
+      this.leases.delete(key);
+    }
+    return entry;
+  }
+  async revokeAll() {
+    const revokePromises = [];
+    for (const [, entry] of this.leases) {
+      revokePromises.push(
+        entry.lease.revoke().catch(() => {
+        })
+      );
+    }
+    this.leases.clear();
+    await Promise.all(revokePromises);
+  }
+  entries() {
+    return this.leases.entries();
+  }
+};
+
+// src/distribution/coordinator/etcd/loader.ts
+async function loadEtcd3Module() {
+  try {
+    return await import('etcd3');
+  } catch (err) {
+    throw new NarsilError(
+      ErrorCodes.COORDINATOR_DEPENDENCY_MISSING,
+      "The `etcd3` package is not installed. Install it with `pnpm add etcd3` (or the npm or yarn equivalent) to use createEtcdCoordinator.",
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+}
+function serializeAllocationTable(table) {
+  const serializable = {
+    indexName: table.indexName,
+    version: table.version,
+    replicationFactor: table.replicationFactor,
+    assignments: Array.from(table.assignments.entries())
+  };
+  return new Uint8Array(encode(serializable));
+}
+function deserializeAllocationTable(data) {
+  const raw = decode(data);
+  if (typeof raw.indexName !== "string") {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "AllocationTable missing or invalid indexName field");
+  }
+  if (typeof raw.version !== "number") {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "AllocationTable missing or invalid version field");
+  }
+  if (!Array.isArray(raw.assignments)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "AllocationTable missing or invalid assignments field");
+  }
+  return {
+    indexName: raw.indexName,
+    version: raw.version,
+    replicationFactor: typeof raw.replicationFactor === "number" ? raw.replicationFactor : 0,
+    assignments: new Map(raw.assignments)
+  };
+}
+function serializeNodeRegistration(reg) {
+  return new Uint8Array(encode(reg));
+}
+function deserializeNodeRegistration(data) {
+  const raw = decode(data);
+  if (typeof raw.nodeId !== "string") {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "NodeRegistration missing or invalid nodeId field");
+  }
+  if (typeof raw.address !== "string") {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "NodeRegistration missing or invalid address field");
+  }
+  return raw;
+}
+function serializeSchema(schema) {
+  return Buffer.from(new Uint8Array(encode(schema)));
+}
+function deserializeSchema(data) {
+  return decode(data);
+}
+
+// src/distribution/coordinator/etcd/types.ts
+var DEFAULT_ETCD_CONFIG = {
+  endpoints: ["http://localhost:2379"],
+  keyPrefix: "_narsil",
+  nodeHeartbeatTtlSeconds: 30,
+  leaseTtlSeconds: 15
+};
+var ETCD_KEY_NODES = "nodes";
+var ETCD_KEY_ALLOCATION = "allocation";
+var ETCD_KEY_PARTITION = "partition";
+var ETCD_KEY_SCHEMA = "schema";
+function buildKey(prefix, ...segments) {
+  return [prefix, ...segments].join("/");
+}
+
+// src/distribution/coordinator/etcd/validation.ts
+var MAX_NODE_ID_LENGTH = 255;
+var VALID_PARTITION_STATES = /* @__PURE__ */ new Set(["UNASSIGNED", "INITIALISING", "ACTIVE", "MIGRATING", "DECOMMISSIONING"]);
+var MAX_WATCHERS = 64;
+function validateNodeId(nodeId) {
+  if (nodeId.length === 0) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "Node ID must not be empty");
+  }
+  if (nodeId.length > MAX_NODE_ID_LENGTH) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, `Node ID exceeds the ${MAX_NODE_ID_LENGTH} character limit`, {
+      nodeId,
+      length: nodeId.length
+    });
+  }
+  if (nodeId.includes("/") || nodeId.includes("\\") || nodeId.includes("..") || nodeId.includes("\0")) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      "Node ID contains forbidden characters (/, \\, .., or null bytes)",
+      {
+        nodeId
+      }
+    );
+  }
+}
+function validatePartitionState(value) {
+  if (!VALID_PARTITION_STATES.has(value)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, `Unknown partition state '${value}'`, {
+      state: value,
+      validStates: Array.from(VALID_PARTITION_STATES)
+    });
+  }
+  return value;
+}
+
+// src/distribution/coordinator/etcd/index.ts
+async function createEtcdCoordinator(config) {
+  const resolvedConfig = {
+    ...DEFAULT_ETCD_CONFIG,
+    ...config
+  };
+  const etcd3Module = await loadEtcd3Module();
+  const client = new etcd3Module.Etcd3({ hosts: resolvedConfig.endpoints });
+  const leaseManager = new LeaseManager();
+  const watchers = /* @__PURE__ */ new Set();
+  let isShutdown = false;
+  function assertNotShutdown() {
+    if (isShutdown) {
+      throw new NarsilError(ErrorCodes.CONFIG_INVALID, "Coordinator has been shut down");
+    }
+  }
+  function nodeKey(nodeId) {
+    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_NODES, nodeId);
+  }
+  function allocationKey(indexName) {
+    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_ALLOCATION, indexName);
+  }
+  function partitionKey(indexName, partitionId) {
+    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_PARTITION, indexName, String(partitionId));
+  }
+  function schemaKey(indexName) {
+    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_SCHEMA, indexName);
+  }
+  function leaseKey(key) {
+    return buildKey(resolvedConfig.keyPrefix, "lease", key);
+  }
+  function genericKey(key) {
+    return buildKey(resolvedConfig.keyPrefix, "kv", key);
+  }
+  function extractSuffix(fullKey, prefix) {
+    return fullKey.slice(prefix.length + 1);
+  }
+  function addWatcher(watcher) {
+    if (watchers.size >= MAX_WATCHERS) {
+      watcher.cancel().catch(() => {
+      });
+      throw new NarsilError(ErrorCodes.CONFIG_INVALID, `Maximum watcher limit (${MAX_WATCHERS}) reached`, {
+        currentCount: watchers.size
+      });
+    }
+    watchers.add(watcher);
+  }
+  function removeWatcher(watcher) {
+    watcher.cancel().catch(() => {
+    });
+    watchers.delete(watcher);
+  }
+  const coordinator = {
+    async registerNode(registration) {
+      assertNotShutdown();
+      validateNodeId(registration.nodeId);
+      const ttl = resolvedConfig.nodeHeartbeatTtlSeconds;
+      const lease = client.lease(ttl);
+      await lease.grant();
+      const key = nodeKey(registration.nodeId);
+      const data = Buffer.from(serializeNodeRegistration(registration));
+      await lease.put(key).value(data).exec();
+      const existing = leaseManager.get(key);
+      if (existing !== void 0) {
+        await existing.lease.revoke().catch(() => {
+        });
+      }
+      leaseManager.track(key, lease, registration.nodeId);
+    },
+    async deregisterNode(nodeId) {
+      assertNotShutdown();
+      validateNodeId(nodeId);
+      const key = nodeKey(nodeId);
+      const entry = leaseManager.remove(key);
+      if (entry !== void 0) {
+        await entry.lease.revoke().catch(() => {
+        });
+      }
+      await client.delete().key(key).exec();
+    },
+    async listNodes() {
+      assertNotShutdown();
+      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_NODES);
+      const result = await client.getAll().prefix(prefix).buffers();
+      const nodes = [];
+      for (const key of Object.keys(result)) {
+        const buf = result[key];
+        if (buf !== void 0) {
+          nodes.push(deserializeNodeRegistration(buf));
+        }
+      }
+      return nodes;
+    },
+    async watchNodes(handler) {
+      assertNotShutdown();
+      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_NODES);
+      const watcher = await client.watch().prefix(prefix).create();
+      addWatcher(watcher);
+      watcher.on("put", (kv) => {
+        try {
+          const registration = deserializeNodeRegistration(kv.value);
+          handler({ type: "node_joined", nodeId: registration.nodeId, registration });
+        } catch (_) {
+        }
+      });
+      watcher.on("delete", (kv) => {
+        const fullKey = kv.key.toString();
+        const nodeId = extractSuffix(fullKey, prefix);
+        handler({ type: "node_left", nodeId, registration: null });
+      });
+      return () => removeWatcher(watcher);
+    },
+    async getAllocation(indexName) {
+      assertNotShutdown();
+      const key = allocationKey(indexName);
+      const buf = await client.get(key).buffer();
+      if (buf === null) {
+        return null;
+      }
+      return deserializeAllocationTable(buf);
+    },
+    async putAllocation(indexName, table, expectedVersion) {
+      assertNotShutdown();
+      const key = allocationKey(indexName);
+      const data = Buffer.from(serializeAllocationTable(table));
+      if (expectedVersion === void 0) {
+        await client.put(key).value(data).exec();
+        return true;
+      }
+      if (expectedVersion === null) {
+        const txn2 = await client.if(key, "Create", "==", 0).then(client.put(key).value(data)).commit();
+        return txn2.succeeded;
+      }
+      const response = await client.get(key).exec();
+      if (response.kvs.length === 0) {
+        return false;
+      }
+      const kv = response.kvs[0];
+      const currentTable = deserializeAllocationTable(Buffer.from(kv.value));
+      if (currentTable.version !== expectedVersion) {
+        return false;
+      }
+      const txn = await client.if(key, "Mod", "==", kv.mod_revision).then(client.put(key).value(data)).commit();
+      return txn.succeeded;
+    },
+    async watchAllocation(handler) {
+      assertNotShutdown();
+      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_ALLOCATION);
+      const watcher = await client.watch().prefix(prefix).create();
+      addWatcher(watcher);
+      watcher.on("put", (kv) => {
+        try {
+          const table = deserializeAllocationTable(kv.value);
+          handler({ indexName: table.indexName, table });
+        } catch (_) {
+        }
+      });
+      return () => removeWatcher(watcher);
+    },
+    async getPartitionState(indexName, partitionId) {
+      assertNotShutdown();
+      const key = partitionKey(indexName, partitionId);
+      const value = await client.get(key).string();
+      if (value === null) {
+        return "UNASSIGNED";
+      }
+      return validatePartitionState(value);
+    },
+    async putPartitionState(indexName, partitionId, state) {
+      assertNotShutdown();
+      const key = partitionKey(indexName, partitionId);
+      await client.put(key).value(state).exec();
+    },
+    async acquireLease(key, nodeId, ttlMs) {
+      assertNotShutdown();
+      const etcdKey = leaseKey(key);
+      const ttlSeconds = Math.max(1, Math.ceil(ttlMs / 1e3));
+      const existing = leaseManager.get(etcdKey);
+      if (existing !== void 0 && existing.nodeId === nodeId) {
+        try {
+          await existing.lease.keepaliveOnce();
+          return true;
+        } catch (_) {
+          leaseManager.remove(etcdKey);
+        }
+      }
+      const lease = client.lease(ttlSeconds);
+      await lease.grant();
+      const txn = await client.if(etcdKey, "Create", "==", 0).then(lease.put(etcdKey).value(nodeId)).commit();
+      if (!txn.succeeded) {
+        await lease.revoke().catch(() => {
+        });
+        const currentValue = await client.get(etcdKey).string();
+        return currentValue === nodeId;
+      }
+      leaseManager.track(etcdKey, lease, nodeId);
+      return true;
+    },
+    async renewLease(key, nodeId, _ttlMs) {
+      assertNotShutdown();
+      const etcdKey = leaseKey(key);
+      const entry = leaseManager.getByNodeId(etcdKey, nodeId);
+      if (entry === void 0) {
+        return false;
+      }
+      try {
+        await entry.lease.keepaliveOnce();
+        return true;
+      } catch (_) {
+        leaseManager.remove(etcdKey);
+        return false;
+      }
+    },
+    async releaseLease(key) {
+      assertNotShutdown();
+      const etcdKey = leaseKey(key);
+      const entry = leaseManager.remove(etcdKey);
+      if (entry !== void 0) {
+        await entry.lease.revoke().catch(() => {
+        });
+      }
+      await client.delete().key(etcdKey).exec();
+    },
+    async get(key) {
+      assertNotShutdown();
+      const etcdKey = genericKey(key);
+      const buf = await client.get(etcdKey).buffer();
+      if (buf === null) {
+        return null;
+      }
+      return new Uint8Array(buf);
+    },
+    async compareAndSet(key, expected, value) {
+      assertNotShutdown();
+      const etcdKey = genericKey(key);
+      const newValue = Buffer.from(value);
+      if (expected === null) {
+        const txn2 = await client.if(etcdKey, "Create", "==", 0).then(client.put(etcdKey).value(newValue)).commit();
+        return txn2.succeeded;
+      }
+      const expectedBuf = Buffer.from(expected);
+      const txn = await client.if(etcdKey, "Value", "==", expectedBuf).then(client.put(etcdKey).value(newValue)).commit();
+      return txn.succeeded;
+    },
+    async getSchema(indexName) {
+      assertNotShutdown();
+      const key = schemaKey(indexName);
+      const buf = await client.get(key).buffer();
+      if (buf === null) {
+        return null;
+      }
+      return deserializeSchema(buf);
+    },
+    async putSchema(indexName, schema) {
+      assertNotShutdown();
+      const key = schemaKey(indexName);
+      await client.put(key).value(serializeSchema(schema)).exec();
+    },
+    async watchSchemas(handler) {
+      assertNotShutdown();
+      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_SCHEMA);
+      const watcher = await client.watch().prefix(prefix).create();
+      addWatcher(watcher);
+      watcher.on("put", (kv) => {
+        try {
+          const schema = deserializeSchema(kv.value);
+          const fullKey = kv.key.toString();
+          const indexName = extractSuffix(fullKey, prefix);
+          handler({ type: "schema_created", indexName, schema });
+        } catch (_) {
+        }
+      });
+      watcher.on("delete", (kv) => {
+        const fullKey = kv.key.toString();
+        const indexName = extractSuffix(fullKey, prefix);
+        handler({ type: "schema_dropped", indexName, schema: null });
+      });
+      return () => removeWatcher(watcher);
+    },
+    async getLeaseHolder(key) {
+      assertNotShutdown();
+      const etcdKey = leaseKey(key);
+      const value = await client.get(etcdKey).string();
+      return value ?? null;
+    },
+    async shutdown() {
+      if (isShutdown) {
+        return;
+      }
+      isShutdown = true;
+      const cancelPromises = [];
+      for (const watcher of watchers) {
+        cancelPromises.push(watcher.cancel().catch(() => {
+        }));
+      }
+      await Promise.all(cancelPromises);
+      watchers.clear();
+      await leaseManager.revokeAll();
+      client.close();
+    }
+  };
+  return coordinator;
+}
+
+export { createEtcdCoordinator, validateNodeId };