Separate Data Interception from Lifecycle Events

[SeanTAllen]

Separate Data Interception from Lifecycle Events

Ref: #137

Problem

Lori's lifecycle event receiver chain uses a single linked list via _next_lifecycle_event_receiver(). This chain defines one wrapping order for all operations. But correct protocol layering requires opposite orderings for reading and writing.

Consider three layers: base TCP, SSL, and a custom handler:

• Reading (wire to application): TCP raw bytes -> SSL decrypt -> custom handler
• Writing (application to wire): custom handler -> SSL encrypt -> TCP send

The reading order is SSL-then-custom. The writing order is custom-then-SSL. A single chain can only represent one ordering. With SSL + compression:

• Write: application data -> compress -> encrypt -> wire
• Read: wire -> decrypt -> decompress -> application

If SSL wraps Compression wraps User: read is correct (decrypt then decompress) but send is wrong (encrypts then compresses). If the wrapping order is reversed: send is correct but read is wrong. Neither wrapping order works for both directions.

Why it works today for SSL alone

The SSL implementation (NetSSLClientConnection/NetSSLServerConnection) works around this by manually routing data outside the chain's ordering. On receive, SSL intercepts raw bytes, decrypts, and pushes decrypted data to the wrapped receiver. On send, SSL delegates the application's _on_send through the chain first, then encrypts the result and sends encrypted bytes directly via _send_final(), bypassing the normal return path. This manual routing gives correct per-direction ordering for SSL specifically, but doesn't generalize to additional layers.

Analysis of Current Design

The lifecycle event receiver traits conflate two concerns:

1. Data transformation (protocol level): _on_received transforms incoming data (SSL decryption), _on_send transforms outgoing data (SSL encryption), _on_expect_set adjusts framing. These are protocol concerns where ordering matters and differs per direction.

2. Application callbacks (application level): _on_connected/_on_started, _on_closed, _on_throttled/_on_unthrottled, and _on_received as the final data consumer. These are application concerns with typically one handler.

SSL participates in both: it transforms data AND intercepts lifecycle events (swallowing _on_connected until handshake completes, cleaning up on close, overriding expect). The current single trait carries all of this, which is the root of the composability problem.

Proposed Design

Separate the two concerns: data interception (protocol level) and lifecycle handling (application level). Interceptors are composed by the programmer — no automatic chaining, no magic.

Interfaces

interface WireSender
  """
  Sends data directly to the wire, bypassing the outgoing interceptor pipeline.
  Provided by TCPConnection to interceptors.
  """
  fun ref send(data: ByteSeq)

interface IncomingDataReceiver
  """
  Receives processed incoming data from an interceptor. TCPConnection provides
  an implementation that delivers data to the lifecycle event receiver's
  _on_received callback.
  """
  fun ref receive(data: Array[U8] iso)

interface SetupControl
  """
  Provided by TCPConnection to interceptors during on_setup(). Gives the
  interceptor the ability to signal readiness, send wire data during
  handshake, and close the connection on protocol errors.

  Only on_setup receives this interface. incoming/outgoing receive the
  narrower WireSender, so adapter classes in composition chains cannot
  accidentally signal readiness or close the connection.
  """
  fun ref signal_ready()
  fun ref send_to_wire(data: ByteSeq)
  fun ref close()

