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.
• 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.

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, so that a later policy restricting StampAt to none makes an omitted clock safe without this rule changing.
• 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. 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 are zero, which is the initial safe fill policy: payload carries no protocol meaning, and a server must never emit residue from another request or client. Request payload bytes never reach a reply.
• Rate limiting, idle expiry, maximum duration, server-initiated close, DSCP socket application and the full ServerFill policy are later slices. Do not add placeholder session fields for them.

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 tests free of sleeps, tolerances and real wall-clock assertions.
• 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.