Hummingbird Integration Guide for VibeTunnel

This guide explains the Hummingbird web framework integration in VibeTunnel for creating the tunnel server functionality.

Current Status

✅ IMPLEMENTED - The VibeTunnel server is now fully implemented with:

HTTP REST API endpoints for terminal session management
WebSocket support for real-time terminal communication
Authentication via API keys
Session management with automatic cleanup
Client SDK for easy integration
Comprehensive error handling

Architecture Overview

The VibeTunnel server is built with the following components:

Core Components

TunnelServer (/VibeTunnel/Core/Services/TunnelServer.swift)
- Main server implementation using Hummingbird
- Manages HTTP endpoints and WebSocket connections
- Handles server lifecycle and configuration
TerminalManager (/VibeTunnel/Core/Services/TerminalManager.swift)
- Actor-based terminal session management
- Handles process creation and command execution
- Manages pipes for stdin/stdout/stderr communication
- Automatic cleanup of inactive sessions
WebSocketHandler (/VibeTunnel/Core/Services/WebSocketHandler.swift)
- Real-time bidirectional communication
- JSON-based message protocol
- Session-based terminal streaming
AuthenticationMiddleware (/VibeTunnel/Core/Services/AuthenticationMiddleware.swift)
- API key-based authentication
- Secure key generation and storage
- Protects all endpoints except health check
TunnelClient (/VibeTunnel/Core/Services/TunnelClient.swift)
- Swift SDK for server interaction
- Async/await based API
- WebSocket client for real-time communication

Data Models

TunnelSession - Represents a terminal session
CreateSessionRequest/Response - Session creation
CommandRequest/Response - Command execution
WSMessage - WebSocket message format

API Endpoints

REST API

GET /health - Health check (no auth required)
GET /info - Server information
GET /sessions - List all active sessions
POST /sessions - Create new terminal session
GET /sessions/:id - Get session details
DELETE /sessions/:id - Close a session
POST /execute - Execute command in session

WebSocket

WS /ws/terminal - Real-time terminal communication

Example Implementation

import Foundation
import Hummingbird
import HummingbirdCore
import Logging
import NIOCore

// Basic server implementation
struct TunnelServerApp {
    let logger = Logger(label: "VibeTunnel.Server")
    
    func buildApplication() -> some ApplicationProtocol {
        let router = Router()
        
        // Health check endpoint
        router.get("/health") { request, context -> [String: Any] in
            return [
                "status": "ok",
                "timestamp": Date().timeIntervalSince1970
            ]
        }
        
        // Command endpoint
        router.post("/tunnel/command") { request, context -> Response in
            struct CommandRequest: Decodable {
                let command: String
                let args: [String]?
            }
            
            let commandRequest = try await request.decode(
                as: CommandRequest.self,
                context: context
            )
            
            // Process command here
            logger.info("Received command: \(commandRequest.command)")
            
            return Response(
                status: .ok,
                headers: HTTPFields([
                    .contentType: "application/json"
                ]),
                body: .data(Data("{\"success\":true}".utf8))
            )
        }
        
        let app = Application(
            router: router,
            configuration: .init(
                address: .hostname("127.0.0.1", port: 8080)
            )
        )
        
        return app
    }
}

WebSocket Support

For real-time communication with Claude Code, you'll want to add WebSocket support:

// Add HummingbirdWebSocket dependency first
import HummingbirdWebSocket

// Then add WebSocket routes
router.ws("/tunnel/stream") { request, ws, context in
    ws.onText { ws, text in
        // Handle incoming text messages
        logger.info("Received: \(text)")
        
        // Echo back or process command
        try await ws.send(text: "Acknowledged: \(text)")
    }
    
    ws.onBinary { ws, buffer in
        // Handle binary data if needed
    }
    
    ws.onClose { closeCode in
        logger.info("WebSocket closed: \(closeCode)")
    }
}

Integration Steps

Update the Package Dependencies: Make sure to include any additional Hummingbird modules you need (like HummingbirdWebSocket).
Replace the Placeholder: Update TunnelServer.swift with the actual Hummingbird implementation.
Handle Concurrency: Since the server runs asynchronously, ensure proper handling of the server lifecycle with the SwiftUI app lifecycle.
Add Security: Implement authentication and secure communication for production use.

Testing the Server

Once implemented, you can test the server with curl:

# Health check
curl http://localhost:8080/health

# Send a command
curl -X POST http://localhost:8080/tunnel/command \
  -H "Content-Type: application/json" \
  -d '{"command":"ls","args":["-la"]}'

Next Steps

Implement actual command execution logic
Add authentication/authorization
Implement WebSocket support for real-time communication
Add SSL/TLS support for secure connections
Create client SDK for easy integration

5.5 KiB Raw Blame History