irtt-rs/docs/protocol/IRTT_CLIENT_PROTOCOL_SPEC.md

IRTT-Compatible Client Protocol Specification

• Version: 1.3-verified
• Date: 2026-08-11
• Verified against: irtt 0.9.1 release, protocol version 1, macOS Darwin 25.3.0 / 25.5.0 arm64

Changes in 1.2: corrections and clarifications arising from server-side verification. See Sections 19.3, 19.9, 19.10, 19.13, 19.14 and 19.15, and the companion IRTT_SERVER_PROTOCOL_SPEC.md.

Changes in 1.3: the reply-length tolerance of Sections 8.5 and 19.14 is narrowed from "accept any longer reply" to the one verified single-clock midpoint case, and stated as a single additional accepted length — upstream_0_9_1_reply_len exactly — rather than a +1..+8 range; the normal minimum and expected reply size is stated as compatible_reply_len rather than the negotiated Length value alone; the monotonic-only decoding ambiguity is recorded rather than papered over with a heuristic; the DSCP wire encoding is separated from user-facing notation (Section 10.8); and the stale suggestion that servers reject a protocol-version mismatch is removed (Section 6.2).

---

1. Status

This document describes the externally observable behavior required for an independent client implementation compatible with existing IRTT (Isochronous Round-Trip Tester) servers.

This document does not describe upstream source structure, internal algorithms, or implementation organization. It is intended for a clean-room implementation that has never seen the upstream source code.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as interoperability requirements, consistent with RFC 2119.

---

2. Scope

• Client-only implementation. Server implementation is out of scope unless server behavior is needed to understand client interoperability. Server behavior is specified separately in IRTT_SERVER_PROTOCOL_SPEC.md, which shares this document's wire format.
• Compatible with existing IRTT servers running protocol version 1.
• This specification describes protocol and measurement behavior; CLI design is not prescribed.

---

3. Terminology

Term	Definition
Client	The endpoint that initiates a session, sends test packets, and receives replies.
Server	The endpoint that accepts sessions and echoes test packets back to the client.
Session	A stateful association between a client and server, identified by a connection token.
Open / Negotiation phase	The initial handshake in which the client proposes test parameters and the server responds with (possibly restricted) parameters and a connection token.
Test packet	A UDP datagram sent by the client during the active test phase. Sometimes called an "echo request."
Reply packet	A UDP datagram sent by the server in response to a test packet. Sometimes called an "echo reply."
Close / Finalization phase	The exchange in which the client notifies the server that the session is ending.
Connection token	A 64-bit value assigned by the server during negotiation, used to identify the session in all subsequent packets.
Round-trip time (RTT)	The time between sending a test packet and receiving its reply, optionally minus server processing time.
Send interval	The fixed time period between successive test packet transmissions.
Sequence number	A 32-bit unsigned integer, starting at 0, assigned to each test packet in order of transmission.
Timeout	The duration the client waits for a server reply during the open phase before retransmitting.
Packet loss	A test packet for which no reply was received.
Duplicate	A reply received with a sequence number for which a reply was already recorded.
Late packet	A reply received with a sequence number lower than the most recently received sequence number (indicates out-of-order delivery).
IPDV (Instantaneous Packet Delay Variation)	The difference in delay between two successive successfully returned replies. Commonly called "jitter."
Server processing delay	The time the server spent between receiving a request and sending its reply, measured by server timestamps.
Received count	A running count of all packets the server has received for this session.
Received window	A 64-bit bitmap indicating the receipt status of the most recent 64 packets at the server.
Wall clock	System real-time clock (nanoseconds since Unix epoch). Subject to NTP adjustments.
Monotonic clock	A clock that only moves forward and is not subject to system time adjustments. Used for duration calculations.
HMAC	Hash-based Message Authentication Code (MD5), used for packet authentication.
DSCP	Differentiated Services Code Point, set in the IP header TOS/Traffic Class field.
Drain period	The period after the last test packet is sent during which the client waits for outstanding replies.

---

4. Conformance

A conforming client MUST implement:

1. Session lifecycle: open, test, close.
2. The binary wire format defined in this document.
3. Parameter negotiation.
4. Connection token handling.
5. Sequence number assignment and reply matching.
6. RTT measurement.
7. Packet loss detection.
8. Tolerance for UDP reordering and duplication.

A conforming client SHOULD implement:

1. HMAC authentication.
2. Server timestamp handling (one-way delay, IPDV).
3. Received stats (count and window) processing.
4. Configurable DSCP.

Implementations are not required to use any specific internal architecture, data structure, function layout, naming convention, concurrency model, or source organization. Only the externally observable behavior described in this document is normative.

---

5. Transport Requirements

5.1 Transport Protocol

IRTT uses UDP exclusively. There is no TCP fallback.

5.2 Default Port

The default server port is 2112. The default client local port is ephemeral (OS-assigned, port 0).

5.3 IPv4 and IPv6

A conforming client MUST support IPv4. IPv6 support is RECOMMENDED. When the user does not specify an IP version preference, the client SHOULD attempt address resolution for both IPv4 and IPv6, and use whichever resolves successfully. If both resolve, the selection behavior is implementation-defined.

The client MUST use a single connected UDP socket for the entire session. The client calls the equivalent of connect() on the socket, binding it to the resolved server address before the open phase.

5.4 Socket Options

• DSCP/TOS: A client SHOULD support setting the DSCP value on outgoing packets. For IPv4, this is the TOS field. For IPv6, this is the Traffic Class field. The DSCP value is negotiated as a parameter; if the server disallows DSCP, the negotiated value will be 0.
• TTL/Hop Limit: A client MAY support setting the IP TTL (IPv4) or Hop Limit (IPv6).
• Don't Fragment (DF): A client MAY support setting the DF bit.
• ECN: ECN bit handling is OPTIONAL and experimental.

5.5 Connectionless Behavior

Although the client uses a connected UDP socket, the protocol is connectionless at the network layer. The client MUST tolerate:

• Packet reordering.
• Packet duplication.
• Packet loss.
• Receiving unrelated UDP traffic on the socket (which MUST be discarded based on validation rules).

5.6 MTU Considerations

Common maximum unfragmented UDP payload sizes for a 1500-byte MTU:

• IPv4: 1472 bytes (1500 - 20 IPv4 header - 8 UDP header)
• IPv6: 1452 bytes (1500 - 40 IPv6 header - 8 UDP header)

The client does not need to perform path MTU discovery. Packet length is a user-configured parameter.

---

6. Session Lifecycle

A client session progresses through the following externally observable states:

  Resolving ──► Opening ──► Active Test ──► Draining ──► Closing ──► Completed
                  │                                         │
                  ▼                                         ▼
               Failed                                   Completed

6.1 Resolving

• Entry: Client is given a server address (hostname or IP) and port.
• Behavior: The client resolves the address to a UDP endpoint. The default port (2112) MUST be appended if no port is specified.
• Exit: Successful resolution transitions to Opening. Failure transitions to Failed.

6.2 Opening / Negotiating

• Entry: The client has a resolved server address and a connected UDP socket.

• Behavior:

  1. The client constructs an open request packet (see Section 8.2) containing the proposed test parameters serialized in the payload.
  2. The client sends the open request and waits for a reply.
  3. If no reply is received within the current timeout, the client retransmits the open request with the next timeout value from its timeout list.
  4. The default timeout sequence is: 1s, 2s, 4s, 8s (total maximum wait: 15s, maximum 4 packets). The minimum timeout value MUST be at least 200ms.
  5. If all timeouts are exhausted with no reply, the session transitions to Failed.

• Valid server responses:

  • An open reply with a non-zero connection token: session parameters are extracted from the reply payload. The client stores the connection token. Transitions to Active Test (or Completed if the no-test flag was set).
  • An open reply with the close flag set, when the client did NOT set Close in its request: the server rejected the session. Transition to Failed. Note that upstream 0.9.1 servers were never observed to produce such a rejection — in particular they do not reject a mismatched protocol version this way (see below and Section 19.13) — so a client MUST handle the shape without depending on any server actually emitting it.
  • An open reply with the close flag set, when the client DID set Close in its request (no-test mode): the server acknowledged the open+close. The connection token is zero. Transition to Completed. [Verified 2026-04-28 — see BLACKBOX_VERIFICATION_REPORT.md Finding D.]

• Parameter negotiation: The server MAY restrict parameters. The client MUST compare returned parameters against its requested parameters. A conforming client MUST, by default, reject the session if parameters were restricted (transition to Failed with an appropriate error). A "loose" mode MAY be provided that accepts server restrictions with a warning.

  The client MUST reject (as an error) the following server parameter changes:

  • Duration increased beyond what was requested.
  • Length increased beyond what was requested.
  • Interval reduced below a safety floor of 1 second. This rejection applies in loose mode as well as strict mode. [Verified 2026-08-11 — see Section 19.9.]

