Add SSL/TLS connection support (#12)

* Add SSL/TLS connection support via SSLMode configuration

Introduces SSLMode (SSLDisabled | SSLRequired) so callers can opt into
TLS by passing an SSLContext through ConnectInfo. Session.create matches
on the mode to choose between lori's plaintext and SSL client
constructors; the state machine is unchanged since lori handles the
TLS handshake before firing on_connected.

Adds dual-container test infrastructure: a TLS-enabled Redis Docker
image (.ci-dockerfiles/redis-ssl) for CI and local Makefile targets
that start both plaintext (port 6379) and TLS (port 6380) containers.
Three new integration tests exercise SSL connection failure, connect-
and-ready, and SET/GET over TLS.

Design: #2

* Add examples/README.md describing each example program

* Install openssl package in redis-ssl Dockerfile

The redis:7 base image doesn't include the openssl CLI tools needed
to generate self-signed certificates at build time.

* Fix redis-ssl key permission for redis user

The redis:7 image runs as the redis user, but the key was owned by
root with 600 permissions. chown to redis:redis before chmod.

Author: SeanTAllen

.ci-dockerfiles/redis-ssl/Dockerfile

@@ -0,0 +1,17 @@
+FROM redis:7
+
+LABEL org.opencontainers.image.source="https://github.com/ponylang/redis"
+
+RUN apt-get update && apt-get install -y --no-install-recommends openssl && \
+    rm -rf /var/lib/apt/lists/* && \
+    mkdir -p /tls && \
+    openssl req -new -x509 -days 3650 -nodes \
+      -out /tls/redis.crt -keyout /tls/redis.key \
+      -subj '/CN=localhost' && \
+    chown redis:redis /tls/redis.key && \
+    chmod 600 /tls/redis.key
+
+CMD ["redis-server", "--tls-port", "6379", "--port", "0", \
+     "--tls-cert-file", "/tls/redis.crt", \
+     "--tls-key-file", "/tls/redis.key", \
+     "--tls-auth-clients", "no"]

.ci-dockerfiles/redis-ssl/build-and-push.bash

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+set -o errexit
+set -o nounset
+
+#
+# *** You should already be logged in to GitHub Container Registry when you run
+#     this ***
+#
+
+DOCKERFILE_DIR="$(dirname "$0")"
+
+docker build --pull \
+  -t ghcr.io/ponylang/redis-ci-redis-ssl:latest "${DOCKERFILE_DIR}"
+docker push ghcr.io/ponylang/redis-ci-redis-ssl:latest

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

@@ -22,6 +22,13 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+      redis-ssl:
+        image: ghcr.io/ponylang/redis-ci-redis-ssl:latest
+        options: >-
+          --health-cmd "redis-cli --tls --insecure ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@v4.1.1
       - name: Unit tests
@@ -31,6 +38,8 @@ jobs:
         env:
           REDIS_HOST: redis
           REDIS_PORT: 6379
+          REDIS_SSL_HOST: redis-ssl
+          REDIS_SSL_PORT: 6379
       - name: Build examples
         run: make build-examples config=debug ssl=libressl
       - name: Send alert on failure

.github/workflows/build-ci-image.yml

@@ -0,0 +1,30 @@
+name: Build CI Image
+
+on:
+  workflow_dispatch:
+
+permissions:
+  packages: write
+
+jobs:
+  redis-ssl:
+    runs-on: ubuntu-latest
+
+    name: redis-ssl
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4.1.1
+      - name: Set up Docker Buildx
+        # v3.10.0
+        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2
+        with:
+          version: v0.23.0
+      - name: Login to GitHub Container Registry
+        # v2.2.0
+        uses: docker/login-action@5139682d94efc37792e6b54386b5b470a68a4737
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push
+        run: bash .ci-dockerfiles/redis-ssl/build-and-push.bash

.github/workflows/pr.yml

@@ -48,6 +48,13 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+      redis-ssl:
+        image: ghcr.io/ponylang/redis-ci-redis-ssl:latest
+        options: >-
+          --health-cmd "redis-cli --tls --insecure ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@v4.1.1
       - name: Unit tests
@@ -57,5 +64,7 @@ jobs:
         env:
           REDIS_HOST: redis
           REDIS_PORT: 6379
+          REDIS_SSL_HOST: redis-ssl
+          REDIS_SSL_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 Redis in Docker for local testing
-make stop-redis         # stop and remove Docker Redis
+make start-redis        # start plaintext + SSL Redis in Docker
+make stop-redis         # stop and remove both Redis containers
 make clean              # clean build artifacts
 ```
 
@@ -40,14 +40,21 @@ Package: `redis`
 ### 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).
+- `ConnectInfo` (in `connect_info.pony`): Connection configuration (host, port, optional password, SSL mode).
 - `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`.
 - `_IllegalState` / `_Unreachable` (in `_mort.pony`): Primitives for detecting impossible states.
 
+### SSL/TLS
+
+- `SSLMode` (type alias in `ssl_mode.pony`): `(SSLDisabled | SSLRequired)`. Controls whether the session uses plaintext TCP or SSL/TLS.
+- `SSLDisabled` (primitive in `ssl_mode.pony`): Plaintext TCP connection (default).
+- `SSLRequired` (class val in `ssl_mode.pony`): Wraps an `SSLContext val` for direct TLS connections. Redis uses direct TLS (typically port 6380) rather than STARTTLS.
+- The `ssl/net` package is a transitive dependency via lori (no `corral.json` change needed). Adding `use "ssl/net"` in source files is sufficient.
+
 ### Trait Composition
 
 - `_ClosedState`: Mixin for the terminal state — rejects or no-ops all operations.
@@ -80,13 +87,23 @@ In `_SessionSubscribed`, any pipelined commands that were in-flight when SUBSCRI
 - 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 `REDIS_HOST` and `REDIS_PORT` from environment (defaults to `127.0.0.2`/`6379` on Linux for WSL2 compatibility)
+- `_RedisTestConfiguration` reads environment variables for both plaintext and SSL 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`)
+
+### 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 a `redis:7` service container with health checks. Integration tests receive `REDIS_HOST=redis` and `REDIS_PORT=6379` as environment variables. 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 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`.
+
+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`.
 
 ## File Layout
 
 - `redis/` — main package source
 - `examples/` — example programs
+- `assets/` — test certificates for SSL Redis container
+- `.ci-dockerfiles/` — Dockerfiles for CI service containers

Makefile

@@ -52,9 +52,15 @@ integration-tests: $(tests_binary)
 
 start-redis:
 	@docker run --name redis -p 6379:6379 -d redis:7
+	@docker run --name redis-ssl \
+		-v $(CURDIR)/assets/test-cert.pem:/tls/redis.crt:ro \
+		-v $(CURDIR)/assets/test-key.pem:/tls/redis.key.orig:ro \
+		-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"
 
 stop-redis:
-	@docker stop redis && docker rm redis
+	@docker stop redis redis-ssl && docker rm redis redis-ssl
 
 $(tests_binary): $(SOURCE_FILES) | $(BUILD_DIR)
 	$(GET_DEPENDENCIES_WITH)

assets/test-cert.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDCTCCAfGgAwIBAgIUW6jIM9PbFPvUnHx5o9KOrxBYXZQwDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI2MDIxNjEzNTY0M1oXDTM2MDIx
+NDEzNTY0M1owFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
+AAOCAQ8AMIIBCgKCAQEA0q/nv9fgUCveG7J90gKimXvp8EE+kIIN6egZoK8eTBz0
+3QPj8NhLJaSodpbSwotkny3UixcxQJ+NQj+6abJmS8BZaw4oTLjAAK3aoh4R8pR6
++t0wDE17RrjnsQZzP2A19n9AANvoVFsWyETvLl38qFhLMVwIPcmjUH66D0ZZVE+q
+MxCSFaSZFetuYq8zKlYvgpnxTFhRliGLi/Q84vZmKT6Vaa1mnv8bVGWF6wUOiuZb
+v6Rc39iG0gCYwdjH2Ig6jsYL4s8xDArSy9SpK4I93E8wLZz4/8NYAuD1aTJMw/+7
+uuar2G++2XGTlvoli9WDrERtJJRIA1HYo1uBZxh9MQIDAQABo1MwUTAdBgNVHQ4E
+FgQUQqGTYKBeXfu2XHd9QddNZzrDijIwHwYDVR0jBBgwFoAUQqGTYKBeXfu2XHd9
+QddNZzrDijIwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAbz16
+Lx2JpHLk+F7/5jA35uQPJamIDCxw7f8Xa/7vjHZp+HhNkzuQ1Vff9dUBLl4tANIC
+GrH3kCAmEpNlVA8sgDzeHR04ubWWMFIrspGBVNTr4ffExFdjlAWtUj2NM6f8O5Kc
+3WxbnkwO/nC2gt5VzpzI0okdHs4EwqhJXCcMy1yomHPryzre0SLRgDKFjH5TtsLL
+i/WL5B4pEYguQ+nPNSklo5vibp76ftrm3bABJF/uNNH13rjJDsEY/TLn0tuMHWHO
+Ym2wtVSrgx6omwnqpRGPdFf1t2KZRFU54BaVpJXJ+ksgvaAfdnqZRxpL9gEdgagE
+CUsb0HtcmNoUq784xQ==
+-----END CERTIFICATE-----

assets/test-key.pem

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDSr+e/1+BQK94b
+sn3SAqKZe+nwQT6Qgg3p6Bmgrx5MHPTdA+Pw2EslpKh2ltLCi2SfLdSLFzFAn41C
+P7ppsmZLwFlrDihMuMAArdqiHhHylHr63TAMTXtGuOexBnM/YDX2f0AA2+hUWxbI
+RO8uXfyoWEsxXAg9yaNQfroPRllUT6ozEJIVpJkV625irzMqVi+CmfFMWFGWIYuL
+9Dzi9mYpPpVprWae/xtUZYXrBQ6K5lu/pFzf2IbSAJjB2MfYiDqOxgvizzEMCtLL
+1Kkrgj3cTzAtnPj/w1gC4PVpMkzD/7u65qvYb77ZcZOW+iWL1YOsRG0klEgDUdij
+W4FnGH0xAgMBAAECggEAAlu6NXKc6JYpHmMVLKE0wTuQGY1IE5WFGC8YfwI0Iwgi
+8d4N3TUKmEwGH7ezTxQA3GrxVAeT2KRAkEiG1WaMEGvW2bosQiRCRUUCQL94liAf
+2p2DC2w1mvZ4ZMn3Rx2+/43v6+KKRfbJY+n+SbpUbkJOFdTGJII/NqgzJyHI37Gf
+C3y5cuUBU6AYlSL48wltM3K/Z924z76ahF9WtaN933H9ZCDI/DOK+1BHp90w0kq4
+YLjPPNSEhb1DpxKTD9bFg7UfHhPmXEuVMSDg6zMXfok7zPdFRVy/QOxAJ+3GnnbL
+QaAGwiavcL8falhAhCvXnAEZP3tFXf66btUYrJh6AQKBgQD5VPIpZL5hHVlMrMaC
+yhIf+SFDY9nNhE+7T9QZ6KV+gHae7KQ54eo/1WjapzghaFhLh1AH+a8hrSHGLr8L
+AvD8XiWQ8mz3AU9sB37GrHEg1aF6H0WoVDVCFNZOYblLdEnMgUYITPAkghVVT7L3
+4ssBVo/GZm+83QokJp294GUBsQKBgQDYUmC8ZxuXoYeAsfa78nDv2nNokYbM14q0
+0eKDtYcFSScOf00ColEx28fICKycWqM7t2CH27+1Qn260HC66odx5zy0zH3gDi7x
+2IWtbOM2zi6RX5j8DmUg1YZdVWAYWNfpUiGf5+//gjuWQoIsjYz8HxO+0qrVj+1Y
+r701fFqTgQKBgQCz0C9U6vLh1uiwA2qmqFSp+mGi2EAbl3BpBglRJhc0RDFILCHE
+HMlzf9U+25n/feEvl0aAefFzuAjDhLMCnfxuBPfSsQMkoC1HG6CyZ2qu42KxUBxM
+aW5/Wce0f4XChPs0IYcANXx619XK0M+hNk5xiJvn2bh73G2T5MWeSlaOAQKBgDX7
+4N5DkPQ3QFySjPN8XkjNKE3pO021YI0db7zUuVxNVCzfAfXtUfvyUBoQaBsg12mY
+qsNcyKvQaxYK3IcY7jIztcec3LDkeTyrfzi3WsCbla17wO7uHLij8MMsAi4xRbiZ
+YYDJXfBSrNIjyN6beJqWmtPdOPrQzzd5q+tEHEqBAoGAK0nQTGNEXWacs+iwpXYr
+LpKxmNavkhy6UVMlbpfmceOljGmrVZK4dgHnEM3oqb9whbGMLK586ZiEgU0hzYGq
+adoJxvPp4OSes9OIjjA5bsmGL5lLdzUq6MUunRTWJ2y8CXT3BDtn1tqurk/6TOqT
+YEoo8GRKRJiXFN5NVkQeKLc=
+-----END PRIVATE KEY-----

examples/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+Each subdirectory is a self-contained Pony program demonstrating a different part of the redis library.
+
+## basic
+
+Minimal example. Connects to Redis, executes `SET hello world`, prints the response, and closes the session. Shows how to create a `ConnectInfo`, implement `SessionStatusNotify` and `ResultReceiver` on a single actor, and match on `RespValue` variants. Start here if you're new to the library.
+
+## pipeline
+
+Command pipelining. Sends 3 SET commands followed by 3 GET commands without waiting for individual responses — all 6 commands are dispatched immediately in `redis_session_ready`. Responses arrive in order and are tracked with a step counter. Shows how pipelining eliminates round-trip latency for independent commands.
+
+## pubsub
+
+Pub/sub messaging using two sessions. One session subscribes to `demo-channel`, the other publishes a message to it. Demonstrates the `SubscriptionNotify` interface (`redis_subscribed`, `redis_message`, `redis_unsubscribed`) and the two-session pattern required because a subscribed session cannot execute regular commands.
+
+## ssl
+
+SSL/TLS-encrypted connection. Same workflow as `basic` (connects and sends PING) but over TLS using `SSLRequired`. Demonstrates how to create an `SSLContext` with a CA certificate, wrap it in `SSLRequired`, and pass it to `ConnectInfo`. Requires a Redis server configured for TLS. Set `REDIS_HOST`, `REDIS_PORT`, and `REDIS_CA_PATH` environment variables to match your server.