interface DataInterceptor
  """
  Protocol-level data transformer. Sits between TCP and the application.
  Handles concerns like encryption, compression, or framing.

  Both incoming and outgoing use a push model: the interceptor receives data
  and pushes results downstream. This supports protocols like SSL that may
  produce zero, one, or many output chunks per input chunk.
  """

  fun ref on_setup(control: SetupControl ref) =>
    """
    Called when the TCP connection is established, before the application is
    notified. Use this for protocol handshakes.

    Call control.signal_ready() when the protocol is ready for application
    data. Non-handshake interceptors should signal immediately (the default).
    Use control.send_to_wire() for protocol data (e.g., ClientHello).
    Use control.close() on fatal protocol errors (e.g., SSL auth failure).

    TCPConnection defers _on_connected/_on_started until signal_ready() is
    called. Incoming data continues to flow through the interceptor during
    this time (for handshake processing). TCP reads begin immediately after
    on_setup returns, regardless of whether signal_ready has been called.
    """
    control.signal_ready()

  fun ref on_teardown() =>
    """
    Called when the connection is closing, for protocol cleanup (e.g., SSL
    session disposal). Called regardless of whether signal_ready() was ever
    called — handles the case where the connection closes during handshake.
    """
    None

  fun ref incoming(data: Array[U8] iso,
    receiver: IncomingDataReceiver ref,
    wire: WireSender ref)
  =>
    """
    Process incoming data from the wire. Call receiver.receive() for each
    chunk of processed data to deliver to the application.

    The wire parameter is for protocols that need to send data during receive
    processing (e.g., SSL handshake responses, renegotiation).

    Interceptors that need to close the connection on errors during incoming
    processing (e.g., SSL encountering an error mid-stream) should store the
    SetupControl reference from on_setup() and call close() on it.
    """
    receiver.receive(consume data)

  fun ref outgoing(data: ByteSeq, wire: WireSender ref) =>
    """
    Process outgoing data from the application. Call wire.send() for each
    chunk of processed data to send to the wire.

    The push model supports protocols like SSL where a single plaintext write
    may produce multiple encrypted records, or where data is buffered during
    handshake and flushed later.
    """
    wire.send(data)

  fun ref adjust_expect(qty: USize): USize =>
    """
    Adjust the expect quantity for protocols that change data framing.

    Called when the application sets an expect value. The interceptor receives
    the application's requested chunk size, may store it internally, and
    returns the value that TCPConnection should use for TCP reads.

    SSL returns 0 (read all available) and tracks the application's value
    internally for its own framing when delivering decrypted data.
    """
    qty

TCPConnection contract with interceptors

Setup timing: on_setup is called only after TCP establishment succeeds. For client connections, _on_connecting and _on_connection_failure go directly to the lifecycle receiver — the interceptor is not involved in pre-connection events.

Ready signaling: TCPConnection defers _on_connected/_on_started until signal_ready(). It guards against multiple signal_ready() calls (delivers _on_connected/_on_started at most once).

Close during handshake: If the connection closes before signal_ready(), on_teardown() is called for cleanup but _on_connected/_on_started is never delivered. The lifecycle receiver sees _on_closed without a preceding _on_connected, which is different from a normal close. For client connections, _on_connection_failure could be called instead to distinguish handshake failure from post-connection close, but this is an implementation detail to resolve.

Never-signaling interceptors: If an interceptor never calls signal_ready(), the application is never notified of the connection. Data continues flowing through incoming() indefinitely. Eventually the remote side or a timeout closes the connection, triggering on_teardown() and _on_closed. This is documented as a "don't do that" — interceptors must either signal ready or close.

Send path: When an interceptor is present, TCPConnection.send() delegates entirely to interceptor.outgoing() and does NOT send the original data itself. The interceptor controls what reaches the wire via wire.send(). Without an interceptor, send() calls _send_final() directly.

Lifecycle Event Receiver Simplification

With data transformation extracted, lifecycle receivers drop _next_lifecycle_event_receiver(), _on_send, and _on_expect_set:

trait ServerLifecycleEventReceiver
  fun ref _connection(): TCPConnection

  fun ref _on_started() => None
  fun ref _on_closed() => None
  fun ref _on_received(data: Array[U8] iso) => None
  fun ref _on_throttled() => None
  fun ref _on_unthrottled() => None

trait ClientLifecycleEventReceiver
  fun ref _connection(): TCPConnection

  fun ref _on_connecting(inflight_connections: U32) => None
  fun ref _on_connected() => None
  fun ref _on_connection_failure() => None
  fun ref _on_closed() => None
  fun ref _on_received(data: Array[U8] iso) => None
  fun ref _on_throttled() => None
  fun ref _on_unthrottled() => None

No chaining. No auto-delegation. One lifecycle receiver per connection.

Behavioral change from removing _on_send: Currently, the application's _on_send sees plaintext before encryption (SSL delegates _on_send through the chain before encrypting). In the new design, there is no equivalent callback — outgoing data goes directly from send() to the interceptor. Applications that need to inspect outgoing data before protocol transformation can write a thin interceptor. In practice, none of the existing examples or tests override _on_send for application logic.

TCPConnection Constructor Changes

new client(auth: TCPConnectAuth,
  host: String,
  port: String,
  from: String,
  enclosing: TCPConnectionActor ref,
  ler: ClientLifecycleEventReceiver ref,
  interceptor: (DataInterceptor ref | None) = None)

new server(auth: TCPServerAuth,
  fd': U32,
  enclosing: TCPConnectionActor ref,
  ler: ServerLifecycleEventReceiver ref,
  interceptor: (DataInterceptor ref | None) = None)

