irtt-rs/crates/irtt-server/AGENTS.md

# `irtt-server` guidance

Repository-wide guidance in the root `AGENTS.md` also applies here.

## Where server behavior comes from

Server wire behavior comes from the sanitized clean server documents, not from
upstream implementation material:

- `docs/protocol/IRTT_SERVER_PROTOCOL_SPEC.md`
- `docs/protocol/test-vectors/SERVER_BEHAVIORAL_VECTORS.md`
- `docs/protocol/BLACKBOX_VERIFICATION_REPORT.md`
- `docs/protocol/IRTT_CLIENT_PROTOCOL_SPEC.md` for the shared wire format

Never derive behavior from upstream `heistp/irtt` source or tests. If the clean
material does not establish a semantic, state the ambiguity instead of guessing.

## Boundaries

- Protocol behavior comes from `irtt-proto`. `irtt-server` must **not** depend
  on `irtt-client` to reuse wire logic; a needed primitive belongs in
  `irtt-proto`, where both sides get it.
- Do not reimplement magic validation, flag rules, HMAC placement, request
  classification, token/header offsets or parameter parsing here.
- No statistics, CLI or presentation concerns.
- `SocketAddr` belongs here: endpoint identity is session state. It does not
  belong in `irtt-proto`.
- Endpoint identity is compared field by field, not with `SocketAddr` equality.
  Family, address and port are established components. The IPv6 flow label is
  excluded because it identifies no endpoint; the IPv6 zone is included as a
  deliberate project policy, because the specification records multi-zone
  behavior as untested and two peers sharing a link-local address in different
  zones are genuinely different peers. Reuse that one comparison rather than
  writing a second identity rule, and keep both choices labelled as policy
  rather than as verified compatibility.

## Core versus runtime

- Deterministic protocol and session logic — admission, negotiation, the session
  table, resource decisions, packet construction — belongs in the core.
- Socket and runtime orchestration — `UdpSocket`, IPv4/IPv6 listeners,
  `recv_from`/`send_to`, timers, expiry, shutdown, `select!`, socket options —
  belongs around the core.
- The server is intentionally **Tokio-native**. Tokio does not need to be
  optional for this crate.
- `Server` owns exactly one Tokio `UdpSocket` and one `ServerCore`. Run protocol
  processing sequentially in that one task: do not spawn per datagram, put the
  core behind a lock, or start an internal detached task.
- The runtime must remain a thin `recv_from` -> `handle_datagram` -> optional
  `send_to` loop. Do not duplicate protocol parsing or encoding around the core.
- A receive failure or core failure may terminate `Server::run`; a per-packet
  send failure (including a short send) drops only that reply and must not stop
  the listener. Core state is not rolled back after a transport send failure.
- Runtime maintenance calls the core's expiry hook. It must not inspect session
  internals or grow a second expiry rule.
- Do not add a blocking server, an alternate-runtime variant, a transport trait,
  a runtime abstraction layer, or a mirrored client-style API family. There is
  no product requirement for any of them, and `ServerCore` being public is not a
  promise of runtime independence.

## One listener and several

`Server` is the packet/runtime primitive and stays that: one socket, one core,
one sequential loop. `ServerSet` is the service around it and owns no protocol
or session state of its own — it binds listeners, supervises them and shuts them
down. Nothing it does is visible on the wire.

- **A set of one is an ordinary set.** Singleton sets are normal and supported,
  and the server CLI runs *every* invocation through one, single bind included.
  There is no bind-count branch to reintroduce: one orchestration path is what
  keeps startup, shutdown and failure semantics identical for one listener and
  for five, and what keeps the singleton case exercised in normal use.
- **Nothing is shared between listeners but configuration.** Each gets its own
  socket, `ServerCore`, session table, tokens, receive/rate/lifetime state,
  clock origin and traffic-class socket state. Do not add an
  `Arc<Mutex<ServerCore>>`, a process-global token allocator or session
  registry, or a shared clock: a token from one listener is an unknown token at
  the others, and that is the point rather than a limitation.
- **`ServerConfig` is cloned per listener, so every bound in it is per
  listener.** `max_sessions` of 100 across two listeners admits 100 each. Say so
  in the rustdoc, the CLI help and the README; do not add a process-wide session
  cap here.
