SSL as a first-class TCPConnection concern

[SeanTAllen]

Context

This discussion explores Direction A from Discussion #156 (Rethinking SSL and protocol transforms in lori): making SSL a first-class connection concern built into TCPConnection. Direction A serves as the foundation — Direction B (protocol adapters above the SSL layer) will be incorporated on top of this once the foundation is solid.

Motivation

Lori's DataInterceptor trait (Discussion #149, PR #154) solves the data ordering problem for protocol layering but introduces a separate object into lori's mixin-pattern architecture. That object is essentially a notifier — it can't receive messages, can't participate in the actor's state machine, and sits outside the compile-time safety the mixin pattern provides. For a single interceptor (just SSL), this is manageable. But composition of multiple interceptors introduces ordering mistakes, setup/ready signaling complexity, error propagation ambiguity, and reintroduces the fundamental limitation lori was created to avoid. See Discussion #156 for the full analysis.

The solution: SSL is not an interceptor. It's a transport-level concern that belongs inside the connection itself.

Design

Four constructors

TCPConnection gets two new SSL-specific constructors alongside the existing two:

// Non-SSL (unchanged)
TCPConnection.client(auth, host, port, from, enclosing, ler)
TCPConnection.server(auth, fd, enclosing, ler)

// SSL
TCPConnection.ssl_client(auth, ssl_ctx, host, port, from, enclosing, ler)
TCPConnection.ssl_server(auth, ssl_ctx, fd, enclosing, ler)

Separate constructors rather than optional parameters because:

• Explicit over implicit — the call site shows immediately whether a connection is SSL-enabled.
• No meaningless parameters — non-SSL constructors don't carry SSL parameters that are irrelevant to their case.
• No runtime branching on construction-time knowledge — avoids (SSLContext | None) parameters that add a runtime branch for something known at construction time.

SSLContext as the dependency injection point

The SSL constructors receive an SSLContext (from the ponylang/ssl library), not raw configuration. This keeps SSL configuration knowledge in the ssl library where it belongs. The user configures the context however they want (certs, CA, ciphers, ALPN, verification settings), and lori just consumes it.

SSLContext is a val class, so it can be shared across connections — create one context, use it for many connections. TCPConnection internally calls ssl_ctx.client(host) or ssl_ctx.server() to create the per-connection SSL session.

Internal SSL session management

TCPConnection owns the SSL session and manages the full lifecycle:

• Handshake: Feeds encrypted bytes through SSL.receive(), checks SSL.state(), sends handshake data via SSL.can_send() / SSL.send(). Defers _on_connected / _on_started until SSL.state() returns SSLReady.
• Receive path: Encrypted wire data goes into SSL.receive(), decrypted plaintext comes out via SSL.read(), and is delivered to the actor's _on_received.
• Send path: The actor calls send() with plaintext. TCPConnection encrypts via SSL.write() and sends ciphertext via SSL.can_send() / SSL.send().
• Close: SSL.dispose() is called on connection close.

This is the same logic currently in SSLClientInterceptor / SSLServerInterceptor — it moves from the interceptor into TCPConnection itself.

No changes needed in ponylang/ssl

The SSL class's existing API is exactly what TCPConnection would use internally:

• SSLContext.client(host) / SSLContext.server() — session creation
• SSL.receive(data) — feed encrypted bytes from the wire
• SSL.read(expect) — extract decrypted plaintext
• SSL.write(data) — encrypt plaintext for sending
• SSL.can_send() / SSL.send() — extract ciphertext for the wire
• SSL.state() — check handshake state
• SSL.alpn_selected() — get negotiated ALPN protocol
• SSL.dispose() — cleanup

The ssl library doesn't need to change. The reference capabilities work: SSLContext is val (shareable), SSL is ref (owned by TCPConnection, which is a ref class owned by one actor).

Open questions to resolve

1. SSL-specific callbacks. Currently NetSSLLifecycleEventReceiver delivers on_alpn_negotiated, on_ssl_auth_failed, on_ssl_error to the actor. How should these reach the actor with SSL built into the connection? Options: a new SSL-specific lifecycle trait the actor implements, additional methods on the existing lifecycle receiver traits, or fold them into existing callbacks (e.g., auth failure becomes _on_connection_failure).

2. Send behavior during handshake. Currently send() returns SendErrorNotReady if the interceptor handshake isn't complete. With SSL built in, does the connection queue data during handshake, return an error, or is it impossible to call send before _on_connected (which is deferred until handshake completes)?

3. What happens to DataInterceptor? With SSL built into the connection, the interceptor's original motivating use case is gone. Does the trait remain for Direction B (protocol adapters), get redesigned for that purpose, or get removed entirely and replaced with something different when we get to Direction B?

4. Connection failure semantics. If the SSL handshake fails (auth failure, protocol error), should the client get _on_connection_failure() (same as TCP connection failure) or a distinct callback? The current interceptor design uses _on_connection_failure for handshake failures before _on_connected was delivered.

