Ambiguous connection module naming causes confusion

[coderabbitai]

Problem

The current organisation of connection-related code creates ambiguity:

• src/connection/ contains outbound-focused connection logic
• src/app/connection.rs contains inbound routing and connection handling

This naming overlap can lead to confusion during requirements gathering, technical discussions, and implementation planning, as it's not immediately clear which module handles which direction of traffic flow.

Context

Raised during PR review: #458

Reported by: @leynos

Recommendation

Consider renaming one or both modules to make the directionality explicit, for example:

• src/connection/outbound/ or src/outbound_connection/
• src/app/inbound_connection.rs or similar

This would make the separation of concerns clearer and reduce cognitive load when navigating the codebase.

[traycerai]

Plan

Observations

The codebase has three connection-related modules: src/connection/ (public, outbound-focused ConnectionActor), src/app/connection.rs (private, inbound routing/handling), and src/server/connection.rs (private, server-level spawning). The public src/connection/ module exports ConnectionActor via pub use connection::ConnectionActor in file:src/lib.rs, making it part of the public API. The private modules are only used internally and not exposed. Renaming the public module would be a breaking change affecting all users.

Approach

Rename the private modules to clarify directionality while preserving the public API. Specifically, rename src/app/connection.rs to src/app/inbound_handler.rs and src/server/connection.rs to src/server/connection_spawner.rs. This eliminates naming ambiguity without breaking changes, as these modules are internal implementation details. The public src/connection/ module remains unchanged to maintain backward compatibility. Update all internal imports and module declarations accordingly.

Implementation Steps

1. Rename src/app/connection.rs to src/app/inbound_handler.rs

File Operations:

• Rename file:src/app/connection.rs to file:src/app/inbound_handler.rs
• Rename file:src/app/connection/tests.rs to file:src/app/inbound_handler/tests.rs

Update Module Declaration:

• In file:src/app/mod.rs, change mod connection; to mod inbound_handler; (line 14)

Rationale: The name "inbound_handler" clearly indicates this module handles incoming connections and routes them to appropriate handlers, eliminating confusion with the outbound-focused src/connection/ module.

2. Rename src/server/connection.rs to src/server/connection_spawner.rs

File Operations:

• Rename file:src/server/connection.rs to file:src/server/connection_spawner.rs

Update Module Declaration:

• In file:src/server/mod.rs, change mod connection; to mod connection_spawner; (line 268)

Update Internal Imports:

• In file:src/server/mod.rs, update any internal references to use the new module name
• Check file:src/server/runtime.rs and other server submodules for imports from this module

Rationale: The name "connection_spawner" accurately describes this module's responsibility: spawning tasks to process TCP connections and managing preamble handling.

3. Update Documentation and Comments

Module-Level Documentation:

• Update the module documentation in file:src/app/inbound_handler.rs (formerly connection.rs) to emphasize its role in inbound connection handling and routing
• Update the module documentation in file:src/server/connection_spawner.rs to clarify its role in spawning connection tasks

Cross-References:

• Search for any documentation comments that reference "connection module" ambiguously and clarify which module is meant
• Update file:src/app/fragmentation_state.rs line 6 comment that mentions ConnectionActor and WireframeApp to clarify the distinction

4. Verify No Breaking Changes

Public API Verification:

• Confirm file:src/lib.rs still exports pub use connection::ConnectionActor; (line 61)
• Verify no public re-exports from the renamed private modules
• Ensure file:src/app/mod.rs does not publicly export anything from the renamed inbound_handler module

Test Compilation:

• Run cargo check to ensure all internal imports resolve correctly
• Run cargo test to verify all tests pass with the new module names
• Run cargo doc to ensure documentation builds without broken links

5. Update CHANGELOG

Add Entry:

• Add a new entry to file:CHANGELOG.md under an "Internal" or "Refactoring" section noting the module renames
• Emphasize that this is a non-breaking internal refactoring
• Example: "Renamed internal modules src/app/connection.rs to src/app/inbound_handler.rs and src/server/connection.rs to src/server/connection_spawner.rs to clarify directionality and reduce naming ambiguity. No public API changes."

Architecture Diagram

graph TD
    A[Public API: src/connection/] -->|exports| B[ConnectionActor]
    B -->|handles| C[Outbound Frames]
    
    D[Private: src/app/inbound_handler.rs] -->|handles| E[Inbound Routing]
    D -->|contains| F[handle_connection methods]
    
    G[Private: src/server/connection_spawner.rs] -->|spawns| H[Connection Tasks]
    G -->|reads| I[Preamble]
    G -->|delegates to| D
    
    J[WireframeApp] -->|uses| D
    K[WireframeServer] -->|uses| G
    
    style A fill:#e1f5e1
    style D fill:#fff4e1
    style G fill:#fff4e1

Loading

Impact Summary