Data flow with an interceptor:

Connect: TCP established -> interceptor.on_setup(control)
                            ... interceptor signals ready ...
                         -> lifecycle._on_connected()

Receive: wire bytes -> interceptor.incoming(data, receiver, wire)
                       ... interceptor calls receiver.receive() ...
                    -> lifecycle._on_received(data)

Send:    connection.send(data) -> interceptor.outgoing(data, wire)
                                  ... interceptor calls wire.send() ...
                               -> _send_final(data)

Close:   interceptor.on_teardown() -> lifecycle._on_closed()

Without an interceptor: identical to current non-SSL behavior.

Composing Multiple Interceptors

The programmer composes interceptors manually, controlling ordering per direction. No framework magic — the user writes the composition.

ChainedInterceptor Helper

For the common case of two interceptors where the receive order should be reversed for send (the standard protocol stack pattern), Lori provides a helper:

class ChainedInterceptor is DataInterceptor
  """
  Chains two interceptors. For incoming, _outer processes before _inner
  (wire-side first). For outgoing, the order reverses: _inner processes
  before _outer (application-side first).

  This matches the standard protocol layering pattern: the wire-side
  protocol (e.g., SSL) decrypts on read and encrypts on write.

  Usage: ChainedInterceptor(ssl, compression)
    incoming: ssl (decrypt) -> compression (decompress) -> application
    outgoing: compression (compress) -> ssl (encrypt) -> wire
  """
  let _outer: DataInterceptor ref  // closer to wire (e.g., SSL)
  let _inner: DataInterceptor ref  // closer to application (e.g., compression)

  new create(outer: DataInterceptor ref, inner: DataInterceptor ref) =>
    _outer = outer
    _inner = inner

  fun ref on_setup(control: SetupControl ref) =>
    // Outer interceptor handles setup (e.g., SSL handshake).
    // Inner interceptor's on_setup is called after outer signals ready,
    // or immediately if it has no handshake.
    // For simplicity, both are called. If inner has no setup, the default
    // signals ready immediately (harmless double-signal, guarded by
    // TCPConnection).
    _outer.on_setup(control)

  fun ref on_teardown() =>
    _outer.on_teardown()
    _inner.on_teardown()

  fun ref incoming(data: Array[U8] iso,
    receiver: IncomingDataReceiver ref,
    wire: WireSender ref)
  =>
    // outer (decrypt) -> inner (decompress) -> application
    let chain = _ChainedReceiver(_inner, receiver, wire)
    _outer.incoming(consume data, chain, wire)

  fun ref outgoing(data: ByteSeq, wire: WireSender ref) =>
    // inner (compress) -> outer (encrypt) -> wire
    let chain = _ChainedSender(_outer, wire)
    _inner.outgoing(data, chain)

  fun ref adjust_expect(qty: USize): USize =>
    // Application -> inner -> outer -> TCP
    _outer.adjust_expect(_inner.adjust_expect(qty))

class _ChainedReceiver is IncomingDataReceiver
  """Adapter: receives data from outer interceptor, passes through inner."""
  let _inner: DataInterceptor ref
  let _downstream: IncomingDataReceiver ref
  let _wire: WireSender ref

  new create(inner: DataInterceptor ref,
    downstream: IncomingDataReceiver ref,
    wire: WireSender ref)
  =>
    _inner = inner
    _downstream = downstream
    _wire = wire

  fun ref receive(data: Array[U8] iso) =>
    _inner.incoming(consume data, _downstream, _wire)

class _ChainedSender is WireSender
  """Adapter: receives data from inner interceptor, passes through outer."""
  let _outer: DataInterceptor ref
  let _wire: WireSender ref

  new create(outer: DataInterceptor ref, wire: WireSender ref) =>
    _outer = outer
    _wire = wire

  fun ref send(data: ByteSeq) =>
    _outer.outgoing(data, _wire)

Note: _ChainedSender receives WireSender ref (not SetupControl ref), so inner interceptors cannot accidentally call signal_ready() or close().

Manual Composition

For cases where ChainedInterceptor doesn't fit (asymmetric setup, non-standard ordering), the programmer writes a custom composition class implementing DataInterceptor directly. The manual composition follows the same adapter pattern shown in ChainedInterceptor.

SSL as a DataInterceptor

The current NetSSLClientConnection (107 lines) and NetSSLServerConnection (104 lines) become SSLClientInterceptor and SSLServerInterceptor implementing DataInterceptor. Sketch of SSLClientInterceptor to validate the interface:

