Redis (RESP) protocol layer — design exploration

[SeanTAllen]

Redis (RESP) Protocol Layer for Lori — Design Exploration

What we're exploring

How should a protocol state machine layer on top of Lori? We use Redis/RESP as the concrete case because it's the simplest of the five target protocols. The goal is to surface design decisions and shape alternatives, not to converge on a single design.

The constraint: Lori's API stays the same. The protocol layer is built on top. However, when a shape would be significantly improved by a Lori API change, we note that — part of the exploration's value is discovering what Lori should eventually provide natively.

RESP protocol overview

RESP (Redis Serialization Protocol) is Redis's wire format. It has five data types:

• Simple strings: +OK\r\n
• Errors: -ERR message\r\n
• Integers: :42\r\n
• Bulk strings: $6\r\nfoobar\r\n (length-prefixed, or $-1\r\n for null)
• Arrays: *3\r\n... (count-prefixed, elements are any RESP type, recursive, or *-1\r\n for null)

Commands are sent as arrays of bulk strings: *2\r\n$3\r\nGET\r\n$3\r\nfoo\r\n

Note: Redis commands are binary-safe — values can contain arbitrary bytes, not just text. The command API should use ByteSeq (or Array[U8] val) for values, not just String. The sketches below use Array[ByteSeq] val for command arguments to reflect this.

State machine

Disconnected ──(TCP connect)──► Connected/Normal
                                  │
                                  ├── send command, receive response (pipelined: N in flight)
                                  │
                                  ├──(SUBSCRIBE)──► Connected/PubSub
                                  │                   │
                                  │                   ├── receive push messages
                                  │                   ├── SUBSCRIBE/UNSUBSCRIBE/PSUBSCRIBE/PUNSUBSCRIBE/PING/QUIT/RESET only
                                  │                   │
                                  │                   ├──(UNSUBSCRIBE all + PUNSUBSCRIBE all)──► Connected/Normal
                                  │                   └──(RESET)──► Connected/Normal
                                  │
                                  └──(close/error)──► Closed

Key behaviors:

• Pipelining: In normal mode, the client can send multiple commands without waiting for responses. Responses arrive in order. The protocol layer needs to match responses to requests.
• Pub/Sub mode switch: SUBSCRIBE changes the connection's behavior. Most commands become invalid. The server pushes messages unprompted.
• Inline commands: Redis also supports a plain-text command format (PING\r\n) but RESP arrays are the standard client format. We'd probably only support RESP.

Design axes

Three independent decisions shape the design:

Axis 1: Who owns the actor?

Option A — Library provides the actor. The Redis library ships a RedisConnection actor. The user never implements TCPConnectionActor or any Lori lifecycle trait. They interact with RedisConnection via behaviors and receive responses through some callback mechanism (see Axis 2).

Option B — User writes the actor. The user's actor implements TCPConnectionActor (Lori's ASIO plumbing trait). The protocol layer is a class or trait that handles RESP parsing and state management within the user's actor. The user doesn't implement Lori's lifecycle receiver traits — the protocol layer intercepts those.

The key difference: In Option A, Redis protocol state and user application state live in different actors. Correlating them requires message passing. In Option B, they share an actor, so the user's protocol callbacks can directly read and mutate application state.

Axis 2: How are protocol events delivered?

Option X — Trait callbacks. The user's actor implements a trait like RedisClientCallbacks with methods like _on_redis_response(value: RedisValue). These run inside the user's actor (or the library actor if combined with Option A, but that defeats the purpose).

Note: In Pony, this could be a trait (nominal subtyping — the user declares is RedisClientCallbacks) or an interface (structural subtyping — the user just needs the right methods). Interfaces are more composable: an actor could satisfy both RedisClientCallbacks and HttpClientCallbacks structurally without diamond inheritance issues. Traits make the relationship explicit and discoverable. This choice matters when multiple protocol layers might coexist on one actor.

Option Y — Notifier object. The user creates a class implementing RedisNotify and passes it (as iso) to the protocol layer. Callbacks run wherever the protocol layer lives. If the protocol layer is a library-owned actor (Option A), the notifier is trapped inside that actor and needs tag references to communicate back.

Option Z — Actor messages. The protocol layer sends behavior calls to a handler actor provided by the user. This only makes sense with Option A (library-owned actor), since if the user owns the actor, they'd just use trait callbacks.

Axis 3: Where does protocol state live?

Protocol state = RESP parse buffer, current parse position, normal-vs-pubsub mode, pending request queue for pipelining.

Option I — Protocol class the user embeds. Like TCPConnection, the user stores a RedisProtocol field and provides access via a method. The class holds all protocol state. Pony's embed keyword (inline allocation, no heap indirection) is an option here if the protocol class can be fully initialized in the constructor — see the discussion of none() necessity below.

Option II — Protocol state in the library actor. If the library owns the actor (Option A), protocol state is just private fields on that actor.

Option III — Split between trait defaults and a state object. A trait provides default implementations for Lori callbacks. Since traits can't have fields in Pony, the actual state lives in a class the user provides access to (like _connection() provides access to TCPConnection).

Concrete shapes

These combine the axes above into complete pictures. Each is internally consistent.

Shape 1: Library-owned actor with handler actors (A + Z + II)

The simplest user experience. The library provides everything. The user sends commands via behaviors and receives responses in a handler actor.

// --- Library provides ---

actor RedisConnection
  // internally: TCPConnectionActor & ClientLifecycleEventReceiver
  // holds TCPConnection, parse buffer, state machine, pending request queue

  new create(auth: TCPConnectAuth, host: String, port: String,
    handler: RedisHandler tag)

  be command(args: Array[ByteSeq] val)
  be subscribe(channel: String)
  be unsubscribe(channel: String)
  be close()

trait tag RedisHandler
  be redis_connected(conn: RedisConnection)
  be redis_response(conn: RedisConnection, value: RedisValue val)
  be redis_push(conn: RedisConnection, channel: String, msg: Array[U8] val)
  be redis_closed(conn: RedisConnection)
  be redis_error(conn: RedisConnection, err: RedisError val)

// --- User writes ---

