@koralabs/kora-labs-common 6.15.0 → 6.15.2

package/cronLock/cqlCronLock.d.ts

@@ -38,6 +38,11 @@ export declare const resolveMode: (offline: string[], topology: CronLockTopology
 export declare const isPeerUnavailableError: (error: unknown) => boolean;
 /** A write timeout leaves an LWT's outcome unknown: the proposal may or may not have been applied. */
 export declare const isWriteTimeoutError: (error: unknown) => boolean;
+/**
+ * An LWT whose outcome is unknown: the coordinator reported a write timeout, or it never replied within
+ * the driver's readTimeout ("The host … did not reply before timeout") — either way it may have committed.
+ */
+export declare const isUnknownOutcomeError: (error: unknown) => boolean;
 /**
  * The directly testable LWT operation. Each invocation owns a unique token, so
  * concurrent ticks on one node cannot both treat the node identity as ownership.
@@ -46,6 +51,18 @@ export declare const acquireWithExecutor: (executor: CqlExecutor, name: string,
 export declare const acquire: (name: string, offline?: string | null, options?: {
     leaseMs?: number;
 }) => Promise<AcquireResult>;
-/** Release only the exact acquisition token owned by this invocation. */
+export type ReleaseResult = {
+    status: 'released';
+} | {
+    status: 'unknown';
+    message: string;
+};
+/**
+ * Release only the exact acquisition token owned by this invocation. The conditional DELETE is an LWT
+ * too: when it fails its outcome is unknown, and a surviving row would idle the job on every box for
+ * the whole lease. A serial read completes any in-flight Paxos round and tells whether the row is still
+ * ours; if it is, the (token-conditional) delete is issued once more.
+ */
+export declare const releaseWithExecutor: (executor: CqlExecutor, name: string, token: string, offline: string | null | undefined, topology: CronLockTopology) => Promise<ReleaseResult>;
 export declare const release: (name: string, token: string, offline?: string | null) => Promise<void>;
 export {};

package/cronLock/cqlCronLock.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.release = exports.acquire = exports.acquireWithExecutor = exports.isWriteTimeoutError = exports.isPeerUnavailableError = exports.resolveMode = exports.parseOffline = exports.leaseMs = exports.resolveTopology = void 0;
+exports.release = exports.releaseWithExecutor = exports.acquire = 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
@@ -117,6 +117,12 @@ exports.isPeerUnavailableError = isPeerUnavailableError;
 /** A write timeout leaves an LWT's outcome unknown: the proposal may or may not have been applied. */
 const isWriteTimeoutError = (error) => error instanceof cassandra_driver_1.errors.ResponseError && error.code === cassandra_driver_1.types.responseErrorCodes.writeTimeout;
 exports.isWriteTimeoutError = isWriteTimeoutError;
+/**
+ * An LWT whose outcome is unknown: the coordinator reported a write timeout, or it never replied within
+ * the driver's readTimeout ("The host … did not reply before timeout") — either way it may have committed.
+ */
+const isUnknownOutcomeError = (error) => (0, exports.isWriteTimeoutError)(error) || error instanceof cassandra_driver_1.errors.OperationTimedOutError;
+exports.isUnknownOutcomeError = isUnknownOutcomeError;
 /**
  * The directly testable LWT operation. Each invocation owns a unique token, so
  * concurrent ticks on one node cannot both treat the node identity as ownership.
@@ -144,7 +150,7 @@ const acquireWithExecutor = async (executor, name, offline, topology, token = cr
         if (mode === 'serial' && (0, exports.isPeerUnavailableError)(error)) {
             return { status: 'peerUnavailable', token, message };
         }
-        if ((0, exports.isWriteTimeoutError)(error)) {
+        if ((0, exports.isUnknownOutcomeError)(error)) {
             // The LWT timed out: it may have been applied WITH OUR TOKEN, in which case nobody (not even
             // us) could run until the lease expired. A read at the same serial consistency completes any
             // in-flight Paxos round, so it tells us the real owner.
@@ -217,22 +223,53 @@ const acquire = async (name, offline, options = {}) => {
     }
 };
 exports.acquire = acquire;
-/** Release only the exact acquisition token owned by this invocation. */
+/**
+ * Release only the exact acquisition token owned by this invocation. The conditional DELETE is an LWT
+ * too: when it fails its outcome is unknown, and a surviving row would idle the job on every box for
+ * the whole lease. A serial read completes any in-flight Paxos round and tells whether the row is still
+ * ours; if it is, the (token-conditional) delete is issued once more.
+ */
+const releaseWithExecutor = async (executor, name, token, offline, topology) => {
+    const mode = (0, exports.resolveMode)((0, exports.parseOffline)(offline), topology);
+    if (mode === 'standDown')
+        return { status: 'released' };
+    const serialConsistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localSerial : cassandra_driver_1.types.consistencies.serial;
+    const consistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localQuorum : cassandra_driver_1.types.consistencies.quorum;
+    const key = scopeName(name, topology);
+    try {
+        await executor.execute(`DELETE FROM ${KEYSPACE}.${LOCK_TABLE} WHERE name = ? IF owner = ?`, [key, token], { prepare: true, serialConsistency, consistency });
+        return { status: 'released' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const read = await readOwner(executor, key, serialConsistency);
+        if (read.error)
+            return { status: 'unknown', message: `${message}; owner read failed (${read.error})` };
+        if (read.owner !== token)
+            return { status: 'released' };
+        return (await deleteIfOwner(executor, key, token, serialConsistency, consistency))
+            ? { status: 'released' }
+            : { status: 'unknown', message: `${message}; the row is still ours and the second delete failed` };
+    }
+};
+exports.releaseWithExecutor = releaseWithExecutor;
 const release = async (name, token, offline) => {
     try {
         const topology = (0, exports.resolveTopology)();
-        const mode = (0, exports.resolveMode)((0, exports.parseOffline)(offline), topology);
-        if (mode === 'standDown')
-            return;
-        const serialConsistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localSerial : cassandra_driver_1.types.consistencies.serial;
-        const consistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localQuorum : cassandra_driver_1.types.consistencies.quorum;
-        await getClient(topology).execute(`DELETE FROM ${KEYSPACE}.${LOCK_TABLE} WHERE name = ? IF owner = ?`, [scopeName(name, topology), token], { prepare: true, serialConsistency, consistency });
+        const result = await (0, exports.releaseWithExecutor)(getClient(topology), name, token, offline, topology);
+        if (result.status === 'unknown') {
+            logger_1.Logger.log({
+                message: `cron lock '${name}' release failed; if the row survived, '${name}' idles on every box until its lease expires: ${result.message}`,
+                event: 'cqlCronLock.release.unknown',
+                category: logger_1.LogCategory.WARN
+            });
+        }
     }
     catch (error) {
         logger_1.Logger.log({
-            message: `cron lock '${name}' release best-effort failed (TTL will reclaim): ${error.message}`,
-            event: 'cqlCronLock.release.softfail',
-            category: logger_1.LogCategory.INFO
+            message: `cron lock '${name}' release failed (TTL will reclaim): ${error.message}`,
+            event: 'cqlCronLock.release.unknown',
+            category: logger_1.LogCategory.WARN
         });
     }
 };

package/package.json

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

package/txBuild/blockfrost.d.ts

@@ -58,6 +58,11 @@ export declare class BlockfrostTxClient {
     getAddressAssetUtxos(address: string, unit: string): Promise<Cardano.Utxo[]>;
     /** The UTxO `txHash#index`; throws `already spent` when it has been consumed. */
     getUtxo(ref: string): Promise<Cardano.Utxo>;
+    /** A stake address's registration state; null when the chain has never seen it. */
+    getAccount(stakeAddress: string): Promise<{
+        stake_address: string;
+        active: boolean;
+    } | null>;
     /** Node (Ogmios) evaluation of every redeemer; `additionalUtxos` supplies inputs not yet on chain. */
     evaluateTx(cbor: string, additionalUtxos?: Cardano.Utxo[]): Promise<Map<RedeemerKey, ExUnits>>;
     /** Submit a signed tx; returns its hash. */

package/txBuild/blockfrost.js

@@ -188,6 +188,10 @@ class BlockfrostTxClient {
             throw new Error(`${ref} already spent by ${output.consumed_by_tx}`);
         return this.toUtxo(output, txHash, output.address);
     }
+    /** A stake address's registration state; null when the chain has never seen it. */
+    getAccount(stakeAddress) {
+        return this.getOrNull(`accounts/${stakeAddress}`);
+    }
     /** Node (Ogmios) evaluation of every redeemer; `additionalUtxos` supplies inputs not yet on chain. */
     async evaluateTx(cbor, additionalUtxos = []) {
         var _a, _b, _c, _d, _e;