class SSLClientInterceptor is DataInterceptor
  let _ssl: SSL
  let _ssl_receiver: (NetSSLLifecycleEventReceiver ref | None)
  let _pending: List[ByteSeq] = _pending.create()
  var _connected: Bool = false
  var _closed: Bool = false
  var _expect: USize = 0
  var _control: (SetupControl ref | None) = None

  new create(ssl: SSL iso,
    ssl_receiver: (NetSSLLifecycleEventReceiver ref | None) = None)
  =>
    _ssl = consume ssl
    _ssl_receiver = ssl_receiver

  fun ref on_setup(control: SetupControl ref) =>
    _control = control
    // SSL handshake begins when first data arrives via incoming().
    // For client SSL, we could also initiate here. _ssl_poll handles it.

  fun ref on_teardown() =>
    _closed = true
    _ssl.dispose()
    _connected = false
    _pending.clear()

  fun ref incoming(data: Array[U8] iso,
    receiver: IncomingDataReceiver ref,
    wire: WireSender ref)
  =>
    _ssl.receive(consume data)
    _ssl_poll(receiver, wire)

  fun ref outgoing(data: ByteSeq, wire: WireSender ref) =>
    if _connected then
      try _ssl.write(data)? end
    else
      _pending.push(data)
    end
    // Send any encrypted data produced
    try
      while _ssl.can_send() do
        wire.send(_ssl.send()?)
      end
    end

  fun ref adjust_expect(qty: USize): USize =>
    _expect = qty
    0  // tell TCP to read all available; SSL manages its own framing

  fun ref _ssl_poll(receiver: IncomingDataReceiver ref,
    wire: WireSender ref)
  =>
    match _ssl.state()
    | SSLReady =>
      if not _connected then
        _connected = true
        match _control
        | let c: SetupControl ref => c.signal_ready()
        end

        match _ssl_receiver
        | let ler: NetSSLLifecycleEventReceiver ref =>
          ler.on_alpn_negotiated(_ssl.alpn_selected())
        end

        // Flush pending writes
        try
          while _pending.size() > 0 do
            _ssl.write(_pending.shift()?)?
          end
        end
      end
    | SSLAuthFail =>
      if not _closed then
        match _ssl_receiver
        | let ler: NetSSLLifecycleEventReceiver ref =>
          ler.on_ssl_auth_failed()
        end
        match _control
        | let c: SetupControl ref => c.close()
        end
      end
      return
    | SSLError =>
      if not _closed then
        match _ssl_receiver
        | let ler: NetSSLLifecycleEventReceiver ref =>
          ler.on_ssl_error()
        end
        match _control
        | let c: SetupControl ref => c.close()
        end
      end
      return
    end

    // Deliver decrypted application data
    while true do
      match _ssl.read(_expect)
      | let d: Array[U8] iso => receiver.receive(consume d)
      | None => break
      end
    end

    // Send any SSL protocol data
    try
      while _ssl.can_send() do
        wire.send(_ssl.send()?)
      end
    end

Note on outgoing vs. incoming _ssl_poll: The current code uses a unified _ssl_poll() that checks SSL state and delivers both decrypted data and encrypted protocol data, called from both _on_received and _on_send. In this design, outgoing() does not have access to IncomingDataReceiver, so it cannot deliver decrypted data. In practice, SSL's write path produces encrypted output but does not produce decrypted input — decrypted data only becomes available after _ssl.receive(), which is called in incoming(). The split is behaviorally equivalent to the current code for all practical scenarios.

SSL-specific callbacks (on_alpn_negotiated, on_ssl_auth_failed, on_ssl_error) are passed to the SSL interceptor's constructor as an optional NetSSLLifecycleEventReceiver ref. The application actor implements this interface (as it does today) and passes this. This decouples SSL-specific callbacks from the base interceptor interface.

Client vs. server differences live in the implementation classes (SSLClientInterceptor vs. SSLServerInterceptor), not in the DataInterceptor interface, which is unified.

Example Usage

Simple server (no interceptor, no change from today except removing _next_lifecycle_event_receiver)

actor Echoer is (TCPConnectionActor & ServerLifecycleEventReceiver)
  var _tcp_connection: TCPConnection = TCPConnection.none()

  new create(auth: TCPServerAuth, fd: U32) =>
    _tcp_connection = TCPConnection.server(auth, fd, this, this)

  fun ref _connection(): TCPConnection => _tcp_connection

  fun ref _on_received(data: Array[U8] iso) =>
    _tcp_connection.send(consume data)

