flare.quic.server

Wrap an already-bound :class:UdpSocket. Internal -- callers use :meth:bind.

Drop the listener: release every rustls session in the slab exactly once.

Each :class:_SessionSlot is a non-owning carrier; the slab itself is the unique owner of the underlying Box<Session>* allocations rustls produced via :func:_do_accept. The free routes through :meth:RustlsQuicAcceptor.free_session so Mojo's deinit rule (no sub-field access during deinit) is respected -- the acceptor borrows self (and its _lib) by reference rather than via a sub-field of the listener.

Open the UDP socket and bind it to config.host / config.port. Returns a ready-to-run listener.

If config.port == 0 the kernel picks an ephemeral port; read it back via :meth:local_addr.

Constructs the per-listener rustls QUIC acceptor from config.rustls_config at bind time so each accepted connection's TLS session is materialized against the same long-lived ServerConfig. An empty / malformed PEM does not raise here; the acceptor surfaces a NULL handle and CRYPTO bytes route through the silent-drop branch.

Return the address the UDP socket is actually bound to. After :meth:bind with config.port == 0 this reports the kernel-chosen ephemeral port.

Whether the UDP socket is bound. True for every listener returned by :meth:bind.

Number of connection slots currently allocated.

Route a single UDP datagram to the right connection slot.

Parses the first byte to pick long vs short header, extracts the Destination Connection ID, looks it up in :attr:cid_table, and either:

• Routes the datagram to the existing slot via :meth:_handle_inbound. Decryption failures are caught and converted to silent drops so a single bad sender can't poison the listener.
• Allocates a new slot for an Initial packet with an unknown DCID (the QUIC accept path -- RFC 9000 §7), then drives the same inbound path on the new connection so the first Initial advances the state machine.
• Returns -1 to drop short-header packets with unknown DCIDs (those datagrams are silently discarded).

Return the stream ids ready for handler dispatch on slot. Delegates to :meth:flare.http3.Http3Connection.take_completed_streams. Empty list if the slot is out of range or has no H3 driver attached.

Materialize the :class:flare.http.Request for (slot, stream_id). The dispatch caller invokes a Handler with this Request, then feeds the Response back through :meth:emit_http3_response.

Raises if the slot is out of range or the H3 driver does not track the stream (see :meth:flare.http3.Http3Connection.take_request for the underlying gating).

Encode response and queue it on the stream's egress for the 1-RTT drain (:meth:_drain_1rtt_coalesced), which frames it as far as flow control and the congestion window allow once the slot's 1-RTT keys are installed.

A streaming response (one carrying a body_stream chunk source) is handled incrementally: its HEADERS (and any inline body prefix) are queued now, the source is boxed on the stream's record, and :meth:pump_http3_streams pulls its body one chunk per tick. The FIN waits until the source is exhausted.

Take the response bytes queued on stream_id and not yet framed, bypassing the 1-RTT drain. Returns an empty list when nothing is queued. A finished buffered response's record is dropped; a streaming one keeps its source.

Accept the extended CONNECT request on stream_id (taken with :meth:take_http3_request): queue a 200 HEADERS and keep the stream open both ways.

Whether the request on stream_id is an extended CONNECT (RFC 9220), ready before the client ends the stream.

Whether t still carries bytes both ways: neither side has ended or reset it and its connection is up.

Queue data as one DATA frame on t; False once our side has ended or been reset (the peer having ended its side does not stop ours). The drain sends it as flow control allows.

The bytes the peer sent on t since the last call. They count as consumed, so connection credit keeps up with a long-lived tunnel (RFC 9000 sec 4.2).

End our side of t: FIN after the queued bytes, then the stream is reclaimed.

Advance every active HTTP/3 streaming response by one chunk.

For each stream whose source is still open, pulls a single chunk (mirroring the H1/H2 one-chunk-per-edge yield) and queues it as a DATA frame on the stream's egress. On end-of-stream the source is freed, the trailers are queued, and the record is marked done so the drain sends the FIN after the last byte. Returns the number of streams advanced (produced a chunk or reached EOS).

Backpressure: a stream with :data:_STREAM_PULL_HIGH_WATER bytes still unsent is skipped. The drain only frames what the peer's MAX_STREAM_DATA / MAX_DATA and the congestion window allow, so a fast source cannot outrun a slow reader.

Drain a burst of inbound datagrams and pump egress.

Reactor I/O loop step:

