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 with generation tokens. 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/):

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

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; with_port distinguishes the 2-tuple (source IP only) from the 4-tuple (source IP + port). 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.

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.