okmodel 0.4.0 → 0.5.0

package/dist/shared/nkc9sfqb.js

@@ -0,0 +1,1161 @@
+import {
+  isConnectionFailure
+} from "./tbszx8mz.js";
+import {
+  createClient
+} from "./bt9sfq0z.js";
+import {
+  OkmError2
+} from "./52szzakm.js";
+
+// src/runtime/topology.ts
+var CIRCUIT_AT = 2;
+var BACKOFF_CAP_MS = 30000;
+var DEFAULT_PROBE_MS = 1000;
+var CAPABILITY_SQL = "select case when to_regprocedure('pg_last_wal_replay_lsn()') is null then false when to_regprocedure('pg_current_wal_insert_lsn()') is null then false else has_function_privilege(to_regprocedure('pg_last_wal_replay_lsn()'), 'execute') and has_function_privilege(to_regprocedure('pg_current_wal_insert_lsn()'), 'execute') end";
+var HEALTH_SQL = "select 1, pg_last_wal_replay_lsn()::text";
+var HEALTH_TIME_SQL = "select 1, pg_last_wal_replay_lsn()::text, pg_last_xact_replay_timestamp()::text";
+var INSERT_LSN_SQL = "select pg_current_wal_insert_lsn()::text";
+var PING_SQL = "select 1";
+var SELECT_NAMES = ["weighted", "roundRobin", "leastConnections", "latencyAware"];
+var LATENCY_ALPHA = 0.2;
+var ROUTING_KEYS = "probe, select, fallback, consistency, maxLag";
+var handles = new WeakMap;
+async function connectTopology(target, options, open) {
+  if (Object.prototype.hasOwnProperty.call(options.schema.model, "using")) {
+    throw new OkmError2("OKM1120", 'Table "using" collides with client.using(). Rename the table.');
+  }
+  refuseRouting(options.routing);
+  const consistency = readConsistency(options.routing?.consistency);
+  const maxLag = readMaxLag(options.routing?.maxLag);
+  const select = readSelect(options.routing?.select);
+  const primaryUrl = readPrimary(target);
+  const replicas = readReplicas(target);
+  const probeMs = readProbe(options.routing?.probe);
+  const defaults = driverFields(options);
+  const opened = [];
+  try {
+    opened.push(await openEndpoint(open, primaryUrl, defaults.max, defaults, "primary", "primary", 1, probeMs));
+    for (let index = 0;index < replicas.length; index += 1) {
+      const replica = replicas[index];
+      if (replica === undefined)
+        continue;
+      const name = replica.name ?? `replica-${String(index + 1)}`;
+      opened.push(await openEndpoint(open, replica.url, replica.max ?? defaults.max, defaults, name, "replica", replica.weight, probeMs));
+    }
+    assertNames(opened);
+    await Promise.all(opened.map((endpoint) => detectPosition(endpoint)));
+    const replicaEndpoints = opened.filter((endpoint) => endpoint.role === "replica");
+    const handle = {
+      closed: false,
+      probeMs,
+      consistency,
+      maxLag,
+      hasReplicas: replicaEndpoints.length > 0,
+      watermark: undefined,
+      positionUnknown: false,
+      unknownEpoch: 0,
+      primaryLsn: undefined,
+      fallback: readFallback(options.routing?.fallback),
+      select,
+      rrLast: undefined,
+      scratch: [],
+      onRoute: options.onRoute,
+      replicaState: options.replicaState,
+      endpoints: opened,
+      closing: undefined
+    };
+    await Promise.all([
+      ...replicaEndpoints.map((endpoint) => sample(handle, endpoint)),
+      samplePrimary(handle)
+    ]);
+    for (const endpoint of replicaEndpoints) {
+      endpoint.nextDelayMs = delayFor(probeMs, endpoint);
+      schedule(handle, endpoint);
+    }
+    schedulePrimary(handle);
+    const primary = opened[0];
+    if (primary === undefined) {
+      throw new OkmError2("OKM1120", "A topology needs one primary URL.");
+    }
+    const shared = {
+      http: options.errors?.http,
+      includeValues: options.errors?.includeValues,
+      logger: options.logger,
+      signal: options.signal,
+      timeout: options.timeout,
+      timeouts: options.timeouts,
+      hookm: options.hookm,
+      catalog: options.catalog,
+      catalogDir: options.catalogDir,
+      requireMeta: options.requireMeta,
+      generators: options.generators
+    };
+    const router = routePool(handle);
+    const client = createClient(options.schema, router, { ownsPool: true, ...shared });
+    const routed = client;
+    routed.using = (route) => derive(options.schema, handle, router, shared, route);
+    handles.set(routed, handle);
+    return routed;
+  } catch (error) {
+    for (const endpoint of opened) {
+      if (endpoint.timer !== undefined)
+        clearTimeout(endpoint.timer);
+      endpoint.timer = undefined;
+    }
+    await Promise.all(opened.map((endpoint) => endpoint.pool.close()));
+    throw error;
+  }
+}
+function refuseRouting(routing) {
+  if (routing === undefined)
+    return;
+  if (typeof routing !== "object" || routing === null || Array.isArray(routing)) {
+    throw new OkmError2("OKM1120", `routing must be an object. Accepted keys: ${ROUTING_KEYS}.`);
+  }
+  for (const key of Object.keys(routing)) {
+    if (key === "probe" || key === "fallback" || key === "select" || key === "consistency" || key === "maxLag") {
+      continue;
+    }
+    throw new OkmError2("OKM1120", `routing.${key} is not a routing option. Accepted keys: ${ROUTING_KEYS}.`);
+  }
+}
+function readSelect(value) {
+  if (value === undefined)
+    return "weighted";
+  if (typeof value === "function")
+    return value;
+  if (typeof value === "string" && isSelectName(value))
+    return value;
+  throw new OkmError2("OKM1120", `routing.select must be "${SELECT_NAMES.join('", "')}", or a function.`);
+}
+function isSelectName(value) {
+  return SELECT_NAMES.includes(value);
+}
+function readConsistency(value) {
+  if (value === undefined || value === "session")
+    return "session";
+  if (value === "eventual")
+    return "eventual";
+  throw new OkmError2("OKM1120", `routing.consistency must be "session" or "eventual". ${shown(value)} is not one of those.`);
+}
+function readMaxLag(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string") {
+    throw new OkmError2("OKM1120", maxLagMessage(shown(value)));
+  }
+  const text = value.trim();
+  const time = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(text);
+  if (time !== null) {
+    const amount = Number(time[1]);
+    const unit = time[2];
+    if (!Number.isFinite(amount) || amount < 0 || unit === undefined) {
+      throw new OkmError2("OKM1120", maxLagMessage(value));
+    }
+    const ms = unit === "ms" ? amount : unit === "s" ? amount * 1000 : amount * 60000;
+    return { kind: "time", ms };
+  }
+  const size = /^(\d+(?:\.\d+)?)(B|KB|MB|GB)$/.exec(text);
+  if (size !== null) {
+    const amount = Number(size[1]);
+    const unit = size[2];
+    if (!Number.isFinite(amount) || amount < 0 || unit === undefined) {
+      throw new OkmError2("OKM1120", maxLagMessage(value));
+    }
+    return { kind: "bytes", bytes: scaleBytes(amount, unit) };
+  }
+  throw new OkmError2("OKM1120", maxLagMessage(value));
+}
+function maxLagMessage(value) {
+  return `routing.maxLag must be a duration ("5s", "500ms", "2m") or a size ("16MB", "512KB", "1GB", "4096B"). ${value} is not one of those forms.`;
+}
+function scaleBytes(amount, unit) {
+  const scale = unit === "B" ? 1n : unit === "KB" ? 1024n : unit === "MB" ? 1048576n : 1073741824n;
+  if (Number.isInteger(amount))
+    return BigInt(amount) * scale;
+  return BigInt(Math.trunc(amount * Number(scale)));
+}
+function readPrimary(target) {
+  const value = fields(target);
+  for (const key of Object.keys(value)) {
+    if (key !== "primary" && key !== "replicas") {
+      throw new OkmError2("OKM1120", `Topology key ${key} is not accepted. Accepted keys: primary, replicas.`);
+    }
+  }
+  const primary = value.primary;
+  if (typeof primary !== "string" || primary.length === 0) {
+    throw new OkmError2("OKM1120", "A topology needs one primary URL. Accepted shape: { primary, replicas }.");
+  }
+  return primary;
+}
+function readReplicas(target) {
+  const value = fields(target).replicas;
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    throw new OkmError2("OKM1120", "replicas must be an array of URLs or { url, weight, name, pool }.");
+  }
+  return value.map((entry, index) => readReplica(entry, index));
+}
+function readReplica(entry, index) {
+  if (typeof entry === "string") {
+    if (entry.length === 0) {
+      throw new OkmError2("OKM1120", `replicas[${String(index)}] is an empty URL.`);
+    }
+    return { url: entry, weight: 1, name: undefined, max: undefined };
+  }
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new OkmError2("OKM1120", `replicas[${String(index)}] must be a URL or { url, weight, name, pool }.`);
+  }
+  const value = fields(entry);
+  for (const key of Object.keys(value)) {
+    if (key !== "url" && key !== "weight" && key !== "name" && key !== "pool") {
+      throw new OkmError2("OKM1120", `replicas[${String(index)}].${key} is not accepted. Accepted keys: url, weight, name, pool.`);
+    }
+  }
+  const url = value.url;
+  if (typeof url !== "string" || url.length === 0) {
+    throw new OkmError2("OKM1120", `replicas[${String(index)}] needs a url.`);
+  }
+  return {
+    url,
+    weight: readWeight(value.weight, index),
+    name: readName(value.name, index),
+    max: readPoolMax(value.pool, index)
+  };
+}
+function readWeight(value, index) {
+  if (value === undefined)
+    return 1;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new OkmError2("OKM1120", `replicas[${String(index)}].weight must be a positive number.`);
+  }
+  return value;
+}
+function readName(value, index) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new OkmError2("OKM1120", `replicas[${String(index)}].name must be a non-empty string.`);
+  }
+  return value;
+}
+function readPoolMax(value, index) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new OkmError2("OKM1120", `replicas[${String(index)}].pool must be { max }.`);
+  }
+  const pool = fields(value);
+  for (const key of Object.keys(pool)) {
+    if (key !== "max") {
+      throw new OkmError2("OKM1120", `replicas[${String(index)}].pool.${key} is not accepted. Accepted key: max.`);
+    }
+  }
+  const max = pool.max;
+  if (typeof max !== "number" || !Number.isInteger(max) || max < 1) {
+    throw new OkmError2("OKM1120", `replicas[${String(index)}].pool.max must be a positive integer.`);
+  }
+  return max;
+}
+function readProbe(value) {
+  if (value === undefined)
+    return DEFAULT_PROBE_MS;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new OkmError2("OKM1120", "routing.probe must be a positive number of milliseconds.");
+    }
+    return value;
+  }
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(value.trim());
+  const amount = match?.[1];
+  const unit = match?.[2];
+  if (amount === undefined || unit === undefined) {
+    throw new OkmError2("OKM1120", 'routing.probe must be a number of milliseconds, or "1s", "500ms", or "1m".');
+  }
+  const parsed = Number(amount);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new OkmError2("OKM1120", "routing.probe must be positive.");
+  }
+  if (unit === "ms")
+    return parsed;
+  if (unit === "s")
+    return parsed * 1000;
+  return parsed * 60000;
+}
+function assertNames(endpoints) {
+  const seen = new Set;
+  for (const endpoint of endpoints) {
+    if (seen.has(endpoint.name)) {
+      throw new OkmError2("OKM1120", `Endpoint name ${endpoint.name} is used twice.`);
+    }
+    seen.add(endpoint.name);
+  }
+}
+function driverFields(options) {
+  const value = fields(options);
+  const prepared = value.prepared;
+  return {
+    max: typeof value.max === "number" ? value.max : undefined,
+    timeouts: typeof value.timeouts === "object" && value.timeouts !== null ? value.timeouts : undefined,
+    prepared: prepared === "named" || prepared === "unnamed" ? prepared : undefined,
+    searchPath: typeof value.searchPath === "string" ? value.searchPath : undefined,
+    ssl: value.ssl
+  };
+}
+async function openEndpoint(open, url, max, defaults, name, role, weight, probeMs) {
+  const pool = await open({
+    url,
+    dataDir: url,
+    ...max !== undefined ? { max } : {},
+    ...defaults.timeouts !== undefined ? { timeouts: defaults.timeouts } : {},
+    ...defaults.prepared !== undefined ? { prepared: defaults.prepared } : {},
+    ...defaults.searchPath !== undefined ? { searchPath: defaults.searchPath } : {},
+    ...defaults.ssl !== undefined ? { ssl: defaults.ssl } : {}
+  });
+  return {
+    name,
+    role,
+    weight,
+    max,
+    pool,
+    position: false,
+    circuit: "closed",
+    failures: 0,
+    replayLsn: null,
+    replayPos: undefined,
+    replayAt: null,
+    nextDelayMs: role === "replica" ? probeMs : 0,
+    timer: undefined,
+    current: 0,
+    inflight: 0,
+    latencyMs: null
+  };
+}
+async function detectPosition(endpoint) {
+  try {
+    const result = await endpoint.pool.execute(CAPABILITY_SQL);
+    endpoint.position = truth(result.rows[0]?.[0]);
+  } catch {
+    endpoint.position = false;
+  }
+}
+async function sample(handle, endpoint) {
+  try {
+    const sampled = await readPosition(handle, endpoint);
+    endpoint.failures = 0;
+    endpoint.circuit = "closed";
+    applySample(endpoint, sampled);
+  } catch {
+    endpoint.failures += 1;
+    if (endpoint.failures >= CIRCUIT_AT)
+      endpoint.circuit = "open";
+  }
+}
+async function readPosition(handle, endpoint) {
+  const state = handle.replicaState;
+  const started = performance.now();
+  if (state === undefined) {
+    const sql = handle.maxLag?.kind === "time" ? HEALTH_TIME_SQL : HEALTH_SQL;
+    const result = await endpoint.pool.execute(sql);
+    observe(endpoint, performance.now() - started);
+    const row = result.rows[0];
+    return { lsn: row?.[1] ?? null, time: row?.[2] ?? null };
+  }
+  await endpoint.pool.execute(PING_SQL);
+  observe(endpoint, performance.now() - started);
+  const lsn = await state.replayLsn({ name: endpoint.name });
+  if (typeof lsn !== "string" && lsn !== null) {
+    throw new OkmError2("OKM1120", "ReplicaState.replayLsn must return a WAL position or null.");
+  }
+  return { lsn, time: await seamTime(handle, endpoint, state) };
+}
+async function seamTime(handle, endpoint, state) {
+  if (handle.maxLag?.kind !== "time" || state.replayTime === undefined)
+    return null;
+  const value = await state.replayTime({ name: endpoint.name });
+  if (value instanceof Date)
+    return value.toISOString();
+  if (typeof value === "string" || value === null)
+    return value;
+  throw new OkmError2("OKM1120", "ReplicaState.replayTime must return a timestamp or null.");
+}
+function applySample(endpoint, sampled) {
+  if (sampled.lsn !== null)
+    noteReplay(endpoint, sampled.lsn);
+  if (sampled.time !== null)
+    noteTime(endpoint, sampled.time);
+}
+function noteReplay(endpoint, text) {
+  const pos = parseLsn(text);
+  if (pos === undefined)
+    return;
+  if (endpoint.replayPos !== undefined && pos < endpoint.replayPos)
+    return;
+  endpoint.replayPos = pos;
+  endpoint.replayLsn = text.trim();
+}
+function noteTime(endpoint, text) {
+  const parsed = parseTime(text);
+  if (parsed === undefined)
+    return;
+  endpoint.replayAt = parsed;
+}
+function observe(endpoint, sampleMs) {
+  const previous = endpoint.latencyMs;
+  endpoint.latencyMs = previous === null ? sampleMs : LATENCY_ALPHA * sampleMs + (1 - LATENCY_ALPHA) * previous;
+}
+function delayFor(probeMs, endpoint) {
+  if (endpoint.circuit === "closed")
+    return probeMs;
+  const steps = Math.min(Math.max(endpoint.failures - 1, 1), 8);
+  const delay = probeMs * 2 ** steps;
+  return delay > BACKOFF_CAP_MS ? BACKOFF_CAP_MS : delay;
+}
+function schedule(handle, endpoint) {
+  if (handle.closed || endpoint.role !== "replica")
+    return;
+  const timer = setTimeout(() => {
+    endpoint.timer = undefined;
+    runProbe(handle, endpoint);
+  }, endpoint.nextDelayMs);
+  timer.unref();
+  endpoint.timer = timer;
+}
+function schedulePrimary(handle) {
+  const primary = handle.endpoints[0];
+  if (handle.closed || primary === undefined || !probesPrimary(handle))
+    return;
+  const timer = setTimeout(() => {
+    primary.timer = undefined;
+    runPrimary(handle);
+  }, handle.probeMs);
+  timer.unref();
+  primary.timer = timer;
+}
+async function runPrimary(handle) {
+  if (handle.closed)
+    return;
+  await samplePrimary(handle);
+  if (handle.closed)
+    return;
+  schedulePrimary(handle);
+}
+async function samplePrimary(handle) {
+  if (!probesPrimary(handle))
+    return;
+  const primary = handle.endpoints[0];
+  if (primary === undefined)
+    return;
+  const epoch = handle.unknownEpoch;
+  const wasUnknown = handle.positionUnknown;
+  try {
+    const lsn = await readInsertLsn(primary.pool);
+    if (lsn === undefined)
+      return;
+    if (wasUnknown && handle.unknownEpoch === epoch && handle.positionUnknown) {
+      raiseWatermark(handle, lsn);
+      return;
+    }
+    notePrimary(handle, lsn);
+  } catch {}
+}
+function probesPrimary(handle) {
+  if (!handle.hasReplicas)
+    return false;
+  const primary = handle.endpoints[0];
+  if (primary === undefined || !primary.position)
+    return false;
+  return handle.consistency === "session" || handle.maxLag !== undefined;
+}
+async function runProbe(handle, endpoint) {
+  if (handle.closed)
+    return;
+  await sample(handle, endpoint);
+  if (handle.closed)
+    return;
+  endpoint.nextDelayMs = delayFor(handle.probeMs, endpoint);
+  schedule(handle, endpoint);
+}
+function closeHandle(handle) {
+  handle.closing ??= shutdown(handle);
+  return handle.closing;
+}
+async function shutdown(handle) {
+  handle.closed = true;
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.timer !== undefined)
+      clearTimeout(endpoint.timer);
+    endpoint.timer = undefined;
+  }
+  await Promise.all(handle.endpoints.map((endpoint) => endpoint.pool.close()));
+}
+function routePool(handle) {
+  const primary = handle.endpoints[0];
+  if (primary === undefined) {
+    throw new OkmError2("OKM1120", "A topology needs one primary URL.");
+  }
+  const pool = {
+    capabilities: primary.pool.capabilities,
+    execute: async (text, params, options) => {
+      if (handle.closed)
+        closed();
+      const choice = await choose(handle, text, options?.route);
+      const result = await attempt(handle, choice, (endpoint) => endpoint.pool.execute(text, params, strip(options)));
+      if (choice.op === "write")
+        await noteWrite(handle, primary.pool);
+      return result;
+    },
+    batch: async (statements, options) => {
+      if (handle.closed)
+        closed();
+      if (options?.route === "replica")
+        replicaRefused();
+      const reason = options?.route === "primary" ? "constraint:primary" : "primary-required";
+      tell(handle, { op: "write", endpoint: primary.name, reason });
+      const result = await primary.pool.batch(statements, strip(options));
+      await noteWrite(handle, primary.pool);
+      return result;
+    },
+    stats: () => primary.pool.stats(),
+    close: () => closeHandle(handle)
+  };
+  if (primary.pool.reserve !== undefined) {
+    pool.reserve = async () => {
+      if (handle.closed)
+        closed();
+      tell(handle, { op: "tx", endpoint: primary.name, reason: "primary-required" });
+      return wrap(handle, await primary.pool.reserve());
+    };
+  }
+  if (primary.pool.describe !== undefined) {
+    pool.describe = async (text, params) => {
+      const choice = await choose(handle, text, undefined);
+      tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+      if (choice.endpoint.pool.describe !== undefined) {
+        return choice.endpoint.pool.describe(text, params);
+      }
+      return primary.pool.describe(text, params);
+    };
+  }
+  if (primary.pool.stream !== undefined) {
+    pool.stream = (text, params) => readStream(handle, text, undefined, params, primary.pool);
+  }
+  if (primary.pool.listen !== undefined) {
+    pool.listen = (channel, onNotify) => {
+      tell(handle, { op: "read", endpoint: primary.name, reason: "primary-required" });
+      return primary.pool.listen(channel, onNotify);
+    };
+  }
+  if (primary.pool.cancel !== undefined) {
+    pool.cancel = () => {
+      for (const endpoint of handle.endpoints)
+        endpoint.pool.cancel?.();
+    };
+  }
+  return pool;
+}
+function derive(schema, handle, router, shared, route) {
+  const name = readRoute(route);
+  const client = createClient(schema, force(handle, router, name), { ...shared, ownsPool: false });
+  delete client.close;
+  return client;
+}
+function force(handle, router, route) {
+  const pool = {
+    forcedRoute: route,
+    capabilities: router.capabilities,
+    execute: (text, params, options) => router.execute(text, params, { ...options, route }),
+    batch: (statements, options) => router.batch(statements, { ...options, route }),
+    stats: () => router.stats(),
+    close: () => Promise.resolve()
+  };
+  if (router.reserve !== undefined) {
+    pool.reserve = () => {
+      if (route === "replica")
+        replicaRefused();
+      return router.reserve();
+    };
+  }
+  if (router.describe !== undefined) {
+    pool.describe = async (text, params) => {
+      const choice = await choose(handle, text, route);
+      tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+      if (choice.endpoint.pool.describe !== undefined) {
+        return choice.endpoint.pool.describe(text, params);
+      }
+      return router.describe(text, params);
+    };
+  }
+  if (router.stream !== undefined) {
+    pool.stream = (text, params) => readStream(handle, text, route, params, router);
+  }
+  if (router.listen !== undefined) {
+    pool.listen = (channel, onNotify) => {
+      if (route === "replica")
+        replicaRefused();
+      return router.listen(channel, onNotify);
+    };
+  }
+  if (router.cancel !== undefined)
+    pool.cancel = () => router.cancel();
+  return pool;
+}
+function classOf(text) {
+  const head = text.trimStart().toLowerCase().replace(/\s+/g, " ");
+  if (/^(begin|start transaction|commit|rollback|savepoint|release|set|reset)\b/.test(head)) {
+    return "tx";
+  }
+  if (head.includes("pg_advisory"))
+    return "lock";
+  if (/\sfor (no key update|key share|update|share)\b/.test(head))
+    return "lock";
+  if (/^(insert|update|delete|with|create|alter|drop|truncate|grant|revoke|comment|vacuum|analyze|reindex|copy)\b/.test(head)) {
+    return "write";
+  }
+  return "read";
+}
+async function choose(handle, text, route) {
+  if (route !== undefined && route !== "primary" && route !== "replica") {
+    throw new OkmError2("OKM1120", 'route must be "primary" or "replica".');
+  }
+  const op = classOf(text);
+  const primary = handle.endpoints[0];
+  if (primary === undefined)
+    throw new OkmError2("OKM1120", "A topology needs one primary URL.");
+  if (text.trimStart().toLowerCase().startsWith("select current_setting")) {
+    return { endpoint: primary, op: "read", reason: "primary-required" };
+  }
+  if (route === "replica" && op !== "read")
+    replicaRefused();
+  if (op !== "read") {
+    return {
+      endpoint: primary,
+      op,
+      reason: route === "primary" ? "constraint:primary" : "primary-required"
+    };
+  }
+  if (route === "primary")
+    return { endpoint: primary, op, reason: "constraint:primary" };
+  if (handle.positionUnknown && handle.consistency === "session" && handle.hasReplicas) {
+    if (route === "replica")
+      noReplica();
+    if (handle.fallback === "error")
+      fallbackRefused("position-unknown");
+    return { endpoint: primary, op, reason: "fallback:position-unknown" };
+  }
+  const explicit = route === "replica";
+  const gated = await gate(handle, undefined, !explicit);
+  const replica = pick(handle, gated.ready, !explicit);
+  if (replica !== undefined) {
+    return {
+      endpoint: replica,
+      op,
+      reason: explicit ? "constraint:replica" : `auto:${replica.name}`
+    };
+  }
+  if (explicit)
+    noReplica();
+  if (handle.fallback === "error")
+    fallbackRefused(gated.miss);
+  return { endpoint: primary, op, reason: `fallback:${gated.miss}` };
+}
+async function* readStream(handle, text, route, params, fallback) {
+  const choice = await choose(handle, text, route);
+  tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+  const pool = choice.endpoint.pool.stream !== undefined ? choice.endpoint.pool : fallback;
+  if (pool.stream === undefined)
+    return;
+  yield* pool.stream(text, params);
+}
+async function attempt(handle, choice, run) {
+  tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+  try {
+    return await tracked(choice.endpoint, choice.op === "read", () => run(choice.endpoint));
+  } catch (error) {
+    if (choice.op !== "read" || !isConnectionFailure(error))
+      throw error;
+    const next = await retryOf(handle, choice);
+    if (next === undefined)
+      throw error;
+    tell(handle, { op: "read", endpoint: next.endpoint.name, reason: next.reason });
+    return tracked(next.endpoint, true, () => run(next.endpoint));
+  }
+}
+async function tracked(endpoint, time, run) {
+  const replica = endpoint.role === "replica";
+  if (replica)
+    endpoint.inflight += 1;
+  const started = replica && time ? performance.now() : 0;
+  try {
+    const result = await run();
+    if (replica && time)
+      observe(endpoint, performance.now() - started);
+    return result;
+  } finally {
+    if (replica)
+      endpoint.inflight -= 1;
+  }
+}
+async function retryOf(handle, choice) {
+  if (choice.endpoint.role === "replica")
+    noteFailure(choice.endpoint);
+  const explicit = choice.reason.startsWith("constraint:");
+  const gated = await gate(handle, choice.endpoint, !explicit);
+  const replica = pick(handle, gated.ready, !explicit);
+  if (replica !== undefined) {
+    return {
+      endpoint: replica,
+      op: "read",
+      reason: explicit ? "constraint:replica" : `auto:${replica.name}`
+    };
+  }
+  if (explicit)
+    return;
+  if (handle.fallback === "error")
+    fallbackRefused(gated.miss);
+  const primary = handle.endpoints[0];
+  if (primary === undefined)
+    return;
+  return { endpoint: primary, op: "read", reason: `fallback:${gated.miss}` };
+}
+async function gate(handle, except, capacity) {
+  const healthy = takeHealthy(handle, except);
+  if (healthy.length === 0)
+    return { ready: healthy, miss: emptyReason(handle, capacity) };
+  const lagged = await consistent(handle, healthy);
+  if (lagged.length === 0)
+    return { ready: lagged, miss: "behind" };
+  if (!capacity)
+    return { ready: lagged, miss: "behind" };
+  const room = [];
+  for (const endpoint of lagged) {
+    if (!saturated(endpoint))
+      room.push(endpoint);
+  }
+  if (room.length === 0)
+    return { ready: room, miss: "saturated" };
+  return { ready: room, miss: "behind" };
+}
+function takeHealthy(handle, except) {
+  const scratch = handle.scratch;
+  scratch.length = 0;
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.role !== "replica" || endpoint === except || endpoint.circuit !== "closed") {
+      continue;
+    }
+    scratch.push(endpoint);
+  }
+  const copy = scratch.slice();
+  scratch.length = 0;
+  return copy;
+}
+async function consistent(handle, healthy) {
+  if (!filters(handle))
+    return healthy;
+  const kept = [];
+  for (const endpoint of healthy) {
+    if (freshEnough(handle, endpoint)) {
+      kept.push(endpoint);
+      continue;
+    }
+    if (!endpoint.position)
+      continue;
+    try {
+      applySample(endpoint, await readPosition(handle, endpoint));
+    } catch (error) {
+      if (error instanceof OkmError2)
+        throw error;
+      noteFailure(endpoint);
+      continue;
+    }
+    if (freshEnough(handle, endpoint))
+      kept.push(endpoint);
+  }
+  return kept;
+}
+function filters(handle) {
+  if (handle.maxLag !== undefined)
+    return true;
+  return handle.consistency === "session" && handle.watermark !== undefined;
+}
+function freshEnough(handle, endpoint) {
+  return coversWatermark(handle, endpoint) && coversLag(handle, endpoint);
+}
+function coversWatermark(handle, endpoint) {
+  if (handle.consistency !== "session" || handle.watermark === undefined)
+    return true;
+  if (!endpoint.position)
+    return false;
+  const replay = endpoint.replayPos;
+  if (replay === undefined)
+    return false;
+  return replay >= handle.watermark;
+}
+function coversLag(handle, endpoint) {
+  const lag = handle.maxLag;
+  if (lag === undefined)
+    return true;
+  if (!endpoint.position)
+    return false;
+  if (lag.kind === "bytes") {
+    const diff = byteLag(handle, endpoint);
+    return diff !== null && diff <= lag.bytes;
+  }
+  const ms = timeLag(handle, endpoint);
+  return ms !== null && ms <= lag.ms;
+}
+function saturated(endpoint) {
+  const max = endpoint.max;
+  if (max === undefined)
+    return false;
+  const stats = endpoint.pool.stats();
+  return stats.idle === 0 && stats.waiting > 0 && stats.size >= max;
+}
+function emptyReason(handle, capacity) {
+  let replicas = 0;
+  let healthy = 0;
+  let room = 0;
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.role !== "replica")
+      continue;
+    replicas += 1;
+    if (endpoint.circuit !== "closed")
+      continue;
+    healthy += 1;
+    if (!capacity || !saturated(endpoint))
+      room += 1;
+  }
+  if (replicas === 0)
+    return "no-replicas";
+  if (healthy === 0)
+    return "unhealthy";
+  if (capacity && room === 0)
+    return "saturated";
+  return "unhealthy";
+}
+function pick(handle, candidates, automatic) {
+  if (candidates.length === 0)
+    return;
+  const select = handle.select;
+  if (typeof select === "function") {
+    if (!automatic || candidates.length < 2)
+      return candidates[0];
+    return fromSelect(handle, select, candidates);
+  }
+  if (select === "roundRobin")
+    return roundRobin(handle, candidates);
+  if (select === "leastConnections")
+    return leastConnections(candidates);
+  if (select === "latencyAware")
+    return latencyAware(candidates);
+  return weighted(handle, candidates);
+}
+function weighted(handle, candidates) {
+  const live = new Set(candidates);
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.role === "replica" && !live.has(endpoint))
+      endpoint.current = 0;
+  }
+  const first = candidates[0];
+  if (first === undefined)
+    throw new Error("selection saw no candidate");
+  let best = first;
+  let total = 0;
+  for (const endpoint of candidates) {
+    endpoint.current += endpoint.weight;
+    total += endpoint.weight;
+    if (endpoint.current > best.current)
+      best = endpoint;
+  }
+  best.current -= total;
+  return best;
+}
+function roundRobin(handle, candidates) {
+  const next = after(handle, handle.rrLast, candidates);
+  handle.rrLast = next;
+  return next;
+}
+function after(handle, last, candidates) {
+  const first = candidates[0];
+  if (first === undefined)
+    throw new Error("selection saw no candidate");
+  if (last === undefined)
+    return first;
+  const start = handle.endpoints.indexOf(last);
+  if (start === -1)
+    return first;
+  for (let step = 1;step <= handle.endpoints.length; step += 1) {
+    const endpoint = handle.endpoints[(start + step) % handle.endpoints.length];
+    if (endpoint !== undefined && candidates.includes(endpoint))
+      return endpoint;
+  }
+  return first;
+}
+function leastConnections(candidates) {
+  let best = candidates[0];
+  if (best === undefined)
+    throw new Error("selection saw no candidate");
+  for (let index = 1;index < candidates.length; index += 1) {
+    const endpoint = candidates[index];
+    if (endpoint !== undefined && endpoint.inflight < best.inflight)
+      best = endpoint;
+  }
+  return best;
+}
+function latencyAware(candidates) {
+  let best = candidates[0];
+  if (best === undefined)
+    throw new Error("selection saw no candidate");
+  for (let index = 1;index < candidates.length; index += 1) {
+    const endpoint = candidates[index];
+    if (endpoint !== undefined && lowerLatency(endpoint, best))
+      best = endpoint;
+  }
+  return best;
+}
+function lowerLatency(endpoint, best) {
+  if (endpoint.latencyMs === null)
+    return false;
+  if (best.latencyMs === null)
+    return true;
+  return endpoint.latencyMs < best.latencyMs;
+}
+function fromSelect(handle, select, candidates) {
+  const endpoints = candidates.slice();
+  const offered = [];
+  for (const endpoint of endpoints) {
+    offered.push({
+      name: endpoint.name,
+      weight: endpoint.weight,
+      inflight: endpoint.inflight,
+      latencyMs: endpoint.latencyMs,
+      lag: byteLagNumber(handle, endpoint)
+    });
+  }
+  const returned = select(offered, { op: "read" });
+  if (typeof returned === "string") {
+    const endpoint = endpoints.find((item) => item.name === returned);
+    if (endpoint !== undefined)
+      return endpoint;
+  } else if (offered.includes(returned)) {
+    const index = offered.indexOf(returned);
+    const endpoint = endpoints[index];
+    if (endpoint !== undefined)
+      return endpoint;
+  }
+  throw new OkmError2("OKM1120", `routing.select returned ${shown(returned)}. It must return a candidate or its name.`);
+}
+function shown(value) {
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (value === null)
+    return "null";
+  if (value === undefined)
+    return "undefined";
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    const name = Reflect.get(value, "name");
+    if (typeof name === "string")
+      return `an object named ${JSON.stringify(name)}`;
+    return "an object";
+  }
+  return typeof value;
+}
+function noteFailure(endpoint) {
+  endpoint.failures += 1;
+  if (endpoint.failures >= CIRCUIT_AT)
+    endpoint.circuit = "open";
+}
+function strip(options) {
+  if (options === undefined || options.route === undefined)
+    return options;
+  const { route: _route, ...rest } = options;
+  if (rest.signal === undefined && rest.timeout === undefined)
+    return;
+  return rest;
+}
+async function noteWrite(handle, runner) {
+  if (!tracks(handle))
+    return;
+  const primary = handle.endpoints[0];
+  if (primary === undefined || !primary.position) {
+    markUnknown(handle);
+    return;
+  }
+  try {
+    const lsn = await readInsertLsn(runner);
+    if (lsn === undefined) {
+      markUnknown(handle);
+      return;
+    }
+    raiseWatermark(handle, lsn);
+  } catch {
+    markUnknown(handle);
+  }
+}
+function markUnknown(handle) {
+  handle.positionUnknown = true;
+  handle.unknownEpoch += 1;
+}
+function tracks(handle) {
+  return handle.hasReplicas && handle.consistency === "session";
+}
+async function readInsertLsn(runner) {
+  const result = await runner.execute(INSERT_LSN_SQL);
+  const text = result.rows[0]?.[0];
+  if (text === null || text === undefined)
+    return;
+  return parseLsn(text);
+}
+function notePrimary(handle, lsn) {
+  if (handle.primaryLsn === undefined || lsn > handle.primaryLsn)
+    handle.primaryLsn = lsn;
+}
+function raiseWatermark(handle, lsn) {
+  notePrimary(handle, lsn);
+  if (handle.watermark === undefined || lsn > handle.watermark)
+    handle.watermark = lsn;
+  handle.positionUnknown = false;
+}
+function byteLag(handle, endpoint) {
+  const primary = handle.primaryLsn;
+  const replay = endpoint.replayPos;
+  if (primary === undefined || replay === undefined)
+    return null;
+  if (replay >= primary)
+    return 0n;
+  return primary - replay;
+}
+function byteLagNumber(handle, endpoint) {
+  const diff = byteLag(handle, endpoint);
+  if (diff === null)
+    return null;
+  if (diff > BigInt(Number.MAX_SAFE_INTEGER))
+    return Number.MAX_SAFE_INTEGER;
+  return Number(diff);
+}
+function timeLag(handle, endpoint) {
+  const primary = handle.primaryLsn;
+  const replay = endpoint.replayPos;
+  if (primary === undefined || replay === undefined)
+    return null;
+  if (replay >= primary)
+    return 0;
+  if (endpoint.replayAt === null)
+    return null;
+  const lag = Date.now() - endpoint.replayAt;
+  return lag < 0 ? 0 : lag;
+}
+function parseLsn(text) {
+  const match = /^([0-9A-Fa-f]+)\/([0-9A-Fa-f]+)$/.exec(text.trim());
+  const high = match?.[1];
+  const low = match?.[2];
+  if (high === undefined || low === undefined)
+    return;
+  return (BigInt(`0x${high}`) << 32n) + BigInt(`0x${low}`);
+}
+function parseTime(text) {
+  const direct = Date.parse(text);
+  if (!Number.isNaN(direct))
+    return direct;
+  const iso = Date.parse(text.replace(" ", "T"));
+  if (!Number.isNaN(iso))
+    return iso;
+  return;
+}
+function controlKind(text) {
+  const head = text.trimStart().toLowerCase().replace(/\s+/g, " ");
+  if (/^commit\b/.test(head))
+    return "commit";
+  if (/^rollback\b/.test(head) && !/^rollback\s+to\b/.test(head))
+    return "rollback";
+  return "other";
+}
+function wrap(handle, conn) {
+  let pending = false;
+  return {
+    execute: async (text, params, options) => {
+      if (options?.route === "replica")
+        replicaRefused();
+      const result = await conn.execute(text, params, strip(options));
+      const kind = controlKind(text);
+      if (kind === "commit") {
+        if (pending) {
+          pending = false;
+          await noteWrite(handle, conn);
+        }
+      } else if (kind === "rollback") {
+        pending = false;
+      } else if (classOf(text) === "write") {
+        pending = true;
+      }
+      return result;
+    },
+    batch: async (statements, options) => {
+      if (options?.route === "replica")
+        replicaRefused();
+      const result = await conn.batch(statements, strip(options));
+      pending = true;
+      return result;
+    },
+    release: () => conn.release(),
+    ...conn.cancel !== undefined ? { cancel: () => conn.cancel() } : {}
+  };
+}
+function tell(handle, event) {
+  if (handle.onRoute === undefined)
+    return;
+  try {
+    handle.onRoute(event);
+  } catch {}
+}
+function readRoute(route) {
+  if (route === "primary" || route === "replica")
+    return route;
+  throw new OkmError2("OKM1120", 'using takes "primary" or "replica".');
+}
+function readFallback(value) {
+  if (value === undefined || value === "primary")
+    return "primary";
+  if (value === "error")
+    return "error";
+  throw new OkmError2("OKM1120", 'routing.fallback must be "primary" or "error".');
+}
+function closed() {
+  throw new OkmError2("OKM1120", "The client is closed.");
+}
+function replicaRefused() {
+  throw new OkmError2("OKM1840", "This operation needs the primary.", {
+    fix: {
+      summary: "Run the operation on the primary. Writes, batch, locks, and tx() never go to a replica."
+    }
+  });
+}
+function noReplica() {
+  throw new OkmError2("OKM1843", "No replica is eligible. This call does not read the primary.", {
+    fix: {
+      summary: "Configure a replica or drop the route. This call does not read the primary."
+    }
+  });
+}
+function fallbackRefused(why) {
+  throw new OkmError2("OKM1844", `No replica is eligible (${why}) and fallback is error.`, {
+    fix: {
+      summary: "Restore a replica, or set fallback to primary if the primary should absorb the read."
+    }
+  });
+}
+function truth(value) {
+  return value === "t" || value === "true" || value === "1";
+}
+function fields(value) {
+  return value;
+}
+var topology_default = connectTopology;
+export {
+  topology_default as default
+};