Epic: Zero-copy frame API (breaking) – adopt Bytes as Frame

[coderabbitai]

Summary
Track the effort to migrate the public Frame type from Vec to Bytes to enable zero-copy decoding and remove the final copying step in the frame processor.

Context and backlinks

• Requested by @leynos
• PR: Optimize frame processor to reduce memory allocations #283
• Comment: Optimize frame processor to reduce memory allocations #283 (comment)

Impact

• This is a breaking change and requires a major version bump (e.g., v1 → v2).
• Downstream users consuming the Frame type will be affected.

Constraints observed today

• BoxedFrameProcessor in app.rs:31 currently constrains Frame = Vec.
• The middleware layer (ServiceRequest, ServiceResponse) operates on Vec.
• Multiple trait bounds across the codebase expect Frame = Vec.

Scope

• Plan and track the design, analysis, benchmarks, and rollout for a Bytes-based Frame API and zero-copy decoding.

Deliverables

• A design proposal outlining options (e.g., Bytes-only vs. dual support), risks, and trade-offs.
• A migration plan and compatibility strategy for downstream users.
• A benchmarking plan and baseline measurements to validate performance goals.
• A release/rollout plan for a major version update.

Definition of done

• Design approved.
• Follow-up analysis issues closed.
• Benchmarks planned with acceptance thresholds.
• Release plan documented (including migration guide outline).

