Module udp 

Pure sans-io UDP load-balancing core.

This module is the pure heart of the UDP datapath (issue #1273). It owns admission, the virtual 4-tuple flow table, the three-knob teardown state-machine, the LB-selection request protocol, and a single-deadline timer scheduler that revalidates flow deadlines on expiry. It performs no I/O: there is no socket, no Instant::now() / SystemTime, no rand, and no Arc<Mutex>. Time is injected as now: Instant parameters; the hash seed is injected at construction. The single admission copy the design allows materialises the borrowed recv buffer into an owned Vec<u8> (Transmit::payload).

The I/O shell (crate::udp) owns every syscall, the buffer pool, the timer wheel, the connected per-flow upstream sockets, the BackendMap, health checks and metrics. It drives this core through ManagerInput / Output.

Two-level split (mirrors the H2 ConnectionH2 / Context split in protocol/mux/):

• manager::UdpManager: flow table + admission + cap/shedding
  • flow-key extraction + LB request + timer scheduling.
• flow::UdpFlow: per-admitted-flow teardown counters, idle / lifetime deadlines, PPv2 bookkeeping, chosen backend, forward/return decisions, and a timer_gen refresh counter.

Long-form lifecycle (flow state machine, NAT return, teardown, hardening): lib/src/protocol/udp/LIFECYCLE.md.

Re-exports

pub use crate::protocol::udp::flow::CloseReason;

pub use crate::protocol::udp::flow::UdpFlow;

pub use crate::protocol::udp::manager::FlowKeyExtractor;

pub use crate::protocol::udp::manager::SourceTupleExtractor;

pub use crate::protocol::udp::manager::UdpManager;

Modules

flow

Per-flow UDP state machine (sans-io).

manager

The sans-io UdpManager: admission, flow table, LB request, timers.

proxy_protocol

Pure PROXY-protocol-v2 DGRAM header builder.

Structs

ClusterConfig

Per-cluster knobs the shell binds to a listener’s flows. Mirrors the UdpClusterConfig proto but stays in pure-core terms. Defaults match the proto defaults.

FlowKey

The virtual flow key extracted from a client datagram. The default SourceTupleExtractor keys on the real (pre-NAT) client source address, IP and port, whatever the cluster’s affinity key: one client socket is one flow with one connected upstream socket, so every backend reply returns to the socket it answers. affinity_key only feeds backend selection (the affinity hash), where SOURCE_IP makes every port of one IP land on the same backend (#1732). Other extractors may key differently — the trait is the only seam — but the 4-tuple impl is the only one in scope.

Transmit

An owned datagram ready to be written by the shell. payload is the single admission copy (Vec<u8>); for the first upstream datagram of a PPv2 flow the core has already prepended the v2 DGRAM header, so the shell writes payload verbatim. segment_size reserves room for a future GSO/GRO fast path and is None in phase 1.

Enums

ConfigEvent

Control-plane events the shell feeds the manager via ManagerInput::Config. Additive; an unknown event must never panic.

DropReason

Why a datagram was dropped. Maps onto udp.datagrams.dropped by-reason.

ManagerInput

Inputs the shell feeds into the manager. Borrows the recv buffer; the core copies into an owned Vec<u8> only on admission.

MetricEvent

Metric events the core asks the shell to record. The shell owns the incr!/count!/gauge!/time! macros (lib/src/metrics/).

Output

Outputs the manager emits; the shell drains them via poll_output until None. The shell owns the actual syscalls and timer wheel.

Traits

BackendSource

The backend set the manager selects from, borrowed from the embedder at the one point selection happens.

Type Aliases

BackendId

Backend identifier, mirroring sozu_command::state’s string backend ids and Backend::backend_id in lib/src/backends.rs.

FlowId

Slab index of an admitted flow. Stable for the flow’s lifetime; reused after close. The shell maps upstream_token -> FlowId for the NAT return path.