• Protocol version check: The client MUST verify that the server's protocol version matches exactly. Protocol version 1 is the current version. Mismatch MUST cause the session to fail.

  The client cannot rely on the server to detect the mismatch. Upstream 0.9.1 servers do not reject a mismatched protocol version: they rewrite it to 1, open a normal session, and return ProtocolVersion = 1 with the Close flag clear. Version checking is therefore effectively client-side only. [Verified 2026-08-11 — see Section 19.13 and IRTT_SERVER_PROTOCOL_SPEC.md Section 7.5.]

6.3 Active Test

• Entry: Open reply received and parameters accepted.

• Behavior:

  1. The client sends test packets at fixed intervals for the configured duration.
  2. The client MUST be able to receive reply packets while continuing to send test packets (i.e., sending and receiving occur concurrently).
  3. Test packets are numbered with sequence numbers starting at 0.
  4. The test duration is exclusive: the client MUST NOT send a packet at or after the end time. The end time is calculated as start time + duration. The next scheduled send time is computed, and if it would be at or past the end time, sending stops.
  5. The expected number of packets for a given duration d and interval i is: ceil(d / i). [Verified 2026-04-28 by black-box testing with irtt 0.9.1. See BLACKBOX_VERIFICATION_REPORT.md Finding A.]

• Exit: All scheduled packets have been sent. Transition to Draining.

6.4 Draining Replies

• Entry: All test packets have been sent.

• Behavior: The client waits for outstanding replies. The wait duration is configurable:

  • Default: 3 times the maximum observed RTT, falling back to 4 seconds if no RTT has been measured.
  • Alternatives: a factor of mean RTT, or a fixed duration.
  • If all replies have already been received, no wait is needed.

• Exit: Wait period expires, or all replies received. Transition to Closing.

6.5 Closing

• Entry: Test and drain are complete.

• Behavior: The client sends a single close packet (see Section 8.4) to the server. The close packet includes the connection token and the close flag. The client does NOT wait for a close acknowledgement (this is a known limitation of protocol version 1).

• Exit: Close packet sent. Transition to Completed.

6.6 Completed

• Entry: Session has finished normally.
• Behavior: Results are computed and made available.

6.7 Failed

• Entry: An unrecoverable error occurred.
• Behavior: Partial results MAY be available if the failure occurred during or after the Active Test phase.

---

7. Packet Format Overview

All IRTT packets share a common header structure. The presence or absence of optional fields is determined by context (packet type and negotiated parameters).

Packet Type	Direction	When Sent	Required	Purpose
Open Request	Client → Server	Opening phase	Yes	Propose session parameters
Open Reply	Server → Client	Opening phase	Yes	Return connection token and (possibly restricted) parameters
Echo Request (Test Packet)	Client → Server	Active test	Yes	Carry test payload with sequence number
Echo Reply	Server → Client	Active test	Yes	Return test payload with timestamps and stats
Close Request	Client → Server	Closing phase	Yes	Signal session end
Close Reply	Server → Client	Closing phase	No	Not part of normal operation. Upstream servers send nothing in response to a close; such a datagram is tolerated by clients but has no demonstrated purpose in protocol version 1

---

8. Binary Wire Format

8.1 General Header Structure

All multi-byte integer fields use little-endian byte order.

The packet format uses a flexible field layout. Fields are placed sequentially in the packet buffer. A field is either present at its full capacity or absent (zero length). The set of present fields is determined by the packet type and negotiated parameters.

8.1.1 Fixed Header Fields (always present)

Offset	Size (bytes)	Field	Encoding	Description
0	3	Magic	Raw bytes	Fixed value: 0x14 0xA7 0x5B
3	1	Flags	Unsigned byte	Bit flags (see below)

Total minimum header: 4 bytes.

8.1.2 Flag Bits

Bit	Mask	Name	Meaning
0	0x01	Open	Set on open request and open reply packets
1	0x02	Reply	Set on all packets from server to client; clear on all packets from client to server
2	0x04	Close	Set on close request and close reply packets
3	0x08	HMAC	Set if an HMAC field is present in the packet

Bits 4-7 are reserved and MUST be zero. A client MUST reject packets where reserved flag bits are set.

8.1.3 Optional Fields

After the fixed header, optional fields appear in the following order when present. A field is either present at full size or entirely absent. There are no length-prefix or presence-indicator bytes; the receiver knows which fields are present based on the packet type and negotiated session parameters.

Verification note: The field ordering below is critical for interoperability. [Verified 2026-04-28 by packet capture with multiple field combinations — see BLACKBOX_VERIFICATION_REPORT.md Section 19.11.]

Order	Field	Size (bytes)	Encoding	When Present
1	HMAC	16	MD5 HMAC	When HMAC flag (0x08) is set
2	Connection Token	8	Little-endian uint64	All packets except initial open request sent from client before token is known. Present in open reply and all subsequent packets.
3	Sequence Number	4	Little-endian uint32	Echo request and echo reply packets
4	Received Count	4	Little-endian uint32	Echo reply, when "count" stats negotiated
5	Received Window	8	Little-endian uint64	Echo reply, when "window" stats negotiated
6	Receive Wall Timestamp	8	Little-endian int64 (ns since Unix epoch)	Echo reply, when receive timestamps negotiated with wall clock
7	Receive Mono Timestamp	8	Little-endian int64 (ns, duration)	Echo reply, when receive timestamps negotiated with monotonic clock
8	Midpoint Wall Timestamp	8	Little-endian int64 (ns since Unix epoch)	Echo reply, when midpoint timestamp negotiated with wall clock
9	Midpoint Mono Timestamp	8	Little-endian int64 (ns, duration)	Echo reply, when midpoint timestamp negotiated with monotonic clock
10	Send Wall Timestamp	8	Little-endian int64 (ns since Unix epoch)	Echo reply, when send timestamps negotiated with wall clock
11	Send Mono Timestamp	8	Little-endian int64 (ns, duration)	Echo reply, when send timestamps negotiated with monotonic clock

Important: Midpoint timestamps are mutually exclusive with receive/send timestamps. If a midpoint timestamp is present, receive and send timestamp fields MUST NOT be present, and vice versa. A packet containing both midpoint and receive/send timestamps is malformed.

When both receive and send timestamps are present, they MUST use the same clock mode (both wall, both monotonic, or both wall+monotonic).

8.1.4 Payload

Everything after the last present header field is payload. The total packet length is the negotiated packet length. If the negotiated length is larger than the header, the remaining bytes are payload. If the negotiated length is 0 or unspecified, the packet length equals the header length (no payload).

The client fills the payload with zeros, random data, or a repeating pattern, as configured. The server fills reply payloads according to its configuration and the negotiated server fill parameter.

8.2 Open Request Packet

Direction: Client → Server
Flags: Open (0x01) set. Reply (0x02) clear. HMAC (0x08) set if HMAC key configured.

Header fields present:

• Magic (3 bytes)
• Flags (1 byte)
• HMAC (16 bytes) — if HMAC configured

The connection token field is NOT present in the open request (the token has not yet been assigned). [Verified 2026-04-28 by packet capture — see BLACKBOX_VERIFICATION_REPORT.md Section 19.1.]

Payload: Serialized parameters (see Section 8.6).

If the client wants to open and immediately close (no-test mode), both the Open (0x01) and Close (0x04) flags are set.

8.3 Open Reply Packet

Direction: Server → Client
Flags: Open (0x01) set. Reply (0x02) set. Close (0x04) set if the server is rejecting the connection. HMAC (0x08) set if applicable.

Header fields present:

• Magic (3 bytes)
• Flags (1 byte)
• HMAC (16 bytes) — if applicable
• Connection Token (8 bytes)

Payload: Serialized parameters (see Section 8.6), reflecting any server restrictions.

Validation:

• If the Close flag is NOT set, the connection token MUST be non-zero. A zero token without the close flag is an error.
• If the Close flag IS set and the client did NOT set Close in its open request, the server is rejecting the session (transition to Failed).
• If the Close flag IS set and the client DID set Close in its open request (no-test mode), the server acknowledged the open+close. The connection token is zero. Transition to Completed. [Verified 2026-04-28 — see BLACKBOX_VERIFICATION_REPORT.md Finding D.]

8.4 Echo Request Packet (Test Packet)

Direction: Client → Server
Flags: Reply (0x02) clear. HMAC (0x08) if applicable. Open (0x01) and Close (0x04) clear.

Header fields present:

