Module session 

Phantom Transport - Session Management

Virtual association that persists across IP changes. Manages streams, encryption state, and multi-path scheduling.

Structs

BandwidthSnapshot

Read-only snapshot of the session’s pacing / bandwidth state (Phase 2.6). Returned by Session::bandwidth_snapshot for telemetry / debugging without exposing the mutable estimator.

CryptoState

Crypto state for session encryption.

Session

Session - virtual association between two endpoints

Enums

SessionState

Session state machine

Constants

MAX_REKEY_CATCHUP

How many epochs the receive path will catch up in one packet when accepting an authenticated forward rekey (C1). A small bound caps the HKDF work an attacker can force per spoofed packet (each step is a trial that commits nothing unless AEAD verifies) while comfortably absorbing the small epoch divergence that arises when both directions rekey at slightly different cadences. A gap larger than this is rejected; over a reliable transport the sender retransmits at the then-current epoch, so no data is lost. In practice (production REKEY_SOFT_LIMIT of 2^47) the gap is essentially always 0 or 1.

REKEY_SOFT_LIMIT

Soft high-watermark for automatic mid-session rekey (C1). Once a direction’s AEAD invocation count crosses this, the data pump rotates to a fresh key before the hard AEAD_MAX_INVOCATIONS ceiling (Invariant 8) so a long-lived session ratchets keys instead of failing with NonceExhausted.

SEQ_REKEY_WATERMARK

Per-stream sequence-space high-watermark that forces a mid-session rekey (C1). The AEAD nonce is (epoch, stream_id, sequence, path_id); sequence is a per-stream u32 that wraps at 2^32. A single hot stream would wrap — reusing a nonce under a fixed key (the Forbidden Attack on AES-GCM) — long before the direction-wide REKEY_SOFT_LIMIT (2^47) could fire. So once any stream’s sequence advances this far within the current epoch, the send path forces a rekey: the epoch bump gives every subsequent packet a fresh nonce prefix, and no stream can traverse the full 2^32 sequence space within a single epoch. 2^31 leaves a full 2^31 of headroom below the wrap to absorb reordered / in-flight packets from the old epoch. Tests lower it via Session::set_seq_rekey_watermark.