Docs: rustdoc coverage; API changes for fragments and backoff

[leynos]

Summary

• Adds extensive rustdoc comments across modules, tests, and support code to standardise documentation style
• Inlines and clarifies field and method docs (e.g., id, correlation_id, payload, and various config/priority docs)
• Normalises BackoffConfig in server runtime to clamp delays and ensure initial_delay <= max_delay, preserving API semantics
• Updates some test world and common types with documentation for clarity
• Public API changes are limited to fragment error variants: FragmentError::IndexOverflow and FragmentationError::IndexOverflow now carry a last: FragmentIndex field; tests updated accordingly
• Documentation and test support updates across modules, tests/worlds, and test helpers
• No other public API changes beyond the fragment error variants; internal backoff normalisation is a safeguard

Why

• Improves signal-to-noise ratio in docs and reduces doc fragility
• Improves reliability of runtime configuration by sanitising backoff values
• Aligns with rustdoc conventions and tests documentation
• Introduces explicit migration surface for fragment error handling due to updated variants

Task

https://www.terragonlabs.com/task/bab289c9-a99e-4663-aac8-ae73906a449b

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 2500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Summary by CodeRabbit

Release Notes

• New Features

  • Added public accessor methods for packet information (identifier, correlation identifier, and payload data).
  • Introduced backoff configuration normalisation to ensure valid delay parameters.
  • Enhanced error types with additional diagnostic fields for improved troubleshooting.

• Documentation

  • Expanded documentation coverage throughout the codebase, including public fields, types, and test utilities.

• Tests

  • Added new test helpers and correlation-specific test world methods.

• Chores

  • Enforced stricter documentation requirements via lint configuration.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Summarise the change: Added public PacketParts accessors, enriched fragmentation error variants with contextual fields, introduced BackoffConfig::normalised and invoked it in accept_loop, and expanded Rustdoc coverage across many modules and tests; also enabled deny for missing_docs in Cargo.toml.

Changes