- **Construction is all-or-nothing and completes before anything runs.** Bind
  every listener first, spawn nothing while iterating, and drop what was bound
  if a later one fails. Startup diagnostics belong after the whole set exists,
  so a set that never started cannot print that it is listening.
- **One task per listener, and the listener stays sequential inside it.** Do not
  spawn per datagram or add a second sender: one sender per socket is what makes
  the socket-wide traffic class race-free, and that invariant is unchanged by
  there being several sockets.
- **One external shutdown, fanned out internally.** The library knows nothing
  about Ctrl-C, signals or atomics. Every listener task is joined before `run`
  returns — no detached tasks, no `abort_all()` for ordinary shutdown, and a
  `JoinError` is never discarded.
- **A listener failure fails the set.** A listener that errors, or that returns
  before shutdown was requested, shuts its siblings down; the group drains and
  returns the first meaningful failure. A service configured for IPv4 and IPv6
  must not continue silently as IPv4 only. There is no error aggregation.
- **Same-port coexistence is settled before the bind, and only there.**
  `IPV6_V6ONLY` can only be set before binding, so a genuine IPv6 listener
  sharing an explicit port with an IPv4 sibling is created through a small
  `socket2` helper and handed to `Server::from_socket`. That helper owns nothing
  else: wildcard destination metadata, the core and traffic-class state stay
  with `Server`. No `SO_REUSEPORT`, no bind-order dependence, no unsafe code,
  and standalone `Server::bind` semantics are unchanged.
- **An IPv4-mapped address is an IPv4 listener here too**, exactly as it is for
  wildcard handling and the traffic-class option. It is never given
  `IPV6_V6ONLY` and never counted as the IPv6 half of a same-port pair.
- Listener sets are fixed at construction. Do not add dynamic add/remove,
  hostname or interface expansion, or per-listener configuration without
  agreement.

## Reply source address

A reply must leave from the address its request was sent to, or a client reading
from a connected socket discards it. An explicit-address listener satisfies that
by construction and asks for no destination metadata — do not give it any merely
because the helper exists. It keeps the plain `recv_from`/`send_to` path
everywhere except Linux, where it receives through `recvmsg` for the unrelated
reason below and still sends with plain `send_to`.

A wildcard listener does not, so it recovers each request's local destination
and sends that reply from it. The supported targets are Linux, macOS and
FreeBSD; a wildcard bind anywhere else fails at construction. Correct refusal is
the point: a listener that starts and then answers from a routing-table source
address fails invisibly, as loss.

- **Destination metadata is runtime transport state.** It never enters
  `ServerCore`, `Session` or `OutboundDatagram`. The core knows peers and
  sessions; which of the host's addresses a request arrived on is not session
  policy, and adding it there would make the core platform-shaped.
- **A wildcard listener must never process a datagram whose local destination it
  could not recover.** Missing destination metadata, `MSG_CTRUNC` and `MSG_TRUNC`
  all drop the datagram *before* the core, so no receive, rate or lifetime state
  moves for a request that cannot be answered correctly. There is no fall back
  to kernel source selection: the listener promised correct sources when it
  accepted the bind.
- Wildcard-ness is decided once, from the bound address, and never inferred from
  a peer.
- Source selection is **per-packet send metadata**; the traffic class stays the
  existing socket-wide setting applied before every send. Two transport
  mechanisms, deliberately: the marking policy is already implemented and tested
  across a wider target matrix, and sequential send ownership is what keeps it
  race-free. Do not migrate it into control messages merely because `sendmsg` is
  now in reach.
- `recvmsg` and `sendmsg` integrate through Tokio readiness — `readable()` /
  `writable()` with `try_io` — following the client's ancillary receive path.
  No blocking call, no `spawn_blocking`, no dedicated receive thread, and still
  one socket and one task.
- The crate forbids unsafe code and that is not negotiable for this feature. Use
  `nix`'s safe `recvmsg`/`sendmsg`, `ControlMessage`, `ControlMessageOwned` and
  `sockopt` wrappers; no raw syscall, no `CMSG_*` walking, no hand-written ABI
  layer. A target that cannot be served this way is refused, not excepted.
- The receive and send structures are not interchangeable, and the BSD IPv4
  options are not Linux's under other names. Build each direction's control
  message explicitly rather than echoing a received one back.
