claudetools/projects/msp-tools/guru-rmm/plans/tunnel-phase1-agent-implementation.md

GuruRMM Tunnel - Phase 1 Agent Implementation

Date: 2026-04-14 Status: COMPLETED Component: Agent (Rust)

---

Summary

Successfully implemented Phase 1 of the GuruRMM real-time tunnel feature on the agent side. The agent now supports mode switching between Heartbeat and Tunnel modes, handles tunnel lifecycle messages, and is ready for Phase 2 terminal command execution.

---

Implementation Details

1. Protocol Extensions

File: agent/src/transport/mod.rs

Added new message types to AgentMessage enum:

• TunnelReady { session_id: String } - Confirmation that tunnel is ready
• TunnelData { channel_id: String, data: TunnelDataPayload } - Bidirectional tunnel data
• TunnelError { channel_id: String, error: String } - Error reporting

Added new message types to ServerMessage enum:

• TunnelOpen { session_id: String, tech_id: Uuid } - Server request to open tunnel
• TunnelClose { session_id: String } - Server request to close tunnel
• TunnelData { channel_id: String, data: TunnelDataPayload } - Bidirectional tunnel data

Added TunnelDataPayload enum (Phase 1: Terminal only):

• Terminal { command: String } - Terminal command request
• TerminalOutput { stdout: String, stderr: String, exit_code: Option<i32> } - Terminal response

2. Tunnel Manager Module

File: agent/src/tunnel/mod.rs (NEW)

Created comprehensive tunnel state management:

AgentMode enum:

pub enum AgentMode {
    Heartbeat,  // Default: 30s heartbeats, metrics, network monitoring
    Tunnel {
        session_id: String,
        tech_id: Uuid,
        channels: HashMap<String, ChannelType>,
    },
}

TunnelManager struct:

• open_tunnel() - Transition from Heartbeat to Tunnel mode
• close_tunnel() - Transition back to Heartbeat mode
• add_channel() - Register new channel (terminal, file, etc.)
• remove_channel() - Cleanup channel
• force_close() - Emergency cleanup on disconnect

Channel types (extensible for future phases):

• Terminal - Command execution (Phase 1)
• File - File operations (Phase 2+)
• Registry - Registry operations (Phase 2+)
• Service - Service management (Phase 2+)

3. WebSocket Integration

File: agent/src/transport/websocket.rs

Updated WebSocket client to support tunnel operations:

New handler functions:

• handle_tunnel_open() - Process TunnelOpen request, send TunnelReady
• handle_tunnel_close() - Process TunnelClose request, cleanup state
• handle_tunnel_data() - Route tunnel data by channel (Phase 1: placeholder)

Message loop updates:

• Created TunnelManager instance in connection lifecycle
• Updated handle_server_message() signature to accept tunnel manager
• Added tunnel message logging (TunnelReady, TunnelData, TunnelError)
• Force-close tunnel on WebSocket disconnect

Mode persistence:

• Tunnel state maintained across message loop iterations
• Heartbeat continues in both modes (connection keepalive)
• Clean shutdown closes active sessions

4. Module Registration

File: agent/src/main.rs

Added tunnel module to module tree:

mod tunnel;

---

Testing

Unit Tests

Created comprehensive test suite in agent/src/tunnel/mod.rs:

Test: test_tunnel_lifecycle

• Starts in Heartbeat mode
• Opens tunnel successfully
• Rejects concurrent tunnel sessions
• Closes tunnel and returns to Heartbeat mode

Test: test_channel_management

• Rejects channel operations without active tunnel
• Adds multiple channels
• Retrieves channel types
• Removes channels
• Force-closes tunnel

Test Results:

running 2 tests
test tunnel::tests::test_tunnel_lifecycle ... ok
test tunnel::tests::test_channel_management ... ok

test result: ok. 2 passed; 0 failed; 0 ignored

Compilation

Status: SUCCESSFUL

Warnings (expected, non-critical):

• tech_id field unused (will be used in Phase 2 for authorization)
• Some enum variants unused (File, Registry, Service - Phase 2+)
• Some methods unused (mode accessors - used in Phase 2)

---

Protocol Flow

Tunnel Open

Server → Agent: TunnelOpen { session_id, tech_id }
Agent:  tunnel_manager.open_tunnel()
Agent → Server: TunnelReady { session_id }

Tunnel Close

Server → Agent: TunnelClose { session_id }
Agent:  tunnel_manager.close_tunnel()

Terminal Command (Phase 1 - Placeholder)