SSL client (interceptor replaces NetSSLClientConnection wrapping)

actor Client is (TCPConnectionActor & ClientLifecycleEventReceiver)
  var _tcp_connection: TCPConnection = TCPConnection.none()

  new create(auth: TCPConnectAuth, ssl: SSL iso,
    host: String, port: String)
  =>
    let interceptor = SSLClientInterceptor(consume ssl, this)
    _tcp_connection = TCPConnection.client(
      auth, host, port, "", this, this, interceptor)

  fun ref _connection(): TCPConnection => _tcp_connection

  fun ref _on_connected() =>
    _tcp_connection.send("Hello")

  fun ref _on_received(data: Array[U8] iso) =>
    // data is already decrypted

SSL + compression (composed interceptors)

actor Client is (TCPConnectionActor & ClientLifecycleEventReceiver)
  var _tcp_connection: TCPConnection = TCPConnection.none()

  new create(auth: TCPConnectAuth, ssl: SSL iso,
    host: String, port: String)
  =>
    let ssl_interceptor = SSLClientInterceptor(consume ssl, this)
    let compression = CompressionInterceptor
    // incoming: SSL decrypt -> decompress -> application
    // outgoing: compress -> SSL encrypt -> wire
    let interceptor = ChainedInterceptor(ssl_interceptor, compression)
    _tcp_connection = TCPConnection.client(
      auth, host, port, "", this, this, interceptor)

  fun ref _connection(): TCPConnection => _tcp_connection

Migration Impact

Every implementor of the lifecycle receiver traits needs to:

1. Delete _next_lifecycle_event_receiver() — all current implementations return None; this is mechanical deletion
2. Delete _on_send if overridden — none of the examples or tests override it for application logic; pure deletion
3. Delete _on_expect_set if overridden — same

SSL users need to:

1. Replace NetSSLClientConnection/NetSSLServerConnection wrapping with the new SSL interceptor parameter
2. Before: let sslc = NetSSLClientConnection(consume ssl, this); TCPConnection.client(auth, host, port, "", this, sslc)
3. After: let interceptor = SSLClientInterceptor(consume ssl, this); TCPConnection.client(auth, host, port, "", this, this, interceptor)

The migration steps are:

1. Add DataInterceptor, IncomingDataReceiver, WireSender, SetupControl interfaces
2. Add optional interceptor parameter to TCPConnection.client() and .server()
3. Implement SSLClientInterceptor and SSLServerInterceptor
4. Add ChainedInterceptor helper
5. Update examples and tests to use interceptors
6. Remove _next_lifecycle_event_receiver(), _on_send, _on_expect_set from lifecycle traits
7. Remove NetSSLClientConnection/NetSSLServerConnection

[SeanTAllen]

Implementation note: ChainedInterceptor deferred

The initial implementation (PR forthcoming) does not include ChainedInterceptor, _ChainedReceiver, or _ChainedSender. Sean has ideas for using interceptors to implement protocol lifecycle on top of this foundation (e.g., HTTP lifecycle built on the interceptor pattern), which should inform how composition works. Building the chaining mechanism before that design work would risk getting the composition model wrong.

The current PR delivers the core DataInterceptor trait, the InterceptorControl/WireSender/IncomingDataReceiver interfaces, adapter classes in TCPConnection, and SSLClientInterceptor/SSLServerInterceptor as the first interceptor implementations. This is a complete, usable foundation — chaining can be added later without breaking the existing interceptor contract.

[SeanTAllen]

Implementation note: ChainedInterceptor (composing multiple DataInterceptors) is deferred from the initial PR (#151). Sean has ideas for using interceptors to implement protocol lifecycle on top of this foundation (e.g., HTTP), which should inform the composition design before we commit to a chaining API.

[SeanTAllen]

this was implemented without the chainedinterceptors so i am leaving this open until we decide not to do chained or they are done.

[SeanTAllen]

The DataInterceptor design from this discussion was implemented in PR #151, then removed in PR #160 as part of a redesign that made SSL a first-class concern of TCPConnection.

The discussions that led to the removal:

• Rethinking SSL and protocol transforms in lori #156 — Research into SSL/TLS alternatives and protocol transform architecture
• SSL as a first-class TCPConnection concern #157 — Design for SSL as a first-class TCPConnection concern (Direction A)
• Implementation plan: SSL as first-class TCPConnection concern #158 — Implementation plan