resplite 1.0.0 → 1.0.4

package/src/blocking/manager.js

@@ -0,0 +1,183 @@
+/**
+ * Blocking list waiters: BLPOP/BRPOP (SPEC_E).
+ * In-memory wait queues by key; single delivery; wake on LPUSH/RPUSH.
+ */
+
+import { asKey } from '../util/buffers.js';
+
+function toMapKey(key) {
+  const k = Buffer.isBuffer(key) ? key : asKey(key);
+  return k.toString('binary');
+}
+
+/**
+ * @param {object} engine - RESPlite engine (for lpop/rpop on wake)
+ * @param {object} [opts]
+ * @param {number} [opts.maxWaitersPerKey=10000]
+ * @param {number} [opts.maxTotalWaiters=50000]
+ * @param {number} [opts.maxKeysPerWait=128]
+ * @param {() => number} [opts.clock=Date.now]
+ */
+export function createBlockingManager(engine, opts = {}) {
+  const maxWaitersPerKey = opts.maxWaitersPerKey ?? 10000;
+  const maxTotalWaiters = opts.maxTotalWaiters ?? 50000;
+  const maxKeysPerWait = opts.maxKeysPerWait ?? 128;
+  const clock = opts.clock ?? (() => Date.now());
+
+  /** @type {Map<string, Array<{ waiter: object }>>} key -> deque of waiter refs */
+  const waitersByKey = new Map();
+  /** @type {Map<string | number, Set<object>>} connectionId -> waiters for cancel */
+  const waitersByConnection = new Map();
+  let totalWaiters = 0;
+
+  function removeWaiterFromQueues(waiter) {
+    for (const key of waiter.keys) {
+      const mapKey = toMapKey(key);
+      const q = waitersByKey.get(mapKey);
+      if (!q) continue;
+      const idx = q.findIndex((ref) => ref.waiter === waiter);
+      if (idx !== -1) q.splice(idx, 1);
+      if (q.length === 0) waitersByKey.delete(mapKey);
+    }
+    const connSet = waitersByConnection.get(waiter.connectionId);
+    if (connSet) {
+      connSet.delete(waiter);
+      if (connSet.size === 0) waitersByConnection.delete(waiter.connectionId);
+    }
+    totalWaiters--;
+  }
+
+  /**
+   * Try to satisfy one waiter: scan keys in order, pop from first non-empty.
+   * @returns {boolean} true if waiter was satisfied and removed
+   */
+  function tryWake(waiter) {
+    if (waiter.completed || waiter.canceled) return false;
+    for (const key of waiter.keys) {
+      try {
+        const val =
+          waiter.kind === 'BLPOP'
+            ? engine.lpop(key, null)
+            : engine.rpop(key, null);
+        if (val != null) {
+          waiter.completed = true;
+          removeWaiterFromQueues(waiter);
+          waiter.resolve([key, val]);
+          return true;
+        }
+      } catch (_) {
+        // wrong type / missing: skip key
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Register a blocked client. Keys in order; timeout in seconds (0 = indefinite).
+   * @param {Buffer[]} keys
+   * @param {'BLPOP'|'BRPOP'} kind
+   * @param {number} timeoutSeconds
+   * @param {(value: [Buffer, Buffer]|null) => void} resolve - called with [key, element] or null on timeout
+   * @param {string|number} connectionId
+   * @returns {{ error?: string }}
+   */
+  function registerWaiter(keys, kind, timeoutSeconds, resolve, connectionId) {
+    if (keys.length > maxKeysPerWait) {
+      return { error: 'ERR too many keys per blocked command' };
+    }
+    if (totalWaiters >= maxTotalWaiters) {
+      return { error: 'ERR too many blocked clients' };
+    }
+    for (const k of keys) {
+      const mapKey = toMapKey(k);
+      const q = waitersByKey.get(mapKey) ?? [];
+      if (q.length >= maxWaitersPerKey) {
+        return { error: 'ERR too many blocked clients' };
+      }
+    }
+
+    const deadline =
+      timeoutSeconds > 0 ? clock() + timeoutSeconds * 1000 : null;
+    const waiter = {
+      connectionId,
+      kind,
+      keys: keys.slice(),
+      deadline,
+      resolve,
+      completed: false,
+      canceled: false,
+    };
+
+    let timer = null;
+    if (deadline != null) {
+      timer = setTimeout(() => {
+        if (waiter.completed || waiter.canceled) return;
+        waiter.completed = true;
+        removeWaiterFromQueues(waiter);
+        resolve(null);
+      }, timeoutSeconds * 1000);
+      if (timer.unref) timer.unref();
+    }
+    waiter.timer = timer;
+
+    totalWaiters++;
+    for (const key of keys) {
+      const mapKey = toMapKey(key);
+      let q = waitersByKey.get(mapKey);
+      if (!q) {
+        q = [];
+        waitersByKey.set(mapKey, q);
+      }
+      q.push({ waiter });
+    }
+    let connSet = waitersByConnection.get(connectionId);
+    if (!connSet) {
+      connSet = new Set();
+      waitersByConnection.set(connectionId, connSet);
+    }
+    connSet.add(waiter);
+    return {};
+  }
+
+  /**
+   * Called after LPUSH/RPUSH on key. Wake at most one waiter (oldest for this key).
+   * @param {Buffer|string} key - key that received the push
+   */
+  function wakeup(key) {
+    const mapKey = toMapKey(key);
+    const q = waitersByKey.get(mapKey);
+    if (!q || q.length === 0) return;
+    const ref = q[0];
+    const waiter = ref.waiter;
+    if (waiter.canceled || waiter.completed) {
+      removeWaiterFromQueues(waiter);
+      return;
+    }
+    tryWake(waiter);
+  }
+
+  /**
+   * On client disconnect: mark waiters canceled and remove from queues.
+   * @param {string|number} connectionId
+   */
+  function cancel(connectionId) {
+    const connSet = waitersByConnection.get(connectionId);
+    if (!connSet) return;
+    for (const waiter of new Set(connSet)) {
+      if (waiter.completed) continue;
+      waiter.canceled = true;
+      if (waiter.timer) {
+        clearTimeout(waiter.timer);
+        waiter.timer = null;
+      }
+      removeWaiterFromQueues(waiter);
+    }
+    waitersByConnection.delete(connectionId);
+  }
+
+  return {
+    registerWaiter,
+    wakeup,
+    cancel,
+  };
+}

package/src/cli/resplite-dirty-tracker.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * resplite-dirty-tracker (SPEC_F §F.6): subscribe to Redis keyspace notifications, record dirty keys in SQLite.
+ * Usage: resplite-dirty-tracker start|stop [options]
+ */
+
+import { createClient } from 'redis';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '../storage/sqlite/db.js';
+import { createRun, getRun, setRunStatus, upsertDirtyKey, logError, RUN_STATUS } from '../migration/registry.js';
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--from' && argv[i + 1]) args.from = argv[++i];
+    else if (arg === '--to' && argv[i + 1]) args.to = argv[++i];
+    else if (arg === '--run-id' && argv[i + 1]) args.runId = argv[++i];
+    else if (arg === '--channels' && argv[i + 1]) args.channels = argv[++i];
+    else if (arg === '--pragma-template' && argv[i + 1]) args.pragmaTemplate = argv[++i];
+    else if (!arg.startsWith('--')) args._.push(arg);
+  }
+  return args;
+}
+
+async function checkKeyspaceNotifications(client) {
+  let val = null;
+  try {
+    const config = await client.configGet('notify-keyspace-events');
+    val = config && typeof config === 'object' ? config['notify-keyspace-events'] : null;
+  } catch (_) {}
+  if (!val || val === '') {
+    throw new Error('Redis notify-keyspace-events is not set. Enable it (e.g. CONFIG SET notify-keyspace-events Kgxe) for the dirty-key tracker.');
+  }
+  return val;
+}
+
+async function startTracker(args) {
+  const redisUrl = args.from || process.env.RESPLITE_IMPORT_FROM || 'redis://127.0.0.1:6379';
+  const dbPath = args.to;
+  const runId = args.runId || process.env.RESPLITE_RUN_ID;
+  if (!dbPath || !runId) {
+    console.error('Usage: resplite-dirty-tracker start --run-id <id> --to <db-path> [--from <redis-url>] [--channels keyevent]');
+    process.exit(1);
+  }
+
+  const db = openDb(dbPath, { pragmaTemplate: args.pragmaTemplate || 'default' });
+  createRun(db, runId, redisUrl);
+
+  const mainClient = createClient({ url: redisUrl });
+  mainClient.on('error', (e) => console.error('Redis (main):', e.message));
+  await mainClient.connect();
+  await checkKeyspaceNotifications(mainClient);
+
+  const subClient = mainClient.duplicate();
+  subClient.on('error', (e) => {
+    console.error('Redis (sub):', e.message);
+    logError(db, runId, 'dirty_apply', 'Tracker disconnect: ' + e.message, null);
+  });
+  await subClient.connect();
+
+  const pattern = '__keyevent@0__:*';
+  console.log('Subscribing to', pattern, '...');
+
+  await subClient.pSubscribe(pattern, (message, channel) => {
+    const event = typeof channel === 'string' ? channel.split(':').pop() : (channel && channel.toString?.())?.split(':').pop() || 'unknown';
+    const key = message;
+    try {
+      upsertDirtyKey(db, runId, key, event);
+    } catch (err) {
+      logError(db, runId, 'dirty_apply', err.message, key);
+    }
+  });
+
+  const shutdown = async () => {
+    console.log('Stopping dirty tracker...');
+    await subClient.pUnsubscribe(pattern);
+    await subClient.quit();
+    await mainClient.quit();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  console.log('Dirty tracker running. Ctrl+C to stop.');
+}
+
+async function stopTracker(args) {
+  const dbPath = args.to;
+  const runId = args.runId || process.env.RESPLITE_RUN_ID;
+  if (!dbPath || !runId) {
+    console.error('Usage: resplite-dirty-tracker stop --run-id <id> --to <db-path>');
+    process.exit(1);
+  }
+  const db = openDb(dbPath, { pragmaTemplate: args.pragmaTemplate || 'default' });
+  const run = getRun(db, runId);
+  if (run && run.status === RUN_STATUS.RUNNING) {
+    setRunStatus(db, runId, RUN_STATUS.PAUSED);
+    console.log('Run', runId, 'status set to paused. Tracker process must be stopped with Ctrl+C if still running.');
+  } else {
+    console.log('Run', runId, 'status:', run?.status ?? 'not found');
+  }
+}
+
+async function main() {
+  const args = parseArgs();
+  const sub = args._[0];
+  if (sub === 'start') await startTracker(args);
+  else if (sub === 'stop') await stopTracker(args);
+  else {
+    console.error('Usage: resplite-dirty-tracker <start|stop> --run-id <id> --to <db-path> [--from <redis-url>]');
+    process.exit(1);
+  }
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url) || process.argv[1]?.endsWith('resplite-dirty-tracker.js');
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, startTracker, stopTracker };

package/src/cli/resplite-import.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * resplite-import CLI (SPEC_F §F.9): preflight, bulk, status, apply-dirty, verify.
+ * Usage: resplite-import <preflight|bulk|status|apply-dirty|verify> [options]
+ */
+
+import { createClient } from 'redis';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '../storage/sqlite/db.js';
+import { runPreflight } from '../migration/preflight.js';
+import { runBulkImport } from '../migration/bulk.js';
+import { runApplyDirty } from '../migration/apply-dirty.js';
+import { runVerify } from '../migration/verify.js';
+import { getRun, getDirtyCounts } from '../migration/registry.js';
+
+const SUBCOMMANDS = ['preflight', 'bulk', 'status', 'apply-dirty', 'verify'];
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--from' && argv[i + 1]) {
+      args.from = argv[++i];
+    } else if (arg === '--to' && argv[i + 1]) {
+      args.to = argv[++i];
+    } else if (arg === '--run-id' && argv[i + 1]) {
+      args.runId = argv[++i];
+    } else if (arg === '--scan-count' && argv[i + 1]) {
+      args.scanCount = parseInt(argv[++i], 10);
+    } else if (arg === '--max-concurrency' && argv[i + 1]) {
+      args.maxConcurrency = parseInt(argv[++i], 10);
+    } else if (arg === '--max-rps' && argv[i + 1]) {
+      args.maxRps = parseInt(argv[++i], 10);
+    } else if (arg === '--batch-keys' && argv[i + 1]) {
+      args.batchKeys = parseInt(argv[++i], 10);
+    } else if (arg === '--batch-bytes' && argv[i + 1]) {
+      const v = argv[++i];
+      const match = v.match(/^(\d+)(MB|KB|GB)?$/i);
+      if (match) {
+        let n = parseInt(match[1], 10);
+        if (match[2]) {
+          if (match[2].toUpperCase() === 'KB') n *= 1024;
+          else if (match[2].toUpperCase() === 'MB') n *= 1024 * 1024;
+          else if (match[2].toUpperCase() === 'GB') n *= 1024 * 1024 * 1024;
+        }
+        args.batchBytes = n;
+      }
+    } else if (arg === '--resume') {
+      args.resume = true;
+    } else if (arg === '--pragma-template' && argv[i + 1]) {
+      args.pragmaTemplate = argv[++i];
+    } else if (arg === '--sample' && argv[i + 1]) {
+      args.sample = argv[++i];
+    } else if (arg.startsWith('--')) {
+      args[arg.slice(2).replace(/-/g, '')] = argv[i + 1] ?? true;
+      if (argv[i + 1] && !argv[i + 1].startsWith('--')) i++;
+    } else {
+      args._.push(arg);
+    }
+  }
+  return args;
+}
+
+function getRedisUrl(args) {
+  return args.from || process.env.RESPLITE_IMPORT_FROM || 'redis://127.0.0.1:6379';
+}
+
+function getDbPath(args) {
+  if (!args.to) {
+    console.error('Missing --to <db-path>');
+    process.exit(1);
+  }
+  return args.to;
+}
+
+function getRunId(args, required = false) {
+  const id = args.runId || process.env.RESPLITE_RUN_ID;
+  if (required && !id) {
+    console.error('Missing --run-id <id>');
+    process.exit(1);
+  }
+  return id;
+}
+
+async function cmdPreflight(args) {
+  const redisUrl = getRedisUrl(args);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    const result = await runPreflight(client);
+    console.log('Preflight:');
+    console.log('  Key count (estimate):', result.keyCountEstimate);
+    console.log('  Type distribution (sample):', result.typeDistribution);
+    console.log('  notify-keyspace-events:', result.notifyKeyspaceEvents ?? '(not set or not readable)');
+    if (!result.notifyKeyspaceEvents || result.notifyKeyspaceEvents === '') {
+      console.warn('  WARNING: Keyspace notifications disabled. Enable for dirty-key tracker (e.g. "Kgxe").');
+    }
+    console.log('  Recommended:');
+    console.log('    --scan-count', result.recommended.scan_count);
+    console.log('    --max-concurrency', result.recommended.max_concurrency);
+    console.log('    --max-rps', result.recommended.max_rps);
+  } finally {
+    await client.quit();
+  }
+}
+
+async function cmdBulk(args) {
+  const redisUrl = getRedisUrl(args);
+  const dbPath = getDbPath(args);
+  const runId = getRunId(args, true);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    const run = await runBulkImport(client, dbPath, runId, {
+      sourceUri: redisUrl,
+      pragmaTemplate: args.pragmaTemplate || 'default',
+      scan_count: args.scanCount || 1000,
+      max_rps: args.maxRps || 0,
+      batch_keys: args.batchKeys || 200,
+      batch_bytes: args.batchBytes || 64 * 1024 * 1024,
+      resume: !!args.resume,
+      onProgress: (r) => {
+        console.log(`  scanned=${r.scanned_keys} migrated=${r.migrated_keys} skipped=${r.skipped_keys} errors=${r.error_keys} cursor=${r.scan_cursor}`);
+      },
+    });
+    console.log('Bulk complete:', run);
+  } finally {
+    await client.quit();
+  }
+}
+
+async function cmdStatus(args) {
+  const dbPath = getDbPath(args);
+  const runId = getRunId(args, true);
+  const db = openDb(dbPath, { pragmaTemplate: args.pragmaTemplate || 'default' });
+  const run = getRun(db, runId);
+  if (!run) {
+    console.error('Run not found:', runId);
+    process.exit(1);
+  }
+  const dirty = getDirtyCounts(db, runId);
+  console.log('Run:', runId);
+  console.log('  status:', run.status);
+  console.log('  source:', run.source_uri);
+  console.log('  scan_cursor:', run.scan_cursor);
+  console.log('  scanned_keys:', run.scanned_keys, 'migrated_keys:', run.migrated_keys, 'skipped_keys:', run.skipped_keys, 'error_keys:', run.error_keys);
+  console.log('  migrated_bytes:', run.migrated_bytes);
+  console.log('  dirty_keys: seen=', run.dirty_keys_seen, 'applied=', run.dirty_keys_applied, 'deleted=', run.dirty_keys_deleted);
+  console.log('  dirty by state:', dirty);
+  if (run.last_error) console.log('  last_error:', run.last_error);
+}
+
+async function cmdApplyDirty(args) {
+  const redisUrl = getRedisUrl(args);
+  const dbPath = getDbPath(args);
+  const runId = getRunId(args, true);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    const run = await runApplyDirty(client, dbPath, runId, {
+      pragmaTemplate: args.pragmaTemplate || 'default',
+      batch_keys: args.batchKeys || 200,
+      max_rps: args.maxRps || 0,
+    });
+    console.log('Apply-dirty complete:', run);
+  } finally {
+    await client.quit();
+  }
+}
+
+async function cmdVerify(args) {
+  const redisUrl = getRedisUrl(args);
+  const dbPath = getDbPath(args);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    let samplePct = 0.5;
+    if (args.sample) {
+      const m = args.sample.match(/^(\d*\.?\d+)\s*%?$/);
+      if (m) samplePct = parseFloat(m[1]);
+    }
+    const result = await runVerify(client, dbPath, {
+      pragmaTemplate: args.pragmaTemplate || 'default',
+      samplePct,
+      maxSample: 10000,
+    });
+    console.log('Verify: sampled=', result.sampled, 'matched=', result.matched, 'mismatches=', result.mismatches.length);
+    if (result.mismatches.length) {
+      result.mismatches.slice(0, 20).forEach((m) => console.log('  ', m.key, m.reason));
+      if (result.mismatches.length > 20) console.log('  ... and', result.mismatches.length - 20, 'more');
+    }
+  } finally {
+    await client.quit();
+  }
+}
+
+async function main() {
+  const args = parseArgs();
+  const sub = args._[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error('Usage: resplite-import <preflight|bulk|status|apply-dirty|verify> [options]');
+    console.error('  --from <redis-url>   (default: redis://127.0.0.1:6379)');
+    console.error('  --to <db-path>       (required for bulk, status, apply-dirty, verify)');
+    console.error('  --run-id <id>        (required for bulk, status, apply-dirty)');
+    console.error('  --scan-count N       (bulk, default 1000)');
+    console.error('  --max-rps N          (bulk, apply-dirty)');
+    console.error('  --batch-keys N       (default 200)');
+    console.error('  --batch-bytes N[MB|KB|GB] (default 64MB)');
+    console.error('  --resume             (bulk: resume from checkpoint)');
+    console.error('  --sample 0.5%        (verify, default 0.5%)');
+    process.exit(1);
+  }
+  try {
+    if (sub === 'preflight') await cmdPreflight(args);
+    else if (sub === 'bulk') await cmdBulk(args);
+    else if (sub === 'status') await cmdStatus(args);
+    else if (sub === 'apply-dirty') await cmdApplyDirty(args);
+    else if (sub === 'verify') await cmdVerify(args);
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url) || process.argv[1]?.endsWith('resplite-import.js');
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, cmdPreflight, cmdBulk, cmdStatus, cmdApplyDirty, cmdVerify };

