Lochnair-Labs/irtt-rs
2
0 Fork 0
Code Issues 1 Pull Requests 4 Actions 8 Packages Projects Releases 6 Wiki Activity

docs: implement release-readiness audit findings #127

Merged
Lochnair merged 8 commits from docs/release-readiness-audit-fixes into main 2026-08-20 08:33:08 +00:00
Conversation 6 Commits 8 Files Changed 5
+87 -17
Lochnair commented 2026-08-20 08:01:56 +00:00 (Migrated from github.com)
Copy link
Copy source

Summary

Implements the small, legitimate documentation/code findings from a release-readiness audit:

  • Point README installation and library-usage examples at crates.io (cargo install irtt-rs --locked, irtt-client = { version = "0.5", ... }) instead of leading with a local checkout, keeping the local/path forms as documented alternatives for development.
  • Document that final per-target CLI summaries print in command-line argument order, not finish order or alphabetical label order (scoped to the final summary only, not live/event-stream ordering).
  • Document Linux's best-effort kernel-timestamp preference for one-way-delay measurement in the README and in OneWayDelaySample::client_to_server's rustdoc (matching the existing server_to_client doc style), plus fix a stale socket_io module doc that still claimed the captured kernel receive timestamp was unconsumed.
  • Expand ManagedClientHandle::update_targets() rustdoc to document full desired-set-replacement semantics, live-target continuity, and that a changed config or a terminal-generation resubmission starts a fresh generation.
  • Fix feature-specific dead-code warnings in crates/irtt-app/src/cmd/format.rs by narrowly #[cfg(feature = "...")]-gating client-only and TUI-only formatting helpers, with matching test splits — no new features, no blanket allows.

Test plan

  • cargo fmt --all -- --check
  • cargo test --workspace --locked
  • cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
  • RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps --locked
  • RUSTFLAGS="-D warnings" cargo check -p irtt-rs --no-default-features (and with --features client/server/tui)
  • git diff --check
## Summary Implements the small, legitimate documentation/code findings from a release-readiness audit: - Point README installation and library-usage examples at crates.io (`cargo install irtt-rs --locked`, `irtt-client = { version = "0.5", ... }`) instead of leading with a local checkout, keeping the local/path forms as documented alternatives for development. - Document that final per-target CLI summaries print in command-line argument order, not finish order or alphabetical label order (scoped to the final summary only, not live/event-stream ordering). - Document Linux's best-effort kernel-timestamp preference for one-way-delay measurement in the README and in `OneWayDelaySample::client_to_server`'s rustdoc (matching the existing `server_to_client` doc style), plus fix a stale `socket_io` module doc that still claimed the captured kernel receive timestamp was unconsumed. - Expand `ManagedClientHandle::update_targets()` rustdoc to document full desired-set-replacement semantics, live-target continuity, and that a changed config or a terminal-generation resubmission starts a fresh generation. - Fix feature-specific dead-code warnings in `crates/irtt-app/src/cmd/format.rs` by narrowly `#[cfg(feature = "...")]`-gating client-only and TUI-only formatting helpers, with matching test splits — no new features, no blanket allows. ## Test plan - [x] `cargo fmt --all -- --check` - [x] `cargo test --workspace --locked` - [x] `cargo clippy --workspace --all-targets --all-features --locked -- -D warnings` - [x] `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps --locked` - [x] `RUSTFLAGS="-D warnings" cargo check -p irtt-rs --no-default-features` (and with `--features client`/`server`/`tui`) - [x] `git diff --check`
👍 1
chatgpt-codex-connector[bot] (Migrated from github.com) reviewed 2026-08-20 08:09:07 +00:00
chatgpt-codex-connector[bot] (Migrated from github.com) left a comment
Copy link
Copy source

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98e7231ede

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

