-module(nquic_error).
-moduledoc """
Canonical error taxonomy for `nquic`.
Every error that crosses the public surface of `nquic` or `nquic_lib`
is shaped by this module so callers can pattern-match exhaustively on
`nquic:error_reason()/0`.
Two responsibilities:
* Constructors: `closed/0`, `timeout/1`, `transport/1`, `tls/1`,
`application/2`, `protocol/1`, `flow_control/1`, `opts/1`,
`connect/1`, `listen/1` return canonical `{error, error_reason()}`
tuples. Use them at sites that already know which bucket the term
belongs to.
* Mappers: `from_socket/2`, `from_tls_alert/1`, `from_handshake/1`,
`from_connection_close/1`, `wrap/1`, `wrap_result/1` translate raw
upstream shapes (POSIX atoms, TLS alerts, `#connection_close{}`
records, internal atoms) into the canonical sum.
`wrap/1` is the single funnel for unknown error terms at the public
boundary; already-canonical values pass through unchanged.
## Error-handling convention contract
`t:nquic:error_reason/0` is a **closed**, `{error, _}`-wrapped,
category-classified tagged union. The *supported* way to interrogate
a value is the trio:
* `category/1`: one atom from the small closed set
`closed | timeout | transport | tls | application | protocol |
flow_control | opts | connect | listen` (never crashes on a
canonical value).
* `is_retryable/1`: `boolean()`.
* `format/1`: human-readable `iodata()`.
Callers should classify and branch via these functions, **not** by
pattern-matching the inner shape (which may gain arms within a
category without a major version bump; the category set will not).
This is the same convention `nhttp_error` follows
(`{error, {category(), reason()}}` plus its own
`category/1` / `is_retryable/1` / `format/1`). The two taxonomies are
therefore *structurally parallel by convention*, not coupled: nquic
ships **no** adapter and depends on no HTTP library. A consumer that
needs to project nquic failures into its own error vocabulary writes
a small total adapter over `category/1` **at its own boundary**. nquic
deliberately does not know nhttp exists, so it stays reusable by any
non-HTTP QUIC consumer and independently releasable.
""".
-include("nquic_frame.hrl").
%%%-----------------------------------------------------------------------------
%% EXPORTS - CONSTRUCTORS
%%%-----------------------------------------------------------------------------
-export([
application/2,
closed/0,
connect/1,
flow_control/1,
listen/1,
opts/1,
protocol/1,
timeout/1,
tls/1,
transport/1
]).
%%%-----------------------------------------------------------------------------
%% EXPORTS - MAPPERS
%%%-----------------------------------------------------------------------------
-export([
from_connection_close/1,
from_handshake/1,
from_socket/2,
from_tls_alert/1,
wrap/1,
wrap_reason/1,
wrap_result/1
]).
%%%-----------------------------------------------------------------------------
%% EXPORTS - HELPERS
%%%-----------------------------------------------------------------------------
-export([
category/1,
format/1,
is_retryable/1
]).
%%%-----------------------------------------------------------------------------
%% TYPES
%%%-----------------------------------------------------------------------------
-export_type([
any_reason/0,
application_reason/0,
category/0,
error_reason/0,
flow_control_reason/0,
opts_reason/0,
protocol_reason/0,
timeout_phase/0,
tls_reason/0,
transport_reason/0
]).
-doc "Phase tag for `{timeout, Phase}` outcomes.".
-type timeout_phase() :: handshake | idle | recv | send | accept.
-doc "Transport-domain error reasons (peer CONNECTION_CLOSE 0x1c or local I/O).".
-type transport_reason() ::
no_error
| internal_error
| connection_refused
| flow_control_error
| stream_limit_error
| stream_state_error
| final_size_error
| frame_encoding_error
| transport_parameter_error
| connection_id_limit_error
| protocol_violation
| invalid_token
| application_error
| crypto_buffer_exceeded
| key_update_error
| aead_limit_reached
| no_viable_path
| crypto_error
| idle_timeout
| stateless_reset
| version_negotiation
| closed_by_peer
| {posix, inet:posix()}
| {peer_close, non_neg_integer(), binary()}.
-doc "TLS-layer error reasons (peer alerts or local handshake validation).".
-type tls_reason() ::
unexpected_message
| handshake_failure
| bad_certificate
| unsupported_certificate
| certificate_revoked
| certificate_expired
| certificate_unknown
| illegal_parameter
| unknown_ca
| access_denied
| decode_error
| decrypt_error
| protocol_version
| insufficient_security
| internal_error
| inappropriate_fallback
| user_canceled
| missing_extension
| unsupported_extension
| unrecognized_name
| bad_certificate_status_response
| unknown_psk_identity
| certificate_required
| no_application_protocol
| no_psk
| no_matching_psk
| no_static_key
| no_peercert
| binder_mismatch
| binder_verification_failed
| psk_identity_binder_mismatch
| client_finished_verification_failed
| malformed_finished
| malformed_new_session_ticket
| not_new_session_ticket
| invalid_ticket_cipher
| invalid_ticket_format
| ticket_decrypt_failed
| ticket_too_short
| {bad_cert, dynamic()}
| {hostname_mismatch, binary()}
| {alert, atom()}.
-doc "Protocol-level errors: wire format, parser, RFC 9000 violations.".
-type protocol_reason() ::
protocol_violation
| frame_encoding_error
| packet_too_short
| integrity_check_failed
| final_size_error
| migration_disabled
| duplicate_parameter
| truncated_param_value
| transport_parameter_error
| no_available_cids
| retry_token_too_short
| invalid_retry_token
| datagrams_not_negotiated
| datagram_too_large
| invalid_packet
| incomplete_binary
| key_update_pending
| no_initial_keys
| no_zero_rtt_keys
| no_probe_needed
| overflow
| stream_state_error
| decrypt_failed
| {transport_parameter_error, atom()}
| {processing_failed, dynamic()}
| {encoding_failed, dynamic()}
| {flight_generation_failed, dynamic()}
| {decrypt_failed, dynamic()}.
-doc "Flow control or congestion-control blocking outcomes.".
-type flow_control_reason() ::
flow_control_error
| stream_limit_error
| congestion_control_blocked
| eagain
| partial_send
| stream_blocked.
-doc "Options / configuration / API-misuse errors.".
-type opts_reason() ::
not_owner
| not_found
| not_connected
| not_established
| not_writable
| unknown_request
| unknown_stream
| invalid_stream
| invalid_stream_id
| stream_not_found
| stream_closed
| stream_reset
| empty
| no_data
| sups_not_ready
| draining
| ctx_requires_wait
| not_supported_in_mode
| {missing_option, atom()}
| {misplaced_option, atom()}
| {certfile, atom()}
| {unsupported_cipher_suite, binary() | atom()}
| {already_started, pid()}.
-doc "Application-domain close reason carrying peer error code and phrase.".
-type application_reason() :: {non_neg_integer(), binary()}.
-doc """
Closed error taxonomy returned by every public function. The outer arm
classifies the failure; the inner value carries detail without growing
the union.
""".
-type error_reason() ::
closed
| fin
| {timeout, timeout_phase()}
| {transport, transport_reason()}
| {tls, tls_reason()}
| {application, non_neg_integer(), binary()}
| {protocol, protocol_reason()}
| {flow_control, flow_control_reason()}
| {opts, opts_reason()}
| {connect, inet:posix() | atom()}
| {listen, inet:posix() | atom()}.
-doc """
Wide internal error type carried by modules that have not yet been
funnelled through a constructor. Callers at the public boundary must
pass these through `wrap/1` before returning to the user.
""".
-type any_reason() ::
error_reason()
| atom()
| tuple()
| binary()
| map()
| list()
| integer().
-doc "Category tag returned by `category/1`, useful for telemetry.".
-type category() ::
closed
| timeout
| transport
| tls
| application
| protocol
| flow_control
| opts
| connect
| listen.
%%%-----------------------------------------------------------------------------
%% CONSTRUCTORS
%%%-----------------------------------------------------------------------------
-doc "Application-domain CONNECTION_CLOSE from the peer.".
-spec application(non_neg_integer(), binary()) -> {error, error_reason()}.
application(Code, Reason) when is_integer(Code), Code >= 0, is_binary(Reason) ->
{error, {application, Code, Reason}}.
-doc "Terminal connection state.".
-spec closed() -> {error, error_reason()}.
closed() ->
{error, closed}.
-doc "Client-side DNS / socket open / connect failure (POSIX atom).".
-spec connect(inet:posix() | atom()) -> {error, error_reason()}.
connect(Reason) when is_atom(Reason) ->
{error, {connect, Reason}}.
-doc "Local flow control / congestion blocking.".
-spec flow_control(flow_control_reason()) -> {error, error_reason()}.
flow_control(Reason) ->
{error, {flow_control, Reason}}.
-doc "Server-side socket bind / listen failure (POSIX atom).".
-spec listen(inet:posix() | atom()) -> {error, error_reason()}.
listen(Reason) when is_atom(Reason) ->
{error, {listen, Reason}}.
-doc "Options / configuration / API-misuse error.".
-spec opts(opts_reason()) -> {error, error_reason()}.
opts(Reason) ->
{error, {opts, Reason}}.
-doc "Wire-format / protocol violation detected locally.".
-spec protocol(protocol_reason()) -> {error, error_reason()}.
protocol(Reason) ->
{error, {protocol, Reason}}.
-doc "Timeout in a named phase.".
-spec timeout(timeout_phase()) -> {error, error_reason()}.
timeout(Phase) when
Phase =:= handshake;
Phase =:= idle;
Phase =:= recv;
Phase =:= send;
Phase =:= accept
->
{error, {timeout, Phase}}.
-doc "TLS-layer error: peer alert or local handshake validation.".
-spec tls(tls_reason()) -> {error, error_reason()}.
tls(Reason) ->
{error, {tls, Reason}}.
-doc "Transport-layer error: peer CONNECTION_CLOSE (0x1c) or local I/O.".
-spec transport(transport_reason()) -> {error, error_reason()}.
transport(Reason) ->
{error, {transport, Reason}}.
%%%-----------------------------------------------------------------------------
%% MAPPERS
%%%-----------------------------------------------------------------------------
-doc """
Map a peer-sent `#connection_close{}` record to a canonical
`{transport, _}` or `{application, Code, Reason}` error.
""".
-spec from_connection_close(#connection_close{}) -> {error, error_reason()}.
from_connection_close(#connection_close{is_application = true, error_code = Code, reason_phrase = R}) ->
{error, {application, Code, R}};
from_connection_close(#connection_close{error_code = Code, reason_phrase = R}) ->
{error, {transport, {peer_close, Code, R}}}.
-doc """
Map a TLS-handshake-side internal failure (no-PSK, binder mismatch,
malformed finished, ...) to a canonical `{tls, _}` error.
""".
-spec from_handshake(atom() | tuple()) -> {error, error_reason()}.
from_handshake({bad_cert, _} = Reason) ->
{error, {tls, Reason}};
from_handshake({hostname_mismatch, _} = Reason) ->
{error, {tls, Reason}};
from_handshake({Tag, _} = Reason) when is_atom(Tag) ->
{error, {tls, Reason}};
from_handshake(Reason) when is_atom(Reason) ->
{error, {tls, Reason}}.
-doc """
Map a raw POSIX atom from a `socket` / `inet` call to the matching
canonical bucket according to which operation produced it.
`Origin` is one of `connect`, `listen`, `transport`.
""".
-spec from_socket(connect | listen | transport, inet:posix() | atom()) ->
{error, error_reason()}.
from_socket(connect, Reason) when is_atom(Reason) ->
{error, {connect, Reason}};
from_socket(listen, Reason) when is_atom(Reason) ->
{error, {listen, Reason}};
from_socket(transport, Reason) when is_atom(Reason) ->
{error, {transport, {posix, Reason}}}.
-doc """
Map a TLS alert atom or `{tls_alert, _}` record to a canonical
`{tls, _}` error.
""".
-spec from_tls_alert(atom() | tuple()) -> {error, error_reason()}.
from_tls_alert({tls_alert, Alert}) when is_atom(Alert) ->
{error, {tls, Alert}};
from_tls_alert({tls_alert, Alert, _Reason}) when is_atom(Alert) ->
{error, {tls, Alert}};
from_tls_alert(Alert) when is_atom(Alert) ->
{error, {tls, Alert}}.
-doc """
Normalise any term into the canonical taxonomy. Already-canonical values
pass through unchanged.
""".
-spec wrap(term()) -> {error, error_reason()}.
wrap({error, Reason}) ->
wrap_reason(Reason);
wrap(Reason) ->
wrap_reason(Reason).
-doc """
Wrap an `{ok, _} | {error, _}` result so the error arm is canonical.
The `ok` and `{ok, _}` arms pass through unchanged.
""".
-spec wrap_result(ok | {ok, T} | {error, term()}) ->
ok | {ok, T} | {error, error_reason()}.
wrap_result(ok) ->
ok;
wrap_result({ok, _} = Ok) ->
Ok;
wrap_result({error, _} = Error) ->
wrap(Error).
%%%-----------------------------------------------------------------------------
%% HELPERS
%%%-----------------------------------------------------------------------------
-doc "Category tag for telemetry / log fields.".
-spec category(error_reason()) -> category().
category(closed) -> closed;
category(fin) -> closed;
category({timeout, _}) -> timeout;
category({transport, _}) -> transport;
category({tls, _}) -> tls;
category({application, _, _}) -> application;
category({protocol, _}) -> protocol;
category({flow_control, _}) -> flow_control;
category({opts, _}) -> opts;
category({connect, _}) -> connect;
category({listen, _}) -> listen.
-doc "Human-readable rendering for log lines.".
-spec format(error_reason()) -> iolist().
format(closed) ->
"connection closed";
format(fin) ->
"stream FIN received; end of stream";
format({timeout, Phase}) ->
io_lib:format("timeout in ~p phase", [Phase]);
format({transport, {peer_close, Code, <<>>}}) ->
io_lib:format("peer closed: transport error code ~b", [Code]);
format({transport, {peer_close, Code, Reason}}) ->
io_lib:format("peer closed: transport error code ~b (~s)", [Code, Reason]);
format({transport, {posix, P}}) ->
io_lib:format("transport I/O error: ~p", [P]);
format({transport, R}) ->
io_lib:format("transport error: ~p", [R]);
format({tls, R}) ->
io_lib:format("TLS error: ~p", [R]);
format({application, Code, <<>>}) ->
io_lib:format("application close: code ~b", [Code]);
format({application, Code, Reason}) ->
io_lib:format("application close: code ~b (~s)", [Code, Reason]);
format({protocol, R}) ->
io_lib:format("protocol error: ~p", [R]);
format({flow_control, R}) ->
io_lib:format("flow control: ~p", [R]);
format({opts, R}) ->
io_lib:format("options error: ~p", [R]);
format({connect, R}) ->
io_lib:format("connect failed: ~p", [R]);
format({listen, R}) ->
io_lib:format("listen failed: ~p", [R]).
-doc "Whether the caller may sensibly retry after this error.".
-spec is_retryable(error_reason()) -> boolean().
is_retryable(closed) -> false;
is_retryable(fin) -> false;
is_retryable({timeout, idle}) -> true;
is_retryable({timeout, recv}) -> true;
is_retryable({timeout, _}) -> false;
is_retryable({transport, no_error}) -> true;
is_retryable({transport, version_negotiation}) -> true;
is_retryable({transport, stateless_reset}) -> true;
is_retryable({transport, idle_timeout}) -> true;
is_retryable({transport, {posix, etimedout}}) -> true;
is_retryable({transport, _}) -> false;
is_retryable({tls, _}) -> false;
is_retryable({application, _, _}) -> false;
is_retryable({protocol, _}) -> false;
is_retryable({flow_control, eagain}) -> true;
is_retryable({flow_control, congestion_control_blocked}) -> true;
is_retryable({flow_control, stream_blocked}) -> true;
is_retryable({flow_control, _}) -> false;
is_retryable({opts, _}) -> false;
is_retryable({connect, econnrefused}) -> true;
is_retryable({connect, etimedout}) -> true;
is_retryable({connect, ehostunreach}) -> true;
is_retryable({connect, enetunreach}) -> true;
is_retryable({connect, _}) -> false;
is_retryable({listen, _}) -> false.
%%%-----------------------------------------------------------------------------
%% INTERNAL
%%%-----------------------------------------------------------------------------
-spec bucket_for_atom(atom()) ->
closed
| {timeout, timeout_phase()}
| flow_control
| protocol
| tls
| transport
| opts
| connect
| listen
| unknown.
%% closed bucket
bucket_for_atom(closed) -> closed;
bucket_for_atom(closed_by_peer) -> closed;
%% timeout bucket
bucket_for_atom(timeout) -> {timeout, recv};
bucket_for_atom(send_timeout) -> {timeout, send};
%% transport bucket
bucket_for_atom(no_error) -> transport;
bucket_for_atom(internal_error) -> transport;
bucket_for_atom(connection_refused) -> transport;
bucket_for_atom(connection_id_limit_error) -> transport;
bucket_for_atom(invalid_token) -> transport;
bucket_for_atom(application_error) -> transport;
bucket_for_atom(crypto_buffer_exceeded) -> transport;
bucket_for_atom(key_update_error) -> transport;
bucket_for_atom(aead_limit_reached) -> transport;
bucket_for_atom(no_viable_path) -> transport;
bucket_for_atom(crypto_error) -> transport;
bucket_for_atom(idle_timeout) -> transport;
bucket_for_atom(stateless_reset) -> transport;
bucket_for_atom(version_negotiation) -> transport;
%% flow control bucket
bucket_for_atom(flow_control_error) -> flow_control;
bucket_for_atom(stream_limit_error) -> flow_control;
bucket_for_atom(congestion_control_blocked) -> flow_control;
bucket_for_atom(eagain) -> flow_control;
bucket_for_atom(partial_send) -> flow_control;
bucket_for_atom(stream_blocked) -> flow_control;
%% protocol bucket
bucket_for_atom(protocol_violation) -> protocol;
bucket_for_atom(frame_encoding_error) -> protocol;
bucket_for_atom(packet_too_short) -> protocol;
bucket_for_atom(integrity_check_failed) -> protocol;
bucket_for_atom(final_size_error) -> protocol;
bucket_for_atom(migration_disabled) -> protocol;
bucket_for_atom(duplicate_parameter) -> protocol;
bucket_for_atom(truncated_param_value) -> protocol;
bucket_for_atom(transport_parameter_error) -> protocol;
bucket_for_atom(no_available_cids) -> protocol;
bucket_for_atom(retry_token_too_short) -> protocol;
bucket_for_atom(invalid_retry_token) -> protocol;
bucket_for_atom(datagrams_not_negotiated) -> protocol;
bucket_for_atom(datagram_too_large) -> protocol;
bucket_for_atom(invalid_packet) -> protocol;
bucket_for_atom(incomplete_binary) -> protocol;
bucket_for_atom(key_update_pending) -> protocol;
bucket_for_atom(no_initial_keys) -> protocol;
bucket_for_atom(no_zero_rtt_keys) -> protocol;
bucket_for_atom(no_probe_needed) -> protocol;
bucket_for_atom(overflow) -> protocol;
bucket_for_atom(stream_state_error) -> protocol;
bucket_for_atom(decrypt_failed) -> protocol;
%% tls bucket
bucket_for_atom(no_psk) -> tls;
bucket_for_atom(no_matching_psk) -> tls;
bucket_for_atom(no_static_key) -> tls;
bucket_for_atom(no_peercert) -> tls;
bucket_for_atom(binder_mismatch) -> tls;
bucket_for_atom(binder_verification_failed) -> tls;
bucket_for_atom(psk_identity_binder_mismatch) -> tls;
bucket_for_atom(client_finished_verification_failed) -> tls;
bucket_for_atom(malformed_finished) -> tls;
bucket_for_atom(malformed_new_session_ticket) -> tls;
bucket_for_atom(not_new_session_ticket) -> tls;
bucket_for_atom(invalid_ticket_cipher) -> tls;
bucket_for_atom(invalid_ticket_format) -> tls;
bucket_for_atom(ticket_decrypt_failed) -> tls;
bucket_for_atom(ticket_too_short) -> tls;
bucket_for_atom(unexpected_message) -> tls;
bucket_for_atom(handshake_failure) -> tls;
bucket_for_atom(bad_certificate) -> tls;
bucket_for_atom(unsupported_certificate) -> tls;
bucket_for_atom(certificate_revoked) -> tls;
bucket_for_atom(certificate_expired) -> tls;
bucket_for_atom(certificate_unknown) -> tls;
bucket_for_atom(illegal_parameter) -> tls;
bucket_for_atom(unknown_ca) -> tls;
bucket_for_atom(access_denied) -> tls;
bucket_for_atom(decode_error) -> tls;
bucket_for_atom(decrypt_error) -> tls;
bucket_for_atom(protocol_version) -> tls;
bucket_for_atom(insufficient_security) -> tls;
bucket_for_atom(inappropriate_fallback) -> tls;
bucket_for_atom(user_canceled) -> tls;
bucket_for_atom(missing_extension) -> tls;
bucket_for_atom(unsupported_extension) -> tls;
bucket_for_atom(unrecognized_name) -> tls;
bucket_for_atom(bad_certificate_status_response) -> tls;
bucket_for_atom(unknown_psk_identity) -> tls;
bucket_for_atom(certificate_required) -> tls;
bucket_for_atom(no_application_protocol) -> tls;
%% opts bucket
bucket_for_atom(not_owner) -> opts;
bucket_for_atom(not_found) -> opts;
bucket_for_atom(not_connected) -> opts;
bucket_for_atom(not_established) -> opts;
bucket_for_atom(not_writable) -> opts;
bucket_for_atom(unknown_request) -> opts;
bucket_for_atom(unknown_stream) -> opts;
bucket_for_atom(invalid_stream) -> opts;
bucket_for_atom(invalid_stream_id) -> opts;
bucket_for_atom(stream_not_found) -> opts;
bucket_for_atom(stream_closed) -> opts;
bucket_for_atom(stream_reset) -> opts;
bucket_for_atom(empty) -> opts;
bucket_for_atom(no_data) -> opts;
bucket_for_atom(sups_not_ready) -> opts;
bucket_for_atom(draining) -> opts;
%% connect bucket (POSIX atoms returned from getaddr/connect/open)
bucket_for_atom(econnrefused) -> connect;
bucket_for_atom(etimedout) -> connect;
bucket_for_atom(ehostunreach) -> connect;
bucket_for_atom(enetunreach) -> connect;
bucket_for_atom(econnreset) -> connect;
bucket_for_atom(ehostdown) -> connect;
bucket_for_atom(enetdown) -> connect;
bucket_for_atom(nxdomain) -> connect;
%% listen bucket (POSIX atoms returned from bind)
bucket_for_atom(eaddrinuse) -> listen;
bucket_for_atom(eaddrnotavail) -> listen;
bucket_for_atom(eacces) -> listen;
bucket_for_atom(_) -> unknown.
-spec classify_atom(atom()) -> {error, error_reason()}.
classify_atom(Atom) ->
case bucket_for_atom(Atom) of
closed -> {error, closed};
{timeout, P} -> {error, {timeout, P}};
flow_control -> {error, {flow_control, Atom}};
protocol -> {error, {protocol, Atom}};
tls -> {error, {tls, Atom}};
transport -> {error, {transport, Atom}};
opts -> {error, {opts, Atom}};
connect -> {error, {connect, Atom}};
listen -> {error, {listen, Atom}};
unknown -> {error, {transport, {posix, Atom}}}
end.
-spec fold_opaque(term()) -> atom().
fold_opaque(A) when is_atom(A) -> A;
fold_opaque(_) -> internal_error.
-doc """
Generic dispatcher used by `wrap/1`. Exported for the rare site that
already destructured the `{error, _}` tuple and only has the payload.
""".
-spec wrap_reason(term()) -> {error, error_reason()}.
%% Already canonical pass-throughs.
wrap_reason(closed) ->
{error, closed};
wrap_reason(fin) ->
{error, fin};
wrap_reason({timeout, Phase} = E) when
Phase =:= handshake;
Phase =:= idle;
Phase =:= recv;
Phase =:= send;
Phase =:= accept
->
{error, E};
wrap_reason({transport, _} = E) ->
{error, E};
wrap_reason({tls, _} = E) ->
{error, E};
wrap_reason({application, _, _} = E) ->
{error, E};
wrap_reason({protocol, _} = E) ->
{error, E};
wrap_reason({flow_control, _} = E) ->
{error, E};
wrap_reason({opts, _} = E) ->
{error, E};
wrap_reason({connect, _} = E) ->
{error, E};
wrap_reason({listen, _} = E) ->
{error, E};
%% Connection state aliases that fold into `closed`.
wrap_reason(closed_by_peer) ->
{error, closed};
wrap_reason(not_connected) ->
{error, {opts, not_connected}};
wrap_reason(not_established) ->
{error, {opts, not_established}};
wrap_reason(draining) ->
{error, {opts, draining}};
%% Bare timeout.
wrap_reason(timeout) ->
{error, {timeout, recv}};
%% Legacy peer-close wire shapes.
wrap_reason({transport_error, Atom}) when is_atom(Atom) ->
{error, {transport, Atom}};
wrap_reason({transport_error, Code, Reason}) when is_integer(Code), is_binary(Reason) ->
{error, {transport, {peer_close, Code, Reason}}};
wrap_reason({application_error, Code, Reason}) when is_integer(Code), is_binary(Reason) ->
{error, {application, Code, Reason}};
%% TLS shapes.
wrap_reason({tls_alert, Alert}) when is_atom(Alert) ->
{error, {tls, Alert}};
wrap_reason({tls_alert, Alert, _}) when is_atom(Alert) ->
{error, {tls, Alert}};
wrap_reason({bad_cert, _} = R) ->
{error, {tls, R}};
wrap_reason({hostname_mismatch, _} = R) ->
{error, {tls, R}};
wrap_reason({unsupported_cipher_suite, _} = R) ->
{error, {opts, R}};
wrap_reason({certfile, _} = R) ->
{error, {opts, R}};
wrap_reason({missing_option, _} = R) ->
{error, {opts, R}};
wrap_reason({already_started, _} = R) ->
{error, {opts, R}};
%% Transport-parameter shapes.
wrap_reason(transport_parameter_error) ->
{error, {protocol, transport_parameter_error}};
wrap_reason({transport_parameter_error, _} = R) ->
{error, {protocol, R}};
wrap_reason({version_negotiation_error, _Atom}) ->
{error, {transport, version_negotiation}};
wrap_reason(version_negotiation) ->
{error, {transport, version_negotiation}};
wrap_reason(stateless_reset) ->
{error, {transport, stateless_reset}};
wrap_reason(idle_timeout) ->
{error, {transport, idle_timeout}};
%% Bare atoms classified by membership.
wrap_reason(Atom) when is_atom(Atom) ->
classify_atom(Atom);
%% Anything else falls into transport as opaque payload.
wrap_reason(Other) ->
{error, {transport, {posix, fold_opaque(Other)}}}.