- **Pin the source address, not the route.** What the protocol requires is the
  address a reply leaves from; which interface carries it is the routing table's
  business. Naming the arrival interface on a send would lose replies on a host
  whose path back to the peer leaves by another one. The single exception is a
  link-local source, which is not unique across interfaces and must name its
  own — every other source, IPv4 included, goes out with no interface set.
- A send failure is per-packet loss, exactly as an ordinary `send_to` failure
  is. It never terminates the listener and never rolls back core state.

## Kernel receive timestamps

A Linux listener asks the kernel for a software receive timestamp
(`SO_TIMESTAMPNS`) on every datagram and reports it as transport metadata. It is
the mirror image of destination metadata, and the contrast is the point.

- **Optional, not required.** Enabling it is best-effort and must never fail
  construction: a listener without it answers every request exactly as it
  otherwise would. Destination metadata failing a wildcard bind is correct;
  timestamp setup failing anything is not.
- **Its absence is never packet loss.** No timestamp, a timestamp truncated away
  on an explicit listener, or one that describes no representable instant, all
  mean the datagram is served with `kernel_rx_timestamp: None`. Only the
  destination rules a datagram out, and only for the listener that needs one.
- **Do not map wall to monotonic.** It is a realtime reading with no monotonic
  counterpart, and `ClockSample` is a paired userspace instant. Synthesizing the
  missing half would invent precision the kernel never reported.
- **Do not judge plausibility in the socket layer.** Conversion there is
  structural only. Whether a representable reading is close enough to the
  server's own sample to measure against belongs with whoever measures, which is
  the core.

### How it reaches the core, and what it may change

There are two receive entry points and one implementation behind them.

- **`ServerCore::handle_datagram(peer, packet)` is the public one and takes no
  timing.** A caller hands over bytes and an endpoint; every instant the reply
  reports is one the core sampled itself. This is exactly the behavior it had
  before the kernel timestamp was consumed, and it is what a direct or manual
  `ServerCore` user gets.
- **The Tokio runtime uses a crate-private entry point** that additionally takes
  the optional kernel-observed wall receive time, passed with the datagram it
  describes. That is the whole mechanism: an explicit per-datagram argument. Do
  **not** replace it with a "next receive timestamp" setter, a pending-metadata
  field, thread-local or global state, or a `ClockSource` wrapper that returns
  transport metadata on the next sample — those hide a per-datagram input behind
  ambient mutable state. Do not make the runtime path a second public API, and
  do not pass `ReplySource` or the whole `ReceivedDatagram` into the core: it
  needs a peer, bytes and an arrival observation, not socket addressing.
- **`ClockSample` is unchanged and still one paired userspace instant.** The
  preferred receive wall value is carried beside it on the classified echo, never
  inside it. A `ClockSample` whose `wall_ns` came from the kernel and whose
  `mono_ns` came from userspace would claim two physical instants were one
  sample.

The acceptance rule is the client's, in principle and in its bound, and lives in
the core as `preferred_receive_wall_ns`. A reading is used only when it converts
into the wire's signed-nanosecond vocabulary, is not later than the core's own
paired receive sample, and lags it by no more than `MAX_KERNEL_RX_LAG` — one
second, inclusive, and a sanity guard rather than an expected wakeup latency.
Anything else falls back to the userspace wall reading. **A rejected reading is
never a rejected datagram**: no error reply, no dropped packet, no session state
moved. Keep the two implementations separate from the client's; a shared helper
is not worth a crate dependency for a dozen lines of timing policy.

What the observation may change is one field:

- **Measurement policy**: `recv_wall` under `StampAt::Receive` and `StampAt::Both`
  on a clock that reports wall time. Nothing else.
- **Lifecycle policy**: always `received_at.mono_ns`, the core's own userspace
  monotonic reading. Idle expiry, rate allowance and the maximum-duration
  deadline never see a kernel value, including for the rate-limited echo that
  produces no reply and for the final echo that carries the close.
- **Midpoint**: always the paired userspace receive and send samples. Moving only
  the wall receive endpoint would improve apparent upstream delay by exactly what
  it cost apparent downstream delay, and leave `midpoint_wall` and
  `midpoint_mono` describing different midpoints — with no residency interval
  recoverable from a midpoint to show for it.
