Name the consuming getter `into_payload`

[coderabbitai]

Follow Rust idioms for consuming accessors. Provide a non-breaking path by adding into_payload(self) and deprecating payload(self).

Proposed Change

     #[must_use]
-    pub fn payload(self) -> Vec<u8> { self.payload }
+    pub fn into_payload(self) -> Vec<u8> { self.payload }

Tasks

• Add into_payload(self) -> Vec<u8> method to PacketParts
• Deprecate existing payload(self) -> Vec<u8> method
• Update internal examples and call sites to use into_payload()
• Ensure backwards compatibility during transition period

Context

Raised in PR #282: #282
Original comment: #282 (comment)

Requested by: @leynos

[leynos]

@coderabbitai looking at the codebase, is this issue still relevant? If the issue has been fixed in the code, does the documentation reflect this?

If it is still relevant, please provide an assessment of the issue criticality (critical, high, medium or low), based on risk of the issue impacting the user and the anticipated blast radius.\n\nOnce a decision has been made, apply the appropriate label.

If the issue is documentation ONLY (i.e., no code changes needed), apply the documentation label in addition to the appropriate criticality label.

Please also provide an impact of the required changes.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch issue `#305` details
gh issue view 305 --json title,body,labels,state,author,createdAt

Length of output: 951

---

🏁 Script executed:

#!/bin/bash
# Find PacketParts definition and check for payload/into_payload methods
echo "=== Finding PacketParts struct definition ==="
rg -n "struct PacketParts" --type rust

echo -e "\n=== Checking for payload method implementations ==="
rg -n "pub fn payload\(self\)" --type rust -A 2

echo -e "\n=== Checking for into_payload method ==="
rg -n "pub fn into_payload\(self\)" --type rust -A 2

echo -e "\n=== Finding PacketParts implementation block ==="
ast-grep --pattern $'impl PacketParts {
  $$$
}'

Length of output: 6224

---

🏁 Script executed:

#!/bin/bash
# Search for usage of PacketParts payload method
echo "=== Finding usages of .payload() on PacketParts ==="
rg -n "\.payload\(\)" --type rust -C 2

echo -e "\n=== Check for public API documentation ==="
fd -e md README CHANGELOG

echo -e "\n=== Check examples directory ==="
fd -e rs . examples

echo -e "\n=== Count total usages of .payload() calls ==="
rg "\.payload\(\)" --type rust | wc -l

Length of output: 12746

---

🏁 Script executed:

#!/bin/bash
# Check examples for payload method usage
echo "=== Checking examples for .payload() usage ==="
rg -n "\.payload\(\)" examples/

echo -e "\n=== Check README content ==="
if [ -f README.md ]; then
    cat README.md
else
    echo "No README.md found"
fi

echo -e "\n=== Check for API documentation in docs ==="
fd -e md . docs 2>/dev/null || echo "No docs directory found"

Length of output: 14022

---

@leynos, I've analyzed the codebase and issue #305 is still relevant. The change has not been implemented yet.

Current Status

The payload(self) consuming method still exists in PacketParts at src/app/envelope.rs:198, and the idiomatic into_payload(self) method has not been added. Interestingly, another struct (Reassembler) already uses the into_payload pattern at src/fragment/reassembler.rs:76, demonstrating the preferred naming convention.

Blast Radius

Found 36 usages of .payload() across the codebase:

• Tests: Majority of usages (packet_parts.rs, response.rs, middleware_order.rs, etc.)
• Source code: middleware.rs, connection/test_support.rs, app/fragmentation_state.rs, app/envelope.rs, fragment/packet.rs
• Examples: No direct usage found

Documentation Impact

The documentation does not reflect the proposed idiomatic naming:

• README.md custom envelope example shows .payload() usage
• API documentation at line 195 in src/app/envelope.rs includes .payload() in the doctest

Both would need updating to demonstrate the new into_payload() method.

Criticality Assessment: LOW

Rationale:

• This is an API consistency improvement, not a bug
• Functionality works correctly; only the naming isn't idiomatic Rust
• Deprecation path ensures backwards compatibility
• Impact is developer experience, not runtime behaviour
• Risk to users is minimal (deprecation warnings, not breakage)
• Moderate blast radius (36 usages, primarily in tests)

Impact of Required Changes

Code changes:

1. Add into_payload(self) -> Vec<u8> method to PacketParts
2. Deprecate existing payload(self) method with appropriate annotation
3. Update ~36 call sites throughout codebase
4. Similar change needed for fragment/packet.rs

Documentation changes:

1. Update README.md custom envelope example
2. Update API documentation examples
3. Update any migration guides if they exist

Not documentation-only — code changes are required.

---

🏁 Script executed:

#!/bin/bash
# Apply the 'low' criticality label to issue `#305`
gh issue edit 305 --add-label "low"

Length of output: 46

---

The low criticality label has been applied to issue #305.

Summary

✅ Issue is still relevant — into_payload has not been implemented yet
✅ Criticality: LOW — API consistency improvement with minimal user risk
✅ Requires code + documentation changes — not documentation-only
✅ Label applied — issue tagged with low criticality

The issue can be addressed when convenient, as it improves developer experience without affecting existing functionality. The deprecation path ensures smooth migration for users.

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Approach

Rename the consuming accessor method payload(self) to into_payload(self) on PacketParts to follow Rust naming conventions, implementing this as a direct breaking change since the project is pre-1.0.

Observations