package/src/commands/blpop.js

@@ -0,0 +1,50 @@
+/**
+ * BLPOP key [key ...] timeout
+ * Block until one of the keys has an element, or timeout (seconds). timeout 0 = block indefinitely.
+ * Returns [key, element] on success, nil on timeout.
+ */
+
+import { ERRORS } from '../engine/errors.js';
+
+function parseTimeout(arg) {
+  if (arg == null || arg === '') return null;
+  const s = Buffer.isBuffer(arg) ? arg.toString('utf8') : String(arg);
+  const n = parseInt(s, 10);
+  if (Number.isNaN(n) || s.trim() === '' || String(n) !== s.trim()) return null;
+  return n;
+}
+
+export function handleBlpop(engine, args, context) {
+  if (!args || args.length < 2) {
+    return { error: 'ERR wrong number of arguments for \'BLPOP\' command' };
+  }
+  const timeoutArg = args[args.length - 1];
+  const timeoutSeconds = parseTimeout(timeoutArg);
+  if (timeoutSeconds === null || timeoutSeconds < 0) {
+    return { error: 'ERR timeout is not an integer or out of range' };
+  }
+  const keys = args.slice(0, -1);
+
+  try {
+    for (const key of keys) {
+      const t = engine.type(key);
+      if (t !== 'none' && t !== 'list') {
+        return { error: ERRORS.WRONGTYPE };
+      }
+    }
+    for (const key of keys) {
+      const val = engine.lpop(key, null);
+      if (val != null) {
+        return [key, val];
+      }
+    }
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    return { error: msg.startsWith('ERR ') ? msg : msg.startsWith('WRONGTYPE') ? msg : 'ERR ' + msg };
+  }
+
+  if (!context) {
+    return { error: 'ERR blocking not supported in this context' };
+  }
+  return { block: { keys, kind: 'BLPOP', timeoutSeconds } };
+}