• Magic (3 bytes)
• Flags (1 byte)
• HMAC (16 bytes) — if applicable
• Connection Token (8 bytes)
• Sequence Number (4 bytes)
• Received Count (4 bytes, zeroed) — if "count" stats negotiated
• Received Window (8 bytes, zeroed) — if "window" stats negotiated
• Timestamp fields (zeroed) — according to negotiated stamp_at and clock

The echo request includes zeroed placeholder fields for received stats and timestamps so that the total packet reaches the negotiated length.

Payload: Filled according to client configuration (zeros, random, or pattern).

Total packet length: The negotiated length parameter. If the header (including zeroed optional fields) is larger than the negotiated length, the actual packet length is the header length. The final negotiated length reflects this minimum.

8.5 Echo Reply Packet

Direction: Server → Client
Flags: Reply (0x02) set. HMAC (0x08) if applicable. Close (0x04) MAY be set (see Section 19.3 — not yet verified by black-box testing).

Header fields present:

• Magic (3 bytes)
• Flags (1 byte)
• HMAC (16 bytes) — if applicable
• Connection Token (8 bytes)
• Sequence Number (4 bytes)
• Received Count (4 bytes) — if negotiated, contains server's running count
• Received Window (8 bytes) — if negotiated, contains 64-bit received bitmap
• Timestamp fields — according to negotiated stamp_at and clock settings

Payload: Server-filled according to negotiation. The client MUST NOT rely on the payload's content: server fill is applied as a continuous stream, so a reply payload does not necessarily begin at the start of the configured fill pattern.

Reply length: The normal, expected size of an echo reply is compatible_reply_len — the larger of the negotiated Length and the mandatory field block, defined below. That, and not the negotiated Length value on its own, is the minimum: the client MUST reject a reply shorter than compatible_reply_len. (The two differ whenever the negotiated Length is smaller than the field block, including the common case of a negotiated Length of 0.) There is exactly one verified case in which a reply is longer, and the required tolerance is scoped to it — see below. This is not a general rule that overlong replies are acceptable; outside that one case, a client MUST keep applying its ordinary strict validation to unexpectedly sized datagrams.

The one case: dual-field midpoint from upstream 0.9.1. When midpoint timestamps are negotiated, upstream 0.9.1 servers emit two midpoint timestamp fields on the wire — the midpoint wall field followed by the midpoint monotonic field, in that order — even when the negotiated clock selects only one clock. A single-clock midpoint reply therefore carries one 8-byte field more than the negotiated parameters imply. (This describes bytes on the wire only; it implies nothing about how any server represents a midpoint internally.)

The extra field enlarges the reply's minimum size; it does not add 8 bytes to every reply. Writing normal_header for the field block the negotiated parameters imply and upstream_header for that block plus one 8-byte timestamp field:

normal_header   = negotiated field block
upstream_header = normal_header + one 8-byte timestamp field

compatible_reply_len     = max(negotiated_length, normal_header)
upstream_0_9_1_reply_len = max(negotiated_length, upstream_header)

Three distinct quantities, not to be conflated: negotiated_length is the value of the negotiated Length parameter; normal_header is the negotiated mandatory field block; compatible_reply_len is the actual normal packet length implied by both.

So the excess is +8 while the negotiated length is at or below normal_header, shrinks through +7…+1 between the two minima, and is 0 once the negotiated length reaches upstream_header — there the extra field displaces 8 bytes of payload instead of lengthening the datagram. Those figures are values the difference takes across different negotiations. For any one set of negotiated Params both quantities are fixed numbers, and the upstream reply has exactly one length.

Required tolerance. When the negotiated parameters are StampAt = Midpoint with a single Clock, a conforming client MUST accept a reply whose length is exactly upstream_0_9_1_reply_len. It MUST NOT require the extra field to be present, and MUST NOT treat its presence as an error.

Where upstream_0_9_1_reply_len > compatible_reply_len, that form is identifiable by length alone and the difference between the two values is between 1 and 8 bytes. This is one extra accepted length, not a +1..+8 window: a client MUST NOT accept an arbitrary length in that span, and MUST reject any length strictly between compatible_reply_len and upstream_0_9_1_reply_len just as it rejects any other unexpected length.

Accepted echo reply lengths, in full. Compute both values once from the negotiated Params. A conforming client then accepts exactly these lengths:

Received packet_len	Condition	Outcome
== compatible_reply_len	always	accepted — the normal exact form
== upstream_0_9_1_reply_len	single-clock Midpoint and upstream_0_9_1_reply_len > compatible_reply_len	accepted — the identifiable upstream midpoint compatibility form
any other value	—	rejected

When upstream_0_9_1_reply_len == compatible_reply_len the two rows collapse: the packet is accepted at the normal exact length, the wire form is ambiguous, and no generic monotonic correction is applied (see below).

Values read by a positional decoder. The extra field is last, and field offsets are derived from the negotiated parameters:

• Clock = wall: the negotiated field comes first, so the value read is correct.
• Clock = monotonic: the first 8-byte region holds the wall-domain value, so an ordinary positional decoder reads a nanoseconds-since-epoch magnitude into its monotonic slot instead of a process-relative one.

Do not correct for that blindly. Once the negotiated length reaches upstream_header, the upstream form and a conforming single-clock form produce datagrams of the same size, and nothing distinguishes them — the second 8-byte region is a timestamp under one form and ordinary payload under the other. A client MAY take its monotonic value from the second region only when the dual-field form is otherwise identifiable — that is, when upstream_0_9_1_reply_len > compatible_reply_len for the negotiated Params and the datagram length is exactly upstream_0_9_1_reply_len. In the equal-length regime (upstream_0_9_1_reply_len == compatible_reply_len) the value SHOULD be recorded as ambiguous rather than guessed. Either way the packet MUST still be accepted, and a client that applies no correction MUST NOT fail on the resulting implausible value. See the server specification, Section 11.3.1. [Verified 2026-08-11, extended 2026-08-11 with a negotiated-length sweep — see Section 19.14.]

8.5.1 Close Request Packet

Direction: Client → Server
Flags: Close (0x04) set. Reply (0x02) clear. HMAC (0x08) if applicable.

Header fields present:

• Magic (3 bytes)
• Flags (1 byte)
• HMAC (16 bytes) — if applicable
• Connection Token (8 bytes)

No sequence number, no payload.

8.6 Parameter Serialization Format

Parameters are serialized as a sequence of tag-value pairs in the packet payload during the open request and open reply.

Each parameter is encoded as:

1. Tag: Unsigned varint (LEB128 encoding).
2. Value: Signed varint (zigzag + LEB128 encoding), EXCEPT for string-typed values.

For string-typed values, the value is:

1. Length as unsigned varint.
2. Raw UTF-8 bytes.

Varint encoding: This uses the same variable-length integer encoding as Google Protocol Buffers:

• Unsigned varint (uvarint): Standard unsigned LEB128. Each byte uses the high bit as a continuation flag. The remaining 7 bits contribute to the value, least significant group first.
• Signed varint (varint): Uses zigzag encoding: (v << 1) ^ (v >> 63) for encoding, decoded as (uv >> 1) ^ -(uv & 1). This maps signed integers to unsigned integers so that small-magnitude values (positive and negative) have compact encodings.

See Section 19.4 for cross-language verification notes.

Parameter tags:

Tag	Name	Value Type	Unit / Encoding	Description
1	ProtocolVersion	Signed varint	Integer	Protocol version (currently 1)
2	Duration	Signed varint	Nanoseconds	Test duration
3	Interval	Signed varint	Nanoseconds	Send interval
4	Length	Signed varint	Bytes	Packet length
5	ReceivedStats	Signed varint	Enum (see below)	Server received packet statistics mode
6	StampAt	Signed varint	Enum (see below)	Server timestamp mode
7	Clock	Signed varint	Enum (see below)	Clock selection for timestamps
8	DSCP	Signed varint	Integer (TOS byte value)	IP TOS/Traffic Class byte value (see Section 10.8)
9	ServerFill	String (length-prefixed)	UTF-8, max 32 bytes	Server payload fill mode

Parameters with a zero value MAY be omitted from serialization (they will default to zero on the receiving end).

Unknown parameter tags MUST be silently ignored by the receiver.

There is no protocol limit on the size of a received parameter payload; a receiver MUST tolerate a payload larger than any it would itself produce. Allocating at least 128 bytes for the parameter buffer is a safe local implementation choice, not a protocol rule (see Section 19.10).

ReceivedStats enum values:

Value	Name	Meaning
0	None	No received packet statistics
1	Count	Include received packet count
2	Window	Include 64-bit received window
3	Both	Include both count and window

StampAt enum values:

Value	Name	Meaning
0	None	No server timestamps
1	Send	Timestamp at server send
2	Receive	Timestamp at server receive
3	Both	Timestamps at both server receive and send
4	Midpoint	Midpoint timestamp (average of receive and send)