actor MyApp is RedisHandler
  var _redis: (RedisConnection | None) = None
  var _counter: U64 = 0   // application state

  new create(auth: TCPConnectAuth) =>
    _redis = RedisConnection(auth, "localhost", "6379", this)

  be redis_connected(conn: RedisConnection) =>
    conn.command(["SET"; "key"; "value"])

  be redis_response(conn: RedisConnection, value: RedisValue val) =>
    _counter = _counter + 1
    // can access _counter directly here

Tradeoffs:

• (+) User never sees Lori. No TCPConnectionActor, no _connection(), no _on_received.
• (+) Protocol library has full control of connection lifecycle.
• (-) Every response delivery crosses an actor boundary (RedisConnection → MyApp). This is extra message passing overhead.
• (-) command() is a behavior (async), so it can't return a token or error synchronously. The user can't know at call time whether the command was accepted. Errors arrive later, asynchronously.
• (-) Backpressure is hard to propagate. When the TCP socket is throttled, the RedisConnection's mailbox keeps accepting command() behaviors. The library would need to buffer internally or drop — the user has no signal at send time.
• (-) Hard to extend (reconnect logic, connection pooling, custom AUTH sequences).

Capability constraint on data types: All data crossing the actor boundary (RedisConnection → MyApp) must be sendable: val, tag, or value types. RedisValue must be val. This means response data is immutable once delivered — the user can't receive an iso array and mutate it in place. In Shapes 2–5, protocol data stays within a single actor, so iso and ref are options. This is a concrete tradeoff: Shape 1 pays for immutable copying; other shapes don't.

Full-response buffering for nested types: The val requirement also forces structural consequences. A Redis MGET returning 1000 bulk strings must be fully constructed as an iso tree inside a recover block before being consumed to val for delivery. The parser cannot incrementally deliver array elements — it must buffer the entire response. For large LRANGE/SMEMBERS/MGET results, this creates memory spikes. Shapes 2–5, running in the user's actor, could deliver ref data or iso chunks incrementally. This is a concrete performance difference beyond message passing overhead, and it differentially affects protocols with large structured responses.

Server side: The library would provide RedisServerConnection as an actor. The listener's _on_accept creates one per incoming connection:

fun ref _on_accept(fd: U32): RedisServerConnection =>
  RedisServerConnection(_server_auth, fd, my_server_handler)

The user still writes a custom TCPListenerActor — Shape 1 hides the connection actor but not the listener. A RedisListener actor could also be provided, wrapping TCPListenerActor and TCPListener, so the user only provides a factory for server handlers. But this means the library needs to provide listener actors too, not just connection actors.

Design question: How does the send system work? Lori's send() returns (SendToken | SendError) synchronously. Behind a behavior boundary, this becomes invisible to the user. Options:

1. The library buffers commands internally and deals with SendError itself (retry on unthrottled, fail on disconnect).
2. The library exposes a be command(...) that can fail, but behaviors can't return values, so failure is reported via redis_error() callback asynchronously.
3. Accept that send-side feedback is lost behind the actor boundary.

Shape 2: Protocol class as lifecycle interceptor (B + X + I)

Mirrors Lori's own pattern. The protocol is a class that sits between TCPConnection and the user, intercepting Lori's lifecycle callbacks and delivering protocol-level callbacks instead.

// --- Library provides ---

class RedisClient is ClientLifecycleEventReceiver
  // Holds TCPConnection, parse buffer, state machine.
  // Implements ClientLifecycleEventReceiver — this is what makes it
  // an interceptor. TCPConnection calls _on_received etc. on this class,
  // which parses RESP and calls the user's RedisClientCallbacks.
  var _tcp_connection: TCPConnection = TCPConnection.none()
  var _parse_buffer: Array[U8] iso = recover Array[U8] end
  var _mode: _RedisMode = _NormalMode
  var _pending: Array[RedisRequestToken] = Array[RedisRequestToken]
  let _callbacks: RedisClientCallbacks ref

  new create(auth: TCPConnectAuth, host: String, port: String,
    enclosing: TCPConnectionActor ref,
    callbacks: RedisClientCallbacks ref)
  =>
    _callbacks = callbacks
    _tcp_connection = TCPConnection.client(auth, host, port, "",
      enclosing, // user's actor — handles ASIO event dispatch
      this)      // RedisClient — handles lifecycle callbacks

  new none() =>
    // ...

  // Required by ClientLifecycleEventReceiver
  fun ref _connection(): TCPConnection => _tcp_connection

  fun ref connection(): TCPConnection => _tcp_connection

  fun ref command(args: Array[ByteSeq] val): (RedisRequestToken | RedisSendError)
    // Serializes to RESP, calls _tcp_connection.send(),
    // returns token or error (synchronous!)
    // RedisSendError should preserve the transient/permanent distinction
    // from Lori's SendErrorNotWriteable (transient, retry after unthrottle)
    // vs SendErrorNotConnected (permanent). This lets the user distinguish
    // "retry later" from "connection is dead" without additional state inspection.

  fun ref subscribe(channel: String): (RedisRequestToken | RedisSendError)
  fun ref unsubscribe(channel: String): (RedisRequestToken | RedisSendError)

  // Lifecycle interception — these fire on RedisClient, not the user
  fun ref _on_connected() =>
    _callbacks._on_redis_connected()

  fun ref _on_received(data: Array[U8] iso) =>
    // accumulate in _parse_buffer, parse RESP frames,
    // call _callbacks._on_redis_response() for each complete value

  fun ref _on_closed() =>
    _callbacks._on_redis_closed()

  fun ref _on_throttled() =>
    _callbacks._on_redis_throttled()

  fun ref _on_unthrottled() =>
    _callbacks._on_redis_unthrottled()

  fun ref _on_sent(token: SendToken) =>
    // RedisClient sees SendToken completions — can correlate with
    // RedisRequestToken internally, hiding SendToken from the user

  fun ref _on_send_failed(token: SendToken) =>
    // Same — translate to protocol-level send failure

trait RedisClientCallbacks
  fun ref _on_redis_connected() => None
  fun ref _on_redis_response(token: RedisRequestToken, value: RedisValue) => None
  fun ref _on_redis_push(channel: String, message: Array[U8] iso) => None
  fun ref _on_redis_closed() => None
  fun ref _on_redis_connection_failure() => None
  fun ref _on_redis_throttled() => None
  fun ref _on_redis_unthrottled() => None

// --- User writes ---

