Struct HandshakeFailure 

pub struct HandshakeFailure {
    pub code: Option<u64>,
    pub code_space: Option<CodeSpace>,
    pub tls_alert: Option<u8>,
    pub reason: String,
}

A handshake that failed, with the codes the failure carried still intact.

The reason it is a struct and not another String variant: a peer’s refusal arrives as a number, and flattening it into prose is lossy in a way that only shows up downstream. A TLS alert reaches QUIC as 0x0100 | alert, so no_application_protocol (120) is 0x178, and a caller that wants to distinguish “this relay does not speak our protocol” from “this relay’s certificate expired” (alert 45, 0x12D) was left parsing error messages for digits.

Every field is optional except reason, because not every failure has a code — a timeout and a DNS miss are real outcomes with nothing numeric in them.

Fields

code: Option<u64>

The QUIC error code, when the failure carried one.

Meaningless without code_space — the same integer says different things in the two spaces.

code_space: Option<CodeSpace>

Which space code is a number in.

tls_alert: Option<u8>

The TLS alert, when the code was a transport code in QUIC’s crypto range.

Derived and not independently sourced: QUIC has no separate field for it, and 0x0100..=0x01ff is how TLS alerts are carried.

reason: String

What the stack said, for the detail no code carries — which certificate field mismatched, when it expired, which name was expected.

Alert 42 (bad_certificate) is rustls’s catch-all, so telling an expired certificate from a name mismatch still means reading this.

Implementations

impl HandshakeFailure

pub fn transport(code: u64, reason: String) -> Self

A failure carrying a transport-space code, with any TLS alert recovered.

Prefer this over a struct literal: it is what keeps tls_alert consistent with code, and a literal can set the two independently.

pub fn application(code: u64, reason: String) -> Self

A failure carrying an application-space close code.

Never carries a TLS alert: application codes are a separate space, and the ones that happen to land in 0x0100..=0x01ff are the trap this constructor exists to close.

pub fn bare(reason: String) -> Self

A failure with nothing numeric in it — a timeout, a DNS miss, a reset.

pub fn alert_of(code: u64) -> Option<u8>

Recover the alert from a transport-space code, if it carries one.

0x0100 | alert is the mapping TLS-over-QUIC defines, so the range is exactly one byte wide and the low byte is the alert. Applying this to an application-space code is a bug — see CodeSpace.

Trait Implementations

impl Clone for HandshakeFailure

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HandshakeFailure

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for HandshakeFailure

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for HandshakeFailure

impl PartialEq for HandshakeFailure

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for HandshakeFailure