Structured Error Types

[SeanTAllen]

Analysis of RequestError and HTTPClientError from the original design discussion (#2), with a recommendation to defer both.

Context

The original design discussion sketched two error types:

class val RequestError
  let status: U16
  let response_body: String
  let message: String

type HTTPClientError is
  ( ConnectionFailed | DNSFailed | TimeoutError | TLSError | ProtocolError )

These were shown in the context of a promise-based API pattern:

be fetch(path: String, promise: Promise[(HTTPResponse | RequestError)]) =>

Analysis

RequestError — HTTP status as error

RequestError bundles an HTTP status code with a response body and message, treating certain HTTP responses as errors. This conflicts with courier's core philosophy, documented in the design discussion:

HTTP status codes are data, not errors. A 404 response is a successful HTTP transaction — the library delivered the response. Network failures, timeouts, and protocol violations are errors.

In courier's callback model, all HTTP responses (2xx, 4xx, 5xx) flow through the same on_response() → on_body_chunk() → on_response_complete() path. The user's code decides what status codes mean in their context. A RequestError type would impose a particular interpretation (e.g., "4xx/5xx are errors") that belongs in domain libraries, not the transport layer.

Domain libraries like a GitHub API client would define their own error types that are meaningful in their context (e.g., RateLimited, NotFound, AuthenticationFailed). These are richer and more useful than a generic RequestError.

HTTPClientError — structured connection failure

HTTPClientError aims to provide structured reasons for connection failures (DNS, TCP, TLS, timeout). The current on_connection_failure() callback provides zero information about why the failure occurred.

However, lori does not expose failure reasons. The _on_connection_failure() callback takes no parameters. Internally, lori reads SO_ERROR to determine if a socket connected, but the errno is not passed to the callback. DNS failures, connection refused, timeouts, and SSL handshake failures all produce the same bare callback.

Courier cannot provide structured connection error information that lori doesn't make available. We could add courier-level tracking (e.g., knowing whether the connection was SSL-mode to distinguish "connect failure" from "possible SSL failure"), but this would be speculative rather than authoritative — we'd be guessing, not reporting.

Recommendation: Defer Both

RequestError: Does not belong in courier. It belongs in domain libraries that define what HTTP status codes mean in their context. Courier treats all HTTP responses as data, which is a deliberate architectural decision.

HTTPClientError: Cannot be meaningfully implemented without lori providing failure detail. Adding a type that wraps on_connection_failure() without adding information would be pure ceremony.

Future path for HTTPClientError: If lori adds structured failure reporting (e.g., passing an error reason to _on_connection_failure()), courier should add a corresponding structured type and update on_connection_failure() to deliver it. This would be the right time to introduce HTTPClientError or equivalent.

Future path for RequestError: Domain libraries should define their own error types. Courier could potentially provide a lightweight ResponseError pattern in the future (e.g., a helper that checks status codes), but this is convenience, not infrastructure. Defer until there are concrete domain libraries requesting it.

What This Means for the API

The error handling in courier covers the current API surface:

• ParseError (7 variants) — covers all response parsing failures
• SendRequestResult (success/closed/pending) — covers request-sending failures
• on_connection_failure() — covers connection failures (limited by lori)
• on_parse_error(ParseError) — delivers parse errors with full detail
• JsonDecodeError (proposed in the typed JSON decoding design) — covers JSON decode failures

No gap exists that can be filled without upstream changes to lori.

Action Item

File a lori issue requesting structured failure information in _on_connection_failure() (e.g., passing an error reason or errno). This is the upstream blocker for HTTPClientError in courier.

[SeanTAllen]

The lori blocker has been addressed and will be in the next release.

[SeanTAllen]

Implemented in #24.