@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/replication/coordinator/etcd.mjs

@@ -1,8 +1,8 @@
 import { compatibilityAllowsPromotion } from '../../chunk-ER7ODTDA.mjs';
-import { CoordinatorError, NoSafePrimaryError } from '../../chunk-BTTFW4Z4.mjs';
-import '../../chunk-2QLXDHAP.mjs';
-import '../../chunk-PBRXXISQ.mjs';
-import { Etcd3 } from 'etcd3';
+import { CoordinatorError, NoSafePrimaryError } from '../../chunk-KU32OT4H.mjs';
+import { optionalDependencyError } from '../../chunk-WOMADPM4.mjs';
+import '../../chunk-BLMRNSUG.mjs';
+import '../../chunk-KINDFBQP.mjs';
 
 // src/replication/coordinator/group-rules.ts
 var MIN_AUTOMATIC_FAILOVER_VOTERS = 3;
@@ -287,7 +287,10 @@ function controllerLeaseKey(clusterId) {
   return `clusters/${encodeKey(clusterId)}/controller`;
 }
 function nodeSessionKey(clusterId, nodeId) {
-  return `clusters/${encodeKey(clusterId)}/nodes/${encodeKey(nodeId)}`;
+  return `${nodeSessionPrefix(clusterId)}${encodeKey(nodeId)}`;
+}
+function nodeSessionPrefix(clusterId) {
+  return `clusters/${encodeKey(clusterId)}/nodes/`;
 }
 function replicationGroupKey(clusterId, groupId) {
   return `clusters/${encodeKey(clusterId)}/groups/${encodeKey(groupId)}`;
@@ -299,6 +302,145 @@ function encodeKey(value) {
   return encodeURIComponent(value);
 }
 
+// src/replication/coordinator/etcd-lease-registry.ts
+async function readLeaseAt(namespace, key) {
+  const value = await namespace.get(key).string();
+  return value ? parseLease(value) : null;
+}
+async function revokeLeaseQuietly(lease) {
+  try {
+    await lease.revoke();
+  } catch {
+    lease.release();
+  }
+}
+var EtcdLeaseRegistry = class {
+  constructor(onLeaseLost) {
+    this.onLeaseLost = onLeaseLost;
+  }
+  entries = /* @__PURE__ */ new Map();
+  get(leaseId) {
+    return this.entries.get(leaseId);
+  }
+  forget(leaseId) {
+    this.entries.delete(leaseId);
+  }
+  leaseIdsForKey(key) {
+    const matches = [];
+    for (const [leaseId, entry] of this.entries) {
+      if (entry.key === key) matches.push(leaseId);
+    }
+    return matches;
+  }
+  track(lease, entry) {
+    this.entries.set(entry.leaseId, { ...entry, lease });
+    lease.on("lost", (err) => {
+      this.entries.delete(entry.leaseId);
+      this.onLeaseLost?.(err instanceof Error ? err : new CoordinatorError(String(err)));
+    });
+  }
+  async discardSuperseded(key, keepLeaseId) {
+    const superseded = [];
+    for (const [leaseId, entry] of this.entries) {
+      if (entry.key === key && leaseId !== keepLeaseId) {
+        this.entries.delete(leaseId);
+        superseded.push(entry);
+      }
+    }
+    await Promise.allSettled(superseded.map((entry) => revokeLeaseQuietly(entry.lease)));
+  }
+  async revokeAll() {
+    const revokes = [];
+    for (const entry of this.entries.values()) {
+      revokes.push(revokeLeaseQuietly(entry.lease));
+    }
+    this.entries.clear();
+    await Promise.allSettled(revokes);
+  }
+};
+
+// src/replication/coordinator/etcd-controller-lease.ts
+async function acquireEtcdControllerLease(namespace, leases, input) {
+  const key = controllerLeaseKey(input.clusterId);
+  const lease = namespace.lease(ttlMsToSeconds(input.ttlMs));
+  const leaseId = await lease.grant();
+  const grantedAtMs = Date.now();
+  const value = serializeLease({
+    id: leaseId,
+    kind: "controller",
+    clusterId: input.clusterId,
+    holderId: input.holderId,
+    ttlMs: input.ttlMs,
+    grantedAtMs,
+    expiresAtMs: grantedAtMs + input.ttlMs,
+    metadata: cloneMetadata(input.metadata)
+  });
+  const result = await namespace.if(key, "Create", "==", 0).then(namespace.put(key).value(value).lease(leaseId)).commit();
+  if (!result.succeeded) {
+    await revokeLeaseQuietly(lease);
+    return { acquired: false, lease: await readLeaseAt(namespace, key) };
+  }
+  leases.track(lease, {
+    leaseId,
+    key,
+    ttlMs: input.ttlMs,
+    ttlSeconds: ttlMsToSeconds(input.ttlMs),
+    kind: "controller",
+    clusterId: input.clusterId,
+    holderId: input.holderId,
+    metadata: cloneMetadata(input.metadata)
+  });
+  return { acquired: true, lease: parseLease(value) };
+}
+async function watchEtcdControllerLease(namespace, clusterId, watcher, watchers, onWatcherError) {
+  const key = controllerLeaseKey(clusterId);
+  let holder = null;
+  let reading = true;
+  let changedWhileReading = false;
+  const report = () => {
+    try {
+      watcher(holder);
+    } catch (err) {
+      onWatcherError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  const record = (next) => {
+    holder = next;
+    if (reading) {
+      changedWhileReading = true;
+      return;
+    }
+    report();
+  };
+  const etcdWatcher = await namespace.watch().key(key).create();
+  watchers.add(etcdWatcher);
+  etcdWatcher.on("put", (kv) => {
+    record(parseLease(kv.value.toString("utf8")));
+  });
+  etcdWatcher.on("delete", () => {
+    record(null);
+  });
+  etcdWatcher.on("error", (err) => {
+    onWatcherError?.(err instanceof Error ? err : new Error(String(err)));
+  });
+  try {
+    const value = await namespace.get(key).string();
+    if (!changedWhileReading) {
+      holder = value ? parseLease(value) : null;
+    }
+  } catch (err) {
+    watchers.delete(etcdWatcher);
+    await etcdWatcher.cancel();
+    throw err;
+  }
+  reading = false;
+  report();
+  return async () => {
+    watchers.delete(etcdWatcher);
+    await etcdWatcher.cancel();
+  };
+}
+
 // src/replication/coordinator/etcd-group-store.ts
 var MAX_CAS_ATTEMPTS = 5;
 var MAX_PROMOTION_ATTEMPTS = 3;
@@ -473,115 +615,104 @@ var EtcdGroupStore = class {
   }
 };
 
-// src/replication/coordinator/etcd-lease-registry.ts
-async function revokeLeaseQuietly(lease) {
+// src/replication/coordinator/etcd-loader.ts
+var ETCD3_DEPENDENCY = {
+  packageName: "etcd3",
+  neededBy: "The etcd coordinator",
+  installCommand: "pnpm add -E etcd3",
+  code: "COORDINATOR_DEPENDENCY_MISSING"
+};
+async function loadEtcd3Module() {
   try {
-    await lease.revoke();
-  } catch {
-    lease.release();
+    return await import('etcd3');
+  } catch (err) {
+    throw optionalDependencyError(ETCD3_DEPENDENCY, err);
   }
 }
-var EtcdLeaseRegistry = class {
-  constructor(onLeaseLost) {
-    this.onLeaseLost = onLeaseLost;
-  }
-  entries = /* @__PURE__ */ new Map();
-  get(leaseId) {
-    return this.entries.get(leaseId);
-  }
-  forget(leaseId) {
-    this.entries.delete(leaseId);
-  }
-  leaseIdsForKey(key) {
-    const matches = [];
-    for (const [leaseId, entry] of this.entries) {
-      if (entry.key === key) matches.push(leaseId);
+
+// src/replication/coordinator/etcd-session-watch.ts
+function nodeIdOf(key, prefix) {
+  return decodeURIComponent(key.slice(prefix.length));
+}
+async function watchEtcdNodeSessions(namespace, clusterId, watcher, watchers, onWatcherError) {
+  const prefix = nodeSessionPrefix(clusterId);
+  const live = /* @__PURE__ */ new Set();
+  const goneWhileReading = /* @__PURE__ */ new Set();
+  let reading = true;
+  const report = () => {
+    try {
+      watcher([...live]);
+    } catch (err) {
+      onWatcherError?.(err instanceof Error ? err : new Error(String(err)));
     }
-    return matches;
-  }
-  track(lease, entry) {
-    this.entries.set(entry.leaseId, { ...entry, lease });
-    lease.on("lost", (err) => {
-      this.entries.delete(entry.leaseId);
-      this.onLeaseLost?.(err instanceof Error ? err : new CoordinatorError(String(err)));
-    });
-  }
-  async discardSuperseded(key, keepLeaseId) {
-    const superseded = [];
-    for (const [leaseId, entry] of this.entries) {
-      if (entry.key === key && leaseId !== keepLeaseId) {
-        this.entries.delete(leaseId);
-        superseded.push(entry);
-      }
+  };
+  const etcdWatcher = await namespace.watch().prefix(prefix).create();
+  watchers.add(etcdWatcher);
+  etcdWatcher.on("put", (kv) => {
+    live.add(nodeIdOf(kv.key.toString("utf8"), prefix));
+    if (!reading) report();
+  });
+  etcdWatcher.on("delete", (kv) => {
+    const nodeId = nodeIdOf(kv.key.toString("utf8"), prefix);
+    live.delete(nodeId);
+    if (reading) {
+      goneWhileReading.add(nodeId);
+      return;
     }
-    await Promise.allSettled(superseded.map((entry) => revokeLeaseQuietly(entry.lease)));
-  }
-  async revokeAll() {
-    const revokes = [];
-    for (const entry of this.entries.values()) {
-      revokes.push(revokeLeaseQuietly(entry.lease));
+    report();
+  });
+  etcdWatcher.on("error", (err) => {
+    onWatcherError?.(err instanceof Error ? err : new Error(String(err)));
+  });
+  try {
+    for (const key of await namespace.getAll().prefix(prefix).keys()) {
+      const nodeId = nodeIdOf(key, prefix);
+      if (!goneWhileReading.has(nodeId)) {
+        live.add(nodeId);
+      }
     }
-    this.entries.clear();
-    await Promise.allSettled(revokes);
-  }
-};
+  } catch (err) {
+    watchers.delete(etcdWatcher);
+    await etcdWatcher.cancel();
+    throw err;
+  }
+  reading = false;
+  report();
+  return async () => {
+    watchers.delete(etcdWatcher);
+    await etcdWatcher.cancel();
+  };
+}
 
 // src/replication/coordinator/etcd.ts
 var EtcdClusterCoordinator = class {
-  client;
-  namespace;
+  options;
+  connection = null;
   onWatcherError;
   leases;
   grantedNodeSessionLeaseIds = /* @__PURE__ */ new Map();
   watchers = /* @__PURE__ */ new Set();
-  groups;
   constructor(options) {
     assertEtcdOptions(options);
-    this.client = new Etcd3(toEtcdOptions(options));
-    this.namespace = this.client.namespace(normaliseKeyPrefix(options.keyPrefix));
+    this.options = options;
     this.onWatcherError = options.onWatcherError;
     this.leases = new EtcdLeaseRegistry(this.onWatcherError);
-    this.groups = new EtcdGroupStore(this.namespace, this.watchers, this.onWatcherError);
   }
-  /** Bids for the controller lease, and reports who holds it. */
+  /** Tries to acquire the controller lease, and returns whether it succeeded along with the current lease. */
   async tryAcquireControllerLease(input) {
     assertNonEmpty(input.clusterId, "clusterId");
     assertNonEmpty(input.holderId, "holderId");
     assertPositiveTtl(input.ttlMs);
-    const key = controllerLeaseKey(input.clusterId);
-    const lease = this.namespace.lease(ttlMsToSeconds(input.ttlMs));
-    const leaseId = await lease.grant();
-    const grantedAtMs = Date.now();
-    const value = serializeLease({
-      id: leaseId,
-      kind: "controller",
-      clusterId: input.clusterId,
-      holderId: input.holderId,
-      ttlMs: input.ttlMs,
-      grantedAtMs,
-      expiresAtMs: grantedAtMs + input.ttlMs,
-      metadata: cloneMetadata(input.metadata)
-    });
-    const result = await this.namespace.if(key, "Create", "==", 0).then(this.namespace.put(key).value(value).lease(leaseId)).commit();
-    if (!result.succeeded) {
-      await revokeLeaseQuietly(lease);
-      const current = await this.getLeaseFromKey(key);
-      return { acquired: false, lease: current };
-    }
-    this.leases.track(lease, {
-      leaseId,
-      key,
-      ttlMs: input.ttlMs,
-      ttlSeconds: ttlMsToSeconds(input.ttlMs),
-      kind: "controller",
-      clusterId: input.clusterId,
-      holderId: input.holderId,
-      metadata: cloneMetadata(input.metadata)
-    });
-    const parsed = parseLease(value);
-    return { acquired: true, lease: parsed };
+    const { namespace } = await this.connect();
+    return acquireEtcdControllerLease(namespace, this.leases, input);
+  }
+  /** Calls `watcher` with the current controller lease when the watch starts and after each change, and returns a function that stops the watch. */
+  async watchControllerLease(clusterId, watcher) {
+    assertNonEmpty(clusterId, "clusterId");
+    const { namespace } = await this.connect();
+    return watchEtcdControllerLease(namespace, clusterId, watcher, this.watchers, this.onWatcherError);
   }
-  /** Extends a lease, and reports false once it has already lapsed. */
+  /** Extends a lease, and returns false for a lease that is expired or unknown to this coordinator. */
   async renewLease(leaseId, ttlMs) {
     assertNonEmpty(leaseId, "leaseId");
     assertPositiveTtl(ttlMs);
@@ -607,9 +738,10 @@ var EtcdClusterCoordinator = class {
       metadata: cloneMetadata(entry.metadata)
     };
     const value = entry.kind === "node-session" && entry.nodeSession ? JSON.stringify({ ...entry.nodeSession, lease: leaseValue }) : serializeLease(leaseValue);
+    const { namespace } = await this.connect();
     let refreshed;
     try {
-      const result = await this.namespace.if(entry.key, "Lease", "==", leaseId).then(this.namespace.put(entry.key).value(value).ignoreLease()).commit();
+      const result = await namespace.if(entry.key, "Lease", "==", leaseId).then(namespace.put(entry.key).value(value).ignoreLease()).commit();
       refreshed = result.succeeded === true;
     } catch {
       return true;
@@ -621,7 +753,7 @@ var EtcdClusterCoordinator = class {
     entry.ttlMs = ttlMs;
     return true;
   }
-  /** Gives up a lease at once instead of waiting for it to lapse. */
+  /** Deletes a lease's key if the key still refers to that lease, then revokes the lease, and returns whether the delete succeeded. */
   async releaseLease(leaseId) {
     assertNonEmpty(leaseId, "leaseId");
     const entry = this.leases.get(leaseId);
@@ -629,11 +761,12 @@ var EtcdClusterCoordinator = class {
       return false;
     }
     this.leases.forget(leaseId);
-    const currentValue = await this.namespace.get(entry.key).string();
+    const { namespace } = await this.connect();
+    const currentValue = await namespace.get(entry.key).string();
     const currentLeaseId = currentValue ? parseLeaseIdForEntry(entry.kind, currentValue) : null;
     let released = false;
     if (currentLeaseId === leaseId && currentValue) {
-      const result = await this.namespace.if(entry.key, "Value", "==", currentValue).then(this.namespace.delete().key(entry.key)).commit();
+      const result = await namespace.if(entry.key, "Value", "==", currentValue).then(namespace.delete().key(entry.key)).commit();
       released = result.succeeded === true;
     }
     await revokeLeaseQuietly(entry.lease);
@@ -644,8 +777,9 @@ var EtcdClusterCoordinator = class {
     assertNonEmpty(input.clusterId, "clusterId");
     assertNonEmpty(input.nodeId, "nodeId");
     assertPositiveTtl(input.ttlMs);
+    const { namespace } = await this.connect();
     const key = nodeSessionKey(input.clusterId, input.nodeId);
-    const existingRawSession = await this.namespace.get(key).string();
+    const existingRawSession = await namespace.get(key).string();
     if (existingRawSession) {
       const existingSession = parseNodeSession(existingRawSession);
       const supersedesOwnSession = this.grantedNodeSessionLeaseIds.get(key) === existingSession.lease.id;
@@ -653,7 +787,7 @@ var EtcdClusterCoordinator = class {
         throw new CoordinatorError(`Node session '${input.nodeId}' is already registered`);
       }
     }
-    const lease = this.namespace.lease(ttlMsToSeconds(input.ttlMs));
+    const lease = namespace.lease(ttlMsToSeconds(input.ttlMs));
     const leaseId = await lease.grant();
     const grantedAtMs = Date.now();
     const session = {
@@ -677,8 +811,8 @@ var EtcdClusterCoordinator = class {
       metadata: cloneMetadata(input.metadata)
     };
     const rawSession = JSON.stringify(session);
-    const transaction = existingRawSession ? this.namespace.if(key, "Value", "==", existingRawSession) : this.namespace.if(key, "Create", "==", 0);
-    const result = await transaction.then(this.namespace.put(key).value(rawSession).lease(leaseId)).commit();
+    const transaction = existingRawSession ? namespace.if(key, "Value", "==", existingRawSession) : namespace.if(key, "Create", "==", 0);
+    const result = await transaction.then(namespace.put(key).value(rawSession).lease(leaseId)).commit();
     if (!result.succeeded) {
       await revokeLeaseQuietly(lease);
       throw new CoordinatorError(`Node session '${input.nodeId}' registration conflicted with a concurrent write`);
@@ -707,14 +841,21 @@ var EtcdClusterCoordinator = class {
     });
     return parseNodeSession(rawSession);
   }
-  /** Reads one node's session, and returns null once its lease has lapsed. */
+  /** Returns one node's session, or null once its lease expires. */
   async getLiveNodeSession(clusterId, nodeId) {
     assertNonEmpty(clusterId, "clusterId");
     assertNonEmpty(nodeId, "nodeId");
-    const value = await this.namespace.get(nodeSessionKey(clusterId, nodeId)).string();
+    const { namespace } = await this.connect();
+    const value = await namespace.get(nodeSessionKey(clusterId, nodeId)).string();
     return value ? parseNodeSession(value) : null;
   }
-  /** Ends one node's membership at once. */
+  /** Calls `watcher` with the IDs of every node that holds a live session, and returns a function that stops the watch. */
+  async watchNodeSessions(clusterId, watcher) {
+    assertNonEmpty(clusterId, "clusterId");
+    const { namespace } = await this.connect();
+    return watchEtcdNodeSessions(namespace, clusterId, watcher, this.watchers, this.onWatcherError);
+  }
+  /** Ends one node's session at once by releasing its leases. */
   async deregisterNodeSession(clusterId, nodeId) {
     assertNonEmpty(clusterId, "clusterId");
     assertNonEmpty(nodeId, "nodeId");
@@ -722,39 +863,47 @@ var EtcdClusterCoordinator = class {
       await this.releaseLease(leaseId);
     }
   }
-  /** Writes the group's state, which seeds a new group or replaces an existing one. */
-  setReplicationGroupState(input) {
-    return this.groups.setReplicationGroupState(input);
+  /** Writes the group's state, which creates a new group or replaces an existing one. */
+  async setReplicationGroupState(input) {
+    const { groups } = await this.connect();
+    return groups.setReplicationGroupState(input);
   }
-  /** Reads the group's state, and returns null when the group is absent. */
-  getReplicationGroupState(clusterId, groupId) {
-    return this.groups.getReplicationGroupState(clusterId, groupId);
+  /** Returns the group's state, or null when etcd has no state for the group. */
+  async getReplicationGroupState(clusterId, groupId) {
+    const { groups } = await this.connect();
+    return groups.getReplicationGroupState(clusterId, groupId);
   }
-  /** Calls back on each change to the group's state, and returns a function that stops the watch. */
-  watchReplicationGroup(clusterId, groupId, watcher) {
-    return this.groups.watchReplicationGroup(clusterId, groupId, watcher);
+  /** Calls `watcher` with the new state after each change to the group, and returns a function that stops the watch. */
+  async watchReplicationGroup(clusterId, groupId, watcher) {
+    const { groups } = await this.connect();
+    return groups.watchReplicationGroup(clusterId, groupId, watcher);
   }
-  /** Promotes a node only while the group is still at the term the caller read. */
-  compareAndAdvancePrimaryTerm(input) {
-    return this.groups.compareAndAdvancePrimaryTerm(input);
+  /** Makes a node primary and advances the term, but only while the group is still at the term that the caller expects. */
+  async compareAndAdvancePrimaryTerm(input) {
+    const { groups } = await this.connect();
+    return groups.compareAndAdvancePrimaryTerm(input);
   }
-  /** Replaces the group's in-sync set, and optionally moves its durability point. */
-  updateInSyncSet(input) {
-    return this.groups.updateInSyncSet(input);
+  /** Replaces the group's in-sync set with a subset of it, and can advance the durability point. */
+  async updateInSyncSet(input) {
+    const { groups } = await this.connect();
+    return groups.updateInSyncSet(input);
   }
   /** Adds one caught-up node to the in-sync set. */
-  admitNodeToInSyncSet(input) {
-    return this.groups.admitNodeToInSyncSet(input);
+  async admitNodeToInSyncSet(input) {
+    const { groups } = await this.connect();
+    return groups.admitNodeToInSyncSet(input);
   }
-  /** Marks one node as being taken out of service, rebuilt, or quarantined. */
-  updateNodeMaintenance(input) {
-    return this.groups.updateNodeMaintenance(input);
+  /** Sets or clears one node's draining, repairing, and faulted flags. */
+  async updateNodeMaintenance(input) {
+    const { groups } = await this.connect();
+    return groups.updateNodeMaintenance(input);
   }
-  /** Promotes whichever in-sync replica is safe to write. */
-  promoteEligibleReplica(input) {
-    return this.groups.promoteEligibleReplica(input);
+  /** Promotes an eligible in-sync replica, and throws a `NoSafePrimaryError` when no replica qualifies. */
+  async promoteEligibleReplica(input) {
+    const { groups } = await this.connect();
+    return groups.promoteEligibleReplica(input);
   }
-  /** Closes the etcd client and stops every watch. */
+  /** Stops every watch, revokes every lease that this coordinator granted, and closes the etcd client. */
   async close() {
     const watcherCancels = [];
     for (const watcher of this.watchers) {
@@ -764,11 +913,27 @@ var EtcdClusterCoordinator = class {
     await Promise.allSettled(watcherCancels);
     this.grantedNodeSessionLeaseIds.clear();
     await this.leases.revokeAll();
-    this.client.close();
-  }
-  async getLeaseFromKey(key) {
-    const value = await this.namespace.get(key).string();
-    return value ? parseLease(value) : null;
+    const connection = this.connection;
+    if (!connection) return;
+    const opened = await connection.catch(() => null);
+    opened?.client.close();
+  }
+  connect() {
+    if (!this.connection) {
+      this.connection = loadEtcd3Module().then(
+        ({ Etcd3 }) => {
+          const client = new Etcd3(toEtcdOptions(this.options));
+          const namespace = client.namespace(normaliseKeyPrefix(this.options.keyPrefix));
+          const groups = new EtcdGroupStore(namespace, this.watchers, this.onWatcherError);
+          return { client, namespace, groups };
+        },
+        (err) => {
+          this.connection = null;
+          throw err;
+        }
+      );
+    }
+    return this.connection;
   }
 };
 function createEtcdCoordinator(options) {