Clock enum values:

Value	Name	Meaning
1	Wall	Wall clock only
2	Monotonic	Monotonic clock only
3	Both	Both wall and monotonic clocks

---

9. Versioning and Compatibility

9.1 Protocol Version

The protocol version is negotiated during the open phase. The current (and only) protocol version is 1.

A conforming client MUST set ProtocolVersion to 1 in its open request.

A conforming client MUST verify that the server's returned protocol version matches exactly. If there is a mismatch, the client MUST abort the session.

Do not depend on the server to signal the mismatch. Upstream 0.9.1 servers accept any value in the ProtocolVersion parameter — including 0, 2, a negative value, or the tag being absent entirely — rewrite it to 1, create a normal session, and return an open reply with the Close flag clear and a non-zero token. A server MAY reject an unknown version by replying with the Close flag set and a zero token, but existing servers do not. [Verified 2026-08-11 — see Section 19.13.]

9.2 Unknown Fields and Extensions

Unknown parameter tags in the negotiation payload MUST be silently ignored.

Reserved flag bits (4-7) MUST NOT be set. Packets with unknown flag bits set MUST be rejected.

9.3 Server Versions

This specification targets interoperability with servers implementing protocol version 1, as found in IRTT versions 0.9.0 and later. Earlier development versions (0.1.x) used an incompatible protocol and are not supported.

---

10. Client Configuration Parameters

The following configuration parameters affect protocol behavior:

10.1 Server Address

• Effect: Determines the destination for all packets.
• Default port: 2112.
• Valid values: Hostname, IPv4 address, IPv6 address (in brackets), optionally with port.

10.2 Duration

• Effect: How long the client sends test packets.
• Default: 60 seconds (1 minute).
• Valid values: Positive duration.
• Protocol: Sent as nanoseconds in the Duration parameter. The server MAY reduce this value.

10.3 Interval

• Effect: Time between successive test packets.
• Default: 1 second.
• Valid values: Positive duration.
• Protocol: Sent as nanoseconds in the Interval parameter. The server MAY increase this value (enforce minimum interval). The server MAY also decrease it to stay within its timeout constraints.

10.4 Length

• Effect: Total UDP payload length of each test packet.
• Default: 0, which means the packet is the minimum size needed for the header fields.
• Valid values: 0 or positive integer. The actual minimum is determined by the header fields present.
• Protocol: Sent in the Length parameter. The server MAY reduce this.

10.5 Received Stats

• Effect: What statistics the server includes about received packets.
• Default: Both (count + window).
• Valid values: None (0), Count (1), Window (2), Both (3).

10.6 Timestamp Mode (StampAt)

• Effect: When the server records timestamps.
• Default: Both (send + receive).
• Valid values: None (0), Send (1), Receive (2), Both (3), Midpoint (4).
• Note: The server MAY restrict timestamps (e.g., allow only single or no timestamps).

10.7 Clock Selection

• Effect: Which clock(s) are used for server timestamps.
• Default: Both (wall + monotonic).
• Valid values: Wall (1), Monotonic (2), Both (3).

10.8 DSCP

• Effect: Sets the TOS/Traffic Class byte in the IP header for both client and server packets during the active test phase.
• Default: 0 (best effort).
• Wire encoding (protocol fact): the DSCP parameter carries the raw IP TOS / Traffic Class byte, range 0–255 — not a 6-bit codepoint. The differentiated-services codepoint occupies the upper 6 bits of that byte and the lower 2 (ECN) are typically zero, so Expedited Forwarding is 0xb8 (184) on the wire. Other common values: 0 (best effort), 0xa0 (CS5), 0x20 (CS1). [Verified 2026-04-28 — see BLACKBOX_VERIFICATION_REPORT.md Finding B.]
• Out of scope — user-facing notation. Whether an implementation's command line and configuration accept a 0–63 codepoint (shifting it left by two to produce the wire byte) or the raw 0–255 byte is a presentation decision for that project, to be made and implemented separately. It is not a protocol fact and this specification does not prescribe it.
• Protocol: For negotiated values in 0..=255, the server echoes packets with that DSCP value. The server MAY disallow DSCP and reset it to 0. Negative and out-of-range handling is host-specific; see IRTT_SERVER_PROTOCOL_SPEC.md Section 20.
• Observed behavior: DSCP/TOS is applied only to echo request and echo reply packets. Open and close packets use TOS=0 regardless of the negotiated DSCP value. [Verified 2026-04-28 — Finding C.]
• Scope of the previous bullet (clarified 2026-08-12). "Open and close packets" means standalone datagrams: the open request, the open reply, and the client's close request. A server-initiated close is not one of them — it is an ordinary echo reply that additionally sets the Close flag, and it carries the session's in-range negotiated marking like any other echo reply. A client must not expect such a reply to arrive unmarked. See IRTT_SERVER_PROTOCOL_SPEC.md Sections 15.2 and 20.

10.9 Open Timeouts

• Effect: Controls retransmission during the open phase.
• Default: 1s, 2s, 4s, 8s.
• Valid values: List of positive durations, each >= 200ms.

10.10 Wait (Drain Period)

• Effect: How long to wait after the last send for outstanding replies.
• Default: 3 times the maximum observed RTT, falling back to 4 seconds if no RTT has been measured.
• Variants:
  • A factor of maximum observed RTT, with a fallback duration if no RTT is available.
  • A factor of mean observed RTT, with a fallback duration if no RTT is available.
  • A fixed duration.

10.11 HMAC Key

• Effect: When set, an MD5-based HMAC is computed over each packet and included in the HMAC field. The server MUST also have the same key.
• Default: None (no HMAC).
• Protocol: When an HMAC key is configured, the HMAC flag (0x08) is set in every packet.

10.12 Server Fill

• Effect: Requests the server to fill reply payloads with specific data.
• Default: Not specified (server uses its default fill).
• Valid values: String, max 32 characters. Common values: "none", "rand", "pattern:XXXX" (hex pattern).
• Protocol: The server MAY restrict this to allowed fill types.

10.13 No-Test Mode

• Effect: Opens a connection and immediately closes it without running a test. Useful for parameter validation.
• Protocol: Both the Open and Close flags are set in the open request.

10.14 Loose Mode

• Effect: When enabled, the client accepts server-restricted parameters with a warning instead of aborting.
• Default: Disabled (strict mode).

---

11. Timing Semantics

11.1 Timestamp Capture Points

• Client send timestamp: SHOULD be captured as close as possible to the send system call. For best RTT accuracy, the timestamp should be taken immediately after the send call returns.

• Client receive timestamp: SHOULD be captured as close as possible to the receive system call return, before any packet processing.

• Server timestamps: Determined by the negotiated StampAt parameter:

  • Receive: the server's arrival instant for the request.
  • Send: the server's departure instant for the reply.
  • Midpoint: the average of the two.

  A client can rely on the pair bracketing the server's handling of that request, and on receive never being later than send. It cannot observe, and MUST NOT assume, anything about where a given server takes those readings internally or how much of its own send and receive path falls outside them.

11.2 Clock Types

A conforming client MUST track both wall clock and monotonic clock times for client-side timestamps. The monotonic clock SHOULD be used for all duration calculations (RTT, IPDV) because it is immune to system time adjustments. The wall clock is needed for one-way delay calculations.

11.3 Send Scheduling

The client sends packets on a fixed isochronous schedule:

1. Record the start time.
2. The ideal send time for packet N is: start + N * interval.
3. The client SHOULD send each packet as close to its ideal send time as the system timer allows.
4. The client SHOULD compensate for cumulative timer drift so that packets remain aligned to integer multiples of the interval from the start time. The specific drift-compensation strategy is implementation-defined.
5. Before each send, the client checks whether the next scheduled time would be at or past start + duration. If so, sending stops.

The observable effect is that packets are sent at approximately start + 0, start + interval, start + 2*interval, etc., with the last packet sent strictly before start + duration.

11.4 Duration and Count Interaction

• The expected packet count is ceil(duration / interval). [Verified 2026-04-28 — see BLACKBOX_VERIFICATION_REPORT.md Finding A.]
• The duration is exclusive: the last packet is sent at approximately start + (ceil(duration / interval) - 1) * interval, which is strictly before start + duration.
• Example: duration=1s, interval=200ms → packets at 0ms, 200ms, 400ms, 600ms, 800ms = 5 packets = ceil(1000/200).
• Example: duration=1s, interval=1s → packet at 0ms only = 1 packet = ceil(1000/1000). The packet at 1000ms is NOT sent (exclusive end).

11.5 Timer Compensation

The client SHOULD use timer error compensation to improve send accuracy. The specific compensation algorithm is implementation-defined. Any approach that produces accurate isochronous sending is acceptable.

11.6 Drain Period