actor MyApp is (TCPConnectionActor & RedisClientCallbacks)
  var _redis: RedisClient = RedisClient.none()
  var _counter: U64 = 0

  new create(auth: TCPConnectAuth) =>
    _redis = RedisClient(auth, "localhost", "6379", this, this)

  fun ref _connection(): TCPConnection => _redis.connection()

  fun ref _on_redis_connected() =>
    match _redis.command(["SET"; "key"; "value"])
    | let token: RedisRequestToken => None // command accepted
    | let err: RedisError => None // handle error
    end

  fun ref _on_redis_response(token: RedisRequestToken, value: RedisValue) =>
    _counter = _counter + 1
    // direct access to _counter, no actor boundary

How it works internally: RedisClient implements ClientLifecycleEventReceiver. This is possible because TCPConnection.client() takes enclosing (the TCPConnectionActor for ASIO dispatch) and ler (the lifecycle event receiver) as separate parameters. The user's actor is enclosing; RedisClient is ler.

Note that ClientLifecycleEventReceiver requires fun ref _connection(): TCPConnection — it's not a pure callback trait. Any class implementing it must provide access to the TCPConnection. This means the interceptor class necessarily owns (or has access to) the connection. This coupling is inherent to Lori's current design and applies to every protocol interceptor, not just Redis.

Two _connection() methods in play: Shape 2 has two distinct _connection() methods that must return the same TCPConnection: one on the user's actor (required by TCPConnectionActor, delegates to _redis.connection()) and one on RedisClient (required by ClientLifecycleEventReceiver, returns _tcp_connection directly). Both are called by different parts of Lori's internals — the first by ASIO behaviors, the second by TCPConnection internally. If they return different objects, behavior is undefined. In the standard Lori pattern (single actor is both TCPConnectionActor and lifecycle receiver), there's only one _connection(). The interceptor pattern introduces this novel two-method constraint.

_on_sent/_on_send_failed routing: Because RedisClient is the lifecycle receiver, Lori delivers _on_sent(token: SendToken) and _on_send_failed(token: SendToken) to RedisClient, not to the user's actor. This is actually a design opportunity: RedisClient sees both the SendToken (from _tcp_connection.send()) and the RedisRequestToken (from command()). It can correlate them internally and either:

• Hide SendToken entirely, translating TCP send events into protocol-level events.
• Expose a _on_redis_sent(token: RedisRequestToken) callback meaning "your command bytes reached the OS."

This is distinct from _on_redis_response, which means "Redis processed the command and sent a reply." The user might care about both (e.g., for latency measurement) or only the response.

Server side: Works naturally. A RedisServer class implements ServerLifecycleEventReceiver and intercepts server-side callbacks. The user's server actor implements TCPConnectionActor and a RedisServerCallbacks trait:

actor MyRedisHandler is (TCPConnectionActor & RedisServerCallbacks)
  var _redis: RedisServer = RedisServer.none()

  new create(auth: TCPServerAuth, fd: U32) =>
    _redis = RedisServer(auth, fd, this, this)

  fun ref _connection(): TCPConnection => _redis.connection()

  fun ref _on_redis_command(cmd: RedisCommand) =>
    // handle incoming Redis command from client

The listener creates these in _on_accept:

fun ref _on_accept(fd: U32): MyRedisHandler =>
  MyRedisHandler(_server_auth, fd)

Tradeoffs:

• (+) command() is synchronous — returns token or error immediately, just like Lori's send().
• (+) Backpressure propagates naturally: command() returns RedisError when throttled.
• (+) User's callbacks run in their own actor — direct access to application state.
• (+) Follows Lori's established pattern (class-in-actor + trait callbacks).
• (+) SendToken is encapsulated — the user never sees Lori's send tracking.
• (+) No override hazard — the interceptor class owns the lifecycle callbacks, the user can't accidentally replace them.
• (-) User still implements TCPConnectionActor and provides _connection(). They know Lori exists.
• (-) Boilerplate: var _redis: RedisClient = RedisClient.none() and fun ref _connection(): TCPConnection => _redis.connection().
• (-) Exposes raw TCPConnection via _connection() — the user could bypass the protocol layer and corrupt state.

Variant: trait defaults for ASIO plumbing. Shape 2's main boilerplate is fun ref _connection(): TCPConnection => _redis.connection(). This exists because TCPConnectionActor requires _connection(). A protocol library could provide a trait that extends TCPConnectionActor and provides this default:

trait RedisClientActor is TCPConnectionActor
  fun ref _redis_client(): RedisClient
  fun ref _connection(): TCPConnection => _redis_client().connection()

// User writes:
actor MyApp is (RedisClientActor & RedisClientCallbacks)
  var _redis: RedisClient = RedisClient.none()

  new create(auth: TCPConnectAuth) =>
    _redis = RedisClient(auth, "localhost", "6379", this, this)

  fun ref _redis_client(): RedisClient => _redis

  fun ref _on_redis_connected() => ...
  fun ref _on_redis_response(token: RedisRequestToken, value: RedisValue) => ...

The user writes one accessor (_redis_client()) instead of two (_connection() + _redis_client()). The override hazard shifts to _connection() and the ASIO behaviors (_event_notify, _read_again, etc.) — but these are Lori internals that no user would think to override, unlike _on_received which has protocol-level meaning. This combines Shape 2's safety (interceptor class owns lifecycle callbacks) with Shape 3's convenience (trait defaults handle boilerplate). The lifecycle override hazard that makes Shape 3 fragile doesn't apply because the lifecycle callbacks live on the interceptor class, not the trait.

none() necessity: TCPConnection.none() is needed because _finish_initialization (a behavior) calls _connection() on the user's actor, and Pony requires all fields to be definitely assigned. But RedisClient.none() may not actually be needed. _finish_initialization calls _connection()._finish_initialization(), i.e. it goes through the user's _connection() accessor to the TCPConnection. It doesn't touch _redis directly. If the user writes:

var _redis: RedisClient
new create(auth: TCPConnectAuth) =>
  _redis = RedisClient(auth, "localhost", "6379", this, this)