[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 details of issue `#284`
gh issue view 284 --json title,body,labels,state,createdAt,author

Length of output: 1587

---

🏁 Script executed:

#!/bin/bash
# Check if app.rs exists and look at line 31 for BoxedFrameProcessor
fd -t f 'app.rs$' --exec cat {}

echo "--- Separator ---"

# Search for Frame type definitions and aliases
rg -n "type Frame" -A 2 -B 2

echo "--- Separator ---"

# Search for BoxedFrameProcessor definition/usage
rg -n "BoxedFrameProcessor" -C 3

echo "--- Separator ---"

# Search for Frame trait or struct definitions
ast-grep --pattern 'struct Frame'
ast-grep --pattern 'type Frame = $_'

echo "--- Separator ---"

# Check for Bytes usage in relation to Frame
rg -n "Bytes" --type rust | head -20

Length of output: 16462

---

🏁 Script executed:

#!/bin/bash
# Search for app module structure
fd -t f -e rs . src/app 2>/dev/null | head -20

echo "--- Separator ---"

# Look for files in src directory
ls -la src/ 2>/dev/null

echo "--- Separator ---"

# Search for ServiceRequest and ServiceResponse
rg -n "ServiceRequest|ServiceResponse" -C 3

echo "--- Separator ---"

# Search for middleware mentions
rg -n "middleware" -i -C 2

echo "--- Separator ---"

# Look for the Envelope type and how it's used
rg -n "pub struct Envelope" -A 5

Length of output: 83484

---

🏁 Script executed:

#!/bin/bash
# Check PR `#283` for context
gh pr view 283 --json title,body,state,mergedAt,closedAt 2>/dev/null || echo "PR 283 not found or not accessible"

echo "--- Separator ---"

# Search for documentation about zero-copy or Bytes migration
rg -i "zero.copy|bytes.*frame|frame.*bytes" --type md -C 2 | head -100

echo "--- Separator ---"

# Check if there's documentation specifically about this Epic
fd -t f -e md . docs | xargs rg -l "zero-copy|Epic.*284" 2>/dev/null

echo "--- Separator ---"

# Look for FrameContainer definition to understand the constraint
rg -n "struct FrameContainer" -A 10

Length of output: 10760

---

🏁 Script executed:

#!/bin/bash
# Read the efficiency report mentioned in PR `#283`
cat docs/efficiency-report.md 2>/dev/null || echo "Efficiency report not found"

echo "--- Separator ---"

# Check the current state - is Frame still Vec<u8> in most places?
rg -n "type Frame = Vec<u8>" --type rust

echo "--- Separator ---"

# Check for any Bytes-based Frame implementations
rg -n "type Frame = Bytes" --type rust

echo "--- Separator ---"

# Look for any recent changes or TODOs related to this migration
rg -i "TODO.*bytes|TODO.*zero.copy|FIXME.*bytes" --type rust -C 2

Length of output: 338

---

🏁 Script executed:

#!/bin/bash
# Check the app module structure more closely
cat src/app/mod.rs | head -50

echo "--- Separator ---"

# Look at src/app/frame_handling.rs more closely since it uses ServiceRequest
cat src/app/frame_handling.rs | head -150

echo "--- Separator ---"

# Check if there are trait bounds that constrain Frame = Vec<u8>
rg -n "Frame.*Vec<u8>|where.*Frame.*=" --type rust src/ | head -30

echo "--- Separator ---"

# Check FrameLike trait definition since WireframeProtocol uses it
rg -n "trait FrameLike" -A 10 --type rust

Length of output: 6441

---

🏁 Script executed:

#!/bin/bash
# Check the zero-copy documentation in the users guide
grep -A 20 "Zero-copy payload extraction" docs/users-guide.md

echo "--- Separator ---"

# Check the execution plan document for zero-copy
cat docs/execplans/9-1-3-enable-zero-copy-payload-extraction-for-codecs.md 2>/dev/null | head -100

echo "--- Separator ---"

# Check roadmap for this feature
grep -B 5 -A 10 "zero-copy\|Bytes.*Frame" docs/roadmap.md

echo "--- Separator ---"

# Verify current middleware implementation uses Vec<u8>
cat src/middleware.rs | grep -A 5 -B 5 "struct ServiceRequest\|struct ServiceResponse"

Length of output: 6946

---

🏁 Script executed:

#!/bin/bash
# Check if there are any benchmarks or performance tests
fd -t f bench --type f 2>/dev/null | head -10

echo "--- Separator ---"

# Look for any existing design docs or ADRs about Bytes migration
fd -t f -e md . docs | xargs rg -l "Frame.*Bytes.*migration|migrate.*Frame.*Bytes" 2>/dev/null

echo "--- Separator ---"

# Check for any usage of Bytes in the codebase besides codec
rg -n "use bytes::" --type rust src/ | head -20

echo "--- Separator ---"

# Apply the appropriate labels to the issue
gh issue edit 284 --add-label "medium" 2>/dev/null || echo "Could not add medium label"

Length of output: 1052

---

@leynos, I've analysed the codebase to assess issue #284. Here's my findings:

Issue Status: STILL RELEVANT

The issue tracks migration of the Frame type from Vec to Bytes to enable zero-copy decoding. Whilst partial progress has been made, the core architectural change remains outstanding.

Current State

What's been completed:

• LengthDelimitedFrameCodec at src/codec.rs:253 uses type Frame = Bytes
• Zero-copy payload extraction implemented (ExecPlan 9.1.3 completed)
• The FrameCodec trait supports frame_payload_bytes method returning Bytes

What remains:

• ServiceRequest and ServiceResponse in src/middleware.rs (lines 40, 81) still use FrameContainer<Vec<u8>>
• The middleware layer — the primary constraint blocking full zero-copy operation
• Multiple trait bounds across the codebase still expect Vec
• Migration plan and benchmarks need completion

Note on issue description: The specific reference to "BoxedFrameProcessor in app.rs:31" appears outdated; that file structure has been refactored. The actual constraint is in the middleware layer.

Documentation Status

Documentation partially reflects the current state:

• The users guide documents zero-copy extraction for codecs
• No documentation exists yet about the planned Frame type migration Epic
• The efficiency report mentioned in PR #283 was not committed to the repository

Criticality Assessment: MEDIUM

Rationale:

• User Impact: Medium — This is a performance optimisation that reduces memory copying in high-throughput scenarios, not a correctness issue
• Blast Radius: Medium-High — Affects the middleware layer, all custom middleware implementations, and downstream users consuming the Frame type
• Risk: Medium — Well-scoped architectural change with clear migration path, but requires careful coordination
• Urgency: Non-critical — System functions correctly with Vec; this is a planned enhancement

Not high/critical because the system works correctly today and partial optimisations are already in place. Not low because this represents significant architectural work with broad API impact.

Impact of Required Changes

Breaking changes required:

1. Modify ServiceRequest and ServiceResponse to use Bytes instead of Vec<u8>
2. Update all middleware implementations (Transform, Service traits)
3. Update handler interfaces that consume frames
4. Modify trait bounds expecting Vec<u8>

Deliverables needed (as outlined in the issue):

• Design proposal comparing options (Bytes-only vs dual support)
• Migration guide for downstream users
• Benchmarking plan with baseline measurements
• Release plan for major version update (v1 → v2)

Estimated scope: This is genuine Epic-level work requiring coordinated changes across multiple modules and extensive testing.

---

I'll now apply the appropriate labels:

---

🏁 Script executed:

#!/bin/bash
# Apply medium criticality label
gh issue edit 284 --add-label "medium"

echo "Label applied successfully"

Length of output: 73

---

Perfect! I've successfully applied the medium criticality label to issue #284.

Summary

Issue Status: Still relevant and requires code changes

Criticality: Medium — This is a performance optimization with significant architectural impact but not urgent

Documentation Status: The issue is not documentation-only. It requires substantial code changes to the middleware layer, trait implementations, and API surface. Therefore, I have not applied the documentation label.

Next Steps:
The Epic deliverables outlined in the issue remain valid:

• Design proposal needed
• Migration plan required
• Benchmarking baseline measurements
• Release plan for major version bump

The partial work completed (zero-copy codec extraction) provides a foundation, but the core middleware migration work remains. This should be prioritized based on performance requirements and user feedback about high-throughput scenarios.

[leynos]

@coderabbitai would it be fair to say that this depends upon #288?

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

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

Length of output: 1166

---

@leynos, yes, that's a fair assessment. Issue #284 has a practical dependency on issue #288.

Here's the relationship:

Issue #288 (Release planning: v2.0) provides:

• Versioning and release strategy
• Migration guide outline for downstream users
• Timeline and coordination checklist
• Communication plan

Issue #284 (Frame type migration Epic) contains:

• The actual breaking technical changes
• Middleware layer modifications
• API surface changes

Dependency rationale

Whilst the technical work in #284 could proceed in parallel with the planning in #288, you wouldn't want to merge or complete #284 without having #288's deliverables in place first. Specifically:

1. The migration guide from #288 needs to document the breaking changes that #284 introduces
2. The release strategy and timeline ensure coordinated delivery
3. The communication plan prepares downstream users for the v2.0 breaking changes

So #284 blocks on #288 from a release readiness perspective, even though development work can overlap.

Recommendation: Consider updating #284 to explicitly list #288 as a prerequisite in the Epic description, or add "blocked by #288" to clarify the execution order.

🐰📋

[leynos]

@coderabbitai Similarly #286 and #287?

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch details of issues `#286` and `#287`
gh issue view 286 --json title,body,labels,state,createdAt,author,url

echo "--- Separator ---"

gh issue view 287 --json title,body,labels,state,createdAt,author,url

Length of output: 2472

---

@leynos, absolutely yes! Issues #286 and #287 are foundational dependencies for #284, though they serve a different role than #288.

Here's the dependency structure:

Issues #286 and #287: Discovery prerequisites

Issue #286 (Middleware layer analysis):

• Maps where Vec<u8> is expected in ServiceRequest/ServiceResponse
• Identifies integration points impacted by frame type changes
• Informs adaptation strategies

Issue #287 (Trait bounds inventory):

• Catalogues all traits, impls, and generics tied to Frame = Vec<u8>
• Documents generalisation paths and risks
• Provides scope assessment

These two issues are inputs to the design proposal mentioned in #284's deliverables. You cannot meaningfully design the migration without understanding:

1. Where middleware constraints exist (#286)
2. What trait bounds need updating (#287)

Dependency flow

The logical execution order is:

`#286` + `#287` (analysis & discovery)
    ↓
`#284` (technical implementation)
    ↓
`#288` (release coordination)

• Analysis: Middleware layer (ServiceRequest/ServiceResponse) dependency on Vec<u8> #286 and #287 inform what needs to change and how to approach it
• Epic: Zero-copy frame API (breaking) – adopt Bytes as Frame #284 performs the actual technical work
• Release planning: v2.0 for zero-copy frame API migration #288 coordinates when and how to release it

Recommendation

Mark #284 as blocked by #286 and #287. These analysis tasks should be completed first to derisk the Epic and inform the design decisions. All three issues feed into #288 for coordinated v2.0 delivery.

🐰🔍