The wireframe codebase is a Rust networking library with packet handling in src/app/envelope.rs where PacketParts is defined. The codebase already follows the into_* naming convention for consuming accessors consistently across 15+ methods (e.g., into_inner(), into_metadata(), into_body()). The PacketParts::payload(self) method is an outlier that consumes self without the conventional into_ prefix. There are 35 call sites across 20 files that currently use payload(). The codebase has established deprecation patterns using #[deprecated(since = "VERSION", note = "...")] attributes.

Implementation Steps

Rename Method and Update Call Sites

Rename the payload() method to into_payload() on PacketParts and update all call sites throughout the codebase as a single breaking change.

Task 1: Rename payload Method to into_payload

Rename the consuming accessor method to follow Rust naming conventions.

• Rename pub fn payload(self) -> Vec<u8> to pub fn into_payload(self) -> Vec<u8> in src/app/envelope.rs
• Keep the #[must_use] attribute
• Update the documentation comment to reflect the new method name while maintaining the description that this method consumes the parts and returns the raw payload bytes

Task 2: Update Documentation Examples

Fix doc examples in the PacketParts definition to use the new method name.

• Update the doc example at lines 58-60 in src/app/envelope.rs (struct-level docs) to use into_payload() instead of payload()
• Update the doc example at lines 191-195 in src/app/envelope.rs (method-level docs) to use into_payload()

Task 3: Update Production Code

Update production code call sites to use the new method name.

• Update src/app/envelope.rs (5 occurrences) - Packet trait implementations and conversions
• Update src/app/fragmentation_state.rs (1 occurrence) - Fragment decoding logic
• Update src/middleware.rs (1 occurrence) - Envelope to ServiceResponse conversion
• Update src/fragment/packet.rs (1 occurrence) - Fragmentation logic
• Update src/fragment/reassembler.rs (1 occurrence) - Message decoding after reassembly
• Update src/connection/test_support.rs (2 occurrences) - Test helper implementations

Task 4: Update Test Code

Update test file call sites to use the new method name.

• Update tests/packet_parts.rs - Direct PacketParts tests
• Update src/client/tests/messaging.rs (2 occurrences) - Client messaging tests
• Update remaining test files (approximately 13 occurrences across 10 additional test files) that call parts.payload() or similar patterns

🤖 Prompt for AI agents

Rename the `payload()` method to `into_payload()` on `PacketParts` and update
all call sites throughout the codebase as a single breaking change to follow
Rust naming conventions.

**Rename the payload method:**
- In `src/app/envelope.rs`, rename `pub fn payload(self) -> Vec<u8>` to `pub fn
into_payload(self) -> Vec<u8>`
- Keep the `#[must_use]` attribute
- Update the documentation comment to reflect the new method name while
maintaining the description that this method consumes the parts and returns the
raw payload bytes

**Update documentation examples:**
- Update the doc example at lines 58-60 in `src/app/envelope.rs` (struct-level
docs) to use `into_payload()` instead of `payload()`
- Update the doc example at lines 191-195 in `src/app/envelope.rs` (method-level
docs) to use `into_payload()`

**Update production code call sites:**
- `src/app/envelope.rs` (5 occurrences) - Update Packet trait implementations
and conversions to use `into_payload()`
- `src/app/fragmentation_state.rs` (1 occurrence) - Update fragment decoding
logic
- `src/middleware.rs` (1 occurrence) - Update envelope to ServiceResponse
conversion
- `src/fragment/packet.rs` (1 occurrence) - Update fragmentation logic
- `src/fragment/reassembler.rs` (1 occurrence) - Update message decoding after
reassembly
- `src/connection/test_support.rs` (2 occurrences) - Update test helper
implementations

**Update test code call sites:**
- `tests/packet_parts.rs` - Update direct PacketParts tests
- `src/client/tests/messaging.rs` (2 occurrences) - Update client messaging
tests
- Update remaining test files (approximately 13 occurrences across 10 additional
test files) that call `parts.payload()` or similar patterns

---

🚀 Next Steps

🤖 All AI agent prompts combined

Rename the `payload()` method to `into_payload()` on `PacketParts` and update
all call sites throughout the codebase as a single breaking change to follow
Rust naming conventions.

**Rename the payload method:**
- In `src/app/envelope.rs`, rename `pub fn payload(self) -> Vec<u8>` to `pub fn
into_payload(self) -> Vec<u8>`
- Keep the `#[must_use]` attribute
- Update the documentation comment to reflect the new method name while
maintaining the description that this method consumes the parts and returns the
raw payload bytes

**Update documentation examples:**
- Update the doc example at lines 58-60 in `src/app/envelope.rs` (struct-level
docs) to use `into_payload()` instead of `payload()`
- Update the doc example at lines 191-195 in `src/app/envelope.rs` (method-level
docs) to use `into_payload()`

**Update production code call sites:**
- `src/app/envelope.rs` (5 occurrences) - Update Packet trait implementations
and conversions to use `into_payload()`
- `src/app/fragmentation_state.rs` (1 occurrence) - Update fragment decoding
logic
- `src/middleware.rs` (1 occurrence) - Update envelope to ServiceResponse
conversion
- `src/fragment/packet.rs` (1 occurrence) - Update fragmentation logic
- `src/fragment/reassembler.rs` (1 occurrence) - Update message decoding after
reassembly
- `src/connection/test_support.rs` (2 occurrences) - Update test helper
implementations

**Update test code call sites:**
- `tests/packet_parts.rs` - Update direct PacketParts tests
- `src/client/tests/messaging.rs` (2 occurrences) - Update client messaging
tests
- Update remaining test files (approximately 13 occurrences across 10 additional
test files) that call `parts.payload()` or similar patterns

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[leynos]

@coderabbitai As we are pre-1.0 we can make a breaking change here. I would rather avoid backwards compat at this stage.

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!