After the last packet is sent, if not all replies have been received, the client MUST wait for outstanding replies for the configured wait duration before closing the session.

---

12. Measurement Semantics

12.1 Round-Trip Time (RTT)

RTT MUST be calculated using client-side monotonic clock values:

RTT = client_receive_mono - client_send_mono

If both server send and receive timestamps are available (monotonic preferred, wall clock as fallback), the server processing time SHOULD be subtracted:

server_processing_time = server_send - server_receive
RTT = (client_receive_mono - client_send_mono) - server_processing_time

This subtraction SHOULD only be applied when both server timestamps are available. See Section 19.12 for edge-case behavior when server processing time appears to exceed the raw round-trip time.

12.2 One-Way Delay

One-way delay requires wall clock timestamps and externally synchronized clocks (e.g., NTP, PTP). Values are only meaningful when clocks are synchronized.

send_delay = server_best_receive_wall - client_send_wall
receive_delay = client_receive_wall - server_best_send_wall

Where "best receive" prefers the actual receive timestamp, falling back to the send timestamp if receive is not available (and vice versa for "best send"). For midpoint timestamps, both best_receive and best_send are the midpoint value.

12.3 Packet Loss

packet_loss_percent = 100 * (packets_sent - unique_replies_received) / packets_sent

If the received count is available from the server:

upstream_loss_percent = 100 * (packets_sent - server_packets_received) / packets_sent
downstream_loss_percent = 100 * (server_packets_received - unique_replies_received) / server_packets_received

12.4 Duplicate Packets

A duplicate is a reply with a sequence number for which a reply has already been recorded. Duplicates MUST be counted but MUST NOT update the original round-trip data for that sequence number.

duplicate_percent = 100 * duplicates / total_packets_received

12.5 Late Packets (Out-of-Order)

A late packet is one whose sequence number is lower than the most recently received sequence number.

late_packets_percent = 100 * late_packets / total_packets_received

12.6 IPDV (Jitter)

IPDV is the difference in delay between two successive successfully received replies. It is only calculable for sequence number N when both packet N and packet N-1 have received replies.

round_trip_ipdv[N] = RTT[N] - RTT[N-1]
send_ipdv[N] = send_delay[N] - send_delay[N-1]         (if timestamps available)
receive_ipdv[N] = receive_delay[N] - receive_delay[N-1] (if timestamps available)

For send and receive IPDV, monotonic clock differences are RECOMMENDED over wall clock differences when both are available, as the monotonic clock is not subject to NTP adjustments. Note that IPDV does NOT require synchronized clocks — only consistent clocks within each endpoint.

12.7 Server Processing Time

When both server send and receive timestamps are available:

server_processing_time = server_send - server_receive

Prefer monotonic clock values if available; fall back to wall clock.

12.8 Per-Packet Upstream/Downstream Loss (Received Window)

When the 64-bit received window is present in a reply:

• Bit 0 (LSB) represents the current packet (the one being replied to).
• Bit 1 represents the packet with sequence number one less than current, etc.
• A set bit means the server received that packet; a clear bit means it did not.

Bit 0 (LSB) is always set in a window emitted by a server, since it represents the current packet which was received. [Verified 2026-04-28 — see Section 19.7.] Implementations SHOULD treat a window value of 0 as potentially invalid and avoid using it for loss classification. Note that upstream 0.9.1 servers never emit 0 when the window is negotiated at all. [Verified 2026-08-11 — see Section 19.15.]

A window of 0x1 carries no historical information. Upstream 0.9.1 servers reset the window to 0x1 — not merely fail to update it — whenever a request arrives with a sequence number lower than the highest already seen, or with a gap of 64 or more from the previous request. 0x1 does not mean the previous 63 packets were lost; it means no useful prior received-history is represented in the window after that transition. A single reordered packet discards everything the window knew about the previous 63 sequence numbers, and later packets rebuild it from scratch. A client that reads 0x1 literally will misclassify up to 63 earlier packets as lost upstream after one reordering event.

A conforming client SHOULD treat a window value of 0x1 on any reply other than the first of the session as "no historical information available" rather than as "the server received nothing earlier." [Verified 2026-08-11 — see Section 19.15 and test-vectors/SERVER_BEHAVIORAL_VECTORS.md Section 1.]

The client processes the received window to classify previous packets:

• If a packet was not received by the client but the window says the server received it → lost downstream.
• If a packet was not received by the client and the window says the server did not receive it → lost upstream.
• If the window cannot confirm (e.g., more than 64 packets ago, or the window carries no history) → generic loss.

The window has a maximum lookback of 63 packets (bits 1-63).

Scope note. The paragraphs above state what the window field represents on the wire, which is what was verified. The downstream/upstream loss classification built on top of it is a client-side interpretation question that has not been audited to the same standard here, and it is scheduled for its own review on the implementation side. Treat the classification rules as a starting point rather than as verified protocol semantics.

12.9 Statistics

For RTT, send delay, receive delay, and IPDV, a conforming client SHOULD calculate:

• Minimum, Maximum, Mean, Median, Standard Deviation, Variance.
• Total count (N).

Median requires storing all values. The method of computing running statistics is implementation-defined.

---

13. Validation Rules

13.1 Magic Bytes

Every received packet MUST begin with the magic bytes 0x14 0xA7 0x5B. Packets with incorrect magic MUST be discarded.

13.2 Flag Validation

Reserved flag bits (4-7) MUST be zero. Packets with invalid flag bits MUST be discarded.

13.3 Reply Flag

All packets received by the client MUST have the Reply flag (0x02) set. Packets without the Reply flag MUST be discarded.

13.4 HMAC Validation

If an HMAC key is configured:

• Received packets MUST have the HMAC flag set.
• The HMAC MUST be validated:
  1. Extract the HMAC value from the packet.
  2. Zero the HMAC field in the packet buffer.
  3. Compute HMAC-MD5 over the entire packet buffer.
  4. Compare the computed HMAC with the extracted value using a constant-time comparison.
• Packets with missing or invalid HMAC MUST be discarded.

If no HMAC key is configured:

• Received packets MUST NOT have the HMAC flag set. Packets with an unexpected HMAC MUST be discarded.

13.5 Sequence Number Validation

Echo reply sequence numbers MUST correspond to a previously sent packet. Replies with sequence numbers outside the range [0, packets_sent) MUST be rejected.

13.6 Timestamp Consistency

If both receive and send timestamps are present in a reply, they MUST use the same clock mode (both wall, both monotonic, or both sets). Inconsistent clock modes MUST cause the packet to be rejected.

Midpoint timestamps MUST be exclusive — if a midpoint timestamp is present, no receive or send timestamp fields may also be present.

13.7 Close Flag in Echo Reply

A server MAY forcibly end a session mid-test by setting the Close flag (0x04) on an otherwise complete echo reply. This is the only in-band mechanism for a server-initiated close; there is no standalone server close packet.

A client MUST handle this case. On receiving an echo reply with the Close flag set, the client MUST stop the test, MUST NOT send further test packets for that session, and SHOULD report the partial results gathered so far as a successful (if truncated) run rather than as an error.

Whether the close-flagged reply's own measurement is recorded is an implementation choice. Upstream 0.9.1 clients discard it: the run is terminated on the "server closed" condition before the measurement is recorded.

The session token is invalid from that moment; a close request the client sends afterwards will be silently dropped by the server, which is normal.

[Verified 2026-08-11 — see Section 19.3 and IRTT_SERVER_PROTOCOL_SPEC.md Section 15.2.]

---

14. Error Handling

Error Category	Client Behavior
Name resolution failure	MUST abort.
Socket creation / bind failure	MUST abort.
Server unreachable (all open timeouts exhausted)	MUST abort. No partial results.
Protocol version mismatch	MUST abort.
Server restriction rejected (strict mode)	MUST abort.
Server restriction accepted (loose mode)	SHOULD warn, continue.
DSCP not supported by OS	MUST abort if DSCP was requested non-zero.
DF bit not supported by OS	MUST abort if DF was requested non-default.
Open reply with Close flag (not no-test)	MUST abort (server rejected session).
Zero connection token (without close flag)	MUST abort.
Send error during test	SHOULD abort, report partial results.
Receive error during test	SHOULD abort, report partial results.
Individual malformed packet during test	SHOULD abort.
Short reply (shorter than compatible_reply_len, the normal compatible reply length — not merely shorter than the negotiated Length)	SHOULD abort.
Reply at an unexpected length (any length other than compatible_reply_len, or the single-clock midpoint form at exactly upstream_0_9_1_reply_len)	SHOULD abort. See Section 8.5.
Stamp-at mismatch in reply	SHOULD abort.
Clock mismatch in reply	SHOULD abort.
Unexpected sequence number	SHOULD abort.
Context cancellation (user interrupt)	SHOULD stop gracefully, close connection, report partial results.
Insufficient resources for test parameters	MUST abort.

