@delali/sirannon-db 0.1.3 → 0.1.5

package/dist/replication/coordinator/etcd.mjs

@@ -0,0 +1,650 @@
+import { compatibilityAllowsPromotion } from '../../chunk-ER7ODTDA.mjs';
+import { CoordinatorError, NoSafePrimaryError } from '../../chunk-UVMVN3OT.mjs';
+import '../../chunk-O7BHI3CF.mjs';
+import { Etcd3 } from 'etcd3';
+
+var MIN_AUTOMATIC_FAILOVER_VOTERS = 3;
+var EtcdClusterCoordinator = class {
+  client;
+  namespace;
+  onWatcherError;
+  leases = /* @__PURE__ */ new Map();
+  watchers = /* @__PURE__ */ new Set();
+  constructor(options) {
+    assertEtcdOptions(options);
+    this.client = new Etcd3(toEtcdOptions(options));
+    this.namespace = this.client.namespace(normaliseKeyPrefix(options.keyPrefix));
+    this.onWatcherError = options.onWatcherError;
+  }
+  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.trackLease(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 };
+  }
+  async renewLease(leaseId, ttlMs) {
+    assertNonEmpty(leaseId, "leaseId");
+    assertPositiveTtl(ttlMs);
+    const entry = this.leases.get(leaseId);
+    if (!entry) {
+      return false;
+    }
+    try {
+      await entry.lease.keepaliveOnce();
+      const renewedAtMs = Date.now();
+      const leaseValue = {
+        id: leaseId,
+        kind: entry.kind,
+        clusterId: entry.clusterId,
+        holderId: entry.holderId,
+        ttlMs,
+        grantedAtMs: renewedAtMs,
+        expiresAtMs: renewedAtMs + ttlMs,
+        metadata: cloneMetadata(entry.metadata)
+      };
+      const value = entry.kind === "node-session" && entry.nodeSession ? JSON.stringify({ ...entry.nodeSession, lease: leaseValue }) : serializeLease(leaseValue);
+      await this.namespace.put(entry.key).value(value).ignoreLease();
+      entry.ttlMs = ttlMs;
+      return true;
+    } catch {
+      this.leases.delete(leaseId);
+      return false;
+    }
+  }
+  async releaseLease(leaseId) {
+    assertNonEmpty(leaseId, "leaseId");
+    const entry = this.leases.get(leaseId);
+    if (!entry) {
+      return false;
+    }
+    this.leases.delete(leaseId);
+    const currentValue = await this.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();
+      released = result.succeeded === true;
+    }
+    await revokeLeaseQuietly(entry.lease);
+    return released;
+  }
+  async registerNodeSession(input) {
+    assertNonEmpty(input.clusterId, "clusterId");
+    assertNonEmpty(input.nodeId, "nodeId");
+    assertPositiveTtl(input.ttlMs);
+    const key = nodeSessionKey(input.clusterId, input.nodeId);
+    const existingRawSession = await this.namespace.get(key).string();
+    if (existingRawSession) {
+      const existingSession = parseNodeSession(existingRawSession);
+      if (existingSession.lease.expiresAtMs > Date.now()) {
+        throw new CoordinatorError(`Node session '${input.nodeId}' is already registered`);
+      }
+    }
+    const lease = this.namespace.lease(ttlMsToSeconds(input.ttlMs));
+    const leaseId = await lease.grant();
+    const grantedAtMs = Date.now();
+    const session = {
+      clusterId: input.clusterId,
+      nodeId: input.nodeId,
+      lease: {
+        id: leaseId,
+        kind: "node-session",
+        clusterId: input.clusterId,
+        holderId: input.nodeId,
+        ttlMs: input.ttlMs,
+        grantedAtMs,
+        expiresAtMs: grantedAtMs + input.ttlMs,
+        metadata: cloneMetadata(input.metadata)
+      },
+      endpoint: input.endpoint,
+      groupIds: [...input.groupIds ?? []],
+      dataBearing: input.dataBearing ?? true,
+      voting: input.voting ?? true,
+      compatibility: cloneCompatibility(input.compatibility),
+      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();
+    if (!result.succeeded) {
+      await revokeLeaseQuietly(lease);
+      throw new CoordinatorError(`Node session '${input.nodeId}' registration conflicted with a concurrent write`);
+    }
+    this.trackLease(lease, {
+      leaseId,
+      key,
+      ttlMs: input.ttlMs,
+      ttlSeconds: ttlMsToSeconds(input.ttlMs),
+      kind: "node-session",
+      clusterId: input.clusterId,
+      holderId: input.nodeId,
+      metadata: cloneMetadata(input.metadata),
+      nodeSession: {
+        clusterId: session.clusterId,
+        nodeId: session.nodeId,
+        endpoint: session.endpoint,
+        groupIds: [...session.groupIds],
+        dataBearing: session.dataBearing,
+        voting: session.voting,
+        compatibility: cloneCompatibility(session.compatibility),
+        metadata: cloneMetadata(session.metadata)
+      }
+    });
+    return parseNodeSession(rawSession);
+  }
+  async getLiveNodeSession(clusterId, nodeId) {
+    assertNonEmpty(clusterId, "clusterId");
+    assertNonEmpty(nodeId, "nodeId");
+    const value = await this.namespace.get(nodeSessionKey(clusterId, nodeId)).string();
+    return value ? parseNodeSession(value) : null;
+  }
+  async deregisterNodeSession(clusterId, nodeId) {
+    assertNonEmpty(clusterId, "clusterId");
+    assertNonEmpty(nodeId, "nodeId");
+    const key = nodeSessionKey(clusterId, nodeId);
+    for (const [leaseId, entry] of this.leases) {
+      if (entry.key === key) {
+        await this.releaseLease(leaseId);
+      }
+    }
+  }
+  async setReplicationGroupState(input) {
+    const state = buildReplicationGroupState(input);
+    await this.namespace.put(replicationGroupKey(input.clusterId, input.groupId)).value(serializeGroupState(state));
+    return cloneReplicationGroupState(state);
+  }
+  async getReplicationGroupState(clusterId, groupId) {
+    assertNonEmpty(clusterId, "clusterId");
+    assertNonEmpty(groupId, "groupId");
+    const value = await this.namespace.get(replicationGroupKey(clusterId, groupId)).string();
+    return value ? parseGroupState(value) : null;
+  }
+  async watchReplicationGroup(clusterId, groupId, watcher) {
+    assertNonEmpty(clusterId, "clusterId");
+    assertNonEmpty(groupId, "groupId");
+    const key = replicationGroupKey(clusterId, groupId);
+    const etcdWatcher = await this.namespace.watch().key(key).create();
+    this.watchers.add(etcdWatcher);
+    etcdWatcher.on("put", (kv) => {
+      try {
+        watcher(parseGroupState(kv.value.toString("utf8")));
+      } catch (err) {
+        const wrappedErr = err instanceof Error ? err : new Error(String(err));
+        this.onWatcherError?.(wrappedErr);
+      }
+    });
+    etcdWatcher.on("error", (err) => {
+      this.onWatcherError?.(err instanceof Error ? err : new Error(String(err)));
+    });
+    return async () => {
+      this.watchers.delete(etcdWatcher);
+      await etcdWatcher.cancel();
+    };
+  }
+  async compareAndAdvancePrimaryTerm(input) {
+    assertNonEmpty(input.clusterId, "clusterId");
+    assertNonEmpty(input.groupId, "groupId");
+    assertNonNegativeTerm(input.expectedPrimaryTerm);
+    assertNonEmpty(input.nextPrimary.nodeId, "nextPrimary.nodeId");
+    const key = replicationGroupKey(input.clusterId, input.groupId);
+    const currentRaw = await this.namespace.get(key).string();
+    if (!currentRaw) {
+      return { advanced: false, state: null };
+    }
+    const current = parseGroupState(currentRaw);
+    if (current.primaryTerm !== input.expectedPrimaryTerm) {
+      return { advanced: false, state: current };
+    }
+    assertPrimaryInGroup(input.nextPrimary, current.votingDataBearingNodeIds);
+    const next = {
+      ...current,
+      currentPrimary: { ...input.nextPrimary },
+      primaryTerm: current.primaryTerm + 1n,
+      updatedAtMs: Date.now()
+    };
+    markDisplacedPrimaryForRepair(next, current.currentPrimary?.nodeId, input.nextPrimary.nodeId);
+    const nextRaw = serializeGroupState(next);
+    const result = await this.namespace.if(key, "Value", "==", currentRaw).then(this.namespace.put(key).value(nextRaw)).commit();
+    if (result.succeeded) {
+      return { advanced: true, state: cloneReplicationGroupState(next) };
+    }
+    return { advanced: false, state: await this.getReplicationGroupState(input.clusterId, input.groupId) };
+  }
+  async updateInSyncSet(input) {
+    assertNonEmpty(input.clusterId, "clusterId");
+    assertNonEmpty(input.groupId, "groupId");
+    if (input.durabilityPointSeq !== void 0) {
+      assertNonNegativeSeq(input.durabilityPointSeq, "durabilityPointSeq");
+    }
+    const inSyncNodeIds = normaliseNodeIds(input.inSyncNodeIds, "inSyncNodeIds");
+    return this.updateGroupStateWithRetry(input.clusterId, input.groupId, (state) => {
+      assertSubset(inSyncNodeIds, state.votingDataBearingNodeIds, "inSyncNodeIds");
+      assertNoInSyncAdditions(state.inSyncNodeIds, inSyncNodeIds);
+      const durabilityPointSeq = input.durabilityPointSeq !== void 0 && input.durabilityPointSeq > state.durabilityPointSeq ? input.durabilityPointSeq : state.durabilityPointSeq;
+      if (arraysEqual(inSyncNodeIds, state.inSyncNodeIds) && durabilityPointSeq === state.durabilityPointSeq) {
+        return state;
+      }
+      return { ...state, durabilityPointSeq, inSyncNodeIds, updatedAtMs: Date.now() };
+    });
+  }
+  async admitNodeToInSyncSet(input) {
+    assertNonEmpty(input.clusterId, "clusterId");
+    assertNonEmpty(input.groupId, "groupId");
+    assertNonEmpty(input.nodeId, "nodeId");
+    assertNonEmpty(input.sourceNodeId, "sourceNodeId");
+    assertNonNegativeSeq(input.appliedSeq, "appliedSeq");
+    return this.updateGroupStateWithRetry(input.clusterId, input.groupId, (state) => {
+      if (!state.votingDataBearingNodeIds.includes(input.nodeId)) {
+        throw new RangeError(`Node '${input.nodeId}' is not configured for the replication group`);
+      }
+      if (state.currentPrimary?.nodeId !== input.sourceNodeId || state.drainingNodeIds.includes(input.nodeId) || state.faultedNodeIds.includes(input.nodeId) || input.appliedSeq < state.durabilityPointSeq) {
+        return state;
+      }
+      const inSyncNodeIds = state.inSyncNodeIds.includes(input.nodeId) ? state.inSyncNodeIds : [...state.inSyncNodeIds, input.nodeId];
+      const repairingNodeIds = removeNodeId(state.repairingNodeIds, input.nodeId);
+      if (arraysEqual(inSyncNodeIds, state.inSyncNodeIds) && arraysEqual(repairingNodeIds, state.repairingNodeIds)) {
+        return state;
+      }
+      return { ...state, inSyncNodeIds, repairingNodeIds, updatedAtMs: Date.now() };
+    });
+  }
+  async updateNodeMaintenance(input) {
+    assertNonEmpty(input.clusterId, "clusterId");
+    assertNonEmpty(input.groupId, "groupId");
+    assertNonEmpty(input.nodeId, "nodeId");
+    return this.updateGroupStateWithRetry(input.clusterId, input.groupId, (state) => {
+      if (!state.votingDataBearingNodeIds.includes(input.nodeId)) {
+        throw new RangeError(`Node '${input.nodeId}' is not configured for the replication group`);
+      }
+      return {
+        ...state,
+        drainingNodeIds: setMembership(state.drainingNodeIds, input.nodeId, input.draining),
+        repairingNodeIds: setMembership(state.repairingNodeIds, input.nodeId, input.repairing),
+        faultedNodeIds: setMembership(state.faultedNodeIds, input.nodeId, input.faulted),
+        inSyncNodeIds: input.draining === true || input.repairing === true || input.faulted === true ? removeNodeId(state.inSyncNodeIds, input.nodeId) : state.inSyncNodeIds,
+        updatedAtMs: Date.now()
+      };
+    });
+  }
+  async promoteEligibleReplica(input) {
+    assertNonEmpty(input.clusterId, "clusterId");
+    assertNonEmpty(input.groupId, "groupId");
+    const excludedNodeIds = new Set(input.excludeNodeIds ?? []);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const state = await this.getReplicationGroupState(input.clusterId, input.groupId);
+      if (!state) {
+        throw new NoSafePrimaryError(`No replication group '${input.groupId}' is registered`);
+      }
+      if (state.votingDataBearingNodeIds.length < MIN_AUTOMATIC_FAILOVER_VOTERS) {
+        throw new NoSafePrimaryError(
+          `Automatic promotion requires at least ${MIN_AUTOMATIC_FAILOVER_VOTERS} voting data-bearing nodes`
+        );
+      }
+      for (const nodeId of state.votingDataBearingNodeIds) {
+        if (nodeId === state.currentPrimary?.nodeId || excludedNodeIds.has(nodeId)) {
+          continue;
+        }
+        const session = await this.getLiveNodeSession(input.clusterId, nodeId);
+        if (!isEligiblePromotionSession(state, nodeId, session)) {
+          continue;
+        }
+        const advanced = await this.compareAndAdvancePrimaryTerm({
+          clusterId: input.clusterId,
+          groupId: input.groupId,
+          expectedPrimaryTerm: state.primaryTerm,
+          nextPrimary: session.endpoint ? { nodeId, endpoint: session.endpoint } : { nodeId }
+        });
+        if (advanced.advanced && advanced.state) {
+          return advanced.state;
+        }
+      }
+    }
+    throw new NoSafePrimaryError(`No safe primary is available for replication group '${input.groupId}'`);
+  }
+  async close() {
+    const watcherCancels = [];
+    for (const watcher of this.watchers) {
+      watcherCancels.push(watcher.cancel());
+    }
+    this.watchers.clear();
+    await Promise.allSettled(watcherCancels);
+    const leaseRevokes = [];
+    for (const entry of this.leases.values()) {
+      leaseRevokes.push(revokeLeaseQuietly(entry.lease));
+    }
+    this.leases.clear();
+    await Promise.allSettled(leaseRevokes);
+    this.client.close();
+  }
+  async getLeaseFromKey(key) {
+    const value = await this.namespace.get(key).string();
+    return value ? parseLease(value) : null;
+  }
+  trackLease(lease, entry) {
+    const fullEntry = { ...entry, lease };
+    this.leases.set(entry.leaseId, fullEntry);
+    lease.on("lost", (err) => {
+      this.leases.delete(entry.leaseId);
+      this.onWatcherError?.(err instanceof Error ? err : new CoordinatorError(String(err)));
+    });
+  }
+  async updateGroupStateWithRetry(clusterId, groupId, mutate) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      const state = await this.getReplicationGroupState(clusterId, groupId);
+      if (!state) {
+        return null;
+      }
+      const next = mutate(state);
+      if (next === state) {
+        return cloneReplicationGroupState(state);
+      }
+      const result = await this.casGroupState(state, next);
+      if (result.updated) {
+        return result.state;
+      }
+    }
+    throw new CoordinatorError(`Failed to update replication group '${groupId}' after concurrent coordinator writes`);
+  }
+  async casGroupState(previous, next) {
+    const key = replicationGroupKey(previous.clusterId, previous.groupId);
+    const previousRaw = serializeGroupState(previous);
+    const nextRaw = serializeGroupState(next);
+    const result = await this.namespace.if(key, "Value", "==", previousRaw).then(this.namespace.put(key).value(nextRaw)).commit();
+    if (result.succeeded) {
+      return { updated: true, state: cloneReplicationGroupState(next) };
+    }
+    return { updated: false, state: await this.getReplicationGroupState(previous.clusterId, previous.groupId) };
+  }
+};
+function createEtcdCoordinator(options) {
+  return new EtcdClusterCoordinator(options);
+}
+function assertEtcdOptions(options) {
+  const hosts = Array.isArray(options.hosts) ? options.hosts : [options.hosts];
+  if (hosts.length === 0) {
+    throw new TypeError("hosts must contain at least one etcd endpoint");
+  }
+  for (const host of hosts) {
+    assertNonEmpty(host, "hosts entry");
+    if (!options.allowInsecure && !host.startsWith("https://")) {
+      throw new TypeError("production coordinator access requires https etcd endpoints");
+    }
+  }
+  assertNonEmpty(options.keyPrefix, "keyPrefix");
+  if (!options.allowInsecure && !options.credentials) {
+    throw new TypeError("production coordinator access requires TLS credentials");
+  }
+  const hasMtlsIdentity = Boolean(options.credentials?.privateKey && options.credentials.certChain);
+  const hasPasswordAuth = Boolean(options.auth?.username && options.auth.password);
+  if (!options.allowInsecure && !hasMtlsIdentity && !hasPasswordAuth) {
+    throw new TypeError("production coordinator access requires an authenticated Sirannon identity");
+  }
+}
+function toEtcdOptions(options) {
+  const defaultCallTimeoutMs = options.defaultCallTimeoutMs;
+  const defaultCallOptions = defaultCallTimeoutMs ? () => ({ deadline: Date.now() + defaultCallTimeoutMs }) : void 0;
+  return {
+    hosts: options.hosts,
+    credentials: options.credentials,
+    auth: options.auth,
+    grpcOptions: options.grpcOptions,
+    dialTimeout: options.dialTimeoutMs,
+    defaultCallOptions
+  };
+}
+function normaliseKeyPrefix(prefix) {
+  const trimmed = prefix.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (trimmed.length === 0) {
+    throw new TypeError("keyPrefix must not resolve to the etcd root");
+  }
+  return `${trimmed}/`;
+}
+function controllerLeaseKey(clusterId) {
+  return `clusters/${encodeKey(clusterId)}/controller`;
+}
+function nodeSessionKey(clusterId, nodeId) {
+  return `clusters/${encodeKey(clusterId)}/nodes/${encodeKey(nodeId)}`;
+}
+function replicationGroupKey(clusterId, groupId) {
+  return `clusters/${encodeKey(clusterId)}/groups/${encodeKey(groupId)}`;
+}
+function encodeKey(value) {
+  return encodeURIComponent(value);
+}
+function ttlMsToSeconds(ttlMs) {
+  return Math.max(1, Math.ceil(ttlMs / 1e3));
+}
+function buildReplicationGroupState(input) {
+  assertNonEmpty(input.clusterId, "clusterId");
+  assertNonEmpty(input.groupId, "groupId");
+  const votingDataBearingNodeIds = normaliseNodeIds(input.votingDataBearingNodeIds, "votingDataBearingNodeIds");
+  const inSyncNodeIds = normaliseNodeIds(input.inSyncNodeIds ?? [], "inSyncNodeIds");
+  const drainingNodeIds = normaliseNodeIds(input.drainingNodeIds ?? [], "drainingNodeIds");
+  const repairingNodeIds = normaliseNodeIds(input.repairingNodeIds ?? [], "repairingNodeIds");
+  const faultedNodeIds = normaliseNodeIds(input.faultedNodeIds ?? [], "faultedNodeIds");
+  assertNonNegativeTerm(input.primaryTerm ?? 0n);
+  assertNonNegativeSeq(input.durabilityPointSeq ?? 0n, "durabilityPointSeq");
+  assertPrimaryInGroup(input.currentPrimary ?? null, votingDataBearingNodeIds);
+  assertSubset(inSyncNodeIds, votingDataBearingNodeIds, "inSyncNodeIds");
+  assertSubset(drainingNodeIds, votingDataBearingNodeIds, "drainingNodeIds");
+  assertSubset(repairingNodeIds, votingDataBearingNodeIds, "repairingNodeIds");
+  assertSubset(faultedNodeIds, votingDataBearingNodeIds, "faultedNodeIds");
+  return {
+    clusterId: input.clusterId,
+    groupId: input.groupId,
+    votingDataBearingNodeIds,
+    currentPrimary: input.currentPrimary ? { ...input.currentPrimary } : null,
+    primaryTerm: input.primaryTerm ?? 0n,
+    durabilityPointSeq: input.durabilityPointSeq ?? 0n,
+    inSyncNodeIds,
+    drainingNodeIds,
+    repairingNodeIds,
+    faultedNodeIds,
+    compatibility: cloneCompatibility(input.compatibility),
+    updatedAtMs: Date.now()
+  };
+}
+function serializeLease(lease) {
+  return JSON.stringify(lease);
+}
+function parseLease(raw) {
+  const value = JSON.parse(raw);
+  return {
+    ...value,
+    metadata: cloneMetadata(value.metadata)
+  };
+}
+function parseNodeSession(raw) {
+  const value = JSON.parse(raw);
+  return {
+    ...value,
+    lease: parseLease(JSON.stringify(value.lease)),
+    groupIds: [...value.groupIds],
+    compatibility: cloneCompatibility(value.compatibility),
+    metadata: cloneMetadata(value.metadata)
+  };
+}
+function parseLeaseIdForEntry(kind, raw) {
+  try {
+    if (kind === "node-session") {
+      return parseNodeSession(raw).lease.id;
+    }
+    return parseLease(raw).id;
+  } catch {
+    return null;
+  }
+}
+function serializeGroupState(state) {
+  const serialized = {
+    ...state,
+    currentPrimary: state.currentPrimary ? { ...state.currentPrimary } : null,
+    votingDataBearingNodeIds: [...state.votingDataBearingNodeIds],
+    primaryTerm: state.primaryTerm.toString(),
+    durabilityPointSeq: state.durabilityPointSeq.toString(),
+    inSyncNodeIds: [...state.inSyncNodeIds],
+    drainingNodeIds: [...state.drainingNodeIds],
+    repairingNodeIds: [...state.repairingNodeIds],
+    faultedNodeIds: [...state.faultedNodeIds],
+    compatibility: cloneCompatibility(state.compatibility)
+  };
+  return JSON.stringify(serialized);
+}
+function parseGroupState(raw) {
+  const value = JSON.parse(raw);
+  return {
+    ...value,
+    currentPrimary: value.currentPrimary ? { ...value.currentPrimary } : null,
+    votingDataBearingNodeIds: [...value.votingDataBearingNodeIds],
+    primaryTerm: BigInt(value.primaryTerm),
+    durabilityPointSeq: value.durabilityPointSeq !== void 0 ? BigInt(value.durabilityPointSeq) : 0n,
+    inSyncNodeIds: [...value.inSyncNodeIds],
+    drainingNodeIds: [...value.drainingNodeIds],
+    repairingNodeIds: [...value.repairingNodeIds],
+    faultedNodeIds: [...value.faultedNodeIds ?? []],
+    compatibility: cloneCompatibility(value.compatibility)
+  };
+}
+function cloneReplicationGroupState(state) {
+  return {
+    ...state,
+    currentPrimary: state.currentPrimary ? { ...state.currentPrimary } : null,
+    votingDataBearingNodeIds: [...state.votingDataBearingNodeIds],
+    durabilityPointSeq: state.durabilityPointSeq,
+    inSyncNodeIds: [...state.inSyncNodeIds],
+    drainingNodeIds: [...state.drainingNodeIds],
+    repairingNodeIds: [...state.repairingNodeIds],
+    faultedNodeIds: [...state.faultedNodeIds],
+    compatibility: cloneCompatibility(state.compatibility)
+  };
+}
+function isEligiblePromotionSession(state, nodeId, session) {
+  if (!session) {
+    return false;
+  }
+  return session.dataBearing && session.voting && state.inSyncNodeIds.includes(nodeId) && compatibilityAllowsPromotion(state.compatibility, session.compatibility) && !state.drainingNodeIds.includes(nodeId) && !state.repairingNodeIds.includes(nodeId) && !state.faultedNodeIds.includes(nodeId);
+}
+function normaliseNodeIds(nodeIds, name) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const nodeId of nodeIds) {
+    assertNonEmpty(nodeId, `${name} entry`);
+    if (seen.has(nodeId)) {
+      throw new RangeError(`${name} contains duplicate node id '${nodeId}'`);
+    }
+    seen.add(nodeId);
+    result.push(nodeId);
+  }
+  return result;
+}
+function setMembership(values, nodeId, enabled) {
+  if (enabled === void 0) return values;
+  const next = values.filter((value) => value !== nodeId);
+  if (enabled) {
+    next.push(nodeId);
+  }
+  return next;
+}
+function markDisplacedPrimaryForRepair(state, displacedPrimaryId, nextPrimaryId) {
+  if (!displacedPrimaryId || displacedPrimaryId === nextPrimaryId) return;
+  state.inSyncNodeIds = removeNodeId(state.inSyncNodeIds, displacedPrimaryId);
+  state.repairingNodeIds = setMembership(state.repairingNodeIds, displacedPrimaryId, true);
+}
+function removeNodeId(values, nodeId) {
+  return values.filter((value) => value !== nodeId);
+}
+function assertSubset(values, allowed, name) {
+  const allowedSet = new Set(allowed);
+  for (const value of values) {
+    if (!allowedSet.has(value)) {
+      throw new RangeError(`${name} contains node id '${value}' that is not configured for the replication group`);
+    }
+  }
+}
+function assertPrimaryInGroup(primary, votingDataBearingNodeIds) {
+  if (!primary) return;
+  assertNonEmpty(primary.nodeId, "primary.nodeId");
+  if (!votingDataBearingNodeIds.includes(primary.nodeId)) {
+    throw new RangeError(`Primary node '${primary.nodeId}' is not configured for the replication group`);
+  }
+}
+function assertNonNegativeTerm(term) {
+  if (term < 0n) {
+    throw new RangeError("primaryTerm must not be negative");
+  }
+}
+function assertNonNegativeSeq(seq, name) {
+  if (seq < 0n) {
+    throw new RangeError(`${name} must not be negative`);
+  }
+}
+function assertNoInSyncAdditions(previous, next) {
+  const previousSet = new Set(previous);
+  for (const nodeId of next) {
+    if (!previousSet.has(nodeId)) {
+      throw new RangeError(`Node '${nodeId}' cannot be added to the in-sync set without catch-up proof`);
+    }
+  }
+}
+function arraysEqual(left, right) {
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i++) {
+    if (left[i] !== right[i]) return false;
+  }
+  return true;
+}
+function cloneCompatibility(compatibility) {
+  return compatibility ? { ...compatibility } : void 0;
+}
+function cloneMetadata(metadata) {
+  return metadata ? { ...metadata } : void 0;
+}
+function assertPositiveTtl(ttlMs) {
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+    throw new RangeError("ttlMs must be a positive safe integer");
+  }
+}
+function assertNonEmpty(value, name) {
+  if (value.length === 0) {
+    throw new TypeError(`${name} must not be empty`);
+  }
+}
+async function revokeLeaseQuietly(lease) {
+  try {
+    await lease.revoke();
+  } catch {
+    lease.release();
+  }
+}
+
+export { EtcdClusterCoordinator, createEtcdCoordinator };