Struct UdpClientTransport 

pub struct UdpClientTransport { /* private fields */ }

Available on crate feature std and non-WebAssembly only.

Implementations

impl UdpClientTransport

pub async fn connect(server: SocketAddr) -> Result<Self, CoreError>

Bind a fresh UNCONNECTED UDP socket for talking to server, choosing a random lifetime connection-ID. The socket is left unconnected (no socket.connect) so the client can recv_from any source — the precondition for hearing, and later following, a server that migrates to a new address. Datagrams are sent with send_to(server_addr).

pub async fn migrate_to( &self, new_local_addr: SocketAddr, ) -> Result<(), CoreError>

Rebind to a fresh local socket and route subsequent traffic through it (Phase 4 / P4.2b — embedder-triggered migration). Best-effort and non-blocking on validation: it binds a fresh unconnected socket (sends still send_to the tracked server_addr), then atomically swaps it in as the active socket while KEEPING the old one for the overlap (the recv loop listens on both until the new path shows life, then drops the old — broken-rebind safety / D7). Subsequent app data + L1 retransmits go out the new socket, so the server detects the new source (P4.1) and challenges → validates → swaps its peer. The caller is responsible for bumping the session send path_id (Session::next_migration_path_id).

A bind/connect failure returns Err WITHOUT touching the active socket, so a migration to a dead/invalid address never tears the session down — the session keeps running on the old socket.

Typed core of the migration; the SocketAddr-free SessionTransport::migrate trait entry parses a String and delegates here.

Trait Implementations

impl SessionTransport for UdpClientTransport

async fn migrate(&self, local_addr: String) -> Result<(), CoreError>

SocketAddr-free trait entry for connection migration (Phase 4 / P4.2c). Parses the embedder-supplied local bind address and delegates to the typed migrate_to. A malformed address is a clean Err that leaves the session on its existing socket (best-effort, never fatal).

async fn send_bytes(&self, data: &[u8]) -> Result<(), CoreError>

Send raw bytes to the peer.

async fn recv_bytes(&self) -> Result<Bytes, CoreError>

Receive the next message from the peer. The returned Bytes is a refcounted view over an opaque buffer; subsequent clone()s are cheap.

fn set_frame_phase(&self, phase: FramePhase)

Move the transport to a new FramePhase, adjusting the receive frame-size cap (WIRE-001). Default no-op — transports that do not length-prefix / buffer, or are inherently bounded, need not implement it. Called once by the session machinery at the handshake → data-pump boundary. Adding this defaulted method is source-compatible for every existing impl.

fn set_outbound_cid(&self, cid: [u8; 8])

Stamp this transport’s outbound routing CID (ε / WIRE v5). Called once by the session machinery at the handshake → data-pump boundary with the session’s current_outbound_cid() (the rotating CID_0), switching the transport off the bootstrap ConnId onto the chain. Default no-op — socket-routed transports (TCP / WebSocket / WASI / Embedded) carry no on-wire CID and ignore it. Source-compatible for every existing impl.

fn confirm_authenticated_source(&self)

Commit the most-recently-received frame’s source as the migration candidate — call ONLY from the post-decrypt path, i.e. once that frame has been AEAD-verified (M-1). On the address-aware UDP server this is the migration-integrity fix: the candidate (and hence the server’s PATH_CHALLENGE target) is only ever an AEAD-authenticated source, so a spoofed CID-matched datagram (which never decrypts) cannot clobber the candidate slot and misdirect / stall a legitimate migration. SocketAddr-free — the address stays inside the concrete transport. Default no-op for transports without migration.

fn has_migration_candidate(&self) -> bool

Whether the transport has observed an unvalidated candidate source for this session — a connection-migration signal (Phase 4). Only an address-aware transport (the UDP server) ever returns true; stream transports (TCP / WebSocket / WASI / Embedded) have no migration and use the default false. Deliberately SocketAddr-free so the generic data pump that calls it stays no_std-clean (std::net::SocketAddr does not exist in core/alloc); the candidate address is held inside the concrete transport.

async fn send_to_candidate(&self, data: &[u8]) -> Result<bool, CoreError>

Send data — an already-encrypted PATH_VALIDATION challenge built by the session — to the transport’s internally-tracked candidate source, distinct from the established peer, under the transport’s own anti-amplification cap (RFC 9000 §8.2). Returns Ok(true) if a candidate existed and the send was within budget, Ok(false) otherwise (no candidate, or the 3× cap was hit). Default (non-address transports): a no-op Ok(false). The candidate address never crosses this boundary, keeping the trait no_std-safe.

fn promote_candidate(&self) -> bool

Promote the migration candidate to the established peer (Phase 4, the switch): after the candidate’s path validates, subsequent app data and retransmits go to it instead of the old peer. Returns true if a candidate was promoted. Default no-op (false) for transports without migration. SocketAddr-free — the address is internal to the concrete transport.

fn migrate_server( &self, _local_addr: String, ) -> impl Future<Output = Result<(), CoreError>> + Send

Migrate the server side of this transport to a new local send address — the mirror of migrate for the accepting peer. The server binds a fresh local socket, sends subsequent server→client datagrams from it (so the client sees a new s2c source and follows it), and receives on it too (so once the client switches its send target the c2s frames are delivered transparently). The address crosses as a String to keep the trait SocketAddr-free / no_std-clean. Best-effort: a parse / bind failure returns Err and the session keeps running on the old socket. Default no-op Ok(()) — only the native UDP server implements it. Kept distinct from migrate so the FFI-exported client migrate() cannot trigger a server migration.