---

15. Result Model

After a test, the client implementation SHOULD expose the following information:

15.1 Per-Packet Data (Round Trips)

For each sent packet (indexed by sequence number):

• Sequence number.
• Lost status: not lost, lost (generic), lost upstream, lost downstream.
• Client send timestamp (wall + monotonic).
• Client receive timestamp (wall + monotonic) — empty if lost.
• Server receive timestamp (wall and/or monotonic) — as negotiated.
• Server send timestamp (wall and/or monotonic) — as negotiated.
• Computed RTT.
• Computed send delay.
• Computed receive delay.
• Computed IPDV (round-trip, send, receive) relative to previous packet.

15.2 Aggregate Statistics

• Test start time (wall + monotonic).
• Actual test duration.
• Packets sent.
• Packets received (unique).
• Packet loss percentage.
• Upstream loss percentage (if server count available).
• Downstream loss percentage (if server count available).
• Duplicate count and percentage.
• Late packet count and percentage.
• RTT statistics: min, max, mean, median, stddev, variance.
• Send delay statistics (if timestamps available).
• Receive delay statistics (if timestamps available).
• IPDV statistics (round-trip, send, receive).
• Server processing time statistics.
• Bytes sent and received.
• Send and receive bitrate.
• Timer error statistics.
• Timer miss count and percentage.
• Wait duration actually used.

15.3 Configuration

• Local and remote addresses (resolved).
• Negotiated parameters.
• Originally supplied parameters.
• IP version used.

15.4 Errors

• Send error (if the send operation failed).
• Receive error (if the receive operation failed).

---

16. Interoperability Requirements

1. A conforming client MUST be able to open a session with a compatible IRTT server running protocol version 1.

2. A conforming client MUST send open requests with correctly serialized parameters using the varint-encoded tag-value format.

3. A conforming client MUST correctly parse server open replies, including restricted parameters.

4. A conforming client MUST include the connection token in all post-open packets.

5. A conforming client MUST send test packets in the negotiated format, with the correct field layout and packet length.

6. A conforming client MUST correctly match replies to sent packets using sequence numbers.

7. A conforming client MUST tolerate UDP reordering, duplication, and loss.

8. A conforming client MUST validate magic bytes, flags, and HMAC on all received packets.

9. A conforming client SHOULD produce RTT measurements consistent with upstream implementations within the precision of the system clocks.

10. A conforming client MUST send a close packet at the end of the session.

11. A conforming client MUST correctly handle the HMAC calculation: compute HMAC-MD5 over the full packet with the HMAC field zeroed.

12. When computing an outgoing HMAC, the client MUST: a. Set the HMAC flag bit. b. Zero the HMAC field. c. Compute HMAC-MD5 over the entire packet buffer. d. Write the resulting MAC into the HMAC field.

---

17. Black-Box Test Plan

Test 1: Basic Connectivity

• Setup: Start an upstream IRTT server with default settings.
• Client config: Default parameters (1s interval, 1m duration), reduce to 5s duration for testing. Server address: localhost.
• Expected: Session opens, packets are exchanged, results include RTT measurements, session closes cleanly.
• Pass criteria: Non-zero packets_sent and packets_received. RTT values present. No errors.

Test 2: Parameter Negotiation

• Setup: Start a server with --max-length=100.
• Client config: Request length 200.
• Expected (strict mode): Client aborts with server restriction error.
• Expected (loose mode): Client continues with length 100.
• Pass criteria (strict): Client exits with error indicating server reduced length.
• Pass criteria (loose): Successful test with negotiated length 100.

Test 3: HMAC Authentication

• Setup: Start server with --hmac=testkey.
• Client config: --hmac=testkey.
• Expected: Session succeeds.
• Pass criteria: Successful test with no errors.
• Variant: Client uses wrong key. Expected: open timeout (server drops packets with bad HMAC silently).

Test 4: Packet Capture Verification

• Setup: Start server on localhost. Capture with tcpdump on the loopback interface, port 2112.
• Client config: Short test (5s, 1s interval).
• Expected: Capture shows:
  • Open request: magic bytes 14 a7 5b, flags=0x01, followed by varint params in payload.
  • Open reply: magic bytes, flags=0x03 (open+reply), 8-byte token, params.
  • Echo requests: magic bytes, flags=0x00, 8-byte token, 4-byte sequence number.
  • Echo replies: magic bytes, flags=0x02 (reply), 8-byte token, 4-byte sequence number, optional stats and timestamps.
  • Close request: magic bytes, flags=0x04.
• Pass criteria: All packets have correct magic, flags, and field layout.

Test 5: Sequence Number Handling

• Setup: Server with default settings.
• Client config: 10s duration, 200ms interval (expect ~51 packets).
• Expected: Reply sequence numbers are in range [0, packets_sent). Results show correct per-packet data.
• Pass criteria: All received replies have valid sequence numbers. No unexpected sequence number errors.

Test 6: Timestamp Modes

• Setup: Server with default settings.
• Variants:
  • --tstamp=none --clock=wall
  • --tstamp=send --clock=wall
  • --tstamp=receive --clock=monotonic
  • --tstamp=both --clock=both
  • --tstamp=midpoint --clock=both
• Expected: Each variant produces the correct timestamp fields in replies. RTT is always available. One-way delay is only available with wall clock timestamps.
• Pass criteria: Results match expected availability of delay measurements.

Test 7: Loss Detection

• Setup: Use a network impairment tool (e.g., tc netem loss 10%) or a server on a lossy link.
• Client config: 30s duration, 100ms interval.
• Expected: packet_loss_percent is non-zero. With --stats=both, upstream and downstream loss are differentiated.
• Pass criteria: Loss percentages are reported. With received window, per-packet loss direction is classified.

Test 8: IPv6

• Setup: Server listening on IPv6 (::1).
• Client config: -6 ::1.
• Expected: Successful test over IPv6.
• Pass criteria: IP version in results is IPv6.

Test 9: No-Test Mode

• Setup: Server with default settings.
• Client config: -n localhost.
• Expected: Connection opens, parameters are negotiated, connection closes immediately. No test packets sent.
• Pass criteria: No round-trip data. No errors.

Test 10: Large Packet Size

• Setup: Server with default settings.
• Client config: -l 1472 -d 5s localhost.
• Expected: Successful test with 1472-byte packets.
• Pass criteria: Non-zero results.

Test 11: Server Fill

• Setup: Server with --allow-fills=rand.
• Client config: --sfill=rand -l 172 -d 5s localhost.
• Expected: Successful test. Server fills reply payloads with random data.
• Pass criteria: Test completes without error.

Test 12: DSCP

• Setup: Server with default settings (DSCP allowed).
• Client config: --dscp=46 -d 5s localhost.
• Expected: Packets are sent with EF DSCP marking. Capture verification shows TOS/TC field set.
• Pass criteria: Test completes. Packet capture confirms DSCP value.

---

18. Packet Test Vectors

18.1 Echo Request with HMAC

Scenario: Echo request with HMAC, received stats (both), timestamps (both, both clocks), pattern fill 0xFF 0xFE 0xFD 0xFC, 92-byte packet (76-byte header + 16-byte payload). [Size corrected 2026-04-28 — originally described as 256 bytes, but HMAC verification confirms the test vector is 92 bytes. See BLACKBOX_VERIFICATION_REPORT.md Finding E.]

Connection token: 0x886bc9a722b33eea (little-endian)
Sequence number: 0x6fe2a1bb (little-endian)
HMAC key: 0x3c 0x68 0x1d 0x39 0x41 0x1d 0x72 0x43

Fields present (in order):

1. Magic: 3 bytes
2. Flags: 1 byte (0x08 = HMAC)
3. HMAC: 16 bytes
4. Connection Token: 8 bytes
5. Sequence Number: 4 bytes
6. Received Count: 4 bytes (zeroed)
7. Received Window: 8 bytes (zeroed)
8. Receive Wall: 8 bytes (zeroed)
9. Receive Mono: 8 bytes (zeroed)
10. Send Wall: 8 bytes (zeroed)
11. Send Mono: 8 bytes (zeroed)

Header total: 3+1+16+8+4+4+8+8+8+8+8 = 76 bytes
Payload: 92 - 76 = 16 bytes of repeating pattern

Hex (92 bytes):

14 a7 5b 08 e7 03 41 e7 d4 08 cf 69 41 f3 f4 78
5a 56 0c 4c ea 3e b3 22 a7 c9 6b 88 bb a1 e2 6f
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 ff fe fd fc
ff fe fd fc ff fe fd fc ff fe fd fc

Field breakdown:

