spindb 0.69.1 → 0.69.4

package/dist/engines/redis/resp-client.js

@@ -46,7 +46,12 @@ function parseReply(buf, offset) {
         case 0x2b: // '+' simple string
             return { value: line, offset: lineEnd };
         case 0x2d: // '-' error
-            return { value: new Error(line), offset: lineEnd };
+            // A bare `-\r\n` carries no text at all. An Error with an empty message
+            // is indistinguishable from "no error" once it is serialized, so name it.
+            return {
+                value: new Error(line || 'The server returned an empty error reply'),
+                offset: lineEnd,
+            };
         case 0x3a: // ':' integer
             return { value: Number(line), offset: lineEnd };
         case 0x24: {
@@ -79,6 +84,13 @@ function parseReply(buf, offset) {
             throw new Error(`Unsupported RESP reply type: ${String.fromCharCode(type)}`);
     }
 }
+// The first byte of every reply RESP2 can produce. Anything else means we are
+// not talking to a Redis server on this port - a TLS record, an HTTP response,
+// or a RESP3 reply from a server that volunteered one. Bailing out on sight is
+// what keeps a mis-typed `redis://` against a TLS-only endpoint from hanging:
+// those bytes carry no CRLF, so the incremental parser would otherwise wait for
+// a line terminator that never arrives.
+const RESP2_REPLY_TYPES = new Set([0x2b, 0x2d, 0x3a, 0x24, 0x2a]);
 // Usernames that name no real ACL user, so AUTH must be sent in its
 // one-argument form (`AUTH <password>`) instead of `AUTH <user> <password>`.
 //
@@ -99,24 +111,82 @@ export function buildRespAuthArgs(password, username) {
         ? ['AUTH', username, password]
         : ['AUTH', password];
 }
+// The handshake rejections a pasted connection string actually produces, each
+// with the one sentence that says what to change. The server's own text is
+// always kept - it is the ground truth - and the hint is appended.
+const HANDSHAKE_HINTS = [
+    {
+        match: /^WRONGPASS/i,
+        hint: 'The username or password in the connection string was rejected. Copy the URL again from the provider console - a rotated credential is the usual cause.',
+    },
+    {
+        match: /^NOAUTH/i,
+        hint: 'The server wants credentials the connection string does not carry. Use the full redis://user:password@host:port URL.',
+    },
+    {
+        match: /Client sent AUTH, but no password is set/i,
+        hint: 'The connection string carries a password but the server has none configured. Drop the credentials from the URL.',
+    },
+    {
+        match: /wrong number of arguments for 'auth'/i,
+        hint: 'This server predates ACL users (Redis 5 or older), so it only accepts a password. Remove the username from the connection string.',
+    },
+    {
+        match: /DB index is out of range|SELECT is not allowed/i,
+        hint: 'The source does not have the numbered database from the end of the URL. Most managed Redis exposes only db 0 - drop the /N suffix.',
+    },
+];
+export function annotateHandshakeError(error) {
+    const hint = HANDSHAKE_HINTS.find((h) => h.match.test(error.message))?.hint;
+    if (!hint)
+        return error;
+    // Server messages end with a period about half the time; do not double it.
+    const text = error.message.replace(/\.\s*$/, '');
+    return new Error(`${text}. ${hint}`);
+}
 export class RespClient {
     socket;
     inbox = Buffer.alloc(0);
     // FIFO of resolvers, one per in-flight command (pipelining-friendly).
     queue = [];
     fatal = null;
-    constructor(socket) {
+    constructor(socket, idleTimeoutMs) {
         this.socket = socket;
         socket.on('data', (chunk) => this.onData(chunk));
         socket.on('error', (err) => this.onFatal(err));
         socket.on('close', () => this.onFatal(new Error('Redis connection closed')));
+        if (idleTimeoutMs > 0) {
+            socket.setTimeout(idleTimeoutMs);
+            socket.on('timeout', () => this.onIdle(idleTimeoutMs));
+        }
     }
     onData(chunk) {
         this.inbox =
             this.inbox.length === 0 ? chunk : Buffer.concat([this.inbox, chunk]);
         let offset = 0;
         for (;;) {
-            const parsed = parseReply(this.inbox, offset);
+            if (offset < this.inbox.length &&
+                !RESP2_REPLY_TYPES.has(this.inbox[offset])) {
+                this.onFatal(new Error('The server did not answer with the Redis protocol (first reply byte ' +
+                    `0x${this.inbox[offset].toString(16).padStart(2, '0')}). ` +
+                    'If the source requires TLS, use rediss:// instead of redis://; ' +
+                    'if it is behind an HTTP proxy or a REST-only endpoint, point at the ' +
+                    'database port instead.'));
+                this.socket.destroy();
+                return;
+            }
+            // A malformed reply must not escape as an uncaught exception: `onData`
+            // runs on the socket's 'data' event, so a throw here would take the whole
+            // process down mid-migration with no --json output at all.
+            let parsed;
+            try {
+                parsed = parseReply(this.inbox, offset);
+            }
+            catch (error) {
+                this.onFatal(error instanceof Error ? error : new Error(String(error)));
+                this.socket.destroy();
+                return;
+            }
             if (!parsed)
                 break;
             offset = parsed.offset;
@@ -130,6 +200,15 @@ export class RespClient {
         }
         this.inbox = offset === 0 ? this.inbox : this.inbox.subarray(offset);
     }
+    // Socket inactivity. Only fatal while we are actually waiting on a reply -
+    // an idle connection between commands is normal and must not be torn down.
+    onIdle(idleTimeoutMs) {
+        if (this.queue.length === 0)
+            return;
+        this.onFatal(new Error(`The Redis server stopped responding (no reply for ${idleTimeoutMs}ms with ` +
+            `${this.queue.length} command(s) in flight)`));
+        this.socket.destroy();
+    }
     onFatal(err) {
         if (this.fatal)
             return;
@@ -160,13 +239,37 @@ export class RespClient {
         this.socket.write(Buffer.concat(commands.map(encodeCommand)));
         return Promise.all(promises);
     }
+    // Like `pipeline`, but a per-command `-ERR` comes back as an Error VALUE
+    // instead of rejecting the batch. The migration needs this to tell "every
+    // RESTORE in this batch was refused because the payload format is foreign"
+    // (recoverable - fall back to a logical copy) from "one key blew up"
+    // (a real failure), which `Promise.all` cannot express: it surfaces the first
+    // rejection and hides the rest.
+    async pipelineSettled(commands) {
+        if (this.fatal)
+            throw this.fatal;
+        const promises = commands.map(() => new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject });
+        }));
+        this.socket.write(Buffer.concat(commands.map(encodeCommand)));
+        const settled = await Promise.allSettled(promises);
+        // A socket-level failure rejects every outstanding waiter with the same
+        // Error. That is not a per-command refusal and must not be mistaken for
+        // one, so re-throw instead of handing back a list of Errors.
+        if (this.fatal)
+            throw this.fatal;
+        return settled.map((s) => s.status === 'fulfilled'
+            ? s.value
+            : s.reason instanceof Error
+                ? s.reason
+                : new Error(String(s.reason)));
+    }
     close() {
         this.socket.destroy();
     }
     static async connect(opts) {
+        const timeoutMs = opts.connectTimeoutMs ?? 15000;
         const socket = await new Promise((resolve, reject) => {
-            const onError = (err) => reject(err);
-            const timeoutMs = opts.connectTimeoutMs ?? 15000;
             const s = opts.tls
                 ? tlsConnect({
                     host: opts.host,
@@ -175,24 +278,42 @@ export class RespClient {
                     rejectUnauthorized: opts.rejectUnauthorized ?? false,
                 })
                 : netConnect({ host: opts.host, port: opts.port });
+            // A rejected connect must not leave the socket open: nothing else holds a
+            // reference to it, so the handle would keep the process alive.
+            const onError = (err) => {
+                s.destroy();
+                reject(err);
+            };
+            const onTimeout = () => {
+                s.destroy();
+                reject(new Error(`Redis connection timed out after ${timeoutMs}ms`));
+            };
             const onReady = () => {
+                // Both handlers have to go, not just 'error': the connect deadline is
+                // re-armed as an IDLE deadline by the constructor, and leaving this
+                // listener attached would tear the socket down on a quiet moment.
                 s.removeListener('error', onError);
+                s.removeListener('timeout', onTimeout);
                 s.setTimeout(0);
                 resolve(s);
             };
-            s.setTimeout(timeoutMs, () => {
-                s.destroy();
-                reject(new Error(`Redis connection timed out after ${timeoutMs}ms`));
-            });
+            s.setTimeout(timeoutMs);
+            s.once('timeout', onTimeout);
             s.once('error', onError);
             s.once(opts.tls ? 'secureConnect' : 'connect', onReady);
         });
-        const client = new RespClient(socket);
-        if (opts.password) {
-            await client.command(buildRespAuthArgs(opts.password, opts.username));
+        const client = new RespClient(socket, opts.idleTimeoutMs ?? timeoutMs * 4);
+        try {
+            if (opts.password) {
+                await client.command(buildRespAuthArgs(opts.password, opts.username));
+            }
+            if (opts.database && opts.database > 0) {
+                await client.command(['SELECT', String(opts.database)]);
+            }
         }
-        if (opts.database && opts.database > 0) {
-            await client.command(['SELECT', String(opts.database)]);
+        catch (error) {
+            client.close();
+            throw error instanceof Error ? annotateHandshakeError(error) : error;
         }
         return client;
     }
@@ -221,10 +342,386 @@ export class RespClient {
         return { cursor: nextCursor, keys };
     }
 }
-// Binary-safe keyspace copy: SCAN the source, pipeline DUMP+PTTL per batch, and
-// RESTORE (with TTL, REPLACE) into the target. Preserves every type and TTL
-// exactly because DUMP/RESTORE moves Redis's own serialization. Used by the
-// `restore --from-url` path for redis/valkey. Returns the number of keys copied.
+// Why the fast path is not always available.
+//
+// DUMP payloads are stamped with the RDB version of the server that produced
+// them, and RESTORE refuses anything its own format does not cover. That is not
+// a "the target is too old" problem that a version bump fixes - Redis and Valkey
+// now serialize into DIFFERENT number spaces:
+//
+//   Redis 7.2            RDB 11        Valkey 8.0    RDB 11
+//   Redis 8.x            RDB 12        Valkey 9.0    RDB 80
+//   Upstash (8.4-compat) RDB 14
+//
+// so a Valkey 9 source cannot RESTORE into any Redis at all, and a Redis 8 or
+// Upstash source cannot RESTORE into Redis 7.2 or Valkey. Measured 2026-09-09
+// against live servers of each. A serverless provider may also simply not
+// implement DUMP. Either way the answer is the same: stop trying to move bytes
+// and move values instead.
+function isPayloadFormatRefusal(message) {
+    return /DUMP payload version or checksum are wrong|Bad data format/i.test(message);
+}
+function isCommandUnavailable(message) {
+    return /unknown command|Command is not available|unsupported command|ERR .*not supported/i.test(message);
+}
+export function shouldFallBackToLogicalCopy(message) {
+    return isPayloadFormatRefusal(message) || isCommandUnavailable(message);
+}
+// The TARGET is full: it has a `maxmemory` and the copy reached it.
+//
+// This is NOT a fallback case. Neither strategy can write a key the server has
+// refused to store, so retrying with the logical path would only walk into the
+// same wall more slowly. It is also the one copy failure whose fix belongs to
+// the operator rather than to spindb, so it gets said plainly instead of being
+// handed over as a bare server code.
+//
+// `MISCONF` refuses writes identically from the caller's side and leaves the
+// same half-populated keyspace, so it is handled here too - but its CAUSE is
+// persistence, not memory, and telling the operator to raise `maxmemory` sends
+// them at the wrong setting. The two are classified apart and worded apart.
+function isTargetOutOfMemory(message) {
+    return /^(?:\(error\)\s*)?OOM\b/m.test(message.trim());
+}
+function isTargetPersistenceFailure(message) {
+    return /^(?:\(error\)\s*)?MISCONF\b/m.test(message.trim());
+}
+/** Either way the target refused the write and the copy is partial. */
+function isTargetWriteRefusal(message) {
+    return isTargetOutOfMemory(message) || isTargetPersistenceFailure(message);
+}
+/**
+ * Restate a target-side write refusal in terms the person running the copy can
+ * act on, leaving every other error exactly as the server sent it.
+ */
+export function describeTargetWriteFailure(error) {
+    const raw = error.message.trim();
+    if (isTargetOutOfMemory(error.message)) {
+        return new Error(`The target database is out of memory and refused the write, so only part ` +
+            `of the keyspace was copied. Its maxmemory is smaller than the source's ` +
+            `data. Raise the target's memory limit, or reduce what is being copied, ` +
+            `then run the copy again. (${raw})`);
+    }
+    if (isTargetPersistenceFailure(error.message)) {
+        return new Error(`The target database refused the write because its RDB/AOF persistence is ` +
+            `failing (MISCONF), so only part of the keyspace was copied. Check the ` +
+            `target server's disk space and its stop-writes-on-bgsave-error / save ` +
+            `settings, fix the background save, then run the copy again. (${raw})`);
+    }
+    return error;
+}
+// Value types the logical path knows how to read and rewrite.
+const LOGICAL_COPY_TYPES = new Set([
+    'string',
+    'list',
+    'set',
+    'zset',
+    'hash',
+    'stream',
+]);
+// Elements pulled per read round-trip, and written per command. Keeps a single
+// reply (and a single command) bounded regardless of how large one key is, which
+// matters both for our own memory and for providers that cap response size.
+// Kept EVEN on purpose: hashes and sorted sets are written as field/value and
+// score/member PAIRS, and an odd chunk would split one across two commands.
+const ELEMENT_CHUNK = 512;
+function replyToBuffer(reply) {
+    return Buffer.isBuffer(reply) ? reply : null;
+}
+function replyToString(reply) {
+    if (Buffer.isBuffer(reply))
+        return reply.toString('latin1');
+    if (typeof reply === 'string')
+        return reply;
+    return '';
+}
+function replyToBuffers(reply) {
+    return Array.isArray(reply)
+        ? reply.filter((r) => Buffer.isBuffer(r))
+        : [];
+}
+// A *SCAN reply: [cursor, [element, ...]].
+function parseScanReply(reply) {
+    if (!Array.isArray(reply) || reply.length < 2) {
+        throw new Error('Unexpected SCAN reply while reading a collection');
+    }
+    return { cursor: replyToString(reply[0]), items: replyToBuffers(reply[1]) };
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+// The first read for a key of this type. Every one of these returns whatever
+// fits in a single chunk, so a batch of keys can be read in ONE round-trip and
+// only the oversized ones need a follow-up walk.
+function firstReadCommand(type, key) {
+    switch (type) {
+        case 'string':
+            return ['GET', key];
+        case 'hash':
+            return ['HSCAN', key, '0', 'COUNT', String(ELEMENT_CHUNK)];
+        case 'set':
+            return ['SSCAN', key, '0', 'COUNT', String(ELEMENT_CHUNK)];
+        case 'zset':
+            return ['ZSCAN', key, '0', 'COUNT', String(ELEMENT_CHUNK)];
+        case 'list':
+            return ['LRANGE', key, '0', String(ELEMENT_CHUNK - 1)];
+        case 'stream':
+            return ['XRANGE', key, '-', '+', 'COUNT', String(ELEMENT_CHUNK)];
+        default:
+            return null;
+    }
+}
+// The largest sequence a stream id can hold: both halves of a stream id are
+// unsigned 64-bit, and Redis rolls a full sequence over into the next
+// millisecond rather than refusing the entry.
+const STREAM_ID_PART_MAX = 18446744073709551615n;
+// Stream ids are `<ms>-<seq>`. XRANGE ranges are inclusive, and the exclusive
+// `(` form only exists from Redis 6.2, so the next page starts at seq+1 of the
+// last id we saw - a form every version understands.
+//
+// The arithmetic is BigInt because both halves are uint64 and a Number cannot
+// hold one past 2^53. `Number('9007199254740993') + 1` is 9007199254740994 by
+// luck, but `Number('18446744073709551615') + 1` is 18446744073709552000 - a
+// value that is not the next id and is not even in the stream, so the walk
+// would silently skip the tail of a large stream. A sequence that is already at
+// the maximum carries into the next millisecond, exactly as Redis does when it
+// assigns one.
+export function nextStreamId(id) {
+    const match = /^(\d+)(?:-(\d+))?$/.exec(id);
+    if (!match) {
+        throw new Error(`Unexpected stream entry id from the source: ${id}`);
+    }
+    const ms = BigInt(match[1]);
+    const seq = match[2] === undefined ? 0n : BigInt(match[2]);
+    return seq >= STREAM_ID_PART_MAX ? `${ms + 1n}-0` : `${ms}-${seq + 1n}`;
+}
+function parseStreamEntries(reply) {
+    if (!Array.isArray(reply))
+        return [];
+    const entries = [];
+    for (const item of reply) {
+        if (!Array.isArray(item) || item.length < 2)
+            continue;
+        entries.push({
+            id: replyToString(item[0]),
+            fields: replyToBuffers(item[1]),
+        });
+    }
+    return entries;
+}
+// Finish reading a key whose first chunk came back full. `first` is that chunk.
+async function readRemainder(src, key, type, first) {
+    switch (type) {
+        case 'string': {
+            const value = replyToBuffer(first);
+            // A key that vanished between SCAN and GET is a non-event, not an error.
+            return value ? { kind: 'string', value } : { kind: 'skip', type: 'none' };
+        }
+        case 'hash':
+        case 'set':
+        case 'zset': {
+            const { cursor, items } = parseScanReply(first);
+            const all = items;
+            let next = cursor;
+            while (next !== '0') {
+                const page = parseScanReply(await src.command([
+                    type === 'hash' ? 'HSCAN' : type === 'set' ? 'SSCAN' : 'ZSCAN',
+                    key,
+                    next,
+                    'COUNT',
+                    String(ELEMENT_CHUNK),
+                ]));
+                all.push(...page.items);
+                next = page.cursor;
+            }
+            return { kind: 'elements', type, items: all };
+        }
+        case 'list': {
+            const all = replyToBuffers(first);
+            // A short page means the end of the list; a full one means there may be
+            // more, so keep walking from where the last page stopped.
+            while (all.length > 0 && all.length % ELEMENT_CHUNK === 0) {
+                const page = replyToBuffers(await src.command([
+                    'LRANGE',
+                    key,
+                    String(all.length),
+                    String(all.length + ELEMENT_CHUNK - 1),
+                ]));
+                if (page.length === 0)
+                    break;
+                all.push(...page);
+            }
+            return { kind: 'elements', type: 'list', items: all };
+        }
+        case 'stream': {
+            const entries = parseStreamEntries(first);
+            while (entries.length > 0 && entries.length % ELEMENT_CHUNK === 0) {
+                const page = parseStreamEntries(await src.command([
+                    'XRANGE',
+                    key,
+                    nextStreamId(entries[entries.length - 1].id),
+                    '+',
+                    'COUNT',
+                    String(ELEMENT_CHUNK),
+                ]));
+                if (page.length === 0)
+                    break;
+                entries.push(...page);
+            }
+            return { kind: 'stream', entries };
+        }
+        default:
+            return { kind: 'skip', type };
+    }
+}
+// The commands that recreate one key on the target. A collection is DELeted
+// first so a re-run replaces it instead of appending to it - the same
+// replace-in-place semantics RESTORE ... REPLACE gives the fast path.
+function writeCommands(key, contents, ttlMs) {
+    const cmds = [];
+    if (contents.kind === 'string') {
+        // SET replaces a key of ANY previous type, so it needs no DEL, and PX folds
+        // the expiry into the same command.
+        cmds.push(ttlMs > 0
+            ? ['SET', key, contents.value, 'PX', String(ttlMs)]
+            : ['SET', key, contents.value]);
+        return cmds;
+    }
+    if (contents.kind === 'elements') {
+        if (contents.items.length === 0)
+            return cmds; // an empty collection cannot exist
+        cmds.push(['DEL', key]);
+        const writer = contents.type === 'hash'
+            ? 'HSET'
+            : contents.type === 'set'
+                ? 'SADD'
+                : contents.type === 'zset'
+                    ? 'ZADD'
+                    : 'RPUSH';
+        // ZSCAN and HSCAN return flat member/score and field/value pairs. ZADD
+        // wants score BEFORE member, which is the order ZSCAN already yields
+        // reversed, so zsets are re-paired; the others are already in write order.
+        const args = contents.type === 'zset'
+            ? contents.items.flatMap((_, i, arr) => i % 2 === 0 ? [arr[i + 1], arr[i]] : [])
+            : contents.items;
+        for (const part of chunk(args, ELEMENT_CHUNK)) {
+            cmds.push([writer, key, ...part]);
+        }
+        if (ttlMs > 0)
+            cmds.push(['PEXPIRE', key, String(ttlMs)]);
+        return cmds;
+    }
+    if (contents.kind === 'stream') {
+        if (contents.entries.length === 0)
+            return cmds;
+        cmds.push(['DEL', key]);
+        for (const entry of contents.entries) {
+            cmds.push(['XADD', key, entry.id, ...entry.fields]);
+        }
+        if (ttlMs > 0)
+            cmds.push(['PEXPIRE', key, String(ttlMs)]);
+    }
+    return cmds;
+}
+// Read one batch of keys off the source and rewrite them on the target with
+// type-specific commands. Returns how many keys landed and which types had to
+// be skipped.
+async function copyBatchLogically(src, dst, keys) {
+    const probe = await src.pipeline(keys.flatMap((k) => [
+        ['TYPE', k],
+        ['PTTL', k],
+    ]));
+    const types = keys.map((_, i) => replyToString(probe[i * 2]));
+    const ttls = keys.map((_, i) => {
+        const pttl = probe[i * 2 + 1];
+        return typeof pttl === 'number' && pttl > 0 ? pttl : 0;
+    });
+    // One round-trip for the first (and usually only) chunk of every key.
+    const readable = keys
+        .map((key, i) => ({ key, i, cmd: firstReadCommand(types[i], key) }))
+        .filter((r) => r.cmd !== null);
+    const firsts = readable.length > 0 ? await src.pipeline(readable.map((r) => r.cmd)) : [];
+    const skippedTypes = new Set();
+    let skipped = 0;
+    for (const type of types) {
+        // `none` means the key expired or was deleted between SCAN and TYPE.
+        if (type !== 'none' && !LOGICAL_COPY_TYPES.has(type)) {
+            skippedTypes.add(type);
+            skipped++;
+        }
+    }
+    const writes = [];
+    let copied = 0;
+    for (const [n, entry] of readable.entries()) {
+        const contents = await readRemainder(src, entry.key, types[entry.i], firsts[n]);
+        if (contents.kind === 'skip')
+            continue;
+        const cmds = writeCommands(entry.key, contents, ttls[entry.i]);
+        if (cmds.length === 0)
+            continue;
+        writes.push(...cmds);
+        copied++;
+    }
+    for (const part of chunk(writes, ELEMENT_CHUNK)) {
+        try {
+            await dst.pipeline(part);
+        }
+        catch (error) {
+            // Same restatement as the DUMP/RESTORE path: the logical walk hits the
+            // target's ceiling in exactly the same way, and this is the strategy
+            // there is no falling back FROM.
+            throw describeTargetWriteFailure(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    return { copied, skipped, skippedTypes };
+}
+// Move one batch with DUMP/RESTORE. Returns null when the target refused the
+// payload format (or an end does not implement the commands), which is the
+// caller's signal to switch to the logical path for good.
+async function copyBatchWithDumpRestore(src, dst, keys) {
+    const probe = await src.pipelineSettled(keys.flatMap((k) => [
+        ['DUMP', k],
+        ['PTTL', k],
+    ]));
+    const restoreCmds = [];
+    for (let i = 0; i < keys.length; i++) {
+        const payload = probe[i * 2];
+        if (payload instanceof Error) {
+            // The source will not DUMP at all - nothing to retry, switch strategy.
+            if (shouldFallBackToLogicalCopy(payload.message))
+                return null;
+            throw payload;
+        }
+        const pttl = probe[i * 2 + 1];
+        // A key can vanish between SCAN and DUMP; DUMP returns null - skip it.
+        if (!Buffer.isBuffer(payload))
+            continue;
+        const ttlMs = typeof pttl === 'number' && pttl > 0 ? pttl : 0;
+        restoreCmds.push(['RESTORE', keys[i], String(ttlMs), payload, 'REPLACE']);
+    }
+    if (restoreCmds.length === 0)
+        return 0;
+    const results = await dst.pipelineSettled(restoreCmds);
+    const failures = results.filter((r) => r instanceof Error);
+    if (failures.length === 0)
+        return restoreCmds.length;
+    if (failures.every((f) => shouldFallBackToLogicalCopy(f.message)))
+        return null;
+    // A pipeline can carry several kinds of failure at once. A target-side write
+    // refusal (OOM / MISCONF) is the one the operator has to act on, and it is
+    // the reason the copy is partial, so it wins over an earlier per-key error
+    // that would otherwise be reported just for arriving first.
+    const refusal = failures.find((f) => isTargetWriteRefusal(f.message));
+    throw describeTargetWriteFailure(refusal ?? failures[0]);
+}
+// Binary-safe keyspace copy: SCAN the source, move each batch into the target,
+// and report progress as it goes. DUMP/RESTORE is tried first because it is
+// exact and cheap; the moment the target refuses that payload format the copy
+// switches - permanently, and re-doing the batch it was in the middle of - to a
+// type-aware read/write walk that does not depend on either end's RDB version.
+// Used by the `restore --from-url` path for redis/valkey.
 export async function copyRedisKeyspace(source, target, options = {}) {
     const batchSize = options.batchSize ?? 200;
     const src = await RespClient.connect(source);
@@ -234,55 +731,42 @@ export async function copyRedisKeyspace(source, target, options = {}) {
         const total = await src.dbsize();
         dst = await RespClient.connect(target);
         await dst.ping();
+        let strategy = options.strategy ?? 'dump-restore';
         let cursor = '0';
         let scanned = 0;
         let restored = 0;
+        let skipped = 0;
+        const skippedTypes = new Set();
         do {
             const { cursor: next, keys } = await src.scan(cursor, batchSize);
             cursor = next;
             if (keys.length === 0)
                 continue;
-            // DUMP + PTTL for every key in the batch, in one round-trip.
-            const probe = await src.pipeline(keys.flatMap((k) => [
-                ['DUMP', k],
-                ['PTTL', k],
-            ]));
-            const restoreCmds = [];
-            for (let i = 0; i < keys.length; i++) {
-                const payload = probe[i * 2];
-                const pttl = probe[i * 2 + 1];
-                // A key can vanish between SCAN and DUMP; DUMP returns null - skip it.
-                if (!Buffer.isBuffer(payload))
+            if (strategy === 'dump-restore') {
+                const moved = await copyBatchWithDumpRestore(src, dst, keys);
+                if (moved !== null) {
+                    scanned += keys.length;
+                    restored += moved;
+                    options.onProgress?.({ scanned, restored, total, strategy });
                     continue;
-                const ttlMs = typeof pttl === 'number' && pttl > 0 ? pttl : 0;
-                restoreCmds.push([
-                    'RESTORE',
-                    keys[i],
-                    String(ttlMs),
-                    payload,
-                    'REPLACE',
-                ]);
-            }
-            scanned += keys.length;
-            if (restoreCmds.length > 0) {
-                try {
-                    await dst.pipeline(restoreCmds);
                 }
-                catch (error) {
-                    const message = error.message;
-                    // RESTORE rejects a DUMP payload whose RDB version is newer than the
-                    // target supports - i.e. the source is a newer engine version than
-                    // the target. Surface that plainly instead of the raw checksum error.
-                    if (/DUMP payload version|checksum are wrong/i.test(message)) {
-                        throw new Error(`The target is an older engine version than the source, so its binary format is incompatible (${message}). Provision the target at the same major version as the source, or newer, and retry.`);
-                    }
-                    throw error;
-                }
-                restored += restoreCmds.length;
+                strategy = 'logical';
             }
-            options.onProgress?.({ scanned, restored, total });
+            const result = await copyBatchLogically(src, dst, keys);
+            scanned += keys.length;
+            restored += result.copied;
+            skipped += result.skipped;
+            for (const t of result.skippedTypes)
+                skippedTypes.add(t);
+            options.onProgress?.({ scanned, restored, total, strategy });
         } while (cursor !== '0');
-        return { keysCopied: restored, total };
+        return {
+            keysCopied: restored,
+            total,
+            strategy,
+            skipped,
+            skippedTypes: [...skippedTypes].sort(),
+        };
     }
     finally {
         src.close();