chore(release): publish docs for irtt-proto, irtt-server, irtt-stats

Version the remaining public crates independently so their crate-specific READMEs, examples, and API doctests are represented in release history.

.gitea/workflows/ci.yml

@@ -7,7 +7,6 @@ on:
   pull_request:
     branches:
       - main
-  merge_group:
   workflow_dispatch:
 
 permissions:
@@ -29,10 +28,10 @@ jobs:
           persist-credentials: false
 
       - name: Install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
         with:
           components: rustfmt
-          cache-key: fmt
+          cache: false
 
       - name: Check formatting
         uses: actions-rust-lang/rustfmt@4066006ec54a31931b9b1fddfd38f2fdf2d27143 # v1
@@ -49,10 +48,10 @@ jobs:
           persist-credentials: false
 
       - name: Install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
         with:
           components: clippy
-          cache-key: clippy
+          cache: false
 
       - name: Run clippy
         run: |
@@ -79,46 +78,22 @@ jobs:
       matrix:
         include:
           - task: check
-            runner: ubuntu-24.04
             target: x86_64-unknown-linux-gnu
             musl: false
 
           - task: test
-            runner: ubuntu-24.04
             target: x86_64-unknown-linux-gnu
             musl: false
 
           - task: check
-            runner: ubuntu-24.04
             target: x86_64-unknown-linux-musl
             musl: true
 
           - task: test
-            runner: ubuntu-24.04
             target: x86_64-unknown-linux-musl
             musl: true
 
-          - task: check
+    runs-on: ubuntu-latest
-            runner: ubuntu-24.04-arm
-            target: aarch64-unknown-linux-gnu
-            musl: false
-
-          - task: test
-            runner: ubuntu-24.04-arm
-            target: aarch64-unknown-linux-gnu
-            musl: false
-
-          - task: check
-            runner: ubuntu-24.04-arm
-            target: aarch64-unknown-linux-musl
-            musl: true
-
-          - task: test
-            runner: ubuntu-24.04-arm
-            target: aarch64-unknown-linux-musl
-            musl: true
-
-    runs-on: ${{ matrix.runner }}
     timeout-minutes: 25
 
     steps:
@@ -134,10 +109,10 @@ jobs:
           sudo apt-get install --no-install-recommends musl-tools
 
       - name: Install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
         with:
           target: ${{ matrix.target }}
-          cache-key: ${{ matrix.task }}-${{ matrix.target }}
+          cache: false
 
       - name: Run ${{ matrix.task }} with all features
         run: |
@@ -172,9 +147,9 @@ jobs:
           persist-credentials: false
 
       - name: Install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
         with:
-          cache-key: docs
+          cache: false
 
       - name: Check docs
         run: |
@@ -183,3 +158,6 @@ jobs:
             --all-features \
             --no-deps \
             --locked
+
+      - name: Run doctests
+        run: cargo test --workspace --doc --all-features --locked

.gitea/workflows/docker-publish.yml

@@ -0,0 +1,99 @@
+name: Publish irtt-server image
+
+on:
+  push:
+    tags:
+      # This repo tags each crate independently (irtt-proto/vX, irtt-client/vX,
+      # ...); only the app package's tag corresponds to this image.
+      - "irtt-rs/v*"
+  workflow_dispatch:
+
+env:
+  IMAGE_NAME: irtt-server
+  IMAGE_OWNER: lochnair
+  GITEA_REGISTRY: git.lochnair.net
+  GHCR_REGISTRY: ghcr.io
+  # Pinned so a floating "latest" release doesn't silently change the build.
+  CRANE_VERSION: v0.20.2
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Determine image tags
+        id: meta
+        run: |
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            version="${GITHUB_REF_NAME#irtt-rs/v}"
+            echo "version=${version}" >> "$GITHUB_OUTPUT"
+            echo "tags=${version},latest" >> "$GITHUB_OUTPUT"
+          else
+            # Manual dispatch off a branch: tag by commit only, never touch
+            # "latest", so an ad-hoc build can't clobber the last release.
+            version="sha-$(git rev-parse --short HEAD)"
+            echo "version=${version}" >> "$GITHUB_OUTPUT"
+            echo "tags=${version}" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Cross-compilation is handled inside the Dockerfile via tonistiigi/xx
+      # (native builds, no emulation), but buildx still needs a driver that
+      # can assemble a multi-platform manifest list.
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
+
+      - name: Log in to Gitea Container Registry
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        with:
+          registry: ${{ env.GITEA_REGISTRY }}
+          # The automatic per-job token comes back unauthorized for package
+          # writes on this instance, so use a PAT (scope: write:package) instead.
+          # (Secret names can't start with GITEA_/GITHUB_, hence REGISTRY_*.)
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        with:
+          registry: ${{ env.GHCR_REGISTRY }}
+          username: ${{ secrets.GHCR_USERNAME }}
+          password: ${{ secrets.GHCR_TOKEN }}
+
+      - name: Build tag list
+        id: tags
+        run: |
+          IFS=',' read -ra tag_list <<< "${{ steps.meta.outputs.tags }}"
+          gitea_tags=""
+          for t in "${tag_list[@]}"; do
+            gitea_tags="${gitea_tags}${GITEA_REGISTRY}/${IMAGE_OWNER}/${IMAGE_NAME}:${t},"
+          done
+          echo "gitea=${gitea_tags%,}" >> "$GITHUB_OUTPUT"
+
+      # Gitea is the primary publish target: this is the only build. Every
+      # other registry gets an exact digest copy of this same image (see
+      # below), never a separate build, so the hash matches everywhere.
+      - name: Build and push to Gitea
+        id: build
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.tags.outputs.gitea }}
+
+      - name: Install crane
+        run: |
+          mkdir -p "${HOME}/.local/bin"
+          curl -sL "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" \
+            | tar -xz -C "${HOME}/.local/bin" crane
+          echo "${HOME}/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Duplicate image to GHCR (same digest, no rebuild)
+        run: |
+          source_ref="${GITEA_REGISTRY}/${IMAGE_OWNER}/${IMAGE_NAME}@${{ steps.build.outputs.digest }}"
+          IFS=',' read -ra tag_list <<< "${{ steps.meta.outputs.tags }}"
+          for t in "${tag_list[@]}"; do
+            crane copy "${source_ref}" "${GHCR_REGISTRY}/${IMAGE_OWNER}/${IMAGE_NAME}:${t}"
+          done

.gitea/workflows/fuzz.yml

@@ -0,0 +1,81 @@
+name: Fuzz Smoke
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  # Pinned for reproducibility; bump deliberately alongside `fuzz/Cargo.lock`.
+  CARGO_FUZZ_VERSION: 0.13.1
+  CARGO_FUZZ_SHA256: 86edc9b8f20c29ff07c3e5fcd67bc3f0784b3b960a5428635060f20d50555461
+  FUZZ_TOOLCHAIN: nightly-x86_64-unknown-linux-gnu
+  FUZZ_TARGET: x86_64-unknown-linux-gnu
+
+jobs:
+  fuzz-smoke:
+    name: cargo fuzz smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install stable Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
+        with:
+          cache: false
+
+      - name: Install nightly Rust toolchain
+        # Installed alongside, but deliberately not made the directory
+        # default: cargo-fuzz itself is built with the default stable
+        # toolchain below, and only `fuzz build`/`fuzz run` are run with
+        # the GNU-host nightly below. Building cargo-fuzz's own dependency
+        # tree under a nightly override can trip build scripts (e.g. rustix) that gate
+        # unstable internal attributes on detecting a nightly compiler.
+        run: rustup toolchain install "${FUZZ_TOOLCHAIN}" --profile minimal --no-self-update
+
+      - name: Install cargo-fuzz
+        run: |
+          set -euo pipefail
+          archive="cargo-fuzz-${CARGO_FUZZ_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/rust-fuzz/cargo-fuzz/releases/download/${CARGO_FUZZ_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${CARGO_FUZZ_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" cargo-fuzz
+          install -Dm755 cargo-fuzz "${RUNNER_TEMP}/bin/cargo-fuzz"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: Build all fuzz targets
+        # libFuzzer sanitizers require dynamically linked GNU binaries; the
+        # runner's default Rust host can be static musl.
+        run: RUSTUP_TOOLCHAIN="${FUZZ_TOOLCHAIN}" cargo fuzz build --target "${FUZZ_TARGET}"
+        working-directory: fuzz
+
+      - name: Run bounded fuzz smoke for every target
+        # A single job building once and running each target sequentially
+        # avoids recompiling the fuzz workspace per target. Ten seconds per
+        # target is enough to catch a broken harness or an obvious
+        # regression; this is not meant to be exhaustive fuzzing.
+        run: |
+          set -euo pipefail
+          for target in decode_request decode_open_reply decode_echo_reply decode_params decode_varint server_core_datagrams; do
+            echo "::group::fuzz smoke: ${target}"
+            RUSTUP_TOOLCHAIN="${FUZZ_TOOLCHAIN}" cargo fuzz run --target "${FUZZ_TARGET}" "${target}" -- \
+              -max_total_time=10 \
+              -timeout=5
+            echo "::endgroup::"
+          done
+        working-directory: fuzz

.gitea/workflows/interop-netem.yml

@@ -30,15 +30,16 @@ jobs:
           persist-credentials: false
 
       - name: Install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
         with:
-          cache-key: interop-netem
+          cache: false
 
-      - name: Check host tools
+      - name: Check host tools and network administration access
         run: |
           ip -V
           tc -V
           go version
+          sudo -n true
 
       - name: Install upstream irtt
         run: |
@@ -46,8 +47,8 @@ jobs:
           go install "github.com/heistp/irtt/cmd/irtt@${IRTT_UPSTREAM_VERSION}"
           "$GOBIN/irtt" version
 
-      - name: Build irtt-rs CLI
+      - name: Build irtt-rs client
-        run: cargo build -p irtt-cli --locked
+        run: cargo build -p irtt-rs --bin irtt-client --locked
 
       - name: Run netem interop comparisons
         run: |
@@ -55,21 +56,21 @@ jobs:
             --all \
             --skip-build \
             --upstream-irtt "$GOBIN/irtt" \
-            --irtt-rs-command "$PWD/target/debug/irtt-cli"
+            --irtt-rs-command "$PWD/target/debug/irtt-client"
 
       - name: Append netem interop summary
         if: always()
         run: |
           latest_summary="$(find target/interop-netem -mindepth 2 -maxdepth 2 -name github-step-summary.md -type f -print 2>/dev/null | sort | tail -n 1)"
           if [ -n "$latest_summary" ]; then
-            cat "$latest_summary" >> "$GITHUB_STEP_SUMMARY"
+            cat "$latest_summary" >> "$GITEA_STEP_SUMMARY"
           else
-            echo "No netem interop github-step-summary.md found." >> "$GITHUB_STEP_SUMMARY"
+            echo "No netem interop github-step-summary.md found." >> "$GITEA_STEP_SUMMARY"
           fi
 
       - name: Upload netem interop artifacts
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        uses: https://gitea.com/actions/gitea-upload-artifact@v7
         with:
           name: interop-netem
           path: target/interop-netem

.gitea/workflows/semver.yml

@@ -0,0 +1,52 @@
+name: Semver
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "irtt-proto/v*.*.*"
+      - "irtt-client/v*.*.*"
+      - "irtt-server/v*.*.*"
+      - "irtt-stats/v*.*.*"
+      - "irtt-rs/v*.*.*"
+
+permissions:
+  contents: read
+
+env:
+  CARGO_SEMVER_CHECKS_VERSION: 0.50.0
+  CARGO_SEMVER_CHECKS_SHA256: 52a65dc88dc53fa8b57d6087954eb52cda149ca03bcfca78ce3fdecd23f893c4
+
+jobs:
+  semver:
+    name: cargo-semver-checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
+        with:
+          cache: false
+
+      # The CLI preserves the previous wrapper's `feature-group: all-features`
+      # behavior without its GitHub API/cache dependency.
+      - name: Install cargo-semver-checks
+        run: |
+          set -euo pipefail
+          archive="cargo-semver-checks-x86_64-unknown-linux-gnu.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/obi1kenobi/cargo-semver-checks/releases/download/v${CARGO_SEMVER_CHECKS_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${CARGO_SEMVER_CHECKS_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" cargo-semver-checks
+          install -Dm755 cargo-semver-checks "${RUNNER_TEMP}/bin/cargo-semver-checks"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: Check semver compatibility
+        run: cargo semver-checks check-release --all-features

.gitea/workflows/supply-chain.yml

@@ -0,0 +1,109 @@
+name: Supply chain
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "41 2 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  ACTIONLINT_VERSION: 1.7.7
+  CARGO_DENY_VERSION: 0.20.2
+  CARGO_DENY_SHA256: 9f12ed4c49936e09b48bf862b595cde2fe64fcbd9d74dfacac6131ca824c8d5f
+  ACTIONLINT_SHA256: 023070a287cd8cccd71515fedc843f1985bf96c436b7effaecce67290e7e0757
+
+jobs:
+  cargo-deny:
+    name: cargo-deny ${{ matrix.checks }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Advisories can appear after code was merged. Keep this visible,
+          # but don't let a surprise upstream advisory nuke every unrelated PR.
+          - checks: advisories
+            continue-on-error: true
+
+          # These are policy choices in this repo. They should block PRs.
+          - checks: bans licenses sources
+            continue-on-error: false
+
+    continue-on-error: ${{ matrix.continue-on-error }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install cargo-deny
+        run: |
+          set -euo pipefail
+          archive="cargo-deny-${CARGO_DENY_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/EmbarkStudios/cargo-deny/releases/download/${CARGO_DENY_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${CARGO_DENY_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" --strip-components=1 \
+            "cargo-deny-${CARGO_DENY_VERSION}-x86_64-unknown-linux-musl/cargo-deny"
+          install -Dm755 cargo-deny "${RUNNER_TEMP}/bin/cargo-deny"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: Run cargo-deny
+        run: >-
+          cargo deny --manifest-path Cargo.toml --all-features check
+          ${{ matrix.checks }}
+
+  actionlint:
+    name: actionlint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install actionlint
+        run: |
+          set -euo pipefail
+          archive="actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${ACTIONLINT_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" actionlint
+          install -Dm755 actionlint "${RUNNER_TEMP}/bin/actionlint"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: actionlint handwritten workflows
+        # actionlint validates GitHub Actions syntax. It cannot parse Gitea's
+        # required absolute action URL in interop-netem.yml, so that workflow
+        # is checked by the Gitea runner instead.
+        run: |
+          actionlint \
+            .gitea/workflows/ci.yml \
+            .gitea/workflows/docker-publish.yml \
+            .gitea/workflows/fuzz.yml \
+            .gitea/workflows/semver.yml \
+            .gitea/workflows/supply-chain.yml \
+            .github/workflows/actions-security.yml \
+            .github/workflows/ci-arm.yml \
+            .github/workflows/osv-scanner.yml \
+            .github/workflows/rust-clippy.yml
+
+      - name: actionlint generated release workflow
+        run: >-
+          actionlint -shellcheck= .github/workflows/irtt-rs-release.yml

.github/workflows/actions-security.yml

@@ -16,34 +16,6 @@ permissions:
   contents: read
 
 jobs:
-  actionlint:
-    name: actionlint
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-
-      - name: actionlint handwritten workflows
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: >-
-            .github/workflows/actions-security.yml,
-            .github/workflows/ci.yml,
-            .github/workflows/interop-netem.yml,
-            .github/workflows/osv-scanner.yml,
-            .github/workflows/rust-clippy.yml,
-            .github/workflows/semver.yml,
-            .github/workflows/supply-chain.yml
-
-      - name: actionlint generated release workflow
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: .github/workflows/irtt-cli-release.yml
-          shellcheck: false
   zizmor:
     name: zizmor
     runs-on: ubuntu-latest
@@ -60,7 +32,13 @@ jobs:
         with:
           persist-credentials: false
 
+      # Zizmor's SARIF integration publishes GitHub Code Scanning results.
+      # It remains here while portable actionlint runs with Gitea CI, but scans
+      # both workflow directories through its GitHub Actions rule set.
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054 # v0.6.2
+        uses: zizmorcore/zizmor-action@cc914d7f3750a2d13d75c7f184a1060aa0e9d482 # v0.6.4
         with:
           persona: regular
+          inputs: |
+            .github/workflows
+            .gitea/workflows

.github/workflows/ci-arm.yml

@@ -0,0 +1,80 @@
+name: Rust ARM CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  merge_group:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  verify:
+    name: cargo ${{ matrix.task }} (${{ matrix.target }})
+    # Gitea currently has only amd64 Linux runners; retain ARM coverage here.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: check
+            target: aarch64-unknown-linux-gnu
+            musl: false
+
+          - task: test
+            target: aarch64-unknown-linux-gnu
+            musl: false
+
+          - task: check
+            target: aarch64-unknown-linux-musl
+            musl: true
+
+          - task: test
+            target: aarch64-unknown-linux-musl
+            musl: true
+
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 25
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install musl toolchain
+        if: matrix.musl
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends musl-tools
+
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
+        with:
+          target: ${{ matrix.target }}
+          cache-key: ${{ matrix.task }}-${{ matrix.target }}
+
+      - name: Run ${{ matrix.task }} with all features
+        run: |
+          cargo ${{ matrix.task }} \
+            --workspace \
+            --all-targets \
+            --all-features \
+            --target ${{ matrix.target }} \
+            --locked
+
+      - name: Run ${{ matrix.task }} without default features
+        run: |
+          cargo ${{ matrix.task }} \
+            --workspace \
+            --all-targets \
+            --no-default-features \
+            --target ${{ matrix.target }} \
+            --locked

.github/workflows/irtt-rs-release.yml

@@ -42,7 +42,7 @@ on:
   pull_request:
   push:
     tags:
-      - 'irtt-cli**[0-9]+.[0-9]+.[0-9]+*'
+      - 'irtt-rs**[0-9]+.[0-9]+.[0-9]+*'
 
 jobs:
   # Run 'dist plan' (or host) to determine what tasks we need to do

.github/workflows/osv-scanner.yml

@@ -31,7 +31,7 @@ permissions:
 jobs:
   scan-scheduled:
     if: ${{ github.event_name == 'push' || github.event_name == 'schedule' }}
-    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@8deb546fdb875b9996d27d4950be7312dac076a1" # v2.5.0
+    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@a345acffa64b0eaede81a3d9aae6141214d9c8fc" # v2.6.0
     with:
       # Example of specifying custom arguments
       scan-args: |-
@@ -40,7 +40,7 @@ jobs:
         ./
   scan-pr:
     if: ${{ github.event_name == 'pull_request' || github.event_name == 'merge_group' }}
-    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@8deb546fdb875b9996d27d4950be7312dac076a1" # v2.5.0
+    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@a345acffa64b0eaede81a3d9aae6141214d9c8fc" # v2.6.0
     with:
       # Example of specifying custom arguments
       scan-args: |-

.github/workflows/rust-clippy.yml

@@ -29,7 +29,7 @@ jobs:
           persist-credentials: false
 
       - name: Install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2
         with:
           components: clippy
           cache-key: clippy-sarif
@@ -60,7 +60,7 @@ jobs:
           exit 0
 
       - name: Upload Clippy SARIF
-        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4
         if: always()
         with:
           sarif_file: rust-clippy-results.sarif

.github/workflows/semver.yml

@@ -1,31 +0,0 @@
-name: Semver
-
-on:
-  workflow_dispatch:
-  push:
-    tags:
-      - "irtt-proto/v*.*.*"
-      - "irtt-client/v*.*.*"
-      - "irtt-server/v*.*.*"
-      - "irtt-stats/v*.*.*"
-      - "irtt-cli/v*.*.*"
-
-permissions:
-  contents: read
-
-jobs:
-  semver:
-    name: cargo-semver-checks
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-
-      - name: Check semver compatibility
-        uses: obi1kenobi/cargo-semver-checks-action@6b69fcf40e9b5fb17adeb57e4b6ecd020649a239 # v2
-        with:
-          feature-group: all-features

.github/workflows/supply-chain.yml

@@ -1,79 +0,0 @@
-name: Supply chain
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-  merge_group:
-  schedule:
-    - cron: "41 2 * * 1"
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  cargo-deny:
-    name: cargo-deny ${{ matrix.checks }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          # Advisories can appear after code was merged. Keep this visible,
-          # but don't let a surprise upstream advisory nuke every unrelated PR.
-          - checks: advisories
-            continue-on-error: true
-
-          # These are policy choices in this repo. They should block PRs.
-          - checks: bans licenses sources
-            continue-on-error: false
-
-    continue-on-error: ${{ matrix.continue-on-error }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-
-      - name: Run cargo-deny
-        uses: EmbarkStudios/cargo-deny-action@3c6349835b2b7b196a839186cb8b78e02f7b5f25 # v2
-        with:
-          command: check
-          arguments: --all-features
-          command-arguments: ${{ matrix.checks }}
-
-  actionlint:
-    name: actionlint
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-
-      - name: actionlint handwritten workflows
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: >-
-            .github/workflows/actions-security.yml,
-            .github/workflows/ci.yml,
-            .github/workflows/interop-netem.yml,
-            .github/workflows/osv-scanner.yml,
-            .github/workflows/rust-clippy.yml,
-            .github/workflows/semver.yml,
-            .github/workflows/supply-chain.yml
-
-      - name: actionlint generated release workflow
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: .github/workflows/irtt-cli-release.yml
-          shellcheck: false

AGENTS.md

@@ -41,7 +41,7 @@ For compatibility questions, the verified spec and black-box observations define
 
 Main boundary:
 
-> `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` — 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-rs` (application package, `crates/irtt-app`) — 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.
@@ -51,7 +51,7 @@ Main boundary:
   - `BlockingManagedClient`: synchronous owner using a dedicated current-thread Tokio runtime.
 - `irtt-server`: exists; 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, server applet orchestration, diagnostics, and exit behavior. Do not duplicate protocol/session state machines here.
+- `irtt-rs` (application package, `crates/irtt-app`): argument parsing, managed orchestration, output, summaries, TUI, server applet orchestration, diagnostics, and exit behavior. Produces the `irtt-rs` multicall dispatcher plus the dedicated `irtt-client`, `irtt-tui`, and `irtt-server` binaries. 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. This rule is specific to `irtt-client` — do not generalize it to `irtt-server`, which has the opposite policy below.
 
@@ -66,7 +66,7 @@ Tokio must remain optional for `irtt-client`; default builds must remain runtime
 - 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.
 - Ownership is layered and the layers do not blur: `Server` is the one-listener primitive (one socket, one `ServerCore`, one sequential loop), and `ServerSet` supervises one or more of them without owning protocol or session state itself. A common `ServerConfig` is cloned into each listener, so its bounds — `max_sessions` included — are per listener and not per process. Listeners share nothing else: no shared `ServerCore`, no global session table or token namespace, no shared clock, and one sequential sender per socket, which is what keeps the socket-wide reply traffic class race-free.
-- The CLI server applet exists behind the `irtt-cli` `server` feature, which is part of that crate's default build. It is thin orchestration/configuration over reusable `irtt-server` — one current-thread Tokio runtime, one repeatable `--bind`, one `ServerSet` — and must not grow a second server state machine. **It always uses `ServerSet`, including for a single bind**: there is no direct CLI-to-`Server` path and no bind-count branch, so startup, shutdown and listener-failure semantics are identical whatever was configured, and the singleton case exercises the same orchestration in normal use. Hostname resolution, interface expansion, daemonization, and configuration files are deliberately absent.
+- The server applet exists behind the `irtt-rs` application package's `server` feature, which is part of that crate's default build. It is thin orchestration/configuration over reusable `irtt-server` — one current-thread Tokio runtime, one repeatable `--bind`, one `ServerSet` — and must not grow a second server state machine. **It always uses `ServerSet`, including for a single bind**: there is no direct CLI-to-`Server` path and no bind-count branch, so startup, shutdown and listener-failure semantics are identical whatever was configured, and the singleton case exercises the same orchestration in normal use. Hostname resolution, interface expansion, daemonization, and configuration files are deliberately absent.
 - Resource policy: the server should use bounded session/resource policy. Upstream's observed lack of useful default session/per-peer bounds, and its never expiring a session that has not carried an echo request (see `IRTT_SERVER_PROTOCOL_SPEC.md`), are not interoperability requirements and must not be reproduced merely for compatibility.
 - Testing: prefer `irtt-server` for normal compliant fake-peer behavior where practical, as far as its implemented behavior reaches. Keep narrow adversarial/raw peers for intentionally malformed, ambiguous, or non-compliant wire behavior.
 
@@ -82,42 +82,44 @@ Tokio must remain optional for `irtt-client`; default builds must remain runtime
 
 ## Testing policy
 
-Tests protect durable behavior, compatibility, and important invariants. They do not exist to maximize test count or coverage percentage.
+Tests protect durable behavior, compatibility, and important invariants. They do not exist to maximize test count or coverage percentage. Tests are maintained repository code: every persistent test adds review, CI, refactoring, and maintenance cost, so it must justify that cost.
 
-### Prefer behavior over internals
+### Test at the owning layer
 
-For client, managed-runtime, blocking, CLI, and TUI behavior, prefer normal-interface component/integration tests: real UDP/session exchange, emitted events/outcomes, negotiated params, multi-target lifecycle, process exit status, and user-visible diagnostics.
+Prefer production interfaces and component/integration tests at the lowest architectural layer that owns the complete behavior. Higher-level or process-level is not inherently better.
 
-One strong behavioral test is usually better than several tests of private helpers that reconstruct the same behavior.
+- `irtt-proto`: wire formats, codecs, validation, malformed input, and protocol boundaries.
+- `irtt-client`: client/session behavior, multi-target orchestration, burst/staggered pacing, scheduling, lifecycle, managed events, and target updates.
+- `irtt-server`: server/session behavior and server runtime/orchestration.
+- `irtt-stats`: statistics, loss/IPDV accounting, rolling windows, and retention bounds.
+- `irtt-rs` / `irtt-app`: behavior introduced by the application layer itself, such as argument-to-config mapping, presentation/formatting, app-specific diagnostics/exit policy, and genuine process/signal behavior.
 
-Do not add persistent tests merely because implementation code changed. Avoid tests that primarily:
+Do not move library behavior into application-binary tests merely to make it more end-to-end. For example, pacing and multi-target scheduling belong in `irtt-client` even though the CLI exposes them.
 
-- assert private fields, cursors, queue shapes, or exact internal representation;
+### Every persistent test must earn its place
-- mirror implementation steps line-for-line;
+
-- exercise branches/helpers solely for coverage;
+Before adding or retaining a test, be able to state the durable behavior, compatibility guarantee, regression, or invariant it protects. Other agents and humans will review tests on that basis. Do not add persistent tests merely because code changed, a branch exists, coverage would increase, or the test was useful during implementation.
+
+One strong behavioral test through a normal production interface is usually better than several tests of private helpers or reconstructed internals. Be especially skeptical of unit tests that depend on private functions, methods, structs, fields, or implementation sequence: harmless internal refactors should not require test rewrites.
+
+Avoid tests that primarily:
+
+- assert private representation or historical implementation details;
+- mirror implementation steps or exercise branches solely for coverage;
 - duplicate stronger coverage at another layer;
-- pin incidental scheduling/ordering that is not contractual;
+- pin exact human-readable wording unless that wording is itself contractual;
 - test standard-library/dependency behavior;
-- require production test-only observability for a fact naturally visible through packets/events/outcomes.
+- use subprocess machinery or test-only observability when the owning crate exposes the behavior directly.
 
-A harmless private refactor should not require widespread test rewrites unless a deliberately protected invariant changed.
+If a component/integration test through the owning crate's normal API protects the same durable behavior, prefer it unless a focused unit test materially improves precision, diagnosis, or coverage of a hard-to-observe invariant.
 
 ### Unit tests where they earn it
 
-Focused unit/table-driven tests are encouraged for stable pure or algorithmic behavior, especially:
+Focused unit/table-driven tests are appropriate for stable pure or algorithmic behavior, especially protocol codecs/vectors, statistics formulas, hand-rolled data structures, and resource/liveness invariants that cannot be observed reliably from a higher-level production interface.
-
-- `irtt-proto` layouts, codecs, vectors, HMAC, parsing, malformed input, and boundaries;
-- `irtt-stats` formulas, loss accounting, IPDV, rolling windows, and bounded state;
-- hand-rolled data structures and subtle pure invariants;
-- resource/liveness guarantees that cannot be observed reliably from a higher layer.
-
-If a unit test and a normal-interface test prove the same durable behavior, prefer the normal-interface test unless the unit test materially improves precision or diagnosis.
 
 ### Temporary implementation tests
 
-Temporary narrow tests are welcome while implementing/debugging a change to prove a hypothesis, reproduce a bug, or exercise a difficult state transition.
+Temporary narrow tests are welcome while implementing/debugging a change to prove a hypothesis, reproduce a bug, or exercise a difficult state transition. Remove or consolidate them before finalizing unless they independently protect a durable regression or invariant.
-
-Before finalizing, remove or consolidate them unless they independently protect a durable regression or invariant. A test being useful during development does not by itself justify permanent repository code.
 
 ### Resource/liveness tests and hooks
 
@@ -171,6 +173,7 @@ Use the narrowest useful checks first. For substantive workspace changes, final
 cargo fmt --all -- --check
 cargo check --workspace --all-targets --all-features --locked
 cargo test --workspace --all-targets --all-features --locked
+cargo test --workspace --doc --all-features --locked
 cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
 ```
 
@@ -192,7 +195,7 @@ Report concisely:
 
 1. what changed;
 2. verification actually run and its result;
-3. meaningful tests added/updated/consolidated/removed;
+3. meaningful tests added/updated/consolidated/removed, with justification for each persistent test added or materially expanded;
 4. remaining risks, ambiguities, or follow-ups.
 
 Do not produce a giant changelog of incidental edits.

CHANGELOG.md

@@ -10,6 +10,12 @@ release. The format is loosely based on
 
 ## irtt-proto
 
+### 0.5.1
+
+#### Added
+
+- Added a crate-specific README and runnable API doctests to make the published crate's protocol types and codecs easier to discover and use.
+
 ### 0.5.0
 
 #### Added
@@ -28,6 +34,18 @@ release. The format is loosely based on
 
 ## irtt-client
 
+### 0.5.2
+
+#### Fixed
+
+- Kernel transmit-timestamp correlation is now invalidated when a probe send fails, preventing a later timestamp from being matched to the wrong probe.
+
+### 0.5.1
+
+#### Added
+
+- `ManagedCommandReceipt::blocking_wait()` lets synchronous callers wait for a managed target-set update to be applied or rejected without entering an async runtime.
+
 ### 0.5.0
 
 #### Added
@@ -50,6 +68,24 @@ release. The format is loosely based on
 
 ## irtt-server
 
+### 0.5.3
+
+#### Added
+
+- Added a crate-specific README and usage examples for single- and multi-listener servers, plus runnable API doctests.
+
+### 0.5.2
+
+#### Changed
+
+- `parse_hex_pattern`'s chunking now uses the stable `slice::as_chunks` API instead of `chunks_exact`; no behavior change.
+
+### 0.5.1
+
+#### Added
+
+- New public `address_family_available()` helper (re-exported from `set`), for probing whether an address family can actually bind locally rather than merely constructing a socket for it. Used by the `irtt-rs` server applet to distinguish a genuinely unsupported address family from an ordinary bind failure when falling back from its default dual-family bind.
+
 ### 0.5.0
 
 #### Added
@@ -77,6 +113,12 @@ release. The format is loosely based on
 
 ## irtt-stats
 
+### 0.5.1
+
+#### Added
+
+- Added a crate-specific README, a finite-versus-continuous statistics example, and runnable API doctests for the published crate.
+
 ### 0.5.0
 
 #### Fixed
@@ -88,6 +130,55 @@ release. The format is loosely based on
 - `LateReplyMode` (`Measure` / `CountOnly`) lets a consumer choose whether replies that arrive after their probe is considered late are still fully measured into the running statistics or only counted, without affecting the other samples.
 - `StatsConfig::estimated_retained_bytes(probe_count)` gives callers an API to estimate the memory a stats configuration will retain for a given probe count, ahead of actually running a session (used by `irtt-cli`'s multi-target memory-usage warning, see below).
 
+## irtt-rs
+
+### 0.7.1
+
+#### Fixed
+
+- `IRTT_SERVER_NO_DSCP` now accepts ordinary boolean environment values such as `1` and `0`; falsey values leave DSCP marking enabled, while truthy values disable it. The `--no-dscp` command-line flag remains a flag without a value.
+
+### 0.7.0
+
+#### Added
+
+- Client target arguments now support per-target HMAC configuration: append `@hmac=KEY` to override the global `--hmac` value for that target, or use `@hmac=` to explicitly disable HMAC for it. The target syntax supports context-aware escaping for literal delimiters.
+- Continuous client runs can now take complete desired target sets from standard input with `--targets-stdin`. Each non-empty record atomically replaces the current set, `[]` selects an empty set, and EOF requests a graceful stop. The controller retains only the newest unapplied record under transient replacement backpressure, with explicit bounds on record size, desired targets, and live target generations.
+
+#### Changed
+
+- A peer-initiated close is now target-local in stdin-controlled continuous runs: the controller and other desired targets keep running, and a later desired set can start that target again.
+
+### 0.6.2
+
+#### Added
+
+- Every `irtt-server` applet flag can now also be set via an `IRTT_SERVER_*` environment variable (`IRTT_SERVER_BIND`, `IRTT_SERVER_HMAC`, `IRTT_SERVER_MAX_SESSIONS`, `IRTT_SERVER_MAX_PACKET_LENGTH`, `IRTT_SERVER_MIN_INTERVAL`, `IRTT_SERVER_BURST`, `IRTT_SERVER_IDLE_TIMEOUT`, `IRTT_SERVER_MAX_DURATION`, `IRTT_SERVER_TIMESTAMP_ALLOWANCE`, `IRTT_SERVER_NO_DSCP`), for deployments that configure by environment (containers, orchestrators) instead of command-line flags. An explicit flag on the command line still overrides the corresponding variable.
+- A `Dockerfile` and Gitea Actions workflow publishing a minimal, statically linked `irtt-server` container image (cross-compiled for `amd64`/`arm64` via `tonistiigi/xx`, no QEMU) to this project's Gitea and GHCR container registries.
+
+#### Changed
+
+- The bundled `ctrlc` dependency now enables its `termination` feature, so the applet also handles `SIGTERM` (not just `SIGINT`) for graceful shutdown.
+
+### 0.6.1
+
+#### Added
+
+- The `irtt-server` applet now has sensible zero-argument defaults: with no `--bind`, it binds the wildcard IRTT port on both address families (`[::]:2112` then `0.0.0.0:2112`) instead of requiring an explicit address, on platforms where wildcard reply-source selection is supported. Any explicit `--bind` fully replaces the default pair rather than adding to it.
+
+#### Changed
+
+- If one of the two default listeners fails because its address family has no local support on the host (e.g. IPv6 administratively disabled on an otherwise IPv4-capable host), the server now falls back to serving just the surviving family instead of failing outright. Any other failure reason (port in use, permission denied, no safe wildcard reply-source path) still fails startup as it would for an explicit `--bind`.
+
+### 0.6.0
+
+#### Changed
+
+- The application Cargo package was renamed from `irtt-cli` to `irtt-rs`, moving to `crates/irtt-app`. This is the application distribution package that produces the `irtt-rs`, `irtt-client`, `irtt-tui`, and `irtt-server` binaries; it is unrelated to the reusable `irtt-client` library crate, which keeps its existing name and version.
+- The `irtt-cli` executable was hard-renamed to `irtt-client` to avoid reading as an umbrella CLI now that the application also ships a first-class server. There is no `irtt-cli` compatibility binary or alias.
+- Dedicated binaries now have role-specific entry points (`irtt-client`, `irtt-tui`, `irtt-server`) instead of all funneling through the multicall dispatcher's argv0/subcommand logic. Each dedicated binary always runs its own role regardless of the name it is invoked or copied under, and no longer links code for the other applet roles it doesn't implement. The `irtt-rs` binary remains the feature-selectable multicall dispatcher and is the only binary that inspects argv0 or subcommands.
+- Future application releases move to the `irtt-rs/vX.Y.Z` tag namespace (previously `irtt-cli/vX.Y.Z`); see [Releasing](#releasing).
+
 ## irtt-cli
 
 ### 0.5.0
@@ -125,6 +216,8 @@ rather than in lockstep. Each crate's release is tagged as `<crate>/vX.Y.Z`
 from. `irtt-proto`, `irtt-client`, `irtt-server`, and `irtt-stats` are
 libraries published to [crates.io](https://crates.io); their tags exist to
 identify the exact source for a given crates.io release and do not produce a
-GitHub Release. `irtt-cli` is the only crate with prebuilt binary artifacts:
+GitHub Release. The application package (`irtt-cli` through 0.5.0, `irtt-rs`
-pushing an `irtt-cli/vX.Y.Z` tag triggers [cargo-dist](https://opensource.axo.dev/cargo-dist/)
+from 0.6.0 onward) is the only package with prebuilt binary artifacts: pushing
-to build and publish a GitHub Release with platform binaries.
+an `irtt-rs/vX.Y.Z` tag triggers [cargo-dist](https://opensource.axo.dev/cargo-dist/)
+to build and publish a GitHub Release with platform binaries. The historical
+`irtt-cli/v0.5.0` tag remains as released; it is not rewritten or replaced.

Cargo.lock

@@ -109,7 +109,16 @@ version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0700ddab506f33b20a03b13996eccd309a48e5ff77d0d95926aa0210fb4e95f1"
 dependencies = [
- "bit-vec",
+ "bit-vec 0.6.3",
+]
+
+[[package]]
+name = "bit-set"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
+dependencies = [
+ "bit-vec 0.8.0",
 ]
 
 [[package]]
@@ -118,6 +127,12 @@ version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "349f9b6a179ed607305526ca489b34ad0a41aed5f7980fa90eb03160b69598fb"
 
+[[package]]
+name = "bit-vec"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
+
 [[package]]
 name = "bitflags"
 version = "1.3.2"
@@ -198,9 +213,9 @@ checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
 
 [[package]]
 name = "clap"
-version = "4.6.6"
+version = "4.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"
+checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -208,9 +223,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.6.6"
+version = "4.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"
+checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d"
 dependencies = [
  "anstream",
  "anstyle",
@@ -220,14 +235,14 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.6.4"
+version = "4.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+checksum = "f9c751b79415d4e559e3d1fcf128e09e720eb673a06d26cf6f392d37d75b66e0"
 dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn 3.0.3",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -370,9 +385,9 @@ dependencies = [
 
 [[package]]
 name = "darling"
-version = "0.24.0"
+version = "0.24.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88490bf1b990d87eaaa7ac8aa887f629a08e7359765b4911faf63c3763347d23"
+checksum = "ed17f5901b6630b993ca003def43f2f8ef4014fc13b047b57aad617ff32bc2ec"
 dependencies = [
  "darling_core",
  "darling_macro",
@@ -380,26 +395,26 @@ dependencies = [
 
 [[package]]
 name = "darling_core"
-version = "0.24.0"
+version = "0.24.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "084e274f91c482280130e1e34e0b8d6e66776a060d7b6de7b84289ca778868c4"
+checksum = "6837e2cf7485aaae18f86181d2f0e9a7ed297a025e220aeabf63fdebd3a2ddff"
 dependencies = [
  "ident_case",
  "proc-macro2",
  "quote",
  "strsim",
- "syn 3.0.3",
+ "syn 3.0.5",
 ]
 
 [[package]]
 name = "darling_macro"
-version = "0.24.0"
+version = "0.24.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68f5792fa0d41cd2325ce0ffa64f0a340eaebd4971a3a0c5e1ffd2cc488a355e"
+checksum = "2ac7135c3ef02b2f7833bbeb1be5ba7f966dcde8a87c6b87f65a778d71a02785"
 dependencies = [
  "darling_core",
  "quote",
- "syn 3.0.3",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -481,9 +496,9 @@ dependencies = [
 
 [[package]]
 name = "either"
-version = "1.17.0"
+version = "1.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
+checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
 
 [[package]]
 name = "equivalent"
@@ -516,10 +531,16 @@ version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b95f7c0680e4142284cf8b22c14a476e87d61b004a3a0861872b32ef7ead40a2"
 dependencies = [
- "bit-set",
+ "bit-set 0.5.3",
  "regex",
 ]
 
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
 [[package]]
 name = "filedescriptor"
 version = "0.8.3"
@@ -689,31 +710,17 @@ dependencies = [
  "indoc",
  "proc-macro2",
  "quote",
- "syn 3.0.3",
+ "syn 3.0.5",
-]
-
-[[package]]
-name = "irtt-cli"
-version = "0.5.0"
-dependencies = [
- "clap",
- "crossterm",
- "ctrlc",
- "irtt-client",
- "irtt-proto",
- "irtt-server",
- "irtt-stats",
- "ratatui",
- "tokio",
 ]
 
 [[package]]
 name = "irtt-client"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "irtt-proto",
  "irtt-server",
  "nix 0.31.3",
+ "proptest",
  "socket2",
  "thiserror 2.0.20",
  "tokio",
@@ -731,17 +738,33 @@ dependencies = [
 
 [[package]]
 name = "irtt-proto"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "hmac",
  "md-5",
+ "proptest",
  "subtle",
  "thiserror 2.0.20",
 ]
 
+[[package]]
+name = "irtt-rs"
+version = "0.7.1"
+dependencies = [
+ "clap",
+ "crossterm",
+ "ctrlc",
+ "irtt-client",
+ "irtt-proto",
+ "irtt-server",
+ "irtt-stats",
+ "ratatui",
+ "tokio",
+]
+
 [[package]]
 name = "irtt-server"
-version = "0.5.0"
+version = "0.5.3"
 dependencies = [
  "getrandom 0.4.3",
  "irtt-proto",
@@ -753,9 +776,10 @@ dependencies = [
 
 [[package]]
 name = "irtt-stats"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "irtt-client",
+ "proptest",
 ]
 
 [[package]]
@@ -781,9 +805,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.104"
+version = "0.3.105"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
+checksum = "ce57d20d1ea864ce2ac172ab472d409214f4fd359f0b2a2775abdf522e2af99e"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -857,15 +881,15 @@ dependencies = [
 
 [[package]]
 name = "log"
-version = "0.4.33"
+version = "0.4.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
 
 [[package]]
 name = "lru"
-version = "0.18.2"
+version = "0.18.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d2f2f9b4ba7e6b24d95e7e899329d35be83bcded72c8540cdd5368932d1d90a"
+checksum = "ff9840bcc50b71349309900da0ce7279aa336ae71d73250b07998932c7d97c25"
 dependencies = [
  "hashbrown 0.17.1",
 ]
@@ -919,9 +943,9 @@ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
 
 [[package]]
 name = "mio"
-version = "1.2.2"
+version = "1.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
+checksum = "4b18443e9c262bfe8fa82f51666e2642c53393f7e5c27b3e1aeab922cff5b9d8"
 dependencies = [
  "libc",
  "log",
@@ -1094,9 +1118,9 @@ dependencies = [
 
 [[package]]
 name = "pest"
-version = "2.8.8"
+version = "2.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7df728be843c7070fab6ab7c328c4e9e9d78e23bf749c0669c86ee7ebfa050a2"
+checksum = "6d45aeb61b4bf818e12d4205f2466f8c4748f85f4fce0146d1c03d69d753f0ad"
 dependencies = [
  "memchr",
  "ucd-trie",
@@ -1104,9 +1128,9 @@ dependencies = [
 
 [[package]]
 name = "pest_derive"
-version = "2.8.8"
+version = "2.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e2dd6fc3b26b3462ee188aac870f5a41d398f1cd5e2408d16531bd71c9591fd"
+checksum = "89cc5a242e25ed4e7704d0be240f2cfbe20a8c27e7e252d94835be93d92dc39f"
 dependencies = [
  "pest",
  "pest_generator",
@@ -1114,9 +1138,9 @@ dependencies = [
 
 [[package]]
 name = "pest_generator"
-version = "2.8.8"
+version = "2.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6a7a9205cfb6f596a9e8b689c0a15f9ceb7a1aafae7aaf788150ac65b29975b6"
+checksum = "7abf21475cc3820fe4b2ca2dc2142902f67a02189f3b5b3a229f4febc01a43e5"
 dependencies = [
  "pest",
  "pest_meta",
@@ -1127,9 +1151,9 @@ dependencies = [
 
 [[package]]
 name = "pest_meta"
-version = "2.8.8"
+version = "2.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85abd351c0de1e8384fc791a0737111a350394937e92b956b743dac12429f57c"
+checksum = "adba4db388f687393c18c51348d44a41d870ca9df71a2c98172ea3035dc6936e"
 dependencies = [
  "pest",
 ]
@@ -1161,7 +1185,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
 dependencies = [
  "phf_shared",
- "rand",
+ "rand 0.8.8",
 ]
 
 [[package]]
@@ -1204,6 +1228,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
 
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -1213,6 +1246,31 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "proptest"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
+dependencies = [
+ "bit-set 0.8.0",
+ "bit-vec 0.8.0",
+ "bitflags 2.13.1",
+ "num-traits",
+ "rand 0.9.5",
+ "rand_chacha",
+ "rand_xorshift",
+ "regex-syntax",
+ "rusty-fork",
+ "tempfile",
+ "unarray",
+]
+
+[[package]]
+name = "quick-error"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
+
 [[package]]
 name = "quote"
 version = "1.0.47"
@@ -1236,11 +1294,31 @@ checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
 [[package]]
 name = "rand"
-version = "0.8.7"
+version = "0.8.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22f6172bdec972074665ed81ed53b71da00bfc44b65a753cfde883ec4c702a1a"
+checksum = "e058c7de0b26af77780c769414d6257830bb240f3c38477dbc2c16e5f54d6d4c"
 dependencies = [
- "rand_core",
+ "rand_core 0.6.4",
+]
+
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.9.5",
 ]
 
 [[package]]
@@ -1249,6 +1327,24 @@ version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
 
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
+[[package]]
+name = "rand_xorshift"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
+dependencies = [
+ "rand_core 0.9.5",
+]
+
 [[package]]
 name = "ratatui"
 version = "0.30.2"
@@ -1416,6 +1512,18 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
+[[package]]
+name = "rusty-fork"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
+dependencies = [
+ "fnv",
+ "quick-error",
+ "tempfile",
+ "wait-timeout",
+]
+
 [[package]]
 name = "ryu"
 version = "1.0.23"
@@ -1461,7 +1569,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.3",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -1520,9 +1628,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "smallvec"
-version = "1.15.2"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+checksum = "b9be42f50aa861c555654aa3a37f52f4b1074bacf4e48fe0ef7fa584e80f1f0f"
 
 [[package]]
 name = "socket2"
@@ -1597,15 +1705,28 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.3"
+version = "3.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+checksum = "12df2e0110f65b775f769bb17ef989067a1d931b2eb822bd4346631eeada89f9"
 dependencies = [
  "proc-macro2",
  "quote",
  "unicode-ident",
 ]
 
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys",
+]
+
 [[package]]
 name = "termina"
 version = "0.3.3"
@@ -1719,7 +1840,7 @@ checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.3",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -1765,7 +1886,7 @@ checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.3",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -1780,6 +1901,12 @@ version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2896d95c02a80c6d6a5d6e953d479f5ddf2dfdb6a244441010e373ac0fb88971"
 
+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -1817,9 +1944,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.24.0"
+version = "1.26.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
+checksum = "b5772d71c9be8a8a6ac2117d949c5b224c1b72241bb611d9a3012edcf8af7812"
 dependencies = [
  "atomic",
  "getrandom 0.4.3",
@@ -1842,6 +1969,15 @@ dependencies = [
  "utf8parse",
 ]
 
+[[package]]
+name = "wait-timeout"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"
@@ -1859,9 +1995,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.127"
+version = "0.2.128"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
+checksum = "aecb87a33d3b0c5e3b7aa46336eaf486cffafbd281b195e4c8b80d50df2351bf"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -1872,9 +2008,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.127"
+version = "0.2.128"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
+checksum = "a690d511e3c1a8b3a55e33511e3c2c00c78415cd23650f32b808627f5696b9ed"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -1882,22 +2018,22 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.127"
+version = "0.2.128"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
+checksum = "411e4887f0071ef2d2164a9d5fdf2d20efbef78fccd3a78b0c10a1dc5295e48a"
 dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.5",
  "wasm-bindgen-shared",
 ]
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.127"
+version = "0.2.128"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
+checksum = "81941cd78d0c92026c33e5e01312845a4cb1e9af3407f9134b100dd03144103e"
 dependencies = [
  "unicode-ident",
 ]
@@ -2016,3 +2152,23 @@ name = "wit-bindgen"
 version = "0.57.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.56"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.56"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]

Cargo.toml

@@ -4,7 +4,7 @@ members = [
     "crates/irtt-client",
     "crates/irtt-server",
     "crates/irtt-stats",
-    "crates/irtt-cli",
+    "crates/irtt-app",
     "crates/irtt-integration-tests",
 ]
 resolver = "2"
@@ -15,22 +15,19 @@ license = "Apache-2.0"
 rust-version = "1.88"
 repository = "https://github.com/Lochnair/irtt-rs"
 homepage = "https://github.com/Lochnair/irtt-rs"
-readme = "README.md"
 
 [workspace.dependencies]
 irtt-proto = { version = "0.5.0", path = "crates/irtt-proto" }
-irtt-client = { version = "0.5.0", path = "crates/irtt-client" }
+irtt-client = { version = "0.5.1", path = "crates/irtt-client" }
-irtt-server = { version = "0.5.0", path = "crates/irtt-server" }
+irtt-server = { version = "0.5.2", path = "crates/irtt-server" }
 irtt-stats = { version = "0.5.0", path = "crates/irtt-stats" }
 
 [profile.release]
 opt-level = "z"
 lto = true
 codegen-units = 1
-panic = "abort"
 strip = "symbols"
 
 # The profile that 'dist' will build with
 [profile.dist]
 inherits = "release"
-lto = "thin"

Dockerfile

@@ -0,0 +1,42 @@
+# syntax=docker/dockerfile:1
+
+# Builds the irtt-server applet only, statically linked against musl, and
+# ships it in a scratch image with no shell or libc.
+#
+# Cross-compiles for TARGETPLATFORM using tonistiigi/xx: the builder stage
+# always runs natively on BUILDPLATFORM (no QEMU emulation) and xx-cargo
+# picks the right musl target triple, sysroot, and linker for whatever
+# platform buildx asked for.
+
+FROM --platform=$BUILDPLATFORM tonistiigi/xx AS xx
+
+FROM --platform=$BUILDPLATFORM rust:1.98-alpine AS builder
+
+COPY --from=xx / /
+
+RUN apk add --no-cache clang lld file
+
+ARG TARGETPLATFORM
+RUN xx-apk add --no-cache musl-dev
+
+WORKDIR /build
+
+COPY Cargo.toml Cargo.lock ./
+COPY crates ./crates
+
+RUN xx-cargo build \
+    --release \
+    --locked \
+    -p irtt-rs \
+    --bin irtt-server \
+    --no-default-features \
+    --features server \
+    --target-dir /build/target \
+    && xx-verify /build/target/$(xx-cargo --print-target-triple)/release/irtt-server \
+    && cp /build/target/$(xx-cargo --print-target-triple)/release/irtt-server /irtt-server
+
+FROM scratch
+
+COPY --from=builder /irtt-server /irtt-server
+
+ENTRYPOINT ["/irtt-server"]

README.md

@@ -1,361 +1,180 @@
 # irtt-rs
 
-`irtt-rs` is a Rust implementation of an IRTT-compatible client and server.
+`irtt-rs` is a Rust implementation of an IRTT-compatible client and server:
+finite or continuous UDP latency probing, plus the server side those probes
+run against.
 
-It provides command-line applets and reusable Rust libraries for finite or continuous latency probing, plus the server side those probes can run against. It is intended for interactive diagnostics, scripting, monitoring, and integration into applications such as network autorate controllers.
+This is not the upstream IRTT project. For the original implementation,
-
+protocol background, and broader documentation, see
-This is not the upstream IRTT project. For the original implementation, protocol background, and broader documentation, see [heistp/irtt](https://github.com/heistp/irtt).
+[heistp/irtt](https://github.com/heistp/irtt). The installed dispatcher is
+named `irtt-rs` rather than `irtt` to avoid conflicting with or being
+mistaken for it.
 
 ## Features
 
 * Finite and continuous probe sessions
-* Concurrent probing of multiple targets
+* Concurrent probing of multiple targets, with staggered or burst pacing
-* Reusable client library with a structured event stream
+* Reusable client library with a structured event stream (blocking, Tokio,
-* Human-readable table output
+  or managed)
-* CSV, TSV, and JSON Lines output for scripts and monitoring systems
+* Human-readable table output, plus CSV, TSV, and JSON Lines for scripts and
-* Selectable output columns
+  monitoring systems, with selectable output columns
-* Automatic final summaries for eligible table-output runs
 * Optional terminal UI
 * Reusable Tokio-native server library
-* UDP server applet with explicit bind and session policy options
+* UDP server applet with sensible zero-argument defaults and explicit bind
+  and session-policy options
 * Router-friendly multi-applet binary layout
 
-The installed dispatcher is named `irtt-rs` rather than `irtt` to avoid conflicting with or being mistaken for upstream IRTT.
+## Comparison with upstream IRTT
+
+`irtt-rs` is an independent, compatible reimplementation, not a successor or
+replacement for upstream IRTT — [heistp/irtt](https://github.com/heistp/irtt)
+remains the original implementation. Interoperability is a project goal; see
+[`docs/INTEROP_COMPARISON.md`](docs/INTEROP_COMPARISON.md) and
+[`docs/protocol/`](docs/protocol/) for the black-box interoperability
+methodology and protocol baseline this project verifies against. Choose
+between them based on the capabilities and deployment model you need.
+
+The table below was checked against upstream release
+[v0.9.2](https://github.com/heistp/irtt/releases/tag/v0.9.2) (2026-07-17).
+This project's own interop testing and protocol baseline are currently
+pinned to the prior release, v0.9.1; the wire protocol version number is
+unchanged between the two, but v0.9.2 has not itself been exercised against
+this project's interop harness.
+
+| Capability | irtt-rs | upstream IRTT (v0.9.2) |
+| --- | --- | --- |
+| Wire protocol | Protocol version 1, verified against upstream v0.9.1 | Protocol version 1 (unchanged in v0.9.2) |
+| Finite probing | Supported, default 10s | Supported, default 1m |
+| Continuous/indefinite operation | Supported (`--duration 0`); still computes running statistics (see below) | Supported via streaming mode (`-s`, added in v0.9.2); computes no statistics at all in that mode |
+| Statistics in continuous mode | Running count/min/max/mean/variance per target; exact medians unavailable; bounded IPDV tracking | None in streaming mode — raw/event output only, by design, to avoid unbounded memory |
+| Multi-target probing (one invocation) | Supported, with labels and staggered/burst pacing | Not supported — one remote address per invocation |
+| Terminal UI | `irtt-tui`, a live graph/dashboard applet | Not present |
+| Output formats | table, csv, tsv, jsonl, with selectable columns | Text summary, JSON (optionally gzip to file), and a fixed-field raw mode; no CSV/TSV and no column selection |
+| Client/server library API | Separate, independently versioned Rust crates (`irtt-client`, `irtt-server`) | One combined Go package exposing both roles |
+| Server: multiple listeners | `ServerSet` supervises several listeners in one process | `ListenAndServe` also serves multiple requested addresses |
+| Server: wildcard reply-source | Default behavior on Linux/macOS/FreeBSD; refused elsewhere rather than served incorrectly | Opt-in via `--set-src-ip`, with a documented per-packet allocation cost |
+| Server: zero-argument bind | Binds the wildcard address on both families by default, gated by the platform check above | Binds the wildcard address on both families by default; no documented platform gate |
+| Prebuilt release binaries | Published for six target triples | None published; install via `go install` or manual build |
+
+Upstream has capabilities this project does not implement: a `report`
+subcommand for replaying saved JSON results, benchmarking and
+timer/clock-diagnostic subcommands, client-side payload fill and
+don't-fragment/wait-strategy/timer-algorithm controls, an operator-configurable
+server-side fill policy (this project's server always honors a session's
+negotiated fill request, with a fixed fallback pattern, but has no equivalent
+to upstream's flags for restricting or overriding it), syslog logging, and
+bundled systemd/OpenRC service files.
+
+This project has capabilities upstream does not implement: multi-target
+probing with labels, the terminal UI, CSV/TSV output with selectable
+columns, a quantified and actively-warned memory-retention model for
+long-running client sessions, and best-effort Linux kernel-timestamp
+preference for its own send/receive endpoint.
 
 ## Installation
 
 The build requires Rust 1.88 or newer.
 
-From a local checkout:
+Install the latest release from crates.io:
+
+```sh
+cargo install irtt-rs --locked
+```
+
+This installs the `irtt-rs` dispatcher plus dedicated `irtt-client`,
+`irtt-tui`, and `irtt-server` binaries. Each applet can also be built in
+isolation with `--no-default-features` plus the applet's own feature, for
+example a lightweight client-only install:
+
+```sh
+cargo install irtt-rs --locked --no-default-features --features client
+```
+
+For development, or to install directly from a checkout:
 
 ```sh
 git clone https://github.com/Lochnair/irtt-rs.git
 cd irtt-rs
-cargo install --path crates/irtt-cli
+cargo install --path crates/irtt-app --locked
-```
-
-This installs:
-
-* `irtt-rs`, the canonical multi-applet dispatcher
-* `irtt-cli`, the stream and text client
-* `irtt-server`, the UDP server
-
-To also install the optional terminal UI:
-
-```sh
-cargo install --path crates/irtt-cli --features tui
 ```
 
 ## Quick start
 
-Probe a server using the default settings:
+Probe a server:
 
 ```sh
-irtt-cli netperf-eu.bufferbloat.net:2112
+irtt-client netperf-eu.bufferbloat.net:2112 --duration 30s --interval 100ms
 ```
 
-Set the test duration and probe interval:
+Probe continuously until interrupted (`Ctrl-C`):
 
 ```sh
-irtt-cli netperf-eu.bufferbloat.net:2112 \
+irtt-client netperf-eu.bufferbloat.net:2112 --duration 0
-    --duration 30s \
-    --interval 100ms
 ```
 
-Run continuously until interrupted:
+Watch the same session live in the terminal UI:
 
 ```sh
-irtt-cli netperf-eu.bufferbloat.net:2112 --duration 0
+irtt-tui netperf-eu.bufferbloat.net:2112
 ```
 
-Use `Ctrl-C` to stop gracefully.
+Run a server with sensible defaults — no `--bind` needed:
-
-## Multiple targets
-
-Probe several targets concurrently:
 
 ```sh
-irtt-cli host-a:2112 host-b:2112
+irtt-server
 ```
 
-Every target argument accepts `[LABEL=]TARGET`. An optional `LABEL=` prefix assigns the logical
+## Documentation
-target name used in output and the TUI; without it, the target string itself is used. Assign
-stable labels to targets:
 
-```sh
+* [`docs/irtt-client.md`](docs/irtt-client.md) — target syntax, output
-irtt-cli ams=ams.example.com:2112 sg=sg.example.com:2112
+  formats and columns, measurement field definitions, finite/continuous
-```
+  memory behavior, kernel timestamps.
+* [`docs/irtt-tui.md`](docs/irtt-tui.md) — controls, continuous default,
+  retained history.
+* [`docs/irtt-server.md`](docs/irtt-server.md) — bind defaults and
+  overrides, wildcard listener behavior, session policy, HMAC.
+* [`docs/irtt-rs.md`](docs/irtt-rs.md) — the multicall dispatcher, applet
+  binary names, feature-gated builds.
+* [docs.rs](https://docs.rs) for the library crates below.
+* [`docs/protocol/`](docs/protocol/) and
+  [`docs/INTEROP_COMPARISON.md`](docs/INTEROP_COMPARISON.md) for the wire
+  protocol specification and interoperability validation against upstream
+  `irtt`.
 
-Labeled and unlabeled targets can be freely mixed in one argument list:
+Every applet also documents its full option list with `--help`.
 
-```sh
+## Crates
-irtt-cli host-a:2112 ams=ams.example.com:2112
-```
 
-Multi-target sessions use staggered pacing by default. To send each target's probes together:
+| Crate | crates.io | What it is |
+| --- | --- | --- |
+| [`irtt-rs`](crates/irtt-app) | [crates.io](https://crates.io/crates/irtt-rs) | Application package: the `irtt-rs`, `irtt-client`, `irtt-tui`, and `irtt-server` binaries |
+| [`irtt-client`](crates/irtt-client) | [crates.io](https://crates.io/crates/irtt-client) | Reusable client/session library ([docs.rs](https://docs.rs/irtt-client)) |
+| [`irtt-server`](crates/irtt-server) | [crates.io](https://crates.io/crates/irtt-server) | Reusable Tokio-native server library ([docs.rs](https://docs.rs/irtt-server)) |
+| [`irtt-stats`](crates/irtt-stats) | [crates.io](https://crates.io/crates/irtt-stats) | Statistics aggregation over `irtt-client` events ([docs.rs](https://docs.rs/irtt-stats)) |
+| [`irtt-proto`](crates/irtt-proto) | [crates.io](https://crates.io/crates/irtt-proto) | Low-level wire protocol encode/decode ([docs.rs](https://docs.rs/irtt-proto)) |
 
-```sh
+Each library crate has its own crates.io README describing what it's for and
-irtt-cli host-a:2112 host-b:2112 --pacing burst
+when to use it instead of `irtt-client`/`irtt-server` directly.
-```
-
-Target labels are included in the default multi-target output.
-
-## Output formats
-
-The CLI supports four event-row formats:
-
-* `table`: human-readable terminal output
-* `csv`: comma-separated output
-* `tsv`: tab-separated output
-* `jsonl`: one JSON object per event
-
-Examples:
-
-```sh
-irtt-cli <server> --format table
-irtt-cli <server> --format jsonl
-irtt-cli <server> --format csv \
-    --columns event,seq,remote,effective_rtt_us
-```
-
-For a stream containing only effective RTT values in microseconds:
-
-```sh
-irtt-cli <server> \
-    --format tsv \
-    --columns effective_rtt_us \
-    --header never
-```
-
-List all available columns with:
-
-```sh
-irtt-cli --list-columns
-```
-
-Useful measurement fields include:
-
-* `raw_rtt_us`: client-observed send-to-receive RTT
-* `adjusted_rtt_us`: RTT adjusted for server processing when available
-* `effective_rtt_us`: adjusted RTT when available, otherwise raw RTT
-* `sd_us` and `rd_us`: send and receive one-way delay estimates
-* `ipdv_us`: inter-packet delay variation
-* `server_processing_us`: time spent processing the packet at the server
-
-Adjusted RTT can be negative when server processing exceeds the measured raw RTT. One-way delay estimates can be negative because of clock skew between the client and server.
-
-Default table output prints a final summary after completed finite runs and interrupted continuous runs when the run policy permits it. CSV, TSV, and JSON Lines output do not print this summary.
-
-A peer closing a finite CLI or TUI run is accepted as a terminal outcome. In
-continuous mode, peer closure exits nonzero unless the user requested
-interruption, allowing a supervisor to restart the client.
-
-## Terminal UI
-
-When built with the `tui` feature, `irtt-tui` provides a live cumulative dashboard:
-
-```sh
-irtt-tui <server>
-```
-
-It runs continuously by default. A finite duration can be selected explicitly:
-
-```sh
-irtt-tui <server> --duration 30s
-```
-
-Multiple targets and pacing options work the same way as in `irtt-cli`:
-
-```sh
-irtt-tui host-a:2112 host-b:2112 --pacing burst
-```
-
-Quit with `q` or `Ctrl-C`.
-
-## Server
-
-The server applet requires at least one explicit bind address:
-
-```sh
-irtt-server --bind 127.0.0.1:2112
-```
-
-The same applet is reachable through the dispatcher:
-
-```sh
-irtt-rs server --bind 192.0.2.10:2112
-```
-
-Repeat `--bind` to serve several addresses from one process, in the order given:
-
-```sh
-irtt-server \
-    --bind 0.0.0.0:2112 \
-    --bind [::]:2112
-```
-
-Every invocation runs through the same multi-listener path, so one address is an
-ordinary set of one rather than a separate mode. The policy options below are
-applied to every listener, but the listeners are otherwise independent: each has
-its own sessions and tokens, so a session belongs to the address it was opened
-on and `--max-sessions` bounds each listener rather than the process. Binding is
-all or nothing — if any address cannot be bound, none are served — and a port of
-`0` selects an unused port per listener. If a listener fails while running, the
-others are shut down with it rather than leaving a service configured for two
-families answering on one.
-
-An explicit interface address works on every supported system. A wildcard bind
-such as `--bind 0.0.0.0:2112` reads each request's local destination from packet
-metadata and sends that request's reply from the same address, so a client on a
-multi-homed host is answered from the endpoint it contacted. That is implemented
-on Linux, macOS and FreeBSD; elsewhere a wildcard bind is refused rather than
-served from a routing-table source address a client would discard. Wildcard
-IPv4 and IPv6 listeners may share one port, as above.
-
-Each bound endpoint is printed on startup once every listener is up, which also
-resolves a port of `0`. `Ctrl-C` stops the server gracefully.
-
-Session policy is set with options that map directly onto the server library's
-configuration; anything left unset keeps the library default:
-
-```sh
-irtt-server \
-    --bind 192.0.2.10:2112 \
-    --max-sessions 512 \
-    --idle-timeout 30s
-```
-
-Two optional controls restrict what the server will provide a session, and both
-are off unless asked for:
-
-```sh
-irtt-server \
-    --bind 192.0.2.10:2112 \
-    --timestamp-allowance single \
-    --no-dscp
-```
-
-`--timestamp-allowance` takes `dual` (the default, honoring every requested
-placement), `single`, which provides at most one timestamp instant and answers a
-request for both receive and send timestamps with the midpoint, or `none`, which
-provides no timestamps. The requested clock source is never changed, so a single
-instant is still reported once per requested clock. `--no-dscp` negotiates any
-requested DSCP to zero, so clients are told their echo replies will be unmarked,
-and they are sent unmarked.
-
-To require authentication, pass the shared key both sides use:
-
-```sh
-irtt-server --bind 192.0.2.10:2112 --hmac secret
-```
-
-For the full option list:
-
-```sh
-irtt-server --help
-```
-
-## Library usage
-
-`irtt-client` exposes the client session and event layer independently of CLI formatting and statistics.
-
-Add it from a local checkout:
-
-```toml
-[dependencies]
-irtt-client = { path = "crates/irtt-client", features = ["tokio"] }
-```
-
-Minimal managed-client example for a synchronous frontend:
-
-```rust
-use std::time::Duration;
-
-use irtt_client::managed::{
-    BlockingManagedClient, ManagedClientConfig, ManagedCompletionPolicy,
-    ManagedTargetConfig, TargetId,
-};
-use irtt_client::ClientConfig;
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let config = ManagedClientConfig {
-        client: ClientConfig {
-            duration: Some(Duration::from_secs(10)),
-            interval: Duration::from_secs(1),
-            ..ClientConfig::default()
-        },
-        completion: ManagedCompletionPolicy::FinishWhenQuiescent,
-        ..ManagedClientConfig::default()
-    };
-    let targets = vec![ManagedTargetConfig::new(
-        TargetId::from("edge"),
-        "netperf-eu.bufferbloat.net:2112",
-    )];
-    let owner = BlockingManagedClient::start(config, targets)?;
-    let outcome = owner.join()?;
-    println!("session ended: {:?}", outcome.end_reason);
-
-    Ok(())
-}
-```
-
-For presentation events, use `BlockingManagedClient::start_with_subscription`,
-`ManagedEvent`, and `ManagedEventTryRecvError`, while consulting the durable
-`handle.status()` and final outcome for authoritative state. Presentation
-events are bounded and lossy, not reliable history. Dynamic desired-target
-updates are available through `ManagedClientHandle::update_targets`.
-
-`BlockingManagedClient` owns a dedicated Tokio runtime and thread for
-synchronous callers. Callers that already own Tokio can drive
-`ManagedClientTask` directly.
 
 ## Binaries and features
 
-| Build                                     | Binaries                                          |
+| Build | Binaries |
-| ----------------------------------------- | ------------------------------------------------- |
+| --- | --- |
-| `--no-default-features`                   | `irtt-rs`                                         |
+| `--no-default-features` | `irtt-rs` |
-| `--no-default-features --features server` | `irtt-rs`, `irtt-server`                          |
+| `--no-default-features --features client` | `irtt-rs`, `irtt-client` |
-| Default features                          | `irtt-rs`, `irtt-cli`, `irtt-server`              |
+| `--no-default-features --features server` | `irtt-rs`, `irtt-server` |
-| `--features tui`                          | `irtt-rs`, `irtt-cli`, `irtt-server`, `irtt-tui`  |
+| `--no-default-features --features tui` | `irtt-rs`, `irtt-tui` |
-| `--all-features`                          | `irtt-rs`, `irtt-cli`, `irtt-server`, `irtt-tui`  |
+| Default features (or `--all-features`) | `irtt-rs`, `irtt-client`, `irtt-tui`, `irtt-server` |
-
-`irtt-cli` requires the `client` feature, `irtt-server` the `server` feature,
-and `irtt-tui` the `tui` feature. The `irtt-rs` dispatcher is always built, and
-reports which applets the build actually contains.
-
-For available command-line options:
-
-```sh
-irtt-cli --help
-irtt-server --help
-irtt-tui --help
-```
 
 ## Development
 
-Common verification commands:
-
 ```sh
-cargo fmt --check
+cargo fmt --all -- --check
-cargo test --workspace
+cargo test --workspace --locked
-cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace --doc --all-features --locked
-cargo build -p irtt-cli --all-features --release
+cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
 ```
 
-## Project status
+See [`AGENTS.md`](AGENTS.md) for architecture, testing policy, and the
-
+clean-room provenance boundary this project maintains against upstream
-The client, event stream, machine-readable output, multi-target execution, local statistics, and optional TUI are implemented.
+`irtt`.
-
-The server library and the server applet are implemented: open negotiation,
-session state, echo processing, per-session rate limiting, idle expiry, the
-maximum-duration close, HMAC authentication, the negotiated per-session reply
-traffic class, which is applied on sockets that support it, server fill,
-wildcard reply-source selection on Linux, macOS and FreeBSD, the optional
-timestamp and DSCP restriction controls, and serving several listeners from one
-process with independent sessions per listener.
-
-Server replies fill their payload with the negotiated ServerFill mode: `none`,
-which is zero-filled, `rand`, or `pattern:` with a repeating hexadecimal
-pattern. Every valid descriptor is honored; a descriptor the server cannot
-parse, and a client that expresses no fill preference at all, get the default
-`pattern:69727474`.

crates/irtt-app/Cargo.toml

@@ -1,17 +1,18 @@
 [package]
-name = "irtt-cli"
+name = "irtt-rs"
-version = "0.5.0"
+version = "0.7.1"
-description = "Command-line IRTT-compatible client and server"
+description = "IRTT-compatible client, TUI, and server applications"
 edition.workspace = true
 license.workspace = true
 rust-version.workspace = true
 repository.workspace = true
 homepage.workspace = true
-readme.workspace = true
+readme = "README.md"
 keywords = ["irtt", "networking", "latency", "rtt"]
 categories = ["command-line-utilities", "network-programming"]
 
 [lib]
+name = "irtt_app"
 doc = false
 
 [[bin]]
@@ -19,9 +20,12 @@ name = "irtt-rs"
 path = "src/bin/irtt-rs.rs"
 
 [[bin]]
-name = "irtt-cli"
+name = "irtt-client"
-path = "src/bin/irtt-cli.rs"
+path = "src/bin/irtt-client.rs"
 required-features = ["client"]
+# This applet shares its name with the irtt-client library crate, whose rustdoc
+# output it would otherwise collide with.
+doc = false
 
 [[bin]]
 name = "irtt-tui"
@@ -43,9 +47,9 @@ server = ["dep:irtt-server", "dep:tokio"]
 tui =["dep:irtt-client", "irtt-client/ancillary", "irtt-client/tokio", "dep:irtt-proto", "dep:irtt-stats", "dep:ratatui", "dep:crossterm"]
 
 [dependencies]
-clap = { version = "4.6.6", features = ["derive"] }
+clap = { version = "4.6.7", features = ["derive", "env"] }
 crossterm = { version = "0.29.0", optional = true }
-ctrlc = "3.5.2"
+ctrlc = { version = "3.5.2", features = ["termination"] }
 irtt-client = { workspace = true, optional = true }
 irtt-proto = { workspace = true, optional = true }
 irtt-server = { workspace = true, optional = true }
@@ -56,3 +60,9 @@ tokio = { version = "1.53.1", default-features = false, features = ["rt", "time"
 [dev-dependencies]
 irtt-server.workspace = true
 tokio = { version = "1.53.1", default-features = false, features = ["rt", "sync"] }
+
+[profile.release]
+opt-level = "z"
+lto = true
+codegen-units = 1
+strip = "symbols"

crates/irtt-app/README.md

@@ -0,0 +1,33 @@
+# irtt-rs
+
+The IRTT-compatible client, TUI, and server applications, packaged as Cargo
+package `irtt-rs`.
+
+Installing this crate builds:
+
+- `irtt-rs` — a multicall dispatcher binary that runs the client, TUI, or
+  server applet by subcommand.
+- `irtt-client` — the dedicated client binary (feature `client`).
+- `irtt-tui` — the interactive terminal UI (feature `tui`).
+- `irtt-server` — the dedicated server binary (feature `server`).
+
+All three features are enabled by default, so a plain `cargo install irtt-rs`
+installs everything.
+
+## This is an application, not a library
+
+This package's library target is undocumented (`doc = false`) and exists only
+to share code between its binaries. If you're looking for the client/session
+or server API to embed in your own Rust program, use
+[`irtt-client`](https://crates.io/crates/irtt-client) or
+[`irtt-server`](https://crates.io/crates/irtt-server) instead.
+
+## Usage
+
+See the [project repository](https://github.com/Lochnair/irtt-rs) for
+installation instructions, command-line usage, and configuration.
+
+## Project
+
+Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
+implementation of an IRTT-compatible protocol stack.

crates/irtt-app/src/applet.rs

@@ -20,9 +20,9 @@ pub enum AppletDispatch {
 
 pub fn detect_applet_from_argv0(argv0: &str) -> Option<RequestedApplet> {
     match applet_basename(argv0) {
-        "irtt-cli" => Some(RequestedApplet::Client),
+        "irtt-client" => Some(RequestedApplet::Client),
         "irtt-tui" => Some(RequestedApplet::Tui),
-        "irttd" | "irtt-server" => Some(RequestedApplet::Server),
+        "irtt-server" => Some(RequestedApplet::Server),
         "irtt-rs" => None,
         _ => None,
     }
@@ -58,7 +58,7 @@ pub fn dispatch_from_argv(argv: Vec<OsString>) -> Result<AppletDispatch, String>
         "-h" | "--help" => Ok(AppletDispatch::Help(dispatcher_help())),
         "client" => Ok(AppletDispatch::Run {
             applet: RequestedApplet::Client,
-            argv: applet_argv("irtt-cli", &argv[2..]),
+            argv: applet_argv("irtt-client", &argv[2..]),
         }),
         "tui" => Ok(AppletDispatch::Run {
             applet: RequestedApplet::Tui,
@@ -111,7 +111,7 @@ fn server_applet_about() -> &'static str {
 }
 
 fn known_applet_binary_names() -> &'static str {
-    "irtt-rs, irtt-cli, irtt-tui, irtt-server"
+    "irtt-rs, irtt-client, irtt-tui, irtt-server"
 }
 
 fn applet_command_names() -> &'static str {
@@ -119,11 +119,11 @@ fn applet_command_names() -> &'static str {
 }
 
 fn dispatcher_after_help() -> String {
-    let mut help = "Recognized applet binary names: irtt-cli, irtt-tui, irtt-server".to_owned();
+    let mut help = "Recognized applet binary names: irtt-client, irtt-tui, irtt-server".to_owned();
 
     let mut missing = Vec::new();
     if !cfg!(feature = "client") {
-        missing.push("irtt-cli requires the client feature");
+        missing.push("irtt-client requires the client feature");
     }
     if !cfg!(feature = "server") {
         missing.push("irtt-server requires the server feature");
@@ -188,7 +188,7 @@ mod tests {
     #[test]
     fn applet_detection_maps_binary_names() {
         assert_eq!(
-            detect_applet_from_argv0("/usr/bin/irtt-cli"),
+            detect_applet_from_argv0("/usr/bin/irtt-client"),
             Some(RequestedApplet::Client)
         );
         assert_eq!(
@@ -199,10 +199,17 @@ mod tests {
             detect_applet_from_argv0("irtt-server"),
             Some(RequestedApplet::Server)
         );
+        assert_eq!(detect_applet_from_argv0("irttd"), None);
         assert_eq!(detect_applet_from_argv0("irtt-rs"), None);
         assert_eq!(detect_applet_from_argv0("custom-name"), None);
     }
 
+    #[test]
+    fn old_irtt_cli_binary_name_is_no_longer_a_recognized_applet() {
+        assert_eq!(detect_applet_from_argv0("irtt-cli"), None);
+        assert_eq!(detect_applet_from_argv0("/usr/bin/irtt-cli"), None);
+    }
+
     #[test]
     fn applet_detection_ignores_the_platform_executable_suffix() {
         let exe = std::env::consts::EXE_SUFFIX;
@@ -212,7 +219,7 @@ mod tests {
             Some(RequestedApplet::Server)
         );
         assert_eq!(
-            detect_applet_from_argv0(&format!("irtt-cli{exe}")),
+            detect_applet_from_argv0(&format!("irtt-client{exe}")),
             Some(RequestedApplet::Client)
         );
 
@@ -288,7 +295,7 @@ mod tests {
                 .unwrap(),
             AppletDispatch::Run {
                 applet: RequestedApplet::Client,
-                argv: vec!["irtt-cli".into(), "host:2112".into()],
+                argv: vec!["irtt-client".into(), "host:2112".into()],
             }
         );
         assert_eq!(
@@ -311,7 +318,7 @@ mod tests {
     fn unknown_irtt_binary_name_is_an_error() {
         let err = dispatch_from_argv(vec!["/usr/bin/irtt-typo".into()]).unwrap_err();
         assert!(err.contains("unknown applet name 'irtt-typo'"));
-        assert!(err.contains("irtt-cli"));
+        assert!(err.contains("irtt-client"));
         if cfg!(feature = "tui") {
             assert!(err.contains("irtt-tui"));
         }

crates/irtt-app/src/bin/irtt-client.rs

@@ -1,5 +1,5 @@
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
-    irtt_cli::entry::main()
+    irtt_app::entry::client_main()
 }

crates/irtt-app/src/bin/irtt-rs.rs

@@ -1,5 +1,5 @@
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
-    irtt_cli::entry::main()
+    irtt_app::entry::dispatcher_main()
 }

crates/irtt-app/src/bin/irtt-server.rs

@@ -1,5 +1,5 @@
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
-    irtt_cli::entry::main()
+    irtt_app::entry::server_main()
 }

crates/irtt-app/src/bin/irtt-tui.rs

@@ -1,5 +1,5 @@
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
-    irtt_cli::entry::main()
+    irtt_app::entry::tui_main()
 }

crates/irtt-app/src/cmd/client/args.rs

@@ -9,17 +9,24 @@ use clap::{Parser, ValueEnum};
 pub const DEFAULT_CLIENT_DURATION: Duration = Duration::from_secs(10);
 
 #[derive(Debug, Clone, Parser)]
-#[command(name = "irtt-cli", about = "Minimal IRTT-compatible stream client")]
+#[command(name = "irtt-client", about = "Minimal IRTT-compatible stream client")]
 pub struct ClientArgs {
-    /// Server address/host, optionally prefixed with LABEL=. Repeat for multi-target mode.
+    /// Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.
     #[arg(
         value_name = "TARGET",
         num_args = 0..,
         value_parser = parse_target,
-        long_help = "Server address/host, optionally prefixed with LABEL=. Repeat for multi-target mode.\n\nExamples:\n  irtt-cli host-a:2112 host-b:2112\n  irtt-cli eu=host-a:2112 us=host-b:2112\n  irtt-cli host-a:2112 eu=host-b:2112"
+        long_help = "Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.\n\nExamples:\n  irtt-client host-a:2112 host-b:2112\n  irtt-client eu=host-a:2112 us=host-b:2112\n  irtt-client ams=host-a:2112@hmac=secret public=host-b:2112@hmac=\n\nA target without @hmac= inherits --hmac. @hmac= explicitly disables it for that target."
     )]
     pub targets: Vec<TargetArg>,
 
+    /// Read complete desired target sets from standard input in continuous mode.
+    #[arg(
+        long,
+        long_help = "Read one complete desired target set per stdin line in continuous mode. Commas separate targets and backslash escapes commas within a target. [] selects an empty desired set. Records are limited to 64 KiB. EOF stops the client gracefully and may discard a revision that has not yet been acknowledged as applied."
+    )]
+    pub targets_stdin: bool,
+
     /// Managed group pacing for multi-target mode.
     #[arg(
         long,
@@ -34,7 +41,7 @@ pub struct ClientArgs {
         default_value = "10s",
         value_parser = parse_test_duration,
         help = "Test duration; use 0 for continuous mode",
-        long_help = "Test duration; use 0 for continuous mode.\n\nFinite runs retain exact statistics for final summaries. Continuous mode uses bounded-memory running statistics and prints a final summary only when interrupted."
+        long_help = "Test duration; use 0 for continuous mode.\n\nFinite runs retain exact statistics for final summaries. Continuous mode uses bounded-memory running statistics and prints a final summary when interrupted; --targets-stdin also prints the final retained summary on EOF."
     )]
     pub duration: Duration,
 
@@ -86,12 +93,16 @@ impl ClientArgs {
     /// Targets are only required here. `--list-columns` returns before this is
     /// called, so listing columns still needs no target.
     pub fn prepare(&self) -> Result<ManagedRunSetup, String> {
+        if self.targets_stdin && !self.is_continuous() {
+            return Err("--targets-stdin requires --duration 0".to_owned());
+        }
         prepare_managed_run(
             &self.common,
             self.duration,
             TargetSelection {
                 targets: &self.targets,
                 pacing: self.pacing,
+                stdin_controlled: self.targets_stdin,
             },
         )
     }
@@ -149,7 +160,7 @@ mod tests {
     use irtt_proto::{Clock, ReceivedStats, StampAt};
 
     fn parse(args: &[&str]) -> Result<ClientArgs, clap::Error> {
-        let mut argv = vec!["irtt-cli"];
+        let mut argv = vec!["irtt-client"];
         argv.extend_from_slice(args);
         ClientArgs::try_parse_from(argv)
     }
@@ -159,14 +170,14 @@ mod tests {
         let args = parse(&["127.0.0.1:2112"]).unwrap();
 
         assert_eq!(args.targets.len(), 1);
-        assert_eq!(args.targets[0].label, None);
+        assert_eq!(args.prepare().unwrap().targets[0].label, "127.0.0.1:2112");
-        assert_eq!(args.targets[0].addr, "127.0.0.1:2112");
         assert_eq!(args.pacing, GroupPacingArg::Staggered);
         assert_eq!(args.duration, DEFAULT_CLIENT_DURATION);
         assert_eq!(args.interval, Duration::from_secs(1));
         assert_eq!(args.format, OutputFormat::Table);
         assert_eq!(args.columns, None);
         assert_eq!(args.header, HeaderMode::Auto);
+        assert!(!args.targets_stdin);
         assert!(!args.is_continuous());
         assert_eq!(args.timestamp_mode(), TimestampArg::Both);
 
@@ -254,8 +265,8 @@ mod tests {
 
     #[test]
     fn invalid_labelled_target_syntax_is_rejected() {
-        assert!(parse(&["=127.0.0.1:2112"]).is_err());
+        assert!(parse(&["=127.0.0.1:2112"]).unwrap().prepare().is_err());
-        assert!(parse(&["label="]).is_err());
+        assert!(parse(&["label="]).unwrap().prepare().is_err());
     }
 
     #[test]
@@ -296,6 +307,34 @@ mod tests {
         assert!(help.contains("--loose"));
     }
 
+    #[test]
+    fn an_empty_hmac_key_is_rejected() {
+        let err = parse(&["--hmac", "", "127.0.0.1:2112"]).unwrap_err();
+        assert!(err.to_string().contains("HMAC key must not be empty"));
+    }
+
+    #[test]
+    fn a_non_empty_hmac_key_is_accepted() {
+        let args = parse(&["--hmac", "secret", "127.0.0.1:2112"]).unwrap();
+        let config = args.prepare().unwrap().client;
+        assert_eq!(config.hmac_key, Some(b"secret".to_vec()));
+    }
+
+    #[test]
+    fn targets_stdin_requires_continuous_mode_and_allows_empty_initial_set() {
+        assert!(parse(&["--targets-stdin"]).unwrap().prepare().is_err());
+        let args = parse(&["--duration", "0", "--targets-stdin"]).unwrap();
+        let setup = args.prepare().unwrap();
+        assert!(setup.targets.is_empty());
+        assert!(setup.stdin_controlled);
+        let config = setup.managed_config();
+        assert_eq!(
+            config.completion,
+            irtt_client::managed::ManagedCompletionPolicy::ExplicitStop
+        );
+        assert_eq!(config.max_live_target_generations, 256);
+    }
+
     #[test]
     fn output_format_summary_policy_is_table_only() {
         assert!(OutputFormat::Table.prints_summary());

crates/irtt-app/src/cmd/client/output.rs

@@ -802,6 +802,11 @@ fn render_table_row(row: &OutputRow, columns: &[Column], context: RenderContext<
 fn format_table_cell(column: &Column, value: Option<String>) -> String {
     let value = value.unwrap_or_else(|| ABSENT.to_owned());
     let width = column.table_width();
+    let value = if matches!(column, Column::Target) {
+        truncate_for_table(&value, width)
+    } else {
+        value
+    };
     if column.align_right() {
         format!("{value:>width$}")
     } else {
@@ -809,6 +814,25 @@ fn format_table_cell(column: &Column, value: Option<String>) -> String {
     }
 }
 
+/// Shortens `value` to fit within `max_width` display characters for TABLE
+/// presentation only. Values within the limit are returned unchanged. Longer
+/// values keep a prefix and end with `"..."` so the result is exactly
+/// `max_width` characters. Operates on `char`s (never raw byte indices) so a
+/// multibyte UTF-8 value cannot be split mid-code-point.
+///
+/// This is a presentation-only concern: callers must keep the untruncated
+/// value for CSV/TSV/JSONL and any non-display use.
+fn truncate_for_table(value: &str, max_width: usize) -> String {
+    if value.chars().count() <= max_width {
+        return value.to_owned();
+    }
+    let suffix = "...";
+    let prefix_len = max_width.saturating_sub(suffix.len());
+    let mut truncated: String = value.chars().take(prefix_len).collect();
+    truncated.push_str(suffix);
+    truncated
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum DelimitedFormat {
     Csv,
@@ -1304,4 +1328,150 @@ mod tests {
 
         assert!(line.starts_with("{\"target\":\"ams\""));
     }
+
+    #[test]
+    fn truncate_for_table_leaves_short_value_unchanged() {
+        assert_eq!(truncate_for_table("ams", 18), "ams");
+    }
+
+    #[test]
+    fn truncate_for_table_leaves_exact_width_value_unchanged() {
+        let value = "a".repeat(18);
+        assert_eq!(truncate_for_table(&value, 18), value);
+    }
+
+    #[test]
+    fn truncate_for_table_shortens_long_value_to_width() {
+        let value = "a".repeat(40);
+        let truncated = truncate_for_table(&value, 18);
+
+        assert_eq!(truncated.chars().count(), 18);
+        assert!(truncated.len() <= 18); // ASCII: byte len matches char len
+    }
+
+    #[test]
+    fn truncate_for_table_keeps_prefix_and_appends_ellipsis_deterministically() {
+        let value = "abcdefghijklmnopqrstuvwxyz";
+        let truncated = truncate_for_table(value, 18);
+
+        assert_eq!(truncated, "abcdefghijklmno...");
+        assert_eq!(truncated.chars().count(), 18);
+    }
+
+    #[test]
+    fn truncate_for_table_does_not_split_multibyte_code_points() {
+        // Each character below is multibyte in UTF-8; a byte-index slice
+        // would panic or corrupt the string on a non-boundary cut.
+        let value = "\u{1F600}".repeat(40); // 😀 repeated, well past width 18
+        let truncated = truncate_for_table(&value, 18);
+
+        // Must not panic (validated by test completing) and must remain
+        // valid UTF-8 with exactly 18 chars (15 prefix chars + "...").
+        assert_eq!(truncated.chars().count(), 18);
+        assert!(truncated.ends_with("..."));
+        assert_eq!(truncated.chars().filter(|c| *c == '\u{1F600}').count(), 15);
+    }
+
+    #[test]
+    fn table_row_with_long_target_keeps_next_column_aligned() {
+        let config = output_config(OutputFormat::Table, None);
+        let long_target = "a".repeat(40);
+        let header = config.render_header().unwrap();
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        // Target column is truncated to its table width (18), so the
+        // "event" column starts at the same offset for both a normal and an
+        // overlong target label.
+        let short_config = output_config(OutputFormat::Table, None);
+        let short_line = short_config
+            .render_event(&reply(), Some("ams"), Some(&EventRenderStats::default()))
+            .unwrap();
+
+        let target_width = Column::Target.table_width();
+        let expected_event_offset = target_width + "  ".len();
+        assert_eq!(&header[expected_event_offset..][..5], "event");
+        // The event column ("echo_reply") starts at the same offset
+        // regardless of whether the target label was short or overlong.
+        assert_eq!(
+            &line[expected_event_offset..][.."echo_reply".len()],
+            "echo_reply"
+        );
+        assert_eq!(
+            &short_line[expected_event_offset..][.."echo_reply".len()],
+            "echo_reply"
+        );
+    }
+
+    #[test]
+    fn csv_preserves_full_long_target_label() {
+        let config = output_config(OutputFormat::Csv, Some("target,seq"));
+        let long_target = "a".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        assert_eq!(line, format!("{long_target},7"));
+    }
+
+    #[test]
+    fn tsv_preserves_full_long_target_label() {
+        let config = output_config(OutputFormat::Tsv, Some("target,seq"));
+        let long_target = "b".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        assert_eq!(line, format!("{long_target}\t7"));
+    }
+
+    #[test]
+    fn jsonl_preserves_full_long_target_label() {
+        let config = output_config(OutputFormat::Jsonl, Some("target,seq"));
+        let long_target = "c".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        assert_eq!(line, format!("{{\"target\":\"{long_target}\",\"seq\":7}}"));
+    }
+
+    #[test]
+    fn explicit_table_columns_with_target_truncate_same_as_default() {
+        let config = output_config(OutputFormat::Table, Some("target,seq"));
+        let long_target = "d".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        let target_width = Column::Target.table_width();
+        let expected_prefix: String = long_target
+            .chars()
+            .take(target_width - 3)
+            .chain("...".chars())
+            .collect();
+        assert!(line.starts_with(&expected_prefix));
+        assert_eq!(&line[..target_width], expected_prefix.as_str());
+    }
 }

crates/irtt-app/src/cmd/format.rs

@@ -12,6 +12,7 @@
 
 use std::time::Duration;
 
+#[cfg(feature = "client")]
 use irtt_client::SignedDuration;
 
 /// Rendering used wherever a scalar is unavailable.
@@ -61,6 +62,7 @@ pub(crate) fn format_optional_ns_i128(value: Option<i128>) -> String {
 }
 
 /// Format an optional nanosecond scalar, rendering `None` as [`ABSENT`].
+#[cfg(feature = "client")]
 pub(crate) fn format_optional_ns_f64(value: Option<f64>) -> String {
     value.map(format_ns_f64).unwrap_or_else(absent)
 }
@@ -71,6 +73,7 @@ pub(crate) fn format_duration(value: Duration) -> String {
 }
 
 /// Format a signed duration as a nanosecond scalar, preserving its sign.
+#[cfg(feature = "client")]
 pub(crate) fn format_signed_duration(value: SignedDuration) -> String {
     format_ns_i128(value.as_nanos())
 }
@@ -88,6 +91,7 @@ pub(crate) fn format_percent(value: f64) -> String {
 /// Format `value` as a percentage of `total`, capped at 100%.
 ///
 /// A zero total has no percentage to report and renders as [`ABSENT`].
+#[cfg(feature = "tui")]
 pub(crate) fn format_percent_ratio(value: u64, total: u64) -> String {
     if total == 0 {
         ABSENT.to_owned()
@@ -97,11 +101,13 @@ pub(crate) fn format_percent_ratio(value: u64, total: u64) -> String {
 }
 
 /// Format a scalar count.
+#[cfg(feature = "tui")]
 pub(crate) fn format_count(value: u64) -> String {
     value.to_string()
 }
 
 /// Format an optional scalar count, rendering `None` as [`ABSENT`].
+#[cfg(feature = "tui")]
 pub(crate) fn format_optional_count(value: Option<u64>) -> String {
     value.map(format_count).unwrap_or_else(absent)
 }
@@ -152,6 +158,11 @@ mod tests {
     fn durations_render_as_nanosecond_scalars() {
         assert_eq!(format_duration(Duration::from_millis(25)), "25.0ms");
         assert_eq!(format_duration(Duration::from_secs(1)), "1.000s");
+    }
+
+    #[test]
+    #[cfg(feature = "client")]
+    fn signed_durations_render_as_nanosecond_scalars() {
         assert_eq!(
             format_signed_duration(SignedDuration::from_nanos(-1_500)),
             "-1.5µs"
@@ -161,18 +172,33 @@ mod tests {
     #[test]
     fn absent_and_non_finite_scalars_render_as_a_placeholder() {
         assert_eq!(format_optional_ns_i128(None), ABSENT);
-        assert_eq!(format_optional_ns_f64(None), ABSENT);
-        assert_eq!(format_optional_count(None), ABSENT);
         assert_eq!(format_ns_f64(f64::NAN), ABSENT);
         assert_eq!(format_ns_f64(f64::INFINITY), ABSENT);
         assert_eq!(format_percent(f64::NAN), ABSENT);
+    }
+
+    #[test]
+    #[cfg(feature = "client")]
+    fn absent_optional_ns_f64_renders_as_a_placeholder() {
+        assert_eq!(format_optional_ns_f64(None), ABSENT);
+    }
+
+    #[test]
+    #[cfg(feature = "tui")]
+    fn absent_counts_and_ratios_render_as_a_placeholder() {
+        assert_eq!(format_optional_count(None), ABSENT);
         assert_eq!(format_percent_ratio(1, 0), ABSENT);
     }
 
     #[test]
-    fn percentages_and_counts_have_one_spelling() {
+    fn percentages_have_one_spelling() {
         assert_eq!(format_percent(0.0), "0.00%");
         assert_eq!(format_percent(12.345), "12.35%");
+    }
+
+    #[test]
+    #[cfg(feature = "tui")]
+    fn percent_ratios_and_counts_have_one_spelling() {
         assert_eq!(format_percent_ratio(1, 4), "25.00%");
         assert_eq!(format_percent_ratio(5, 4), "100.00%");
         assert_eq!(format_count(42), "42");

crates/irtt-app/src/cmd/server/args.rs

@@ -1,8 +1,14 @@
-use std::{net::SocketAddr, time::Duration};
+use std::{
+    net::{Ipv4Addr, Ipv6Addr, SocketAddr},
+    time::Duration,
+};
 
 use clap::{Parser, ValueEnum};
 use irtt_server::{ServerConfig, TimestampAllowance};
 
+/// The ordinary IRTT port, used to build the zero-argument default binds.
+const DEFAULT_PORT: u16 = 2112;
+
 // Every policy option is optional. An omitted option leaves the corresponding
 // `ServerConfig` default in place rather than restating it here, so library and
 // CLI defaults cannot drift apart.
@@ -10,15 +16,15 @@ use irtt_server::{ServerConfig, TimestampAllowance};
 #[command(
     name = "irtt-server",
     about = "Minimal IRTT-compatible UDP server",
-    after_help = "Policy options left unset keep the irtt-server library defaults.\nRepeat --bind to serve multiple addresses in one process. All listeners use the same policy but keep independent session namespaces."
+    after_help = "With no --bind, the server listens on the wildcard IRTT port for both address families ([::]:2112 and 0.0.0.0:2112) where the platform supports wildcard reply-source selection.\nRepeat --bind to serve multiple addresses in one process; any explicit --bind replaces the default pair entirely. All listeners use the same policy but keep independent session namespaces."
 )]
 pub struct ServerArgs {
     /// Local UDP address to bind, as ADDR:PORT. Repeatable.
     #[arg(
         long,
-        required = true,
         value_name = "ADDR",
-        long_help = "Local UDP address to bind, as ADDR:PORT, for example 127.0.0.1:2112 or [::1]:2112. Host names are not resolved.\n\nRepeat the option to serve several addresses from one process, in the order given. Every listener applies the same policy options, but each keeps its own sessions and tokens, so a session belongs to the address it was opened on. Binding is all or nothing: if any address cannot be bound, none are served.\n\nA wildcard bind such as 0.0.0.0:2112 answers each request from the address it was sent to, using per-packet destination metadata. That is supported on Linux, macOS and FreeBSD; on other systems a wildcard bind is refused and an explicit interface address is required.\n\nA port of 0 selects an unused port per listener, so two such binds get two different ports."
+        env = "IRTT_SERVER_BIND",
+        long_help = "Local UDP address to bind, as ADDR:PORT, for example 127.0.0.1:2112 or [::1]:2112. Host names are not resolved.\n\nRepeat the option to serve several addresses from one process, in the order given. Every listener applies the same policy options, but each keeps its own sessions and tokens, so a session belongs to the address it was opened on. Binding is all or nothing: if any address cannot be bound, none are served.\n\nWith no --bind at all, the server binds the wildcard IRTT port on both address families, [::]:2112 then 0.0.0.0:2112, on platforms with wildcard reply-source support; elsewhere it fails and asks for an explicit address instead of guessing one. Any explicit --bind replaces that default pair rather than adding to it.\n\nA wildcard bind such as 0.0.0.0:2112 answers each request from the address it was sent to, using per-packet destination metadata. That is supported on Linux, macOS and FreeBSD; on other systems a wildcard bind is refused and an explicit interface address is required.\n\nA port of 0 selects an unused port per listener, so two such binds get two different ports.\n\nIRTT_SERVER_BIND sets the same thing for deployments that configure by environment (systemd, Docker, ...), and takes exactly one address, the same as one --bind. Leave it unset on ordinary hosts: the wildcard default above is already what you want there. A --bind on the command line overrides it entirely."
     )]
     pub bind: Vec<SocketAddr>,
 
@@ -26,7 +32,9 @@ pub struct ServerArgs {
     #[arg(
         long,
         value_name = "KEY",
-        long_help = "HMAC key, taken as the UTF-8 bytes of this argument.\n\nAuthentication is global: with a key configured, every request must carry a valid MAC and every reply is authenticated. Without one, authenticated requests are dropped. The key is visible in the process arguments."
+        value_parser = parse_hmac_key,
+        env = "IRTT_SERVER_HMAC",
+        long_help = "HMAC key, taken as the UTF-8 bytes of this argument.\n\nAuthentication is global: with a key configured, every request must carry a valid MAC and every reply is authenticated. Without one, authenticated requests are dropped. The key is visible in the process arguments, or in the environment as IRTT_SERVER_HMAC."
     )]
     pub hmac: Option<String>,
 
@@ -34,6 +42,7 @@ pub struct ServerArgs {
     #[arg(
         long,
         value_name = "COUNT",
+        env = "IRTT_SERVER_MAX_SESSIONS",
         long_help = "Maximum number of simultaneously live sessions per listener. Once a listener's table is full, a session-creating open to it is dropped silently; nothing is evicted. Zero refuses every session-creating open.\n\nThis is a per-listener bound, not a process-wide one: with two --bind options, each listener admits up to this many sessions."
     )]
     pub max_sessions: Option<usize>,
@@ -42,16 +51,18 @@ pub struct ServerArgs {
     #[arg(
         long,
         value_name = "BYTES",
+        env = "IRTT_SERVER_MAX_PACKET_LENGTH",
         long_help = "Maximum echo datagram size a session may negotiate, in bytes. A longer requested length is reduced during negotiation, an open whose mandatory field block would not fit is refused, and inbound echo requests are admitted against the same limit. This is a resource bound, not an MTU."
     )]
     pub max_packet_length: Option<usize>,
 
-    /// Floor on the negotiated send interval, and the allowance refill cadence.
+    /// Floor on the negotiated send interval.
     #[arg(
         long,
         value_name = "DURATION",
         value_parser = parse_duration_allow_zero,
-        long_help = "Floor on the send interval a session may negotiate, and the cadence its reply allowance refills at. The negotiated interval is still capped at a quarter of the idle timeout afterwards. Use 0 for no time-based throttling."
+        env = "IRTT_SERVER_MIN_INTERVAL",
+        long_help = "Floor on the send interval a session may negotiate. The negotiated interval is still capped at a quarter of the idle timeout afterwards, so a value above that cap is not what actually gets negotiated.\n\nA session's reply allowance refills at the shorter of this floor and the interval it actually negotiated. Ordinarily that is this floor itself; it is the shorter, negotiated value only where the idle-timeout cap above pulled the negotiated interval below it. Use 0 for no time-based throttling."
     )]
     pub min_interval: Option<Duration>,
 
@@ -59,6 +70,7 @@ pub struct ServerArgs {
     #[arg(
         long,
         value_name = "COUNT",
+        env = "IRTT_SERVER_BURST",
         long_help = "Echo replies one session may have answered before its allowance has to refill. Use 0 for no allowance at all, which rate-limits every echo request whatever the interval is."
     )]
     pub burst: Option<u32>,
@@ -68,6 +80,7 @@ pub struct ServerArgs {
         long,
         value_name = "DURATION",
         value_parser = parse_duration_allow_zero,
+        env = "IRTT_SERVER_IDLE_TIMEOUT",
         long_help = "Release a session after this long without a served or rate-limited echo request. The deadline runs from the open, and release is silent. Use 0 to expire a session at the next evaluation; it is not a way to disable expiry."
     )]
     pub idle_timeout: Option<Duration>,
@@ -77,6 +90,7 @@ pub struct ServerArgs {
         long,
         value_name = "DURATION",
         value_parser = parse_positive_duration,
+        env = "IRTT_SERVER_MAX_DURATION",
         long_help = "Maximum test duration a session may negotiate. A longer request is reduced to it, and a continuous request is answered with it. Omit this flag for no maximum; a maximum of zero cannot be expressed, because a negotiated duration of zero means continuous."
     )]
     pub max_duration: Option<Duration>,
@@ -86,14 +100,28 @@ pub struct ServerArgs {
         long,
         value_name = "MODE",
         value_enum,
+        env = "IRTT_SERVER_TIMESTAMP_ALLOWANCE",
         long_help = "How many timestamps this server will provide.\n\ndual: honor a request for send, receive, both or midpoint timestamps.\nsingle: provide at most one timestamp instant; a request for both is negotiated to midpoint.\nnone: provide no timestamps at all.\n\nThe requested clock source is never changed, only which instants are reported, so a single instant is still reported once per requested clock. Omit this flag to honor every requested placement."
     )]
     pub timestamp_allowance: Option<TimestampAllowanceArg>,
 
     /// Refuse to provide requested DSCP marking.
+    //
+    // `FalseyValueParser` rather than clap's default `bool` parser for a flag,
+    // which is what makes IRTT_SERVER_NO_DSCP usable from the environment at
+    // all. A flag's default parser accepts only the literals `true` and
+    // `false`, so the ordinary container/orchestrator spelling
+    // `IRTT_SERVER_NO_DSCP=1` did not enable the flag — it failed argument
+    // parsing and the server refused to start. Falsey semantics are clap's own
+    // documented recipe for a boolean environment flag: `0`, `false`, `no`,
+    // `n`, `off` and empty are off, anything else is on, and an absent
+    // variable is off as before. The command-line flag is unaffected: it still
+    // takes no value and still means "on".
     #[arg(
         long,
-        long_help = "Refuse to provide requested traffic-class marking. Any requested DSCP is negotiated to zero, so the client is told its echo replies will be unmarked, and they are sent unmarked. The session is not refused."
+        env = "IRTT_SERVER_NO_DSCP",
+        value_parser = clap::builder::FalseyValueParser::new(),
+        long_help = "Refuse to provide requested traffic-class marking. Any requested DSCP is negotiated to zero, so the client is told its echo replies will be unmarked, and they are sent unmarked. The session is not refused.\n\nIRTT_SERVER_NO_DSCP sets the same thing from the environment: 0, false, no, n, off and an empty value leave marking enabled, and any other value disables it."
     )]
     pub no_dscp: bool,
 }
@@ -123,6 +151,20 @@ impl From<TimestampAllowanceArg> for TimestampAllowance {
 }
 
 impl ServerArgs {
+    /// The addresses this invocation binds: the requested `--bind` list, or
+    /// the wildcard IRTT port on both address families if none was given.
+    #[must_use]
+    pub fn resolve_binds(&self) -> Vec<SocketAddr> {
+        if self.bind.is_empty() {
+            vec![
+                SocketAddr::from((Ipv6Addr::UNSPECIFIED, DEFAULT_PORT)),
+                SocketAddr::from((Ipv4Addr::UNSPECIFIED, DEFAULT_PORT)),
+            ]
+        } else {
+            self.bind.clone()
+        }
+    }
+
     /// Builds the server configuration this invocation asks for.
     #[must_use]
     pub fn server_config(&self) -> ServerConfig {
@@ -160,6 +202,15 @@ impl ServerArgs {
     }
 }
 
+/// Rejects an empty HMAC key so a blank shell expansion cannot silently
+/// enable authentication with predictable, empty key material.
+fn parse_hmac_key(input: &str) -> Result<String, String> {
+    if input.is_empty() {
+        return Err("HMAC key must not be empty".to_owned());
+    }
+    Ok(input.to_owned())
+}
+
 /// Parses a duration whose zero is meaningful server policy.
 fn parse_duration_allow_zero(input: &str) -> Result<Duration, String> {
     if input == "0" {
@@ -212,11 +263,14 @@ mod tests {
     use std::net::{Ipv4Addr, Ipv6Addr};
 
     use super::*;
+    use crate::cmd::server::env_lock::with_env_lock;
 
     fn parse(args: &[&str]) -> Result<ServerArgs, clap::Error> {
-        let mut argv = vec!["irtt-server"];
+        with_env_lock(|| {
-        argv.extend_from_slice(args);
+            let mut argv = vec!["irtt-server"];
-        ServerArgs::try_parse_from(argv)
+            argv.extend_from_slice(args);
+            ServerArgs::try_parse_from(argv)
+        })
     }
 
     fn bound(args: &[&str]) -> ServerArgs {
@@ -226,12 +280,7 @@ mod tests {
     }
 
     #[test]
-    fn bind_is_required_and_parses_both_families() {
+    fn bind_is_optional_and_parses_both_families() {
-        assert!(
-            parse(&[]).is_err(),
-            "a server with no address serves nothing"
-        );
-
         let ipv4 = parse(&["--bind", "127.0.0.1:2112"]).unwrap();
         assert_eq!(ipv4.bind, [SocketAddr::from((Ipv4Addr::LOCALHOST, 2112))]);
 
@@ -245,6 +294,39 @@ mod tests {
         assert!(parse(&["--bind", "127.0.0.1:2112,[::1]:2112"]).is_err());
     }
 
+    #[test]
+    fn no_explicit_bind_resolves_to_the_wildcard_default_pair() {
+        let args = parse(&[]).unwrap();
+        assert!(
+            args.bind.is_empty(),
+            "the empty list is the parsed representation of \"no explicit bind\""
+        );
+        assert_eq!(
+            args.resolve_binds(),
+            [
+                SocketAddr::from((Ipv6Addr::UNSPECIFIED, 2112)),
+                SocketAddr::from((Ipv4Addr::UNSPECIFIED, 2112)),
+            ],
+            "zero explicit binds means the ordinary port on both wildcard families, IPv6 first"
+        );
+    }
+
+    #[test]
+    fn an_explicit_bind_replaces_the_defaults_rather_than_augmenting_them() {
+        let args = parse(&["--bind", "127.0.0.1:2112"]).unwrap();
+        assert_eq!(
+            args.resolve_binds(),
+            [SocketAddr::from((Ipv4Addr::LOCALHOST, 2112))],
+            "one explicit bind means exactly that one listener, not that listener plus defaults"
+        );
+    }
+
+    #[test]
+    fn repeated_explicit_binds_are_unaffected_by_the_default_resolution() {
+        let args = parse(&["--bind", "127.0.0.1:2112", "--bind", "[::1]:2112"]).unwrap();
+        assert_eq!(args.resolve_binds(), args.bind);
+    }
+
     #[test]
     fn bind_is_repeatable_and_keeps_the_requested_order() {
         let args = parse(&[
@@ -404,10 +486,165 @@ mod tests {
         assert!(parse(&["--bind", "127.0.0.1:2112", "--idle-timeout", "ms"]).is_err());
     }
 
+    #[test]
+    fn an_empty_hmac_key_is_rejected() {
+        let err = parse(&["--bind", "127.0.0.1:2112", "--hmac", ""]).unwrap_err();
+        assert!(err.to_string().contains("HMAC key must not be empty"));
+    }
+
+    #[test]
+    fn a_whitespace_only_hmac_key_is_accepted_literally() {
+        let config = bound(&["--hmac", " "]).server_config();
+        assert_eq!(config.hmac_key(), Some(b" ".as_slice()));
+    }
+
     #[test]
     fn a_zero_maximum_duration_is_not_a_spelling_of_no_maximum() {
         assert!(parse(&["--bind", "127.0.0.1:2112", "--max-duration", "0"]).is_err());
         assert!(parse(&["--bind", "127.0.0.1:2112", "--max-duration", "0s"]).is_err());
         assert_eq!(bound(&[]).server_config().max_test_duration(), None);
     }
+
+    /// Runs `body` with the given environment variables set, restoring
+    /// whatever was there before (present or absent) once `body` returns.
+    /// Held under `with_env_lock` for the whole span, including `body`, so a
+    /// `parse` call elsewhere never observes a partially-applied environment.
+    fn with_env<T>(vars: &[(&str, &str)], body: impl FnOnce() -> T) -> T {
+        with_env_lock(|| {
+            let previous: Vec<(&str, Option<String>)> = vars
+                .iter()
+                .map(|(k, _)| (*k, std::env::var(k).ok()))
+                .collect();
+            for (k, v) in vars {
+                std::env::set_var(k, v);
+            }
+            let result = body();
+            for (k, v) in previous {
+                match v {
+                    Some(v) => std::env::set_var(k, v),
+                    None => std::env::remove_var(k),
+                }
+            }
+            result
+        })
+    }
+
+    #[test]
+    fn environment_variables_supply_policy_when_no_flag_is_given() {
+        with_env(
+            &[
+                ("IRTT_SERVER_MAX_SESSIONS", "512"),
+                ("IRTT_SERVER_MAX_PACKET_LENGTH", "1472"),
+                ("IRTT_SERVER_MIN_INTERVAL", "20ms"),
+                ("IRTT_SERVER_BURST", "3"),
+                ("IRTT_SERVER_IDLE_TIMEOUT", "30s"),
+                ("IRTT_SERVER_MAX_DURATION", "2m"),
+                ("IRTT_SERVER_TIMESTAMP_ALLOWANCE", "single"),
+                ("IRTT_SERVER_HMAC", "secret"),
+                ("IRTT_SERVER_NO_DSCP", "true"),
+            ],
+            || {
+                let config = parse(&["--bind", "127.0.0.1:2112"])
+                    .unwrap()
+                    .server_config();
+                assert_eq!(config.max_sessions(), 512);
+                assert_eq!(config.max_packet_length(), 1472);
+                assert_eq!(config.min_send_interval(), Duration::from_millis(20));
+                assert_eq!(config.burst_allowance(), 3);
+                assert_eq!(config.idle_timeout(), Duration::from_secs(30));
+                assert_eq!(config.max_test_duration(), Some(Duration::from_secs(120)));
+                assert_eq!(config.timestamp_allowance(), TimestampAllowance::Single);
+                assert_eq!(config.hmac_key(), Some(b"secret".as_slice()));
+                assert!(!config.dscp_allowed());
+            },
+        );
+    }
+
+    /// `IRTT_SERVER_NO_DSCP` is the one policy variable whose value is a
+    /// boolean rather than a number, a duration or a string, and the
+    /// container/orchestrator deployments this whole environment surface
+    /// exists for spell booleans `1`/`0`. clap's default parser for a flag
+    /// accepts only the literals `true`/`false` and turns everything else
+    /// into a *parse failure*, so `IRTT_SERVER_NO_DSCP=1` used to stop the
+    /// server from starting at all rather than enabling the flag. Falsey
+    /// semantics are what keeps that from being a startup failure.
+    #[test]
+    fn the_no_dscp_environment_variable_accepts_ordinary_boolean_spellings() {
+        for value in ["1", "true", "TRUE", "yes", "on", "enabled"] {
+            with_env(&[("IRTT_SERVER_NO_DSCP", value)], || {
+                let config = parse(&["--bind", "127.0.0.1:2112"])
+                    .expect("a truthy value must not fail argument parsing")
+                    .server_config();
+                assert!(!config.dscp_allowed(), "IRTT_SERVER_NO_DSCP={value}");
+            });
+        }
+
+        for value in ["0", "false", "no", "off", ""] {
+            with_env(&[("IRTT_SERVER_NO_DSCP", value)], || {
+                let config = parse(&["--bind", "127.0.0.1:2112"])
+                    .expect("a falsey value must not fail argument parsing")
+                    .server_config();
+                assert!(config.dscp_allowed(), "IRTT_SERVER_NO_DSCP={value}");
+            });
+        }
+    }
+
+    /// The command-line flag stays a flag: it takes no value, whatever the
+    /// environment parser accepts.
+    #[test]
+    fn the_no_dscp_flag_still_takes_no_command_line_value() {
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--no-dscp=false"]).is_err());
+        assert!(!bound(&["--no-dscp"]).server_config().dscp_allowed());
+    }
+
+    #[test]
+    fn an_explicit_flag_overrides_the_environment() {
+        with_env(&[("IRTT_SERVER_MAX_SESSIONS", "512")], || {
+            let config = parse(&["--bind", "127.0.0.1:2112", "--max-sessions", "4"])
+                .unwrap()
+                .server_config();
+            assert_eq!(
+                config.max_sessions(),
+                4,
+                "the command-line value wins over the environment"
+            );
+        });
+    }
+
+    #[test]
+    fn the_environment_wins_over_the_built_in_default() {
+        with_env(&[("IRTT_SERVER_BURST", "9")], || {
+            let config = bound(&[]).server_config();
+            assert_eq!(
+                config.burst_allowance(),
+                9,
+                "an unset flag still falls back to the environment before the library default"
+            );
+        });
+    }
+
+    #[test]
+    fn irtt_server_bind_supplies_a_single_address_from_the_environment() {
+        with_env(&[("IRTT_SERVER_BIND", "127.0.0.1:2113")], || {
+            let args = parse(&[]).unwrap();
+            assert_eq!(args.bind, [SocketAddr::from((Ipv4Addr::LOCALHOST, 2113))]);
+        });
+    }
+
+    #[test]
+    fn an_explicit_bind_flag_overrides_irtt_server_bind() {
+        with_env(&[("IRTT_SERVER_BIND", "127.0.0.1:2113")], || {
+            let args = parse(&["--bind", "[::1]:2112"]).unwrap();
+            assert_eq!(args.bind, [SocketAddr::from((Ipv6Addr::LOCALHOST, 2112))]);
+        });
+    }
+
+    #[test]
+    fn leaving_irtt_server_bind_unset_keeps_the_wildcard_default() {
+        let args = parse(&[]).unwrap();
+        assert!(
+            args.bind.is_empty(),
+            "with no --bind and no IRTT_SERVER_BIND, resolve_binds still falls back to the wildcard pair"
+        );
+    }
 }

crates/irtt-app/src/cmd/server/env_lock.rs

@@ -0,0 +1,30 @@
+//! Serializes every test in this module tree that touches process
+//! environment variables.
+//!
+//! `ServerArgs` parsing reads `IRTT_SERVER_*` via `clap`'s `env` support, and
+//! `std::env::set_var`/`remove_var` mutate genuinely process-wide state.
+//! Every test that parses `ServerArgs` — whether or not it sets an env var
+//! itself — must go through [`with_env_lock`], or a parse in one test thread
+//! can observe a value another thread's test set only for the duration of
+//! its own assertions. Reentrant per-thread, since a test that sets env vars
+//! typically calls `parse` again from inside its own locked section.
+
+use std::{cell::Cell, sync::Mutex};
+
+static ENV_LOCK: Mutex<()> = Mutex::new(());
+thread_local! {
+    static ENV_LOCK_HELD: Cell<bool> = const { Cell::new(false) };
+}
+
+pub(crate) fn with_env_lock<T>(f: impl FnOnce() -> T) -> T {
+    if ENV_LOCK_HELD.with(Cell::get) {
+        return f();
+    }
+    let _guard = ENV_LOCK
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    ENV_LOCK_HELD.with(|held| held.set(true));
+    let result = f();
+    ENV_LOCK_HELD.with(|held| held.set(false));
+    result
+}

crates/irtt-app/src/cmd/server/mod.rs

@@ -1,4 +1,6 @@
 pub mod args;
+#[cfg(test)]
+pub(crate) mod env_lock;
 pub mod run;
 
 pub use args::ServerArgs;

crates/irtt-app/src/cmd/server/run.rs

@@ -0,0 +1,209 @@
+use std::{
+    net::SocketAddr,
+    sync::atomic::{AtomicBool, Ordering},
+    time::Duration,
+};
+
+use irtt_server::{address_family_available, ServerSet, ServerSetError};
+
+use super::args::ServerArgs;
+
+/// How often the shutdown future samples the process-wide signal flag.
+///
+/// The flag a signal handler sets has no async wake mechanism, so the future
+/// polls it on a timer rather than spinning. `ServerSet::run` owns everything
+/// after that future becomes ready, including fanning it out to the listeners.
+const SHUTDOWN_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// Runs the configured listeners until the process is asked to shut down.
+///
+/// The applet owns exactly one current-thread Tokio runtime and one
+/// [`ServerSet`], whatever number of addresses was requested. A single `--bind`
+/// is an ordinary set of one and takes the same path as a set of several: one
+/// construction, one shutdown future, one supervision rule. Listener
+/// concurrency is async I/O concurrency and needs no worker threads.
+pub fn run_server(
+    args: ServerArgs,
+    shutdown_requested: &AtomicBool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()?;
+    runtime.block_on(serve(args, shutdown_requested))
+}
+
+async fn serve(
+    args: ServerArgs,
+    shutdown_requested: &AtomicBool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let config = args.server_config();
+    let binds = args.resolve_binds();
+    let is_implicit_default = args.bind.is_empty();
+    let set = match ServerSet::bind(binds.clone(), config.clone()).await {
+        Ok(set) => set,
+        Err(ServerSetError::ListenerSetup { addr, source }) => {
+            let family_available = address_family_available(addr);
+            match implicit_default_fallback(is_implicit_default, family_available, &binds, addr) {
+                Some(remaining) => {
+                    eprintln!(
+                        "irtt-server: default listener {addr} unavailable ({source}); \
+                         continuing with the remaining default listener"
+                    );
+                    // `remaining`'s lone survivor is bound exactly as it
+                    // would be alone: the address family that just failed
+                    // has no local support at all, so nothing on that family
+                    // could be competing for the surviving listener's port.
+                    ServerSet::bind(remaining, config).await?
+                }
+                None => return Err(ServerSetError::ListenerSetup { addr, source }.into()),
+            }
+        }
+        Err(err) => return Err(err.into()),
+    };
+    // Only once every listener is up. Announcing one address and then failing
+    // to bind the next would report a service that never started.
+    for addr in set.local_addrs() {
+        eprintln!("irtt-server: listening on {addr}");
+    }
+    set.run(shutdown_signal(shutdown_requested)).await?;
+    Ok(())
+}
+
+/// Whether a listener-setup failure for `failed_addr` should be retried with
+/// a reduced bind set instead of failing the whole invocation, and if so,
+/// what to retry with.
+///
+/// Only the implicit zero-argument default gets this treatment, and only
+/// when `failed_addr`'s own address family has no local support on this host
+/// at all (`family_available` is `false`) — not merely because its specific
+/// port was unavailable for some other reason: already in use, permission
+/// denied, no safe wildcard reply-source path, or anything else
+/// `ServerSet::bind` can fail with. Those are real configuration or
+/// environment problems this invocation should fail on, not silently work
+/// around by dropping a listener the operator asked for. An explicit
+/// `--bind` list keeps the library's ordinary all-or-nothing behavior
+/// regardless.
+fn implicit_default_fallback(
+    is_implicit_default: bool,
+    family_available: bool,
+    original_binds: &[SocketAddr],
+    failed_addr: SocketAddr,
+) -> Option<Vec<SocketAddr>> {
+    if !is_implicit_default || family_available || !original_binds.contains(&failed_addr) {
+        return None;
+    }
+    let remaining: Vec<SocketAddr> = original_binds
+        .iter()
+        .copied()
+        .filter(|&addr| addr != failed_addr)
+        .collect();
+    (!remaining.is_empty()).then_some(remaining)
+}
+
+async fn shutdown_signal(shutdown_requested: &AtomicBool) {
+    while !shutdown_requested.load(Ordering::Relaxed) {
+        tokio::time::sleep(SHUTDOWN_POLL_INTERVAL).await;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use clap::Parser;
+
+    use super::*;
+    use crate::cmd::server::env_lock::with_env_lock;
+
+    /// The ordinary invocation, and the one that keeps the single-listener case
+    /// on the same orchestration path as every other.
+    #[test]
+    fn an_already_requested_shutdown_binds_one_listener_and_returns() {
+        let args = with_env_lock(|| {
+            ServerArgs::try_parse_from(["irtt-server", "--bind", "127.0.0.1:0"]).unwrap()
+        });
+        let shutdown_requested = AtomicBool::new(true);
+
+        run_server(args, &shutdown_requested).unwrap();
+    }
+
+    #[test]
+    fn an_already_requested_shutdown_binds_every_listener_and_returns() {
+        let args = with_env_lock(|| {
+            ServerArgs::try_parse_from([
+                "irtt-server",
+                "--bind",
+                "127.0.0.1:0",
+                "--bind",
+                "127.0.0.1:0",
+            ])
+            .unwrap()
+        });
+        let shutdown_requested = AtomicBool::new(true);
+
+        run_server(args, &shutdown_requested).unwrap();
+    }
+
+    fn default_binds() -> Vec<SocketAddr> {
+        with_env_lock(|| {
+            ServerArgs::try_parse_from(["irtt-server"])
+                .unwrap()
+                .resolve_binds()
+        })
+    }
+
+    #[test]
+    fn implicit_default_losing_an_unsupported_family_falls_back_to_the_other() {
+        let binds = default_binds();
+        let failed = binds[0];
+
+        let remaining = implicit_default_fallback(true, false, &binds, failed).unwrap();
+
+        assert_eq!(remaining, [binds[1]]);
+    }
+
+    #[test]
+    fn a_supported_familys_failure_never_falls_back() {
+        // The family itself works fine here; whatever made this specific
+        // bind fail (port in use, permission, ...) is a real problem this
+        // invocation should surface, not paper over.
+        let binds = default_binds();
+
+        assert_eq!(
+            implicit_default_fallback(true, true, &binds, binds[0]),
+            None,
+            "family_available: true means this is not a family-support problem"
+        );
+    }
+
+    #[test]
+    fn explicit_binds_never_fall_back() {
+        let binds = default_binds();
+
+        assert_eq!(
+            implicit_default_fallback(false, false, &binds, binds[0]),
+            None
+        );
+    }
+
+    #[test]
+    fn a_failure_outside_the_requested_set_does_not_fall_back() {
+        let binds = default_binds();
+        let unrelated = SocketAddr::from(([127, 0, 0, 1], 2113));
+
+        assert_eq!(
+            implicit_default_fallback(true, false, &binds, unrelated),
+            None,
+            "the failing address must actually be one this invocation asked for"
+        );
+    }
+
+    #[test]
+    fn losing_the_only_remaining_default_address_does_not_fall_back() {
+        let single = [SocketAddr::from(([0, 0, 0, 0], 2112))];
+
+        assert_eq!(
+            implicit_default_fallback(true, false, &single, single[0]),
+            None,
+            "no address would be left to retry with"
+        );
+    }
+}

crates/irtt-app/src/cmd/tui/args.rs

@@ -14,13 +14,13 @@ pub const DEFAULT_TUI_DURATION: Duration = Duration::ZERO;
 #[derive(Debug, Clone, Parser)]
 #[command(name = "irtt-tui", about = "Minimal IRTT-compatible TUI client")]
 pub struct TuiArgs {
-    /// Server address/host, optionally prefixed with LABEL=. Repeat for multi-target mode.
+    /// Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.
     #[arg(
         value_name = "TARGET",
         num_args = 1..,
         required = true,
         value_parser = parse_target,
-        long_help = "Server address/host, optionally prefixed with LABEL=. Repeat for multi-target mode.\n\nExplicit labels are used in the legend and status table.\n\nExamples:\n  irtt-tui host.example\n  irtt-tui eu=host.example\n  irtt-tui eu=host-a.example us=host-b.example"
+        long_help = "Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.\n\nExplicit labels are used in the legend and status table. A target without @hmac= inherits --hmac; @hmac= disables it for that target.\n\nExamples:\n  irtt-tui host.example\n  irtt-tui eu=host.example\n  irtt-tui eu=host-a.example@hmac=secret us=host-b.example"
     )]
     pub targets: Vec<TargetArg>,
 
@@ -58,6 +58,7 @@ impl TuiArgs {
             TargetSelection {
                 targets: &self.targets,
                 pacing: self.pacing,
+                stdin_controlled: false,
             },
         )
     }
@@ -107,8 +108,7 @@ mod tests {
     fn tui_parser_defaults_to_continuous_and_has_no_output_option() {
         let args = parse(&["127.0.0.1:2112"]).unwrap();
         assert_eq!(args.targets.len(), 1);
-        assert_eq!(args.targets[0].label, None);
+        assert_eq!(args.prepare().unwrap().targets[0].label, "127.0.0.1:2112");
-        assert_eq!(args.targets[0].addr, "127.0.0.1:2112");
         assert_eq!(args.pacing, GroupPacingArg::Staggered);
         assert_eq!(args.duration, DEFAULT_TUI_DURATION);
         assert!(args.is_continuous());
@@ -181,8 +181,8 @@ mod tests {
 
     #[test]
     fn invalid_labelled_target_syntax_is_rejected() {
-        assert!(parse(&["=127.0.0.1:2112"]).is_err());
+        assert!(parse(&["=127.0.0.1:2112"]).unwrap().prepare().is_err());
-        assert!(parse(&["label="]).is_err());
+        assert!(parse(&["label="]).unwrap().prepare().is_err());
     }
 
     #[test]
@@ -270,6 +270,14 @@ mod tests {
         assert_eq!(shared.socket_config.ttl, tui.socket_config.ttl);
     }
 
+    #[test]
+    fn an_empty_hmac_key_is_rejected_via_the_shared_args() {
+        // CommonClientArgs is flattened into both the client and TUI parsers,
+        // so proving rejection once here covers both without duplicating it.
+        let err = parse(&["--hmac", "", "127.0.0.1:2112"]).unwrap_err();
+        assert!(err.to_string().contains("HMAC key must not be empty"));
+    }
+
     #[test]
     fn tui_help_lists_multi_target_options() {
         let help = TuiArgs::command().render_help().to_string();

crates/irtt-app/src/entry.rs

@@ -0,0 +1,133 @@
+#[cfg(any(feature = "client", feature = "server", feature = "tui"))]
+use std::sync::{atomic::AtomicBool, Arc};
+use std::{env, ffi::OsString, process::ExitCode};
+
+use crate::applet::{dispatch_from_argv, AppletDispatch, RequestedApplet};
+#[cfg(any(feature = "client", feature = "server", feature = "tui"))]
+use crate::signal::install_signal_handler;
+
+/// Entry point for the `irtt-rs` multicall dispatcher binary.
+///
+/// Chooses an applet by subcommand or by recognized argv0 and may reference
+/// every applet enabled by the active feature set.
+pub fn dispatcher_main() -> ExitCode {
+    run_with_exit_code("irtt-rs", run_dispatcher_from_env)
+}
+
+/// Entry point for the dedicated `irtt-client` binary.
+///
+/// Runs the stream client directly; it never consults argv0 or the applet
+/// dispatcher, so a renamed or copied executable still runs the client.
+#[cfg(feature = "client")]
+pub fn client_main() -> ExitCode {
+    run_with_exit_code("irtt-client", || {
+        run_client_applet(env::args_os().collect())
+    })
+}
+
+/// Entry point for the dedicated `irtt-tui` binary.
+///
+/// Runs the terminal UI directly; it never consults argv0 or the applet
+/// dispatcher, so a renamed or copied executable still runs the TUI.
+#[cfg(feature = "tui")]
+pub fn tui_main() -> ExitCode {
+    run_with_exit_code("irtt-tui", || run_tui_applet(env::args_os().collect()))
+}
+
+/// Entry point for the dedicated `irtt-server` binary.
+///
+/// Runs the server directly; it never consults argv0 or the applet
+/// dispatcher, so a renamed or copied executable still runs the server.
+#[cfg(feature = "server")]
+pub fn server_main() -> ExitCode {
+    run_with_exit_code("irtt-server", || {
+        run_server_applet(env::args_os().collect())
+    })
+}
+
+fn run_with_exit_code(
+    program: &str,
+    f: impl FnOnce() -> Result<(), Box<dyn std::error::Error>>,
+) -> ExitCode {
+    match f() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(err) => {
+            eprintln!("{program}: {err}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn run_dispatcher_from_env() -> Result<(), Box<dyn std::error::Error>> {
+    let argv: Vec<OsString> = env::args_os().collect();
+    let (requested, argv) = match dispatch_from_argv(argv)? {
+        AppletDispatch::Run { applet, argv } => (applet, argv),
+        AppletDispatch::Help(help) => {
+            print!("{help}");
+            return Ok(());
+        }
+    };
+
+    match requested {
+        RequestedApplet::Client => run_client_applet(argv),
+        RequestedApplet::Tui => run_tui_applet(argv),
+        RequestedApplet::Server => run_server_applet(argv),
+    }
+}
+
+/// Installs the shutdown signal handler shared by every applet and hands the
+/// resulting flag to `f`.
+#[cfg(any(feature = "client", feature = "server", feature = "tui"))]
+fn with_shutdown_flag(
+    f: impl FnOnce(&AtomicBool) -> Result<(), Box<dyn std::error::Error>>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let shutdown_requested = Arc::new(AtomicBool::new(false));
+    install_signal_handler(Arc::clone(&shutdown_requested))
+        .map_err(|err| format!("failed to install signal handler: {err}"))?;
+    f(shutdown_requested.as_ref())
+}
+
+#[cfg(feature = "client")]
+fn run_client_applet(argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    use clap::Parser;
+
+    with_shutdown_flag(|shutdown_requested| {
+        let args = crate::cmd::client::ClientArgs::parse_from(argv);
+        crate::cmd::client::run_stream(args, shutdown_requested)
+    })
+}
+
+#[cfg(not(feature = "client"))]
+fn run_client_applet(_argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    Err("client applet is not available; rebuild with the client feature".into())
+}
+
+#[cfg(feature = "server")]
+fn run_server_applet(argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    use clap::Parser;
+
+    with_shutdown_flag(|shutdown_requested| {
+        let args = crate::cmd::server::ServerArgs::parse_from(argv);
+        crate::cmd::server::run_server(args, shutdown_requested)
+    })
+}
+
+#[cfg(not(feature = "server"))]
+fn run_server_applet(_argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    Err("server applet is not available; rebuild with the server feature".into())
+}
+
+#[cfg(feature = "tui")]
+fn run_tui_applet(argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    use clap::Parser;
+
+    with_shutdown_flag(|shutdown_requested| {
+        let args = crate::cmd::tui::TuiArgs::parse_from(argv);
+        crate::cmd::tui::run_tui(args, shutdown_requested)
+    })
+}
+
+#[cfg(not(feature = "tui"))]
+fn run_tui_applet(_argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    Err("TUI applet is not available; rebuild with the tui feature".into())
+}

crates/irtt-app/src/shared/client/args.rs

@@ -15,7 +15,7 @@ pub struct CommonClientArgs {
     pub length: u32,
 
     /// HMAC key.
-    #[arg(long)]
+    #[arg(long, value_parser = parse_hmac_key)]
     pub hmac: Option<String>,
 
     /// Clock mode to request.
@@ -189,6 +189,13 @@ pub fn parse_length(input: &str) -> Result<u32, String> {
     Ok(length)
 }
 
+pub fn parse_hmac_key(input: &str) -> Result<String, String> {
+    if input.is_empty() {
+        return Err("HMAC key must not be empty".to_owned());
+    }
+    Ok(input.to_owned())
+}
+
 pub fn parse_server_fill(input: &str) -> Result<String, String> {
     if input.is_empty() {
         return Err("server fill must not be empty".to_owned());

crates/irtt-app/src/shared/client/mod.rs

@@ -9,9 +9,12 @@ pub use args::{
     ClockArg, CommonClientArgs, ReceivedStatsArg, TimestampArg,
 };
 pub use config::{expected_probe_count, DEFAULT_RECV_TIMEOUT};
-pub use prepare::{prepare_managed_run, ManagedRunSetup, TargetSelection, MANAGED_EVENT_CAPACITY};
+pub use prepare::{
+    prepare_managed_run, ManagedRunSetup, TargetSelection, MANAGED_EVENT_CAPACITY,
+    STDIN_MAX_DESIRED_TARGETS, STDIN_MAX_LIVE_TARGET_GENERATIONS, STDIN_OUTCOME_HISTORY_LIMIT,
+};
 pub use session::is_shutdown_requested;
 pub use targets::{
-    parse_target, prepare_managed_targets, target_specs, GroupPacingArg, PreparedTarget, TargetArg,
+    parse_stdin_target_set, parse_target, prepare_managed_targets, target_specs, GroupPacingArg,
-    TargetSpec,
+    PreparedTarget, TargetArg, TargetSpec,
 };

crates/irtt-app/src/shared/client/prepare.rs

@@ -22,6 +22,9 @@ use super::{
 
 /// Capacity of the lossy managed presentation event channel.
 pub const MANAGED_EVENT_CAPACITY: usize = 16_384;
+pub const STDIN_MAX_DESIRED_TARGETS: usize = 128;
+pub const STDIN_MAX_LIVE_TARGET_GENERATIONS: usize = 256;
+pub const STDIN_OUTCOME_HISTORY_LIMIT: usize = 256;
 
 /// Target and pacing arguments common to the client applets.
 ///
@@ -31,6 +34,7 @@ pub const MANAGED_EVENT_CAPACITY: usize = 16_384;
 pub struct TargetSelection<'a> {
     pub targets: &'a [TargetArg],
     pub pacing: GroupPacingArg,
+    pub stdin_controlled: bool,
 }
 
 /// Everything a managed run needs, prepared and validated together.
@@ -46,6 +50,8 @@ pub struct ManagedRunSetup {
     pub client: ClientConfig,
     /// Send coordination across active targets.
     pub pacing: ManagedPacing,
+    /// Whether this stream may replace its desired set from stdin.
+    pub stdin_controlled: bool,
 }
 
 impl ManagedRunSetup {
@@ -70,7 +76,7 @@ impl ManagedRunSetup {
     /// Managed driver configuration for this run.
     pub fn managed_config(&self) -> ManagedClientConfig {
         let target_count = self.target_count();
-        ManagedClientConfig {
+        let mut config = ManagedClientConfig {
             client: self.client.clone(),
             pacing: self.pacing,
             completion: ManagedCompletionPolicy::FinishWhenQuiescent,
@@ -78,7 +84,13 @@ impl ManagedRunSetup {
             outcome_history_limit: target_count,
             max_live_target_generations: target_count,
             ..ManagedClientConfig::default()
+        };
+        if self.stdin_controlled {
+            config.completion = ManagedCompletionPolicy::ExplicitStop;
+            config.outcome_history_limit = STDIN_OUTCOME_HISTORY_LIMIT;
+            config.max_live_target_generations = STDIN_MAX_LIVE_TARGET_GENERATIONS;
         }
+        config
     }
 }
 
@@ -91,12 +103,22 @@ pub fn prepare_managed_run(
     duration: Duration,
     selection: TargetSelection<'_>,
 ) -> Result<ManagedRunSetup, String> {
-    let specs = target_specs(selection.targets)?;
+    let specs = if selection.stdin_controlled {
+        if selection.targets.len() > STDIN_MAX_DESIRED_TARGETS {
+            return Err(format!(
+                "initial target set exceeds the {STDIN_MAX_DESIRED_TARGETS}-target limit"
+            ));
+        }
+        super::targets::target_specs_with_empty(selection.targets, true)?
+    } else {
+        target_specs(selection.targets)?
+    };
     let targets = prepare_managed_targets(specs)?;
     Ok(ManagedRunSetup {
         targets,
         client: common.to_client_config(duration),
         pacing: selection.pacing.into(),
+        stdin_controlled: selection.stdin_controlled,
     })
 }
 
@@ -119,17 +141,11 @@ mod tests {
     }
 
     fn unlabeled(addr: &str) -> TargetArg {
-        TargetArg {
+        TargetArg::new(addr)
-            label: None,
-            addr: addr.to_owned(),
-        }
     }
 
     fn labeled(label: &str, addr: &str) -> TargetArg {
-        TargetArg {
+        TargetArg::new(format!("{label}={addr}"))
-            label: Some(label.to_owned()),
-            addr: addr.to_owned(),
-        }
     }
 
     fn prepare(
@@ -137,7 +153,15 @@ mod tests {
         pacing: GroupPacingArg,
         duration: Duration,
     ) -> Result<ManagedRunSetup, String> {
-        prepare_managed_run(&common(&[]), duration, TargetSelection { targets, pacing })
+        prepare_managed_run(
+            &common(&[]),
+            duration,
+            TargetSelection {
+                targets,
+                pacing,
+                stdin_controlled: false,
+            },
+        )
     }
 
     #[test]
@@ -212,6 +236,7 @@ mod tests {
             TargetSelection {
                 targets: &targets,
                 pacing: GroupPacingArg::Staggered,
+                stdin_controlled: false,
             },
         )
         .unwrap();

crates/irtt-app/src/shared/client/targets.rs

@@ -0,0 +1,491 @@
+use std::{collections::HashSet, fmt};
+
+use clap::ValueEnum;
+use irtt_client::{
+    managed::{ManagedPacing, ManagedTargetConfig, TargetId},
+    ClientAuthConfig,
+};
+
+/// One raw positional target captured by Clap.
+///
+/// Parsing happens during run preparation so invalid target syntax never makes
+/// Clap include the original argument (which may carry an HMAC key) in an
+/// error diagnostic.
+#[derive(Clone, PartialEq, Eq)]
+pub struct TargetArg {
+    input: String,
+}
+
+impl TargetArg {
+    pub fn new(input: impl Into<String>) -> Self {
+        Self {
+            input: input.into(),
+        }
+    }
+}
+
+impl fmt::Debug for TargetArg {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("TargetArg(<redacted>)")
+    }
+}
+
+/// Capture one positional target without exposing it through Clap diagnostics.
+pub fn parse_target(input: &str) -> Result<TargetArg, String> {
+    Ok(TargetArg::new(input))
+}
+
+#[derive(Clone, PartialEq, Eq)]
+pub enum TargetAuth {
+    Inherit,
+    Override(Vec<u8>),
+    Disable,
+}
+
+impl fmt::Debug for TargetAuth {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Inherit => f.write_str("Inherit"),
+            Self::Override(_) => f.write_str("Override(<redacted>)"),
+            Self::Disable => f.write_str("Disable"),
+        }
+    }
+}
+
+#[derive(Clone, PartialEq, Eq)]
+pub struct TargetSpec {
+    pub label: String,
+    pub addr: String,
+    pub auth: TargetAuth,
+}
+
+impl fmt::Debug for TargetSpec {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("TargetSpec")
+            .field("label", &self.label)
+            .field("addr", &self.addr)
+            .field("auth", &self.auth)
+            .finish()
+    }
+}
+
+#[derive(Clone)]
+pub struct PreparedTarget {
+    pub label: String,
+    pub managed: ManagedTargetConfig,
+}
+
+impl fmt::Debug for PreparedTarget {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("PreparedTarget")
+            .field("label", &self.label)
+            .field("server_addr", &self.managed.server_addr)
+            .field(
+                "auth",
+                &match &self.managed.auth {
+                    None => TargetAuth::Inherit,
+                    Some(ClientAuthConfig { hmac_key: Some(_) }) => {
+                        TargetAuth::Override(Vec::new())
+                    }
+                    Some(ClientAuthConfig { hmac_key: None }) => TargetAuth::Disable,
+                },
+            )
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum GroupPacingArg {
+    Staggered,
+    Burst,
+}
+
+impl From<GroupPacingArg> for ManagedPacing {
+    fn from(value: GroupPacingArg) -> Self {
+        match value {
+            GroupPacingArg::Staggered => Self::Staggered,
+            GroupPacingArg::Burst => Self::Burst,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TargetParseError {
+    EmptyLabel,
+    EmptyAddress,
+    InvalidEscape,
+    EmptyTarget,
+}
+
+impl fmt::Display for TargetParseError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::EmptyLabel => "target label must not be empty",
+            Self::EmptyAddress => "target address must not be empty",
+            Self::InvalidEscape => "invalid target escape sequence",
+            Self::EmptyTarget => "target must not be empty",
+        };
+        f.write_str(message)
+    }
+}
+
+fn split_unescaped(input: &str, delimiter: char) -> Result<Vec<&str>, TargetParseError> {
+    let mut parts = Vec::new();
+    let mut start = 0;
+    let mut escaped = false;
+    for (index, ch) in input.char_indices() {
+        if escaped {
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else if ch == delimiter {
+            parts.push(&input[start..index]);
+            start = index + ch.len_utf8();
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    parts.push(&input[start..]);
+    Ok(parts)
+}
+
+fn first_unescaped(input: &str, delimiter: char) -> Result<Option<usize>, TargetParseError> {
+    let mut escaped = false;
+    for (index, ch) in input.char_indices() {
+        if escaped {
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else if ch == delimiter {
+            return Ok(Some(index));
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    Ok(None)
+}
+
+fn unescape(input: &str) -> Result<String, TargetParseError> {
+    let mut output = String::with_capacity(input.len());
+    let mut escaped = false;
+    for ch in input.chars() {
+        if escaped {
+            if !matches!(ch, '\\' | '=' | ';' | ',' | '@') {
+                return Err(TargetParseError::InvalidEscape);
+            }
+            output.push(ch);
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else {
+            output.push(ch);
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    Ok(output)
+}
+
+fn hmac_modifier(input: &str) -> Result<Option<usize>, TargetParseError> {
+    let mut escaped = false;
+    for (index, ch) in input.char_indices() {
+        if escaped {
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else if input[index..].starts_with("@hmac=") {
+            return Ok(Some(index));
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    Ok(None)
+}
+
+fn parse_target_syntax(
+    input: &str,
+) -> Result<(Option<String>, String, TargetAuth), TargetParseError> {
+    if input.is_empty() {
+        return Err(TargetParseError::EmptyTarget);
+    }
+    let (main, auth) = match hmac_modifier(input)? {
+        Some(index) => {
+            let value = unescape(&input[index + "@hmac=".len()..])?;
+            let auth = if value.is_empty() {
+                TargetAuth::Disable
+            } else {
+                TargetAuth::Override(value.into_bytes())
+            };
+            (&input[..index], auth)
+        }
+        None => (input, TargetAuth::Inherit),
+    };
+    let (label, address) = match first_unescaped(main, '=')? {
+        None => (None, unescape(main)?),
+        Some(index) => {
+            let label = unescape(&main[..index])?;
+            let address = unescape(&main[index + '='.len_utf8()..])?;
+            (Some(label), address)
+        }
+    };
+    if label.as_deref().is_some_and(str::is_empty) {
+        return Err(TargetParseError::EmptyLabel);
+    }
+    if address.is_empty() {
+        return Err(TargetParseError::EmptyAddress);
+    }
+    Ok((label, address, auth))
+}
+
+pub(crate) fn target_specs_with_empty(
+    targets: &[TargetArg],
+    allow_empty: bool,
+) -> Result<Vec<TargetSpec>, String> {
+    let mut specs = Vec::with_capacity(targets.len());
+    let mut unlabeled_counts = std::collections::HashMap::<String, usize>::new();
+    for (index, target) in targets.iter().enumerate() {
+        let (explicit_label, addr, auth) = parse_target_syntax(&target.input)
+            .map_err(|error| format!("invalid target {}: {error}", index + 1))?;
+        let label = match explicit_label {
+            Some(label) => label,
+            None => {
+                let count = unlabeled_counts.entry(addr.clone()).or_default();
+                *count += 1;
+                if *count == 1 {
+                    addr.clone()
+                } else {
+                    format!("{}#{}", addr, *count)
+                }
+            }
+        };
+        specs.push(TargetSpec { label, addr, auth });
+    }
+
+    if specs.is_empty() && !allow_empty {
+        return Err("at least one target is required unless --list-columns is set".to_owned());
+    }
+
+    let mut labels = HashSet::new();
+    for spec in &specs {
+        if !labels.insert(spec.label.clone()) {
+            return Err("duplicate target label".to_owned());
+        }
+    }
+
+    Ok(specs)
+}
+
+pub fn target_specs(targets: &[TargetArg]) -> Result<Vec<TargetSpec>, String> {
+    target_specs_with_empty(targets, false)
+}
+
+pub fn prepare_managed_targets(specs: Vec<TargetSpec>) -> Result<Vec<PreparedTarget>, String> {
+    let mut targets = Vec::with_capacity(specs.len());
+    for spec in specs {
+        let mut managed = ManagedTargetConfig::new(TargetId::from(spec.label.clone()), spec.addr);
+        managed.auth = match spec.auth {
+            TargetAuth::Inherit => None,
+            TargetAuth::Override(hmac_key) => Some(ClientAuthConfig {
+                hmac_key: Some(hmac_key),
+            }),
+            TargetAuth::Disable => Some(ClientAuthConfig { hmac_key: None }),
+        };
+        targets.push(PreparedTarget {
+            label: spec.label,
+            managed,
+        });
+    }
+    Ok(targets)
+}
+
+/// Parse one complete stdin target set after its line terminator was removed.
+///
+/// Commas frame stdin elements only; positional target arguments do not use
+/// this framing and may therefore contain raw commas.
+pub fn parse_stdin_target_set(
+    record: &str,
+    maximum_targets: usize,
+) -> Result<Vec<PreparedTarget>, String> {
+    if record == "[]" {
+        return Ok(Vec::new());
+    }
+    let elements = split_unescaped(record, ',').map_err(|error| error.to_string())?;
+    if elements.len() > maximum_targets {
+        return Err(format!(
+            "target set exceeds the {maximum_targets}-target limit"
+        ));
+    }
+    let args = elements.into_iter().map(TargetArg::new).collect::<Vec<_>>();
+    prepare_managed_targets(target_specs_with_empty(&args, true)?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn target(input: &str) -> TargetArg {
+        TargetArg::new(input)
+    }
+
+    fn specs(inputs: &[&str]) -> Result<Vec<TargetSpec>, String> {
+        target_specs(&inputs.iter().map(|input| target(input)).collect::<Vec<_>>())
+    }
+
+    #[test]
+    fn legacy_target_syntax_and_ipv6_remain_supported() {
+        let parsed = specs(&[
+            "host.example",
+            "host.example:2112",
+            "[::1]:2112",
+            "eu=host.example",
+        ])
+        .unwrap();
+        assert_eq!(parsed[0].label, "host.example");
+        assert_eq!(parsed[1].label, "host.example:2112");
+        assert_eq!(parsed[2].label, "[::1]:2112");
+        assert_eq!(parsed[3].label, "eu");
+        assert!(parsed
+            .iter()
+            .all(|target| matches!(target.auth, TargetAuth::Inherit)));
+    }
+
+    #[test]
+    fn target_hmac_supports_inherit_override_disable_and_base64_padding() {
+        let parsed = specs(&[
+            "default=default.example",
+            "private=private.example@hmac=YWJjZA==",
+            "public=public.example@hmac=",
+        ])
+        .unwrap();
+        assert!(matches!(parsed[0].auth, TargetAuth::Inherit));
+        assert_eq!(parsed[1].auth, TargetAuth::Override(b"YWJjZA==".to_vec()));
+        assert!(matches!(parsed[2].auth, TargetAuth::Disable));
+    }
+
+    #[test]
+    fn target_delimiters_are_escaped_contextually() {
+        let parsed = specs(&["eu\\=west=host\\@hmac=literal@hmac=a\\@b\\,c\\=d\\\\e"]).unwrap();
+        assert_eq!(parsed[0].label, "eu=west");
+        assert_eq!(parsed[0].addr, "host@hmac=literal");
+        assert_eq!(parsed[0].auth, TargetAuth::Override(b"a@b,c=d\\e".to_vec()));
+    }
+
+    #[test]
+    fn positional_commas_are_not_reserved() {
+        let parsed = specs(&["edge=host,region@hmac=key,part"]).unwrap();
+        assert_eq!(parsed[0].addr, "host,region");
+        assert_eq!(parsed[0].auth, TargetAuth::Override(b"key,part".to_vec()));
+    }
+
+    #[test]
+    fn parser_diagnostics_and_debug_do_not_reveal_hmac_values() {
+        let secret = "very-secret-value";
+        let error = specs(&[&format!("target=host@hmac={secret}\\q")]).unwrap_err();
+        assert!(!error.contains(secret));
+        assert!(!format!("{:?}", target(&format!("target=host@hmac={secret}"))).contains(secret));
+        assert!(
+            !format!("{:?}", TargetAuth::Override(secret.as_bytes().to_vec())).contains(secret)
+        );
+    }
+
+    #[test]
+    fn target_specs_suffix_repeated_unlabeled_and_reject_duplicate_labels() {
+        let parsed = specs(&["host-a:2112", "host-a:2112"]).unwrap();
+        assert_eq!(parsed[0].label, "host-a:2112");
+        assert_eq!(parsed[1].label, "host-a:2112#2");
+        assert_eq!(
+            specs(&["host-a:2112", "host-a:2112=host-b:2112"]).unwrap_err(),
+            "duplicate target label"
+        );
+    }
+
+    #[test]
+    fn target_specs_preserve_argument_order_and_unlabeled_counts() {
+        let parsed = specs(&["local", "eu=eu.example", "foo", "us=us.example", "foo"]).unwrap();
+        let labels: Vec<_> = parsed.iter().map(|target| target.label.as_str()).collect();
+        assert_eq!(labels, ["local", "eu", "foo", "us", "foo#2"]);
+        let addresses: Vec<_> = parsed.iter().map(|target| target.addr.as_str()).collect();
+        assert_eq!(
+            addresses,
+            ["local", "eu.example", "foo", "us.example", "foo"]
+        );
+    }
+
+    #[test]
+    fn target_specs_reject_generated_suffix_collisions() {
+        assert_eq!(
+            specs(&[
+                "host.example",
+                "host.example",
+                "host.example#2=other.example"
+            ])
+            .unwrap_err(),
+            "duplicate target label"
+        );
+    }
+
+    #[test]
+    fn malformed_target_syntax_is_rejected_without_echoing_input() {
+        for input in ["=host", "label=", "host@hmac=value\\q", "host\\x"] {
+            assert!(specs(&[input]).is_err(), "{input}");
+        }
+    }
+
+    #[test]
+    fn target_preparation_maps_auth_to_managed_config() {
+        let prepared =
+            prepare_managed_targets(specs(&["a=one@hmac=key", "b=two@hmac="]).unwrap()).unwrap();
+        assert_eq!(
+            prepared[0]
+                .managed
+                .auth
+                .as_ref()
+                .unwrap()
+                .hmac_key
+                .as_deref(),
+            Some(b"key".as_slice())
+        );
+        assert_eq!(prepared[1].managed.auth.as_ref().unwrap().hmac_key, None);
+    }
+
+    #[test]
+    fn target_preparation_preserves_duplicate_endpoints() {
+        let prepared =
+            prepare_managed_targets(specs(&["a=example.test", "b=example.test"]).unwrap()).unwrap();
+        assert_eq!(prepared[0].managed.server_addr, "example.test");
+        assert_eq!(prepared[1].managed.server_addr, "example.test");
+    }
+
+    #[test]
+    fn stdin_target_sets_frame_commas_without_trimming_payload() {
+        let parsed = parse_stdin_target_set("a=one@hmac=x\\,y,b=two", 128).unwrap();
+        assert_eq!(
+            parsed[0].managed.auth.as_ref().unwrap().hmac_key.as_deref(),
+            Some(b"x,y".as_slice())
+        );
+        assert_eq!(parsed[1].label, "b");
+        assert_eq!(
+            parse_stdin_target_set(" []", 128).unwrap()[0]
+                .managed
+                .server_addr,
+            " []"
+        );
+        assert_eq!(
+            parse_stdin_target_set("[] ", 128).unwrap()[0]
+                .managed
+                .server_addr,
+            "[] "
+        );
+        assert!(parse_stdin_target_set("", 128).is_err());
+        assert!(parse_stdin_target_set("a=one,b=two", 1).is_err());
+    }
+
+    #[test]
+    fn stdin_empty_set_is_exactly_bracket_pair() {
+        assert!(parse_stdin_target_set("[]", 128).unwrap().is_empty());
+    }
+}

crates/irtt-cli/src/cmd/client/run.rs

@@ -1,487 +0,0 @@
-use std::collections::BTreeMap;
-use std::{
-    collections::HashSet,
-    io::{self, Write},
-    sync::atomic::AtomicBool,
-    thread,
-    time::Duration,
-};
-
-use irtt_client::{
-    managed::{
-        BlockingManagedClient, ManagedEndReason, ManagedEvent, ManagedEventSubscription,
-        ManagedEventTryRecvError, ManagedTargetEndReason, ManagedTargetOutcome, TargetInstance,
-    },
-    ClientEvent,
-};
-
-use super::{
-    args::ClientArgs,
-    output::{EventRenderStats, OutputConfig},
-};
-
-use crate::shared::client::expected_probe_count;
-use crate::shared::client::{
-    is_shutdown_requested,
-    session::{
-        drain_managed_events, peer_close_run_error, request_managed_stop_for_peer_close,
-        request_managed_stop_once, should_print_final_summary, ManagedDrainState,
-    },
-};
-
-use irtt_stats::{StatsCollector, StatsConfig};
-
-const MIB: u64 = 1024 * 1024;
-
-const GIB: u64 = 1024 * MIB;
-
-const FINITE_STATS_MEMORY_WARNING_BYTES: u64 = 128 * MIB;
-
-const FINITE_STATS_MEMORY_STRONG_WARNING_BYTES: u64 = 512 * MIB;
-
-const FINITE_STATS_MEMORY_VERY_STRONG_WARNING_BYTES: u64 = GIB;
-const MANAGED_EVENT_WAIT_SLICE: Duration = Duration::from_millis(20);
-
-pub fn run_stream(
-    args: ClientArgs,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    if args.list_columns {
-        print!("{}", OutputConfig::list_columns());
-        return Ok(());
-    }
-    let setup = args
-        .prepare()
-        .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))?;
-    let multi_target = setup.is_multi_target();
-    let output_config = OutputConfig::new(
-        args.format,
-        args.columns.as_deref(),
-        args.header,
-        args.verbose,
-    )
-    .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))?;
-    let continuous = args.is_continuous();
-    let target_count = setup.target_count();
-
-    if let Some(warning) = finite_stats_memory_warning(&args, target_count) {
-        eprintln!("{warning}");
-    }
-    if is_shutdown_requested(shutdown_requested) {
-        return Ok(());
-    }
-    let (owner, mut events) = BlockingManagedClient::start_with_subscription(
-        setup.managed_config(),
-        setup.managed_targets(),
-    )?;
-    let handle = owner.handle();
-    let mut stdout = io::LineWriter::new(io::stdout().lock());
-    let mut stream_output = StreamOutput {
-        config: output_config,
-        header_printed: false,
-        print_final_summary: false,
-        show_running_only_summary_note: false,
-        out: &mut stdout,
-    };
-
-    let mut stats = setup
-        .targets
-        .iter()
-        .map(|target| {
-            (
-                target.label.clone(),
-                StatsCollector::new(stats_config(continuous)),
-            )
-        })
-        .collect::<BTreeMap<_, _>>();
-    let mut terminal_targets = HashSet::new();
-    let mut dropped_events = 0_u64;
-    let mut interrupted = false;
-    let mut stop_requested = false;
-    let mut subscription_closed = false;
-    loop {
-        if is_shutdown_requested(shutdown_requested) {
-            interrupted = true;
-            if request_managed_stop_once(&mut stop_requested) {
-                drop(handle.stop());
-            }
-        }
-        if request_managed_stop_for_peer_close(
-            continuous,
-            interrupted,
-            handle.status().peer_closed_target_outcomes,
-            &mut stop_requested,
-        ) {
-            drop(handle.stop());
-        }
-        let drain_state = drain_events(
-            &mut events,
-            &mut stream_output,
-            &mut stats,
-            &mut terminal_targets,
-            &mut dropped_events,
-        )?;
-        match drain_state {
-            ManagedDrainState::Empty => thread::sleep(MANAGED_EVENT_WAIT_SLICE),
-            ManagedDrainState::Closed => subscription_closed = true,
-            ManagedDrainState::BudgetExhausted => {}
-        }
-        if handle.status().final_outcome.is_some() || subscription_closed {
-            break;
-        }
-    }
-    if interrupted {
-        eprintln!("interrupted, closing managed run...");
-    }
-    let outcome = owner.join()?;
-    drain_final_events(
-        &mut events,
-        &mut stream_output,
-        &mut stats,
-        &mut terminal_targets,
-        &mut dropped_events,
-    )?;
-    if let Some(warning) = dropped_event_warning(dropped_events) {
-        eprintln!("{warning}");
-    }
-    if outcome.discarded_target_outcomes != 0 {
-        eprintln!(
-            "irtt-rs: warning: {} final target outcomes were discarded",
-            outcome.discarded_target_outcomes
-        );
-    }
-    for target in outcome.recent_target_outcomes.iter() {
-        if terminal_targets.insert(target.target.clone()) {
-            report_target_failure(target);
-        }
-    }
-    interrupted |= is_shutdown_requested(shutdown_requested);
-    let terminal_error = match &outcome.end_reason {
-        ManagedEndReason::DriverFailed(failure) => {
-            Some(format!("managed driver failed: {failure}"))
-        }
-        _ => peer_close_run_error(continuous, interrupted, outcome.peer_closed_target_outcomes)
-            .or_else(|| {
-                (!interrupted
-                    && outcome.successful_target_outcomes == 0
-                    && outcome.failed_target_outcomes > 0)
-                    .then(|| {
-                        format!(
-                            "no managed target completed successfully ({} failed)",
-                            outcome.failed_target_outcomes
-                        )
-                    })
-            }),
-    };
-    stream_output.print_final_summary = should_print_final_summary(continuous, interrupted);
-    stream_output.show_running_only_summary_note =
-        continuous && interrupted && stream_output.print_final_summary;
-    for (label, stats) in &stats {
-        if multi_target
-            && stream_output.print_final_summary
-            && stream_output.config.prints_summary()
-        {
-            writeln!(stream_output.out)?;
-            writeln!(stream_output.out, "target: {label}")?;
-        }
-        stream_output.print_summary(stats)?;
-    }
-    stream_output.out.flush()?;
-    if let Some(error) = terminal_error {
-        return Err(error.into());
-    }
-    Ok(())
-}
-
-fn process_event<W: Write>(
-    event: ManagedEvent,
-    stream_output: &mut StreamOutput<'_, W>,
-    stats: &mut BTreeMap<String, StatsCollector>,
-    terminal_targets: &mut HashSet<TargetInstance>,
-) -> io::Result<()> {
-    match event {
-        ManagedEvent::Client { target, event } => {
-            let collector = stats
-                .entry(target.id.as_str().to_owned())
-                .or_insert_with(|| StatsCollector::new(stats_config(false)));
-            print_events_with_stats(
-                stream_output,
-                std::slice::from_ref(&event),
-                Some(target.id.as_str()),
-                collector,
-            )?;
-        }
-        ManagedEvent::TargetFinished { outcome } => {
-            terminal_targets.insert(outcome.target.clone());
-            report_target_failure(&outcome);
-        }
-        _ => {}
-    }
-    Ok(())
-}
-
-fn drain_events<W: Write>(
-    events: &mut ManagedEventSubscription,
-    stream_output: &mut StreamOutput<'_, W>,
-    stats: &mut BTreeMap<String, StatsCollector>,
-    terminal_targets: &mut HashSet<TargetInstance>,
-    dropped_events: &mut u64,
-) -> io::Result<ManagedDrainState> {
-    drain_managed_events(events, dropped_events, |event| {
-        process_event(event, stream_output, stats, terminal_targets)
-    })
-}
-
-fn drain_final_events<W: Write>(
-    events: &mut ManagedEventSubscription,
-    stream_output: &mut StreamOutput<'_, W>,
-    stats: &mut BTreeMap<String, StatsCollector>,
-    terminal_targets: &mut HashSet<TargetInstance>,
-    dropped_events: &mut u64,
-) -> io::Result<()> {
-    loop {
-        match events.try_recv() {
-            Ok(event) => process_event(event, stream_output, stats, terminal_targets)?,
-            Err(ManagedEventTryRecvError::Empty | ManagedEventTryRecvError::Closed) => break,
-            Err(ManagedEventTryRecvError::Lagged(count)) => {
-                *dropped_events = dropped_events.saturating_add(count);
-            }
-        }
-    }
-    Ok(())
-}
-
-fn report_target_failure(target: &ManagedTargetOutcome) {
-    for message in target_failure_messages(target) {
-        eprintln!("{message}");
-    }
-}
-
-fn target_failure_messages(target: &ManagedTargetOutcome) -> Vec<String> {
-    let mut messages = Vec::with_capacity(2);
-    if let ManagedTargetEndReason::Failed(failure) = &target.end_reason {
-        messages.push(format!(
-            "irtt-rs: target {} failed ({} {}): {}",
-            target.target.id, failure.phase, failure.kind, failure.message
-        ));
-    }
-    if let Some(failure) = &target.cleanup_failure {
-        messages.push(format!(
-            "irtt-rs: target {} cleanup failed ({} {}): {}",
-            target.target.id, failure.phase, failure.kind, failure.message
-        ));
-    }
-    messages
-}
-fn dropped_event_warning(dropped_events: u64) -> Option<String> {
-    (dropped_events > 0).then(|| format!("irtt-rs: warning: dropped {dropped_events} managed run event{}; output and statistics may be incomplete", if dropped_events == 1 { "" } else { "s" }))
-}
-
-struct StreamOutput<'a, W: Write> {
-    config: OutputConfig,
-    header_printed: bool,
-    print_final_summary: bool,
-    show_running_only_summary_note: bool,
-    out: &'a mut W,
-}
-impl<W: Write> StreamOutput<'_, W> {
-    fn print_events(
-        &mut self,
-        events: &[ClientEvent],
-        target: Option<&str>,
-        stats_updates: &[EventRenderStats],
-    ) -> io::Result<()> {
-        self.print_header()?;
-        for (event, stats_update) in events.iter().zip(stats_updates) {
-            if let Some(line) = self.config.render_event(event, target, Some(stats_update)) {
-                writeln!(self.out, "{line}")?;
-            }
-        }
-        Ok(())
-    }
-    fn print_header(&mut self) -> io::Result<()> {
-        if self.header_printed {
-            return Ok(());
-        }
-        self.header_printed = true;
-        if let Some(header) = self.config.render_header() {
-            writeln!(self.out, "{header}")?;
-        }
-        Ok(())
-    }
-
-    fn print_summary(&mut self, stats: &StatsCollector) -> io::Result<()> {
-        if self.print_final_summary && self.config.prints_summary() {
-            write!(
-                self.out,
-                "{}",
-                crate::cmd::client::summary::format_summary_with_options(
-                    &stats.snapshot(),
-                    crate::cmd::client::summary::SummaryFormatOptions {
-                        verbose: self.config.summary_verbose(),
-                        show_running_only_note: self.show_running_only_summary_note
-                    }
-                )
-            )?;
-        }
-        Ok(())
-    }
-}
-
-fn print_events_with_stats<W: Write>(
-    stream_output: &mut StreamOutput<'_, W>,
-    events: &[ClientEvent],
-    target: Option<&str>,
-    stats: &mut StatsCollector,
-) -> io::Result<()> {
-    let updates = events
-        .iter()
-        .map(|event| EventRenderStats::from(stats.process(event)))
-        .collect::<Vec<_>>();
-    stream_output.print_events(events, target, &updates)
-}
-
-fn stats_config(continuous: bool) -> StatsConfig {
-    if continuous {
-        StatsConfig::continuous()
-    } else {
-        StatsConfig::finite()
-    }
-}
-fn finite_stats_memory_warning(args: &ClientArgs, target_count: usize) -> Option<String> {
-    if args.is_continuous() || args.duration.is_zero() {
-        return None;
-    }
-    let target_count = u64::try_from(target_count).unwrap_or(u64::MAX);
-    let total_probe_count =
-        expected_probe_count(args.duration, args.interval).saturating_mul(target_count);
-    // Ask the stats crate what the configuration this run will actually use
-    // retains; the CLI owns the probe count and the thresholds, not the
-    // retention model.
-    let estimated_bytes = stats_config(false).estimated_retained_bytes(total_probe_count);
-    if estimated_bytes < FINITE_STATS_MEMORY_WARNING_BYTES {
-        return None;
-    }
-    let formatted = if estimated_bytes >= GIB {
-        format!("{} GiB", estimated_bytes.saturating_add(GIB / 2) / GIB)
-    } else {
-        format!("{} MiB", estimated_bytes.saturating_add(MIB / 2) / MIB)
-    };
-    let guidance = if estimated_bytes >= FINITE_STATS_MEMORY_VERY_STRONG_WARNING_BYTES {
-        "this may be unsuitable on memory-constrained systems"
-    } else if estimated_bytes >= FINITE_STATS_MEMORY_STRONG_WARNING_BYTES {
-        "consider shortening the run, increasing the interval, or using continuous mode"
-    } else {
-        "use continuous mode for bounded-memory long-running tests"
-    };
-    Some(format!("irtt-rs: warning: finite exact statistics may retain about {formatted} for this run; {guidance}"))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use irtt_client::managed::{
-        ManagedTargetFailure, ManagedTargetFailureKind, ManagedTargetFailurePhase, TargetId,
-    };
-    use std::sync::Arc;
-
-    fn long_finite_args() -> ClientArgs {
-        use clap::Parser;
-
-        ClientArgs::try_parse_from([
-            "irtt-cli",
-            "--duration",
-            "4200s",
-            "--interval",
-            "100ms",
-            "127.0.0.1:2112",
-        ])
-        .unwrap()
-    }
-
-    /// Smallest target count whose aggregate estimate reaches the warning
-    /// threshold, derived from the stats crate's own estimate rather than from
-    /// any bytes-per-probe assumption held here.
-    fn first_warning_target_count(args: &ClientArgs) -> usize {
-        let probes = expected_probe_count(args.duration, args.interval);
-        (1..=1024)
-            .find(|targets| {
-                let total = probes.saturating_mul(*targets as u64);
-                stats_config(false).estimated_retained_bytes(total)
-                    >= FINITE_STATS_MEMORY_WARNING_BYTES
-            })
-            .expect("a long finite run should cross the warning threshold within 1024 targets")
-    }
-
-    #[test]
-    fn finite_stats_memory_warning_accounts_for_target_count() {
-        let args = long_finite_args();
-        let crossing = first_warning_target_count(&args);
-
-        assert!(
-            crossing > 1,
-            "this run should need more than one target to cross the threshold, \
-             otherwise the test proves nothing about target-count accounting"
-        );
-        assert!(
-            finite_stats_memory_warning(&args, crossing - 1).is_none(),
-            "an aggregate estimate below the threshold should not warn"
-        );
-        assert!(
-            finite_stats_memory_warning(&args, crossing).is_some(),
-            "an aggregate estimate at the threshold should warn"
-        );
-    }
-
-    #[test]
-    fn finite_stats_memory_warning_saturates_target_count_multiplication() {
-        assert!(finite_stats_memory_warning(&long_finite_args(), usize::MAX).is_some());
-    }
-
-    #[test]
-    fn lagged_events_are_counted_saturatingly() {
-        let mut dropped = 0_u64;
-        dropped = dropped.saturating_add(7);
-        dropped = dropped.saturating_add(3);
-        assert_eq!(dropped, 10);
-        assert_eq!(u64::MAX.saturating_add(1), u64::MAX);
-        assert!(dropped_event_warning(dropped)
-            .unwrap()
-            .contains("dropped 10 managed run events"));
-    }
-
-    #[test]
-    fn target_failure_diagnostics_include_primary_and_cleanup_failures() {
-        let target = ManagedTargetOutcome {
-            target: TargetInstance {
-                id: TargetId::from("edge"),
-                generation: 1,
-            },
-            server_addr: Arc::from("127.0.0.1:2112"),
-            remote: None,
-            end_reason: ManagedTargetEndReason::Failed(ManagedTargetFailure {
-                phase: ManagedTargetFailurePhase::Receiving,
-                kind: ManagedTargetFailureKind::Protocol,
-                message: "primary failure".into(),
-            }),
-            packets_sent: 0,
-            replies_received: 0,
-            duplicates: 0,
-            late: 0,
-            warning_events: 0,
-            cleanup_failure: Some(ManagedTargetFailure {
-                phase: ManagedTargetFailurePhase::Closing,
-                kind: ManagedTargetFailureKind::Socket,
-                message: "cleanup failure".into(),
-            }),
-        };
-
-        assert_eq!(
-            target_failure_messages(&target),
-            [
-                "irtt-rs: target edge failed (receiving protocol): primary failure",
-                "irtt-rs: target edge cleanup failed (closing socket): cleanup failure",
-            ]
-        );
-    }
-}

crates/irtt-cli/src/cmd/server/run.rs

@@ -1,85 +0,0 @@
-use std::{
-    sync::atomic::{AtomicBool, Ordering},
-    time::Duration,
-};
-
-use irtt_server::ServerSet;
-
-use super::args::ServerArgs;
-
-/// How often the shutdown future samples the process-wide signal flag.
-///
-/// The flag a signal handler sets has no async wake mechanism, so the future
-/// polls it on a timer rather than spinning. `ServerSet::run` owns everything
-/// after that future becomes ready, including fanning it out to the listeners.
-const SHUTDOWN_POLL_INTERVAL: Duration = Duration::from_millis(50);
-
-/// Runs the configured listeners until the process is asked to shut down.
-///
-/// The applet owns exactly one current-thread Tokio runtime and one
-/// [`ServerSet`], whatever number of addresses was requested. A single `--bind`
-/// is an ordinary set of one and takes the same path as a set of several: one
-/// construction, one shutdown future, one supervision rule. Listener
-/// concurrency is async I/O concurrency and needs no worker threads.
-pub fn run_server(
-    args: ServerArgs,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let runtime = tokio::runtime::Builder::new_current_thread()
-        .enable_all()
-        .build()?;
-    runtime.block_on(serve(args, shutdown_requested))
-}
-
-async fn serve(
-    args: ServerArgs,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let config = args.server_config();
-    let set = ServerSet::bind(args.bind, config).await?;
-    // Only once every listener is up. Announcing one address and then failing
-    // to bind the next would report a service that never started.
-    for addr in set.local_addrs() {
-        eprintln!("irtt-server: listening on {addr}");
-    }
-    set.run(shutdown_signal(shutdown_requested)).await?;
-    Ok(())
-}
-
-async fn shutdown_signal(shutdown_requested: &AtomicBool) {
-    while !shutdown_requested.load(Ordering::Relaxed) {
-        tokio::time::sleep(SHUTDOWN_POLL_INTERVAL).await;
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use clap::Parser;
-
-    use super::*;
-
-    /// The ordinary invocation, and the one that keeps the single-listener case
-    /// on the same orchestration path as every other.
-    #[test]
-    fn an_already_requested_shutdown_binds_one_listener_and_returns() {
-        let args = ServerArgs::try_parse_from(["irtt-server", "--bind", "127.0.0.1:0"]).unwrap();
-        let shutdown_requested = AtomicBool::new(true);
-
-        run_server(args, &shutdown_requested).unwrap();
-    }
-
-    #[test]
-    fn an_already_requested_shutdown_binds_every_listener_and_returns() {
-        let args = ServerArgs::try_parse_from([
-            "irtt-server",
-            "--bind",
-            "127.0.0.1:0",
-            "--bind",
-            "127.0.0.1:0",
-        ])
-        .unwrap();
-        let shutdown_requested = AtomicBool::new(true);
-
-        run_server(args, &shutdown_requested).unwrap();
-    }
-}

crates/irtt-cli/src/entry.rs

@@ -1,99 +0,0 @@
-use std::{
-    env,
-    ffi::OsString,
-    process::ExitCode,
-    sync::{atomic::AtomicBool, Arc},
-};
-
-use crate::{
-    applet::{dispatch_from_argv, AppletDispatch, RequestedApplet},
-    signal::install_signal_handler,
-};
-
-pub fn main() -> ExitCode {
-    match run_from_env() {
-        Ok(()) => ExitCode::SUCCESS,
-        Err(err) => {
-            eprintln!("irtt-rs: {err}");
-            ExitCode::FAILURE
-        }
-    }
-}
-
-fn run_from_env() -> Result<(), Box<dyn std::error::Error>> {
-    let argv: Vec<OsString> = env::args_os().collect();
-    let (requested, argv) = match dispatch_from_argv(argv)? {
-        AppletDispatch::Run { applet, argv } => (applet, argv),
-        AppletDispatch::Help(help) => {
-            print!("{help}");
-            return Ok(());
-        }
-    };
-
-    let shutdown_requested = Arc::new(AtomicBool::new(false));
-    install_signal_handler(Arc::clone(&shutdown_requested))
-        .map_err(|err| format!("failed to install signal handler: {err}"))?;
-
-    match requested {
-        RequestedApplet::Client => run_client_applet(argv, shutdown_requested.as_ref()),
-        RequestedApplet::Tui => run_tui_applet(argv, shutdown_requested.as_ref()),
-        RequestedApplet::Server => run_server_applet(argv, shutdown_requested.as_ref()),
-    }
-}
-
-#[cfg(feature = "client")]
-fn run_client_applet(
-    argv: Vec<OsString>,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    use clap::Parser;
-
-    let args = crate::cmd::client::ClientArgs::parse_from(argv);
-    crate::cmd::client::run_stream(args, shutdown_requested)
-}
-
-#[cfg(not(feature = "client"))]
-fn run_client_applet(
-    _argv: Vec<OsString>,
-    _shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    Err("client applet is not available; rebuild with the client feature".into())
-}
-
-#[cfg(feature = "server")]
-fn run_server_applet(
-    argv: Vec<OsString>,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    use clap::Parser;
-
-    let args = crate::cmd::server::ServerArgs::parse_from(argv);
-    crate::cmd::server::run_server(args, shutdown_requested)
-}
-
-#[cfg(not(feature = "server"))]
-fn run_server_applet(
-    _argv: Vec<OsString>,
-    _shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    Err("server applet is not available; rebuild with the server feature".into())
-}
-
-#[cfg(feature = "tui")]
-fn run_tui_applet(
-    argv: Vec<OsString>,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    use clap::Parser;
-
-    let args = crate::cmd::tui::TuiArgs::parse_from(argv);
-    crate::cmd::tui::run_tui(args, shutdown_requested)
-}
-
-#[cfg(not(feature = "tui"))]
-fn run_tui_applet(
-    _argv: Vec<OsString>,
-    _shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    Err("TUI applet is not available; rebuild with the tui feature".into())
-}

crates/irtt-cli/src/shared/client/targets.rs

@@ -1,226 +0,0 @@
-use std::collections::HashSet;
-
-use clap::ValueEnum;
-use irtt_client::managed::{ManagedPacing, ManagedTargetConfig, TargetId};
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct TargetArg {
-    pub label: Option<String>,
-    pub addr: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct TargetSpec {
-    pub label: String,
-    pub addr: String,
-}
-
-#[derive(Debug, Clone)]
-pub struct PreparedTarget {
-    pub label: String,
-    pub managed: ManagedTargetConfig,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
-pub enum GroupPacingArg {
-    Staggered,
-    Burst,
-}
-
-impl From<GroupPacingArg> for ManagedPacing {
-    fn from(value: GroupPacingArg) -> Self {
-        match value {
-            GroupPacingArg::Staggered => Self::Staggered,
-            GroupPacingArg::Burst => Self::Burst,
-        }
-    }
-}
-
-/// Parse one positional target argument, as `TARGET` or `LABEL=TARGET`.
-pub fn parse_target(input: &str) -> Result<TargetArg, String> {
-    match input.split_once('=') {
-        None => Ok(TargetArg {
-            label: None,
-            addr: input.to_owned(),
-        }),
-        Some((label, addr)) => {
-            if label.is_empty() {
-                return Err("target label must not be empty".to_owned());
-            }
-            if addr.is_empty() {
-                return Err("target address must not be empty".to_owned());
-            }
-            Ok(TargetArg {
-                label: Some(label.to_owned()),
-                addr: addr.to_owned(),
-            })
-        }
-    }
-}
-
-pub fn target_specs(targets: &[TargetArg]) -> Result<Vec<TargetSpec>, String> {
-    let mut specs = Vec::with_capacity(targets.len());
-    let mut unlabeled_counts = std::collections::HashMap::<&str, usize>::new();
-    for target in targets {
-        let label = match &target.label {
-            Some(label) => label.clone(),
-            None => {
-                let count = unlabeled_counts.entry(target.addr.as_str()).or_default();
-                *count += 1;
-                if *count == 1 {
-                    target.addr.clone()
-                } else {
-                    format!("{}#{}", target.addr, *count)
-                }
-            }
-        };
-        specs.push(TargetSpec {
-            label,
-            addr: target.addr.clone(),
-        });
-    }
-
-    if specs.is_empty() {
-        return Err("at least one target is required unless --list-columns is set".to_owned());
-    }
-
-    let mut labels = HashSet::new();
-    for spec in &specs {
-        if !labels.insert(spec.label.clone()) {
-            return Err(format!("duplicate target label {:?}", spec.label));
-        }
-    }
-
-    Ok(specs)
-}
-
-pub fn prepare_managed_targets(specs: Vec<TargetSpec>) -> Result<Vec<PreparedTarget>, String> {
-    let mut targets = Vec::with_capacity(specs.len());
-    for spec in specs {
-        targets.push(PreparedTarget {
-            label: spec.label.clone(),
-            managed: ManagedTargetConfig::new(TargetId::from(spec.label), spec.addr),
-        });
-    }
-    Ok(targets)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn unlabeled(addr: &str) -> TargetArg {
-        TargetArg {
-            label: None,
-            addr: addr.to_owned(),
-        }
-    }
-
-    fn labeled(label: &str, addr: &str) -> TargetArg {
-        TargetArg {
-            label: Some(label.to_owned()),
-            addr: addr.to_owned(),
-        }
-    }
-
-    #[test]
-    fn parse_target_without_equals_is_unlabeled() {
-        let target = parse_target("host.example").unwrap();
-        assert_eq!(target.label, None);
-        assert_eq!(target.addr, "host.example");
-
-        let target = parse_target("host.example:2112").unwrap();
-        assert_eq!(target.label, None);
-        assert_eq!(target.addr, "host.example:2112");
-
-        let target = parse_target("[::1]:2112").unwrap();
-        assert_eq!(target.label, None);
-        assert_eq!(target.addr, "[::1]:2112");
-    }
-
-    #[test]
-    fn parse_target_with_equals_splits_on_first() {
-        let target = parse_target("eu=host.example").unwrap();
-        assert_eq!(target.label, Some("eu".to_owned()));
-        assert_eq!(target.addr, "host.example");
-
-        let target = parse_target("eu=host.example:2112").unwrap();
-        assert_eq!(target.label, Some("eu".to_owned()));
-        assert_eq!(target.addr, "host.example:2112");
-    }
-
-    #[test]
-    fn parse_target_rejects_empty_label_or_address() {
-        assert!(parse_target("=host.example").is_err());
-        assert!(parse_target("eu=").is_err());
-    }
-
-    #[test]
-    fn target_specs_suffix_repeated_unlabeled_and_reject_duplicate_labels() {
-        let targets = vec![unlabeled("host-a:2112"), unlabeled("host-a:2112")];
-        let specs = target_specs(&targets).unwrap();
-
-        assert_eq!(specs[0].label, "host-a:2112");
-        assert_eq!(specs[1].label, "host-a:2112#2");
-
-        let targets = vec![
-            unlabeled("host-a:2112"),
-            labeled("host-a:2112", "host-b:2112"),
-        ];
-        let err = target_specs(&targets).unwrap_err();
-        assert!(err.contains("duplicate target label"));
-    }
-
-    #[test]
-    fn target_specs_preserve_argument_order_with_mixed_labels() {
-        let targets = vec![
-            unlabeled("local"),
-            labeled("eu", "eu.example"),
-            unlabeled("backup"),
-            labeled("us", "us.example"),
-        ];
-        let specs = target_specs(&targets).unwrap();
-
-        let labels: Vec<_> = specs.iter().map(|spec| spec.label.as_str()).collect();
-        assert_eq!(labels, ["local", "eu", "backup", "us"]);
-        let addrs: Vec<_> = specs.iter().map(|spec| spec.addr.as_str()).collect();
-        assert_eq!(addrs, ["local", "eu.example", "backup", "us.example"]);
-    }
-
-    #[test]
-    fn target_specs_count_unlabeled_occurrences_independently_of_explicit_labels() {
-        let targets = vec![unlabeled("foo"), labeled("eu", "foo"), unlabeled("foo")];
-        let specs = target_specs(&targets).unwrap();
-
-        let labels: Vec<_> = specs.iter().map(|spec| spec.label.as_str()).collect();
-        assert_eq!(labels, ["foo", "eu", "foo#2"]);
-    }
-
-    #[test]
-    fn target_specs_reject_generated_suffix_collisions() {
-        let targets = vec![
-            unlabeled("host.example"),
-            unlabeled("host.example"),
-            labeled("host.example#2", "other.example"),
-        ];
-        let err = target_specs(&targets).unwrap_err();
-        assert!(err.contains("duplicate target label"));
-    }
-
-    #[test]
-    fn target_preparation_preserves_hostname_and_allows_duplicate_endpoints() {
-        let specs = vec![
-            TargetSpec {
-                label: "a".to_owned(),
-                addr: "example.test".to_owned(),
-            },
-            TargetSpec {
-                label: "b".to_owned(),
-                addr: "example.test".to_owned(),
-            },
-        ];
-        let targets = prepare_managed_targets(specs).unwrap();
-        assert_eq!(targets[0].managed.server_addr, "example.test");
-        assert_eq!(targets[1].managed.server_addr, "example.test");
-    }
-}

crates/irtt-cli/tests/applet_dispatch.rs

@@ -1,211 +0,0 @@
-use std::process::{Command, Output};
-
-fn irtt_rs() -> Command {
-    Command::new(env!("CARGO_BIN_EXE_irtt-rs"))
-}
-
-#[cfg(unix)]
-fn irtt_rs_with_arg0(arg0: &str) -> Command {
-    use std::os::unix::process::CommandExt;
-
-    let mut command = irtt_rs();
-    command.arg0(arg0);
-    command
-}
-
-fn output_text(output: &Output) -> String {
-    let mut text = String::new();
-    text.push_str(&String::from_utf8_lossy(&output.stdout));
-    text.push_str(&String::from_utf8_lossy(&output.stderr));
-    text
-}
-
-#[test]
-fn canonical_help_shows_dispatcher_help() {
-    let output = irtt_rs().arg("--help").output().unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("IRTT-compatible multi-applet dispatcher"));
-    assert!(text.contains("client"));
-    assert!(text.contains("tui"));
-    assert!(text.contains("server"));
-}
-
-#[test]
-fn canonical_without_applet_errors() {
-    let output = irtt_rs().output().unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("choose an applet"), "{text}");
-    assert!(text.contains("client"));
-    assert!(text.contains("tui"));
-    assert!(text.contains("server"));
-}
-
-#[cfg(feature = "client")]
-#[test]
-fn canonical_client_subcommand_dispatches_to_client() {
-    let output = irtt_rs().args(["client", "--help"]).output().unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible stream client"));
-    assert!(text.contains("--format <FORMAT>"));
-    assert!(text.contains("--columns <COLUMNS>"));
-}
-
-#[cfg(not(feature = "client"))]
-#[test]
-fn canonical_client_subcommand_reports_unavailable_when_disabled() {
-    let output = irtt_rs().args(["client", "--help"]).output().unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(
-        text.contains("client applet is not available; rebuild with the client feature"),
-        "{text}"
-    );
-}
-
-#[cfg(feature = "server")]
-#[test]
-fn canonical_server_subcommand_dispatches_to_server() {
-    let output = irtt_rs().args(["server", "--help"]).output().unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible UDP server"));
-    assert!(text.contains("--bind <ADDR>"));
-    assert!(text.contains("--max-sessions <COUNT>"));
-    assert!(text.contains("--idle-timeout <DURATION>"));
-    assert!(text.contains("--timestamp-allowance <MODE>"));
-    assert!(text.contains("--no-dscp"));
-}
-
-#[cfg(not(feature = "server"))]
-#[test]
-fn canonical_server_subcommand_reports_unavailable_when_disabled() {
-    let output = irtt_rs().args(["server", "--help"]).output().unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(
-        text.contains("server applet is not available; rebuild with the server feature"),
-        "{text}"
-    );
-}
-
-#[cfg(feature = "server")]
-#[test]
-fn standalone_server_binary_exposes_the_same_arguments() {
-    let output = std::process::Command::new(env!("CARGO_BIN_EXE_irtt-server"))
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible UDP server"));
-    assert!(text.contains("--bind <ADDR>"));
-}
-
-#[cfg(unix)]
-#[cfg(feature = "client")]
-#[test]
-fn client_applet_name_dispatches_to_client() {
-    let output = irtt_rs_with_arg0("irtt-cli")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible stream client"));
-    assert!(text.contains("--format <FORMAT>"));
-    assert!(text.contains("--columns <COLUMNS>"));
-}
-
-#[cfg(all(unix, not(feature = "client")))]
-#[test]
-fn client_applet_name_reports_unavailable_when_disabled() {
-    let output = irtt_rs_with_arg0("irtt-cli")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(
-        text.contains("client applet is not available; rebuild with the client feature"),
-        "{text}"
-    );
-}
-
-#[cfg(all(unix, feature = "tui"))]
-#[test]
-fn tui_applet_name_dispatches_to_tui_when_enabled() {
-    let output = irtt_rs_with_arg0("irtt-tui")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible TUI client"));
-    assert!(text.contains("--duration <DURATION>"));
-}
-
-#[cfg(all(unix, not(feature = "tui")))]
-#[test]
-fn tui_applet_name_reports_unavailable_when_disabled() {
-    let output = irtt_rs_with_arg0("irtt-tui")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("TUI applet is not available"), "{text}");
-}
-
-#[cfg(all(unix, feature = "server"))]
-#[test]
-fn server_applet_name_dispatches_to_server_when_enabled() {
-    let output = irtt_rs_with_arg0("irtt-server")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible UDP server"));
-    assert!(text.contains("--bind <ADDR>"));
-}
-
-#[cfg(all(unix, not(feature = "server")))]
-#[test]
-fn server_applet_name_reports_unavailable_when_disabled() {
-    let output = irtt_rs_with_arg0("irtt-server")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("server applet is not available"), "{text}");
-}
-
-#[cfg(unix)]
-#[test]
-fn unknown_irtt_applet_name_errors() {
-    let output = irtt_rs_with_arg0("irtt-typo").output().unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("unknown applet name 'irtt-typo'"), "{text}");
-    assert!(text.contains("irtt-cli"));
-    assert!(text.contains("irtt-tui"));
-    assert!(text.contains("irtt-server"));
-}

crates/irtt-cli/tests/support/in_tree_server.rs

@@ -1,74 +0,0 @@
-use std::{
-    net::{IpAddr, Ipv4Addr, SocketAddr},
-    sync::mpsc,
-    thread::{self, JoinHandle},
-    time::Duration,
-};
-
-use irtt_server::{Server, ServerConfig};
-use tokio::sync::oneshot;
-
-const STARTUP_TIMEOUT: Duration = Duration::from_secs(2);
-
-pub struct InTreeServer {
-    pub addr: SocketAddr,
-    shutdown: Option<oneshot::Sender<()>>,
-    done: Option<JoinHandle<Result<(), irtt_server::ServerRuntimeError>>>,
-}
-
-impl InTreeServer {
-    pub fn start() -> Self {
-        let (startup_tx, startup_rx) = mpsc::sync_channel(1);
-        let (shutdown_tx, shutdown_rx) = oneshot::channel();
-        let done = thread::spawn(move || {
-            let runtime = tokio::runtime::Builder::new_current_thread()
-                .enable_all()
-                .build()
-                .expect("failed to build in-tree test server runtime");
-            runtime.block_on(async move {
-                let bind_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
-                let mut server = Server::bind(bind_addr, ServerConfig::default()).await?;
-                startup_tx
-                    .send(server.local_addr()?)
-                    .expect("test stopped waiting for in-tree server startup");
-                server
-                    .run(async {
-                        let _ = shutdown_rx.await;
-                    })
-                    .await
-            })
-        });
-
-        let addr = match startup_rx.recv_timeout(STARTUP_TIMEOUT) {
-            Ok(addr) => addr,
-            Err(error) => {
-                let _ = shutdown_tx.send(());
-                let result = done.join().expect("in-tree test server thread panicked");
-                panic!("in-tree test server failed before startup ({error}): {result:?}");
-            }
-        };
-
-        Self {
-            addr,
-            shutdown: Some(shutdown_tx),
-            done: Some(done),
-        }
-    }
-
-    fn stop(&mut self) {
-        if let Some(shutdown) = self.shutdown.take() {
-            let _ = shutdown.send(());
-        }
-        if let Some(done) = self.done.take() {
-            done.join()
-                .expect("in-tree test server thread panicked")
-                .expect("in-tree test server stopped with an error");
-        }
-    }
-}
-
-impl Drop for InTreeServer {
-    fn drop(&mut self) {
-        self.stop();
-    }
-}

crates/irtt-client/AGENTS.md

@@ -26,30 +26,30 @@ configuration (`try_enable_tx_timestamping` restores it explicitly) and
 timing falls back to userspace `sent_at` as it always has. TX capability
 failure is never a public error and is never logged from the library.
 
-### Correlation invariant: kernel ID == wire sequence
+### Best-effort kernel-ID correlation
 
-The client uses the kernel's automatic `OPT_ID` directly as the probe's wire
+The client uses the kernel's automatic `OPT_ID` as the probe's wire-sequence
-sequence number — no separate correlation map. This is safe because:
+correlation ID — no separate correlation map. On the normal successful-send
+path, both counters start at zero after Open and advance together. This is
+not a permanent identity: a kernel ID can theoretically be consumed while a
+send is being prepared and then survive a subsequent send failure, leaving
+kernel IDs one or more steps ahead of `next_wire_seq`. Do not restore an
+assumption that failed or nonblocking sends cannot cause that desynchrony.
 
-- **A failed/nonblocking send never consumes an ID.** Linux increments the
+The effect is confined to the optional timing enhancement. A kernel timestamp
-  per-socket ID counter (`sk->sk_tskey`) speculatively while building a
+whose ID cannot be matched to a pending or retained timed-out probe is
-  datagram and rolls the increment back (`atomic_dec`) on every error path
+discarded, as is any implausible timestamp; `sent_at` remains the ordinary
-  out of `__ip_append_data`/`__ip6_append_data`
+userspace fallback. **After every failed probe submission, disable kernel-ID
-  (`net/ipv4/ip_output.c`, `net/ipv6/ip6_output.c`), guarded by a local
+correlation for the rest of that session.** A gap means an otherwise plausible
-  `hold_tskey` flag. A `WouldBlock` `try_send` therefore can never leave a
+later ID can name the wrong probe, so subsequent error-queue timestamps must
-  gap in, or otherwise advance, the ID the kernel will assign to the next
+be discarded rather than attached by ID. This is safe because:
-  *successful* submission. (`include/net/sock.h`'s `_sock_tx_timestamp`
+
-  performs the same increment for the non-corked path.) Client-side, the
+- **Normal successful sends track together.** `wire_seq` starts at 0 on every
-  existing send transaction only calls `commit_probe_sent` — which is the
+  successful Open (`SessionMachine::commit_open` builds a fresh
-  only thing that advances `next_wire_seq` — after a successful socket send;
+  `ActiveSession` with `next_wire_seq: 0`) and advances by exactly 1 only via
-  a `WouldBlock` result never reaches it.
+  `commit_probe_sent`, after a confirmed successful socket send. TX
-- **The two counters start together and advance together.** `wire_seq`
+  timestamping is enabled after that same successful Open and before any probe
-  starts at 0 on every successful Open (`SessionMachine::commit_open` builds
+  is sent, so the normal zero points line up.
-  a fresh `ActiveSession` with `next_wire_seq: 0`) and advances by exactly 1
-  only via `commit_probe_sent`, which only runs after a confirmed successful
-  send — the same condition under which the kernel's counter advances by 1.
-  TX timestamping is enabled only after that same successful Open and before
-  any probe is sent, so both counters' zero points line up exactly.
 - **One socket, one session, no reopen.** `SessionMachine`'s state machine
   only reaches `Open` from `Connected`, and `commit_open`/`commit_local_close`
   never route back to `Connected`. A `Client`/`AsyncClient` cannot reopen a

crates/irtt-client/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "irtt-client"
-version = "0.5.0"
+version = "0.5.2"
 description = "IRTT-compatible Rust client library"
 edition.workspace = true
 license.workspace = true
 rust-version.workspace = true
 repository.workspace = true
 homepage.workspace = true
-readme.workspace = true
+readme = "README.md"
 keywords = ["irtt", "networking", "latency", "rtt"]
 categories = ["network-programming"]
 
@@ -27,7 +27,25 @@ tokio = ["dep:tokio"]
 
 [package.metadata.docs.rs]
 all-features = true
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+
+[[example]]
+name = "blocking_client"
+doc-scrape-examples = true
+
+[[example]]
+name = "tokio_client"
+required-features = ["tokio"]
+doc-scrape-examples = true
+
+[[example]]
+name = "managed_client"
+required-features = ["tokio"]
+doc-scrape-examples = true
 
 [dev-dependencies]
-irtt-server.workspace = true
+# Keep the packaged client testable against the latest published server while
+# workspace tests continue to exercise the local source through this path.
+irtt-server = { version = "0.5.1", path = "../irtt-server" }
+proptest = "1.11.0"
 tokio = { version = "1.53.1", default-features = false, features = ["rt", "sync"] }

crates/irtt-client/README.md

@@ -0,0 +1,37 @@
+# irtt-client
+
+Reusable client/session library for IRTT-compatible round-trip-time probing:
+socket lifecycle, open negotiation, probe send/receive, loss/duplicate/late
+classification, and a typed event stream.
+
+## Looking for the CLI?
+
+If you just want to run probes from the command line, use the
+[`irtt-rs`](https://crates.io/crates/irtt-rs) application package instead,
+which installs the `irtt-client` binary. This crate is the library the
+binaries are built on.
+
+## API tiers
+
+- `Client` — runtime-free blocking adapter. No Tokio dependency; this is the
+  default build.
+- `AsyncClient` (feature `tokio`) — low-level Tokio adapter for callers that
+  own a runtime and drive readiness directly.
+- `managed` (feature `tokio`) — a unified managed driver: `ManagedClientTask`
+  / `ManagedClientHandle` for multi-target orchestration under a Tokio
+  runtime, and `BlockingManagedClient` for synchronous callers, which owns its
+  own dedicated current-thread runtime.
+
+Tokio stays optional: the default build has no runtime and no Tokio
+dependency at all.
+
+See `examples/` in the repository for runnable examples of each tier.
+
+## Documentation
+
+Full API documentation is on [docs.rs/irtt-client](https://docs.rs/irtt-client).
+
+## Project
+
+Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
+implementation of an IRTT-compatible protocol stack.

crates/irtt-client/examples/blocking_client.rs

@@ -0,0 +1,110 @@
+//! Runtime-free blocking client example.
+//!
+//! Opens a session against a local IRTT-compatible server, sends a few
+//! probes, and prints the events observed. Uses only [`Client`], which has no
+//! Tokio dependency and works in a default (`--no-default-features`) build.
+//!
+//! Run a server first, then run this example:
+//!
+//! ```text
+//! cargo run -p irtt-rs --bin irtt-server --features server
+//! cargo run -p irtt-client --example blocking_client
+//! ```
+//!
+//! Without a reachable server this exits quickly with an open-timeout error
+//! instead of hanging, because the example shortens `open_timeouts` for a
+//! fast demonstration; a real caller would normally keep the default retry
+//! schedule.
+
+use std::time::{Duration, Instant};
+
+use irtt_client::{Client, ClientConfig, ClientEvent};
+
+const RUN_DURATION: Duration = Duration::from_secs(2);
+
+fn main() {
+    let config = ClientConfig {
+        server_addr: "127.0.0.1:2112".to_owned(),
+        duration: Some(RUN_DURATION),
+        interval: Duration::from_millis(200),
+        // A single short attempt keeps this example fast when no server is
+        // reachable; production callers should generally keep the default.
+        open_timeouts: vec![Duration::from_millis(300)],
+        socket_config: irtt_client::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(100)),
+            ..Default::default()
+        },
+        ..Default::default()
+    };
+
+    let mut client = match Client::connect(config) {
+        Ok(client) => client,
+        Err(err) => {
+            eprintln!("failed to prepare client socket: {err}");
+            return;
+        }
+    };
+
+    match client.open() {
+        Ok(outcome) => println!("session opened: {outcome:?}"),
+        Err(err) => {
+            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
+            return;
+        }
+    }
+
+    // The run itself lasts `duration`, but a lost probe isn't classified as
+    // `EchoLoss` until `probe_timeout()` after it was sent; wait at least
+    // that much past the run's own end so a loss near the end can still be
+    // observed and printed before this example gives up and closes.
+    let deadline = Instant::now() + RUN_DURATION + client.probe_timeout();
+    while Instant::now() < deadline && !client.is_run_complete() {
+        // send_probe is caller-paced: only call it once its own schedule
+        // says a probe is due, rather than as fast as the loop spins.
+        if client
+            .next_send_deadline()
+            .is_some_and(|send_at| Instant::now() >= send_at)
+        {
+            // A failed send retains its prepared probe without advancing the
+            // schedule, so a persistent error (e.g. the interface going
+            // down) would otherwise make this loop retry silently until the
+            // safety deadline instead of reporting it.
+            match client.send_probe() {
+                Ok(events) => events.iter().for_each(print_event),
+                Err(err) => {
+                    eprintln!("send failed: {err}");
+                    break;
+                }
+            }
+        }
+        match client.recv_once() {
+            Ok(events) => events.iter().for_each(print_event),
+            Err(err) => {
+                eprintln!("receive failed: {err}");
+                break;
+            }
+        }
+        match client.poll_timeouts() {
+            Ok(events) => events.iter().for_each(print_event),
+            Err(err) => {
+                eprintln!("timeout polling failed: {err}");
+                break;
+            }
+        }
+    }
+
+    match client.close() {
+        Ok(events) => events.iter().for_each(print_event),
+        Err(err) => eprintln!("close failed: {err}"),
+    }
+}
+
+fn print_event(event: &ClientEvent) {
+    match event {
+        ClientEvent::EchoReply { seq, rtt, .. } => {
+            println!("seq {seq}: rtt {:?}", rtt.effective);
+        }
+        ClientEvent::EchoLoss { seq, .. } => println!("seq {seq}: lost"),
+        other => println!("{other:?}"),
+    }
+}

crates/irtt-client/examples/managed_client.rs

@@ -0,0 +1,73 @@
+//! Managed multi-target client example (`tokio` feature).
+//!
+//! [`BlockingManagedClient`] runs one or more targets under a dedicated
+//! current-thread Tokio runtime and exposes a synchronous handle, so a caller
+//! that does not want to touch Tokio directly can still get managed
+//! multi-target orchestration, retries, and a lossy event stream.
+//!
+//! Run a server first, then run this example:
+//!
+//! ```text
+//! cargo run -p irtt-rs --bin irtt-server --features server
+//! cargo run -p irtt-client --example managed_client --features tokio
+//! ```
+//!
+//! This example does not wait for the managed run to finish naturally: it
+//! requests a stop after a fixed short window so it exits promptly even
+//! without a reachable server.
+
+use std::time::Duration;
+
+use irtt_client::managed::{
+    BlockingManagedClient, ManagedClientConfig, ManagedCompletionPolicy, ManagedEvent,
+    ManagedTargetConfig,
+};
+use irtt_client::ClientConfig;
+
+fn main() {
+    let config = ManagedClientConfig {
+        client: ClientConfig {
+            duration: None,
+            interval: Duration::from_millis(200),
+            open_timeouts: vec![Duration::from_millis(300)],
+            ..Default::default()
+        },
+        completion: ManagedCompletionPolicy::ExplicitStop,
+        ..Default::default()
+    };
+    let targets = vec![ManagedTargetConfig::new("local", "127.0.0.1:2112")];
+
+    let (owner, mut events) = match BlockingManagedClient::start_with_subscription(config, targets)
+    {
+        Ok(started) => started,
+        Err(err) => {
+            eprintln!("failed to start managed client: {err}");
+            return;
+        }
+    };
+
+    let stop_after = Duration::from_secs(1);
+    let deadline = std::time::Instant::now() + stop_after;
+    while std::time::Instant::now() < deadline {
+        match events.try_recv() {
+            Ok(event) => print_event(&event),
+            Err(_) => std::thread::sleep(Duration::from_millis(50)),
+        }
+    }
+
+    // `stop()` requests the stop synchronously; the returned receipt is only
+    // useful for awaiting durable acknowledgement, which this blocking
+    // example does not need.
+    std::mem::drop(owner.handle().stop());
+    match owner.join() {
+        Ok(outcome) => println!("managed run ended: {:?}", outcome.end_reason),
+        Err(err) => eprintln!("managed worker did not join cleanly: {err}"),
+    }
+}
+
+fn print_event(event: &ManagedEvent) {
+    match event {
+        ManagedEvent::Client { target, event } => println!("{}: {event:?}", target.id),
+        other => println!("{other:?}"),
+    }
+}

crates/irtt-client/examples/tokio_client.rs

@@ -0,0 +1,133 @@
+//! Low-level Tokio client example (`tokio` feature).
+//!
+//! Drives [`AsyncClient`] directly on a caller-owned runtime. This is the
+//! adapter to reach for when you already have a Tokio runtime and want to
+//! await sends/receives yourself, rather than use the higher-level `managed`
+//! driver (see the `managed_client` example).
+//!
+//! Run a server first, then run this example:
+//!
+//! ```text
+//! cargo run -p irtt-rs --bin irtt-server --features server
+//! cargo run -p irtt-client --example tokio_client --features tokio
+//! ```
+//!
+//! Without a reachable server this exits quickly with an open-timeout error
+//! instead of hanging, because the example shortens `open_timeouts` for a
+//! fast demonstration.
+
+use std::time::{Duration, Instant};
+
+use irtt_client::{AsyncClient, ClientConfig, ClientEvent};
+
+/// Upper bound on how long the receive wait can go without also calling
+/// `poll_timeouts()`. `AsyncClient` does not expose the earliest pending
+/// probe's own timeout deadline, so this example polls on a short fixed
+/// cadence instead of waiting for the full `probe_timeout()` from whenever
+/// this loop last ran — that would let poll_timeouts() classify a lost
+/// probe (and its dependent statistics/session state) far later than it
+/// actually became lost.
+const TIMEOUT_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+fn main() {
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_io()
+        .enable_time()
+        .build()
+        .expect("failed to build Tokio runtime");
+
+    runtime.block_on(run());
+}
+
+async fn run() {
+    let config = ClientConfig {
+        server_addr: "127.0.0.1:2112".to_owned(),
+        duration: Some(Duration::from_secs(2)),
+        interval: Duration::from_millis(200),
+        // A single short attempt keeps this example fast when no server is
+        // reachable; production callers should generally keep the default.
+        open_timeouts: vec![Duration::from_millis(300)],
+        ..Default::default()
+    };
+
+    let mut client = match AsyncClient::connect(config).await {
+        Ok(client) => client,
+        Err(err) => {
+            eprintln!("failed to prepare client socket: {err}");
+            return;
+        }
+    };
+
+    match client.open().await {
+        Ok(outcome) => println!("session opened: {outcome:?}"),
+        Err(err) => {
+            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
+            return;
+        }
+    }
+
+    while !client.is_run_complete() {
+        // Bound the receive wait by the next send/timeout deadline, rather
+        // than awaiting recv() unconditionally: a lost or rate-limited reply
+        // must not stall pacing or timeout classification indefinitely.
+        let wake_at = client
+            .next_send_deadline()
+            .into_iter()
+            .chain(std::iter::once(Instant::now() + TIMEOUT_POLL_INTERVAL))
+            .min()
+            .expect("the fixed poll-interval deadline is always present");
+
+        let recv_result = tokio::select! {
+            events = client.recv() => Some(events),
+            () = tokio::time::sleep_until(tokio::time::Instant::from_std(wake_at)) => None,
+        };
+        if let Some(result) = recv_result {
+            match result {
+                Ok(events) => events.iter().for_each(print_event),
+                Err(err) => {
+                    eprintln!("receive failed: {err}");
+                    break;
+                }
+            }
+        }
+
+        if client
+            .next_send_deadline()
+            .is_some_and(|send_at| Instant::now() >= send_at)
+        {
+            // A failed send retains its prepared probe without advancing the
+            // schedule, so a persistent error (e.g. the interface going
+            // down) would otherwise make this loop retry forever instead of
+            // reporting it.
+            match client.send_probe().await {
+                Ok(events) => events.iter().for_each(print_event),
+                Err(err) => {
+                    eprintln!("send failed: {err}");
+                    break;
+                }
+            }
+        }
+        match client.poll_timeouts() {
+            Ok(events) => events.iter().for_each(print_event),
+            Err(err) => {
+                eprintln!("timeout polling failed: {err}");
+                break;
+            }
+        }
+    }
+
+    match client.close().await {
+        Ok(events) => events.iter().for_each(print_event),
+        Err(err) => eprintln!("close failed: {err}"),
+    }
+}
+
+fn print_event(event: &ClientEvent) {
+    match event {
+        ClientEvent::EchoReply { seq, rtt, .. } => {
+            println!("seq {seq}: rtt {:?}", rtt.effective);
+        }
+        ClientEvent::EchoLoss { seq, .. } => println!("seq {seq}: lost"),
+        other => println!("{other:?}"),
+    }
+}

crates/irtt-client/src/async_client.rs

@@ -242,6 +242,31 @@ impl AsyncClientTestHooks {
 /// `AsyncClient` does not construct, own, or store a Tokio runtime. Its async
 /// methods are polled by the caller and require a current Tokio runtime with I/O
 /// and time enabled.
+///
+/// # Example
+///
+/// Use this low-level adapter when the application already owns Tokio and wants
+/// to drive the session lifecycle itself. This example type-checks without
+/// contacting a server.
+///
+/// ```no_run
+/// use irtt_client::{AsyncClient, ClientConfig};
+///
+/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
+/// let mut client = AsyncClient::connect(ClientConfig::default()).await?;
+/// let outcome = client.open().await?;
+/// println!("opened: {outcome:?}");
+/// let sent = client.send_probe().await?;
+/// println!("sent: {sent:?}");
+/// let received = client.recv().await?;
+/// println!("received: {received:?}");
+/// let timed_out = client.poll_timeouts()?;
+/// println!("timeouts: {timed_out:?}");
+/// let closed = client.close().await?;
+/// println!("closed: {closed:?}");
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug)]
 pub struct AsyncClient {
     socket: tokio::net::UdpSocket,
@@ -608,8 +633,14 @@ impl AsyncClient {
                 // No sent_at measurement, no machine commit, no schedule
                 // commit: the transaction is fully discarded and retried
                 // with a fresh send_anchor on the next loop iteration.
-                Err(error) if error.kind() == io::ErrorKind::WouldBlock => continue,
+                Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
-                Err(error) => return Poll::Ready(Err(ClientError::Socket(error))),
+                    self.machine.invalidate_kernel_tx_correlation();
+                    continue;
+                }
+                Err(error) => {
+                    self.machine.invalidate_kernel_tx_correlation();
+                    return Poll::Ready(Err(ClientError::Socket(error)));
+                }
             };
 
             #[cfg(not(test))]

crates/irtt-client/src/client.rs

@@ -103,6 +103,31 @@ use crate::{
 /// session, send probes, receive replies, poll timeouts, and close. Callers
 /// that do not need to own this loop can use the unified managed API in
 /// [`crate::managed`] when the `tokio` feature is enabled.
+///
+/// # Example
+///
+/// `Client` is the runtime-free adapter. The caller drives receives and timeout
+/// polling between sends; see the standalone example for a complete loop.
+/// This example type-checks without contacting a server:
+///
+/// ```no_run
+/// use irtt_client::{Client, ClientConfig};
+///
+/// # fn run() -> Result<(), Box<dyn std::error::Error>> {
+/// let mut client = Client::connect(ClientConfig::default())?;
+/// let outcome = client.open()?;
+/// println!("opened: {outcome:?}");
+/// let sent = client.send_probe()?;
+/// println!("sent: {sent:?}");
+/// let received = client.recv_once()?;
+/// println!("received: {received:?}");
+/// let timed_out = client.poll_timeouts()?;
+/// println!("timeouts: {timed_out:?}");
+/// let closed = client.close()?;
+/// println!("closed: {closed:?}");
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug)]
 pub struct Client {
     runtime: SessionMachine,
@@ -163,12 +188,13 @@ impl Client {
     ///
     /// On success, returns the negotiated open outcome and transitions the
     /// client into either an open probe session or completed no-test state.
-    /// Open attempts use [`ClientConfig::open_timeouts`]. Malformed, unrelated,
+    /// Open attempts use [`ClientConfig::open_timeouts`]. Malformed or
-    /// or unauthenticated datagrams are ignored until the current attempt's
+    /// unrelated datagrams are ignored until the current attempt's absolute
-    /// absolute deadline, so one attempt may consume several datagrams without
+    /// deadline, so one attempt may consume several datagrams without
     /// retransmitting. Silence or ignored traffic eventually produces
-    /// [`ClientError::OpenTimeout`], while authenticated incompatibility remains
+    /// [`ClientError::OpenTimeout`]. A structurally recognizable malformed or
-    /// terminal.
+    /// incompatible Open reply from the connected peer is terminal; when HMAC
+    /// is configured, that recognition additionally requires authentication.
     ///
     /// When a trusted reply allocates a token but later negotiation or socket
     /// preparation fails, the client sends a best-effort cleanup close and
@@ -523,11 +549,18 @@ impl Client {
             .unwrap_or_else(Instant::now);
         #[cfg(test)]
         if fail_send {
+            runtime.invalidate_kernel_tx_correlation();
             return Err(ClientError::Socket(io::Error::other(
                 "injected probe send failure",
             )));
         }
-        let bytes = socket.send(&prepared.bytes)?;
+        let bytes = match socket.send(&prepared.bytes) {
+            Ok(bytes) => bytes,
+            Err(error) => {
+                runtime.invalidate_kernel_tx_correlation();
+                return Err(ClientError::Socket(error));
+            }
+        };
         #[cfg(not(test))]
         let send_finished_at = Instant::now();
         #[cfg(test)]

crates/irtt-client/src/config.rs

@@ -46,6 +46,31 @@ pub(crate) const DEFAULT_MAX_PENDING: usize = 4096;
 /// request and the local client behavior used to drive the UDP socket. Values
 /// that are negotiated by the server are available after opening the session
 /// through [`NegotiatedParams`](crate::NegotiatedParams).
+///
+/// # Example
+///
+/// Configure a finite run with larger probes and accept documented server
+/// restrictions. Use `duration: None` for continuous mode, or
+/// [`RunMode::NoTest`] for negotiation without probes.
+///
+/// ```
+/// use std::time::Duration;
+///
+/// use irtt_client::{ClientConfig, NegotiationPolicy};
+///
+/// let config = ClientConfig {
+///     server_addr: "example.net:2112".into(),
+///     duration: Some(Duration::from_secs(10)),
+///     interval: Duration::from_millis(250),
+///     length: 1200,
+///     negotiation_policy: NegotiationPolicy::Loose,
+///     ..ClientConfig::default()
+/// };
+///
+/// assert_eq!(config.duration, Some(Duration::from_secs(10)));
+/// assert_eq!(config.interval, Duration::from_millis(250));
+/// assert_eq!(config.length, 1200);
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientConfig {
     /// Remote server name or address.
@@ -176,6 +201,29 @@ impl Default for ClientConfig {
 /// These settings affect how the client binds, resolves, and receives from the
 /// socket. They do not change the IRTT protocol parameters negotiated with the
 /// server.
+///
+/// # Example
+///
+/// Bind to a chosen local endpoint and set the outgoing IPv4 TTL:
+///
+/// ```
+/// use std::net::{Ipv4Addr, SocketAddr};
+///
+/// use irtt_client::{ClientConfig, SocketConfig};
+///
+/// let config = ClientConfig {
+///     socket_config: SocketConfig {
+///         bind_addr: Some(SocketAddr::from((Ipv4Addr::UNSPECIFIED, 0))),
+///         ttl: Some(32),
+///         ipv4_only: true,
+///         ..SocketConfig::default()
+///     },
+///     ..ClientConfig::default()
+/// };
+///
+/// assert_eq!(config.socket_config.ttl, Some(32));
+/// assert!(config.socket_config.ipv4_only);
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct SocketConfig {
     /// Local address to bind before connecting the UDP socket.

crates/irtt-client/src/event.rs

@@ -260,6 +260,19 @@ pub struct RttSample {
 /// processing time or comparing wall-clock timestamps from different hosts. It
 /// should not be used to represent raw elapsed wall-clock or monotonic time,
 /// which is non-negative and represented by [`Duration`].
+///
+/// # Example
+///
+/// Signed timing values retain a negative result instead of clamping clock
+/// skew or server processing adjustments to zero:
+///
+/// ```
+/// use irtt_client::SignedDuration;
+///
+/// let adjusted_rtt = SignedDuration::from_nanos(-250_000);
+/// assert!(adjusted_rtt.is_negative());
+/// assert_eq!(adjusted_rtt.as_micros(), -250);
+/// ```
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub struct SignedDuration {
     ns: i128,
@@ -351,7 +364,22 @@ pub struct OneWayDelaySample {
     /// Client-to-server delay.
     ///
     /// This is computed from the client send wall time and the server receive
-    /// wall time when both are available.
+    /// wall time when both are available. The client send endpoint is the
+    /// correlated Linux kernel TX timestamp for this send when one is
+    /// available and plausible for this send, and the userspace post-send wall
+    /// time otherwise. The server receive endpoint is whatever wall time the
+    /// peer reported; against this crate's own Tokio server runtime on Linux
+    /// (the `irtt-server` applet), that is its kernel receive timestamp when
+    /// one is available and plausible, and its userspace receive wall time
+    /// otherwise. Against another IRTT-compatible peer, or an application
+    /// driving `irtt_server::ServerCore::handle_datagram` directly, the
+    /// client has no way to know which clock source produced it — the public
+    /// `ServerCore` API never supplies a kernel timestamp of its own accord.
+    /// `RttSample::raw` is unaffected and remains a userspace
+    /// monotonic measurement, but `adjusted` and `effective` can still shift:
+    /// when the session negotiated wall-clock timing rather than monotonic,
+    /// server processing time is derived from this same server receive
+    /// endpoint.
     pub client_to_server: Option<SignedDuration>,
     /// Server-to-client delay.
     ///

crates/irtt-client/src/lib.rs

@@ -13,10 +13,19 @@
 //! also signed when the required wall-clock timestamps are available; negative
 //! values usually indicate client/server clock skew.
 //!
-//! [`Client`] is the runtime-free low-level blocking adapter. With the
+//! [`Client`] is the runtime-free low-level blocking adapter and requires no
-//! `tokio` feature, `AsyncClient` provides the corresponding Tokio adapter;
+//! Tokio dependency at all; it is what a caller without a runtime, or that
-//! [`managed`] contains the unified managed task/handle implementation,
+//! wants full control over its own event loop, should start from. With the
-//! including the dedicated-runtime blocking frontend for synchronous callers.
+//! `tokio` feature, `AsyncClient` provides the corresponding low-level Tokio
+//! adapter for a caller that owns a runtime and drives socket readiness
+//! itself. [`managed`] sits above both: `ManagedClientTask` /
+//! `ManagedClientHandle` (`tokio` feature) run and control one or more
+//! targets under a Tokio runtime, and `BlockingManagedClient` (`tokio`
+//! feature) wraps that in a synchronous owner backed by its own dedicated
+//! current-thread runtime for callers that want managed multi-target
+//! behavior without touching Tokio themselves.
+//!
+//! See `examples/` in the repository for a runnable example of each tier.
 //!
 #![forbid(unsafe_code)]
 

crates/irtt-client/src/managed/blocking_tests.rs

@@ -250,15 +250,11 @@ fn dynamic_update_reaches_background_worker() {
         .unwrap();
     let handle = owner.handle();
 
-    let acknowledgement = test_runtime().block_on(async {
+    let acknowledgement = handle
-        timeout(
+        .update_targets(vec![target(&server)])
-            Duration::from_secs(2),
-            handle.update_targets(vec![target(&server)]).unwrap(),
-        )
-        .await
         .unwrap()
-        .unwrap()
+        .blocking_wait()
-    });
+        .unwrap();
     assert_eq!(acknowledgement.sequence, 1);
     server.wait_probe();
     test_runtime().block_on(async {

crates/irtt-client/src/managed/task.rs

@@ -44,6 +44,42 @@ const POST_DEADLINE_RECEIVE_BUDGET: usize = TARGET_WORK_BUDGET;
 const MAX_BROADCAST_CHANNEL_CAPACITY: usize = usize::MAX >> 1;
 
 /// Entry point for constructing a unified Tokio managed task.
+///
+/// # Example
+///
+/// Construct the task and its separate control handle, subscribe before
+/// starting the task, then run it under the caller's Tokio runtime. A reachable
+/// server is required at runtime, so this example only type-checks.
+///
+/// ```no_run
+/// use irtt_client::{ClientConfig, ClientEvent};
+/// use irtt_client::managed::{
+///     ManagedClient, ManagedClientConfig, ManagedEvent, ManagedTargetConfig,
+/// };
+///
+/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
+/// let config = ManagedClientConfig {
+///     client: ClientConfig {
+///         duration: Some(std::time::Duration::from_secs(10)),
+///         ..ClientConfig::default()
+///     },
+///     ..ManagedClientConfig::default()
+/// };
+/// let targets = vec![ManagedTargetConfig::new("edge", "127.0.0.1:2112")];
+/// let (task, handle) = ManagedClient::task(config, targets)?;
+/// let mut events = handle.subscribe()?;
+/// let driver = tokio::spawn(task);
+///
+/// while let Ok(event) = events.recv().await {
+///     if let ManagedEvent::Client { event: ClientEvent::EchoReply { .. }, .. } = event {
+///         println!("received a probe reply");
+///     }
+/// }
+/// let outcome = driver.await?;
+/// println!("run ended: {:?}", outcome.end_reason);
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug, Default)]
 pub struct ManagedClient;
 
@@ -236,7 +272,21 @@ impl ManagedClientHandle {
         ManagedStopReceipt::new(Arc::clone(&self.stop))
     }
 
-    /// Submit one complete desired target set without awaiting queue capacity.
+    /// Submit the complete desired target set, replacing any previous one.
+    ///
+    /// `targets` is not a delta: any live target whose id is missing from
+    /// `targets` is stopped and removed. A target that is still present with an
+    /// unchanged configuration continues undisturbed — it is not restarted and
+    /// does not get a new generation. A target present with a *changed*
+    /// configuration, or whose current generation already reached a terminal
+    /// state (e.g. failed, completed, or was closed by the peer), is treated as
+    /// a fresh start: it is retired and a new generation is created for it, even
+    /// if the configuration is byte-for-byte identical to the one that just
+    /// finished.
+    ///
+    /// This call enqueues the update without waiting for queue capacity; await
+    /// the returned [`ManagedCommandReceipt`] to observe whether — and how — it
+    /// was applied.
     pub fn update_targets(
         &self,
         targets: Vec<ManagedTargetConfig>,
@@ -287,6 +337,19 @@ pub struct ManagedCommandReceipt {
     receiver: oneshot::Receiver<Result<ManagedCommandAcknowledgement, ManagedCommandApplyError>>,
 }
 
+impl ManagedCommandReceipt {
+    /// Block until the target-set transaction is applied or rejected.
+    ///
+    /// This is for synchronous callers such as [`crate::managed::BlockingManagedClient`]. It
+    /// must not be called from an asynchronous runtime; use the [`Future`]
+    /// implementation there instead.
+    pub fn blocking_wait(self) -> Result<ManagedCommandAcknowledgement, ManagedCommandApplyError> {
+        self.receiver
+            .blocking_recv()
+            .unwrap_or(Err(ManagedCommandApplyError::AcknowledgementDisconnected))
+    }
+}
+
 impl Future for ManagedCommandReceipt {
     type Output = Result<ManagedCommandAcknowledgement, ManagedCommandApplyError>;
     fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
@@ -1586,6 +1649,30 @@ impl ManagedClientTask {
         self.send_gate = self.send_gate.filter(|gate| *gate > now);
     }
 
+    /// The next stagger gate after a send was accepted at `accepted_at`.
+    ///
+    /// The gate advances on its **own** cadence rather than being re-anchored
+    /// on every observed accept time. Anchoring on `accepted_at` folds each
+    /// send's wakeup latency into the next slot and then into every slot after
+    /// it, so the gate — and with it the whole group's send cadence — drifts
+    /// later without bound while the per-target schedules stay on their
+    /// absolute grid. The drift is not hypothetical: it shows up as a
+    /// monotonically growing `EchoSent::timer_error` and, once it exceeds one
+    /// interval, as probe slots the schedule then skips.
+    ///
+    /// `accepted_at` is still the anchor in the two cases where continuing the
+    /// old cadence would be wrong: there is no previous gate, or the pacer has
+    /// fallen a full slot behind it. Re-anchoring there is what keeps a gate
+    /// stranded in the past from releasing a burst of catch-up sends once the
+    /// group starts moving again.
+    fn next_stagger_gate(&self, spacing: Duration, accepted_at: Instant) -> Option<Instant> {
+        let base = match self.send_gate {
+            Some(gate) if gate <= accepted_at && accepted_at.duration_since(gate) < spacing => gate,
+            _ => accepted_at,
+        };
+        base.checked_add(spacing)
+    }
+
     fn record_stagger_acceptance(
         &mut self,
         result: SendResult,
@@ -1599,7 +1686,7 @@ impl ManagedClientTask {
             return;
         };
         self.last_stagger_send = Some(accepted_at);
-        self.send_gate = accepted_at.checked_add(spacing);
+        self.send_gate = self.next_stagger_gate(spacing, accepted_at);
         #[cfg(test)]
         if let Some(observations) = &self.stagger_observations {
             observations.lock().unwrap().push((_active, spacing));

crates/irtt-client/src/managed/tests.rs

@@ -1576,6 +1576,37 @@ fn authenticated_peer_close_outcome() {
     assert!(!has_close(&records));
 }
 
+#[test]
+fn peer_close_leaves_other_explicitly_managed_targets_running() {
+    let closing = start_server(ServerBehavior::PeerClose, None);
+    let continuing = start_server(ServerBehavior::Echo, None);
+    let mut managed = config(ManagedPacing::Staggered);
+    managed.completion = ManagedCompletionPolicy::ExplicitStop;
+    managed.client.duration = None;
+    let (task, handle) = ManagedClient::task(
+        managed,
+        vec![
+            target("closing", closing.addr),
+            target("continuing", continuing.addr),
+        ],
+    )
+    .unwrap();
+    let runtime = runtime();
+    let mut task = Box::pin(task);
+
+    drive_task_until(&runtime, &mut task, |task| {
+        handle.status().peer_closed_target_outcomes == 1
+            && task.targets[1].counters.packets_sent != 0
+    });
+    assert_eq!(handle.status().lifecycle, ManagedLifecycle::Running);
+
+    let stop = handle.stop();
+    runtime.block_on(task);
+    runtime.block_on(stop);
+    closing.finish();
+    assert!(!probes(&continuing.finish()).is_empty());
+}
+
 #[test]
 fn peer_close_during_stop_drain_remains_authoritative() {
     let key = b"managed-drain-peer-close".to_vec();
@@ -1864,6 +1895,78 @@ fn stagger_gate_tracks_active_membership() {
     second.finish();
 }
 
+/// The stagger gate must not fold each send's observed wakeup latency into
+/// every later slot.
+///
+/// The gate is the binding constraint on when the *group* may send next (see
+/// `next_deadline`), while each target's own schedule stays on an absolute
+/// grid anchored at its open. Re-anchoring the gate on every observed accept
+/// time therefore made the whole group's cadence drift later without bound:
+/// `EchoSent::timer_error` grew monotonically, and once the drift exceeded one
+/// interval `skip_missed_probe_slots_at` started dropping probe slots
+/// outright. Measured before this was fixed, a single-target 20 s run at a
+/// 50 ms interval sent 381 probes instead of 400.
+///
+/// This asserts the invariant directly rather than through a real-time run,
+/// because reproducing accumulation behaviorally needs seconds of wall clock
+/// and a jitter assumption. Two properties, both durable:
+///
+/// - while the pacer keeps up, N accepted sends advance the gate by exactly
+///   N spacings from the first anchor, whatever lateness each send is
+///   observed with;
+/// - a gate the pacer has fallen a full spacing behind re-anchors on the
+///   accept time instead, so a stranded gate cannot release a burst of
+///   catch-up sends.
+#[test]
+fn the_stagger_gate_advances_by_one_spacing_per_send_without_accumulating_lateness() {
+    // No socket is involved: the gate is driven directly and the task is never
+    // polled, so an unreachable address is all a valid target set needs here.
+    let (mut task, _) = ManagedClient::task(
+        config(ManagedPacing::Staggered),
+        vec![target("only", "127.0.0.1:9".parse().unwrap())],
+    )
+    .unwrap();
+
+    let spacing = Duration::from_millis(50);
+    let start = Instant::now();
+    let lateness = Duration::from_millis(3);
+
+    task.record_stagger_acceptance(
+        SendResult::Ready { accepted: true },
+        Some((1, spacing)),
+        start,
+    );
+    assert_eq!(task.send_gate, Some(start + spacing), "first send anchors");
+
+    // Every later send is observed `lateness` after the gate that released it.
+    // The gate must still advance one spacing per send from `start`, not
+    // `spacing + lateness`.
+    for slot in 1..=8_u32 {
+        let released_at = start + spacing * slot;
+        task.record_stagger_acceptance(
+            SendResult::Ready { accepted: true },
+            Some((1, spacing)),
+            released_at + lateness,
+        );
+        assert_eq!(
+            task.send_gate,
+            Some(start + spacing * (slot + 1)),
+            "slot {slot} accumulated observed lateness into the gate"
+        );
+    }
+
+    // A full spacing behind is no longer the same cadence, so the gate
+    // re-anchors rather than staying stranded in the past.
+    let stalled_gate = task.send_gate.expect("the gate is set");
+    let resumed_at = stalled_gate + spacing;
+    task.record_stagger_acceptance(
+        SendResult::Ready { accepted: true },
+        Some((1, spacing)),
+        resumed_at,
+    );
+    assert_eq!(task.send_gate, Some(resumed_at + spacing));
+}
+
 #[test]
 fn timeout_discovery_inspects_at_most_one_budget_of_targets() {
     let target_count = TIMEOUT_WORK_BUDGET + 1;

crates/irtt-client/src/probe.rs

@@ -39,7 +39,8 @@ pub(crate) struct PendingProbe {
     /// eligible only for upstream one-way delay after local plausibility
     /// validation against `tx_not_before_wall` (see `compute_one_way`'s
     /// `preferred_send_wall`). `sent_at` remains the userspace fallback for
-    /// upstream one-way delay when this is absent or implausible.
+    /// upstream one-way delay when this is absent, implausible, or kernel-ID
+    /// correlation was invalidated by a failed probe submission.
     pub kernel_tx_timestamp: Option<SystemTime>,
 }
 

crates/irtt-client/src/receive/linux.rs

@@ -12,14 +12,17 @@
 //! After a successful Open, the client adapter best-effort upgrades the
 //! socket from [`RX_TIMESTAMPING_FLAGS`] to [`error_queue::TX_TIMESTAMPING_FLAGS`]
 //! via [`try_enable_tx_timestamping`]. When that succeeds, the automatic
-//! `SOF_TIMESTAMPING_OPT_ID` counter the kernel assigns to each successfully
+//! `SOF_TIMESTAMPING_OPT_ID` counter normally tracks the probe wire sequence
-//! submitted datagram is used directly as the probe's wire sequence number
+//! after successful sends, so it is used as a best-effort correlation ID.
-//! (see the client crate's `AGENTS.md` for the correlation invariant this
+//! A kernel ID can theoretically be consumed by a send that later fails,
-//! relies on). [`drain_tx_timestamps`] performs a small bounded, nonblocking
+//! desynchronizing that correlation. [`drain_tx_timestamps`] discards
-//! read of `MSG_ERRQUEUE` so the adapter can opportunistically collect those
+//! unmatched or implausible records; the userspace `sent_at` timestamp remains
-//! timestamps without ever waiting for one. The observed kernel TX wall time
+//! the fallback. After a probe send failure, correlation is disabled for that
-//! is retained as metadata only; it is not consumed by any measurement in
+//! session so later IDs cannot be misattributed. It performs a small bounded,
-//! this change.
+//! nonblocking read of
+//! `MSG_ERRQUEUE` so the adapter can opportunistically collect timestamps
+//! without ever waiting for one. The observed kernel TX wall time is retained
+//! as metadata only; it is not consumed by any measurement in this change.
 
 use std::{
     io::{self, IoSliceMut},

crates/irtt-client/src/receive/linux/error_queue.rs

@@ -624,22 +624,14 @@ mod tests {
         ));
     }
 
-    // NOTE: a live test proving that a failed nonblocking `sendmsg` does not
+    // NOTE: There is no live test for whether a failed nonblocking `sendmsg`
-    // consume an automatic OPT_ID is not included here. Forcing a reliable,
+    // consumes an automatic OPT_ID. Forcing a reliable, non-flaky `WouldBlock`
-    // non-flaky `WouldBlock` on a connected loopback UDP socket (e.g. via
+    // on a connected loopback UDP socket (for example through socket-buffer
-    // socket-buffer saturation) has no deterministic OS-level mechanism
+    // saturation) has no deterministic OS-level mechanism in this environment,
-    // available in this environment, and the repository's testing policy
+    // and the repository's testing policy forbids sleep/saturation-based
-    // explicitly forbids faking coverage with sleep/saturation-based
+    // flakiness. The correlation is intentionally best effort: a kernel ID can
-    // flakiness. That safety is instead established from Linux kernel
+    // theoretically be consumed by a send that later fails. The deterministic
-    // source: `_sock_tx_timestamp` (include/net/sock.h) and
+    // adapter test covers only the local half: an injected `WouldBlock` does
-    // `__ip_append_data`/`__ip6_append_data` (net/ipv4/ip_output.c,
+    // not advance the local wire-sequence counter. Any later unmatched kernel
-    // net/ipv6/ip6_output.c) increment `sk->sk_tskey` speculatively before
+    // timestamp is discarded and the userspace `sent_at` remains the fallback.
-    // a datagram is fully built and explicitly `atomic_dec` it back out on
-    // every error path (tracked via a local `hold_tskey` flag), so a failed
-    // send can never leave a gap in — or otherwise advance — the ID space
-    // the kernel hands out to successfully submitted datagrams. See the
-    // client crate's `AGENTS.md` for the full citation. The client-side
-    // half of this invariant (a `WouldBlock` `try_send` never advances the
-    // local wire-sequence counter used as the correlation ID) is covered by
-    // a deterministic test in the adapter module that injects `WouldBlock`.
 }

crates/irtt-client/src/session/machine.rs

@@ -60,6 +60,7 @@ struct ActiveSession {
     pending: PendingMap,
     timed_out: TimedOutMap,
     completed: CompletedSet,
+    kernel_tx_correlation_valid: bool,
 }
 
 #[derive(Debug)]
@@ -423,15 +424,27 @@ impl SessionMachine {
         }
     }
 
+    /// Disable Linux kernel TX timestamp correlation after a probe send fails.
+    ///
+    /// A failed submission can consume a kernel `SOF_TIMESTAMPING_OPT_ID`
+    /// without advancing the wire sequence. Existing associated timestamps
+    /// remain valid observations; later error-queue timestamps cannot be
+    /// associated safely and are ignored for the rest of this session.
+    pub(crate) fn invalidate_kernel_tx_correlation(&mut self) {
+        if let MachineState::Open(session) = &mut self.state {
+            session.kernel_tx_correlation_valid = false;
+        }
+    }
+
     /// Record an observed Linux kernel TX timestamp for `wire_seq`, the
     /// automatic `SOF_TIMESTAMPING_OPT_ID` the kernel assigned when the
     /// datagram was submitted.
     ///
-    /// `wire_seq` doubles as that correlation ID: both counters start at
+    /// `wire_seq` normally matches that correlation ID after successful
-    /// zero for a session's first timestamped send and advance by exactly
+    /// sends. This is best effort rather than an invariant: a kernel ID can
-    /// one only on a confirmed successful submission, so they stay
+    /// theoretically be consumed by a send that later fails, leaving the
-    /// identical for the life of one open session (see the client crate's
+    /// counters desynchronized. An unmatched or implausible ID is discarded;
-    /// `AGENTS.md` for the full invariant).
+    /// the probe's userspace `sent_at` remains the fallback.
     ///
     /// Updates a still-pending or already-timed-out probe in place. Never
     /// resurrects a completed, evicted, or unknown probe, and never touches
@@ -443,6 +456,9 @@ impl SessionMachine {
         let MachineState::Open(session) = &mut self.state else {
             return;
         };
+        if !session.kernel_tx_correlation_valid {
+            return;
+        }
         if let Some(probe) = session.pending.get_mut(wire_seq) {
             probe.kernel_tx_timestamp.get_or_insert(timestamp);
             return;
@@ -636,6 +652,7 @@ impl SessionMachine {
             pending: PendingMap::new(self.config.max_pending_probes),
             timed_out: TimedOutMap::new(self.config.max_pending_probes),
             completed: CompletedSet::new(self.config.max_pending_probes),
+            kernel_tx_correlation_valid: true,
         }));
 
         let event = ClientEvent::SessionStarted {
@@ -1231,6 +1248,7 @@ mod tests {
             pending: PendingMap::new(max_pending_probes),
             timed_out: TimedOutMap::new(max_pending_probes),
             completed: CompletedSet::new(max_pending_probes),
+            kernel_tx_correlation_valid: true,
         }));
         machine
     }
@@ -2873,6 +2891,25 @@ mod tests {
         );
     }
 
+    #[test]
+    fn invalidated_kernel_tx_correlation_uses_userspace_send_time() {
+        let mono = Instant::now();
+        let mut machine = upstream_probe(send_wall_ms(1_000), mono);
+
+        // A failed send can consume a kernel ID without advancing wire_seq.
+        // A later timestamp whose ID happens to match a pending wire sequence
+        // must not be associated after that gap.
+        machine.invalidate_kernel_tx_correlation();
+        machine.record_kernel_tx_timestamp(0, send_wall_ms(1_005));
+
+        let events = upstream_reply(&mut machine, 1_020, send_wall_ms(1_040), mono);
+
+        assert_eq!(
+            reply_one_way(&events).unwrap().client_to_server,
+            Some(SignedDuration::from_nanos(20_000_000))
+        );
+    }
+
     #[test]
     fn upstream_one_way_delay_falls_back_without_kernel_tx() {
         let mono = Instant::now();
@@ -3097,4 +3134,691 @@ mod tests {
             Some(SignedDuration::from_nanos(12_000_000))
         );
     }
+
+    /// Model-based tests for `SessionMachine`'s open-session operation
+    /// contract: probe sends, reply classification, timeouts, and close.
+    ///
+    /// ## Reference-model boundary
+    ///
+    /// The open handshake itself (accept/reject, run-mode, version and
+    /// token checks) is deliberately out of scope here: it already has
+    /// focused deterministic coverage above in `mod tests`, and every
+    /// generated case here starts from an already-`Open` session built the
+    /// same way `open_machine` above builds one, by constructing
+    /// `MachineState::Open` directly. What *is* generated and checked
+    /// against an independent reference model is the combinatorial space
+    /// that only exists once a session is open: interleaved probe sends,
+    /// valid/duplicate/late/unknown/wrong-token replies, peer and local
+    /// close, bounded and unbounded timeout polling, and `u32` wire-sequence
+    /// wraparound.
+    ///
+    /// The reference [`Model`] tracks only state the public contract
+    /// documents: open/closed(local)/closed(peer) state, the next wire
+    /// sequence and total sent-packet counters (mirroring
+    /// `SessionMachine::packets_sent`), which sequences are pending, timed
+    /// out, or completed (this drives the exact
+    /// `EchoReply`/`LateReply`/`DuplicateReply`/`Warning` classification
+    /// documented on `ClientEvent`), each pending probe's timeout deadline
+    /// (documented on `ClientEvent::EchoLoss::timeout_at`), and the highest
+    /// accepted in-window sequence used for late-reply classification. It
+    /// deliberately does *not* model the bounded FIFO eviction that
+    /// `PendingMap`/`TimedOutMap`/`CompletedSet` apply once
+    /// `max_pending_probes` is exceeded: that is a private capacity policy
+    /// with its own focused unit tests in `probe.rs`, not part of this
+    /// contract. Every generated case here uses a `max_pending_probes` far
+    /// larger than the generated operation count, so capacity/eviction
+    /// behavior never confounds the classification assertions made here.
+    ///
+    /// `u32` sequence wraparound is exercised by seeding a session's
+    /// starting wire sequence near `u32::MAX` through direct construction,
+    /// the same way `open_machine` above builds an open session without
+    /// running the handshake. The repository's `AGENTS.md` testing policy
+    /// names "sequence wrap" as a sanctioned reason to construct state
+    /// directly rather than drive billions of real sends.
+    mod model_properties {
+        use std::collections::{HashSet, VecDeque};
+
+        use proptest::prelude::*;
+        use proptest::test_runner::TestCaseError;
+
+        use super::*;
+        use irtt_proto::{encode_echo_reply, ReceivedStats, StampAt};
+
+        const TOKEN: u64 = 0x1122_3344_5566_7788;
+        const WRONG_TOKEN: u64 = 0x8877_6655_4433_2211;
+        const PROBE_TIMEOUT: Duration = Duration::from_millis(30);
+        /// Far larger than the generated operation count (`1..=OP_LIMIT`),
+        /// so pending/timed-out/completed bounded eviction never triggers;
+        /// see the module doc comment.
+        const MAX_PENDING_PROBES: usize = 4096;
+        const OP_LIMIT: usize = 50;
+        const CASES: u32 = 256;
+
+        fn model_config() -> ClientConfig {
+            ClientConfig {
+                received_stats: ReceivedStats::None,
+                stamp_at: StampAt::None,
+                clock: Clock::Wall,
+                probe_timeout: PROBE_TIMEOUT,
+                max_pending_probes: MAX_PENDING_PROBES,
+                run_mode: RunMode::Normal,
+                ..ClientConfig::default()
+            }
+        }
+
+        /// Builds an already-`Open` session directly, the same way `mod
+        /// tests`'s `open_machine` does, starting its wire sequence at
+        /// `start_seq` instead of always zero. See the module doc comment
+        /// for why this bypasses the open handshake and for the sequence
+        /// seeding rationale.
+        fn open_machine_for_model(start_seq: u32) -> (SessionMachine, Params) {
+            let config = model_config();
+            let remote = "127.0.0.1:2112".parse().unwrap();
+            let mut machine = SessionMachine::new(config, remote).unwrap();
+            let params = machine.requested.clone();
+            let negotiated = NegotiatedParams {
+                params: params.clone(),
+                restrictions: Vec::new(),
+            };
+            machine.state = MachineState::Open(Box::new(ActiveSession {
+                token: TOKEN,
+                negotiated,
+                local_close_packet: encode_request(RequestToEncode::Close { token: TOKEN }, None)
+                    .unwrap()
+                    .into_boxed_slice(),
+                next_wire_seq: start_seq,
+                highest_received_seq: None,
+                packets_sent: 0,
+                pending: PendingMap::new(MAX_PENDING_PROBES),
+                timed_out: TimedOutMap::new(MAX_PENDING_PROBES),
+                completed: CompletedSet::new(MAX_PENDING_PROBES),
+                kernel_tx_correlation_valid: true,
+            }));
+            (machine, params)
+        }
+
+        fn build_echo_reply(params: &Params, token: u64, seq: u32, close: bool) -> Vec<u8> {
+            let mut flags_value = flags::FLAG_REPLY;
+            if close {
+                flags_value |= flags::FLAG_CLOSE;
+            }
+            let reply = EchoReply {
+                flags: flags_value,
+                token,
+                sequence: seq,
+                recv_count: None,
+                recv_window: None,
+                timestamps: TimestampFields::default(),
+                payload: Vec::new(),
+            };
+            encode_echo_reply(&reply, params, None).unwrap()
+        }
+
+        /// Independently-authored mirror of the sequence-space half-window
+        /// "after" comparison (RFC 1982 style), used only to predict
+        /// expected late/in-window classification. Deliberately not a call
+        /// into `super::sequence_is_after`/`sequence_is_before`, so a bug in
+        /// the production comparator is not automatically invisible to this
+        /// model.
+        fn seq_after(candidate: u32, current: u32) -> bool {
+            candidate != current && candidate.wrapping_sub(current) < (1 << 31)
+        }
+
+        fn seq_before(candidate: u32, current: u32) -> bool {
+            seq_after(current, candidate)
+        }
+
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        enum ModelState {
+            Open,
+            ClosedLocal,
+            ClosedPeer,
+        }
+
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        enum ExpectedEvent {
+            EchoReply(u32),
+            LateReply(u32),
+            DuplicateReply(u32),
+            WarnWrongToken,
+            WarnUntracked,
+            SessionClosed,
+        }
+
+        /// The independent reference model. See the module doc comment for
+        /// its deliberate boundary against `SessionMachine`'s private state.
+        struct Model {
+            state: ModelState,
+            next_wire_seq: u32,
+            packets_sent: u64,
+            pending: VecDeque<(u32, Instant)>,
+            timed_out: HashSet<u32>,
+            completed: HashSet<u32>,
+            highest_received_seq: Option<u32>,
+        }
+
+        impl Model {
+            fn new(start_seq: u32) -> Self {
+                Self {
+                    state: ModelState::Open,
+                    next_wire_seq: start_seq,
+                    packets_sent: 0,
+                    pending: VecDeque::new(),
+                    timed_out: HashSet::new(),
+                    completed: HashSet::new(),
+                    highest_received_seq: None,
+                }
+            }
+
+            fn pending_remove(&mut self, seq: u32) -> bool {
+                if let Some(pos) = self.pending.iter().position(|&(s, _)| s == seq) {
+                    self.pending.remove(pos);
+                    true
+                } else {
+                    false
+                }
+            }
+
+            fn sorted_pending(&self) -> Vec<u32> {
+                let mut v: Vec<u32> = self.pending.iter().map(|&(s, _)| s).collect();
+                v.sort_unstable();
+                v
+            }
+
+            fn sorted_timed_out(&self) -> Vec<u32> {
+                let mut v: Vec<u32> = self.timed_out.iter().copied().collect();
+                v.sort_unstable();
+                v
+            }
+
+            fn sorted_completed(&self) -> Vec<u32> {
+                let mut v: Vec<u32> = self.completed.iter().copied().collect();
+                v.sort_unstable();
+                v
+            }
+
+            /// Resolves a generated [`ReplyTarget`] to a concrete sequence
+            /// number against the model's *current* membership. When the
+            /// requested bucket is empty this falls back to the raw index as
+            /// a literal (likely-unknown) sequence, so every `ReplyTarget`
+            /// variant remains a valid, meaningful generator input
+            /// regardless of what has happened so far.
+            fn resolve(&self, target: ReplyTarget) -> u32 {
+                fn pick(v: &[u32], i: u32) -> u32 {
+                    if v.is_empty() {
+                        i
+                    } else {
+                        v[(i as usize) % v.len()]
+                    }
+                }
+                match target {
+                    ReplyTarget::Pending(i) => pick(&self.sorted_pending(), i),
+                    ReplyTarget::TimedOut(i) => pick(&self.sorted_timed_out(), i),
+                    ReplyTarget::Completed(i) => pick(&self.sorted_completed(), i),
+                    ReplyTarget::Unknown(seq) => seq,
+                }
+            }
+
+            fn update_highest(&mut self, seq: u32) {
+                self.highest_received_seq = Some(match self.highest_received_seq {
+                    None => seq,
+                    Some(h) if seq_after(seq, h) => seq,
+                    Some(h) => h,
+                });
+            }
+
+            fn apply_send(&mut self, seq: u32, timeout_at: Instant) {
+                assert_eq!(
+                    seq, self.next_wire_seq,
+                    "model/machine wire sequence desync"
+                );
+                self.pending.push_back((seq, timeout_at));
+                self.next_wire_seq = self.next_wire_seq.wrapping_add(1);
+                self.packets_sent += 1;
+            }
+
+            fn apply_poll(&mut self, now: Instant, limit: usize) -> (Vec<u32>, bool) {
+                let mut expired = Vec::new();
+                while expired.len() < limit {
+                    let Some(&(seq, timeout_at)) = self.pending.front() else {
+                        break;
+                    };
+                    if timeout_at > now {
+                        break;
+                    }
+                    self.pending.pop_front();
+                    self.timed_out.insert(seq);
+                    expired.push(seq);
+                }
+                let more_due = self
+                    .pending
+                    .front()
+                    .is_some_and(|&(_, timeout_at)| timeout_at <= now);
+                (expired, more_due)
+            }
+
+            /// Mirrors `SessionMachine::process_echo_reply`'s classification
+            /// exactly (see that function's branches), mutating this model
+            /// the same way. Returns the event kinds a correct
+            /// implementation must produce, in order.
+            fn reply(&mut self, seq: u32, wrong_token: bool, close: bool) -> Vec<ExpectedEvent> {
+                if wrong_token {
+                    // A wrong-token reply is rejected before the close flag
+                    // is ever inspected, so `close` has no effect here.
+                    return vec![ExpectedEvent::WarnWrongToken];
+                }
+                let mut events = Vec::new();
+                if self.pending_remove(seq) {
+                    let is_late = self
+                        .highest_received_seq
+                        .is_some_and(|h| seq_before(seq, h));
+                    self.update_highest(seq);
+                    self.completed.insert(seq);
+                    events.push(if is_late {
+                        ExpectedEvent::LateReply(seq)
+                    } else {
+                        ExpectedEvent::EchoReply(seq)
+                    });
+                } else if self.completed.contains(&seq) {
+                    self.update_highest(seq);
+                    events.push(ExpectedEvent::DuplicateReply(seq));
+                } else if self.timed_out.remove(&seq) {
+                    self.update_highest(seq);
+                    self.completed.insert(seq);
+                    events.push(ExpectedEvent::LateReply(seq));
+                } else if self
+                    .highest_received_seq
+                    .is_some_and(|h| seq_before(seq, h))
+                {
+                    events.push(ExpectedEvent::LateReply(seq));
+                } else {
+                    events.push(ExpectedEvent::WarnUntracked);
+                }
+                if close {
+                    self.state = ModelState::ClosedPeer;
+                    events.push(ExpectedEvent::SessionClosed);
+                }
+                events
+            }
+        }
+
+        fn classify_real(events: &[ClientEvent]) -> Vec<ExpectedEvent> {
+            events
+                .iter()
+                .map(|event| match event {
+                    ClientEvent::EchoReply { seq, .. } => ExpectedEvent::EchoReply(*seq),
+                    ClientEvent::LateReply { seq, .. } => ExpectedEvent::LateReply(*seq),
+                    ClientEvent::DuplicateReply { seq, .. } => ExpectedEvent::DuplicateReply(*seq),
+                    ClientEvent::Warning {
+                        kind: WarningKind::WrongToken,
+                        ..
+                    } => ExpectedEvent::WarnWrongToken,
+                    ClientEvent::Warning {
+                        kind: WarningKind::UntrackedReply,
+                        ..
+                    } => ExpectedEvent::WarnUntracked,
+                    ClientEvent::SessionClosed { .. } => ExpectedEvent::SessionClosed,
+                    other => panic!("unexpected event from an open session: {other:?}"),
+                })
+                .collect()
+        }
+
+        fn is_already_closed<T: std::fmt::Debug>(result: &Result<T, ClientError>) -> bool {
+            matches!(result, Err(ClientError::AlreadyClosed))
+        }
+
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        struct Observable {
+            is_open: bool,
+            is_terminal: bool,
+            is_peer_closed: bool,
+            packets_sent: u64,
+            pending_is_empty: bool,
+        }
+
+        fn observe(machine: &SessionMachine) -> Observable {
+            Observable {
+                is_open: machine.is_open(),
+                is_terminal: machine.is_terminal(),
+                is_peer_closed: machine.is_peer_closed(),
+                packets_sent: machine.packets_sent(),
+                pending_is_empty: machine.pending_is_empty(),
+            }
+        }
+
+        fn check_generic_invariants(
+            machine: &SessionMachine,
+            model: &Model,
+        ) -> Result<(), TestCaseError> {
+            prop_assert_eq!(machine.is_open(), model.state == ModelState::Open);
+            prop_assert_eq!(
+                machine.is_terminal(),
+                matches!(
+                    model.state,
+                    ModelState::ClosedLocal | ModelState::ClosedPeer
+                )
+            );
+            prop_assert_eq!(
+                machine.is_peer_closed(),
+                model.state == ModelState::ClosedPeer
+            );
+            prop_assert_eq!(machine.packets_sent(), model.packets_sent);
+            if model.state == ModelState::Open {
+                prop_assert_eq!(machine.pending_is_empty(), model.pending.is_empty());
+            } else {
+                prop_assert!(machine.pending_is_empty());
+            }
+            Ok(())
+        }
+
+        /// Drives the full real send transaction: prepare, preflight,
+        /// finalize, commit. Mirrors how `Client`/`AsyncClient` drive
+        /// `SessionMachine` around a real socket send, using `now` for both
+        /// the pre-send anchor and the post-send `sent_at` sample since no
+        /// real send elapses time here.
+        fn do_send(
+            machine: &mut SessionMachine,
+            now: ClientTimestamp,
+        ) -> Result<ProbeSent, ClientError> {
+            let prepared = machine
+                .prepare_probe()?
+                .expect("prepare_probe always returns Some when Ok");
+            let preflight = machine.preflight_probe_commit(&prepared)?;
+            let commit = machine.finalize_probe_commit(preflight, now)?;
+            let bytes = prepared.bytes.len();
+            Ok(machine.commit_probe_sent(commit, now, bytes))
+        }
+
+        #[derive(Debug, Clone, Copy)]
+        enum ReplyTarget {
+            Pending(u32),
+            TimedOut(u32),
+            Completed(u32),
+            Unknown(u32),
+        }
+
+        #[derive(Debug, Clone, Copy)]
+        enum Op {
+            Send,
+            StaleProbe,
+            PrepareAbandon,
+            Reply {
+                target: ReplyTarget,
+                wrong_token: bool,
+                close: bool,
+            },
+            PollTimeouts,
+            PollTimeoutsBounded(u8),
+            AdvanceClock(u16),
+            LocalClose,
+            ReopenAttempt,
+        }
+
+        fn op_strategy() -> impl Strategy<Value = Op> {
+            let reply_target = prop_oneof![
+                any::<u32>().prop_map(ReplyTarget::Pending),
+                any::<u32>().prop_map(ReplyTarget::TimedOut),
+                any::<u32>().prop_map(ReplyTarget::Completed),
+                any::<u32>().prop_map(ReplyTarget::Unknown),
+            ];
+            prop_oneof![
+                4 => Just(Op::Send),
+                1 => Just(Op::StaleProbe),
+                1 => Just(Op::PrepareAbandon),
+                5 => (reply_target, any::<bool>(), any::<bool>()).prop_map(
+                    |(target, wrong_token, close)| Op::Reply {
+                        target,
+                        wrong_token,
+                        close,
+                    }
+                ),
+                2 => Just(Op::PollTimeouts),
+                1 => (0u8..=6).prop_map(Op::PollTimeoutsBounded),
+                4 => (0u16..=120).prop_map(Op::AdvanceClock),
+                1 => Just(Op::LocalClose),
+                1 => Just(Op::ReopenAttempt),
+            ]
+        }
+
+        /// Biased toward `0` (the common case) and toward the last few
+        /// values before `u32::MAX` (so a handful of sends from here cross
+        /// the wraparound boundary), with a uniformly random third case for
+        /// general coverage.
+        fn start_seq_strategy() -> impl Strategy<Value = u32> {
+            prop_oneof![
+                2 => Just(0u32),
+                3 => (u32::MAX - 4)..=u32::MAX,
+                2 => any::<u32>(),
+            ]
+        }
+
+        fn apply_op(
+            machine: &mut SessionMachine,
+            model: &mut Model,
+            params: &Params,
+            now: &mut ClientTimestamp,
+            op: Op,
+        ) -> Result<(), TestCaseError> {
+            match op {
+                Op::Send => {
+                    let result = do_send(machine, *now);
+                    match model.state {
+                        ModelState::Open => {
+                            let sent = result.expect(
+                                "open session send should succeed within chosen capacity bounds",
+                            );
+                            prop_assert_eq!(sent.seq, model.next_wire_seq);
+                            let timeout_at = now
+                                .mono
+                                .checked_add(PROBE_TIMEOUT)
+                                .expect("no overflow at test timescales");
+                            model.apply_send(sent.seq, timeout_at);
+                        }
+                        _ => prop_assert!(
+                            is_already_closed(&result),
+                            "expected AlreadyClosed, got {:?}",
+                            result
+                        ),
+                    }
+                }
+                Op::StaleProbe => {
+                    if model.state != ModelState::Open {
+                        let result = machine.prepare_probe();
+                        prop_assert!(
+                            is_already_closed(&result),
+                            "expected AlreadyClosed, got {:?}",
+                            result
+                        );
+                    } else {
+                        let prepared_a = machine
+                            .prepare_probe()
+                            .unwrap()
+                            .expect("open session prepares probes");
+                        prop_assert_eq!(prepared_a.seq, model.next_wire_seq);
+
+                        let sent = do_send(machine, *now).expect(
+                            "intervening send should succeed within chosen capacity bounds",
+                        );
+                        prop_assert_eq!(sent.seq, prepared_a.seq);
+                        let timeout_at = now
+                            .mono
+                            .checked_add(PROBE_TIMEOUT)
+                            .expect("no overflow at test timescales");
+                        model.apply_send(sent.seq, timeout_at);
+
+                        match machine.preflight_probe_commit(&prepared_a) {
+                            Err(ClientError::StalePreparedProbe {
+                                prepared_seq,
+                                next_wire_seq,
+                            }) => {
+                                prop_assert_eq!(prepared_seq, prepared_a.seq);
+                                prop_assert_eq!(next_wire_seq, model.next_wire_seq);
+                            }
+                            other => {
+                                prop_assert!(false, "expected StalePreparedProbe, got {:?}", other)
+                            }
+                        }
+                    }
+                }
+                Op::PrepareAbandon => {
+                    let before = observe(machine);
+                    let result = machine.prepare_probe();
+                    match model.state {
+                        ModelState::Open => {
+                            let prepared = result.unwrap().expect("open session prepares probes");
+                            prop_assert_eq!(prepared.seq, model.next_wire_seq);
+                            prop_assert!(!prepared.bytes.is_empty());
+                        }
+                        _ => prop_assert!(
+                            is_already_closed(&result),
+                            "expected AlreadyClosed, got {:?}",
+                            result
+                        ),
+                    }
+                    prop_assert_eq!(observe(machine), before);
+                }
+                Op::Reply {
+                    target,
+                    wrong_token,
+                    close,
+                } => {
+                    let seq = model.resolve(target);
+                    let token = if wrong_token { WRONG_TOKEN } else { TOKEN };
+                    let packet = build_echo_reply(params, token, seq, close);
+                    let result =
+                        machine.process_received_echo_packet(&packet, *now, ReceiveMeta::default());
+                    match model.state {
+                        ModelState::Open => {
+                            let events = result.expect("open session processes echo packets");
+                            let expected = model.reply(seq, wrong_token, close);
+                            prop_assert_eq!(classify_real(&events), expected);
+                        }
+                        _ => prop_assert!(
+                            is_already_closed(&result),
+                            "expected AlreadyClosed, got {:?}",
+                            result
+                        ),
+                    }
+                }
+                Op::PollTimeouts => {
+                    let result = machine.poll_timeouts_at(now.mono);
+                    match model.state {
+                        ModelState::Open => {
+                            let events = result.expect("open session polls succeed");
+                            let (expired, _more_due) = model.apply_poll(now.mono, usize::MAX);
+                            let real: Vec<u32> = events
+                                .iter()
+                                .map(|event| match event {
+                                    ClientEvent::EchoLoss { seq, .. } => *seq,
+                                    other => {
+                                        panic!("unexpected event from poll_timeouts_at: {other:?}")
+                                    }
+                                })
+                                .collect();
+                            prop_assert_eq!(real, expired);
+                        }
+                        _ => prop_assert!(
+                            is_already_closed(&result),
+                            "expected AlreadyClosed, got {:?}",
+                            result
+                        ),
+                    }
+                }
+                Op::PollTimeoutsBounded(limit) => {
+                    let result = machine.poll_timeouts_bounded_at(now.mono, limit as usize);
+                    match model.state {
+                        ModelState::Open => {
+                            let batch = result.expect("open session polls succeed");
+                            let (expired, more_due) = model.apply_poll(now.mono, limit as usize);
+                            let real: Vec<u32> = batch
+                                .events
+                                .iter()
+                                .map(|event| match event {
+                                    ClientEvent::EchoLoss { seq, .. } => *seq,
+                                    other => panic!(
+                                        "unexpected event from poll_timeouts_bounded_at: {other:?}"
+                                    ),
+                                })
+                                .collect();
+                            prop_assert_eq!(real, expired);
+                            prop_assert_eq!(batch.more_due, more_due);
+                        }
+                        _ => prop_assert!(
+                            is_already_closed(&result),
+                            "expected AlreadyClosed, got {:?}",
+                            result
+                        ),
+                    }
+                }
+                Op::AdvanceClock(millis) => {
+                    let delta = Duration::from_millis(u64::from(millis));
+                    now.mono += delta;
+                    now.wall += delta;
+                }
+                Op::LocalClose => match model.state {
+                    ModelState::Open => {
+                        let PreparedClose { commit, .. } = machine
+                            .prepare_close()
+                            .expect("open session can prepare close");
+                        let event = machine.commit_local_close(commit, *now);
+                        let is_session_closed = matches!(event, ClientEvent::SessionClosed { .. });
+                        prop_assert!(is_session_closed);
+                        model.state = ModelState::ClosedLocal;
+                    }
+                    _ => {
+                        let result = machine.prepare_close();
+                        prop_assert!(
+                            is_already_closed(&result),
+                            "expected AlreadyClosed, got {:?}",
+                            result
+                        );
+                    }
+                },
+                Op::ReopenAttempt => {
+                    let before = observe(machine);
+                    let result = machine.prepare_open_request();
+                    match model.state {
+                        ModelState::Open => {
+                            prop_assert!(matches!(result, Err(ClientError::AlreadyOpen)));
+                        }
+                        ModelState::ClosedLocal | ModelState::ClosedPeer => {
+                            prop_assert!(is_already_closed(&result));
+                        }
+                    }
+                    prop_assert_eq!(observe(machine), before);
+                }
+            }
+            check_generic_invariants(machine, model)
+        }
+
+        proptest! {
+            #![proptest_config(ProptestConfig::with_cases(CASES))]
+
+            /// Drives a generated sequence of operations through both a real,
+            /// already-`Open` `SessionMachine` and an independent reference
+            /// [`Model`], asserting after every operation that the observable
+            /// state (open/terminal/peer-closed/packets-sent/pending-empty)
+            /// matches, every error returned matches the model's
+            /// expectation, and every event/classification produced for a
+            /// probe send, a reply, or a timeout poll matches the model's
+            /// prediction. No operation should ever panic.
+            #[test]
+            fn open_session_matches_reference_model(
+                start_seq in start_seq_strategy(),
+                ops in proptest::collection::vec(op_strategy(), 1..=OP_LIMIT),
+            ) {
+                let (mut machine, params) = open_machine_for_model(start_seq);
+                let mut model = Model::new(start_seq);
+                let mut now = ClientTimestamp {
+                    mono: Instant::now(),
+                    wall: SystemTime::now(),
+                };
+
+                check_generic_invariants(&machine, &model)?;
+                for op in ops {
+                    apply_op(&mut machine, &mut model, &params, &mut now, op)?;
+                }
+            }
+        }
+    }
 }

crates/irtt-proto/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "irtt-proto"
-version = "0.5.0"
+version = "0.5.1"
 description = "IRTT protocol encoding and decoding primitives"
 edition.workspace = true
 license.workspace = true
 rust-version.workspace = true
 repository.workspace = true
 homepage.workspace = true
-readme.workspace = true
+readme = "README.md"
 keywords = ["irtt", "networking", "latency", "protocol"]
 categories = ["network-programming"]
 
@@ -16,3 +16,6 @@ hmac = "0.13"
 md-5 = "0.11"
 subtle = "2.6.1"
 thiserror = "2.0.20"
+
+[dev-dependencies]
+proptest = "1.11.0"

crates/irtt-proto/README.md

@@ -0,0 +1,30 @@
+# irtt-proto
+
+Low-level wire encoding and decoding for the IRTT-compatible protocol: request
+and reply structs, flags, negotiable parameters, varint/zigzag primitives, and
+HMAC-MD5 packet authentication. No sockets, no runtime, no session state.
+
+## Who should use this
+
+Most applications should not depend on this crate directly. Use
+[`irtt-client`](https://docs.rs/irtt-client) to run client sessions or
+[`irtt-server`](https://docs.rs/irtt-server) to run a server; both build on
+`irtt-proto` and provide session lifecycle, negotiation, and validated
+configuration on top of it.
+
+Reach for `irtt-proto` directly only if you are implementing another
+IRTT-compatible client or server from scratch and need the raw packet layer.
+
+Field values mirror the wire format closely rather than expressing policy:
+`Params::decode` rejects malformed input, but direct construction plus
+`Params::encode` performs no additional validation — callers are responsible
+for validating values before sending them.
+
+## Documentation
+
+Full API documentation is on [docs.rs/irtt-proto](https://docs.rs/irtt-proto).
+
+## Project
+
+Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
+implementation of an IRTT-compatible protocol stack.

crates/irtt-proto/src/echo.rs

@@ -60,6 +60,50 @@ pub struct TimestampFields {
     pub send_mono: Option<i64>,
 }
 
+/// Encodes an ECHO reply.
+///
+/// `params` supplies the negotiated layout and length, exactly as on the
+/// request side, and every optional field the layout requires must be present
+/// in `reply`: a `Some` where the layout has no field, or a `None` where it has
+/// one, is an error. `hmac_key` is authoritative: `Some(key)` sets `FLAG_HMAC`
+/// and signs the finished datagram.
+///
+/// # Errors
+///
+/// Returns [`ProtoError::MissingFlag`] or [`ProtoError::UnexpectedFlag`] when
+/// the reply does not carry exactly the packet-type flags this encoder
+/// requires, [`ProtoError::MissingField`] or [`ProtoError::UnexpectedField`]
+/// when `reply`'s optional fields do not match the negotiated layout, and
+/// [`ProtoError::PayloadTooLarge`] when the payload does not fit the negotiated
+/// length.
+///
+/// # Example
+///
+/// ```
+/// use irtt_proto::{
+///     decode_echo_reply, encode_echo_reply, EchoReply, Params, ReceivedStats,
+///     TimestampFields, FLAG_REPLY,
+/// };
+///
+/// // `received_stats` negotiates a receive counter; four payload bytes.
+/// let params = Params {
+///     length: 24,
+///     received_stats: ReceivedStats::Count,
+///     ..Params::default()
+/// };
+/// let reply = EchoReply {
+///     flags: FLAG_REPLY,
+///     token: 0x1234_5678_9abc_def0,
+///     sequence: 7,
+///     recv_count: Some(3),
+///     recv_window: None,
+///     timestamps: TimestampFields::default(),
+///     payload: vec![1, 2, 3, 4],
+/// };
+///
+/// let packet = encode_echo_reply(&reply, &params, None).unwrap();
+/// assert_eq!(decode_echo_reply(&packet, &params, None).unwrap(), reply);
+/// ```
 pub fn encode_echo_reply(
     reply: &EchoReply,
     params: &Params,

crates/irtt-proto/src/hmac.rs

@@ -68,6 +68,23 @@ pub fn verify_hmac(key: &[u8], packet: &[u8], hmac_offset: usize) -> Result<()>
 /// [`ProtoError::InvalidHmacOffset`] when the field is truncated, and
 /// [`ProtoError::BadHmac`] when the MAC does not match. The packet is never
 /// modified.
+///
+/// # Example
+///
+/// ```
+/// use irtt_proto::{encode_request, verify_packet_hmac, Params, RequestToEncode};
+///
+/// // Synthetic example key — use a real shared secret in production.
+/// let key = b"example key";
+/// let params = Params::with_protocol_defaults();
+/// let packet = encode_request(
+///     RequestToEncode::Open { params: &params, no_test: false },
+///     Some(key),
+/// ).unwrap();
+///
+/// verify_packet_hmac(key, &packet).unwrap();
+/// assert!(verify_packet_hmac(b"wrong key", &packet).is_err());
+/// ```
 pub fn verify_packet_hmac(key: &[u8], packet: &[u8]) -> Result<()> {
     let envelope = envelope::decode_structural(packet)?;
     if !envelope.hmac_present {

crates/irtt-proto/src/layout.rs

@@ -135,6 +135,20 @@ pub fn echo_header_len(hmac: bool, params: &Params) -> usize {
 /// A ceiling on what a negotiated length may legitimately *be* — an MTU, a
 /// resource bound, a maximum packet size — is deliberately not here. That is
 /// server and runtime policy, and it belongs where the negotiation happens.
+///
+/// # Example
+///
+/// ```
+/// use irtt_proto::{echo_packet_len, Params};
+///
+/// // The default layout's mandatory field block is 16 bytes (header, token,
+/// // sequence), so a smaller requested length is floored up to it.
+/// assert_eq!(echo_packet_len(false, &Params::default()).unwrap(), 16);
+/// assert_eq!(
+///     echo_packet_len(false, &Params { length: 40, ..Params::default() }).unwrap(),
+///     40,
+/// );
+/// ```
 pub fn echo_packet_len(hmac: bool, params: &Params) -> Result<usize> {
     let header_len = echo_header_len(hmac, params);
     let requested = if params.length <= 0 {

crates/irtt-proto/src/lib.rs

@@ -6,6 +6,10 @@
 //! 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`]
@@ -38,6 +42,39 @@
 //! 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();
+//! ```
+//!
 #![forbid(unsafe_code)]
 
 pub mod echo;

crates/irtt-proto/src/open.rs

@@ -13,6 +13,34 @@ pub struct OpenReply {
     pub params: Params,
 }
 
+/// Encodes an open reply.
+///
+/// `hmac_key` is authoritative: `Some(key)` sets `FLAG_HMAC` and signs the
+/// finished datagram, while `None` produces an unauthenticated reply and clears
+/// any caller-supplied `FLAG_HMAC`. A zero token is rejected unless the reply
+/// also carries `FLAG_CLOSE` (a rejected open).
+///
+/// # Errors
+///
+/// Returns [`ProtoError::MissingFlag`] when the reply lacks `FLAG_OPEN` or
+/// `FLAG_REPLY`, and [`ProtoError::ZeroToken`] for a zero token without
+/// `FLAG_CLOSE`.
+///
+/// # Example
+///
+/// ```
+/// use irtt_proto::{
+///     decode_open_reply, encode_open_reply, OpenReply, Params, FLAG_OPEN, FLAG_REPLY,
+/// };
+///
+/// let reply = OpenReply {
+///     flags: FLAG_OPEN | FLAG_REPLY,
+///     token: 0x1234_5678_9abc_def0,
+///     params: Params::with_protocol_defaults(),
+/// };
+/// let packet = encode_open_reply(&reply, None).unwrap();
+/// assert_eq!(decode_open_reply(&packet, None).unwrap(), reply);
+/// ```
 pub fn encode_open_reply(reply: &OpenReply, hmac_key: Option<&[u8]>) -> Result<Vec<u8>> {
     let params = reply.params.encode();
     let mut out = envelope::begin_checked(
@@ -30,6 +58,18 @@ pub fn encode_open_reply(reply: &OpenReply, hmac_key: Option<&[u8]>) -> Result<V
     envelope::finish(out, hmac_key)
 }
 
+/// Decodes an open reply.
+///
+/// Requires `FLAG_OPEN` and `FLAG_REPLY`, and — when `hmac_key` is supplied —
+/// verifies the authentication field. The decoded [`Params`] are validated:
+/// malformed or incompatible parameter values are rejected here.
+///
+/// # Errors
+///
+/// Returns [`ProtoError::MissingFlag`], [`ProtoError::HmacPresenceMismatch`],
+/// [`ProtoError::BadHmac`], [`ProtoError::PacketTooShort`],
+/// [`ProtoError::ZeroToken`], or a parameter decode error. See
+/// [`encode_open_reply`] for a round-trip example.
 pub fn decode_open_reply(packet: &[u8], hmac_key: Option<&[u8]>) -> Result<OpenReply> {
     let envelope = envelope::decode(
         packet,

crates/irtt-proto/src/params.rs

@@ -16,6 +16,29 @@ pub const MAX_SERVER_FILL_BYTES: usize = 32;
 /// [`clock`](Params::clock) is [`Clock::Unspecified`], which is what an open
 /// request with an empty parameter payload means. It is not a set of sensible
 /// client settings; a client builds its request from its own configuration.
+///
+/// # Example
+///
+/// Construct a `Params`, encode it, and decode it back:
+///
+/// ```
+/// use irtt_proto::{Clock, Params, ReceivedStats, ServerFill, StampAt};
+///
+/// let params = Params {
+///     protocol_version: 1,
+///     duration_ns: 3_000_000_000,
+///     interval_ns: 1_000_000_000,
+///     length: 1472,
+///     received_stats: ReceivedStats::Both,
+///     stamp_at: StampAt::Both,
+///     clock: Clock::Both,
+///     server_fill: Some(ServerFill { value: "rand".to_owned() }),
+///     ..Params::default()
+/// };
+///
+/// let encoded = params.encode();
+/// assert_eq!(Params::decode(&encoded).unwrap(), params);
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct Params {
     pub protocol_version: i64,
@@ -88,6 +111,20 @@ impl Params {
     /// Presence means the tag appeared at least once. Repeated known tags keep
     /// last-value-wins, and unknown tags remain ignored and untracked.
     ///
+    /// # Example
+    ///
+    /// ```
+    /// use irtt_proto::Params;
+    ///
+    /// // Wire bytes: tag 2 (duration) carrying an explicit zero. Interval
+    /// // (tag 3) is absent, so both fields decode to zero but only one is
+    /// // reported present.
+    /// let decoded = Params::decode_with_presence(&[0x02, 0x00]).unwrap();
+    /// assert_eq!(decoded.params.duration_ns, 0);
+    /// assert!(decoded.presence.duration_ns);
+    /// assert!(!decoded.presence.interval_ns);
+    /// ```
+    ///
     /// [`decode`]: Params::decode
     pub fn decode_with_presence(input: &[u8]) -> Result<DecodedParams> {
         let mut params = Self::default();
@@ -764,4 +801,340 @@ mod tests {
         let encoded = [99];
         assert_eq!(Params::decode(&encoded), Err(ProtoError::TruncatedVarint));
     }
+
+    mod properties {
+        use super::*;
+        use proptest::prelude::*;
+
+        fn received_stats_strategy() -> impl Strategy<Value = ReceivedStats> {
+            prop_oneof![
+                Just(ReceivedStats::None),
+                Just(ReceivedStats::Count),
+                Just(ReceivedStats::Window),
+                Just(ReceivedStats::Both),
+            ]
+        }
+
+        fn stamp_at_strategy() -> impl Strategy<Value = StampAt> {
+            prop_oneof![
+                Just(StampAt::None),
+                Just(StampAt::Send),
+                Just(StampAt::Receive),
+                Just(StampAt::Both),
+                Just(StampAt::Midpoint),
+            ]
+        }
+
+        /// A `Clock` valid for direct construction, including `Unspecified`
+        /// (wire omission). Never produces an explicit zero on the wire; see
+        /// `explicit_clock_strategy` for that.
+        fn clock_strategy() -> impl Strategy<Value = Clock> {
+            prop_oneof![
+                Just(Clock::Unspecified),
+                Just(Clock::Wall),
+                Just(Clock::Monotonic),
+                Just(Clock::Both),
+            ]
+        }
+
+        /// A `Clock` value valid to encode *explicitly* on the wire (tag 7).
+        /// Excludes `Unspecified`/zero, which is only ever reached by omission.
+        fn explicit_clock_value_strategy() -> impl Strategy<Value = i64> {
+            1_i64..=3
+        }
+
+        fn server_fill_strategy() -> impl Strategy<Value = Option<ServerFill>> {
+            prop_oneof![
+                Just(None),
+                proptest::collection::vec(proptest::char::any(), 0..=8).prop_map(|chars| Some(
+                    ServerFill {
+                        value: chars.into_iter().collect(),
+                    }
+                )),
+            ]
+        }
+
+        fn params_strategy() -> impl Strategy<Value = Params> {
+            (
+                any::<i64>(),
+                any::<i64>(),
+                any::<i64>(),
+                any::<i64>(),
+                any::<i64>(),
+                received_stats_strategy(),
+                stamp_at_strategy(),
+                clock_strategy(),
+                server_fill_strategy(),
+            )
+                .prop_map(
+                    |(
+                        protocol_version,
+                        duration_ns,
+                        interval_ns,
+                        length,
+                        dscp,
+                        received_stats,
+                        stamp_at,
+                        clock,
+                        server_fill,
+                    )| Params {
+                        protocol_version,
+                        duration_ns,
+                        interval_ns,
+                        length,
+                        received_stats,
+                        stamp_at,
+                        clock,
+                        dscp,
+                        server_fill,
+                    },
+                )
+        }
+
+        fn encode_tagged_int(tag: u64, value: i64, out: &mut Vec<u8>) {
+            varint::encode_uvarint(tag, out);
+            varint::encode_varint(value, out);
+        }
+
+        fn encode_tagged_server_fill(value: &str, out: &mut Vec<u8>) {
+            varint::encode_uvarint(9, out);
+            varint::encode_uvarint(value.len() as u64, out);
+            out.extend_from_slice(value.as_bytes());
+        }
+
+        proptest! {
+            #[test]
+            fn valid_params_round_trip(params in params_strategy()) {
+                let encoded = params.encode();
+                let decoded = Params::decode(&encoded).unwrap();
+                prop_assert_eq!(decoded, params);
+            }
+
+            #[test]
+            fn encoded_param_presence_matches_omission_rules(params in params_strategy()) {
+                let encoded = params.encode();
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(&decoded.params, &params);
+
+                prop_assert_eq!(decoded.presence.protocol_version, params.protocol_version != 0);
+                prop_assert_eq!(decoded.presence.duration_ns, params.duration_ns != 0);
+                prop_assert_eq!(decoded.presence.interval_ns, params.interval_ns != 0);
+                prop_assert_eq!(decoded.presence.length, params.length != 0);
+                prop_assert_eq!(decoded.presence.dscp, params.dscp != 0);
+                prop_assert_eq!(
+                    decoded.presence.received_stats,
+                    params.received_stats != ReceivedStats::None
+                );
+                prop_assert_eq!(decoded.presence.stamp_at, params.stamp_at != StampAt::None);
+                prop_assert_eq!(decoded.presence.clock, params.clock != Clock::Unspecified);
+                prop_assert_eq!(decoded.presence.server_fill, params.server_fill.is_some());
+            }
+
+            #[test]
+            fn repeated_protocol_version_is_last_wins(first: i64, second: i64) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(1, first, &mut encoded);
+                encode_tagged_int(1, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.protocol_version, second);
+                prop_assert!(decoded.presence.protocol_version);
+            }
+
+            #[test]
+            fn repeated_duration_ns_is_last_wins(first: i64, second: i64) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(2, first, &mut encoded);
+                encode_tagged_int(2, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.duration_ns, second);
+                prop_assert!(decoded.presence.duration_ns);
+            }
+
+            #[test]
+            fn repeated_interval_ns_is_last_wins(first: i64, second: i64) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(3, first, &mut encoded);
+                encode_tagged_int(3, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.interval_ns, second);
+                prop_assert!(decoded.presence.interval_ns);
+            }
+
+            #[test]
+            fn repeated_length_is_last_wins(first: i64, second: i64) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(4, first, &mut encoded);
+                encode_tagged_int(4, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.length, second);
+                prop_assert!(decoded.presence.length);
+            }
+
+            #[test]
+            fn repeated_received_stats_is_last_wins(first in 0_i64..=3, second in 0_i64..=3) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(5, first, &mut encoded);
+                encode_tagged_int(5, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.received_stats, ReceivedStats::try_from(second).unwrap());
+                prop_assert!(decoded.presence.received_stats);
+            }
+
+            #[test]
+            fn repeated_stamp_at_is_last_wins(first in 0_i64..=4, second in 0_i64..=4) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(6, first, &mut encoded);
+                encode_tagged_int(6, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.stamp_at, StampAt::try_from(second).unwrap());
+                prop_assert!(decoded.presence.stamp_at);
+            }
+
+            #[test]
+            fn repeated_clock_is_last_wins(
+                first in explicit_clock_value_strategy(),
+                second in explicit_clock_value_strategy(),
+            ) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(7, first, &mut encoded);
+                encode_tagged_int(7, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.clock, Clock::try_from(second).unwrap());
+                prop_assert!(decoded.presence.clock);
+            }
+
+            #[test]
+            fn repeated_dscp_is_last_wins(first: i64, second: i64) {
+                let mut encoded = Vec::new();
+                encode_tagged_int(8, first, &mut encoded);
+                encode_tagged_int(8, second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(decoded.params.dscp, second);
+                prop_assert!(decoded.presence.dscp);
+            }
+
+            #[test]
+            fn repeated_server_fill_is_last_wins(
+                first in proptest::collection::vec(proptest::char::any(), 0..=8)
+                    .prop_map(|chars| chars.into_iter().collect::<String>()),
+                second in proptest::collection::vec(proptest::char::any(), 0..=8)
+                    .prop_map(|chars| chars.into_iter().collect::<String>()),
+            ) {
+                let mut encoded = Vec::new();
+                encode_tagged_server_fill(&first, &mut encoded);
+                encode_tagged_server_fill(&second, &mut encoded);
+                let decoded = Params::decode_with_presence(&encoded).unwrap();
+                prop_assert_eq!(
+                    decoded.params.server_fill,
+                    Some(ServerFill { value: second })
+                );
+                prop_assert!(decoded.presence.server_fill);
+            }
+
+            #[test]
+            fn unknown_scalar_tag_prefix_does_not_disturb_known_params(
+                params in params_strategy(),
+                unknown_tag in 10_u64..=u16::MAX as u64,
+                unknown_value: u64,
+            ) {
+                let mut prefixed = Vec::new();
+                varint::encode_uvarint(unknown_tag, &mut prefixed);
+                varint::encode_uvarint(unknown_value, &mut prefixed);
+                prefixed.extend_from_slice(&params.encode());
+
+                let decoded = Params::decode(&prefixed).unwrap();
+                prop_assert_eq!(decoded, params.clone());
+
+                let decoded_with_presence = Params::decode_with_presence(&prefixed).unwrap();
+                let expected_presence = Params::decode_with_presence(&params.encode()).unwrap().presence;
+                prop_assert_eq!(decoded_with_presence.presence, expected_presence);
+            }
+
+            #[test]
+            fn unknown_scalar_tag_suffix_does_not_disturb_known_params(
+                params in params_strategy(),
+                unknown_tag in 10_u64..=u16::MAX as u64,
+                unknown_value: u64,
+            ) {
+                let mut suffixed = params.encode();
+                varint::encode_uvarint(unknown_tag, &mut suffixed);
+                varint::encode_uvarint(unknown_value, &mut suffixed);
+
+                let decoded = Params::decode(&suffixed).unwrap();
+                prop_assert_eq!(decoded, params.clone());
+
+                let decoded_with_presence = Params::decode_with_presence(&suffixed).unwrap();
+                let expected_presence = Params::decode_with_presence(&params.encode()).unwrap().presence;
+                prop_assert_eq!(decoded_with_presence.presence, expected_presence);
+            }
+        }
+
+        /// Omitted-vs-explicit-zero presence, for the fields where explicit
+        /// zero is valid on the wire. `Clock` is deliberately excluded: an
+        /// explicit zero there is rejected outright, not merely "present with
+        /// the default value" (see `explicit_clock_zero_is_rejected`).
+        #[test]
+        fn omitted_vs_explicit_zero_presence_for_zero_valid_fields() {
+            let scalar_tags = [1_u64, 2, 3, 4, 8];
+            for tag in scalar_tags {
+                let omitted = Params::decode_with_presence(&[]).unwrap();
+                let mut explicit_zero = Vec::new();
+                encode_tagged_int(tag, 0, &mut explicit_zero);
+                let explicit = Params::decode_with_presence(&explicit_zero).unwrap();
+
+                assert_eq!(omitted.params, explicit.params);
+                assert_eq!(explicit.params, Params::default());
+
+                let (omitted_presence, explicit_presence) = match tag {
+                    1 => (
+                        omitted.presence.protocol_version,
+                        explicit.presence.protocol_version,
+                    ),
+                    2 => (omitted.presence.duration_ns, explicit.presence.duration_ns),
+                    3 => (omitted.presence.interval_ns, explicit.presence.interval_ns),
+                    4 => (omitted.presence.length, explicit.presence.length),
+                    8 => (omitted.presence.dscp, explicit.presence.dscp),
+                    _ => unreachable!(),
+                };
+                assert!(!omitted_presence);
+                assert!(explicit_presence);
+            }
+
+            let enum_tags = [5_u64, 6];
+            for tag in enum_tags {
+                let omitted = Params::decode_with_presence(&[]).unwrap();
+                let mut explicit_zero = Vec::new();
+                encode_tagged_int(tag, 0, &mut explicit_zero);
+                let explicit = Params::decode_with_presence(&explicit_zero).unwrap();
+
+                assert_eq!(omitted.params, explicit.params);
+
+                let (omitted_presence, explicit_presence) = match tag {
+                    5 => (
+                        omitted.presence.received_stats,
+                        explicit.presence.received_stats,
+                    ),
+                    6 => (omitted.presence.stamp_at, explicit.presence.stamp_at),
+                    _ => unreachable!(),
+                };
+                assert!(!omitted_presence);
+                assert!(explicit_presence);
+            }
+
+            // `Clock` deliberately breaks the pattern above: explicit zero is
+            // rejected rather than accepted-but-present.
+            let omitted = Params::decode_with_presence(&[]).unwrap();
+            assert_eq!(omitted.params.clock, Clock::Unspecified);
+            assert!(!omitted.presence.clock);
+            let mut explicit_clock_zero = Vec::new();
+            encode_tagged_int(7, 0, &mut explicit_clock_zero);
+            assert_eq!(
+                Params::decode_with_presence(&explicit_clock_zero),
+                Err(ProtoError::InvalidEnum {
+                    name: "Clock",
+                    value: 0,
+                })
+            );
+        }
+    }
 }

crates/irtt-proto/src/request.rs

@@ -88,6 +88,26 @@ pub enum DecodedRequestKind<'a> {
 /// the negotiated length is positive and wider than `usize`. A *negative*
 /// negotiated length is not an error: see [`echo_packet_len`], which floors it
 /// at the mandatory field block.
+///
+/// # Example
+///
+/// ```
+/// use irtt_proto::{encode_request, Params, RequestToEncode};
+///
+/// // An unauthenticated ECHO probe. `params` supplies the negotiated length,
+/// // which reserves four payload bytes beyond the 16-byte echo header.
+/// let params = Params { length: 20, ..Params::default() };
+/// let packet = encode_request(
+///     RequestToEncode::Echo {
+///         token: 0x1234_5678_9abc_def0,
+///         sequence: 7,
+///         params: &params,
+///         payload: &[1, 2, 3, 4],
+///     },
+///     None,
+/// ).unwrap();
+/// assert_eq!(packet.len(), 20);
+/// ```
 pub fn encode_request(request: RequestToEncode<'_>, hmac_key: Option<&[u8]>) -> Result<Vec<u8>> {
     match request {
         RequestToEncode::Open { params, no_test } => encode_open(params, no_test, hmac_key),
@@ -138,6 +158,21 @@ pub fn encode_request(request: RequestToEncode<'_>, hmac_key: Option<&[u8]>) ->
 /// Returns [`ProtoError::PacketTooShort`], [`ProtoError::BadMagic`],
 /// [`ProtoError::ReservedFlags`], or [`ProtoError::UnexpectedFlag`] for
 /// `FLAG_REPLY`.
+///
+/// # Example
+///
+/// ```
+/// use irtt_proto::{decode_request, encode_request, DecodedRequestKind, RequestToEncode};
+///
+/// let packet = encode_request(
+///     RequestToEncode::Close { token: 0x1234_5678_9abc_def0 },
+///     None,
+/// ).unwrap();
+///
+/// let request = decode_request(&packet).unwrap();
+/// assert!(!request.hmac_present);
+/// assert_eq!(request.kind, DecodedRequestKind::Close { token: 0x1234_5678_9abc_def0 });
+/// ```
 pub fn decode_request(packet: &[u8]) -> Result<DecodedRequest<'_>> {
     let envelope = envelope::decode_structural(packet)?;
     if has(envelope.flags, FLAG_REPLY) {

crates/irtt-proto/src/varint.rs

@@ -1,3 +1,19 @@
+//! Variable-length integer encoding for IRTT wire values.
+//!
+//! Tags use an unsigned base-128 varint ([`encode_uvarint`]), and signed
+//! integers (such as parameter values) use the same encoding after a zigzag
+//! transform ([`encode_varint`]), which keeps small negative numbers compact.
+//!
+//! # Example
+//!
+//! ```
+//! use irtt_proto::varint::{decode_varint, encode_varint};
+//!
+//! let mut out = Vec::new();
+//! encode_varint(1_000_000_000, &mut out);
+//! assert_eq!(decode_varint(&out).unwrap(), (1_000_000_000, out.len()));
+//! ```
+
 use crate::{ProtoError, Result};
 
 pub fn encode_uvarint(mut value: u64, out: &mut Vec<u8>) {
@@ -112,4 +128,43 @@ mod tests {
         encode_uvarint(24, &mut tag);
         assert_eq!(tag, [0x18]);
     }
+
+    mod properties {
+        use super::*;
+        use proptest::prelude::*;
+
+        proptest! {
+            #[test]
+            fn uvarint_round_trips(value: u64) {
+                let mut encoded = Vec::new();
+                encode_uvarint(value, &mut encoded);
+                prop_assert!(!encoded.is_empty());
+                prop_assert!(encoded.len() <= 10);
+                let (decoded, used) = decode_uvarint(&encoded).unwrap();
+                prop_assert_eq!(decoded, value);
+                prop_assert_eq!(used, encoded.len());
+            }
+
+            #[test]
+            fn signed_varint_round_trips(value: i64) {
+                let mut encoded = Vec::new();
+                encode_varint(value, &mut encoded);
+                prop_assert!(!encoded.is_empty());
+                prop_assert!(encoded.len() <= 10);
+                let (decoded, used) = decode_varint(&encoded).unwrap();
+                prop_assert_eq!(decoded, value);
+                prop_assert_eq!(used, encoded.len());
+            }
+
+            #[test]
+            fn zigzag_round_trips_from_signed(value: i64) {
+                prop_assert_eq!(zigzag_decode(zigzag_encode(value)), value);
+            }
+
+            #[test]
+            fn zigzag_round_trips_from_unsigned(value: u64) {
+                prop_assert_eq!(zigzag_encode(zigzag_decode(value)), value);
+            }
+        }
+    }
 }

crates/irtt-server/AGENTS.md

@@ -500,13 +500,14 @@ session policy lives.
   unmarked reply into a *dropped* one, because an unappliable marking stops the
   send. Verify a platform before extending that list.
 - A genuinely dual-stack `[::]` listener still emits **unmarked** IPv4-mapped
-  replies, and this is known. It is not fixed by choosing the option per reply,
+  replies on Linux. When reply DSCP/traffic-class marking for IPv4 peers
-  for the macOS reason above, and it predates wildcard source selection. Leave it
+  matters, configure the normal same-port `[::]:PORT` plus `0.0.0.0:PORT`
-  until it is worth its own slice, and do not "fix" it by weakening the rule that
+  listener pair instead; `ServerSet` makes the IPv6 half IPv6-only for that
-  an unappliable marking stops the send. The crate forbids unsafe code;
+  pair. Do not force `IPV6_V6ONLY` on every lone IPv6 listener, and do not
-  there is no raw `setsockopt` and no `sendmsg`/`cmsg` machinery. Keep the
+  weaken the rule that an unappliable marking stops the send. The crate forbids
-  target lists identical to the pinned `socket2` version's own gates — check
+  unsafe code; there is no raw `setsockopt` and no `sendmsg`/`cmsg` machinery.
-  its source rather than copying another crate's older matrix.
+  Keep the target lists identical to the pinned `socket2` version's own gates
+  — check its source rather than copying another crate's older matrix.
 
 ## Rate, lifetime and server-initiated close
 

crates/irtt-server/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "irtt-server"
-version = "0.5.0"
+version = "0.5.3"
 description = "IRTT-compatible Rust server library"
 edition.workspace = true
 license.workspace = true
 rust-version.workspace = true
 repository.workspace = true
 homepage.workspace = true
-readme.workspace = true
+readme = "README.md"
 keywords = ["irtt", "networking", "latency", "server"]
 categories = ["network-programming"]
 
@@ -23,3 +23,13 @@ tokio = { version = "1.53.1", default-features = false, features = ["rt", "net",
 # source-selection path here; elsewhere a wildcard bind is refused.
 [target.'cfg(any(target_os = "linux", target_os = "macos", target_os = "freebsd"))'.dependencies]
 nix = { version = "0.31.3", default-features = false, features = ["net", "uio"] }
+
+[package.metadata.docs.rs]
+all-features = true
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+
+[[example]]
+name = "basic_server"
+
+[[example]]
+name = "multi_listener"

crates/irtt-server/README.md

@@ -0,0 +1,41 @@
+# irtt-server
+
+Reusable, Tokio-native library for running an IRTT-compatible UDP server:
+open negotiation, the bounded session table, echo processing, per-session
+rate limiting, idle and max-duration expiry, and reply construction.
+
+## Looking for the CLI?
+
+If you just want to run a server from the command line, use the
+[`irtt-rs`](https://crates.io/crates/irtt-rs) application package instead,
+which installs the `irtt-server` binary. This crate is the library that
+binary is built on.
+
+## Structure
+
+- `Server` — the one-listener primitive: one UDP socket, one deterministic
+  `ServerCore`, one sequential receive/reply loop.
+- `ServerSet` — supervises one or more `Server`s as a single service: binds
+  them all or none, runs each in its own task, and fans one shutdown out to
+  all of them.
+
+Unlike `irtt-client`, Tokio is not optional here — this crate is intentionally
+Tokio-native, with no blocking or alternate-runtime variant.
+
+A wildcard listener (`0.0.0.0` / `[::]`) recovers each request's local
+destination and replies from it, so a client on a second local address is
+answered from the address it actually contacted. That path is implemented
+for Linux, macOS, and FreeBSD; a wildcard bind is refused at construction on
+other targets rather than served incorrectly. Explicit-address listeners are
+unaffected everywhere.
+
+See `examples/` in the repository for runnable examples.
+
+## Documentation
+
+Full API documentation is on [docs.rs/irtt-server](https://docs.rs/irtt-server).
+
+## Project
+
+Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
+implementation of an IRTT-compatible protocol stack.

crates/irtt-server/examples/basic_server.rs

@@ -0,0 +1,42 @@
+//! Basic single-listener server example.
+//!
+//! Binds one [`Server`] on an ephemeral loopback port, serves it for a short
+//! fixed window, and shuts down. A real deployment would normally bind a
+//! fixed port and run until an external shutdown signal.
+//!
+//! Run with:
+//!
+//! ```text
+//! cargo run -p irtt-server --example basic_server
+//! ```
+
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::time::Duration;
+
+use irtt_server::{Server, ServerConfig};
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() {
+    let bind_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
+    let config = ServerConfig::default();
+
+    let mut server = match Server::bind(bind_addr, config).await {
+        Ok(server) => server,
+        Err(err) => {
+            eprintln!("failed to bind server: {err}");
+            return;
+        }
+    };
+
+    println!(
+        "listening on {}",
+        server
+            .local_addr()
+            .expect("bound socket has a local address")
+    );
+
+    let result = server.run(tokio::time::sleep(Duration::from_secs(2))).await;
+    if let Err(err) = result {
+        eprintln!("server stopped with an error: {err}");
+    }
+}

crates/irtt-server/examples/multi_listener.rs

@@ -0,0 +1,43 @@
+//! Multi-listener example using [`ServerSet`].
+//!
+//! `ServerSet` binds several independent [`Server`] listeners as one service:
+//! all-or-nothing bind, one shutdown fanned out to every listener, and the
+//! whole set fails if any listener does. Each listener still gets its own
+//! socket, session table, and tokens — a token issued by one is unknown at
+//! the other. This is what the `irtt-rs` server CLI always runs through, even
+//! for a single bind.
+//!
+//! Run with:
+//!
+//! ```text
+//! cargo run -p irtt-server --example multi_listener
+//! ```
+
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::time::Duration;
+
+use irtt_server::{ServerConfig, ServerSet};
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() {
+    let addrs = [
+        SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0),
+        SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0),
+    ];
+    let config = ServerConfig::default();
+
+    let set = match ServerSet::bind(addrs, config).await {
+        Ok(set) => set,
+        Err(err) => {
+            eprintln!("failed to bind listener set: {err}");
+            return;
+        }
+    };
+
+    println!("listening on {:?}", set.local_addrs());
+
+    let result = set.run(tokio::time::sleep(Duration::from_secs(2))).await;
+    if let Err(err) = result {
+        eprintln!("listener set stopped with an error: {err}");
+    }
+}

crates/irtt-server/src/config.rs

@@ -98,6 +98,28 @@ pub enum TimestampAllowance {
 /// [`max_packet_length`](Self::max_packet_length) like every other reply, and
 /// `none` is zero-filled here rather than left as residue. An operator
 /// restriction can be added if a real use case turns up.
+///
+/// # Example
+///
+/// Configure a modest per-listener session budget and restrict timestamp
+/// placement while leaving DSCP marking disabled:
+///
+/// ```
+/// use std::time::Duration;
+///
+/// use irtt_server::{ServerConfig, TimestampAllowance};
+///
+/// let config = ServerConfig::default()
+///     .with_max_sessions(128)
+///     .with_idle_timeout(Duration::from_secs(30))
+///     .with_timestamp_allowance(TimestampAllowance::Single)
+///     .with_dscp_allowed(false);
+///
+/// assert_eq!(config.max_sessions(), 128);
+/// assert_eq!(config.idle_timeout(), Duration::from_secs(30));
+/// assert_eq!(config.timestamp_allowance(), TimestampAllowance::Single);
+/// assert!(!config.dscp_allowed());
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ServerConfig {
     hmac_key: Option<Vec<u8>>,

crates/irtt-server/src/core.rs

@@ -47,6 +47,32 @@ use crate::{
 /// a transport abstraction, and there is no blocking or alternate-runtime
 /// counterpart.
 ///
+/// # Example
+///
+/// The core can be driven directly with a normally encoded open request. It
+/// returns a reply to send and records the new session without performing I/O:
+///
+/// ```
+/// use std::net::{Ipv4Addr, SocketAddr};
+///
+/// use irtt_proto::{decode_open_reply, encode_request, Params, RequestToEncode};
+/// use irtt_server::{ServerConfig, ServerCore};
+///
+/// let peer = SocketAddr::from((Ipv4Addr::LOCALHOST, 40_000));
+/// let mut core = ServerCore::new(ServerConfig::default());
+/// let params = Params::with_protocol_defaults();
+/// let request = encode_request(
+///     RequestToEncode::Open { params: &params, no_test: false },
+///     None,
+/// )
+/// .unwrap();
+///
+/// let reply = core.handle_datagram(peer, &request).unwrap().unwrap();
+/// let open = decode_open_reply(reply.bytes(), None).unwrap();
+/// assert_ne!(open.token, 0);
+/// assert_eq!(core.session_count(), 1);
+/// ```
+///
 /// # Scope
 ///
 /// The core implements open handling, session creation and negotiation,

crates/irtt-server/src/fill.rs

@@ -115,7 +115,9 @@ fn parse_hex_pattern(body: &str) -> Option<Vec<u8>> {
         return None;
     }
     digits
-        .chunks_exact(2)
+        .as_chunks::<2>()
+        .0
+        .iter()
         .map(|pair| Some(hex_digit(pair[0])? << 4 | hex_digit(pair[1])?))
         .collect()
 }

crates/irtt-server/src/lib.rs

@@ -32,6 +32,9 @@
 //! [`ServerConfig`] — `max_sessions` included — applies **per listener**, not
 //! per process.
 //!
+//! See `examples/` in the repository for a runnable single-listener and
+//! multi-listener example.
+//!
 //! # Rejection is silence
 //!
 //! The protocol defines no error reply, no reset and no NACK. Malformed,
@@ -129,4 +132,4 @@ pub use config::{
 pub use core::{OutboundDatagram, ServerCore};
 pub use error::ServerError;
 pub use runtime::{Server, ServerRuntimeError};
-pub use set::{ServerSet, ServerSetError};
+pub use set::{address_family_available, ServerSet, ServerSetError};

crates/irtt-server/src/runtime.rs

@@ -53,6 +53,28 @@ const MAINTENANCE_INTERVAL: Duration = Duration::from_secs(1);
 /// [`ServerRuntimeError::WildcardSourceSelectionUnsupported`] — rather than
 /// served by a listener whose replies a client on a second address would
 /// silently discard. Explicit-address listeners are unaffected everywhere.
+///
+/// # Example
+///
+/// Bind one listener, inspect the resolved endpoint, and let the caller decide
+/// when serving ends. This example type-checks without opening a socket:
+///
+/// ```no_run
+/// use std::{net::{Ipv4Addr, SocketAddr}, time::Duration};
+///
+/// use irtt_server::{Server, ServerConfig};
+///
+/// # async fn serve() -> Result<(), Box<dyn std::error::Error>> {
+/// let mut server = Server::bind(
+///     SocketAddr::from((Ipv4Addr::LOCALHOST, 0)),
+///     ServerConfig::default(),
+/// )
+/// .await?;
+/// println!("listening on {}", server.local_addr()?);
+/// server.run(tokio::time::sleep(Duration::from_secs(60))).await?;
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug)]
 pub struct Server {
     socket: UdpSocket,
@@ -109,6 +131,28 @@ impl Server {
         socket: UdpSocket,
         config: ServerConfig,
     ) -> Result<Self, ServerRuntimeError> {
+        Self::with_core(socket, ServerCore::new(config))
+    }
+
+    /// Test-only seam: builds a listener around an already-constructed core
+    /// instead of one this method would build from a [`ServerConfig`].
+    ///
+    /// This exists so a unit test can substitute a scripted
+    /// [`TokenSource`](crate::token::TokenSource) and make one listener in a
+    /// [`ServerSet`](crate::ServerSet) fail deterministically after it has
+    /// already bound and answered real traffic — the runtime otherwise offers
+    /// no way to make a core failure happen on command without OS-level
+    /// socket sabotage. Every other code path here — wildcard setup, kernel
+    /// timestamp configuration — is unchanged from [`Server::from_socket`].
+    #[cfg(test)]
+    pub(crate) fn from_socket_with_core(
+        socket: UdpSocket,
+        core: ServerCore,
+    ) -> Result<Self, ServerRuntimeError> {
+        Self::with_core(socket, core)
+    }
+
+    fn with_core(socket: UdpSocket, core: ServerCore) -> Result<Self, ServerRuntimeError> {
         let addr = socket
             .local_addr()
             .map_err(|source| ServerRuntimeError::LocalAddr { source })?;
@@ -131,7 +175,7 @@ impl Server {
 
         Ok(Self {
             socket,
-            core: ServerCore::new(config),
+            core,
             recv_buffer: vec![0; RECEIVE_BUFFER_LEN],
             listener_is_ipv4: marks_with_ipv4_option(addr),
             select_reply_source,

crates/irtt-server/src/set.rs

@@ -57,6 +57,29 @@ use crate::{Server, ServerConfig, ServerRuntimeError};
 /// whole set: a service configured for IPv4 and IPv6 must not quietly continue
 /// as IPv4 only. Every listener task is joined before `run` returns, so no task
 /// outlives it.
+///
+/// # Example
+///
+/// Bind independent listeners, inspect their resolved addresses, then serve
+/// them under one caller-owned shutdown future. This example type-checks
+/// without binding sockets:
+///
+/// ```no_run
+/// use std::{net::{Ipv4Addr, SocketAddr}, time::Duration};
+///
+/// use irtt_server::{ServerConfig, ServerSet};
+///
+/// # async fn serve() -> Result<(), Box<dyn std::error::Error>> {
+/// let addrs = [
+///     SocketAddr::from((Ipv4Addr::LOCALHOST, 0)),
+///     SocketAddr::from((Ipv4Addr::LOCALHOST, 0)),
+/// ];
+/// let set = ServerSet::bind(addrs, ServerConfig::default()).await?;
+/// println!("listening on {:?}", set.local_addrs());
+/// set.run(tokio::time::sleep(Duration::from_secs(60))).await?;
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug)]
 pub struct ServerSet {
     servers: Vec<Server>,
@@ -91,6 +114,14 @@ impl ServerSet {
     /// An IPv4-mapped address such as `[::ffff:0.0.0.0]` is an IPv4 listener
     /// here, not an IPv6 one, matching how the runtime already reads it.
     ///
+    /// A lone explicit dual-stack `[::]:PORT` listener is not the recommended
+    /// configuration when reply DSCP/traffic-class marking for IPv4 peers
+    /// matters: Linux serves those peers as IPv4-mapped and cannot retain the
+    /// negotiated marking on their replies. Request the normal same-port
+    /// `[::]:PORT` and `0.0.0.0:PORT` pair instead. This method makes the IPv6
+    /// half IPv6-only for that pair only; a lone IPv6 listener retains its
+    /// normal socket behavior.
+    ///
     /// # Errors
     ///
     /// Returns [`ServerSetError::NoListeners`] if `addrs` is empty — a set
@@ -218,6 +249,40 @@ impl ServerSet {
     }
 }
 
+/// Whether `addr`'s address family has any local support on this host at
+/// all, independent of whether this particular address or port can be
+/// bound.
+///
+/// A [`ServerSetError::ListenerSetup`] failure can mean many different
+/// things — the port is already in use, permission is denied, this target
+/// has no safe wildcard reply-source path (see [`ServerRuntimeError`]) — and
+/// only one of them, the address family itself having no local support at
+/// all (for example IPv6 disabled on the host), is safe for a caller to work
+/// around by silently trying a different address instead. This checks only
+/// that, by actually binding the wildcard address of `addr`'s family on an
+/// ephemeral port: a bare socket of an unsupported family can still
+/// construct successfully on some systems (Linux administratively disables
+/// IPv6 per-interface, so `AF_INET6` sockets keep working while every bind
+/// fails with `EADDRNOTAVAIL`), so construction alone is not a reliable
+/// signal — only a real bind attempt is.
+#[must_use]
+pub fn address_family_available(addr: SocketAddr) -> bool {
+    let wildcard = if addr.is_ipv6() {
+        SocketAddr::from((std::net::Ipv6Addr::UNSPECIFIED, 0))
+    } else {
+        SocketAddr::from((std::net::Ipv4Addr::UNSPECIFIED, 0))
+    };
+    let domain = if addr.is_ipv6() {
+        Domain::IPV6
+    } else {
+        Domain::IPV4
+    };
+    let Ok(socket) = Socket::new(domain, Type::DGRAM, Some(Protocol::UDP)) else {
+        return false;
+    };
+    socket.bind(&SockAddr::from(wildcard)).is_ok()
+}
+
 /// Binds one listener, pre-configuring the socket where the bind itself depends
 /// on it.
 ///
@@ -323,7 +388,10 @@ pub enum ServerSetError {
 
 #[cfg(test)]
 mod tests {
+    use std::time::Duration;
+
     use super::*;
+    use crate::{token::TokenSource, ServerCore, ServerError};
 
     /// Which listener of a requested set has to be bound IPv6-only.
     ///
@@ -409,4 +477,162 @@ mod tests {
             Err(ServerSetError::NoListeners)
         ));
     }
+
+    /// A token source that draws one value successfully and then fails every
+    /// later draw.
+    ///
+    /// This is the same seam the core's own tests already use to make token
+    /// allocation fail deterministically (see [`crate::token::TokenSource`]
+    /// and its `ScriptedTokens::failing`), specialized here so the *first*
+    /// open still succeeds: the listener built from it answers one real
+    /// exchange exactly like a healthy listener would, and only a second open
+    /// discovers the failure.
+    #[derive(Debug)]
+    struct FailAfterFirstToken(Option<u64>);
+
+    impl TokenSource for FailAfterFirstToken {
+        fn next_token(&mut self) -> Result<u64, ServerError> {
+            self.0.take().ok_or_else(|| ServerError::RandomSource {
+                reason: "test fault injection: exhausted after the first token".to_owned(),
+            })
+        }
+    }
+
+    const FIRST_TOKEN: u64 = 0xdead_beef_dead_beef;
+    const TEST_TIMEOUT: Duration = Duration::from_secs(5);
+    const REPLY_TIMEOUT: Duration = Duration::from_secs(1);
+
+    fn loopback(port: u16) -> SocketAddr {
+        SocketAddr::from((std::net::Ipv4Addr::LOCALHOST, port))
+    }
+
+    fn requested_params() -> irtt_proto::Params {
+        irtt_proto::Params {
+            protocol_version: 1,
+            duration_ns: 10_000_000_000,
+            interval_ns: 100_000_000,
+            received_stats: irtt_proto::ReceivedStats::Both,
+            stamp_at: irtt_proto::StampAt::Both,
+            clock: irtt_proto::Clock::Both,
+            ..irtt_proto::Params::default()
+        }
+    }
+
+    async fn send_open(client: &UdpSocket, addr: SocketAddr) {
+        let request = irtt_proto::encode_request(
+            irtt_proto::RequestToEncode::Open {
+                params: &requested_params(),
+                no_test: false,
+            },
+            None,
+        )
+        .unwrap();
+        client.send_to(&request, addr).await.unwrap();
+    }
+
+    /// Sends one open request and returns its reply, or `None` if the
+    /// listener stayed silent within [`REPLY_TIMEOUT`].
+    async fn open(client: &UdpSocket, addr: SocketAddr) -> Option<irtt_proto::OpenReply> {
+        send_open(client, addr).await;
+        let mut buffer = [0u8; 4096];
+        match tokio::time::timeout(REPLY_TIMEOUT, client.recv_from(&mut buffer)).await {
+            Ok(received) => {
+                let (len, from) = received.unwrap();
+                assert_eq!(from, addr, "a reply came from the wrong listener");
+                Some(irtt_proto::decode_open_reply(&buffer[..len], None).unwrap())
+            }
+            Err(_) => None,
+        }
+    }
+
+    /// A fatal failure inside one listener, after every listener in the set
+    /// has already bound and answered real traffic, shuts its siblings down,
+    /// joins every task and fails the set — with no external shutdown ever
+    /// sent.
+    ///
+    /// The failure is injected the same way the core's own tests already
+    /// drive a token-allocation failure: a scripted
+    /// [`crate::token::TokenSource`] substituted for one listener's
+    /// [`crate::ServerCore`], through the test-only
+    /// [`Server::from_socket_with_core`]. That source draws one token
+    /// successfully, so the listener built from it answers a first open
+    /// exactly like its healthy sibling does — which is the startup/readiness
+    /// synchronization this test relies on: both are bound and actively
+    /// serving real traffic before anything is asked to fail, not merely
+    /// spawned. Only a *second* open against that listener draws its second
+    /// token, which the scripted source refuses, and that single draw is the
+    /// one injected fatal failure. Nothing about the socket, the receive loop
+    /// or the sibling listener is touched.
+    #[tokio::test(flavor = "current_thread")]
+    async fn a_mid_run_listener_failure_shuts_down_its_siblings_and_fails_the_set() {
+        let config = ServerConfig::default().with_min_send_interval(Duration::ZERO);
+
+        let failing_socket = UdpSocket::bind(loopback(0)).await.unwrap();
+        let failing_core = ServerCore::with_token_source(
+            config.clone(),
+            Box::new(FailAfterFirstToken(Some(FIRST_TOKEN))),
+        );
+        let failing = Server::from_socket_with_core(failing_socket, failing_core).unwrap();
+        let failing_addr = failing.local_addr().unwrap();
+
+        let healthy_socket = UdpSocket::bind(loopback(0)).await.unwrap();
+        let healthy = Server::from_socket(healthy_socket, config).unwrap();
+        let healthy_addr = healthy.local_addr().unwrap();
+
+        let set = ServerSet {
+            servers: vec![failing, healthy],
+            local_addrs: vec![failing_addr, healthy_addr],
+        };
+
+        // A shutdown future that never resolves: whatever stops the set has
+        // to come from the injected failure, not from this caller.
+        let run = tokio::spawn(set.run(std::future::pending::<()>()));
+
+        let client = UdpSocket::bind(loopback(0)).await.unwrap();
+
+        // Both listeners answer a first, ordinary open before anything fails.
+        let opened = open(&client, failing_addr)
+            .await
+            .expect("the failing listener is bound and serving before it fails");
+        assert_eq!(opened.token, FIRST_TOKEN);
+        assert!(
+            open(&client, healthy_addr).await.is_some(),
+            "the healthy listener is bound and serving too"
+        );
+
+        // The second open at the failing listener draws its second token,
+        // which the scripted source refuses. It terminates that listener
+        // before any reply could be built, so this exchange places no
+        // expectation on a reply.
+        send_open(&client, failing_addr).await;
+
+        let outcome = tokio::time::timeout(TEST_TIMEOUT, run)
+            .await
+            .expect("the set stopped on its own, with no external shutdown sent")
+            .expect("the supervising task did not panic");
+        match outcome {
+            Err(ServerSetError::ListenerRun { addr, source }) => {
+                assert_eq!(
+                    addr, failing_addr,
+                    "the failure names the listener that actually failed"
+                );
+                assert!(
+                    matches!(
+                        source,
+                        ServerRuntimeError::Core(ServerError::RandomSource { .. })
+                    ),
+                    "unexpected failure source: {source}"
+                );
+            }
+            other => panic!("expected the injected listener failure, got {other:?}"),
+        }
+
+        // The sibling did not linger after the failure: its task was joined
+        // and its socket released, exactly like the listener that failed —
+        // proof neither task nor socket was leaked.
+        for addr in [healthy_addr, failing_addr] {
+            std::net::UdpSocket::bind(addr)
+                .unwrap_or_else(|error| panic!("{addr} was not released: {error}"));
+        }
+    }
 }

crates/irtt-server/src/socket_io.rs

@@ -32,11 +32,11 @@
 //! instant, is served normally with no timestamp. Nothing about which datagrams
 //! reach [`ServerCore`](crate::ServerCore) depends on it.
 //!
-//! **Nothing consumes it yet.** It is captured here so a follow-up change can
+//! [`ServerCore`](crate::ServerCore) prefers it over its own receive sample
-//! decide how a kernel-observed arrival time enters the protocol core; today
+//! when reporting a request's receive instant, falling back to that sample
-//! the core still samples its own receive instant and no protocol timing is
+//! when no plausible kernel reading is available; see
-//! affected. It is a software wall-clock reading only — not a NIC hardware
+//! `preferred_receive_wall_ns`. It is a software wall-clock reading only —
-//! timestamp, not monotonic, and not a transmit timestamp.
+//! not a NIC hardware timestamp, not monotonic, and not a transmit timestamp.
 
 use std::{io, net::SocketAddr, time::SystemTime};
 

crates/irtt-stats/Cargo.toml

@@ -1,15 +1,21 @@
 [package]
 name = "irtt-stats"
-version = "0.5.0"
+version = "0.5.1"
 description = "Statistics aggregation for irtt-client events"
 edition.workspace = true
 license.workspace = true
 rust-version.workspace = true
 repository.workspace = true
 homepage.workspace = true
-readme.workspace = true
+readme = "README.md"
 keywords = ["irtt", "networking", "latency", "statistics"]
 categories = ["network-programming"]
 
 [dependencies]
 irtt-client.workspace = true
+
+[[example]]
+name = "finite_vs_continuous"
+
+[dev-dependencies]
+proptest = "1.11.0"

crates/irtt-stats/README.md

@@ -0,0 +1,38 @@
+# irtt-stats
+
+Statistics aggregation over [`irtt-client`](https://crates.io/crates/irtt-client)
+events: loss/duplicate/late accounting, RTT and one-way-delay timing, and
+inter-packet delay variation (IPDV), as cumulative and rolling snapshots.
+
+## Relationship to irtt-client
+
+This crate does not open sessions or drive sockets. Feed it the `ClientEvent`
+stream produced by an `irtt-client` `Client`, `AsyncClient`, or managed
+session via `StatsCollector::process`, and read back a `Snapshot`.
+
+A `StatsCollector` has one sequence/IPDV namespace and one packet count, both
+scoped to a single target. A managed session covering multiple targets needs
+one collector per target — as the `irtt-rs` CLI does — since a target's
+sequence numbers start over at zero and feeding two targets into one
+collector would pair up unrelated probes.
+
+## Retention modes
+
+`StatsConfig::finite()` retains exact timing samples for its cumulative
+snapshot, so every metric with samples reports an exact median there —
+retention grows with the probe count. `StatsConfig::continuous()` keeps
+bounded running statistics instead (no exact median) plus a bounded
+4096-entry adjacent-sequence IPDV store per target, for long-running or
+unbounded sessions. Rolling-window snapshots are always running-only and
+report no medians, whichever `StatsConfig` produced them.
+
+See `examples/` in the repository for a runnable comparison of both modes.
+
+## Documentation
+
+Full API documentation is on [docs.rs/irtt-stats](https://docs.rs/irtt-stats).
+
+## Project
+
+Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
+implementation of an IRTT-compatible protocol stack.