..._redis is assigned before the constructor completes, and _finish_initialization runs asynchronously (as a behavior) after the constructor. So _redis is initialized by the time anything accesses it. If this holds, RedisClient.none() is unnecessary — one less invalid state to reason about. But TCPConnection.none() inside RedisClient is still needed (for the same reason it's needed today).

embed vs var: If RedisClient.none() is unnecessary, embed becomes viable: embed _redis: RedisClient places the object inline in the actor, eliminating heap indirection. This requires that RedisClient is always fully initialized in the constructor (no reassignment). Worth investigating for performance-sensitive protocol layers.

Design question: Which Lori callbacks to expose vs absorb? The protocol interceptor receives all lifecycle callbacks. It must decide which to translate into protocol-level callbacks and which to handle silently. _on_connected → _on_redis_connected is obvious. But what about:

• _on_connecting(inflight_connections) — expose as _on_redis_connecting? Or absorb silently?
• _on_throttled/_on_unthrottled — the user needs these for backpressure awareness, but should they be renamed to _on_redis_throttled or left out (since command() already returns errors when throttled)?
• _on_sent/_on_send_failed — absorb and correlate internally, or expose?

This "which callbacks to forward" question applies to every protocol layer, not just Redis. It's a design decision that shapes how much Lori leaks through.

Design question: Who manages expect()? The RESP parser could use expect() to request exact byte counts (e.g., after parsing $6\r\n, request exactly 8 bytes for foobar\r\n). But expect() can only express "give me exactly N bytes" — it can't express "read until \r\n." RESP's line-based type prefixes (+OK\r\n, :42\r\n, $6\r\n) are variable-length, so expect() can't help with parsing them — only with the bulk string body after the length is known.

This means the protocol layer needs its own buffering regardless. expect() provides marginal benefit for RESP — it helps with bulk string bodies but not with the variable-length framing headers. This finding generalizes: any protocol with variable-length framing (HTTP headers, SMTP commands, WebSocket after the initial frame header) can't fully leverage expect(). The protocol layer always needs its own buffer.

Design question: Token correlation. RedisRequestToken tracks which command a response belongs to. Lori's SendToken tracks "bytes reached the OS." These are independent — a single command might fragment across multiple TCP sends, or multiple pipelined commands might share one send. Since the interceptor sees both (it calls send() and receives _on_sent), it can correlate them or keep them separate. The user probably doesn't need SendToken at all — RedisRequestToken plus _on_redis_response is sufficient.

Shape 3: Trait with defaults (B + X + III)

The protocol is a trait that extends Lori's traits and provides default implementations for the lifecycle callbacks. The user implements the protocol trait, which gives them protocol-level callbacks "for free."

// --- Library provides ---

trait RedisClientActor is (TCPConnectionActor & ClientLifecycleEventReceiver)
  fun ref _redis_state(): RedisState

  // Default implementations intercept Lori callbacks:
  fun ref _on_connected() =>
    _on_redis_connected()

  fun ref _on_received(data: Array[U8] iso) =>
    _redis_state().feed(consume data)
    while _redis_state().has_value() do
      match _redis_state().next_value()
      | let v: RedisResponse => _on_redis_response(v.token, v.value)
      | let p: RedisPush => _on_redis_push(p.channel, p.message)
      end
    end

  fun ref _on_closed() =>
    _on_redis_closed()

  fun ref _on_throttled() =>
    _on_redis_throttled()

  fun ref _on_unthrottled() =>
    _on_redis_unthrottled()

  // Protocol-level callbacks for user to implement:
  fun ref _on_redis_connected() => None
  fun ref _on_redis_response(token: RedisRequestToken, value: RedisValue) => None
  fun ref _on_redis_push(channel: String, message: Array[U8] iso) => None
  fun ref _on_redis_closed() => None
  fun ref _on_redis_throttled() => None
  fun ref _on_redis_unthrottled() => None

  // Protocol operations:
  fun ref redis_command(args: Array[ByteSeq] val): (RedisRequestToken | RedisError) =>
    // serialize, call _connection().send(), track in _redis_state()

class RedisState
  // Parse buffer, mode, pending request queue
  // No reference to TCPConnection or the actor — pure protocol state

// --- User writes ---

actor MyApp is RedisClientActor
  var _tcp_connection: TCPConnection = TCPConnection.none()
  var _redis: RedisState = RedisState.create()
  var _counter: U64 = 0

  new create(auth: TCPConnectAuth) =>
    _tcp_connection = TCPConnection.client(auth, "localhost", "6379", "", this, this)

  fun ref _connection(): TCPConnection => _tcp_connection
  fun ref _redis_state(): RedisState => _redis

  fun ref _on_redis_connected() =>
    redis_command(["SET"; "key"; "value"])

  fun ref _on_redis_response(token: RedisRequestToken, value: RedisValue) =>
    _counter = _counter + 1

Tradeoffs:

• (+) Minimal user boilerplate — is RedisClientActor gives you everything.
• (+) Single actor, direct state access, synchronous operations.
• (+) The user "doesn't write a Lori actor" — they write a Redis actor that happens to use Lori under the hood.
• (-) Override hazard: If the user overrides _on_received() (which is a valid method on the trait), the protocol breaks silently. Pony has no final keyword to prevent this. There is no mechanism in the language to make a trait method non-overridable. This is a fundamental weakness, not a fixable one. It makes Shape 3 strictly more fragile than Shape 2, where the interceptor class owns the lifecycle callbacks and the user can't replace them.
• (-) Two accessor methods required: _connection() (Lori's requirement) and _redis_state() (protocol state).
• (-) TCPConnection is created with this as both enclosing and ler. The user's actor IS the lifecycle receiver. The trait provides defaults, but the user can silently override them.
• (-) _on_sent/_on_send_failed handling is awkward. The trait could provide defaults that correlate tokens, but the state needed for correlation lives in RedisState (accessible only via _redis_state()). The indirection through accessors makes the logic less direct than Shape 2 where the interceptor class holds everything.

Server side: A RedisServerActor trait extends TCPConnectionActor & ServerLifecycleEventReceiver with the same pattern. The listener creates the user's actor in _on_accept as usual. Works, but has the same override hazard.

Design question: Can the override hazard be mitigated? Not really. Documentation ("don't override _on_received") is the only option. Making the trait's _on_received call _redis_state().feed() which then calls back via a second trait doesn't help — it just re-introduces the interceptor pattern (Shape 2) with extra steps. The override hazard is an inherent cost of the trait-with-defaults approach.

Shape 4: Delegation without interception (B + X + I)

A hybrid between Shape 2 (interceptor) and the parser-only approach. The user remains the lifecycle receiver but delegates _on_received to a protocol class. The protocol class doesn't implement any Lori trait — it's a pure state machine that accepts bytes, produces protocol events, and receives a TCPConnection ref when it needs to send.

// --- Library provides ---

class RedisProtocol
  // Pure protocol state machine. Does NOT implement ClientLifecycleEventReceiver.
  // No _connection(), no none(), no Lori dependency beyond knowing how to
  // call TCPConnection.send().
  var _parse_buffer: Array[U8] iso = recover Array[U8] end
  var _mode: _RedisMode = _NormalMode
  var _pending: Array[RedisRequestToken] = Array[RedisRequestToken]

  fun ref received(data: Array[U8] iso,
    callbacks: RedisClientCallbacks ref)
  =>
    // accumulate, parse RESP, call callbacks._on_redis_response() etc.

  fun ref connected(callbacks: RedisClientCallbacks ref) =>
    callbacks._on_redis_connected()

  fun ref command(args: Array[ByteSeq] val,
    conn: TCPConnection ref): (RedisRequestToken | RedisError)
  =>
    // serialize to RESP, call conn.send(), track pending

trait RedisClientCallbacks
  fun ref _on_redis_connected() => None
  fun ref _on_redis_response(token: RedisRequestToken, value: RedisValue) => None
  fun ref _on_redis_push(channel: String, message: Array[U8] iso) => None
  fun ref _on_redis_closed() => None

// --- User writes ---

actor MyApp is (TCPConnectionActor & ClientLifecycleEventReceiver
    & RedisClientCallbacks)
  var _tcp_connection: TCPConnection = TCPConnection.none()
  let _redis: RedisProtocol = RedisProtocol.create()
  var _counter: U64 = 0

  new create(auth: TCPConnectAuth) =>
    _tcp_connection = TCPConnection.client(auth, "localhost", "6379", "",
      this, this)

  fun ref _connection(): TCPConnection => _tcp_connection

  // One-line delegation — user writes this boilerplate
  fun ref _on_received(data: Array[U8] iso) =>
    _redis.received(consume data, this)

  fun ref _on_connected() =>
    _redis.connected(this)

  fun ref _on_closed() =>
    _on_redis_closed()

  // Protocol callbacks
  fun ref _on_redis_connected() =>
    match _redis.command(["SET"; "key"; "value"], _tcp_connection)
    | let token: RedisRequestToken => None
    | let err: RedisError => None
    end

  fun ref _on_redis_response(token: RedisRequestToken, value: RedisValue) =>
    _counter = _counter + 1

How it differs from Shape 2: The protocol class doesn't implement ClientLifecycleEventReceiver. It doesn't own the TCPConnection. It doesn't need _connection() or none(). The user is the lifecycle receiver and writes a few lines of delegation boilerplate.

How it differs from the parser-only approach (Shape 5): The protocol class manages state machine logic — pub/sub mode tracking, pipelining request queue, command validation — not just byte parsing.

Tradeoffs:

• (+) Protocol class has no Lori dependency — it just parses bytes and calls conn.send(). More reusable, easier to test.
• (+) No none() needed — the protocol class is fully initialized immediately.
• (+) No _connection() exposure problem — the user passes TCPConnection ref explicitly when calling command(), so there's no accessor for the protocol class to expose.
• (+) embed is viable since there's no none() pattern.
• (+) The user controls which lifecycle callbacks are delegated and which are handled directly.
• (-) More boilerplate than Shape 2: the user writes _on_received, _on_connected, _on_closed delegation manually (3-4 one-line methods).
• (-) User still implements TCPConnectionActor and ClientLifecycleEventReceiver. They know Lori exists.
• (-) SendToken gap: _on_sent/_on_send_failed land on the user's actor, not the protocol class. The protocol class has no way to correlate SendToken with RedisRequestToken because it never sees the callback. The user would need to implement _on_sent, look up the SendToken in a mapping exposed by the protocol class, and feed it back. This isn't just "harder" — the protocol class structurally cannot provide "your command bytes reached the OS" without the user doing extra wiring. Shape 2's interceptor handles this naturally because it receives both the SendToken (from send()) and the _on_sent callback.
• (-) User can forget delegation or do it wrong (call the wrong method, forget to delegate _on_closed). Shape 2's interceptor guarantees correct delegation by owning the callbacks.

Server side: Same pattern — a RedisServerProtocol class with received()/command_received() methods. The user's server actor delegates _on_received and _on_started.

Design question: Is the delegation boilerplate a real cost? Shape 4 requires ~4 extra one-line methods compared to Shape 2. But those lines make the lifecycle flow explicit — the user can see that _on_received goes to the Redis protocol while _on_throttled is handled differently. Whether this explicitness is a feature or noise depends on taste.

Shape 5: Parser library only — no state machine driving (B + manual + I)

The protocol library provides RESP parsing and serialization as standalone classes. No lifecycle interception, no callback traits. The user writes a normal Lori actor and calls the parser manually.

// --- Library provides ---

class RespParser
  fun ref feed(data: Array[U8] iso): None
  fun ref has_value(): Bool
  fun ref next_value(): RedisValue ?

primitive RespSerializer
  fun command(args: Array[ByteSeq] val): Array[U8] val

// --- User writes ---

actor MyApp is (TCPConnectionActor & ClientLifecycleEventReceiver)
  var _tcp_connection: TCPConnection = TCPConnection.none()
  let _parser: RespParser = RespParser.create()
  var _counter: U64 = 0

  new create(auth: TCPConnectAuth) =>
    _tcp_connection = TCPConnection.client(auth, "localhost", "6379", "", this, this)

  fun ref _connection(): TCPConnection => _tcp_connection

  fun ref _on_connected() =>
    _tcp_connection.send(RespSerializer.command(["SET"; "key"; "value"]))

  fun ref _on_received(data: Array[U8] iso) =>
    _parser.feed(consume data)
    while _parser.has_value() do
      try
        let value = _parser.next_value()?
        _handle_response(value)
      end
    end

  fun ref _handle_response(value: RedisValue) =>
    _counter = _counter + 1

Tradeoffs:

• (+) No magic. The user sees exactly what's happening.
• (+) Parser and serializer are independently testable, reusable across shapes.
• (+) No override hazards, no interception, no coupling beyond RESP format.
• (-) Doesn't achieve the goal: "I don't write an actor that implements Lori." The user writes the full Lori actor.
• (-) Protocol state machine (pub/sub mode, pipelining tracking) lives in the user's code, not the library. Each user reimplements it.
• (-) Not a "protocol driver" — it's a codec.

But it's a useful building block. Shapes 1–4 all need a RESP parser internally. Shape 5's parser could be the foundation that the other shapes build on. The question is whether Lori should provide the driving layer on top.

Cross-cutting design questions

How does the pub/sub mode switch surface in the API?

In Redis, SUBSCRIBE changes what the connection can do. Options:

1. Single type, runtime checks: RedisClient (or equivalent) has both command() and subscribe(). Calling command() in pub/sub mode returns an error. Simple, but the type system doesn't prevent misuse.

2. Mode-typed connections: subscribe() returns a RedisPubSubConnection with a different API. The original connection becomes unusable. Type-safe, but awkward — the connection object changes out from under you. In the class-in-actor shapes (2, 3), this means swapping the embedded field.

3. Separate connection types: The user creates a RedisClient for command mode or a RedisSubscriber for pub/sub mode. No mode switching — different tools for different jobs. Clean, but doesn't support the actual Redis pattern of switching mid-connection.

How does pipelining surface in the API?

In normal mode, the user might send 10 commands before any responses arrive. The protocol layer needs to match responses to commands (they arrive in order). Options:

1. Token-based: command() returns a token. _on_redis_response(token, value) delivers the response with the matching token. The user correlates. This mirrors Lori's SendToken pattern.

2. Callback-per-command: command(args, callback) takes a closure or handler. The protocol layer calls the right callback when the response arrives. In Pony, this works within a single actor: a lambda {ref(value: RedisValue) => _counter = _counter + 1} captures the actor's ref and can mutate state. The protocol class stores these closures in an Array[{ref(RedisValue)}] — standard Pony. So the capability concern is tractable within Shapes 2–4 (single-actor). In Shape 1 (cross-actor), closures can't capture ref state from another actor, so this option doesn't work there.

3. Sequential assumption: No explicit correlation. Responses are delivered in order, and the user is expected to know what they sent. Simplest, matches the raw Redis behavior, but fragile.

Where does AUTH fit?

Redis AUTH is just a command, but it typically runs before any other commands. Options:

• Credentials in the constructor, AUTH sent automatically before _on_redis_connected() fires.
• User sends AUTH manually like any other command.
• Both — the constructor optionally takes credentials, and if provided, the library handles AUTH. If not, the user can AUTH manually.

This is relevant because it shows how "protocol setup" sequences interact with the state machine. SMTP has a similar pattern (EHLO → AUTH before MAIL FROM).

Command-to-send mapping

Lori's send(data: ByteSeq) accepts a single ByteSeq and returns a single SendToken. A Redis command serialized as one buffer is one send() call. But the protocol layer must decide:

1. One send() per command: Each command() call serializes and sends immediately. N pipelined commands = N send() calls = N SendTokens. Simple correlation, but more syscalls.
2. Batched send(): Multiple pipelined commands are serialized into one buffer and sent as one send() call. 1 SendToken for N commands. Fewer syscalls, but _on_sent/_on_send_failed can't distinguish which commands in the batch were affected.
3. Hybrid: Buffer commands until a flush point (explicit flush, or when the event loop yields), then send the batch.

Option 2 means _on_send_failed for a batch can't be mapped to individual RedisRequestTokens — all commands in the batch failed. Option 1 gives clean correlation but may hurt throughput. This decision affects the SendToken-to-RedisRequestToken correlation logic in Shape 2 (where the interceptor handles it) and Shape 4 (where the user would need to feed tokens back to the protocol class).

Receive-side flow control (mute/unmute)

TCPConnection has mute() and unmute() to pause/resume reading. The document discusses send-side backpressure (_on_throttled/_on_unthrottled) but receive-side flow control interacts with protocol buffering differently.

When mute() stops new data delivery, the protocol layer's parse buffer may contain partially or fully parsed frames. Options:

1. Drain before muting: Deliver all complete frames from the parse buffer before honoring mute. Simple, but the user can't truly pause mid-stream.
2. Immediate mute: Stop delivering frames, even if complete ones are buffered. Buffered data waits for unmute. The user gets precise control, but frames can sit in the buffer arbitrarily long.
3. Protocol-level mute distinct from TCP mute: The protocol layer exposes its own pause/resume that operates on the parse buffer, independent of TCP-level mute. More flexibility, more API surface.

For Redis pipelining, a user might want to mute after receiving N responses to process them before accepting more. Whether "mute" means "stop reading from TCP" or "stop delivering parsed responses" is a design choice that applies to all shapes and all five target protocols.

TLS interaction with the protocol layer

Redis supports TLS natively (since Redis 6), and Lori has ssl_client/ssl_server constructors plus start_tls(). How does TLS interact with each shape?

In Shape 2, the lifecycle receiver (RedisClient) receives _on_tls_ready/_on_tls_failure callbacks. The protocol layer would need to:

• Offer SSL-aware constructors (mirroring TCPConnection.ssl_client()/ssl_server()).
• Translate _on_tls_ready to _on_redis_connected (or a Redis-specific TLS callback).
• Enforce ordering: TLS handshake must complete before AUTH.

In Shape 4 (delegation), the user receives TLS callbacks directly and must coordinate with the protocol class manually.

This matters more for SMTP than Redis: SMTP's STARTTLS is a protocol command — the protocol state machine itself decides when to upgrade. The protocol layer must call start_tls() on the TCPConnection at the right moment in the state machine, then handle the callbacks. This interaction between protocol state machines and TLS should influence which shapes are viable for STARTTLS-heavy protocols.

Protocol-level error handling

When the RESP parser encounters malformed data (incomplete frame, invalid type byte, protocol violation), what happens?

1. Hard close: The protocol layer calls hard_close() on the TCPConnection. The user gets _on_redis_closed() but may not understand why.
2. Error callback then close: The protocol layer delivers _on_redis_error(MalformedData) (or similar) before closing, giving the user a chance to log or react.
3. Error callback, connection stays open: The protocol layer reports the error and tries to recover. Risky — a parse error likely means the byte stream is desynchronized, making recovery unreliable.
4. Mode-dependent: In normal mode, close on parse error (the stream is likely corrupted). In pub/sub mode, maybe skip the malformed message and continue.

This is analogous to Lori's own error strategy: SSL errors trigger hard_close() with specific failure callbacks. The protocol layer should probably follow the same pattern — error callback followed by close — rather than trying to recover from a corrupted byte stream.

Multiple connections per actor

Lori's design assumes one connection per actor: _connection() returns a single TCPConnection. But Redis applications commonly use multiple connections — one for commands, one for pub/sub (since pub/sub blocks the connection from normal commands).

In Shape 1, multiple connections are natural — just create multiple RedisConnection actors. In Shapes 2–4, each connection requires its own actor because of the one-_connection() constraint. This means a Redis application using both command mode and pub/sub needs at least two actors in Shapes 2–4, even though the application might prefer to handle both in one place.

This is a Lori-level constraint, not a protocol-level one. If Lori's design eventually evolves (e.g., Discussion #174's state object refactoring), multiple connections per actor might become possible, which would change the protocol layer design space significantly.

Should the protocol layer own reconnection?

The current shapes all represent a single connection. Reconnection (detect disconnect, reconnect, re-subscribe to pub/sub channels, replay failed commands) is a common Redis client feature. Options:

• Out of scope — the protocol layer is one connection, the user builds reconnection on top.
• Built into the library actor (Shape 1 only — the library controls the actor lifecycle).
• A separate wrapper layer on top of the protocol layer.

This question applies to all five target protocols, not just Redis.

The _connection() accessor problem

In Shapes 2 and 3, the user's actor implements TCPConnectionActor, which requires fun ref _connection(): TCPConnection. But the TCPConnection lives inside the protocol class. So the user writes fun ref _connection(): TCPConnection => _redis.connection() — delegating through the protocol layer.

This has two distinct problems:

Bypass risk: The user could call _connection().send(raw_bytes) directly, bypassing the protocol layer and corrupting the state machine.

Load-bearing dispatch chain: In Shape 2, _notify_sent and _notify_send_failed (behaviors on TCPConnectionActor) call _connection()._fire_on_sent(token), which dispatches to the lifecycle event receiver (i.e., RedisClient). This means the user's _connection() delegation (_redis.connection()) is not just an accessor — it's the active dispatch path for send token callbacks. If the user writes _connection() incorrectly (returns TCPConnection.none(), or some other connection), send token callbacks silently vanish. The protocol layer's correctness depends on the user implementing this one-line delegation correctly. Shape 4 (delegation without interception) avoids this because the user is the lifecycle receiver directly, and _connection() returns the TCPConnection they own.

Is this:

• Fine (the user's footgun, they chose to reach past the protocol layer)?
• A problem that should be prevented (but how, given that TCPConnectionActor requires _connection())?
• An argument for Shape 1, where the user never touches TCPConnection?
• An argument for Shape 4, where the delegation chain is simpler (user owns TCPConnection directly)?

A Lori API change could help here: if TCPConnectionActor didn't require _connection() as a public accessor but instead took the TCPConnection reference internally (e.g., at construction time), the protocol class could hold the connection without the user having a path to it. This is one of those cases where the exploration suggests Lori's own API might want to evolve.

Interception at the ASIO layer vs the lifecycle layer

All shapes that intercept callbacks do so at the lifecycle receiver level (_on_received, _on_connected, etc.). There's another interception point: the TCPConnectionActor behaviors (_event_notify, _read_again, _notify_sent, _notify_send_failed). A protocol layer could theoretically wrap these instead.

This is almost certainly wrong — these behaviors are ASIO plumbing, not application logic. Intercepting them would mean reimplementing Lori's event loop. The lifecycle receiver layer is the correct interception point because it's the boundary between "TCP connection management" (Lori's job) and "what to do with the bytes" (the protocol's job). Mentioned here to close off the alternative explicitly.

Does this generalize?

The whole point of building Redis first is to discover what Lori should eventually provide as generic protocol infrastructure. Looking at the shapes:

• Shape 1 (library actor) — Each protocol builds its own actor. Not much to generalize in Lori beyond maybe a common pattern.
• Shape 2 (protocol class as interceptor) — The pattern of "class implements lifecycle receiver, intercepts _on_received, parses bytes, calls protocol callbacks" could be a generic framework. Lori could provide a ProtocolClient[State, Callbacks] base class.
• Shape 3 (trait with defaults) — The pattern of "trait extends TCPConnectionActor, provides default lifecycle implementations" could be generic. But the override hazard makes this risky as a general pattern.
• Shape 4 (delegation without interception) — The protocol class is a pure state machine with no Lori dependency. Most portable and testable, but the user writes a few lines of delegation boilerplate. Lori could provide a very thin ProtocolDriver class that the protocol state machine plugs into, reducing the boilerplate.
• Shape 5 (parser only) — Doesn't inform Lori's design at all; it's just a library.

Shape 2 (interceptor) and Shape 4 (delegation) are the most promising for generalization. Shape 2 is more seamless for the user but couples the protocol class to Lori's lifecycle traits. Shape 4 keeps the protocol class Lori-independent, which makes it easier to test and reuse, at the cost of a few lines of boilerplate per actor. The choice between them might vary by protocol: simple protocols (Redis) might prefer Shape 4's simplicity, while complex protocols with TLS interaction (SMTP) might benefit from Shape 2's interceptor having direct access to the lifecycle.

Protocol-aware listeners

All shapes treat the listener as unchanged — the user always writes a TCPListenerActor. But for server-side protocols, the listener often needs protocol-level configuration: SMTP server banners, HTTP server-level middleware, WebSocket upgrade negotiation, connection limits per protocol state.

_on_accept(fd: U32): TCPConnectionActor constrains what the listener can do — it returns a TCPConnectionActor, so the per-connection actor must be created there. The protocol layer needs to flow configuration from the listener to each connection. Options:

1. User's listener, protocol class per connection: The user writes a TCPListenerActor that creates protocol-aware connection actors in _on_accept. Configuration lives on the listener and is passed to each connection actor's constructor. This is the pattern all shapes assume today.

2. Library-provided listener: The protocol library provides a listener actor (e.g., RedisListener) that wraps TCPListenerActor and TCPListener. The user provides a connection factory. But this requires the library to provide listener actors for every protocol, and the user loses listener-level customization.

3. Listener trait: A protocol-specific trait extends TCPListenerActor and provides defaults for _on_accept (creating the right connection actor type). The user implements the trait and provides protocol configuration via accessor methods. Similar to Shape 3's approach at the connection level, with the same override hazard.

For the five target protocols, listener integration varies in complexity: Redis and SMTP servers need minimal listener customization, HTTP servers need routing and middleware configuration at the listener level, and WebSocket servers need to coordinate the HTTP upgrade handshake at the listener/connection boundary. The listener integration pattern deserves attention as protocols are built, even though it may not need to be solved generically upfront.

Communication pattern diversity

Redis in normal mode is request-response, but the five target protocols span very different communication patterns:

Pattern	Protocols
Request-response	Redis (normal), HTTP/1.1
Server-initiated first message	SMTP (server greeting)
Mode switch to push	Redis (pub/sub)
Bidirectional	WebSocket
Half-duplex command/response	SMTP
Protocol upgrade	WebSocket (HTTP → framed)

Any generic "protocol state machine driver" framework would need to handle all of these, not just request-response. The interceptor pattern (Shape 2) is agnostic to communication direction — it just parses incoming bytes and provides methods for sending — so it naturally accommodates all patterns. The trait-with-defaults pattern (Shape 3) is similarly agnostic. The library-actor pattern (Shape 1) would need different actor shapes for different communication patterns (a request-response actor vs a bidirectional actor vs a push-only actor), which is more fragmented.

What Lori API changes would help

While the constraint is "Lori stays the same," the exploration reveals several places where Lori changes would improve protocol layering:

1. Split _connection() off the lifecycle receiver traits: ClientLifecycleEventReceiver and ServerLifecycleEventReceiver both require _connection(). This means any class implementing them must own or access the TCPConnection. If the lifecycle receiver were a pure callback trait (no _connection() requirement), interceptor classes would be simpler.
2. Pluggable buffering strategies: expect(N) handles length-prefixed (framed) protocols but not delimiter-based (line-oriented) protocols like RESP's \r\n-terminated headers. Rather than adding a parallel expect_until(delimiter) API — which creates two competing interfaces that could be mixed in confusing ways — the underlying concept is that both are buffering strategies: ways of telling Lori "don't deliver data to _on_received until a complete unit is ready." The design question is what a pluggable buffering strategy interface looks like, so Lori can support both framed and line-oriented protocols through one clean abstraction rather than accumulating ad-hoc methods.

[SeanTAllen]

Item 1 analysis: Split _connection() off the lifecycle receiver traits

_connection() is declared on both ClientLifecycleEventReceiver and ServerLifecycleEventReceiver, but none of their default method implementations call it. TCPConnection also never calls _connection() on the lifecycle receiver — it only calls the _on_* callbacks. So removing it is technically possible.

The tradeoff: _connection() is there to support the mixin pattern. Today the defaults are all => None, so the accessor is unused. But if a lifecycle receiver trait (or a protocol-level trait extending it) ever wants a default implementation that interacts with the connection — e.g., a default _on_received that feeds data to a parser then calls expect() — it needs access to the TCPConnection.

Without the accessor, that access would have to come through method parameters. Every callback that might need the connection would become something like _on_received(conn: TCPConnection, data: Array[U8] iso) instead of _on_received(data: Array[U8] iso). You'd either pass the connection to all callbacks (heavier signatures across the board) or pick which ones get it (and guess wrong sometimes).

What it enables: In the interceptor pattern (Shape 2), removing _connection() from the lifecycle receiver traits means the interceptor class no longer needs to provide an accessor to the TCPConnection. The connection can be a fully private field on the interceptor. This prevents the user from reaching through the protocol layer to call send() directly on the raw connection.

What it costs: Heavier callback signatures if default implementations ever need connection access. The accessor is the cleaner version of the same access pattern — one method on the trait vs. a parameter on every callback.

This is a real tradeoff, not a clear win in either direction.

[SeanTAllen]

Item 2 analysis: Buffering strategies (deferred)

Adding expect_until(delimiter) alongside expect(N) is a bad idea — it creates two competing APIs that can be mixed in confusing ways. What does it mean to call expect(5) after expect_until("\r\n")? The interaction semantics are unclear and error-prone.

Both are instances of the same concept: buffering strategies that sit between TCP reads and _on_received, deciding when a complete unit is ready for the application. There are three basic strategies:

1. Framed — give me exactly N bytes. This is what expect(N) does today. Works for protocols with length-prefixed units (WebSocket frames, msgpack).
2. Line-oriented — give me bytes until a delimiter like \r\n. Works for line-based protocols (SMTP commands/responses, RESP simple types).
3. None — Lori delivers raw bytes, the protocol layer handles its own buffering entirely. This is what complex protocols like HTTP end up needing regardless — HTTP's body-length determination is too messy (Content-Length, chunked, connection close, implicit from status) for either strategy 1 or 2 to handle cleanly. Note: HTTP Content-Length isn't "framing" — it's metadata in one section of the message describing the size of another section. The body has no structural framing; it's just raw bytes whose size is determined by external rules.

The core abstraction for a pluggable strategy is simple: buffer in → (complete_unit, remaining_bytes) where the complete unit is either a slice (ready) or empty (need more data). A framed strategy checks if the buffer has N bytes; a line-oriented strategy scans for the delimiter. Both return the remainder.

The hard part is configuration. How does the enclosing actor tell Lori which strategy to use? How does switching between strategies work mid-stream without creating a messy API surface? The actor would need to know which strategy is active and call the right configuration method (expect vs some line-oriented equivalent), which is essentially the "two competing APIs" problem restated at a different level.

Decision: Deferred. The current expect(N) covers framed protocols. Protocols that need line-oriented or mixed buffering handle it themselves (strategy 3). A clean unified buffering abstraction would be nice eventually, but the configuration/switching problem doesn't have an obvious clean answer yet.

[SeanTAllen]

Decision: Build concrete protocols first, extract abstractions later

Rather than trying to design a generic protocol framework upfront, the plan is to build all 5 target protocols on top of Lori as-is and then look for commonalities across the concrete implementations. The right abstraction will emerge from real code, not from speculative design.

This discussion is useful as background research for the design space, but the next step is "build Redis" — not "design a pluggable protocol layer."