### 💡 Codex Review Here are some automated review suggestions for this pull request. **Reviewed commit:** `98e7231ede` <details> <summary>ℹ️ About Codex in GitHub</summary> <br/> [Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you - Open a pull request for review - Mark a draft as ready - Comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". </details>
crates/irtt-client/src/event.rs
@@ -351,7 +351,22 @@ pub struct OneWayDelaySample {
/// Client-to-server delay.
chatgpt-codex-connector[bot] (Migrated from github.com) commented 2026-08-20 08:09:07 +00:00
Copy link
Copy source

P2 Badge Limit the unaffected claim to raw RTT

When the peer is the Linux irtt-server and negotiates wall-clock receive-and-send timestamps, the preferred kernel receive timestamp also becomes recv_wall; compute_server_processing subtracts it from send_wall, and that processing interval changes RttSample::adjusted and therefore effective. Only raw RTT remains an unaffected userspace-monotonic measurement, so qualify this sentence—and the matching README claim—to avoid misleading users interpreting adjusted/effective RTT results.

Useful? React with 👍 / 👎.

**<sub><sub>![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)</sub></sub> Limit the unaffected claim to raw RTT** When the peer is the Linux `irtt-server` and negotiates wall-clock receive-and-send timestamps, the preferred kernel receive timestamp also becomes `recv_wall`; `compute_server_processing` subtracts it from `send_wall`, and that processing interval changes `RttSample::adjusted` and therefore `effective`. Only `raw` RTT remains an unaffected userspace-monotonic measurement, so qualify this sentence—and the matching README claim—to avoid misleading users interpreting adjusted/effective RTT results. Useful? React with 👍 / 👎.
Lochnair (Migrated from github.com) reviewed 2026-08-20 08:12:09 +00:00
crates/irtt-client/src/event.rs
@@ -351,7 +351,22 @@ pub struct OneWayDelaySample {
/// Client-to-server delay.
Lochnair (Migrated from github.com) commented 2026-08-20 08:12:09 +00:00
Copy link
Copy source

Fixed: qualified this to raw RTT only. adjusted_rtt_us/effective_rtt_us are derived from server-reported processing time, which shares the same server receive endpoint this field documents as kernel-preferred, so I updated both the client_to_server rustdoc and the matching README sentence (commit c9269ca) to say raw RTT is unaffected while adjusted/effective can still shift.

🤖 Addressed by Claude Code

Fixed: qualified this to raw RTT only. `adjusted_rtt_us`/`effective_rtt_us` are derived from server-reported processing time, which shares the same server receive endpoint this field documents as kernel-preferred, so I updated both the `client_to_server` rustdoc and the matching README sentence (commit c9269ca) to say raw RTT is unaffected while adjusted/effective can still shift. _🤖 Addressed by [Claude Code](https://claude.com/claude-code)_
chatgpt-codex-connector[bot] (Migrated from github.com) reviewed 2026-08-20 08:17:39 +00:00
chatgpt-codex-connector[bot] (Migrated from github.com) left a comment
Copy link
Copy source

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c9269ca0ee

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

### 💡 Codex Review Here are some automated review suggestions for this pull request. **Reviewed commit:** `c9269ca0ee` <details> <summary>ℹ️ About Codex in GitHub</summary> <br/> [Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you - Open a pull request for review - Mark a draft as ready - Comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". </details>
crates/irtt-client/src/event.rs
@@ -351,7 +351,22 @@ pub struct OneWayDelaySample {
/// Client-to-server delay.
chatgpt-codex-connector[bot] (Migrated from github.com) commented 2026-08-20 08:17:39 +00:00
Copy link
Copy source

P2 Badge Scope the server kernel timestamp claim to this server

When irtt-client is used with an arbitrary IRTT-compatible peer, it only receives a wall-clock value from the wire and cannot know whether that peer obtained it from the kernel, userspace, or another clock source. This rustdoc therefore overpromises that the server endpoint prefers a plausible kernel timestamp; that behavior is specific to the Linux Tokio runtime in this repository. Qualify this claim—and the matching broad README statement—so consumers do not misinterpret measurements from other servers.

Useful? React with 👍 / 👎.

**<sub><sub>![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)</sub></sub> Scope the server kernel timestamp claim to this server** When `irtt-client` is used with an arbitrary IRTT-compatible peer, it only receives a wall-clock value from the wire and cannot know whether that peer obtained it from the kernel, userspace, or another clock source. This rustdoc therefore overpromises that the server endpoint prefers a plausible kernel timestamp; that behavior is specific to the Linux Tokio runtime in this repository. Qualify this claim—and the matching broad README statement—so consumers do not misinterpret measurements from other servers. Useful? React with 👍 / 👎.
Lochnair (Migrated from github.com) reviewed 2026-08-20 08:18:57 +00:00
crates/irtt-client/src/event.rs
@@ -351,7 +351,22 @@ pub struct OneWayDelaySample {
/// Client-to-server delay.
Lochnair (Migrated from github.com) commented 2026-08-20 08:18:57 +00:00
Copy link
Copy source

Fixed: scoped the kernel-preference claim to this crate's own irtt-server on Linux. Against any other IRTT-compatible peer, the client has no way to know what clock source produced the reported wall-clock endpoint, so it's now stated as used as-is in that case, in both this rustdoc and the matching README sentence (commit cab1fd1).

🤖 Addressed by Claude Code

Fixed: scoped the kernel-preference claim to this crate's own `irtt-server` on Linux. Against any other IRTT-compatible peer, the client has no way to know what clock source produced the reported wall-clock endpoint, so it's now stated as used as-is in that case, in both this rustdoc and the matching README sentence (commit cab1fd1). _🤖 Addressed by [Claude Code](https://claude.com/claude-code)_
chatgpt-codex-connector[bot] (Migrated from github.com) reviewed 2026-08-20 08:23:06 +00:00
chatgpt-codex-connector[bot] (Migrated from github.com) left a comment
Copy link
Copy source

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cab1fd1aab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

### 💡 Codex Review Here are some automated review suggestions for this pull request. **Reviewed commit:** `cab1fd1aab` <details> <summary>ℹ️ About Codex in GitHub</summary> <br/> [Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you - Open a pull request for review - Mark a draft as ready - Comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". </details>
crates/irtt-client/src/event.rs
@@ -351,7 +351,22 @@ pub struct OneWayDelaySample {
/// Client-to-server delay.
chatgpt-codex-connector[bot] (Migrated from github.com) commented 2026-08-20 08:23:06 +00:00
Copy link
Copy source

P2 Badge Limit the kernel timestamp claim to the Tokio server

When an application pairs this client with the public irtt_server::ServerCore::handle_datagram API on Linux, the peer is still this crate's irtt-server, but no kernel receive timestamp is used: crates/irtt-server/src/core.rs:161-165 states that this path samples every instant itself, while only the crate-private Tokio runtime entry point supplies transport metadata. Qualify this claim, and the matching README sentence, to the Tokio Server/server applet rather than the whole server crate. Fresh evidence is the inspected public ServerCore path, which always calls process(..., None) at core.rs:173-178.

Useful? React with 👍 / 👎.

**<sub><sub>![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)</sub></sub> Limit the kernel timestamp claim to the Tokio server** When an application pairs this client with the public `irtt_server::ServerCore::handle_datagram` API on Linux, the peer is still this crate's `irtt-server`, but no kernel receive timestamp is used: `crates/irtt-server/src/core.rs:161-165` states that this path samples every instant itself, while only the crate-private Tokio runtime entry point supplies transport metadata. Qualify this claim, and the matching README sentence, to the Tokio `Server`/server applet rather than the whole server crate. Fresh evidence is the inspected public `ServerCore` path, which always calls `process(..., None)` at `core.rs:173-178`. Useful? React with 👍 / 👎.
Lochnair (Migrated from github.com) reviewed 2026-08-20 08:24:52 +00:00
crates/irtt-client/src/event.rs
@@ -351,7 +351,22 @@ pub struct OneWayDelaySample {
/// Client-to-server delay.
Lochnair (Migrated from github.com) commented 2026-08-20 08:24:52 +00:00
Copy link
Copy source

Fixed: scoped this to the Tokio server runtime specifically. ServerCore::handle_datagram is a public API that always passes kernel_rx_timestamp = None; only the crate-private entry point the Tokio runtime (the irtt-server applet) uses actually supplies one. Both the rustdoc and README now say so explicitly (commit 1754b77).

🤖 Addressed by Claude Code

Fixed: scoped this to the Tokio server runtime specifically. `ServerCore::handle_datagram` is a public API that always passes `kernel_rx_timestamp = None`; only the crate-private entry point the Tokio runtime (the `irtt-server` applet) uses actually supplies one. Both the rustdoc and README now say so explicitly (commit 1754b77). _🤖 Addressed by [Claude Code](https://claude.com/claude-code)_
Sign in to join this conversation.
Reviewers
No Reviewers
chatgpt-codex-connector[bot]
Lochnair
Labels
Clear labels
bug
Something isn't working
 dependencies
documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 question
Further information is requested
 wontfix
This will not be worked on
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
Lochnair renovate (Renovate Bot) Bot
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Lochnair-Labs/irtt-rs#127