5. adjust_expect equivalent. The current DataInterceptor has adjust_expect() because SSL changes data framing (returns 0 to read all available, tracks the application's value internally). With SSL inside TCPConnection, this needs to be handled internally — does TCPConnection manage expect differently when SSL is active?

[SeanTAllen]

Send lifecycle and failure semantics

Send before connected

In an async actor system, "create connection then send data" is a natural pattern — the send can arrive before the connection is established. The connection should handle this gracefully:

• send() always accepts and returns a SendToken, regardless of connection state.
• If connected and SSL ready: data is encrypted and sent. _on_sent(token) fires when handed to the OS.
• If not yet connected (or SSL handshake in progress): data is queued. After connection + handshake completes, queued data is flushed. _on_sent(token) fires for each.
• If backpressured: current SendErrorNotWriteable behavior (transient, not a pre-connection concern).

This means SendErrorNotConnected and SendErrorNotReady from the current send system go away — those cases are handled by queuing + async failure notification instead of synchronous rejection.

Explicit send failure notification

Every send gets an explicit outcome: either _on_sent(token) or _on_send_failed(token). The user never has to infer that a send failed from a connection-level event.

_on_send_failed(token) fires for any send that can't be delivered, regardless of context:

• Connection never established
• SSL handshake failed with queued sends
• Connection dropped with data in the write buffer

_on_closed / _on_connection_failure fire separately for the connection-level event. This separates "your connection is gone" from "your specific send didn't make it."

Note: This separation of _on_send_failed from _on_connection_failure / _on_closed might be incorrect. It's possible that a unified approach (failed sends reported as part of the close/failure event) is better. Starting with separation because it's more explicit and allows separation of concerns on the client end, but this is a point that may be revisited.

SSL handshake failure is a connection failure

SSL handshake failure (auth failure, protocol error) maps to _on_connection_failure() — the same callback as TCP connection failure. The user asked to connect, it didn't work. No distinction is made between failure reasons.

Possible future work: expanding _on_connection_failure to provide a reason (SSL auth failure vs unreachable host vs timeout, etc.). But for now, it's just "it failed."

[SeanTAllen]

SSL-specific callbacks: none

SSL is invisible to the actor's callback interface. There are no SSL-specific callbacks:

• SSL auth failure / protocol errors map to _on_connection_failure() (resolved in the previous comment).
• ALPN negotiation results are not surfaced to the actor. ALPN configuration happens on the SSLContext (the ssl library's concern), but lori does not deliver the result. If someone needs it later, adding a callback or query method is additive and non-breaking.

The actor's callback interface is identical for SSL and non-SSL connections: _on_connected, _on_received, _on_closed, _on_connection_failure, _on_sent, _on_send_failed, _on_throttled, _on_unthrottled. The only difference between SSL and non-SSL is the constructor used.

This means NetSSLLifecycleEventReceiver (the current SSL-specific callback trait) has no equivalent in this design.

[SeanTAllen]

DataInterceptor: removed

The DataInterceptor trait is removed. Its original motivating use case (SSL) is now handled inside TCPConnection. Protocol adapters (Direction B) will be designed later from real use cases — pick a simple protocol, build support for it, and let the abstraction emerge from actual needs rather than building a general framework upfront.

The adjust_expect concern (question 5) is an internal implementation detail: TCPConnection handles expect differently when SSL is active (SSL manages its own framing). Not a design decision, just implementation work.

Direction A summary

All design questions are resolved:

Decision	Resolution
Constructors	Four explicit: client, server, ssl_client, ssl_server
SSL configuration	SSLContext passed to SSL constructors. User configures it, TCPConnection creates the SSL session internally
ssl library changes	None needed. Existing SSL class API used as-is
Send before connected	Accepted and queued. Flushed after connection + handshake. Every send gets an explicit outcome
Send failure	_on_send_failed(token) fires for any undeliverable send, regardless of context. Separate from _on_connection_failure / _on_closed (may revisit — might unify)
SSL handshake failure	Maps to _on_connection_failure(). No distinction from TCP failure. Failure reasons are possible future work
SSL-specific callbacks	None. SSL is invisible to the actor's callback interface. ALPN results not surfaced (additive future work if needed)
DataInterceptor	Removed. Protocol adapters (Direction B) designed later from real use cases
adjust_expect	Internal to TCPConnection when SSL is active. Implementation detail

The actor's experience with SSL is: use ssl_client or ssl_server constructor instead of client or server. Everything else — callbacks, send behavior, failure handling — is identical.

Next step: Direction B — protocol adapters on top of this foundation, driven by a concrete simple protocol use case.

[SeanTAllen]

Discussion #158 has the concrete implementation plan for Direction A. Eleven steps covering send queueing, failure notification, SSL constructors, internal SSL logic, removal of DataInterceptor infrastructure, and example/test updates. Includes a phased approach if incremental merging is preferred.

[SeanTAllen]

This design was implemented across two PRs:

• PR Add _on_send_failed and _on_start_failure lifecycle callbacks #159 — Added _on_send_failed and _on_start_failure lifecycle callbacks
• PR Make SSL a first-class TCPConnection concern #160 — Added ssl_client/ssl_server constructors, removed DataInterceptor infrastructure, removed SendErrorNotReady

Deviations from the original design:

• Send queueing dropped: send() remains fallible with SendErrorNotConnected and SendErrorNotWriteable instead of queueing pre-connection sends.
• ssl_server made non-partial: Instead of raising on SSL session creation failure, it reports failure asynchronously via _on_start_failure(), matching the ssl_client pattern.