• Bytes 0-2: Magic 14 a7 5b
• Byte 3: Flags 08 (HMAC set)
• Bytes 4-19: HMAC e7 03 41 e7 d4 08 cf 69 41 f3 f4 78 5a 56 0c 4c
• Bytes 20-27: Connection Token ea 3e b3 22 a7 c9 6b 88 (LE: 0x886bc9a722b33eea)
• Bytes 28-31: Sequence Number bb a1 e2 6f (LE: 0x6fe2a1bb)
• Bytes 32-35: Received Count (zeroed)
• Bytes 36-43: Received Window (zeroed)
• Bytes 44-51: Receive Wall Timestamp (zeroed)
• Bytes 52-59: Receive Mono Timestamp (zeroed)
• Bytes 60-67: Send Wall Timestamp (zeroed)
• Bytes 68-75: Send Mono Timestamp (zeroed)
• Bytes 76+: Payload (pattern fill)

Client behavior: This packet is sent to the server during the active test phase.

18.2 Echo Reply with HMAC and Full Timestamps

Scenario: Echo reply with HMAC, received stats (both), timestamps (both, both clocks), pattern fill, 92-byte packet (76-byte header + 16-byte payload). [Size corrected 2026-04-28 — see Finding E.]

Connection token: 0xe666ceb6766fcbc3 (little-endian)
Sequence number: 0x1d3b0706 (little-endian)
HMAC key: 0xda 0xb3 0xe9 0x04 0xa6 0x87 0x92 0x49
Received count: 0xa3bc9f19 (little-endian)
Received window: 0xd7e939e586f83b9b (little-endian)

Timestamps (little-endian int64):

• Receive wall: 0x525af13dee2a75a1
• Receive mono: 0x2d5562223e4ac69a
• Send wall: 0x589705d446293f69
• Send mono: 0x461df12fdd2c5066

Fields present (in order):

