Untangle layering: move fragment_packet from app to dedicated module

[coderabbitai]

Context

Related to PR #424 which demonstrates the pattern for modularisation by refactoring the connection module.

Request from: @leynos
Source: #424

Objective

Untangle layering violation where fragment_packet is under app but used by the connection actor. Move it to a non-app module and re-export from app if needed to preserve the old path.

Current situation

• fragment_packet is defined in src/app/fragment_utils.rs:1
• Used by connection actor at src/connection.rs:52 and src/connection.rs:662
• This creates a layering violation where the connection module depends on app-specific utilities

Proposed solution

• Move fragment_packet to a non-app module (e.g., src/fragment/packet.rs)
• Re-export from app to preserve the old public API path if needed
• Update imports in src/connection.rs to reference the new location

Approach

Follow the pattern established in PR #424:

• Extract the functionality into a dedicated module
• Maintain public API compatibility through re-exports where appropriate
• Ensure all tests continue to pass after refactoring

[traycerai]

Plan

Observations

The fragment_packet function currently resides in file:src/app/fragment_utils.rs but is used by the connection actor (file:src/connection.rs) and internal app state (file:src/app/fragmentation_state.rs). This creates a layering violation where lower-level modules depend on app-specific utilities. The function primarily uses types from the fragment module (Fragmenter, FragmentationError, encode_fragment_payload) and only requires Packet and PacketParts from the app layer. A dedicated fragment module already exists with related functionality.

Approach

Following the modularization pattern from PR #424, extract fragment_packet into a new file:src/fragment/packet.rs module. Maintain backward compatibility by re-exporting the function from the original file:src/app/fragment_utils.rs location. Update internal imports to reference the new canonical location in the fragment module. This resolves the layering violation while preserving the public API surface.

Implementation Steps

1. Create New Fragment Packet Module

Create file:src/fragment/packet.rs with the following structure:

• Add module documentation explaining the purpose: "Shared helpers for applying transport-level fragmentation to packets"
• Move the entire fragment_packet function from file:src/app/fragment_utils.rs (lines 8-41)
• Update imports to reference:
  • crate::app::{Packet, PacketParts} (keep these as they define the packet abstraction)
  • crate::fragment::{FragmentationError, Fragmenter, encode_fragment_payload} (use relative imports: super::{...})

2. Update Fragment Module Exports

Modify file:src/fragment/mod.rs:

• Add pub mod packet; to the module declarations (after line 16, following the existing pattern)
• Add pub use packet::fragment_packet; to the re-exports section (around line 24, after the payload re-exports)

3. Maintain Backward Compatibility

Update file:src/app/fragment_utils.rs:

• Remove the function implementation (lines 8-41)
• Keep the module documentation (lines 1-2)
• Add a re-export: pub use crate::fragment::fragment_packet;
• Add a deprecation comment explaining the new location for future reference

4. Update Internal Imports

In file:src/connection.rs:

• Change line 53 from app::{Packet, fragment_utils::fragment_packet} to app::Packet, fragment::fragment_packet
• This removes the layering violation by importing directly from the fragment module

In file:src/app/fragmentation_state.rs:

• Change line 47 from crate::app::fragment_utils::fragment_packet(&self.fragmenter, packet) to crate::fragment::fragment_packet(&self.fragmenter, packet)
• This uses the canonical location within the same crate

5. Verify Module Structure

Ensure the module hierarchy is correct:

src/
├── app/
│   ├── fragment_utils.rs  (now just re-exports)
│   └── mod.rs             (keeps `pub mod fragment_utils;`)
└── fragment/
    ├── packet.rs          (new, contains fragment_packet)
    └── mod.rs             (updated with packet module)

6. Validation Checklist

• Verify all imports compile without errors
• Confirm fragment_packet is accessible via both paths:
  • New canonical: crate::fragment::fragment_packet
  • Legacy compatibility: crate::app::fragment_utils::fragment_packet
• Ensure no breaking changes to public API (function remains accessible at wireframe::app::fragment_utils::fragment_packet)
• Run existing tests to confirm functionality is preserved
• Check that connection module no longer depends on app module for fragmentation

Architecture Diagram

