# Upstream IRTT 0.9.1 Client Interoperability

## Scope

The released upstream IRTT 0.9.1 client was run as a **black box** against the
Tokio `irtt_server::Server` runtime. Only the executable's reported version, its
command-line help, its exit status and its normal stdout/stderr were observed.
Upstream implementation source, tests and repository history were **not**
inspected, and no upstream behavior was inferred beyond what the running program
printed.

- Tested against `irtt-rs` base commit `ace3defe22e71980f18ccdce1ef783d630e070cf`.
  No implementation change was required, so the validated behavior is that of the
  unmodified baseline.
- Listeners were **explicit loopback binds only** (`127.0.0.1:0`, `[::1]:0`).
  Wildcard binds were not exercised.
- DSCP marking, the full `ServerFill` policy and wildcard/multi-homed
  source-address (`pktinfo`) handling are unimplemented and out of scope here.
- This document records implementation validation. It creates no protocol
  requirements and does not amend the airlocked protocol evidence.

The server was exposed through a small throwaway Cargo harness kept outside this
repository. It only built a `ServerConfig`, called `Server::bind`, printed the
bound `SocketAddr` and called `Server::run`; it contains no protocol handling and
is deliberately not committed.

## Environment

| Item | Value |
| --- | --- |
| Date | 2026-08-13 |
| OS | macOS 26.5.2 (Darwin 25.5.0) |
| Architecture | arm64 (Apple silicon) |
| Rust toolchain | rustc 1.97.1, cargo 1.97.1 |
| Upstream reported version | `irtt version: 0.9.1`, protocol version 1, JSON format version 1 |
| Upstream executable SHA-256 | `35df8b2b2c10fe81a222eaac2fa7461891fa2354f74c1e9b379c3c31f43c61cc` |
| How obtained | Pre-existing installation already on `PATH`; version confirmed with `irtt version`. No isolated build was needed and no upstream source was fetched. |
| `irtt-rs` base SHA | `ace3defe22e71980f18ccdce1ef783d630e070cf` |

Flags used were taken from the executable's own `irtt help client` output:
`-d`, `-i`, `-l`, `-n`, `-4`, `-6`, `--hmac`, `--loose`, `--timeouts`,
`--tstamp`, `--clock`.

`--loose` is upstream's documented client-side switch for accepting
server-restricted test parameters instead of exiting non-zero. Restriction
scenarios were therefore run **both** ways: without it to confirm the client
detects and reports the restriction, and with it to confirm the restricted
session actually runs.

## Matrix

Server policy is `ServerConfig::default()` unless stated. All runs used numeric
loopback addresses and no DNS.