- **`StampAt::Send`, `StampAt::None` and `Clock::Monotonic`** emit no arrival wall
  field, so an observation cannot reach them. An open or a close ignores it too.
- **Ordering still holds.** The reported arrival wall value is held back to the
  send reading in its own right, because it may not have come from the receive
  sample `ClockSample::not_after` orders.

One consequence is intended: under `Clock::Wall` with `StampAt::Both`, the
server-processing interval a client computes now runs from the kernel's arrival
reading rather than the server's wakeup, so it includes the kernel-to-userspace
portion of the server's residency and the adjusted round-trip shrinks to match.
Under `Clock::Both` the monotonic pair still yields the unchanged userspace
interval. Do not force the two to agree, and in particular do not estimate a
kernel monotonic instant to do it.
- Linux only, and receive only. No macOS, FreeBSD or Windows implementation, and
  no transmit timestamping, without a reason and agreement.
- Control-buffer capacity is derived from the cmsg payload types and asserted at
  compile time. Adding a control message means extending that derivation — an
  undersized buffer sets `MSG_CTRUNC`, which is silent packet loss for a wildcard
  listener. Never parse cmsgs positionally or stop at the first match: the kernel
  orders them as it likes, and each kind is collected independently.

## Rejection is silence

Malformed, unauthenticated, unsupported and policy-refused input is discarded
without a reply and without disturbing any live session. The protocol defines no
error reply, no reset and no NACK. Reserve the error type for internal failures
on the server's own side; an inbound `ProtoError` must never surface as a server
failure. Hostile UDP must leave the server running.

Do not let reply behavior reveal which stage rejected a datagram — in
particular, an authentication failure must be indistinguishable from an unknown
token.

## An acknowledged open must be executable

Validate the **final, restricted** parameters before acknowledging an open, not
just the requested ones. Once an open passes admission and negotiation, its
effective parameters must be safe for the server to run.

- Effective non-none `StampAt` with `Clock::Unspecified` is silently rejected.
  Timestamps from no clock lay out no timestamp field, so the session could not
  be run. Do **not** synthesize a clock and do **not** rewrite `StampAt` to
  none: either answers with a session the client did not ask for. This is
  `irtt-rs` policy for nonconforming input, chosen because the clean evidence
  records the reference server accepting this combination and then failing on
  the first echo. A conforming client always sends a clock when it selects
  timestamps, so conforming traffic is unaffected.
- `Clock::Unspecified` alone is valid — it is just an absent tag. Only the
  combination is refused, and only an absent tag reaches it, since an explicit
  zero Clock is already out of range for the decoder.
- Run the check after negotiation. That is what makes a configured timestamp
  allowance of none accept this same request: its effective `StampAt` is none, so
  the omitted clock selects nothing and the session is executable. See
  "Capability restrictions" below.
- Negative `Length` stays an accepted negotiated value, returned unchanged in
  the open reply and stored verbatim in the session. It needs no clamping to be
  executable: `irtt-proto` floors actual echo packet sizing at the required
  protocol field block, so a negative length behaves as zero does.
- A session's echo datagram must fit `ServerConfig::max_packet_length`, whose
  default is 65,507 bytes. That is `irtt-rs` resource policy, not an
  interoperability requirement: it is the largest IPv4 UDP payload, a
  conservative cross-family ceiling that bounds one session's echo buffer to
  roughly 64 KiB and that no normal client exceeds. It is **not** an MTU, not an
  upstream default, and says nothing about what a path will carry. Upstream's
  unlimited default is not a compatibility target.
- A requested positive `Length` above the configured maximum is reduced to it
  during negotiation, so the reply is honest about what the server will emit.
  Zero and negative values are left exactly as requested.
- Capping the parameter is not sufficient. After negotiation, the mandatory echo
  field block must itself fit the configured maximum or the open is silently
  refused — statistics and timestamp fields, and authentication's 16 bytes, can
  exceed a small maximum on their own. Ask `irtt_proto::echo_packet_len` with
  this server's actual HMAC mode rather than growing a second packet-size rule
  here; an unrepresentable length from it is a request rejection, not a
  `ServerError`.
- Zero is a valid maximum and is not a synonym for unlimited: it refuses every
  session, and no-test opens with it, since both are validated against the same
  effective session.