Server → Agent: TunnelData {
    channel_id: "...",
    data: Terminal { command: "..." }
}
Agent:  Log command (execution in Phase 2)
Agent → Server: TunnelData {
    channel_id: "...",
    data: TerminalOutput {
        stdout: "",
        stderr: "Not implemented",
        exit_code: Some(-1)
    }
}

Connection Loss

WebSocket disconnect detected
Agent:  tunnel_manager.force_close()
Agent:  Cleanup tasks, return to heartbeat mode

---

Key Features

Mode Switching

• Clean transition between Heartbeat and Tunnel modes
• Single active tunnel per agent (prevents session conflicts)
• Tunnel state persists across message loop iterations

Channel Multiplexing

• HashMap-based channel routing by channel_id
• Extensible channel types (Terminal, File, Registry, Service)
• Channel lifecycle management (add, remove, cleanup)

Error Handling

• Validates session IDs on close requests
• Rejects concurrent tunnel sessions
• Sends TunnelError messages for failures
• Force-close on unexpected disconnect

Logging

• Info-level: Tunnel open/close, mode transitions
• Debug-level: Channel operations, TunnelData routing
• Warn-level: Errors, rejected operations

---

Files Modified

1. agent/src/transport/mod.rs - Protocol message definitions
2. agent/src/transport/websocket.rs - WebSocket tunnel integration
3. agent/src/main.rs - Module registration
4. agent/src/tunnel/mod.rs - NEW: Tunnel manager implementation

---

Next Steps (Phase 2)

Terminal Command Execution

Implementation required in handle_tunnel_data():

1. Parse TunnelDataPayload::Terminal { command }
2. Spawn process using tokio::process::Command
3. Capture stdout/stderr streams
4. Handle exit codes and timeouts
5. Send TunnelDataPayload::TerminalOutput response

Considerations:

• Shell selection (PowerShell, cmd, bash based on OS)
• Working directory restrictions (security)
• Timeout enforcement (prevent hung processes)
• Error handling (process spawn failures, permission errors)

Integration Testing

Manual testing with server:

1. Deploy updated agent to test machine
2. Server sends TunnelOpen via WebSocket
3. Verify TunnelReady response
4. Send Terminal command
5. Verify TerminalOutput response (Phase 2)
6. Server sends TunnelClose
7. Verify graceful cleanup

---

Compliance with Architecture Plan

Alignment with plans/real-time-tunnel-architecture.md:

• [OK] AgentMode state machine (Heartbeat ↔ Tunnel)
• [OK] Channel routing by channel_id
• [OK] TunnelOpen/TunnelClose lifecycle
• [OK] TunnelReady confirmation message
• [OK] TunnelDataPayload enum (Phase 1: Terminal only)
• [OK] Heartbeat maintained in tunnel mode
• [OK] Force-close on disconnect
• [OK] Unit tests for state machine
• [PENDING] Terminal command execution (Phase 2)
• [PENDING] File operations (Phase 3)
• [PENDING] MCP server integration (Phase 4)

---

Known Limitations

1. Terminal execution not implemented - Phase 1 only handles protocol and state management. Actual command execution is Phase 2.

2. No working directory restrictions - Security layer for path validation will be added in Phase 2.

3. Single tunnel per agent - By design, prevents session conflicts. Multi-tech sessions deferred to future enhancement.

4. No channel-level timeouts - Will be added in Phase 2 with actual command execution.

---

Security Notes

Implemented:

• Session validation (session_id matching on close)
• Single tunnel enforcement (rejects concurrent sessions)
• Clean state transitions (no lingering channels)

Pending (Phase 2+):

• Command sanitization (injection prevention)
• Working directory allowlist
• Rate limiting (server-side)
• Audit logging (server-side)

---

Performance Impact

Memory:

• TunnelManager: ~200 bytes (enum + HashMap overhead)
• Active per connection, deallocated on disconnect
• Negligible impact on heartbeat mode

CPU:

• Mode checks: O(1) enum match
• Channel routing: O(1) HashMap lookup
• No continuous tasks in tunnel mode
• Heartbeat continues at 30s interval (unchanged)

Network:

• TunnelReady: Single message on tunnel open (~100 bytes)
• Heartbeat continues in tunnel mode (no change)
• TunnelData: Variable (depends on command output in Phase 2)

---

Conclusion

Phase 1 agent implementation is complete and tested. The agent can now:

• Switch between Heartbeat and Tunnel modes
• Handle TunnelOpen/TunnelClose lifecycle
• Route tunnel messages by channel_id
• Maintain connection integrity in both modes

Ready for Phase 2: Terminal command execution implementation.

Status: READY FOR SERVER INTEGRATION TESTING