RESP2 and RESP3

The client speaks the Redis wire protocol itself. It can use RESP3 or RESP2, and the commands, option types and reply types are the same under both. The protocol option chooses what the connection asks for.

The protocol optionCopy Anchor Link

Example (Pinning a Protocol)

import { RedisNode } from "@effect-kit/redis/node";

export const Resp2 = RedisNode.layer({ url: "redis://localhost:6379", protocol: "resp2" });

HELLO 3 is sent after authentication and before CLIENT SETNAME and SELECT. The fallback in auto applies only to two rejections: NOPROTO unsupported protocol version and ERR unknown command 'HELLO'. A connection that is rejected for another reason fails with a HandshakeError with stage: "hello". If the server accepts HELLO 3 but does not report protocol 3, the connection also fails with stage: "hello".

The negotiated protocol is ConnectionSnapshot.protocol, which is "resp2", "resp3" or undefined before the handshake completes. Upstash HTTP has no protocol option.

What changes between the twoCopy Anchor Link

Nothing in the API. The reply decoders accept both shapes and return one type:

• Members (smembers, sinter) decode from a RESP3 set or a RESP2 array into readonly Uint8Array[].
• Field and value pairs (hgetall) decode from a RESP3 map, a RESP2 flat array or an array of pairs into an ordered array of tuples. Binary keys and duplicate keys are kept, and nothing becomes a JavaScript object.
• Scores decode from a RESP3 double or a RESP2 bulk string into the server's decimal text, or a number for zscore.
• A missing value is None. RESP2 uses a nil bulk string or a nil array and RESP3 uses a null. A nil array is not a missing scalar: an empty pop such as lpopCount on a missing list is None, and a missing string is None too, each through its own decoder.
• Attribute replies are unwrapped before decoding.

RespValueCopy Anchor Link

Replies are decoded into a lossless RespValue first and then into a typed value. redis.raw returns the RespValue without decoding it. Error replies from raw arrive as values of _tag: "SimpleError" or "BlobError" and do not fail the Effect.

RespPairs is ReadonlyArray<readonly [RespValue, RespValue]>. Doubles stay as text so no precision is lost.

Example (Inspecting a Raw Reply)

import { Effect } from "effect";

import { Redis } from "@effect-kit/redis";
import type { RawContract } from "@effect-kit/redis";

const contract: RawContract = { execution: "ordinary", routing: { _tag: "Keyless" } };

const program = Effect.gen(function* () {
  const redis = yield* Redis;

  const reply = yield* redis.raw(["ECHO", "hello"], contract);
        
const reply: RespValue

  return reply._tag;
});

Low-level codecCopy Anchor Link

encodeCommand(tokens, limits?) returns a Result with the RESP frame or a ProtocolError. makeRespDecoder(limits?) returns a Result with a RespDecoder that you feed bytes, drain with next, and close with end. The decode limits are maxHeaderBytes, maxBlobBytes, maxBufferedBytes, maxAggregateEntries and maxNestingDepth, set through limits. A frame that breaks the grammar or a limit fails with a ProtocolError.

Replication and RDB framing and streamed RESP3 aggregates are outside the ordinary command API.