@delali/sirannon-db 0.1.7 → 0.2.0

package/dist/client/topology.mjs

@@ -0,0 +1,682 @@
+import { DatabaseClient, toBaseUrl, createEndpointTransport, RemoteError, toServerBaseUrl, unrefTimer } from '../chunk-H237TXZW.mjs';
+
+// src/client/cluster-routing.ts
+function clusterRoutingFingerprint(state) {
+  const readEndpoints = state.readEndpoints.map((endpoint) => ({
+    url: endpoint.url,
+    readConcerns: [...endpoint.readConcerns].sort()
+  })).sort((left, right) => left.url.localeCompare(right.url));
+  return JSON.stringify({
+    currentPrimary: state.currentPrimary,
+    primaryTerm: state.primaryTerm,
+    readEndpoints
+  });
+}
+function clusterRoutingChanged(previous, next) {
+  return previous === void 0 || clusterRoutingFingerprint(previous) !== clusterRoutingFingerprint(next);
+}
+function isReadConcernLevel(value) {
+  return value === "local" || value === "majority" || value === "linearizable";
+}
+function parseDiscoveredReadConcerns(value) {
+  if (!Array.isArray(value)) {
+    throw new RemoteError("INVALID_RESPONSE", "Cluster metadata readConcerns must be an array");
+  }
+  const concerns = [];
+  for (const concern of value) {
+    if (!isReadConcernLevel(concern)) {
+      throw new RemoteError("INVALID_RESPONSE", "Cluster metadata contains an invalid read concern");
+    }
+    if (!concerns.includes(concern)) {
+      concerns.push(concern);
+    }
+  }
+  return concerns;
+}
+function toDiscoveredServerBaseUrl(endpoint, databaseId) {
+  try {
+    return toServerBaseUrl(endpoint, databaseId);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new RemoteError("INVALID_RESPONSE", `Cluster metadata contains an unsafe endpoint: ${message}`);
+  }
+}
+function parseClusterRouting(data, databaseId) {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new RemoteError("INVALID_RESPONSE", "Cluster metadata must be an object");
+  }
+  const record = data;
+  if (record.databaseId !== databaseId) {
+    throw new RemoteError("INVALID_RESPONSE", "Cluster metadata database id does not match the request");
+  }
+  if (record.primaryTerm !== void 0 && typeof record.primaryTerm !== "string") {
+    throw new RemoteError("INVALID_RESPONSE", "Cluster metadata primaryTerm must be a string");
+  }
+  let currentPrimary = null;
+  if (record.currentPrimary !== void 0 && record.currentPrimary !== null) {
+    if (typeof record.currentPrimary !== "object" || Array.isArray(record.currentPrimary)) {
+      throw new RemoteError("INVALID_RESPONSE", "Cluster metadata currentPrimary must be an object or null");
+    }
+    const primary = record.currentPrimary;
+    if (typeof primary.endpoint !== "string") {
+      throw new RemoteError("INVALID_RESPONSE", "Cluster metadata currentPrimary.endpoint must be a string");
+    }
+    currentPrimary = toDiscoveredServerBaseUrl(primary.endpoint, databaseId);
+  }
+  const readEndpointsRaw = record.readEndpoints;
+  if (readEndpointsRaw !== void 0 && !Array.isArray(readEndpointsRaw)) {
+    throw new RemoteError("INVALID_RESPONSE", "Cluster metadata readEndpoints must be an array");
+  }
+  const readEndpoints = (readEndpointsRaw ?? []).map((endpointInfo) => {
+    if (typeof endpointInfo !== "object" || endpointInfo === null || Array.isArray(endpointInfo)) {
+      throw new RemoteError("INVALID_RESPONSE", "Cluster metadata read endpoint must be an object");
+    }
+    const endpoint = endpointInfo;
+    if (typeof endpoint.endpoint !== "string") {
+      throw new RemoteError("INVALID_RESPONSE", "Cluster metadata read endpoint URL must be a string");
+    }
+    return {
+      url: toDiscoveredServerBaseUrl(endpoint.endpoint, databaseId),
+      readConcerns: parseDiscoveredReadConcerns(endpoint.readConcerns)
+    };
+  });
+  return {
+    currentPrimary,
+    primaryTerm: record.primaryTerm ?? null,
+    readEndpoints
+  };
+}
+function shouldRefreshRouting(err) {
+  if (!(err instanceof RemoteError)) {
+    return false;
+  }
+  return err.code === "STALE_PRIMARY" || err.code === "AUTHORITY_LOST" || err.code === "COORDINATOR_UNAVAILABLE" || err.code === "NO_SAFE_PRIMARY" || err.code === "CONNECTION_ERROR";
+}
+
+// src/client/topology-subscriptions.ts
+var TopologySubscriptionSet = class {
+  constructor(databaseId, routing, assertOpen) {
+    this.databaseId = databaseId;
+    this.routing = routing;
+    this.assertOpen = assertOpen;
+  }
+  transport = null;
+  transportRequest = null;
+  operation = Promise.resolve();
+  subscriptions = /* @__PURE__ */ new Map();
+  nextSubscriptionId = 0;
+  currentUrl = "";
+  get size() {
+    return this.subscriptions.size;
+  }
+  async subscribe(table, filter, callback, options) {
+    return this.track(
+      (transport) => transport.subscribe(table, filter, callback, options),
+      (transport) => transport.subscribe(table, filter, callback, { onReset: options?.onReset })
+    );
+  }
+  async subscribeLive(name, args, handlers, registryDigest) {
+    const open = (transport) => transport.liveSubscribe(name, args, handlers, registryDigest);
+    return this.track(open, open);
+  }
+  async track(open, reopen) {
+    try {
+      return await this.subscribeOnCurrentEndpoint(open, reopen);
+    } catch (err) {
+      if (this.routing._usesCoordinatorDiscovery() && shouldRefreshRouting(err)) {
+        const hadActiveSubscriptions = this.subscriptions.size > 0;
+        if (!hadActiveSubscriptions) {
+          this.closeTransport();
+        }
+        await this.routing._refreshClusterRouting(this.databaseId);
+        if (!hadActiveSubscriptions) {
+          this.closeTransport();
+        }
+        return this.subscribeOnCurrentEndpoint(open, reopen);
+      }
+      throw err;
+    }
+  }
+  async handleRoutingChanged() {
+    if (!this.routing._usesCoordinatorDiscovery()) return;
+    if (this.subscriptions.size === 0) return;
+    await this.withOperation(() => this.migrateToCurrentEndpoint());
+  }
+  closeAll() {
+    for (const subscription of this.subscriptions.values()) {
+      subscription.active = false;
+      subscription.remote = null;
+    }
+    this.subscriptions.clear();
+    this.closeTransport();
+  }
+  async subscribeOnCurrentEndpoint(open, reopen) {
+    return this.withOperation(async () => {
+      const transport = await this.getTransport(this.routing._getReadConcern());
+      const remote = await open(transport);
+      const subscription = {
+        id: ++this.nextSubscriptionId,
+        reopen,
+        remote,
+        active: true
+      };
+      this.subscriptions.set(subscription.id, subscription);
+      return this.createSubscriptionHandle(subscription);
+    });
+  }
+  createSubscriptionHandle(subscription) {
+    return {
+      unsubscribe: () => {
+        if (!subscription.active) return;
+        subscription.active = false;
+        this.subscriptions.delete(subscription.id);
+        const remote = subscription.remote;
+        subscription.remote = null;
+        remote?.unsubscribe();
+      }
+    };
+  }
+  async migrateToCurrentEndpoint() {
+    this.assertOpen();
+    const subscriptions = [...this.subscriptions.values()].filter((subscription) => subscription.active);
+    if (subscriptions.length === 0) return;
+    const readConcern = this.routing._getReadConcern();
+    const endpoint = await this.routing._getReadEndpoint(this.databaseId, readConcern);
+    this.assertOpen();
+    if (this.transport && this.currentUrl === endpoint) {
+      return;
+    }
+    const nextTransport = this.routing._createTransportForEndpoint(endpoint, this.databaseId);
+    const nextSubscriptions = /* @__PURE__ */ new Map();
+    try {
+      for (const subscription of subscriptions) {
+        if (!subscription.active) continue;
+        const remote = await subscription.reopen(nextTransport);
+        if (!subscription.active) {
+          remote.unsubscribe();
+          continue;
+        }
+        nextSubscriptions.set(subscription.id, remote);
+      }
+    } catch (err) {
+      for (const remote of nextSubscriptions.values()) {
+        remote.unsubscribe();
+      }
+      nextTransport.close();
+      throw toSubscriptionRoutingError(err, this.databaseId);
+    }
+    const oldTransport = this.transport;
+    this.transport = nextTransport;
+    this.currentUrl = endpoint;
+    for (const subscription of subscriptions) {
+      const nextRemote = nextSubscriptions.get(subscription.id);
+      if (!nextRemote) continue;
+      const previousRemote = subscription.remote;
+      if (!subscription.active) {
+        nextRemote.unsubscribe();
+        continue;
+      }
+      subscription.remote = nextRemote;
+      previousRemote?.unsubscribe();
+    }
+    if (oldTransport) {
+      oldTransport.close();
+    }
+  }
+  async getTransport(readConcern) {
+    this.assertOpen();
+    if (this.transport) {
+      return this.transport;
+    }
+    while (this.transportRequest) {
+      await this.transportRequest.catch(() => void 0);
+      this.assertOpen();
+      if (this.transport) {
+        return this.transport;
+      }
+    }
+    const request = this.resolveTransport(readConcern);
+    this.transportRequest = request;
+    try {
+      return await request;
+    } finally {
+      if (this.transportRequest === request) {
+        this.transportRequest = null;
+      }
+    }
+  }
+  async resolveTransport(readConcern) {
+    if (this.transport) {
+      return this.transport;
+    }
+    const endpoint = await this.routing._getReadEndpoint(this.databaseId, readConcern);
+    this.assertOpen();
+    if (this.transport) {
+      return this.transport;
+    }
+    this.transport = this.routing._createTransportForEndpoint(endpoint, this.databaseId);
+    this.currentUrl = endpoint;
+    return this.transport;
+  }
+  closeTransport() {
+    if (this.transport) {
+      this.transport.close();
+      this.transport = null;
+    }
+    this.currentUrl = "";
+  }
+  async withOperation(operation) {
+    const previous = this.operation;
+    let release = () => {
+    };
+    this.operation = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous.catch(() => void 0);
+    try {
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+};
+function toSubscriptionRoutingError(err, databaseId) {
+  return new RemoteError(
+    "ROUTING_ERROR",
+    `Could not re-establish active subscriptions on refreshed routing for database '${databaseId}': ${err instanceof Error ? err.message : String(err)}`
+  );
+}
+
+// src/client/topology-transport.ts
+var TopologyAwareTransport = class {
+  constructor(databaseId, routing, onClose) {
+    this.databaseId = databaseId;
+    this.routing = routing;
+    this.onClose = onClose;
+    this.subscriptionSet = new TopologySubscriptionSet(databaseId, routing, () => this.assertOpen());
+  }
+  closed = false;
+  readTransport = null;
+  writeTransport = null;
+  readTransportRequest = null;
+  writeTransportRequest = null;
+  subscriptionSet;
+  currentReadUrl = "";
+  currentWriteUrl = "";
+  async query(sql, params) {
+    const readConcern = this.routing._getReadConcern();
+    const transport = await this.getReadTransport(readConcern);
+    const endpointUsed = this.currentReadUrl;
+    try {
+      return await transport.query(sql, params, readConcern ? { level: readConcern } : void 0);
+    } catch (err) {
+      if (this.routing._usesCoordinatorDiscovery() && shouldRefreshRouting(err)) {
+        await this.routing._refreshClusterRouting(this.databaseId);
+        this.readTransport = null;
+        this.currentReadUrl = "";
+        const refreshed = await this.getReadTransport(readConcern);
+        return refreshed.query(sql, params, readConcern ? { level: readConcern } : void 0);
+      }
+      const isTransportError = err instanceof Error && (err.name !== "RemoteError" || err.code === "CONNECTION_ERROR");
+      const writeEndpoint = await this.routing._getWriteEndpoint(this.databaseId);
+      if (isTransportError && endpointUsed && endpointUsed !== writeEndpoint) {
+        this.routing._removeReplica(endpointUsed);
+        if (this.currentReadUrl === endpointUsed) {
+          this.readTransport = null;
+          this.currentReadUrl = "";
+        }
+        const fallback = await this.getReadTransport();
+        return fallback.query(sql, params);
+      }
+      throw err;
+    }
+  }
+  async execute(sql, params) {
+    return this.onWriteTransport((transport) => transport.execute(sql, params));
+  }
+  async transaction(statements) {
+    return this.onWriteTransport((transport) => transport.transaction(statements));
+  }
+  async batch(sql, paramsBatch, writeConcern) {
+    return this.onWriteTransport((transport) => transport.batch(sql, paramsBatch, writeConcern));
+  }
+  async load(sql, paramsBatch, durability, checkpoint) {
+    return this.onWriteTransport((transport) => transport.load(sql, paramsBatch, durability, checkpoint));
+  }
+  async onWriteTransport(operation) {
+    const transport = await this.getWriteTransport();
+    try {
+      return await operation(transport);
+    } catch (err) {
+      if (this.routing._usesCoordinatorDiscovery() && shouldRefreshRouting(err)) {
+        await this.routing._refreshClusterRouting(this.databaseId);
+        this.writeTransport = null;
+        this.currentWriteUrl = "";
+      }
+      throw err;
+    }
+  }
+  async queryNamed(name, args) {
+    const readConcern = this.routing._getReadConcern();
+    const transport = await this.getReadTransport(readConcern);
+    return transport.queryNamed(name, args, readConcern ? { level: readConcern } : void 0);
+  }
+  async executeNamed(name, args, writeConcern) {
+    return this.onWriteTransport((transport) => transport.executeNamed(name, args, writeConcern));
+  }
+  async liveSubscribe(name, args, handlers, registryDigest) {
+    return this.subscriptionSet.subscribeLive(name, args, handlers, registryDigest);
+  }
+  async subscribe(table, filter, callback, options) {
+    return this.subscriptionSet.subscribe(table, filter, callback, options);
+  }
+  async _handleClusterRoutingChanged() {
+    await this.subscriptionSet.handleRoutingChanged();
+  }
+  close() {
+    this.closed = true;
+    const sameTransport = this.readTransport !== null && this.readTransport === this.writeTransport;
+    this.subscriptionSet.closeAll();
+    if (this.readTransport) {
+      this.readTransport.close();
+      this.readTransport = null;
+    }
+    if (this.writeTransport && !sameTransport) {
+      this.writeTransport.close();
+    }
+    this.writeTransport = null;
+    this.onClose(this);
+  }
+  async getReadTransport(readConcern) {
+    this.assertOpen();
+    while (this.readTransportRequest) {
+      await this.readTransportRequest.catch(() => void 0);
+      this.assertOpen();
+    }
+    const request = this.resolveReadTransport(readConcern);
+    this.readTransportRequest = request;
+    try {
+      return await request;
+    } finally {
+      if (this.readTransportRequest === request) {
+        this.readTransportRequest = null;
+      }
+    }
+  }
+  async resolveReadTransport(readConcern) {
+    const endpoint = await this.routing._getReadEndpoint(this.databaseId, readConcern);
+    this.assertOpen();
+    if (this.readTransport && this.currentReadUrl === endpoint) {
+      return this.readTransport;
+    }
+    const nextTransport = this.routing._createTransportForEndpoint(endpoint, this.databaseId);
+    const oldTransport = this.readTransport;
+    this.readTransport = nextTransport;
+    this.currentReadUrl = endpoint;
+    if (oldTransport) {
+      oldTransport.close();
+    }
+    return this.readTransport;
+  }
+  async getWriteTransport() {
+    this.assertOpen();
+    while (this.writeTransportRequest) {
+      await this.writeTransportRequest.catch(() => void 0);
+      this.assertOpen();
+    }
+    const request = this.resolveWriteTransport();
+    this.writeTransportRequest = request;
+    try {
+      return await request;
+    } finally {
+      if (this.writeTransportRequest === request) {
+        this.writeTransportRequest = null;
+      }
+    }
+  }
+  async resolveWriteTransport() {
+    const endpoint = await this.routing._getWriteEndpoint(this.databaseId);
+    this.assertOpen();
+    if (this.writeTransport && this.currentWriteUrl === endpoint) {
+      return this.writeTransport;
+    }
+    const nextTransport = this.routing._createTransportForEndpoint(endpoint, this.databaseId);
+    const oldTransport = this.writeTransport;
+    this.writeTransport = nextTransport;
+    this.currentWriteUrl = endpoint;
+    if (oldTransport) {
+      oldTransport.close();
+    }
+    return this.writeTransport;
+  }
+  assertOpen() {
+    if (this.closed) {
+      throw new RemoteError("TRANSPORT_ERROR", "Transport is closed");
+    }
+  }
+};
+
+// src/client/topology.ts
+var CLUSTER_DISCOVERY_FETCH_TIMEOUT_MS = 2e3;
+var LATENCY_TTL_MS = 6e4;
+var LATENCY_PROBE_TIMEOUT_MS = 5e3;
+var TopologyAwareClient = class extends DatabaseClient {
+  baseUrl;
+  primaryUrl;
+  replicaUrls;
+  readPreference;
+  discovery;
+  readConcern;
+  starterEndpoints;
+  clusterRouting = /* @__PURE__ */ new Map();
+  topologyTransports = /* @__PURE__ */ new Map();
+  latencies = [];
+  latencyMeasuredAt = 0;
+  latencyMeasuring = null;
+  removedReplicas = /* @__PURE__ */ new Set();
+  constructor(options) {
+    super(options);
+    this.primaryUrl = options.primary ? toBaseUrl(options.primary) : void 0;
+    this.replicaUrls = (options.replicas ?? []).map(toBaseUrl);
+    this.readPreference = options.readPreference ?? "primary";
+    this.discovery = options.discovery ?? "static";
+    this.readConcern = options.readConcern;
+    this.starterEndpoints = (options.endpoints ?? []).map(toBaseUrl);
+    this.baseUrl = this.primaryUrl ?? this.replicaUrls[0] ?? this.starterEndpoints[0] ?? "";
+  }
+  createTransport(databaseId) {
+    const transport = new TopologyAwareTransport(
+      databaseId,
+      this,
+      (closing) => this.unregisterTopologyTransport(databaseId, closing)
+    );
+    this.topologyTransports.set(databaseId, transport);
+    return transport;
+  }
+  _createTransportForEndpoint(url, databaseId) {
+    return createEndpointTransport(this.settings, url, databaseId);
+  }
+  async resolveServerUrl(databaseId) {
+    return this._getWriteEndpoint(databaseId);
+  }
+  async _getReadEndpoint(databaseId, readConcern) {
+    if (this.discovery === "coordinator" && databaseId) {
+      return this.routedReadEndpoint(databaseId, readConcern);
+    }
+    if (this.readPreference === "primary") {
+      return this.primaryUrl ?? this.baseUrl;
+    }
+    const availableReplicas = this.replicaUrls.filter((url) => !this.removedReplicas.has(url));
+    if (this.readPreference === "replica") {
+      if (availableReplicas.length === 0) {
+        return this.primaryUrl ?? this.baseUrl;
+      }
+      return availableReplicas[Math.floor(Math.random() * availableReplicas.length)];
+    }
+    await this.ensureLatencyMeasured();
+    const reachable = this.latencies.filter((entry) => entry.reachable && !this.removedReplicas.has(entry.url));
+    if (reachable.length === 0) {
+      return this.primaryUrl ?? this.baseUrl;
+    }
+    reachable.sort((left, right) => left.latencyMs - right.latencyMs);
+    return reachable[0].url;
+  }
+  async routedReadEndpoint(databaseId, readConcern) {
+    const routing = await this.ensureClusterRouting(databaseId);
+    const concern = readConcern ?? this.readConcern ?? "majority";
+    if (concern === "linearizable") {
+      if (routing.currentPrimary) return routing.currentPrimary;
+      throw new RemoteError("NO_SAFE_PRIMARY", "No current primary is available for linearizable reads");
+    }
+    const readable = routing.readEndpoints.filter((endpoint) => endpoint.readConcerns.includes(concern));
+    const preferredReadable = this.readPreference === "replica" && routing.currentPrimary ? readable.filter((endpoint) => endpoint.url !== routing.currentPrimary) : readable;
+    if (this.readPreference !== "primary" && preferredReadable.length > 0) {
+      if (this.readPreference === "nearest") {
+        return preferredReadable[0].url;
+      }
+      return preferredReadable[Math.floor(Math.random() * preferredReadable.length)].url;
+    }
+    if (routing.currentPrimary) return routing.currentPrimary;
+    const localReadable = routing.readEndpoints.find((endpoint) => endpoint.readConcerns.includes("local"));
+    if (localReadable) return localReadable.url;
+    throw new RemoteError("ROUTING_ERROR", "No usable read endpoint is available");
+  }
+  async _getWriteEndpoint(databaseId) {
+    if (this.discovery === "coordinator" && databaseId) {
+      const routing = await this.ensureClusterRouting(databaseId);
+      if (!routing.currentPrimary) {
+        throw new RemoteError("NO_SAFE_PRIMARY", "No current primary is available");
+      }
+      return routing.currentPrimary;
+    }
+    return this.primaryUrl ?? this.baseUrl;
+  }
+  _getReadConcern() {
+    return this.readConcern;
+  }
+  _usesCoordinatorDiscovery() {
+    return this.discovery === "coordinator";
+  }
+  _removeReplica(url) {
+    this.removedReplicas.add(url);
+  }
+  async _refreshClusterRouting(databaseId) {
+    const encodedId = encodeURIComponent(databaseId);
+    for (const endpoint of this.clusterDiscoveryCandidates(databaseId)) {
+      const next = await this.fetchClusterRouting(toServerBaseUrl(endpoint, databaseId), encodedId, databaseId);
+      if (!next) continue;
+      const previous = this.clusterRouting.get(databaseId);
+      this.clusterRouting.set(databaseId, next);
+      if (clusterRoutingChanged(previous, next)) {
+        try {
+          await this.notifyClusterRoutingChanged(databaseId);
+        } catch (err) {
+          if (previous) {
+            this.clusterRouting.set(databaseId, previous);
+          } else {
+            this.clusterRouting.delete(databaseId);
+          }
+          throw err;
+        }
+      }
+      return;
+    }
+    throw new RemoteError("ROUTING_ERROR", `Could not discover cluster routing for database '${databaseId}'`);
+  }
+  async fetchClusterRouting(base, encodedId, databaseId) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CLUSTER_DISCOVERY_FETCH_TIMEOUT_MS);
+    unrefTimer(timeout);
+    try {
+      const response = await fetch(`${base}/db/${encodedId}/cluster`, {
+        headers: this.settings.headers,
+        signal: controller.signal
+      });
+      if (!response.ok) return null;
+      return parseClusterRouting(await response.json(), databaseId);
+    } catch (err) {
+      if (err instanceof RemoteError && err.code === "INVALID_RESPONSE") {
+        throw err;
+      }
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  async ensureClusterRouting(databaseId) {
+    const existing = this.clusterRouting.get(databaseId);
+    if (existing) return existing;
+    await this._refreshClusterRouting(databaseId);
+    const refreshed = this.clusterRouting.get(databaseId);
+    if (!refreshed) {
+      throw new RemoteError("ROUTING_ERROR", `Could not discover cluster routing for database '${databaseId}'`);
+    }
+    return refreshed;
+  }
+  clusterDiscoveryCandidates(databaseId) {
+    const candidates = /* @__PURE__ */ new Set();
+    for (const endpoint of this.starterEndpoints) candidates.add(endpoint);
+    if (this.primaryUrl) candidates.add(this.primaryUrl);
+    for (const endpoint of this.replicaUrls) candidates.add(endpoint);
+    const existing = this.clusterRouting.get(databaseId);
+    if (existing?.currentPrimary) candidates.add(existing.currentPrimary);
+    for (const endpoint of existing?.readEndpoints ?? []) candidates.add(endpoint.url);
+    if (this.baseUrl) candidates.add(this.baseUrl);
+    return [...candidates];
+  }
+  async ensureLatencyMeasured() {
+    if (this.latencies.length > 0 && Date.now() - this.latencyMeasuredAt < LATENCY_TTL_MS) {
+      return;
+    }
+    if (this.latencyMeasuring) {
+      await this.latencyMeasuring;
+      return;
+    }
+    this.latencyMeasuring = this.measureLatencies();
+    try {
+      await this.latencyMeasuring;
+    } finally {
+      this.latencyMeasuring = null;
+    }
+  }
+  async measureLatencies() {
+    const allEndpoints = [];
+    if (this.primaryUrl) {
+      allEndpoints.push(this.primaryUrl);
+    }
+    for (const replica of this.replicaUrls) {
+      allEndpoints.push(replica);
+    }
+    this.latencies = await Promise.all(allEndpoints.map((url) => measureEndpointLatency(url)));
+    this.latencyMeasuredAt = Date.now();
+  }
+  unregisterTopologyTransport(databaseId, transport) {
+    if (this.topologyTransports.get(databaseId) === transport) {
+      this.topologyTransports.delete(databaseId);
+    }
+  }
+  async notifyClusterRoutingChanged(databaseId) {
+    const transport = this.topologyTransports.get(databaseId);
+    if (!transport) return;
+    await transport._handleClusterRoutingChanged();
+  }
+};
+async function measureEndpointLatency(url) {
+  const start = performance.now();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LATENCY_PROBE_TIMEOUT_MS);
+  unrefTimer(timeout);
+  try {
+    const response = await fetch(`${url}/health`, { signal: controller.signal });
+    if (!response.ok) {
+      return { url, latencyMs: Number.MAX_SAFE_INTEGER, reachable: false };
+    }
+    return { url, latencyMs: performance.now() - start, reachable: true };
+  } catch {
+    return { url, latencyMs: Number.MAX_SAFE_INTEGER, reachable: false };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export { TopologyAwareClient };