Module	Old Name	New Name	Visibility	Breaking Change
Outbound connection actor	src/connection/	src/connection/	Public	No (unchanged)
Inbound connection handler	src/app/connection.rs	src/app/inbound_handler.rs	Private	No
Server connection spawner	src/server/connection.rs	src/server/connection_spawner.rs	Private	No

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has three connection-related modules: `src/connection/` (public, outbound-focused `ConnectionActor`), `src/app/connection.rs` (private, inbound routing/handling), and `src/server/connection.rs` (private, server-level spawning). The public `src/connection/` module exports `ConnectionActor` via `pub use connection::ConnectionActor` in `file:src/lib.rs`, making it part of the public API. The private modules are only used internally and not exposed. Renaming the public module would be a breaking change affecting all users.

## Approach

Rename the private modules to clarify directionality while preserving the public API. Specifically, rename `src/app/connection.rs` to `src/app/inbound_handler.rs` and `src/server/connection.rs` to `src/server/connection_spawner.rs`. This eliminates naming ambiguity without breaking changes, as these modules are internal implementation details. The public `src/connection/` module remains unchanged to maintain backward compatibility. Update all internal imports and module declarations accordingly.

## Implementation Steps

### 1. Rename `src/app/connection.rs` to `src/app/inbound_handler.rs`

**File Operations:**
- Rename `file:src/app/connection.rs` to `file:src/app/inbound_handler.rs`
- Rename `file:src/app/connection/tests.rs` to `file:src/app/inbound_handler/tests.rs`

**Update Module Declaration:**
- In `file:src/app/mod.rs`, change `mod connection;` to `mod inbound_handler;` (line 14)

**Rationale:** The name "inbound_handler" clearly indicates this module handles incoming connections and routes them to appropriate handlers, eliminating confusion with the outbound-focused `src/connection/` module.

### 2. Rename `src/server/connection.rs` to `src/server/connection_spawner.rs`

**File Operations:**
- Rename `file:src/server/connection.rs` to `file:src/server/connection_spawner.rs`

**Update Module Declaration:**
- In `file:src/server/mod.rs`, change `mod connection;` to `mod connection_spawner;` (line 268)

**Update Internal Imports:**
- In `file:src/server/mod.rs`, update any internal references to use the new module name
- Check `file:src/server/runtime.rs` and other server submodules for imports from this module

**Rationale:** The name "connection_spawner" accurately describes this module's responsibility: spawning tasks to process TCP connections and managing preamble handling.

### 3. Update Documentation and Comments

**Module-Level Documentation:**
- Update the module documentation in `file:src/app/inbound_handler.rs` (formerly `connection.rs`) to emphasize its role in inbound connection handling and routing
- Update the module documentation in `file:src/server/connection_spawner.rs` to clarify its role in spawning connection tasks

**Cross-References:**
- Search for any documentation comments that reference "connection module" ambiguously and clarify which module is meant
- Update `file:src/app/fragmentation_state.rs` line 6 comment that mentions `ConnectionActor` and `WireframeApp` to clarify the distinction

### 4. Verify No Breaking Changes

**Public API Verification:**
- Confirm `file:src/lib.rs` still exports `pub use connection::ConnectionActor;` (line 61)
- Verify no public re-exports from the renamed private modules
- Ensure `file:src/app/mod.rs` does not publicly export anything from the renamed `inbound_handler` module

**Test Compilation:**
- Run `cargo check` to ensure all internal imports resolve correctly
- Run `cargo test` to verify all tests pass with the new module names
- Run `cargo doc` to ensure documentation builds without broken links

### 5. Update CHANGELOG

**Add Entry:**
- Add a new entry to `file:CHANGELOG.md` under an "Internal" or "Refactoring" section noting the module renames
- Emphasize that this is a non-breaking internal refactoring
- Example: "Renamed internal modules `src/app/connection.rs` to `src/app/inbound_handler.rs` and `src/server/connection.rs` to `src/server/connection_spawner.rs` to clarify directionality and reduce naming ambiguity. No public API changes."

## Architecture Diagram

```mermaid
graph TD
    A[Public API: src/connection/] -->|exports| B[ConnectionActor]
    B -->|handles| C[Outbound Frames]
    
    D[Private: src/app/inbound_handler.rs] -->|handles| E[Inbound Routing]
    D -->|contains| F[handle_connection methods]
    
    G[Private: src/server/connection_spawner.rs] -->|spawns| H[Connection Tasks]
    G -->|reads| I[Preamble]
    G -->|delegates to| D
    
    J[WireframeApp] -->|uses| D
    K[WireframeServer] -->|uses| G
    
    style A fill:#e1f5e1
    style D fill:#fff4e1
    style G fill:#fff4e1
```

## Impact Summary

| Module | Old Name | New Name | Visibility | Breaking Change |
|--------|----------|----------|------------|-----------------|
| Outbound connection actor | `src/connection/` | `src/connection/` | Public | No (unchanged) |
| Inbound connection handler | `src/app/connection.rs` | `src/app/inbound_handler.rs` | Private | No |
| Server connection spawner | `src/server/connection.rs` | `src/server/connection_spawner.rs` | Private | No |

---

Execution Information

Branch: main
Commit: 3ddde5a

---

💡 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.