Add RESP3 protocol support (#14)

Implement RESP3 (Redis 6.0+) protocol negotiation and all RESP3 value
types, completing Phase 6 of the implementation plan.

Protocol layer: extend the RespValue union with 8 new types (RespBoolean,
RespDouble, RespBigNumber, RespBulkError, RespVerbatimString, RespMap,
RespSet, RespPush). Parser handles all RESP3 type bytes in both the
completeness check and destructive parse. New _map_size method handles
the map wire format (count = number of pairs, elements = count * 2).

Session layer: add _SessionNegotiating state for HELLO 3 handshake with
automatic RESP2 fallback when the server doesn't support RESP3. HELLO
failure with a password configured falls through to standard AUTH.
Add on_push to the state interface for routing RESP3 push messages
separately from regular responses. _SessionSubscribed dispatches both
RespArray (RESP2) and RespPush (RESP3) pub/sub messages through a
shared _dispatch_pubsub_values method. ConnectInfo gains protocol
(ProtocolVersion) and username fields for RESP3 and ACL support.

_ResponseHandler routes RespPush before the general RespValue match arm
so push messages reach on_push rather than on_response.

Test coverage includes a Redis 5 container for HELLO fallback integration
testing and unit tests for the HELLO/AUTH command construction primitives.

Design: #2

Author: SeanTAllen

.github/workflows/breakage-against-ponyc-latest.yml

@@ -29,6 +29,13 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+      redis-resp2:
+        image: redis:5
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@v4.1.1
       - name: Unit tests
@@ -40,6 +47,8 @@ jobs:
           REDIS_PORT: 6379
           REDIS_SSL_HOST: redis-ssl
           REDIS_SSL_PORT: 6379
+          REDIS_RESP2_HOST: redis-resp2
+          REDIS_RESP2_PORT: 6379
       - name: Build examples
         run: make build-examples config=debug ssl=libressl
       - name: Send alert on failure

.github/workflows/pr.yml

@@ -55,6 +55,13 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+      redis-resp2:
+        image: redis:5
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@v4.1.1
       - name: Unit tests
@@ -66,5 +73,7 @@ jobs:
           REDIS_PORT: 6379
           REDIS_SSL_HOST: redis-ssl
           REDIS_SSL_PORT: 6379
+          REDIS_RESP2_HOST: redis-resp2
+          REDIS_RESP2_PORT: 6379
       - name: Build examples
         run: make build-examples config=debug ssl=libressl

CLAUDE.md

@@ -7,8 +7,8 @@ make                    # build and run all tests (requires Redis running)
 make unit-tests         # run unit tests only (no Redis needed)
 make integration-tests  # run integration tests only (requires Redis)
 make build-examples     # build example programs
-make start-redis        # start plaintext + SSL Redis in Docker
-make stop-redis         # stop and remove both Redis containers
+make start-redis        # start plaintext, SSL, and RESP2-only Redis in Docker
+make stop-redis         # stop and remove all Redis containers
 make clean              # clean build artifacts
 ```
 
@@ -30,22 +30,24 @@ make stop-redis
 
 Package: `redis`
 
-### RESP2 Protocol Layer
+### Protocol Layer
 
-- `RespValue` (union type in `resp_value.pony`): Core type for RESP2 wire format values. Union of `RespSimpleString`, `RespBulkString`, `RespInteger`, `RespArray`, `RespError`, `RespNull`.
+- `RespValue` (union type in `resp_value.pony`): Core type for RESP2/RESP3 wire format values. Union of `RespSimpleString`, `RespBulkString`, `RespInteger`, `RespArray`, `RespError`, `RespNull`, `RespBoolean`, `RespDouble`, `RespBigNumber`, `RespBulkError`, `RespVerbatimString`, `RespMap`, `RespSet`, `RespPush`.
 - `RespMalformed` (in `resp_value.pony`): Parser error type indicating invalid RESP data. Not part of `RespValue` — represents a protocol violation, not a valid value.
-- `_RespParser` (in `_resp_parser.pony`): Two-pass parser — peek-based completeness check, then destructive parse. Returns `(RespValue | None | RespMalformed)` from a `buffered.Reader`.
+- `_RespParser` (in `_resp_parser.pony`): Two-pass parser — peek-based completeness check, then destructive parse. Returns `(RespValue | None | RespMalformed)` from a `buffered.Reader`. Supports all RESP2 and RESP3 type bytes.
 - `_RespSerializer` (in `_resp_serializer.pony`): Serializes commands (`Array[ByteSeq] val`) to RESP2 wire format.
+- `ProtocolVersion` (type alias in `protocol_version.pony`): `(Resp2 | Resp3)`. Controls which protocol the session negotiates on connect.
 
 ### Session Layer
 
-- `Session` (actor in `session.pony`): Main entry point. Manages connection lifecycle and pub/sub via a state machine. Implements `lori.TCPConnectionActor & lori.ClientLifecycleEventReceiver`. All state machine classes (`_SessionUnopened`, `_SessionConnected`, `_SessionReady`, `_SessionSubscribed`, `_SessionClosed`) are in `session.pony`, following the postgres pattern.
-- `ConnectInfo` (in `connect_info.pony`): Connection configuration (host, port, optional password, SSL mode).
+- `Session` (actor in `session.pony`): Main entry point. Manages connection lifecycle and pub/sub via a state machine. Implements `lori.TCPConnectionActor & lori.ClientLifecycleEventReceiver`. All state machine classes (`_SessionUnopened`, `_SessionNegotiating`, `_SessionConnected`, `_SessionReady`, `_SessionSubscribed`, `_SessionClosed`) are in `session.pony`, following the postgres pattern.
+- `ConnectInfo` (in `connect_info.pony`): Connection configuration (host, port, optional password, SSL mode, optional username, protocol version).
 - `SessionStatusNotify` (in `session_status_notify.pony`): Lifecycle callback interface. All callbacks have default no-op implementations. Callbacks: `redis_session_connected`, `redis_session_connection_failed`, `redis_session_ready`, `redis_session_authentication_failed`, `redis_session_closed`.
 - `ResultReceiver` (in `result_receiver.pony`): Command response callback interface. Callbacks: `redis_response`, `redis_command_failed`.
 - `SubscriptionNotify` (in `subscription_notify.pony`): Pub/sub callback interface. All callbacks have default no-op implementations. Callbacks: `redis_subscribed`, `redis_unsubscribed`, `redis_message`, `redis_psubscribed`, `redis_punsubscribed`, `redis_pmessage`.
 - `ClientError` (in `client_error.pony`): Client-side error trait with `SessionNotReady`, `SessionClosed`, and `SessionInSubscribedMode` primitives.
-- `_ResponseHandler` (in `_response_handler.pony`): Loops `_RespParser` over a `buffered.Reader`, delivering parsed `RespValue`s to the current state. Shuts down on `RespMalformed`.
+- `_ResponseHandler` (in `_response_handler.pony`): Loops `_RespParser` over a `buffered.Reader`, routing `RespPush` to `on_push` and other `RespValue`s to `on_response`. Shuts down on `RespMalformed`.
+- `_BuildHelloCommand` / `_BuildAuthCommand` (primitives in `session.pony`): Build HELLO 3 and AUTH commands for protocol negotiation and authentication.
 - `_IllegalState` / `_Unreachable` (in `_mort.pony`): Primitives for detecting impossible states.
 
 ### SSL/TLS
@@ -60,13 +62,18 @@ Package: `redis`
 - `_ClosedState`: Mixin for the terminal state — rejects or no-ops all operations.
 - `_ConnectedState`: Mixin for states with a readbuf — handles `on_received` and `_ResponseHandler` dispatch.
 - `_NotReadyForCommands`: Mixin that rejects `execute()` with `SessionNotReady`.
-- `_NotSubscribed`: Mixin that no-ops `subscribe`, `unsubscribe`, `psubscribe`, `punsubscribe` for states where pub/sub is not applicable.
+- `_NotSubscribed`: Mixin that no-ops `subscribe`, `unsubscribe`, `psubscribe`, `punsubscribe` for states where pub/sub is not applicable. Also provides a no-op `on_push` for states that don't handle push messages (only trait that provides `on_push`, to avoid diamond inheritance in `_SessionClosed`).
 
 ### State Machine
 
 ```
-_SessionUnopened ──on_connected──► _SessionConnected (if password)
-                 ──on_connected──► _SessionReady (if no password)
+_SessionUnopened ──on_connected──► _SessionNegotiating (if Resp3)
+                 ──on_connected──► _SessionConnected (if Resp2 + password)
+                 ──on_connected──► _SessionReady (if Resp2, no password)
+
+_SessionNegotiating ──HELLO map──► _SessionReady
+                    ──HELLO error──► _SessionConnected (if password, send AUTH)
+                    ──HELLO error──► _SessionReady (if no password)
 
 _SessionConnected ──AUTH OK──► _SessionReady
                   ──AUTH error──► _SessionClosed
@@ -80,24 +87,25 @@ _SessionSubscribed ──unsub count 0──► _SessionReady
 
 Commands are pipelined in `_SessionReady`: each `execute()` call sends the command immediately over the wire without waiting for prior responses. Responses are matched to receivers in FIFO order.
 
-In `_SessionSubscribed`, any pipelined commands that were in-flight when SUBSCRIBE was sent are drained first (Redis guarantees in-order response delivery), then incoming responses are routed as pub/sub messages.
+In `_SessionSubscribed`, any pipelined commands that were in-flight when SUBSCRIBE was sent are drained first (Redis guarantees in-order response delivery), then incoming responses are routed as pub/sub messages. In RESP3 mode, pub/sub messages arrive as `RespPush` via `on_push`; in RESP2 mode they arrive as `RespArray` via `on_response`.
 
 ## Test Infrastructure
 
 - Unit tests: `--exclude=integration/` — no external dependencies
 - Integration tests: `--only=integration/` — require a running Redis server
 - Test names prefixed with `integration/` for filtering
-- `_RedisTestConfiguration` reads environment variables for both plaintext and SSL Redis:
+- `_RedisTestConfiguration` reads environment variables for plaintext, SSL, and RESP2-only Redis:
   - `REDIS_HOST` / `REDIS_PORT` — plaintext (defaults to `127.0.0.2`/`6379` on Linux)
   - `REDIS_SSL_HOST` / `REDIS_SSL_PORT` — TLS (defaults to same host/`6380`)
+  - `REDIS_RESP2_HOST` / `REDIS_RESP2_PORT` — RESP2-only Redis 5 (defaults to same host/`6381`)
 
 ### SSL-to-Plaintext Deadlock
 
 Do not write tests that connect with SSL to a plaintext Redis server. The TLS ClientHello is binary data with no `\r\n`, so Redis's RESP parser buffers it waiting for a line terminator. Meanwhile the SSL client waits for a ServerHello. Neither side sends more data — both block indefinitely. To test the SSL constructor path, connect to a non-listening port instead (TCP connection refused is fast and deterministic).
 
 ### CI
 
-Both `pr.yml` and `breakage-against-ponyc-latest.yml` use the `shared-docker-ci-standard-builder-with-libressl-4.2.0` image (for ssl support) and two Redis service containers: `redis` (plaintext) and `redis-ssl` (TLS via `ghcr.io/ponylang/redis-ci-redis-ssl:latest`). Integration tests receive `REDIS_HOST=redis`, `REDIS_PORT=6379`, `REDIS_SSL_HOST=redis-ssl`, and `REDIS_SSL_PORT=6379`. All make targets pass `ssl=libressl`.
+Both `pr.yml` and `breakage-against-ponyc-latest.yml` use the `shared-docker-ci-standard-builder-with-libressl-4.2.0` image (for ssl support) and three Redis service containers: `redis` (plaintext, Redis 7), `redis-ssl` (TLS via `ghcr.io/ponylang/redis-ci-redis-ssl:latest`), and `redis-resp2` (Redis 5, RESP2-only for HELLO fallback testing). Integration tests receive `REDIS_HOST=redis`, `REDIS_PORT=6379`, `REDIS_SSL_HOST=redis-ssl`, `REDIS_SSL_PORT=6379`, `REDIS_RESP2_HOST=redis-resp2`, and `REDIS_RESP2_PORT=6379`. All make targets pass `ssl=libressl`.
 
 The `redis-ssl` CI image is built via `build-ci-image.yml` (manually triggered `workflow_dispatch`). Source: `.ci-dockerfiles/redis-ssl/Dockerfile`. Build locally with `.ci-dockerfiles/redis-ssl/build-and-push.bash`.
 

Makefile

@@ -58,9 +58,10 @@ start-redis:
 		-p 6380:6379 \
 		-d --entrypoint sh redis:7 \
 		-c "cp /tls/redis.key.orig /tls/redis.key && chmod 600 /tls/redis.key && exec redis-server --tls-port 6379 --port 0 --tls-cert-file /tls/redis.crt --tls-key-file /tls/redis.key --tls-auth-clients no"
+	@docker run --name redis-resp2 -p 6381:6379 -d redis:5
 
 stop-redis:
-	@docker stop redis redis-ssl && docker rm redis redis-ssl
+	@docker stop redis redis-ssl redis-resp2 && docker rm redis redis-ssl redis-resp2
 
 $(tests_binary): $(SOURCE_FILES) | $(BUILD_DIR)
 	$(GET_DEPENDENCIES_WITH)

examples/resp3/main.pony

@@ -0,0 +1,89 @@
+use "cli"
+use lori = "lori"
+// in your code this `use` statement would be:
+// use "redis"
+use "../../redis"
+
+actor Main
+  new create(env: Env) =>
+    let info = ServerInfo(env.vars)
+    let auth = lori.TCPConnectAuth(env.root)
+    Client(auth, info, env.out)
+
+actor Client is (SessionStatusNotify & ResultReceiver)
+  let _session: Session
+  let _out: OutStream
+  var _step: USize = 0
+
+  new create(auth: lori.TCPConnectAuth, info: ServerInfo, out: OutStream) =>
+    _out = out
+    _session = Session(
+      ConnectInfo(auth, info.host, info.port where protocol' = Resp3),
+      this)
+
+  be redis_session_ready(session: Session) =>
+    _out.print("Connected with RESP3 protocol.")
+    // HSET writes fields on a hash key.
+    let cmd: Array[ByteSeq] val =
+      ["HSET"; "_resp3_example"; "name"; "Pony"; "version"; "0.60"]
+    session.execute(cmd, this)
+
+  be redis_session_connection_failed(session: Session) =>
+    _out.print("Failed to connect.")
+
+  be redis_response(session: Session, response: RespValue) =>
+    _step = _step + 1
+    if _step == 1 then
+      // HSET response — integer count of fields added.
+      _out.print("HSET done.")
+      // HGETALL returns a map in RESP3 mode.
+      let cmd: Array[ByteSeq] val = ["HGETALL"; "_resp3_example"]
+      session.execute(cmd, this)
+    elseif _step == 2 then
+      // HGETALL response — RespMap in RESP3, RespArray in RESP2.
+      match response
+      | let m: RespMap =>
+        _out.print("HGETALL returned a map with "
+          + m.pairs.size().string() + " pairs:")
+        for (k, v) in m.pairs.values() do
+          let ks = match k
+          | let b: RespBulkString => String.from_array(b.value)
+          else "?"
+          end
+          let vs = match v
+          | let b: RespBulkString => String.from_array(b.value)
+          else "?"
+          end
+          _out.print("  " + ks + " = " + vs)
+        end
+      | let a: RespArray =>
+        // Fallback to RESP2 — server didn't support HELLO.
+        _out.print("HGETALL returned an array (RESP2 fallback) with "
+          + a.values.size().string() + " elements.")
+      else
+        _out.print("Unexpected response type from HGETALL.")
+      end
+      // Clean up.
+      let cmd: Array[ByteSeq] val = ["DEL"; "_resp3_example"]
+      session.execute(cmd, this)
+    else
+      _out.print("Cleaned up. Done.")
+      _session.close()
+    end
+
+  be redis_command_failed(session: Session,
+    command: Array[ByteSeq] val, failure: ClientError)
+  =>
+    _out.print("Command failed: " + failure.message())
+    _session.close()
+
+class val ServerInfo
+  let host: String
+  let port: String
+
+  new val create(vars: (Array[String] val | None)) =>
+    let e = EnvVars(vars)
+    host = try e("REDIS_HOST")? else
+      ifdef linux then "127.0.0.2" else "localhost" end
+    end
+    port = try e("REDIS_PORT")? else "6379" end