1. Magic: 3 bytes
2. Flags: 1 byte (0x08 = HMAC, plus 0x02 = Reply → but let's verify from the test vector)
3. HMAC: 16 bytes
4. Connection Token: 8 bytes
5. Sequence Number: 4 bytes
6. Received Count: 4 bytes
7. Received Window: 8 bytes
8. Receive Wall: 8 bytes
9. Receive Mono: 8 bytes
10. Send Wall: 8 bytes
11. Send Mono: 8 bytes

Note on flags: The flags byte in this test vector is 0x08 (only HMAC set). This vector is provided for verifying field layout and HMAC computation only. In actual protocol operation, the Reply flag (0x02) MUST also be set on all server-to-client packets, making the expected flags byte 0x0A for a normal HMAC echo reply. Implementers MUST set the Reply flag in actual protocol exchanges; the HMAC computation itself does not depend on the Reply flag's value.

Hex (first 92 bytes):

14 a7 5b 08 d2 98 a3 4a 6a 13 41 02 68 b2 67 a8
d6 7e 28 25 c3 cb 6f 76 b6 ce 66 e6 06 07 3b 1d
19 9f bc a3 9b 3b f8 86 e5 39 e9 d7 a1 75 2a ee
3d f1 5a 52 9a c6 4a 3e 22 62 55 2d 69 3f 29 46
d4 05 97 58 66 50 2c dd 2f f1 1d 46 ff fe fd fc
ff fe fd fc ff fe fd fc ff fe fd fc

Field breakdown:

• Bytes 0-2: Magic 14 a7 5b
• Byte 3: Flags 08 (HMAC; see note above about Reply flag)
• Bytes 4-19: HMAC d2 98 a3 4a 6a 13 41 02 68 b2 67 a8 d6 7e 28 25
• Bytes 20-27: Connection Token c3 cb 6f 76 b6 ce 66 e6 (LE: 0xe666ceb6766fcbc3)
• Bytes 28-31: Sequence Number 06 07 3b 1d (LE: 0x1d3b0706)
• Bytes 32-35: Received Count 19 9f bc a3 (LE: 0xa3bc9f19)
• Bytes 36-43: Received Window 9b 3b f8 86 e5 39 e9 d7 (LE: 0xd7e939e586f83b9b)
• Bytes 44-51: Receive Wall a1 75 2a ee 3d f1 5a 52 (LE: 0x525af13dee2a75a1)
• Bytes 52-59: Receive Mono 9a c6 4a 3e 22 62 55 2d (LE: 0x2d5562223e4ac69a)
• Bytes 60-67: Send Wall 69 3f 29 46 d4 05 97 58 (LE: 0x589705d446293f69)
• Bytes 68-75: Send Mono 66 50 2c dd 2f f1 1d 46 (LE: 0x461df12fdd2c5066)
• Bytes 76+: Payload (pattern fill)

Expected client behavior: Validate magic, validate HMAC, extract connection token, extract sequence number, extract received stats, extract timestamps, record round-trip data.

---

19. Open Questions / Verification Required

19.1 Open Request Field Layout — ✅ RESOLVED

Status: Verified 2026-04-28, irtt 0.9.1, macOS arm64.

Result: The open request does NOT include a connection token field. The layout is: magic (3) + flags (1) + [HMAC (16) if applicable] + params. Verified by packet capture (captures/full-session.pcapng, captures/hmac-session.pcapng).

19.2 Minimum Packet Length Calculation — ✅ RESOLVED

Status: Verified 2026-04-28, irtt 0.9.1, macOS arm64.

Result: Minimum echo packet lengths verified for all stats/tstamp/clock combinations. See BLACKBOX_VERIFICATION_REPORT.md Section 19.2 for the complete table. The minimum is 16 bytes (no stats, no timestamps) and the maximum default is 76 bytes (both+both+both+HMAC).

19.3 Server Close During Test — ✅ RESOLVED

Status: Verified 2026-08-11, irtt 0.9.1, macOS arm64.

Result: Yes. A server that enforces a maximum test duration answers the first otherwise-serviceable echo request after its hard deadline with a complete, ordinary echo reply that additionally has the Close flag set, and removes the session at the same moment. The deadline is the configured maximum duration plus a 2-second grace, measured from the session's first echo request that is actually served. Measured: a 1-second maximum produced a close-flagged reply 3.01 s after the first echo; a 2-second maximum produced one at 4.06 s.

Refined 2026-08-12. This entry previously said the deadline was measured from the session's first echo request, and that the first request after the deadline carries the flag. A later boundary sweep narrowed both ends. For the origin, a request that is dropped — the two classes tested were exceeding the maximum length and arriving from a foreign source endpoint — does not start the clock, and a later served echo does. For the trigger, a deadline-crossing request that was rate-limited did not carry the flag; the next served echo did. The corresponding behavior for other independently dropped post-deadline request classes was not tested and is not specified here. The earlier measurements above are unaffected, because their first request was served and their triggering request was too. The same sweep showed the 2-second margin to be additive across configured maxima of 500 ms, 1 s and 3 s. See IRTT_SERVER_PROTOCOL_SPEC.md Section 15.2 and BLACKBOX_VERIFICATION_REPORT.md Finding S-23; nothing a client does depends on the distinction, since a conforming client never reaches the deadline.

A conforming client never reaches this deadline, because it stops sending at the negotiated duration. The mechanism exists to bound sessions from clients that ignore the negotiation.

Observed upstream 0.9.1 client reaction: it discards the close-flagged reply's measurement, terminates the run with a "server closed connection" condition, prints the partial results, and exits with a success status.

No other server condition was observed to set the Close flag on an echo reply: idle expiry, shutdown, rate limiting, oversize requests and authentication failure were each exercised and none produced one.

See Section 13.7, IRTT_SERVER_PROTOCOL_SPEC.md Section 15.2, and captures/server-close.pcapng (frame 36 carries flags 0x06).

19.4 Varint Encoding Compatibility — ✅ RESOLVED

Status: Verified 2026-04-28, irtt 0.9.1, macOS arm64.

Result: Parameters decoded from captured packets match expected values using standard protobuf-style zigzag + LEB128. All parameter tags and values verified. See BLACKBOX_VERIFICATION_REPORT.md Section 19.4.

19.5 HMAC Computation Scope — ✅ RESOLVED

Status: Verified 2026-04-28, irtt 0.9.1, macOS arm64.

Result: HMAC-MD5 is computed over the entire packet buffer (including payload) with the 16-byte HMAC field zeroed. Cross-checked with a separately written Python script for all four packet types (open request, echo request, echo reply, close request). The spec's test vectors (18.1 and 18.2) also verify correctly at 92-byte packet size.

19.6 Send Timestamp Capture Timing — OPEN (not externally testable)

This is an implementation-internal detail that cannot be verified via black-box testing. The client SHOULD capture timestamps as close to the send/receive system calls as possible (see Section 11.1), but the exact timing is an implementation choice.

19.7 Server Received Window Validity — ✅ RESOLVED

Status: Verified 2026-04-28, irtt 0.9.1, macOS arm64.

Result: Bit 0 (LSB) of the received window is always set for valid windows (it represents the current packet which was received). Observed window values: seq 0 → 0x01, seq 1 → 0x03, seq 2 → 0x07. A window value of 0 can be used as the invalid sentinel. See BLACKBOX_VERIFICATION_REPORT.md Section 19.7.

Extended 2026-08-11. Upstream 0.9.1 was subsequently confirmed never to emit 0 when the window is negotiated at all, and the far more common 0x1 was found to be a valid window carrying no history — which is a distinct condition from the 0 sentinel and must not be treated the same way. See Section 19.15 and Section 12.8.

19.8 Open Reply Without HMAC When Client Expects HMAC — ✅ RESOLVED

Status: Verified 2026-04-28, irtt 0.9.1, macOS arm64.

Result: The server silently drops packets with missing or invalid HMAC. The client times out with [OpenTimeout] no reply from server. Same behavior for wrong key and no key. See BLACKBOX_VERIFICATION_REPORT.md Section 19.8.

19.9 Minimum Restricted Interval Safety Floor — ✅ RESOLVED

Status: Verified 2026-08-11, irtt 0.9.1, macOS arm64.

Result: The safety floor is 1 second, and it is enforced in loose mode as well as strict mode.

The test uses an ordinary, unmodified server: a server restricts the negotiated interval to at most one quarter of its idle timeout, so an idle timeout below 4 seconds forces a reduction below 1 second for a client requesting 1 second.

Server idle timeout	Returned interval	Client outcome
2 s	500 ms	Aborts: reduction below 1 s — strict and loose
3 s	750 ms	Aborts: reduction below 1 s — strict and loose
4 s	1 s (no reduction for a 1 s request)	Proceeds

A reduction to exactly 1 second (requesting 2 s against a 4 s idle timeout) is treated as an ordinary server restriction: rejected in strict mode, accepted in loose mode.

See test-vectors/SERVER_BEHAVIORAL_VECTORS.md Section 4.4.

19.10 Maximum Parameter Buffer Size — ✅ RESOLVED (as a local choice)

Status: Verified 2026-08-11, irtt 0.9.1, macOS arm64.

Result: There is no protocol limit on the size of a received parameter payload. An open request carrying over 200 bytes of parameters (80 repetitions of an unknown tag) was accepted and answered normally by an upstream server.

The largest payload a version-1 peer can legitimately produce remains small: the observed maximum from a real client was 52 bytes, and the theoretical maximum with all tags at their widest encodings plus a 32-byte ServerFill string is under 90 bytes. Allocating at least 128 bytes for the parameter buffer is a safe implementation choice, not a protocol requirement, and a receiver SHOULD tolerate larger payloads rather than rejecting them.

19.11 Field Ordering Verification — ✅ RESOLVED

Status: Verified 2026-04-28, irtt 0.9.1, macOS arm64.

Result: The field ordering in Section 8.1.3 is correct. Verified with six different field combinations including no optional fields, various stats/tstamp combinations, midpoint timestamps, and HMAC. See BLACKBOX_VERIFICATION_REPORT.md Section 19.11.

19.12 RTT When Server Processing Time Exceeds Raw Round-Trip — OPEN / Verification Required

Status: Not tested. Hard to trigger on localhost.

Question: When server processing time (as reported by server timestamps) exceeds the client-measured round-trip time — possible due to clock granularity or drift — the subtraction would produce a negative RTT. Should the client skip the subtraction, clamp to zero, or report the negative value?

This edge case requires server processing time to exceed the raw client-measured RTT, which is extremely unlikely under normal conditions.

19.13 Server-Side Protocol Version Enforcement — ✅ RESOLVED

Status: Verified 2026-08-11, irtt 0.9.1, macOS arm64.

Result: Upstream servers do not enforce the protocol version. Open requests carrying ProtocolVersion values of 0, 2 and −1, and requests omitting the tag entirely, each produced a session-creating open reply with flags 0x03 (Open|Reply), a non-zero token, and ProtocolVersion = 1 in the returned parameters.

Consequence for the client: the mismatch check in Sections 6.2 and 9.1 is the only line of defence and MUST be implemented. A client that assumes the server will reject it will silently run a test against an incompatible peer.

19.14 Reply Length Longer Than Negotiated — ✅ RESOLVED

Status: Verified 2026-08-11, irtt 0.9.1, macOS arm64. Extended 2026-08-11 with a negotiated-length sweep and a version comparison.

Result: Yes, in one specific, verified case. When midpoint timestamps are negotiated with a single clock (wall only or monotonic only), upstream 0.9.1 servers emit both midpoint fields on the wire — wall field then monotonic field — which is one 8-byte field more than the negotiated parameters imply. Measured across all combinations of received-stats and clock with midpoint timestamps; confirmed at the application layer by an upstream client reporting 36-byte packets while receiving 44-byte datagrams, and completing normally.

The excess is bounded by the ordinary length rule, not constant. Reply length is the larger of the negotiated length and the field block; the extra field enlarges only the field block. Measured with received-stats = both, midpoint, wall (normal_header 36, upstream_header 44): negotiated lengths 0, 16, 32, 36 → 44-byte replies; 37 → 44 (+7); 40 → 44 (+4); 43 → 44 (+1); 44 → 44 (0); 45, 64, 1024, 4096 → exactly the negotiated length (0). At 4096 the midpoint region still contains both fields — the extra field displaces payload rather than extending the datagram. Any claim that upstream replies are simply "the negotiated length plus 8" is wrong outside the first regime. Each cell of that sweep is a different negotiation with a single reply length; the +7 / +4 / +1 figures are differences between negotiations, never alternative lengths available within one.

Scope of the requirement. For single-clock midpoint the client MUST accept a reply at exactly upstream_0_9_1_reply_len. Where that value exceeds compatible_reply_len the form is identifiable by length alone and the two values differ by between 1 and 8 bytes — but that is one additional accepted length, not a +1..+8 window, and a length strictly between the two MUST be rejected like any other unexpected length. That is the whole of the tolerance: it does not generalise to accepting arbitrary overlong echo replies, and the client MUST continue to reject replies shorter than compatible_reply_len — the normal compatible reply length, not merely the negotiated Length value — and to validate every other unexpectedly sized datagram strictly. It MUST NOT require the extra field to be present.

The monotonic-only ambiguity. Once the negotiated length reaches upstream_header, the upstream and conforming forms are the same size and are not distinguishable from the datagram alone. A client MUST NOT unconditionally read the second 8-byte region as the monotonic value whenever midpoint + monotonic is negotiated — against a conforming server that region is ordinary payload. Apply a correction only when the dual-field form is otherwise identifiable, meaning upstream_0_9_1_reply_len > compatible_reply_len and the datagram is exactly that length; otherwise record the value as ambiguous, and accept the packet either way. See the server specification, Section 11.3.1.

A server that emits only the negotiated fields is also fully interoperable: a server built to do so was driven by the upstream 0.9.1 client for wall-only, monotonic-only and dual-clock midpoint configurations and every run completed cleanly. Upstream 0.9.0 behaves that way on the wire; the dual-field form appears in 0.9.1 and is unchanged in the tested post-0.9.1 tree.

19.15 Received Window After Reordering or a Large Gap — ✅ RESOLVED

Status: Verified 2026-08-11, irtt 0.9.1, macOS arm64.

Result: The window is reset to 0x1, not merely left unshifted, in both of these cases:

• a request whose sequence number is lower than the highest already seen (reordering, or a late gap fill);
• a request whose sequence number is 64 or more ahead of the previous one.

The count still increments. A gap of exactly 63 preserves the older packet in bit 63; a gap of 64 discards everything.

The window value 0 was never observed; bit 0 is always set. 32-bit sequence wraparound is handled as ordinary modular arithmetic and does not disturb the window.

Full input → output tables are in test-vectors/SERVER_BEHAVIORAL_VECTORS.md Section 1, with a capture in captures/server-recv-window.pcapng. See Section 12.8 for the classification consequence.

---

20. Non-Goals

This specification does not require:

• Matching upstream source layout, file organization, or module structure.
• Matching upstream private names (functions, types, variables).
• Matching upstream internal algorithms where equivalent behavior can be achieved independently.
• Matching exact CLI text output.
• Implementing the server.
• Implementing every optional upstream feature in the first milestone.
• Implementing timer compensation with any specific algorithm (only accurate send timing is required).
• Implementing any specific concurrency model.
• Using any specific programming language features or libraries.
• Supporting IRTT protocol versions other than 1.
• Supporting the development-era (0.1.x) protocol.