- Echo request admission reuses this same configured maximum, comparing it
  against the received datagram length before any receive state is mutated.

## Echo processing

- An accepted echo owns per-session `ReceiveState` — count, window and the
  previous accepted sequence number. Admission order is authentication, then
  received datagram length against the configured maximum, then token, then
  endpoint; a request failing any of them mutates nothing, in this session or
  any other.
- The count and window transitions follow the clean specification's Section 10
  and the Section 1 vectors, including the parts that read as defects: a
  duplicate advances the count and leaves the window alone, and a late,
  reordered or far-gap request resets the window to `0x1` rather than setting a
  historical bit, because the distance is unsigned. Do not replace this with a
  conventional selective-acknowledgement bitmap. Reference the vectors rather
  than restating the tables here.
- Only the token and sequence number mean anything in a request. The tail is
  opaque, and the request's length never sizes the reply — layout and length
  come from the session's negotiated params through `irtt-proto` alone.
- The transition is pure and is committed only after the reply has encoded, so
  an internal encoding failure cannot leave a session claiming to have answered
  a request it never did.
- Clock sampling is a private injected seam, like token generation, not a
  runtime abstraction: the receive instant is taken as soon as a datagram is
  classified as an echo and the send instant just before the reply is built, so
  they bracket the server's own handling. The monotonic origin belongs to the
  clock source and is stable for its life.
- A reply's receive instant is held back to its send instant where the wall
  clock stepped backwards between the two readings, so the required ordering
  holds — and so is a reported arrival wall value that came from the kernel
  instead, which needs the rule applied in its own right because it was not part
  of the pair. That correction is per reply and stateless on purpose: latching a
  pre-step wall value across packets would keep reporting a time the host has
  corrected away, which is the smoothing the specification forbids, and
  anchoring the wall clock to the monotonic origin would drift and never pick up
  a legitimate correction. The server reports its own wall clock honestly.
- For a single-clock midpoint, `irtt-rs` emits the one negotiated field. It does
  not reproduce upstream 0.9.1's dual-field midpoint; `irtt-proto` still decodes
  that form from a peer.
- Reply payload bytes come from the session's fill; see "Server fill" below.
  Request payload bytes never reach a reply under any mode.

## Server fill

The ServerFill *string* is wire data `irtt-proto` carries verbatim, and it
already enforces the 32-byte, UTF-8 and truncation rules. What a descriptor
*means* is server policy and lives in `fill`. Do not move descriptor parsing
into `irtt-proto`, and do not duplicate the decoder's checks here.

- **All three valid descriptor families are accepted**: `none`, `rand` and
  `pattern:HH…`. Mode names are case-sensitive; only a pattern's hexadecimal
  body is not. This is deliberately more permissive than the reference server's
  configurable glob allow-list, which is upstream policy rather than an
  interoperability requirement. Do **not** add glob, regex or allow-list
  configuration, and do not add server fill CLI knobs.
- **Absent or empty means no preference.** The negotiated params keep their
  representation exactly — absent stays absent, empty stays empty — while the
  session uses the server default internally. Writing the default descriptor
  into the reply would manufacture a restriction, which a strict client rightly
  rejects.
- **The default and fallback descriptor is `pattern:69727474`**, the bytes
  `irtt`. The descriptor and the bytes are separate constants; neither is
  derived from the other at run time.
- **An unknown or malformed explicit descriptor is replaced** in the negotiated
  params by that default descriptor, because the server really did change what
  was asked for. The client models it as `ServerFillChanged`; do not weaken
  client negotiation to hide it.
- **`none` zero-fills.** The clean evidence records the reference server leaving
  the region as residual buffer content, returning other clients' bytes. Zero is
  produced by handing the encoder an empty payload, not by copying zeroes over
  an already-zeroed packet.
- **Pattern phase resets for every reply.** Upstream's observed cross-packet and
  cross-listener continuity is explicitly not required of a conforming server,
  and per-packet reset keeps the server free of global mutable fill state and
  makes replies deterministic. There is no shared phase between sessions or
  listeners, and adding one would be a regression.
- **`FillMode` belongs to the `Session`**, parsed once at open. Never re-derive
  it from `params` later: that would lose the absent-descriptor-with-default-
  behavior distinction. Keep the type crate-private.
