resplite 1.3.4 → 1.3.6

package/README.md

@@ -107,7 +107,6 @@ const m = createMigration({
   batchKeys:      1000,
   batchBytes:     64 * 1024 * 1024,  // 64 MB
   maxRps:         0,                  // 0 = unlimited
-  redisCommandTimeoutMs: 30000,       // fail a stuck Redis command instead of waiting forever
 
   // If your Redis deployment renamed CONFIG for security:
   // configCommand: 'MYCONFIG',
@@ -190,10 +189,7 @@ await m.close();
 `resume` defaults to `true`. It doesn't matter whether it's the first run or a resume: the same script works for both starting and continuing. The first run starts from cursor 0; if the process is interrupted (Ctrl+C, crash, etc.), running the script again continues from the last checkpoint. You don't need to pass `resume: false` on the first run or change anything to resume.
 
 **Graceful shutdown**  
-On SIGINT (Ctrl+C) or SIGTERM, the bulk importer checkpoints progress, sets the run status to `aborted`, closes the SQLite database cleanly (so WAL is checkpointed and the file is not left open), and tears down the Redis client so a stuck command does not trap the process forever. You can safely interrupt a long-running bulk and resume later. The same applies to **apply-dirty**: Ctrl+C stops the delta apply, sets the run to `aborted`, and exits so you can inspect and retry.
-
-**Errors and stalls**  
-Use `onProgress` to see progress and detect problems. The callback receives the run row (e.g. `scanned_keys`, `migrated_keys`, `dirty_keys_applied`, `last_error`) plus transient fields like `_activeStage`, `_activeKey`, `_activeForMs`, `_stallWarning`, and `_stallMessage` when the importer is waiting on Redis. Each Redis command is also protected by `redisCommandTimeoutMs` (30s by default), so a dead connection or pathological key fails with the active stage/key in the error instead of silently hanging forever. When a key fails to import, the error is logged to `migration_errors` and the run’s `last_error` is set; the real error message is included so you can diagnose. After any failure, check `m.status()` and query `migration_errors` in the DB if needed.
+On SIGINT (Ctrl+C) or SIGTERM, the bulk importer checkpoints progress, sets the run status to `aborted`, closes the SQLite database cleanly (so WAL is checkpointed and the file is not left open), then exits. You can safely interrupt a long-running bulk and resume later.
 
 The JS API can run the dirty-key tracker in-process via `m.startDirtyTracker()` / `m.stopDirtyTracker()`, so the full flow stays inside a single script.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",

package/src/migration/apply-dirty.js

@@ -9,21 +9,15 @@ import { createHashesStorage } from '../storage/sqlite/hashes.js';
 import { createSetsStorage } from '../storage/sqlite/sets.js';
 import { createListsStorage } from '../storage/sqlite/lists.js';
 import { createZsetsStorage } from '../storage/sqlite/zsets.js';
-import { getRun, getDirtyBatch, markDirtyState, logError, setRunStatus, updateBulkProgress, RUN_STATUS } from './registry.js';
+import { getRun, getDirtyBatch, markDirtyState, logError, RUN_STATUS } from './registry.js';
 import { importKeyFromRedis } from './import-one.js';
-import { createRedisCommandGuard, isFatalRedisCommandError } from './redis-guard.js';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-const HEARTBEAT_INTERVAL_MS = 15000;
-const STALL_WARNING_MS = 60000;
-
 /**
  * Apply dirty keys: for each key in registry with state=dirty, reimport from Redis or delete in destination.
- * On SIGINT/SIGTERM, sets run status to ABORTED, closes DB and rethrows so the process can exit and Ctrl+C works.
- *
  * @param {import('redis').RedisClientType} redisClient
  * @param {string} dbPath
  * @param {string} runId
@@ -31,73 +25,12 @@ const STALL_WARNING_MS = 60000;
  * @param {string} [options.pragmaTemplate='default']
  * @param {number} [options.batch_keys=200]
  * @param {number} [options.max_rps=0]
- * @param {number} [options.redis_command_timeout_ms=30000]
- * @param {(run: object) => void | Promise<void>} [options.onProgress] - Called after each batch and on heartbeat; may receive _stallWarning if no progress for 60s.
+ * @param {(run: object) => void | Promise<void>} [options.onProgress] - Called after each batch with the current run row.
  */
 export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
-  const { pragmaTemplate = 'default', batch_keys = 200, max_rps = 0, redis_command_timeout_ms = 30000, onProgress } = options;
+  const { pragmaTemplate = 'default', batch_keys = 200, max_rps = 0, onProgress } = options;
 
   const db = openDb(dbPath, { pragmaTemplate });
-  const redisGuard = createRedisCommandGuard({
-    redisClient,
-    timeoutMs: redis_command_timeout_ms,
-  });
-  let abortRequested = false;
-  const onSignal = () => {
-    abortRequested = true;
-    redisGuard.signalAbort('Apply dirty interrupted by signal (SIGINT/SIGTERM)', 'APPLY_DIRTY_ABORTED');
-  };
-  process.on('SIGINT', onSignal);
-  process.on('SIGTERM', onSignal);
-
-  function enrichProgress(run) {
-    const active = redisGuard.snapshot();
-    if (!active) return run;
-
-    return {
-      ...run,
-      _activeStage: active.stage,
-      _activeKey: active.key,
-      _activeSince: active.startedAt,
-      _activeForMs: active.activeForMs,
-    };
-  }
-
-  function withStallContext(run) {
-    const active = redisGuard.snapshot();
-    let payload = enrichProgress(run);
-    if (run.updated_at && Date.now() - run.updated_at > STALL_WARNING_MS) {
-      const detail = active
-        ? ` Active operation: ${active.stage}${active.key ? ` key=${active.key}` : ''}.`
-        : '';
-      payload = {
-        ...payload,
-        _stallWarning: true,
-        _stallMessage: `No progress for 60s — possible hang or Redis timeout.${detail}`,
-      };
-    }
-    return payload;
-  }
-
-  let abortHandled = false;
-  function markAborted() {
-    if (abortHandled) return getRun(db, runId);
-    abortHandled = true;
-    setRunStatus(db, runId, RUN_STATUS.ABORTED);
-    updateBulkProgress(db, runId, { last_error: 'Interrupted by SIGINT/SIGTERM' });
-    return getRun(db, runId);
-  }
-
-  let heartbeatTimer = null;
-  if (onProgress) {
-    heartbeatTimer = setInterval(() => {
-      const run = getRun(db, runId);
-      if (!run) return;
-      const payload = withStallContext(run);
-      Promise.resolve(onProgress(payload)).catch(() => {});
-    }, HEARTBEAT_INTERVAL_MS);
-  }
-
   const run = getRun(db, runId);
   if (!run) throw new Error(`Run ${runId} not found`);
 
@@ -112,9 +45,7 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
   const minIntervalMs = max_rps > 0 ? 1000 / max_rps : 0;
   let lastKeyTime = 0;
 
-  try {
   for (;;) {
-    if (abortRequested) break;
     let r = getRun(db, runId);
     if (r && r.status === RUN_STATUS.ABORTED) break;
     while (r && r.status === RUN_STATUS.PAUSED) {
@@ -130,7 +61,6 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
 
     // ── Re-import (or remove) keys that changed while bulk was running ──
     for (const { key: keyBuf } of dirtyBatch) {
-      if (abortRequested) break;
       r = getRun(db, runId);
       if (r && r.status === RUN_STATUS.ABORTED) break;
       while (r && r.status === RUN_STATUS.PAUSED) {
@@ -146,29 +76,22 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
 
       const keyName = keyBuf.toString('utf8');
       try {
-        const type = (await redisGuard.run(
-          () => redisClient.type(keyName),
-          { stage: 'apply-dirty.type', key: keyName }
-        )).toLowerCase();
+        const type = (await redisClient.type(keyName)).toLowerCase();
         if (type === 'none' || !type) {
           keys.delete(keyBuf);
           markDirtyState(db, runId, keyBuf, 'deleted');
         } else {
-          const outcome = await importKeyFromRedis(redisClient, keyName, storages, {
-            redisGuard,
-            knownType: type,
-          });
+          const outcome = await importKeyFromRedis(redisClient, keyName, storages, {});
           if (outcome.ok) {
             markDirtyState(db, runId, keyBuf, 'applied');
           } else if (outcome.skipped) {
             markDirtyState(db, runId, keyBuf, 'skipped');
           } else {
-            logError(db, runId, 'dirty_apply', outcome.errorMessage || (outcome.error ? 'Import failed' : 'Skipped'), keyName);
+            logError(db, runId, 'dirty_apply', outcome.error ? 'Import failed' : 'Skipped', keyName);
             markDirtyState(db, runId, keyBuf, 'error');
           }
         }
       } catch (err) {
-        if (isFatalRedisCommandError(err)) throw err;
         logError(db, runId, 'dirty_apply', err.message, keyBuf);
         markDirtyState(db, runId, keyBuf, 'error');
       }
@@ -179,7 +102,6 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
     // Marked as 'deleted' in the run counter; state changed away from 'deleted'
     // so the next getDirtyBatch call won't return them again (avoiding infinite loop).
     for (const { key: keyBuf } of deletedBatch) {
-      if (abortRequested) break;
       r = getRun(db, runId);
       if (r && r.status === RUN_STATUS.ABORTED) break;
       while (r && r.status === RUN_STATUS.PAUSED) {
@@ -205,33 +127,9 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
     }
     if (batchSize > 0 && onProgress) {
       const run = getRun(db, runId);
-      if (run) Promise.resolve(onProgress(enrichProgress(run))).catch(() => {});
+      if (run) Promise.resolve(onProgress(run)).catch(() => {});
     }
   }
 
-  if (abortRequested) {
-    const run = markAborted();
-    if (onProgress && run) Promise.resolve(onProgress(enrichProgress(run))).catch(() => {});
-    const err = new Error('Apply dirty interrupted by signal (SIGINT/SIGTERM)');
-    err.code = 'APPLY_DIRTY_ABORTED';
-    throw err;
-  }
-
   return getRun(db, runId);
-  } catch (err) {
-    if (err.code === 'APPLY_DIRTY_ABORTED') {
-      const run = markAborted();
-      if (onProgress && run) Promise.resolve(onProgress(enrichProgress(run))).catch(() => {});
-    } else {
-      setRunStatus(db, runId, RUN_STATUS.FAILED);
-      updateBulkProgress(db, runId, { last_error: err.message });
-      logError(db, runId, 'dirty_apply', err.message, null);
-    }
-    throw err;
-  } finally {
-    if (heartbeatTimer) clearInterval(heartbeatTimer);
-    process.off('SIGINT', onSignal);
-    process.off('SIGTERM', onSignal);
-    db.close();
-  }
 }

package/src/migration/bulk.js

@@ -18,7 +18,6 @@ import {
   RUN_STATUS,
 } from './registry.js';
 import { importKeyFromRedis } from './import-one.js';
-import { createRedisCommandGuard } from './redis-guard.js';
 
 function parseScanResult(result) {
   if (Array.isArray(result)) {
@@ -36,9 +35,6 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-const HEARTBEAT_INTERVAL_MS = 15000;
-const STALL_WARNING_MS = 60000;
-
 /**
  * Run bulk import: SCAN keys from Redis, import into RespLite DB with checkpointing.
  * On SIGINT/SIGTERM, checkpoint progress, set run status to ABORTED, close DB and rethrow.
@@ -55,9 +51,8 @@ const STALL_WARNING_MS = 60000;
  * @param {number} [options.batch_keys=200]
  * @param {number} [options.batch_bytes=64*1024*1024] - 64MB
  * @param {number} [options.checkpoint_interval_sec=30]
- * @param {number} [options.redis_command_timeout_ms=30000]
  * @param {boolean} [options.resume=true] - true: start from 0 or continue from checkpoint; false: always start from 0
- * @param {function(run): void} [options.onProgress] - called after checkpoint and on heartbeat; may receive _stallWarning if no progress for 60s
+ * @param {function(run): void} [options.onProgress] - called after checkpoint with run row
  */
 export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
   const {
@@ -68,86 +63,18 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     batch_keys = 200,
     batch_bytes = 64 * 1024 * 1024,
     checkpoint_interval_sec = 30,
-    redis_command_timeout_ms = 30000,
     resume = true,
     onProgress,
   } = options;
 
   const db = openDb(dbPath, { pragmaTemplate });
-  const redisGuard = createRedisCommandGuard({
-    redisClient,
-    timeoutMs: redis_command_timeout_ms,
-  });
   let abortRequested = false;
   const onSignal = () => {
     abortRequested = true;
-    redisGuard.signalAbort('Bulk import interrupted by signal (SIGINT/SIGTERM)', 'BULK_ABORTED');
   };
   process.on('SIGINT', onSignal);
   process.on('SIGTERM', onSignal);
 
-  function enrichProgress(run) {
-    const active = redisGuard.snapshot();
-    if (!active) return run;
-
-    return {
-      ...run,
-      _activeStage: active.stage,
-      _activeKey: active.key,
-      _activeSince: active.startedAt,
-      _activeForMs: active.activeForMs,
-    };
-  }
-
-  function withStallContext(run) {
-    const active = redisGuard.snapshot();
-    let payload = enrichProgress(run);
-    if (run.updated_at && Date.now() - run.updated_at > STALL_WARNING_MS) {
-      const detail = active
-        ? ` Active operation: ${active.stage}${active.key ? ` key=${active.key}` : ''}.`
-        : '';
-      payload = {
-        ...payload,
-        _stallWarning: true,
-        _stallMessage: `No progress for 60s — possible hang or Redis timeout.${detail}`,
-      };
-    }
-    return payload;
-  }
-
-  let heartbeatTimer = null;
-  if (onProgress) {
-    heartbeatTimer = setInterval(() => {
-      const run = getRun(db, runId);
-      if (!run) return;
-      const payload = withStallContext(run);
-      Promise.resolve(onProgress(payload)).catch(() => {});
-    }, HEARTBEAT_INTERVAL_MS);
-  }
-
-  let cursor = 0;
-  let scanned_keys = 0;
-  let migrated_keys = 0;
-  let skipped_keys = 0;
-  let error_keys = 0;
-  let migrated_bytes = 0;
-  let abortHandled = false;
-  function markAborted() {
-    if (abortHandled) return getRun(db, runId);
-    abortHandled = true;
-    updateBulkProgress(db, runId, {
-      scan_cursor: String(cursor),
-      scanned_keys,
-      migrated_keys,
-      skipped_keys,
-      error_keys,
-      migrated_bytes,
-      last_error: 'Interrupted by SIGINT/SIGTERM',
-    });
-    setRunStatus(db, runId, RUN_STATUS.ABORTED);
-    return getRun(db, runId);
-  }
-
   try {
     const keys = createKeysStorage(db);
     const strings = createStringsStorage(db, keys);
@@ -161,12 +88,12 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     let run = getRun(db, runId);
     if (!run) throw new Error(`Run ${runId} not found`);
 
-    cursor = resume && run.scan_cursor !== undefined ? parseInt(String(run.scan_cursor), 10) : 0;
-    scanned_keys = resume ? (run.scanned_keys || 0) : 0;
-    migrated_keys = resume ? (run.migrated_keys || 0) : 0;
-    skipped_keys = resume ? (run.skipped_keys || 0) : 0;
-    error_keys = resume ? (run.error_keys || 0) : 0;
-    migrated_bytes = resume ? (run.migrated_bytes || 0) : 0;
+    let cursor = resume && run.scan_cursor !== undefined ? parseInt(String(run.scan_cursor), 10) : 0;
+    let scanned_keys = resume ? (run.scanned_keys || 0) : 0;
+    let migrated_keys = resume ? (run.migrated_keys || 0) : 0;
+    let skipped_keys = resume ? (run.skipped_keys || 0) : 0;
+    let error_keys = resume ? (run.error_keys || 0) : 0;
+    let migrated_bytes = resume ? (run.migrated_bytes || 0) : 0;
 
     if (!resume) {
       updateBulkProgress(db, runId, { scan_cursor: String(cursor), scanned_keys, migrated_keys, skipped_keys, error_keys, migrated_bytes });
@@ -187,10 +114,7 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
         run = getRun(db, runId);
       }
 
-      const result = await redisGuard.run(
-        () => redisClient.scan(cursor, { COUNT: scan_count }),
-        { stage: 'bulk.scan' }
-      );
+      const result = await redisClient.scan(cursor, { COUNT: scan_count });
       const parsed = parseScanResult(result);
       cursor = parsed.cursor;
       const keyList = parsed.keys || [];
@@ -212,10 +136,7 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
         }
 
         const now = Date.now();
-        const outcome = await importKeyFromRedis(redisClient, keyName, storages, {
-          now,
-          redisGuard,
-        });
+        const outcome = await importKeyFromRedis(redisClient, keyName, storages, { now });
         if (outcome.ok) {
           migrated_keys++;
           migrated_bytes += outcome.bytes || 0;
@@ -225,7 +146,7 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
           skipped_keys++;
         } else {
           error_keys++;
-          logError(db, runId, 'bulk', outcome.errorMessage || (outcome.error ? 'Import failed' : 'Skipped'), keyName);
+          logError(db, runId, 'bulk', outcome.error ? 'Import failed' : 'Skipped', keyName);
         }
 
         const now2 = Date.now();
@@ -246,7 +167,7 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
           batchScanned = 0;
           batchBytes = 0;
           run = getRun(db, runId);
-          if (onProgress && run) onProgress(enrichProgress(run));
+          if (onProgress && run) onProgress(run);
         }
       }
     } while (cursor !== 0);
@@ -260,8 +181,9 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
         error_keys,
         migrated_bytes,
       });
-      run = markAborted();
-      if (onProgress && run) onProgress(enrichProgress(run));
+      setRunStatus(db, runId, RUN_STATUS.ABORTED);
+      run = getRun(db, runId);
+      if (onProgress && run) onProgress(run);
       const err = new Error('Bulk import interrupted by signal (SIGINT/SIGTERM)');
       err.code = 'BULK_ABORTED';
       throw err;
@@ -278,17 +200,13 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     setRunStatus(db, runId, RUN_STATUS.COMPLETED);
     return getRun(db, runId);
   } catch (err) {
-    if (err.code === 'BULK_ABORTED') {
-      const run = markAborted();
-      if (onProgress && run) onProgress(enrichProgress(run));
-    } else {
+    if (err.code !== 'BULK_ABORTED') {
       setRunStatus(db, runId, RUN_STATUS.FAILED);
       updateBulkProgress(db, runId, { last_error: err.message });
       logError(db, runId, 'bulk', err.message, null);
     }
     throw err;
   } finally {
-    if (heartbeatTimer) clearInterval(heartbeatTimer);
     process.off('SIGINT', onSignal);
     process.off('SIGTERM', onSignal);
     db.close();

package/src/migration/import-one.js

@@ -4,7 +4,6 @@
  */
 
 import { asKey, asValue } from '../util/buffers.js';
-import { isFatalRedisCommandError } from './redis-guard.js';
 
 const SUPPORTED_TYPES = new Set(['string', 'hash', 'set', 'list', 'zset']);
 
@@ -20,27 +19,20 @@ function toBuffer(value) {
  * @param {import('redis').RedisClientType} redisClient
  * @param {string} keyName
  * @param {{ keys: import('../storage/sqlite/keys.js').ReturnType<import('../storage/sqlite/keys.js').createKeysStorage>; strings: ReturnType<import('../storage/sqlite/strings.js').createStringsStorage>; hashes: ReturnType<import('../storage/sqlite/hashes.js').createHashesStorage>; sets: ReturnType<import('../storage/sqlite/sets.js').createSetsStorage>; lists: ReturnType<import('../storage/sqlite/lists.js').createListsStorage>; zsets: ReturnType<import('../storage/sqlite/zsets.js').createZsetsStorage> }} storages
- * @param {{ now?: number; knownType?: string; redisGuard?: { run(fn: Function, options: { stage: string, key?: string | null }): Promise<any> } }} options
- * @returns {Promise<{ ok: boolean; skipped?: boolean; error?: boolean; errorMessage?: string; bytes?: number }>}
+ * @param {{ now?: number }} options
+ * @returns {Promise<{ ok: boolean; skipped?: boolean; error?: boolean; bytes?: number }>}
  */
 export async function importKeyFromRedis(redisClient, keyName, storages, options = {}) {
   const now = options.now ?? Date.now();
-  const knownType = options.knownType ? String(options.knownType).toLowerCase() : null;
-  const redisGuard = options.redisGuard ?? null;
   const { keys, strings, hashes, sets, lists, zsets } = storages;
-  const runRedis = (stage, fn) => (
-    redisGuard
-      ? redisGuard.run(fn, { stage, key: keyName })
-      : Promise.resolve().then(fn)
-  );
 
   try {
-    const type = knownType || (await runRedis('import.type', () => redisClient.type(keyName))).toLowerCase();
+    const type = (await redisClient.type(keyName)).toLowerCase();
     if (!SUPPORTED_TYPES.has(type)) {
       return { ok: false, skipped: true };
     }
 
-    let pttl = await runRedis('import.pttl', () => redisClient.pTTL(keyName));
+    let pttl = await redisClient.pTTL(keyName);
     if (pttl === -2) pttl = -1;
     const expiresAt = pttl > 0 ? now + pttl : null;
     const keyBuf = asKey(keyName);
@@ -48,7 +40,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     let bytes = keyBuf.length;
 
     if (type === 'string') {
-      const value = await runRedis('import.string.get', () => redisClient.get(keyName));
+      const value = await redisClient.get(keyName);
       if (value === undefined || value === null) return { ok: false, skipped: true };
       const valBuf = asValue(value);
       bytes += valBuf.length;
@@ -57,7 +49,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'hash') {
-      const obj = await runRedis('import.hash.hGetAll', () => redisClient.hGetAll(keyName));
+      const obj = await redisClient.hGetAll(keyName);
       if (!obj || typeof obj !== 'object') return { ok: false, skipped: true };
       const pairs = [];
       for (const [f, v] of Object.entries(obj)) {
@@ -73,7 +65,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'set') {
-      const members = await runRedis('import.set.sMembers', () => redisClient.sMembers(keyName));
+      const members = await redisClient.sMembers(keyName);
       if (!members || !members.length) return { ok: false, skipped: true };
       const memberBuffers = members.map((m) => toBuffer(m));
       for (const b of memberBuffers) bytes += b.length;
@@ -83,7 +75,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'list') {
-      const elements = await runRedis('import.list.lRange', () => redisClient.lRange(keyName, 0, -1));
+      const elements = await redisClient.lRange(keyName, 0, -1);
       if (!elements || !elements.length) return { ok: false, skipped: true };
       const valueBuffers = elements.map((e) => toBuffer(e));
       for (const b of valueBuffers) bytes += b.length;
@@ -93,7 +85,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'zset') {
-      const withScores = await runRedis('import.zset.zRangeWithScores', () => redisClient.zRangeWithScores(keyName, 0, -1));
+      const withScores = await redisClient.zRangeWithScores(keyName, 0, -1);
       if (!withScores || !withScores.length) return { ok: false, skipped: true };
       const pairs = withScores.map((item) => ({
         member: toBuffer(item.value),
@@ -107,8 +99,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
 
     return { ok: false, skipped: true };
   } catch (err) {
-    if (isFatalRedisCommandError(err)) throw err;
-    return { ok: false, error: true, errorMessage: err.message };
+    return { ok: false, error: true };
   }
 }
 

package/src/migration/index.js

@@ -38,7 +38,6 @@ import { startDirtyTracker as startDirtyTrackerProcess } from './tracker.js';
  * @property {number} [maxRps=0]                      - Max requests/s (0 = unlimited).
  * @property {number} [batchKeys=200]
  * @property {number} [batchBytes=67108864]           - 64 MB default.
- * @property {number} [redisCommandTimeoutMs=30000]   - Fail a stuck Redis command instead of waiting forever.
  * @property {string} [configCommand='CONFIG']        - Redis CONFIG command name. Override if renamed for security.
  */
 
@@ -68,7 +67,6 @@ export function createMigration({
   maxRps = 0,
   batchKeys = 200,
   batchBytes = 64 * 1024 * 1024,
-  redisCommandTimeoutMs = 30000,
   configCommand = 'CONFIG',
 } = {}) {
   if (!to) throw new Error('createMigration: "to" (db path) is required');
@@ -170,7 +168,6 @@ export function createMigration({
         max_rps: maxRps,
         batch_keys: batchKeys,
         batch_bytes: batchBytes,
-        redis_command_timeout_ms: redisCommandTimeoutMs,
         resume,
         onProgress,
       });
@@ -203,7 +200,6 @@ export function createMigration({
         pragmaTemplate,
         batch_keys: bk,
         max_rps: rps,
-        redis_command_timeout_ms: redisCommandTimeoutMs,
         onProgress,
       });
     },

package/src/storage/sqlite/db.js

@@ -1,20 +1,27 @@
 /**
  * Open SQLite database, apply pragmas and schema.
+ * If the path points to a file in a directory that does not exist, the directory is created.
  */
 
 import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import path from 'node:path';
 import { applyPragmas } from './pragmas.js';
 import { applySchema } from './schema.js';
 import { applyMigrationSchema } from './migration-schema.js';
 
 /**
- * @param {string} path - Database file path
+ * @param {string} dbPath - Database file path (or ':memory:')
  * @param {object} [options] - Options: pragmaTemplate (default|performance|safety|minimal), plus any better-sqlite3 options
  * @returns {import('better-sqlite3').Database}
  */
-export function openDb(path, options = {}) {
+export function openDb(dbPath, options = {}) {
+  if (dbPath !== ':memory:') {
+    const dir = path.dirname(dbPath);
+    if (dir) fs.mkdirSync(dir, { recursive: true });
+  }
   const { pragmaTemplate = 'default', ...dbOptions } = options;
-  const db = new Database(path, dbOptions);
+  const db = new Database(dbPath, dbOptions);
   applyPragmas(db, pragmaTemplate);
   applySchema(db);
   applyMigrationSchema(db);

package/src/migration/redis-guard.js

@@ -1,174 +0,0 @@
-/**
- * Guard Redis migration commands with timeouts and abort-aware progress context.
- */
-
-const FATAL_CODES = new Set([
-  'REDIS_COMMAND_TIMEOUT',
-  'BULK_ABORTED',
-  'APPLY_DIRTY_ABORTED',
-  'MIGRATION_ABORTED',
-]);
-
-function normalizeKey(key) {
-  if (key == null) return null;
-  if (Buffer.isBuffer(key)) return key.toString('utf8');
-  return String(key);
-}
-
-function attachContext(err, snapshot) {
-  if (!snapshot || !err || typeof err !== 'object') return err;
-  if (!('migrationStage' in err)) err.migrationStage = snapshot.stage;
-  if (!('migrationKey' in err)) err.migrationKey = snapshot.key;
-  if (!('migrationActiveSince' in err)) err.migrationActiveSince = snapshot.startedAt;
-  return err;
-}
-
-function formatContext(message, snapshot) {
-  if (!snapshot) return message;
-  const parts = [message, `during ${snapshot.stage}`];
-  if (snapshot.key) parts.push(`for key "${snapshot.key}"`);
-  return parts.join(' ');
-}
-
-function abortRedisTransport(redisClient) {
-  if (!redisClient) return;
-
-  for (const methodName of ['disconnect', 'destroy']) {
-    if (typeof redisClient[methodName] !== 'function') continue;
-    try {
-      const result = redisClient[methodName]();
-      if (result && typeof result.catch === 'function') {
-        result.catch(() => {});
-      }
-    } catch (_) {
-      // Best effort: we're already aborting because the client is unhealthy.
-    }
-    return;
-  }
-}
-
-export function isFatalRedisCommandError(err) {
-  return !!(err && typeof err === 'object' && FATAL_CODES.has(err.code));
-}
-
-export function createRedisCommandGuard({ redisClient, timeoutMs = 30000 } = {}) {
-  const abortListeners = new Set();
-  let active = null;
-  let terminalError = null;
-  let transportAborted = false;
-
-  function snapshot() {
-    if (!active) return null;
-    return {
-      stage: active.stage,
-      key: active.key,
-      startedAt: active.startedAt,
-      activeForMs: Date.now() - active.startedAt,
-    };
-  }
-
-  function notifyAbort(err) {
-    for (const listener of abortListeners) {
-      try {
-        listener(err);
-      } catch (_) {
-        // Ignore listener failures while aborting.
-      }
-    }
-  }
-
-  function abortTransport() {
-    if (transportAborted) return;
-    transportAborted = true;
-    abortRedisTransport(redisClient);
-  }
-
-  function signalAbort(message, code = 'MIGRATION_ABORTED') {
-    if (terminalError) return terminalError;
-    const current = snapshot();
-    const err = attachContext(new Error(formatContext(message, current)), current);
-    err.code = code;
-    terminalError = err;
-    abortTransport();
-    notifyAbort(err);
-    return err;
-  }
-
-  async function run(fn, { stage, key = null, timeoutMs: overrideTimeoutMs } = {}) {
-    if (terminalError) throw terminalError;
-
-    const opTimeoutMs = overrideTimeoutMs ?? timeoutMs;
-    const opKey = normalizeKey(key);
-    const opState = {
-      stage,
-      key: opKey,
-      startedAt: Date.now(),
-    };
-    active = opState;
-
-    return await new Promise((resolve, reject) => {
-      let settled = false;
-      let timeoutId = null;
-
-      const cleanup = () => {
-        abortListeners.delete(onAbort);
-        if (timeoutId) clearTimeout(timeoutId);
-        if (active === opState) active = null;
-      };
-
-      const finishResolve = (value) => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        resolve(value);
-      };
-
-      const finishReject = (err) => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        reject(err);
-      };
-
-      const onAbort = (err) => {
-        finishReject(err);
-      };
-
-      abortListeners.add(onAbort);
-
-      if (Number.isFinite(opTimeoutMs) && opTimeoutMs > 0) {
-        timeoutId = setTimeout(() => {
-          const current = snapshot() ?? {
-            stage,
-            key: opKey,
-            startedAt: opState.startedAt,
-            activeForMs: Date.now() - opState.startedAt,
-          };
-          const err = attachContext(
-            new Error(formatContext(`Redis command timed out after ${opTimeoutMs}ms`, current)),
-            current
-          );
-          err.code = 'REDIS_COMMAND_TIMEOUT';
-          terminalError = err;
-          abortTransport();
-          notifyAbort(err);
-          finishReject(err);
-        }, opTimeoutMs);
-      }
-
-      Promise.resolve()
-        .then(fn)
-        .then(
-          (value) => finishResolve(value),
-          (err) => finishReject(attachContext(err, snapshot() ?? opState))
-        );
-    });
-  }
-
-  return {
-    run,
-    snapshot,
-    signalAbort,
-    abortTransport,
-  };
-}

package/test/unit/migration-timeouts.test.js

@@ -1,122 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { runBulkImport } from '../../src/migration/bulk.js';
-import { runApplyDirty } from '../../src/migration/apply-dirty.js';
-import { createRedisCommandGuard } from '../../src/migration/redis-guard.js';
-import { openDb } from '../../src/storage/sqlite/db.js';
-import { createRun, getRun, upsertDirtyKey } from '../../src/migration/registry.js';
-import { tmpDbPath } from '../helpers/tmp.js';
-
-function never() {
-  return new Promise(() => {});
-}
-
-describe('migration Redis timeouts', () => {
-  it('runBulkImport fails a stuck scan with timeout context', async () => {
-    const dbPath = tmpDbPath();
-    let disconnectCalls = 0;
-    const redisClient = {
-      scan: () => never(),
-      disconnect() {
-        disconnectCalls += 1;
-      },
-    };
-
-    await assert.rejects(
-      () => runBulkImport(redisClient, dbPath, 'bulk-timeout', {
-        sourceUri: 'redis://example.test:6379',
-        pragmaTemplate: 'minimal',
-        redis_command_timeout_ms: 20,
-      }),
-      (err) => {
-        assert.equal(err.code, 'REDIS_COMMAND_TIMEOUT');
-        assert.match(err.message, /bulk\.scan/);
-        return true;
-      }
-    );
-
-    const db = openDb(dbPath, { pragmaTemplate: 'minimal' });
-    try {
-      const run = getRun(db, 'bulk-timeout');
-      assert.equal(run.status, 'failed');
-      assert.match(run.last_error, /bulk\.scan/);
-    } finally {
-      db.close();
-    }
-
-    assert.equal(disconnectCalls, 1);
-  });
-
-  it('runApplyDirty fails a stuck key lookup with key context', async () => {
-    const dbPath = tmpDbPath();
-    const db = openDb(dbPath, { pragmaTemplate: 'minimal' });
-    try {
-      createRun(db, 'apply-timeout', 'redis://example.test:6379');
-      upsertDirtyKey(db, 'apply-timeout', 'stuck:key', 'set');
-    } finally {
-      db.close();
-    }
-
-    let disconnectCalls = 0;
-    const redisClient = {
-      type: () => never(),
-      disconnect() {
-        disconnectCalls += 1;
-      },
-    };
-
-    await assert.rejects(
-      () => runApplyDirty(redisClient, dbPath, 'apply-timeout', {
-        pragmaTemplate: 'minimal',
-        redis_command_timeout_ms: 20,
-      }),
-      (err) => {
-        assert.equal(err.code, 'REDIS_COMMAND_TIMEOUT');
-        assert.match(err.message, /apply-dirty\.type/);
-        assert.match(err.message, /stuck:key/);
-        return true;
-      }
-    );
-
-    const verifyDb = openDb(dbPath, { pragmaTemplate: 'minimal' });
-    try {
-      const run = getRun(verifyDb, 'apply-timeout');
-      assert.equal(run.status, 'failed');
-      assert.match(run.last_error, /apply-dirty\.type/);
-      const row = verifyDb.prepare('SELECT message FROM migration_errors WHERE run_id = ? ORDER BY rowid DESC LIMIT 1').get('apply-timeout');
-      assert.match(row.message, /stuck:key/);
-    } finally {
-      verifyDb.close();
-    }
-
-    assert.equal(disconnectCalls, 1);
-  });
-
-  it('redis guard aborts a pending command immediately', async () => {
-    let disconnectCalls = 0;
-    const guard = createRedisCommandGuard({
-      redisClient: {
-        disconnect() {
-          disconnectCalls += 1;
-        },
-      },
-      timeoutMs: 1000,
-    });
-
-    const pending = guard.run(() => never(), { stage: 'bulk.scan' });
-    queueMicrotask(() => {
-      guard.signalAbort('Bulk import interrupted by signal (SIGINT/SIGTERM)', 'BULK_ABORTED');
-    });
-
-    await assert.rejects(
-      () => pending,
-      (err) => {
-        assert.equal(err.code, 'BULK_ABORTED');
-        assert.match(err.message, /bulk\.scan/);
-        return true;
-      }
-    );
-
-    assert.equal(disconnectCalls, 1);
-  });
-});