package/src/commands/brpop.js

@@ -0,0 +1,50 @@
+/**
+ * BRPOP key [key ...] timeout
+ * Block until one of the keys has an element (pop from right), or timeout (seconds). timeout 0 = block indefinitely.
+ * Returns [key, element] on success, nil on timeout.
+ */
+
+import { ERRORS } from '../engine/errors.js';
+
+function parseTimeout(arg) {
+  if (arg == null || arg === '') return null;
+  const s = Buffer.isBuffer(arg) ? arg.toString('utf8') : String(arg);
+  const n = parseInt(s, 10);
+  if (Number.isNaN(n) || s.trim() === '' || String(n) !== s.trim()) return null;
+  return n;
+}
+
+export function handleBrpop(engine, args, context) {
+  if (!args || args.length < 2) {
+    return { error: 'ERR wrong number of arguments for \'BRPOP\' command' };
+  }
+  const timeoutArg = args[args.length - 1];
+  const timeoutSeconds = parseTimeout(timeoutArg);
+  if (timeoutSeconds === null || timeoutSeconds < 0) {
+    return { error: 'ERR timeout is not an integer or out of range' };
+  }
+  const keys = args.slice(0, -1);
+
+  try {
+    for (const key of keys) {
+      const t = engine.type(key);
+      if (t !== 'none' && t !== 'list') {
+        return { error: ERRORS.WRONGTYPE };
+      }
+    }
+    for (const key of keys) {
+      const val = engine.rpop(key, null);
+      if (val != null) {
+        return [key, val];
+      }
+    }
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    return { error: msg.startsWith('ERR ') ? msg : msg.startsWith('WRONGTYPE') ? msg : 'ERR ' + msg };
+  }
+
+  if (!context) {
+    return { error: 'ERR blocking not supported in this context' };
+  }
+  return { block: { keys, kind: 'BRPOP', timeoutSeconds } };
+}

