From e0e8d3870bbdef3ca5f55b6b5e39be995d8f35de Mon Sep 17 00:00:00 2001 From: Nils Andreas Svee Date: Tue, 11 Aug 2026 18:26:05 +0700 Subject: [PATCH] docs(agents): add server protocol guidance --- AGENTS.md | 37 ++++++++++++++++++++++++++++--------- crates/irtt-proto/AGENTS.md | 11 ++++++++++- 2 files changed, 38 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7f7c162..013b9d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,13 +15,19 @@ Before editing, also check for a more specific `AGENTS.md` in the target subtree Compatibility and interoperability references: -- `docs/protocol/IRTT_CLIENT_PROTOCOL_SPEC.md` — verified wire/measurement +- `docs/protocol/IRTT_CLIENT_PROTOCOL_SPEC.md` — verified client-side compatibility baseline. -- `docs/protocol/BLACKBOX_VERIFICATION_REPORT.md` — black-box observations - resolving ambiguous behavior in the original specification. -- `docs/protocol/test-vectors/README.md` — captured packet vectors. +- `docs/protocol/IRTT_SERVER_PROTOCOL_SPEC.md` — verified server-side + compatibility baseline. +- `docs/protocol/BLACKBOX_VERIFICATION_REPORT.md` — black-box evidence and + corrections supporting both the client and server baselines. +- `docs/protocol/test-vectors/README.md` — captured client-facing packet + vectors. +- `docs/protocol/test-vectors/SERVER_BEHAVIORAL_VECTORS.md` — black-box + server behavioral vectors, edge cases, and session behavior. - `docs/protocol/captures/` — packet captures referenced by the verification - report. + report and behavioral vectors. Behavioral vectors and captures are + evidence/artifacts, not architecture prescriptions. - `docs/INTEROP_COMPARISON.md` — procedures for black-box comparison against the upstream `irtt` executable. - `docs/clean-room/CLEANROOM_NOTES.md` — provenance only; not a normative @@ -33,9 +39,9 @@ For compatibility questions, the verified spec and black-box observations define ## Architecture -Main boundary: +Main boundary (`irtt-server` is planned, not yet implemented): -> `irtt-proto` implements wire semantics. `irtt-client` implements client/session behavior. `irtt-stats` aggregates events. `irtt-cli` presents and orchestrates them. +> `irtt-proto` — wire semantics shared by client/server. `irtt-client` — client/session behavior. `irtt-server` — server/session behavior and Tokio runtime/orchestration. `irtt-stats` — statistics over client-facing events/results as currently designed. `irtt-cli` — presentation/orchestration. - `irtt-proto`: pure protocol encoding/decoding, flags, layouts, params, varints/zigzag, HMAC-MD5, validation. No sockets, runtimes, lifecycle, stats, or presentation. - `irtt-client`: socket/session lifecycle, negotiation, probe send/receive, timing metadata, classification, bounded state, and events. @@ -43,12 +49,25 @@ Main boundary: - `AsyncClient`: optional Tokio low-level adapter. - `ManagedClientTask` / `ManagedClientHandle`: unified Tokio managed driver/control surface. - `BlockingManagedClient`: synchronous owner using a dedicated current-thread Tokio runtime. +- `irtt-server`: planned; see "Server architecture (`irtt-server`)" below. - `irtt-stats`: cumulative/rolling/finite statistics over client events. No wire/session state machine logic. - `irtt-cli`: argument parsing, managed orchestration, output, summaries, TUI, diagnostics, and exit behavior. Do not duplicate protocol/session state machines here. -Tokio must remain optional for `irtt-client`; default builds must remain runtime-free and Tokio-free unless an explicit architectural change says otherwise. +Tokio must remain optional for `irtt-client`; default builds must remain runtime-free and Tokio-free unless an explicit architectural change says otherwise. This rule is specific to `irtt-client` — do not generalize it to `irtt-server`, which has the opposite policy below. -A first-class reusable `irtt-server` crate is a valid project direction. It must follow the same clean-room boundary and share wire logic through `irtt-proto`. A future real server may replace compliant fake peers in integration tests; purpose-built adversarial peers remain appropriate for intentionally malformed or non-compliant behavior. +### Server architecture (`irtt-server`) + +`irtt-server` is a planned first-class reusable server crate. It does not exist yet; this section describes the intended boundary for it, not an implemented API. + +- It shares wire semantics with the client through `irtt-proto` and follows the same clean-room boundary. +- It must **not** depend on `irtt-client` merely to reuse protocol behavior. +- Unlike `irtt-client`, the server has no product requirement to remain runtime-free: `irtt-server` is intentionally **Tokio-native**, and Tokio does not need to be optional for it. +- There is currently no requirement for a blocking server API, alternate async runtimes, a runtime abstraction layer, or a runtime-free server feature. Do not build blocking/runtime variants merely for symmetry with the client, and do not invent a mirrored client-style API family (`BlockingServer`, `AsyncServer`, `ManagedServer`, `BlockingManagedServer`, or similar) ahead of agreement. +- Protocol/session logic should be separated from socket/runtime orchestration where that materially improves deterministic testing, ownership clarity, state-machine reasoning, or maintainability. A `ServerCore`-like internal boundary is therefore desirable, but its exact name/API is not prescribed, it need not be public, it is not a promise of runtime independence, and simple code should not be tortured merely to make the core artificially pure. +- Runtime/server orchestration belongs around that core and may freely use Tokio for UDP sockets, `recv_from`/`send_to`, IPv4/IPv6 listeners, timers, session expiry, max-duration deadlines, shutdown, bounded control/config channels where useful, and `select!`-style orchestration. +- The CLI server applet, when added, should remain thin orchestration/configuration over reusable `irtt-server`, not contain a second server state machine. +- Resource policy: the server should use bounded session/resource policy. Upstream's observed lack of useful default session/per-peer bounds (see `IRTT_SERVER_PROTOCOL_SPEC.md`) is not an interoperability requirement and must not be reproduced merely for compatibility. +- Testing: once a real `irtt-server` exists, prefer it for normal compliant fake-peer behavior where practical. Keep narrow adversarial/raw peers for intentionally malformed, ambiguous, or non-compliant wire behavior. ## Engineering rules diff --git a/crates/irtt-proto/AGENTS.md b/crates/irtt-proto/AGENTS.md index 5d2c9ed..1da51c2 100644 --- a/crates/irtt-proto/AGENTS.md +++ b/crates/irtt-proto/AGENTS.md @@ -2,13 +2,22 @@ Repository-wide guidance in the root `AGENTS.md` also applies here. -`irtt-proto` is the pure protocol boundary. Keep it free of sockets, runtimes, client/server lifecycle, statistics, and presentation concerns. +`irtt-proto` is the pure protocol boundary. Keep it free of sockets, runtimes, client/server lifecycle, session tables, statistics, and presentation concerns. + +As `irtt-server` is built, it may need server-facing wire-inspection +primitives here, such as request decoding, reply encoding, packet/header +validation, HMAC-presence inspection, and token/header inspection before +Params-dependent decoding. For protocol behavior, consult before changing semantics: - `docs/protocol/IRTT_CLIENT_PROTOCOL_SPEC.md` +- `docs/protocol/IRTT_SERVER_PROTOCOL_SPEC.md` - `docs/protocol/BLACKBOX_VERIFICATION_REPORT.md` - `docs/protocol/test-vectors/README.md` +- `docs/protocol/test-vectors/SERVER_BEHAVIORAL_VECTORS.md` + +Protocol changes that affect server-side parsing, encoding, or session-facing wire semantics must consult the server spec and behavioral vectors as well as the client-side material above. Focused unit and table-driven tests are explicitly encouraged in this crate. Exact wire vectors, layout rules, flag combinations, malformed inputs, boundary values, HMAC behavior, and encode/decode round trips are durable compatibility coverage rather than test-count inflation.