nquic_path (nquic v1.0.0)

Path validation for QUIC connection migration (RFC 9000 Section 9).

Pure-functional module operating on #path_state{}. Handles peer address change detection, PATH_CHALLENGE/PATH_RESPONSE tracking, and anti-amplification limits on new paths. All state lives in the connection's #conn_state{} record; this module provides the logic without owning any processes.

Summary

Types

state()

Functions

detect_peer_change/2

Detect if the source address of a received packet differs from the current peer.

get_previous_peer/1

Return the previous peer address (for fallback on validation failure).

initiate_validation(PS, NewPeer)

Initiate path validation by generating an 8-byte challenge. Stores the challenge data and candidate address. Returns the updated path state and a PATH_CHALLENGE frame to send to the new address.

is_nat_rebinding/1

True if the migration is a likely NAT rebinding: same IP, different port. When true, callers should skip CC/RTT reset since the underlying network path has not changed (RFC 9000 Section 9.3.1).

is_validated/1

True if the current path has been validated.

is_validating/1

True if a path validation is currently in progress.

new(Peer)

Create a new path state with the given initial peer address.

on_response/2

Process a PATH_RESPONSE. If the response data matches the pending challenge, the path is validated. Otherwise the state is unchanged.

on_timeout/1

Handle path validation timeout. Retries up to 3 times with a fresh challenge. After 3 retries, returns failed so the caller can revert to the previous peer.

Types

state()

-type state() ::
          #path_state{peer :: nquic_socket:sockaddr() | undefined,
                      previous_peer :: nquic_socket:sockaddr() | undefined,
                      pending_challenge :: binary() | undefined,
                      challenge_sent_time :: non_neg_integer(),
                      challenge_retries :: non_neg_integer(),
                      path_validated :: boolean(),
                      new_path_bytes_sent :: non_neg_integer(),
                      new_path_bytes_received :: non_neg_integer()}.

Functions

detect_peer_change/2

-spec detect_peer_change(state(), nquic_socket:sockaddr()) -> unchanged | {changed, state()}.

Detect if the source address of a received packet differs from the current peer.

Returns unchanged when the addresses match or {changed, UpdatedPathState} when the source differs. A previously-undefined peer is treated as a first-time set rather than a change.

get_previous_peer/1

-spec get_previous_peer(state()) -> nquic_socket:sockaddr() | undefined.

Return the previous peer address (for fallback on validation failure).

initiate_validation(PS, NewPeer)

-spec initiate_validation(state(), nquic_socket:sockaddr()) ->
                             {state(), #path_challenge{data :: binary()}}.

Initiate path validation by generating an 8-byte challenge. Stores the challenge data and candidate address. Returns the updated path state and a PATH_CHALLENGE frame to send to the new address.

is_nat_rebinding/1

-spec is_nat_rebinding(state()) -> boolean().

True if the migration is a likely NAT rebinding: same IP, different port. When true, callers should skip CC/RTT reset since the underlying network path has not changed (RFC 9000 Section 9.3.1).

is_validated/1

-spec is_validated(state()) -> boolean().

True if the current path has been validated.

is_validating/1

-spec is_validating(state()) -> boolean().

True if a path validation is currently in progress.

new(Peer)

-spec new(nquic_socket:sockaddr() | undefined) -> state().

Create a new path state with the given initial peer address.

on_response/2

-spec on_response(state(), binary()) -> {validated, state()} | {mismatch, state()}.

Process a PATH_RESPONSE. If the response data matches the pending challenge, the path is validated. Otherwise the state is unchanged.

on_timeout/1

-spec on_timeout(state()) -> {retry, state(), #path_challenge{data :: binary()}} | {failed, state()}.

Handle path validation timeout. Retries up to 3 times with a fresh challenge. After 3 retries, returns failed so the caller can revert to the previous peer.