Crate irtt_proto 

Low-level wire encode/decode support for the IRTT protocol.

irtt-proto intentionally mirrors protocol fields closely: request/reply structs expose wire-oriented values, flags, counters, timestamps, and parameter enums rather than higher-level policy decisions. Higher-level crates such as irtt-client are responsible for session behavior and user-facing validation.

Most applications should depend on irtt-client or irtt-server instead of this crate directly; use irtt-proto only when implementing another IRTT-compatible client or server that needs the raw packet layer itself.

Params::decode rejects malformed or incompatible incoming parameter values, including invalid enum discriminants, malformed UTF-8, and oversized server_fill values. Direct construction followed by Params::encode performs no additional validation, so callers that build Params manually are responsible for validating those values before sending them.

Parameters are optional on the wire, and an absent tag takes its wire default — zero for every integer field, and Clock::Unspecified for the clock. A receiver that must distinguish an omitted tag from one explicitly encoded as zero uses Params::decode_with_presence, which runs the same parser and additionally reports a ParamPresence.

The crate also provides packet layout calculation, packet encoding and decoding, and optional HMAC placement, computation, and verification helpers. Encoder hmac_key arguments are authoritative: Some(key) adds FLAG_HMAC, while None removes it from caller-supplied reply flags.

Directional model

Requests use one encoder and one decoder for all three request kinds: encode_request builds a request from borrowed sender-side values, and decode_request structurally classifies an inbound request without a key, negotiated Params, or any session state. verify_packet_hmac authenticates a packet separately, once the applicable key is known — FLAG_HMAC being present is a statement about layout, not about validity.

Replies keep type-specific decoders (decode_open_reply, decode_echo_reply) because a client already knows from its session state which reply kind to expect, and the two need genuinely different semantic context.

Example

The normal path is directional: a sender encodes with encode_request, a receiver classifies with decode_request, and authentication is a separate step once the applicable key is known.

use irtt_proto::{
    decode_request, encode_request, verify_packet_hmac, DecodedRequestKind, Params,
    RequestToEncode,
};

// Sender side: encode an authenticated open request.
let params = Params::with_protocol_defaults();
let key = b"example key";
let packet = encode_request(
    RequestToEncode::Open { params: &params, no_test: false },
    Some(key),
).unwrap();

// Receiver side: classify structurally, before any key is known.
let request = decode_request(&packet).unwrap();
assert!(request.hmac_present);
let DecodedRequestKind::Open { no_test, params: encoded } = request.kind else {
    panic!("expected an open request");
};
assert!(!no_test);
assert_eq!(Params::decode(encoded).unwrap(), params);

// Authentication is a separate step, once the applicable key is known.
verify_packet_hmac(key, &packet).unwrap();

Re-exports

pub use echo::decode_echo_reply;

pub use echo::encode_echo_reply;

pub use echo::EchoReply;

pub use echo::TimestampFields;

pub use error::ProtoError;

pub use error::Result;

pub use hmac::compute_hmac;

pub use hmac::compute_hmac_in_place;

pub use hmac::verify_hmac;

pub use hmac::verify_packet_hmac;

pub use layout::echo_header_len;

pub use layout::echo_packet_len;

pub use layout::PacketLayout;

pub use open::decode_open_reply;

pub use open::encode_open_reply;

pub use open::OpenReply;

pub use params::Clock;

pub use params::DecodedParams;

pub use params::ParamPresence;

pub use params::Params;

pub use params::ReceivedStats;

pub use params::ServerFill;

pub use params::StampAt;

pub use params::MAX_SERVER_FILL_BYTES;

pub use request::decode_request;

pub use request::encode_request;

pub use request::DecodedRequest;

pub use request::DecodedRequestKind;

pub use request::RequestToEncode;

pub use flags::*;

Modules

echo

error

flags

hmac

layout

open

params

request

Directional request codecs: one sender-side encoder and one receiver-side structural decoder.

varint

Variable-length integer encoding for IRTT wire values.

Constants

HMAC_SIZE

MAGIC

PROTOCOL_VERSION

RECV_COUNT_SIZE

RECV_WINDOW_SIZE

SEQ_SIZE

TIMESTAMP_SIZE

TOKEN_SIZE