@koralabs/kora-labs-common 6.18.4 → 6.19.0

package/cronLock/cqlCronLock.d.ts

@@ -48,6 +48,8 @@ export declare const isUnknownOutcomeError: (error: unknown) => boolean;
  * concurrent ticks on one node cannot both treat the node identity as ownership.
  */
 export declare const acquireWithExecutor: (executor: CqlExecutor, name: string, offline: string | null | undefined, topology: CronLockTopology, token?: string, lease?: number) => Promise<AcquireResult>;
+/** One fresh process's acquisition: make sure the lock table exists, then take the lock. */
+export declare const acquireOnExecutor: (executor: CqlExecutor, name: string, offline: string | null | undefined, topology: CronLockTopology, lease?: number) => Promise<AcquireResult>;
 export declare const acquire: (name: string, offline?: string | null, options?: {
     leaseMs?: number;
 }) => Promise<AcquireResult>;

package/cronLock/cqlCronLock.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.release = exports.releaseWithExecutor = exports.acquire = exports.acquireWithExecutor = exports.isUnknownOutcomeError = exports.isWriteTimeoutError = exports.isPeerUnavailableError = exports.resolveMode = exports.parseOffline = exports.leaseMs = exports.resolveTopology = void 0;
+exports.release = exports.releaseWithExecutor = exports.acquire = exports.acquireOnExecutor = exports.acquireWithExecutor = exports.isUnknownOutcomeError = exports.isWriteTimeoutError = exports.isPeerUnavailableError = exports.resolveMode = exports.parseOffline = exports.leaseMs = exports.resolveTopology = void 0;
 /**
  * Cross-datacenter cron mutex for the self-hosted, multi-DC Scylla topology.
  * (Moved from minting.handle.me src/helpers/cronLock/cqlCronLock.ts @ 6ecb9c3 so every box cron
@@ -14,9 +14,9 @@ exports.release = exports.releaseWithExecutor = exports.acquire = exports.acquir
  *  - all boxes online: SERIAL / QUORUM;
  *  - this box offline: stand down;
  *  - this box is the only declared-online box: LOCAL_SERIAL / LOCAL_QUORUM;
- *  - an undeclared peer outage: the caller normally fails closed. StateData may
- *    use its DC-local fallback only for mintPaidSessions and only after a definite
- *    CQL UNAVAILABLE response (never after a timeout or unknown failure).
+ *  - an undeclared peer outage: 'peerUnavailable'. Callers whose job is safe on one
+ *    box (on-chain/idempotent) may take a DC-local fallback, and only after this
+ *    definite CQL UNAVAILABLE response (never after a timeout or unknown failure).
  *
  * The row TTL recovers crashed holders. Unique per-invocation owner tokens prevent
  * overlapping ticks on one box from mistaking node identity for lock ownership.
@@ -70,7 +70,7 @@ const leaseSeconds = (override) => Math.ceil((0, exports.leaseMs)(override) / 10
 const scopeName = (name, topology) => `${topology.network}:${name}`;
 let client = null;
 let clientTopologyKey = '';
-let ensured = false;
+const ensured = new WeakSet();
 const getClient = (topology) => {
     const topologyKey = JSON.stringify([topology.contactPoints, topology.localDataCenter]);
     if (!client || clientTopologyKey !== topologyKey) {
@@ -80,17 +80,25 @@ const getClient = (topology) => {
             socketOptions: { connectTimeout: 8000, readTimeout: 12000 }
         });
         clientTopologyKey = topologyKey;
-        ensured = false;
     }
     return client;
 };
+/**
+ * Schema changes need a majority of the whole cluster, so with a peer DC down a CREATE … IF NOT EXISTS
+ * hangs until the driver times out — masking the definite UNAVAILABLE the one-box solo path relies on
+ * (incident 2026-10-07). system_schema is replicated to every node (LocalStrategy), so reading it
+ * needs no peer; DDL is issued only on a cluster that really lacks the table.
+ */
 const ensureSchema = async (executor) => {
-    if (ensured)
+    if (ensured.has(executor))
         return;
-    await executor.execute(`CREATE KEYSPACE IF NOT EXISTS ${KEYSPACE} WITH replication = ` +
-        `{'class':'NetworkTopologyStrategy','kora-dc1':1,'kora-dc2':1}`);
-    await executor.execute(`CREATE TABLE IF NOT EXISTS ${KEYSPACE}.${LOCK_TABLE} (name text PRIMARY KEY, owner text, acquired_at timestamp)`);
-    ensured = true;
+    const existing = await executor.execute('SELECT table_name FROM system_schema.tables WHERE keyspace_name = ? AND table_name = ?', [KEYSPACE, LOCK_TABLE], { prepare: true, consistency: cassandra_driver_1.types.consistencies.localOne });
+    if (existing.rows.length === 0) {
+        await executor.execute(`CREATE KEYSPACE IF NOT EXISTS ${KEYSPACE} WITH replication = ` +
+            `{'class':'NetworkTopologyStrategy','kora-dc1':1,'kora-dc2':1}`);
+        await executor.execute(`CREATE TABLE IF NOT EXISTS ${KEYSPACE}.${LOCK_TABLE} (name text PRIMARY KEY, owner text, acquired_at timestamp)`);
+    }
+    ensured.add(executor);
 };
 const parseOffline = (raw) => {
     const value = (raw !== null && raw !== void 0 ? raw : '').trim().toLowerCase();
@@ -191,12 +199,16 @@ const deleteIfOwner = async (executor, key, token, serialConsistency, consistenc
         return false;
     }
 };
+/** One fresh process's acquisition: make sure the lock table exists, then take the lock. */
+const acquireOnExecutor = async (executor, name, offline, topology, lease) => {
+    await ensureSchema(executor);
+    return (0, exports.acquireWithExecutor)(executor, name, offline, topology, undefined, lease);
+};
+exports.acquireOnExecutor = acquireOnExecutor;
 const acquire = async (name, offline, options = {}) => {
     try {
         const topology = (0, exports.resolveTopology)();
-        const executor = getClient(topology);
-        await ensureSchema(executor);
-        const result = await (0, exports.acquireWithExecutor)(executor, name, offline, topology, undefined, options.leaseMs);
+        const result = await (0, exports.acquireOnExecutor)(getClient(topology), name, offline, topology, options.leaseMs);
         if (result.status === 'peerUnavailable') {
             logger_1.Logger.log({
                 message: `cron lock '${name}' SERIAL unavailable because the configured peer quorum is unavailable: ${result.message}`,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.18.4",
+    "version": "6.19.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",