package/src/commands/registry.js

@@ -41,6 +41,8 @@ import * as lrange from './lrange.js';
 import * as lindex from './lindex.js';
 import * as lpop from './lpop.js';
 import * as rpop from './rpop.js';
+import * as blpop from './blpop.js';
+import * as brpop from './brpop.js';
 import * as scan from './scan.js';
 import * as zadd from './zadd.js';
 import * as zrem from './zrem.js';
@@ -97,8 +99,10 @@ const HANDLERS = new Map([
   ['LLEN', (e, a) => llen.handleLlen(e, a)],
   ['LRANGE', (e, a) => lrange.handleLrange(e, a)],
   ['LINDEX', (e, a) => lindex.handleLindex(e, a)],
-  ['LPOP', (e, a) => lpop.handleLpop(e, a)],
-  ['RPOP', (e, a) => rpop.handleRpop(e, a)],
+  ['LPOP', (e, a, ctx) => lpop.handleLpop(e, a)],
+  ['RPOP', (e, a, ctx) => rpop.handleRpop(e, a)],
+  ['BLPOP', (e, a, ctx) => blpop.handleBlpop(e, a, ctx)],
+  ['BRPOP', (e, a, ctx) => brpop.handleBrpop(e, a, ctx)],
   ['SCAN', (e, a) => scan.handleScan(e, a)],
   ['ZADD', (e, a) => zadd.handleZadd(e, a)],
   ['ZREM', (e, a) => zrem.handleZrem(e, a)],
@@ -123,9 +127,10 @@ const HANDLERS = new Map([
  * Dispatch command. Full argv: [commandNameBuf, ...argBuffers].
  * @param {object} engine
  * @param {Buffer[]} argv - first element is command name, rest are arguments
- * @returns {{ result: unknown } | { error: string } | { quit: true }}
+ * @param {object} [context] - optional connection context (connectionId, writeResponse) for blocking commands
+ * @returns {{ result: unknown } | { error: string } | { quit: true } | { block: object }}
  */
-export function dispatch(engine, argv) {
+export function dispatch(engine, argv, context) {
   if (!argv || argv.length === 0) {
     return { error: 'ERR wrong number of arguments' };
   }
@@ -136,9 +141,10 @@ export function dispatch(engine, argv) {
     return { error: unsupported() };
   }
   try {
-    const result = handler(engine, args);
+    const result = handler(engine, args, context);
     if (result && result.quit) return result;
     if (result && result.error) return result;
+    if (result && result.block) return result;
     return { result };
   } catch (err) {
     const msg = err && err.message ? err.message : String(err);