Structured Failure Reasons for Connection Callbacks

[SeanTAllen]

Motivation

Courier's structured error type analysis identified that _on_connection_failure(), _on_start_failure(), and _on_tls_failure() carry no information about why the failure occurred. Internally, lori knows the category of failure at each call site but discards it before invoking the callback. This blocks downstream libraries from reporting meaningful failure types.

Current State

All three failure callbacks are parameterless:

fun ref _on_connection_failure() => None
fun ref _on_start_failure() => None
fun ref _on_tls_failure() => None

A client connection can fail for three distinct reasons — DNS resolution, TCP connection, or SSL/TLS — but the application receives the same bare callback for all of them. The same applies to server start failures (currently only SSL) and TLS upgrade failures (auth vs general).

Proposed Types

Three new type aliases following the existing pattern (SendError, StartTLSError):

ConnectionFailureReason

primitive ConnectionFailedDNS
  """
  Name resolution returned no usable addresses. The `_on_connecting` callback
  was never called — no TCP connections were attempted.
  """

primitive ConnectionFailedTCP
  """
  All TCP connection attempts failed. At least one address was resolved and
  attempted, but none connected successfully.
  """

primitive ConnectionFailedSSL
  """
  SSL session creation or handshake failed. For handshake failures, the TCP
  connection succeeded but the SSL layer rejected the connection before data
  could be exchanged.
  """

type ConnectionFailureReason is
  (ConnectionFailedDNS | ConnectionFailedTCP | ConnectionFailedSSL)

StartFailureReason

primitive StartFailedSSL
  """
  SSL session creation or handshake failed before the server connection was
  ready for application data.
  """

type StartFailureReason is StartFailedSSL

Currently a single-variant union. The type alias exists for forward compatibility — adding a non-SSL failure mode later won't change the callback signature.

TLSFailureReason

primitive TLSAuthFailed
  """
  Peer certificate or identity verification failed during the TLS upgrade
  handshake initiated by `start_tls()`.
  """

primitive TLSGeneralError
  """
  The TLS upgrade handshake failed for a non-authentication reason (protocol
  mismatch, malformed handshake, etc.).
  """

type TLSFailureReason is (TLSAuthFailed | TLSGeneralError)

Callback Changes

// Before
fun ref _on_connection_failure() => None
fun ref _on_start_failure() => None
fun ref _on_tls_failure() => None

// After
fun ref _on_connection_failure(reason: ConnectionFailureReason) => None
fun ref _on_start_failure(reason: StartFailureReason) => None
fun ref _on_tls_failure(reason: TLSFailureReason) => None

This is a breaking change. Code that overrides these callbacks must add the parameter. Code that relies on the default implementation is unaffected.

Semantic Mapping

_on_connection_failure(reason)

Scenario	Reason
pony_os_connect_tcp initiates 0 connection attempts (name resolution failed)	ConnectionFailedDNS
All Happy Eyeballs TCP attempts fail (via _connecting_callback draining to 0)	ConnectionFailedTCP
Application calls close() during connecting; inflight connections drain without success	ConnectionFailedTCP (DNS failure fires synchronously before user code runs, so only TCP is reachable here)
Application calls hard_close() during connecting	ConnectionFailedTCP (same reasoning)
SSL session creation fails (ssl_ctx.client() throws)	ConnectionFailedSSL
SSL handshake fails after TCP connects but before _on_connected	ConnectionFailedSSL

_on_start_failure(reason)

Scenario	Reason
SSL session creation fails (ssl_ctx.server() throws)	StartFailedSSL
SSL handshake fails before _on_started	StartFailedSSL

_on_tls_failure(reason)

Scenario	Reason
ssl.state() returns SSLAuthFail during upgrade	TLSAuthFailed
ssl.state() returns SSLError during upgrade	TLSGeneralError

Design Decisions

DNS vs TCP distinction: pony_os_connect_tcp returns the number of connection attempts initiated (not addresses resolved). If it returns 0, no TCP connections were attempted. If it returns >0 but all attempts fail, it's a TCP failure. A new internal flag tracks whether any connections were ever initiated.

Known imprecision: If DNS succeeds but socket creation fails for every resolved address (e.g., the system is out of file descriptors), pony_os_connect_tcp still returns 0. This would be reported as ConnectionFailedDNS even though DNS succeeded. This is a rare edge case not worth distinguishing at this level.

SSL creation vs handshake: Both map to the same reason (ConnectionFailedSSL / StartFailedSSL). Session creation failure is a configuration problem (bad cert files); handshake failure is a runtime problem (cert validation, protocol mismatch). Both result in "the SSL layer prevented the connection," which is the actionable category.

Application-initiated abort during connecting: When the application calls close() or hard_close() during the connecting phase, _on_connection_failure still fires with ConnectionFailedTCP (DNS failure fires synchronously before user code can run, so only TCP is reachable). The application already knows it initiated the abort — the reason tells it what phase the connection was in, not that a spontaneous failure occurred.

TLS auth vs general for initial SSL: The SSLAuthFail/SSLError distinction from ssl.state() is available for initial SSL handshake failures too, but is collapsed into ConnectionFailedSSL/StartFailedSSL. The auth/general split is only exposed for _on_tls_failure where the connection was already established and the distinction is more actionable (the application may want to report "certificate invalid" vs "protocol error" to the user differently).

What This Does NOT Include

• OS errno: With Happy Eyeballs, multiple connection attempts fail with potentially different errors — reporting a single errno is ambiguous (first? last? all of them?). The categorical approach avoids this complexity entirely.
• Detailed SSL error strings: Would require changes to the ssl package.
• DNS error detail: pony_os_connect_tcp returns a count, not an error code. Specific DNS errors (NXDOMAIN, SERVFAIL, timeout) would require ponyc runtime changes.
• Per-attempt failure information: Happy Eyeballs tries multiple connections; this design reports only the overall outcome.

These could be added in future iterations by changing the primitives to classes that carry data, though that would be another breaking change.

Implementation Sketch

Two new internal fields on TCPConnection:

• _had_inflight: Bool — set when pony_os_connect_tcp returns > 0, used to distinguish DNS from TCP failure.
• _ssl_auth_failed: Bool — set in _ssl_poll() when SSLAuthFail is detected, before the hard_close() call. Only consulted in the _tls_upgrade path of hard_close() where _on_tls_failure fires; for initial SSL connections, auth and general failures are both reported as ConnectionFailedSSL/StartFailedSSL.

Each callback call site reads the appropriate fields to determine the reason before invoking the callback.

[SeanTAllen]

Implemented in PR #202 (merged). The implementation matched the design exactly — three type aliases (ConnectionFailureReason, StartFailureReason, TLSFailureReason), two internal tracking fields (_had_inflight, _ssl_auth_failed), and reason parameters on all four callback signatures.