Cohort / File(s)	Summary
Lint configuration Cargo.toml	Added missing_docs = "deny" under [lints.rust] to enforce documentation.
Packet accessors src/app/envelope.rs	Added pub const fn id(&self) -> u32, pub const fn correlation_id(&self) -> Option<u64>, and pub fn payload(self) -> Vec<u8> on PacketParts.
Fragmentation errors & diagnostics src/fragment/error.rs, CHANGELOG.md, docs/.../generic-message-fragmentation-and-re-assembly-design.md, src/fragment/tests.rs	Converted several FragmentError and FragmentationError variants to carry contextual data: MessageMismatch { expected, found }, IndexMismatch { expected, found }, and IndexOverflow { last }. Updated tests, changelog and docs to reflect pattern-match changes.
Backoff config & runtime src/server/runtime.rs	Added pub fn normalised(mut self) -> Self on BackoffConfig; normalise invoked at start of accept_loop. Documented fields and method; enforces minimum delays and swaps if inverted.
Connection & test harness docs src/connection.rs, src/connection/test_support.rs	Added Rustdoc comments to public fields (ConnectionChannels<F> queues/handle; ActorHarness / ActorStateSnapshot docs).
Push queues docs & enums src/push/queues/errors.rs, src/push/queues/mod.rs	Added field docs to PushConfigError::InvalidCapacity and variant docs for PushPriority::{High,Low}.
Tests: types, worlds and doc placement tests/common/mod.rs, tests/advanced/concurrency_loom.rs, tests/worlds/*	Added TestApp and TestResult type aliases with docs; moved crate-level cfg attribute placement in concurrency_loom; added doc comments and small accessor methods in test world files (e.g. tests/worlds/correlation.rs).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• Review focus:
  • Audit all construction and pattern-match sites for modified FragmentError/FragmentationError variants to ensure exhaustive matches updated.
  • Verify PacketParts::payload(self) consuming semantics are safe and used correctly.
  • Validate BackoffConfig::normalised respects minimums, swap logic and that accept_loop usage preserves intended backoff behaviour.
  • Check that making missing_docs = "deny" does not break build due to any undocumented public items introduced.

Possibly related issues

• Add documentation for BackoffConfig::normalised method #315 — Relates to implementing and documenting BackoffConfig normalisation and swap behaviour in accept_loop.

Possibly related PRs

• Implement Transport-Level Fragmentation And Reassembly #393 — Modifies the same fragmentation error types / diagnostics that are updated here; likely directly related.

Suggested labels

codex

Suggested reviewers

• codescene-delta-analysis

Poem

Docs tighten, errors tell the truth,
Accessors fetch the packet's youth,
Backoff learned to mind its bounds,
Tests and notes in tidy rounds,
Code walks straighter for this proof.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title accurately summarises the main changes: rustdoc coverage improvements and API updates for fragments and backoff configuration.
Description check	✅ Passed	Description comprehensively details all major changes, including rustdoc additions, BackoffConfig normalisation, and fragment error variant updates.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch comprehensive-doc-comments

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9391453 and fe73fc6.

📒 Files selected for processing (7)

• CHANGELOG.md (1 hunks)
• docs/generic-message-fragmentation-and-re-assembly-design.md (1 hunks)
• src/fragment/tests.rs (1 hunks)
• src/server/runtime.rs (3 hunks)
• tests/advanced/concurrency_loom.rs (1 hunks)
• tests/worlds/correlation.rs (1 hunks)
• tests/worlds/multi_packet.rs (2 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

**/*.rs: Run make check-fmt (cargo fmt --workspace -- --check) before committing to validate Rust formatting across the entire workspace without modifying files.
Run make lint (cargo clippy --workspace --all-targets --all-features -- -D warnings) before committing to lint every target with all features enabled and deny all Clippy warnings.
Run make test (cargo test --workspace) before committing to run the full workspace test suite.
Clippy warnings MUST be disallowed. Fix any warnings emitted during tests in the code itself rather than silencing them.
Use make fmt (cargo fmt --workspace) to apply formatting fixes reported by the formatter check.
Where a Rust function is too long, extract meaningfully named helper functions adhering to separation of concerns and CQRS.
Where a Rust function has too many parameters, group related parameters in meaningfully named structs.
Where a Rust function is returning a large error, consider using Arc to reduce the amount of data returned.
Write unit and behavioural tests for new Rust functionality. Run both before and after making any change.
Every Rust module must begin with a module level (//!) comment explaining the module's purpose and utility.
Document public Rust APIs using Rustdoc comments (///) so documentation can be generated with cargo doc.
Prefer immutable data and avoid unnecessary mut bindings in Rust code.
Avoid unsafe code in Rust unless absolutely necessary, and document any usage clearly with a 'SAFETY' comment.
Place function attributes after doc comments in Rust code.
Do not use return in single-line Rust functions.
Use predicate functions for Rust conditional criteria with more than two branches.
Lints must not be silenced in Rust except as a last resort. Lint rule suppressions must be tightly scoped and include a clear reason.
Use concat!() to combine long string literals in Rust rather than escaping newlines with a backslash.
Prefer single-line versions of Rust functions where...

Files:

• src/fragment/tests.rs
• src/server/runtime.rs
• tests/worlds/multi_packet.rs
• tests/worlds/correlation.rs
• tests/advanced/concurrency_loom.rs

---

⚙️ CodeRabbit configuration file

**/*.rs: * Seek to keep the cognitive complexity of functions no more than 9.

• Adhere to single responsibility and CQRS
• Place function attributes after doc comments.
• Do not use return in single-line functions.
• Move conditionals with >2 branches into a predicate function.
• Avoid unsafe unless absolutely necessary.
• Every module must begin with a //! doc comment that explains the module's purpose and utility.
• Comments and docs must follow en-GB-oxendict (-ize / -yse / -our) spelling and grammar
• Lints must not be silenced except as a last resort.
  • #[allow] is forbidden.
  • Only narrowly scoped #[expect(lint, reason = "...")] is allowed.
  • No lint groups, no blanket or file-wide suppression.
  • Include FIXME: with link if a fix is expected.
• Where code is only used by specific features, it must be conditionally compiled or a conditional expectation for unused_code applied.
• Use rstest fixtures for shared setup and to avoid repetition between tests.
• Replace duplicated tests with #[rstest(...)] parameterised cases.
• Prefer mockall for mocks/stubs.
• Prefer .expect() over .unwrap() in tests.
• .expect() and .unwrap() are forbidden outside of tests. Errors must be propagated.
• Ensure that any API or behavioural changes are reflected in the documentation in docs/
• Ensure that any completed roadmap steps are recorded in the appropriate roadmap in docs/
• Files must not exceed 400 lines in length
  • Large modules must be decomposed
  • Long match statements or dispatch tables should be decomposed by domain and collocated with targets
  • Large blocks of inline data (e.g., test fixtures, constants or templates) must be moved to external files and inlined at compile-time or loaded at run-time.
• Environment access (env::set_var and env::remove_var) are always unsafe in Rust 2024 and MUST be marked as such
  • For testing of functionality depending upon environment variables, dependency injection and...

Files:

• src/fragment/tests.rs
• src/server/runtime.rs
• tests/worlds/multi_packet.rs
• tests/worlds/correlation.rs
• tests/advanced/concurrency_loom.rs

**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

**/*.md: Validate Markdown files using make markdownlint.
Run make fmt after any documentation changes to format all Markdown files and fix table markup.
Validate Mermaid diagrams in Markdown files by running make nixie.
Markdown paragraphs and bullet points must be wrapped at 80 columns.
Code blocks in Markdown must be wrapped at 120 columns.
Markdown tables and headings must not be wrapped.
Use dashes (-) for list bullets in Markdown.
Use GitHub-flavoured Markdown footnotes ([^1]) for references and footnotes in Markdown.

Files:

• CHANGELOG.md
• docs/generic-message-fragmentation-and-re-assembly-design.md

---

⚙️ CodeRabbit configuration file

**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")

• Use en-GB-oxendict (-ize / -yse / -our) spelling and grammar
• Headings must not be wrapped.
• Documents must start with a level 1 heading
• Headings must correctly increase or decrease by no more than one level at a time
• Use GitHub-flavoured Markdown style for footnotes and endnotes.
• Numbered footnotes must be numbered by order of appearance in the document.

Files:

• CHANGELOG.md
• docs/generic-message-fragmentation-and-re-assembly-design.md

docs/**/*.md

📄 CodeRabbit inference engine (docs/contents.md)

Follow the documentation style guide conventions when writing project documentation

docs/**/*.md: Use British English based on the Oxford English Dictionary (en-GB-oxendict), including: -ize suffix in words like 'realize' and 'organization', -lyse suffix in words like 'analyse', -our suffix in words like 'colour', -re suffix in words like 'centre', double 'l' in words like 'cancelled', maintain 'e' in words like 'likeable', -ogue suffix in words like 'catalogue'
The word 'outwith' is acceptable in British English documentation
Keep US spelling when used in an API (for example, 'color')
Use the Oxford comma in documentation: 'ships, planes, and hovercraft' where it aids comprehension
Treat company names as collective nouns: 'Lille Industries are expanding'
Write headings in sentence case in documentation
Use Markdown headings (#, ##, ###, and so on) in order without skipping levels
Follow markdownlint recommendations for Markdown files
Always provide a language identifier for fenced code blocks in documentation; use 'plaintext' for non-code text
Use '-' as the first level bullet and renumber lists when items change in documentation
Prefer inline links using 'text' or angle brackets around the URL in documentation
Ensure blank lines before and after bulleted lists and fenced blocks in documentation
Ensure tables have a delimiter line below the header row in documentation
Expand any uncommon acronym on first use in documentation (for example, Continuous Integration (CI))
Wrap paragraphs at 80 columns in documentation
Wrap code at 120 columns in documentation
Do not wrap tables in documentation
Use footnotes referenced with '[^label]' in documentation
Include Mermaid diagrams where they add clarity to documentation
When embedding figures in documentation, use '' and provide brief alt text describing the content
Add a short description before each Mermaid diagram so screen readers can understand it

Write official documentation with se...

Files:

• docs/generic-message-fragmentation-and-re-assembly-design.md

docs/**/*.{rs,md}

📄 CodeRabbit inference engine (docs/rust-doctest-dry-guide.md)

Every doctest should validate the public API of a crate from the perspective of an external user, treating each documentation test as a separate temporary crate that imports the library as an external dependency

Files:

• docs/generic-message-fragmentation-and-re-assembly-design.md

🪛 LanguageTool

CHANGELOG.md

[typographical] ~53-~53: Two consecutive dots
Context: ... If the last value is not needed, use { .. } to ignore it: ```rust match err...

(DOUBLE_PUNCTUATION)

🔍 Remote MCP Deepwiki, Ref

Summary — additional repo facts relevant to reviewing PR #403 (concise):

• BackoffConfig.normalised behaviour: clamps initial_delay and max_delay to >=1ms and swaps them if initial_delay > max_delay; accept_loop invokes normalised before use (affects accept backoff behaviour).

• PacketParts / Envelope API: PacketParts exposes id(), correlation_id(), and payload() accessors; envelopes/packet types and correlation_id are first‑class in routing/response pipeline (used for multi‑packet/correlation).

• Fragmentation / error enum API change: FragmentError::IndexOverflow and FragmentationError::IndexOverflow carry a last: FragmentIndex field now (struct variant) — requires downstream pattern‑match updates; changelog/migration guidance present.

• missing_docs lint: Cargo.toml now sets missing_docs = "deny", enforcing documentation on public items (will cause compile failures where docs are missing).

• Tests and test utilities touched: tests updated to assert IndexOverflow payload, added correlation_id test helpers and test aliases; wireframe_testing utilities and fixtures are used widely (drive_with_bincode, processor, logger) — expect CI/test impacts from docs lint and API variant changes.

Tools used:

⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build-test

🔇 Additional comments (10)

tests/advanced/concurrency_loom.rs (1)

4-6: Attribute placement now correct.

The #![cfg(...)] attribute is properly positioned after the module-level documentation, aligning with the coding guideline that function attributes must be placed after doc comments.

src/server/runtime.rs (3)

60-64: Field documentation added.

The documentation clarifies the purpose of each delay field in the backoff configuration.

---

76-106: normalised() implementation is correct and well-documented.

The method:

• Clamps both delays to a minimum of 1 millisecond
• Swaps the delays when initial_delay > max_delay
• Returns Self for fluent usage
• Includes a doctest demonstrating the swap behaviour

---

381-381: Defensive normalisation invoked before use.

Calling backoff.normalised() at the start of accept_loop ensures the configuration satisfies invariants regardless of how the public fields were mutated. This addresses the concern raised in the past review comment.

src/fragment/tests.rs (1)

94-99: Test correctly updated for struct variant.

The assertion now matches the exact structure of FragmentError::IndexOverflow { last } and validates that last contains FragmentIndex::new(u32::MAX), aligning with the public API change documented in the CHANGELOG.

CHANGELOG.md (1)

15-60: Migration guide is comprehensive and clear.

The breaking change documentation:

• Explains the new last: FragmentIndex field clearly
• Provides before/after code examples for both affected error types
• Shows the { .. } pattern for ignoring the field when unnecessary

The static analysis hint flagging { .. } as "two consecutive dots" is a false positive; this is standard Rust syntax for ignoring remaining struct fields in pattern matching.

docs/generic-message-fragmentation-and-re-assembly-design.md (1)

381-383: Design documentation updated to reflect the new error variant structure.

The description now accurately documents that IndexOverflow carries a last: FragmentIndex field, maintaining consistency with the CHANGELOG and implementation.

tests/worlds/multi_packet.rs (2)

1-6: Keep module-level docs and cfg layout as-is

Maintain the //! module docs followed by #![cfg(not(loom))]; this satisfies the module-doc guideline and keeps the loom-specific configuration isolated to non-loom builds.

---

25-30: Retain the new MultiPacketWorld Rustdoc

Keep this struct-level doc; it clearly states the world’s purpose (multi-packet behaviours and back-pressure) and aligns with the new missing_docs = "deny" policy.

tests/worlds/correlation.rs (1)

20-45: Keep new docs and #[must_use] placement for correlation accessors

Leave these additions as written:

• The struct-level doc for CorrelationWorld and the method docs for set_expected/expected clearly describe the correlation-id contract and include examples, matching the missing_docs = "deny" requirement.
• #[must_use] is correctly placed after the doc comment and immediately before pub fn expected, now complying with the attribute-order guideline.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

tests/worlds/multi_packet.rs (1)

1-5: Module doc comment is split by the inner attribute.

The #![cfg(not(loom))] attribute at line 2 interrupts the module-level documentation. Other test world files in this PR (e.g., tests/worlds/fragment/mod.rs, tests/worlds/stream_end.rs) place this attribute after the complete //! doc block.

Move the attribute after the module documentation for consistency:

 //! Test world for multi-packet channel scenarios.
+//!
+//! Provides [`MultiPacketWorld`] to verify message ordering, back-pressure
+//! handling, and channel lifecycle in cucumber-based behaviour tests.
 #![cfg(not(loom))]
-//!
-//! Provides [`MultiPacketWorld`] to verify message ordering, back-pressure
-//! handling, and channel lifecycle in cucumber-based behaviour tests.

src/connection.rs (1)

1-6: File exceeds 400-line limit.

This file is 992 lines, well above the 400-line threshold specified in your coding guidelines. Decompose this module into smaller, domain-focused submodules (e.g., separate ActorState, MultiPacketContext, event handling) in a follow-up PR.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 920257e and 9391453.

📒 Files selected for processing (15)

• Cargo.toml (1 hunks)
• src/app/envelope.rs (1 hunks)
• src/connection.rs (1 hunks)
• src/connection/test_support.rs (2 hunks)
• src/fragment/error.rs (2 hunks)
• src/push/queues/errors.rs (1 hunks)
• src/push/queues/mod.rs (1 hunks)
• src/server/runtime.rs (2 hunks)
• tests/advanced/concurrency_loom.rs (1 hunks)
• tests/common/mod.rs (1 hunks)
• tests/worlds/correlation.rs (1 hunks)
• tests/worlds/fragment/mod.rs (1 hunks)
• tests/worlds/multi_packet.rs (1 hunks)
• tests/worlds/panic.rs (1 hunks)
• tests/worlds/stream_end.rs (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

**/*.rs: Run make check-fmt (cargo fmt --workspace -- --check) before committing to validate Rust formatting across the entire workspace without modifying files.
Run make lint (cargo clippy --workspace --all-targets --all-features -- -D warnings) before committing to lint every target with all features enabled and deny all Clippy warnings.
Run make test (cargo test --workspace) before committing to run the full workspace test suite.
Clippy warnings MUST be disallowed. Fix any warnings emitted during tests in the code itself rather than silencing them.
Use make fmt (cargo fmt --workspace) to apply formatting fixes reported by the formatter check.
Where a Rust function is too long, extract meaningfully named helper functions adhering to separation of concerns and CQRS.
Where a Rust function has too many parameters, group related parameters in meaningfully named structs.
Where a Rust function is returning a large error, consider using Arc to reduce the amount of data returned.
Write unit and behavioural tests for new Rust functionality. Run both before and after making any change.
Every Rust module must begin with a module level (//!) comment explaining the module's purpose and utility.
Document public Rust APIs using Rustdoc comments (///) so documentation can be generated with cargo doc.
Prefer immutable data and avoid unnecessary mut bindings in Rust code.
Avoid unsafe code in Rust unless absolutely necessary, and document any usage clearly with a 'SAFETY' comment.
Place function attributes after doc comments in Rust code.
Do not use return in single-line Rust functions.
Use predicate functions for Rust conditional criteria with more than two branches.
Lints must not be silenced in Rust except as a last resort. Lint rule suppressions must be tightly scoped and include a clear reason.
Use concat!() to combine long string literals in Rust rather than escaping newlines with a backslash.
Prefer single-line versions of Rust functions where...

Files:

• src/fragment/error.rs
• tests/worlds/multi_packet.rs
• src/push/queues/errors.rs
• tests/common/mod.rs
• tests/worlds/fragment/mod.rs
• tests/worlds/stream_end.rs
• src/app/envelope.rs
• tests/worlds/panic.rs
• src/push/queues/mod.rs
• src/connection.rs
• tests/advanced/concurrency_loom.rs
• tests/worlds/correlation.rs
• src/connection/test_support.rs
• src/server/runtime.rs

---

⚙️ CodeRabbit configuration file

**/*.rs: * Seek to keep the cognitive complexity of functions no more than 9.

• Adhere to single responsibility and CQRS
• Place function attributes after doc comments.
• Do not use return in single-line functions.
• Move conditionals with >2 branches into a predicate function.
• Avoid unsafe unless absolutely necessary.
• Every module must begin with a //! doc comment that explains the module's purpose and utility.
• Comments and docs must follow en-GB-oxendict (-ize / -yse / -our) spelling and grammar
• Lints must not be silenced except as a last resort.
  • #[allow] is forbidden.
  • Only narrowly scoped #[expect(lint, reason = "...")] is allowed.
  • No lint groups, no blanket or file-wide suppression.
  • Include FIXME: with link if a fix is expected.
• Where code is only used by specific features, it must be conditionally compiled or a conditional expectation for unused_code applied.
• Use rstest fixtures for shared setup and to avoid repetition between tests.
• Replace duplicated tests with #[rstest(...)] parameterised cases.
• Prefer mockall for mocks/stubs.
• Prefer .expect() over .unwrap() in tests.
• .expect() and .unwrap() are forbidden outside of tests. Errors must be propagated.
• Ensure that any API or behavioural changes are reflected in the documentation in docs/
• Ensure that any completed roadmap steps are recorded in the appropriate roadmap in docs/
• Files must not exceed 400 lines in length
  • Large modules must be decomposed
  • Long match statements or dispatch tables should be decomposed by domain and collocated with targets
  • Large blocks of inline data (e.g., test fixtures, constants or templates) must be moved to external files and inlined at compile-time or loaded at run-time.
• Environment access (env::set_var and env::remove_var) are always unsafe in Rust 2024 and MUST be marked as such
  • For testing of functionality depending upon environment variables, dependency injection and...

Files:

• src/fragment/error.rs
• tests/worlds/multi_packet.rs
• src/push/queues/errors.rs
• tests/common/mod.rs
• tests/worlds/fragment/mod.rs
• tests/worlds/stream_end.rs
• src/app/envelope.rs
• tests/worlds/panic.rs
• src/push/queues/mod.rs
• src/connection.rs
• tests/advanced/concurrency_loom.rs
• tests/worlds/correlation.rs
• src/connection/test_support.rs
• src/server/runtime.rs

Cargo.toml

📄 CodeRabbit inference engine (AGENTS.md)

Cargo.toml: Use explicit version ranges in Cargo.toml and keep dependencies up-to-date.
All crate versions specified in Cargo.toml must use SemVer-compatible caret requirements (e.g., some-crate = "1.2.3"). Wildcard (*) or open-ended inequality (>=) version requirements are strictly forbidden. Tilde requirements (~) should only be used where a dependency must be locked to patch-level updates for a specific, documented reason.

Files:

• Cargo.toml

🧬 Code graph analysis (1)

src/app/envelope.rs (5)

src/connection/test_support.rs (4)

• id (24-24)
• id (36-36)
• correlation_id (26-26)
• correlation_id (38-38)

tests/lifecycle.rs (2)

• id (151-151)
• correlation_id (153-153)

tests/routes.rs (2)

• id (42-42)
• correlation_id (45-45)

src/connection.rs (1)

• correlation_id (236-241)

src/correlation.rs (3)

• correlation_id (11-11)
• correlation_id (18-18)
• correlation_id (24-24)

🔍 Remote MCP Deepwiki, Ref

Now I have sufficient context. Let me compile the findings:

Additional Context for PR #403 Review

Repository Context

The wireframe codebase is progressing toward version 1.0, which introduces significant public API expansions and breaking changes, including new traits (WireframeProtocol), enhanced Response enum variants (Vec, Stream, Empty), new PushHandle APIs for asynchronous server pushes, and generic WireframeError<E> for error handling.

BackoffConfig Changes

The PR adds initial_delay and max_delay fields to BackoffConfig and introduces the normalised() method. The normalised() method ensures critical invariants: it clamps both delays to a minimum of 1 millisecond and swaps the values if initial_delay exceeds max_delay. This configuration is used by the WireframeServer's accept_loop to implement exponential backoff during connection acceptance failures.

PacketParts Public API Changes

The PR adds three new public accessor methods to PacketParts:

• pub const fn id(&self) -> u32
• pub const fn correlation_id(&self) -> Option<u64>
• pub fn payload(self) -> Vec<u8> (consuming function)

These complement existing struct fields and align with the library's recent introduction of correlation_id functionality for tying packets to requests in multi-packet streaming responses.

Documentation Lint Configuration

The missing_docs = "deny" lint configuration added to Cargo.toml enforces that all public items must have documentation. By default, the missing_docs lint is allowed in Rust; setting it to "deny" treats missing documentation as a hard error rather than a warning, supporting the PR's stated goal of preparing for stricter documentation requirements.

Breaking Changes Context

While the PR's stated objective focuses on documentation standardization, it's part of a broader trajectory toward version 1.0 that includes public API breaking changes. The error variant changes (adding fields to FragmentError::MessageMismatch, FragmentError::IndexMismatch, and FragmentationError::IndexOverflow) represent changes to public enum structures that may affect exhaustive pattern matching in downstream code.

⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build-test

🔇 Additional comments (19)

tests/worlds/panic.rs (1)

78-83: LGTM!

The added doc comment accurately describes the test world's purpose and aligns with the PR's documentation standardization goals.

Cargo.toml (1)

118-122: LGTM!

Adding missing_docs = "deny" enforces documentation coverage for all public items, aligning with the coding guidelines requiring Rustdoc comments for public APIs. This is a sensible change ahead of stricter documentation requirements.

src/push/queues/mod.rs (1)

50-57: LGTM!

The doc comments for PushPriority variants are concise and clearly describe the semantic difference between high and low priority queues.

tests/worlds/correlation.rs (2)

19-24: LGTM!

The doc comment for CorrelationWorld clearly describes the test world's purpose.

---

26-34: LGTM!

The doc comment and example for set_expected are clear and useful.

src/connection/test_support.rs (2)

69-70: LGTM!

The field-level doc comment clearly describes the purpose of the out field for test assertions.

---

177-186: LGTM!

The doc comments on ActorStateSnapshot fields provide clear, concise descriptions of each lifecycle flag and counter. This aligns well with the PR's documentation standardisation goals.

tests/worlds/fragment/mod.rs (1)

32-33: LGTM!

The doc comment succinctly describes the struct's role in behavioural testing. Good use of en-GB spelling.

tests/worlds/stream_end.rs (1)

24-25: LGTM!

Clear and concise doc comment describing the struct's testing purpose.

tests/worlds/multi_packet.rs (1)

26-27: LGTM!

The struct doc comment is well-placed and uses correct en-GB spelling ("behaviours").

src/push/queues/errors.rs (1)

28-33: LGTM!

Field-level doc comments clearly describe what each capacity value represents. This aligns with the PR's documentation standardisation effort and supports the missing_docs = "deny" lint configuration.

src/connection.rs (1)

98-103: Documentation additions are appropriate and concise.

The field-level doc comments accurately describe the purpose of queues and handle within ConnectionChannels<F>. This aligns with the PR's goal of standardizing rustdoc style.

src/server/runtime.rs (1)

76-106: Well-designed normalisation method.

The normalised() method correctly handles edge cases (zero durations, inverted values) and uses British spelling per coding guidelines. The doctest clearly demonstrates the swap behaviour.

src/app/envelope.rs (3)

125-136: Accessor method is well-formed.

The id() accessor is correctly marked const fn and #[must_use]. The doctest is clear and demonstrates the expected behaviour.

---

138-149: Accessor aligns with CorrelatableFrame trait pattern.

The correlation_id() method mirrors the trait method signature seen in src/correlation.rs (line 10). Using const fn is appropriate for simple field access.

---

151-162: Consuming accessor transfers ownership correctly.

The payload(self) method intentionally consumes PacketParts to transfer ownership of the Vec<u8>. This is used in From<PacketParts> for Envelope at line 210, confirming the design is intentional.

tests/common/mod.rs (1)

22-25: Type alias documentation is clear and appropriate.

The doc comments succinctly describe the purpose of TestApp and TestResult for test scaffolding. This aligns with the PR's documentation standardisation goals.

src/fragment/error.rs (2)

27-51: Field documentation is well-structured.

The doc comments for expected, found, and last fields clearly describe their semantic meaning, aiding debugging and error handling.

---

46-50: The review comment is incorrect. IndexOverflow is already defined as a struct variant in both FragmentError and FragmentationError, and all existing code already uses compatible pattern matching syntax. All references to IndexOverflow in the codebase use matches!(err, FragmentError::IndexOverflow { .. }) or construct it as FragmentError::IndexOverflow { last: ... }. There are no exhaustive pattern matches like FragmentError::IndexOverflow => ... that would fail to compile. If this variant structure changed, it was already completed and all downstream code has been updated.

Likely an incorrect or invalid review comment.

[leynos]

@coderabbitai please create a new GitHub issue for the following:

src/connection.rs (1)

    1-6: File exceeds 400-line limit.

    This file is 992 lines, well above the 400-line threshold specified in your coding guidelines. Decompose this module into smaller, domain-focused submodules (e.g., separate ActorState, MultiPacketContext, event handling) in a follow-up PR.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
gh issue create \
  --title "Refactor src/connection.rs: exceeds 400-line coding guideline" \
  --body "## Issue Description

The file \`src/connection.rs\` currently contains 992 lines, significantly exceeding the 400-line threshold specified in the coding guidelines.

## Requested Action

Decompose this module into smaller, domain-focused submodules in a follow-up PR. Suggested areas for extraction:
- ActorState
- MultiPacketContext
- Event handling

## Context

This issue was identified during the review of PR #403.

**Related PR:** https://github.com/leynos/wireframe/pull/403
**Requested by:** @leynos" \
  --assignee leynos

Length of output: 46

---

@leynos: I've created GitHub issue #404 for refactoring src/connection.rs to comply with the 400-line coding guideline: #404

The issue has been assigned to you and includes the context from this PR review.