graph TD
    A[src/connection.rs] -->|uses| B[src/fragment/packet.rs]
    C[src/app/fragmentation_state.rs] -->|uses| B
    D[src/app/fragment_utils.rs] -->|re-exports| B
    B -->|depends on| E[src/app/envelope.rs<br/>Packet, PacketParts]
    B -->|depends on| F[src/fragment/fragmenter.rs<br/>Fragmenter]
    B -->|depends on| G[src/fragment/payload.rs<br/>encode_fragment_payload]
    B -->|depends on| H[src/fragment/error.rs<br/>FragmentationError]
    
    style B fill:#90EE90
    style D fill:#FFE4B5
    style A fill:#87CEEB
    style C fill:#87CEEB

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `fragment_packet` function currently resides in `file:src/app/fragment_utils.rs` but is used by the connection actor (`file:src/connection.rs`) and internal app state (`file:src/app/fragmentation_state.rs`). This creates a layering violation where lower-level modules depend on app-specific utilities. The function primarily uses types from the `fragment` module (`Fragmenter`, `FragmentationError`, `encode_fragment_payload`) and only requires `Packet` and `PacketParts` from the app layer. A dedicated `fragment` module already exists with related functionality.

## Approach

Following the modularization pattern from PR #424, extract `fragment_packet` into a new `file:src/fragment/packet.rs` module. Maintain backward compatibility by re-exporting the function from the original `file:src/app/fragment_utils.rs` location. Update internal imports to reference the new canonical location in the fragment module. This resolves the layering violation while preserving the public API surface.

## Implementation Steps

### 1. Create New Fragment Packet Module

Create `file:src/fragment/packet.rs` with the following structure:

- Add module documentation explaining the purpose: "Shared helpers for applying transport-level fragmentation to packets"
- Move the entire `fragment_packet` function from `file:src/app/fragment_utils.rs` (lines 8-41)
- Update imports to reference:
  - `crate::app::{Packet, PacketParts}` (keep these as they define the packet abstraction)
  - `crate::fragment::{FragmentationError, Fragmenter, encode_fragment_payload}` (use relative imports: `super::{...}`)

### 2. Update Fragment Module Exports

Modify `file:src/fragment/mod.rs`:

- Add `pub mod packet;` to the module declarations (after line 16, following the existing pattern)
- Add `pub use packet::fragment_packet;` to the re-exports section (around line 24, after the `payload` re-exports)

### 3. Maintain Backward Compatibility

Update `file:src/app/fragment_utils.rs`:

- Remove the function implementation (lines 8-41)
- Keep the module documentation (lines 1-2)
- Add a re-export: `pub use crate::fragment::fragment_packet;`
- Add a deprecation comment explaining the new location for future reference

### 4. Update Internal Imports

**In `file:src/connection.rs`:**
- Change line 53 from `app::{Packet, fragment_utils::fragment_packet}` to `app::Packet, fragment::fragment_packet`
- This removes the layering violation by importing directly from the fragment module

**In `file:src/app/fragmentation_state.rs`:**
- Change line 47 from `crate::app::fragment_utils::fragment_packet(&self.fragmenter, packet)` to `crate::fragment::fragment_packet(&self.fragmenter, packet)`
- This uses the canonical location within the same crate

### 5. Verify Module Structure

Ensure the module hierarchy is correct:

```
src/
├── app/
│   ├── fragment_utils.rs  (now just re-exports)
│   └── mod.rs             (keeps `pub mod fragment_utils;`)
└── fragment/
    ├── packet.rs          (new, contains fragment_packet)
    └── mod.rs             (updated with packet module)
```

### 6. Validation Checklist

- Verify all imports compile without errors
- Confirm `fragment_packet` is accessible via both paths:
  - New canonical: `crate::fragment::fragment_packet`
  - Legacy compatibility: `crate::app::fragment_utils::fragment_packet`
- Ensure no breaking changes to public API (function remains accessible at `wireframe::app::fragment_utils::fragment_packet`)
- Run existing tests to confirm functionality is preserved
- Check that connection module no longer depends on app module for fragmentation

## Architecture Diagram

```mermaid
graph TD
    A[src/connection.rs] -->|uses| B[src/fragment/packet.rs]
    C[src/app/fragmentation_state.rs] -->|uses| B
    D[src/app/fragment_utils.rs] -->|re-exports| B
    B -->|depends on| E[src/app/envelope.rs<br/>Packet, PacketParts]
    B -->|depends on| F[src/fragment/fragmenter.rs<br/>Fragmenter]
    B -->|depends on| G[src/fragment/payload.rs<br/>encode_fragment_payload]
    B -->|depends on| H[src/fragment/error.rs<br/>FragmentationError]
    
    style B fill:#90EE90
    style D fill:#FFE4B5
    style A fill:#87CEEB
    style C fill:#87CEEB
```

---

Execution Information

Branch: main
Commit: 9b4ea6e

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.