1. One recvmmsg blocks (SO_RCVTIMEO) until a datagram arrives or the wait times out cleanly, and takes the rest of the burst, up to :data:_RX_BATCH datagrams, with each one's ECN codepoint. Without recvmmsg, a blocking recv_from wakes the tick and try_recv_from drains the rest. Either way the per-tick H3 pump / timer / egress bookkeeping in the serve loop is amortized over the whole burst instead of paid per datagram.
2. Each datagram routes through :meth:dispatch_datagram by DCID; the matched slot's :meth:_drain_and_send flushes its ACK / response.

Returns True if at least one datagram was dispatched, False if the initial recv_from timed out.

How long :meth:tick may block: until the next timer (PTO, loss time, idle, closing) is due, at most max_ms and at least 1 ms (SO_RCVTIMEO 0 would block forever). A fixed 100 ms wait delayed every timer on a quiet connection by up to that long.

Emit a single fully-protected QUIC datagram on the listener's UDP socket, ECN-marked when the 1-RTT packet just built asked for it (_tx_ecn, consumed here). Returns the byte count actually written (UDP either sends the whole datagram or raises).

:meth:take_ready_slots without consuming them.

The slots that received request-stream data since the last call; only these can have new completed requests.

Drain the egress of every slot something was queued on since the last call (a packet, a response, a tunnel or datagram send, a streaming chunk, GOAWAY). Returns the number of slots that emitted. Timers drain their own slot.

Queue payload as an unreliable DATAGRAM (RFC 9221) for the next drain. False, and nothing queued, when the client takes no DATAGRAMs, the frame would exceed its max_datagram_frame_size or one packet, or the queue is full.

Send payload as an HTTP Datagram (RFC 9297) on tunnel t. False, and nothing sent, unless both ends sent SETTINGS_H3_DATAGRAM, the tunnel is open, and :meth:send_datagram takes it.

The HTTP Datagram payloads received on tunnel t since the last call, Quarter Stream ID removed.

The DATAGRAM payloads received on slot since the last call, in arrival order.

Run the listener's event loop. Blocks until :meth:shutdown flips the stop flag.

The loop drives the full I/O cycle recv -> dispatch -> drain -> protect -> sendto -> advance_timers:

1. tick(100) blocks up to 100 ms in recv_from; on a datagram it runs the dispatch + handle + drain chain.
2. On a 100 ms timeout it still calls :meth:drain_all_egress so any session that started handshaking can flush its first response.
3. :meth:advance_timers then runs the wheel against the current monotonic clock so the idle-timeout callbacks fire on time.

The 100 ms recv timeout caps the worst-case timer slop and the shutdown-flag polling interval.

Start a graceful shutdown (RFC 9114 sec 5.2): every live connection is sent GOAWAY naming the next request stream it may not open, new connections are refused, and :meth:drain_step closes each connection once its requests are answered or timeout_ms has passed.

Advance a drain started by :meth:begin_drain: close (H3_NO_ERROR, RFC 9114 sec 5.2) each connection with no request left in flight, and every connection once the deadline passes. Returns whether no live connection remains; False when no drain is running.

Request the event loop to exit. Idempotent; safe to call from a signal handler (sets a single Bool flag).

Arm the idle timer for slot from the current wheel tick.

The delay is the effective idle timeout of RFC 9000 sec 10.1: the minimum of config.max_idle_timeout_ms and the client's max_idle_timeout (when non-zero), at least three PTOs. When both are 0 the timeout is disabled: nothing is armed and the returned id is 0. Cancels the slot's previous idle timer if any so every handle_packet only ever has one idle timer in flight per connection.

Returns the new timer id (stored back into the slot's :attr:QuicConnection.idle_timer_id).

Advance the wheel to now_ms and dispatch every fired timer token to the matching action (per :mod:flare.quic.timers). Returns the number of tokens dispatched.

Handles all three registered kinds:

• TIMER_KIND_IDLE -- RFC 9000 sec 10.1 idle timeout: flips the connection to closed via on_idle_expired.
• TIMER_KIND_ACK_DELAY -- RFC 9000 sec 13.2.1 deferred ACK: flushes any owed 1-RTT ACK through the coalesced egress path so a quiescent peer still learns what arrived even when no further inbound packet drives a drain.
• TIMER_KIND_PTO -- RFC 9002 sec 6.2 probe timeout: dispatched to :meth:_on_pto_expired.

Also sweeps the CID table for any connections whose alive flag flipped False during dispatch (idle timeout, draining); their CIDs are retired so a stray retransmit doesn't route to a dead slot.

Close the underlying UDP socket. Idempotent. The :class:UdpSocket destructor also closes the fd, so explicit calls are only required when callers want to free the port before the listener goes out of scope.