- **Fill is generated before the reply is encoded**, like every other part of an
  echo, so the packet's HMAC covers the fill bytes through the ordinary encoder
  path and no session state commits before encoding succeeds. Never mutate a
  payload after encoding.
- **A random-source failure zero-fills that one payload and is not fatal.** It
  must never become a `ServerError`, terminate `Server::run` or drop the
  session. The bytes exist to vary the payload and are not security state;
  session tokens keep their own source.
- Payload length comes from `irtt-proto`'s layout and `echo_packet_len`, never
  from `params.length`, and needs no second packet-size bound of its own.

## Capability restrictions

Two optional negotiation policies restrict what a session may ask this server to
*provide*. Both default to off, so a configuration that sets neither negotiates
exactly what it did before they existed. Both live in `negotiate`, with the rest
of open negotiation, and neither reaches the runtime.

- **`TimestampAllowance` is server policy, and deliberately not `StampAt`.** The
  wire enum describes what a session requests and negotiates; the allowance
  describes what this server is willing to hand out. Keep the two types apart,
  and keep the allowance out of `irtt-proto`.
- The default is `Dual`, which honors every requested placement. `None` maps every
  non-none placement to none. `Single` maps `Both` to **`Midpoint`** and leaves
  every already-single placement alone — that one substitution is the only
  interesting row; the rest is in the clean spec's Section 11.4.
- **`Clock` is never rewritten.** The evidence describes an allowance on timestamp
  *placement*, not on clock domains, and the echo layout already carries no
  timestamp field once the placement is none. So `Single` bounds reported
  *instants*, not field count: on `Clock::Both` a negotiated midpoint still emits
  a wall and a monotonic field. Do not document it as one field. Rewriting the clock would answer
  with a session the client did not ask for.
- **Restriction runs before the effective-session executability check**, and that
  ordering is load-bearing: it is what makes a request selecting timestamps with
  an omitted Clock *safe* under a none allowance, where the same request is
  refused under the default. Do not move the check onto the requested params.
- **DSCP permission defaults to allowed.** When disallowed, negotiation sets
  `Params.dscp` to zero before the reply is encoded and before the `Session`
  exists, for every requested value including ones outside `0..=255`. The open is
  never refused over DSCP, and nothing is clamped or wrapped.
- **No second policy bit anywhere.** The negotiated params are the single source
  of truth: the session stores zero, `OutboundDatagram`'s traffic class derives
  from it as for any other zero-DSCP session, and the runtime never learns that
  `ServerConfig::dscp_allowed` exists. `Params::encode` omits a zero integer, so
  the reply simply carries no DSCP tag.