| Scenario | Server policy | Client request | Result | Notes |
| --- | --- | --- | --- | --- |
| IPv4 ordinary | default | `-4 -d 1s -i 100ms -l 128` | **PASS** | 10/10 packets, 0.00% loss, exit 0 |
| HMAC | `with_hmac_key("interop-secret")` | `--hmac=interop-secret -d 500ms -i 100ms -l 128` | **PASS** | 5/5 packets, 0.00% loss, exit 0 |
| HMAC, wrong key (negative control) | `with_hmac_key("interop-secret")` | `--hmac=wrong-secret --timeouts=200ms,200ms` | **PASS** | Silently refused; client reports `[OpenTimeout] no reply from server`, exit 1; server unaffected |
| IPv6 | default, bound `[::1]:0` | `-6 -d 1s -i 100ms -l 128` | **PASS** | 10/10 packets, 0.00% loss, exit 0 |
| Packet-length restriction | `with_max_packet_length(96)` | `-l 128` (strict) | **PASS** | `[ServerRestriction] server reduced length from 128 to 96`, exit 1 — upstream's documented strict-mode policy |
| Packet-length restriction | `with_max_packet_length(96)` | `-l 128 --loose` | **PASS** | Runs at 96 bytes, 10/10 packets, 0.00% loss, exit 0 |
| Interval restriction | default (10 ms floor) | `-i 1ms -d 500ms --loose` | **PASS** | `server increased interval from 1ms to 10ms`; 50/50 packets, 0.00% loss — the rate limiter never penalised a client sending at the interval it was given |
| Maximum-duration Close | `with_max_test_duration(500ms)` | `-d 5s -i 100ms --loose` | **PASS** (restriction) | `server reduced duration from 5s to 500ms`; 5/5 packets, exit 0. The Close-flagged reply itself is **not reachable** by a conforming client — see Findings. |
| Continuous request | `with_max_test_duration(500ms)` | `-d 0` | **SKIPPED** | Upstream rejects it client-side (`[DurationNonPositive] duration (0s) must be > 0`); a continuous request never reaches the wire from this CLI |
| No-test (optional) | default | `-n -l 128` | **PASS** | `[NoTest] skipping test at user request`, exit 0, no measurement session |
| Midpoint, single clock (optional) | default | `--tstamp=midpoint --clock=monotonic` | **PASS** | 5/5 packets, exit 0; RTT and IPDV computed from the single midpoint field |
| Midpoint, wall only (optional) | default | `--tstamp=midpoint --clock=wall` | **PASS** | 3/3 packets, exit 0 |
| Midpoint, both clocks (optional) | default | `--tstamp=midpoint --clock=both` | **PASS** | 3/3 packets, exit 0 |

In every scenario the harness process was still alive after the client exited
and shut down cleanly on `SIGTERM` (`Server::run` returned `Ok`).

## Findings

No implementation incompatibility was found in the tested matrix, and no code
change was made.

Two observations are worth recording.

**The single-field midpoint reply is accepted.** `irtt-rs` emits one timestamp
field per negotiated clock for `StampAt::Midpoint`, deliberately not reproducing
upstream 0.9.1's dual-field midpoint form (see `crates/irtt-server/AGENTS.md`).
The released upstream client parsed that reply without complaint and derived RTT
and send/receive IPDV from it, in the monotonic-only, wall-only and both-clocks
cases. This was the tested path most likely to expose a reply-shape
incompatibility, and it did not.

**The server-initiated maximum-duration Close is not reachable by a conforming
client.** The deadline is `first served echo + configured maximum + 2 s`, while
negotiation reduces a session's Duration to at most that same configured maximum.
A client that honours the Duration it was given therefore always stops sending at
least two seconds before the deadline, so no echo ever arrives to carry the
Close flag. That was confirmed empirically: with a 500 ms maximum against a
requested 5 s test, the upstream client accepted the restriction, sent for
~400 ms and exited 0 without a Close ever being due.

This is not a defect and no fix is authorised for it. The two-second grace is
recorded in the airlocked evidence as the measured upstream margin and is a fixed
internal constant; the implementation matches that evidence rather than violating
it. The consequence is simply that the Close is a defence against a client that
overruns its negotiated Duration, not part of an ordinary session. Upstream's
CLI offers no way to build such a client — `--loose` accepts and uses the
restricted parameters, and a continuous request is rejected before it reaches the
wire. The Close path itself remains covered deterministically in-repo by
`crates/irtt-server/src/tests/lifecycle.rs`, notably
`the_first_echo_past_the_maximum_duration_carries_close_and_ends_the_session`.

## Scope remaining

This validation does **not** establish:

- DSCP response marking;
- full `ServerFill` behavior (echo payloads remain zero-filled);
- wildcard or multi-homed source-address handling (`pktinfo`);
- behavior under pathological or exhaustive parameter combinations;
- behavior on operating systems other than the macOS/arm64 host recorded above;
- behavior across a real network path, MTU limits or fragmentation.

No claim of universal compatibility is made. No permanent test in this repository
depends on the upstream executable, the Go toolchain or network access; this
validation is intentionally manual and reproducible from the commands above.