- **This is operator policy, not socket capability detection.** What a given host
  can apply to a socket is settled per send by the runtime (see "Reply traffic
  class"). Do not couple `ServerCore` negotiation to `socket2` or to runtime
  capability state.

## Reply traffic class

The core hands each reply out as an `OutboundDatagram`: the bytes plus the
transport policy sending them requires. The runtime must not rediscover that
policy by decoding the outgoing packet, inspecting the inbound token, reaching
into a `Session` or keeping its own token-to-marking map — the core is where
session policy lives.

- `traffic_class` is the **raw 8-bit IPv4 TOS / IPv6 Traffic Class byte**, which
  is what the DSCP protocol parameter carries. The six-bit codepoint is
  `traffic_class >> 2` and the low two bits are ECN. Never shift, mask or round
  it inside the server.
- Open and no-test replies always request class zero, whatever the session
  negotiates. That is observed behavior, not a simplification.
- An echo reply requests the session's negotiated byte, and a server-close echo
  reply keeps it: the close is an ordinary reply with a flag added, not a
  special packet.
- A negotiated integer outside `0..=255` stays in `Params` — returned and stored
  exactly as requested — but is transported unmarked. This is **`irtt-rs`
  policy**: the clean evidence records the reference host's handling of such
  values as platform-specific and explicitly not a compatibility requirement, so
  there is nothing to reproduce, and a malformed-but-accepted session should
  stay usable rather than be given a marking nobody asked for. Do not add
  negotiation-time rejection, clamping or wrapping for it.
- The runtime applies a class before **every** send. Zero must be applied as
  explicitly as a nonzero value: skipping the call would send an open reply, or
  an unmarked session's reply, under whichever marking the previous reply left
  on the shared socket. There is no restore-to-zero-after-send step, and no
  cached "current value" to elide the call — the next reply is authoritative.
- **Sequential send ownership is what makes a socket-wide setting race-free.**
  One task owns the socket and no other sends from it, including while a send is
  suspended. Do not introduce concurrent sends without replacing this with
  per-packet control messages.
- Applying the class and sending are both per-packet transport steps: a failure
  of either drops that one reply and the listener keeps serving. A marking that
  could not be applied means the reply is not sent at all, because sending it
  would put it on the wire under the previous reply's marking.
- **One exception, and it is what keeps the server usable on hosts without the
  option**: an *unmarked* reply may still be sent when this server has never
  successfully applied a nonzero class to the socket, because then there is no
  marking of ours for it to inherit. Some Windows builds do not support
  `IP_TOS`, and a few targets have no safe setter at all; without this, such a
  host would drop every open reply and no session could ever start. The flag
  behind it is consulted only on failure — it never elides a call.
- The platform helper must report failure honestly, including for zero. "The
  socket was cleared" and "nothing was written" are different statements, and a
  socket passed to `Server::from_socket` may have been marked by its creator.
  Whether an unappliable zero is nevertheless safe is the runtime's decision,
  made from what this server itself applied.
- The option itself comes from `socket2`'s safe API, chosen by the listener's
  bound address family rather than the peer's. **On Linux an IPv4-mapped bound
  address is an IPv4 listener**, whatever shape it wears: the socket is
  `AF_INET6`, but the kernel binds it to the IPv4 side and `IPV6_TCLASS` does not
  reach the packets it emits — it leaves their TOS at zero and the negotiated
  marking is lost, while `IP_TOS` on that same socket marks them. macOS rejects
  `IP_TOS` on an `AF_INET6` socket outright and marks nothing either way, so it
  keeps the IPv6 option: reading a mapped bind as IPv4 there would turn an
  unmarked reply into a *dropped* one, because an unappliable marking stops the
  send. Verify a platform before extending that list.
- A genuinely dual-stack `[::]` listener still emits **unmarked** IPv4-mapped
  replies on Linux. When reply DSCP/traffic-class marking for IPv4 peers
  matters, configure the normal same-port `[::]:PORT` plus `0.0.0.0:PORT`
  listener pair instead; `ServerSet` makes the IPv6 half IPv6-only for that
  pair. Do not force `IPV6_V6ONLY` on every lone IPv6 listener, and do not
  weaken the rule that an unappliable marking stops the send. The crate forbids
  unsafe code; there is no raw `setsockopt` and no `sendmsg`/`cmsg` machinery.
  Keep the target lists identical to the pinned `socket2` version's own gates
  — check its source rather than copying another crate's older matrix.

## Rate, lifetime and server-initiated close

Defaults: minimum send interval 10 ms, burst allowance 5, idle timeout 60 s, no
maximum test duration. All four are per-server configuration, and the burst
allowance is per session.

Negotiation applies the interval floor first and the (idle timeout ÷ 4) cap
second, so a configured minimum above a quarter of the timeout ends with the cap
winning and the returned interval below that minimum. A configured maximum test
duration reduces a longer requested Duration and also replaces a *continuous*
request (an absent Duration), because restricting continuous mode to a finite
test is what configuring a maximum means. A zero configured maximum is stored as
no maximum: Duration zero on the wire means continuous, so a finite maximum of
zero could only be expressed by making a client's finite test endless.

Several choices below deliberately differ from the reference server's observed
behavior. Each is **`irtt-rs` project policy**, taken where the clean evidence
records upstream behavior as policy rather than an interoperability requirement.
Do not rewrite the protocol evidence to match them.

- **The refill interval is the shorter of the configured minimum and the
  negotiated interval.** The specification records upstream replenishing on the
  configured minimum regardless, so its own idle cap can hand a client a 2 s
  interval while the limiter enforces 5 s and rate-limits a fully conforming
  client. A server must not enforce a cadence it did not advertise. Ordinary
  configurations are unaffected: a 10 ms minimum against a 1 s negotiated
  interval still refills every 10 ms.
- **Zero means two different things and neither is "unlimited".** A zero minimum
  send interval is no time-based throttling; a zero burst allowance is no
  allowance at all, so every echo is rate-limited.
- **A rate-limited echo refreshes the idle deadline and advances no statistic.**
  This one *is* observed behavior — the only tested drop class that refreshes —
  and is kept deliberately.
- **The idle deadline runs from the open**, not from the first echo request. A
  session that never carries one still ages out; upstream's never-expiring
  unused session is a resource leak the specification recommends against.
- **Expiry is immediate and silent at the configured deadline.** No five-second
  additive grace, no final lazy-release reply to the first echo that finds an
  expired session, and no request-class-dependent "who consumed it" behavior.
  The only interoperability constraint is negative — expiry must never be
  signalled — and silence satisfies it. A zero idle timeout expires a session at
  the next evaluation; it is not "never expire".
- **Logical expiry is request-exact; physical reclamation also runs on the
  runtime's fixed maintenance cadence.** Every authenticated, structurally valid
  request runs the global sweep before dispatch, so a request at the deadline
  finds the session expired and a stale session cannot deny an open. The Tokio
  runtime invokes that same core sweep once per second so dead sessions do not
  remain resident when there is no further traffic. This cadence is internal
  housekeeping, not protocol policy or public configuration, and the runtime
  must not inspect session internals or duplicate the expiry rule.
- **The maximum-duration deadline is `first served echo + maximum + 2 s`.** The
  origin is measured behavior: neither the open, nor a rejected first echo, nor a
  rate-limited one starts it. The two-second grace matches the measured upstream
  margin and is a fixed internal constant, not a configuration knob.
- **Rate allowance is judged before the maximum-duration close.** A
  deadline-crossing echo with no allowance is dropped silently and the close is
  carried by the next echo that is served. Other rejected classes likewise do not
  trigger or defer it — the specification records that case as untested, so this
  is the deterministic reading rather than an observed one.
- **A server close is an ordinary echo reply with `FLAG_CLOSE` added**, carrying
  the triggering request's sequence number, statistics, timestamps and
  authentication. There is no standalone close packet in protocol version 1. The
  session is released once that reply has encoded, so every later request is an
  unknown token.

Every state transition — receive, rate and lifetime — is computed purely and
committed only after the reply has encoded, so an encoding failure leaves the
session exactly as it was and releases nothing.

## Resource policy

Total session and resource state must stay bounded. A single unauthenticated
datagram creates a session and opens are never deduplicated, so neither an
unbounded table nor a remotely chosen packet buffer is defensible. Upstream's
observed absence of session and per-peer bounds, and its unlimited default
packet length, are explicitly **not** compatibility targets and must not be
reproduced.

Configured bounds are trusted local policy: an operator may deliberately set an
absurd `max_sessions` or `max_packet_length`, and that is their choice. The
defaults are what must stay bounded, and no bound gets an unlimited setting.

Keep fallible preparation before irreversible state mutation: a reply is
prepared before a session is inserted, so an internal failure cannot leave a
half-created session.

## Testing

- Drive the core with real packets built by the production encoders. Do not
  maintain shadow encoders for well-formed wire data.
- Hand-build packets only where the point is a payload a compliant encoder
  cannot produce — truncated varints, out-of-range enums, corrupted MACs.
- Token generation and clock sampling are the only nondeterministic parts; tests
  inject a scripted source for each, so identity, collisions, allocation failure
  and timestamp values are all assertable. Keep both seams private, and keep
  timestamp, rate and lifetime tests free of sleeps, tolerances and real
  wall-clock assertions.
- Two clock fakes, for two different questions. A scripted clock returns a fixed
  list of samples and is for tests that assert individual timestamp *readings*; a
  hand-moved clock stands still until the test moves it, and is for rate and
  lifetime tests, which care when a datagram arrived and not how many times the
  core read the clock on the way. Prefer the latter for anything about deadlines.
- Assert rate and lifetime behavior from replies: which datagrams came back, the
  count and window they reported, and `session_count`. The token bucket is a
  black-box inference about the reference server, not a protocol requirement, so
  do not add accessors for allowance, activity instants or the maximum-duration
  origin.
- As the server gains behavior, prefer it over fake peers for normal compliant
  behavior in other crates' tests. Keep small raw/adversarial peers for
  intentionally malformed or non-compliant wire behavior.