vibetunnel/docs/swift-rust-comm.md

Swift-Rust Communication Architecture

This document describes the inter-process communication (IPC) architecture between the Swift VibeTunnel macOS application and the Rust tty-fwd terminal multiplexer.

Overview

VibeTunnel uses a Unix domain socket for communication between the Swift app and Rust components. This approach avoids UI spawning issues and provides reliable, bidirectional communication.

Architecture Components

1. Terminal Spawn Service (Swift)

File: VibeTunnel/Core/Services/TerminalSpawnService.swift

The TerminalSpawnService listens on a Unix domain socket at /tmp/vibetunnel-terminal.sock and handles requests to spawn terminal windows.

Key features:

• Uses POSIX socket APIs (socket, bind, listen, accept) for reliable Unix domain socket communication
• Runs on a dedicated queue with .userInitiated QoS
• Automatically cleans up the socket on startup and shutdown
• Handles JSON-encoded spawn requests and responses
• Non-blocking accept loop with proper error handling

Lifecycle:

• Started in AppDelegate.applicationDidFinishLaunching
• Stopped in AppDelegate.applicationWillTerminate

2. Socket Client (Rust)

File: tty-fwd/src/term_socket.rs

The Rust client connects to the Unix socket to request terminal spawning:

pub fn spawn_terminal_via_socket(
    command: &[String],
    working_dir: Option<&str>,
) -> Result<String>

Communication Protocol:

Request format (optimized):

{
  "command": "tty-fwd --session-id=\"uuid\" -- zsh && exit",
  "workingDir": "/Users/example",
  "sessionId": "uuid-here",
  "ttyFwdPath": "/path/to/tty-fwd",
  "terminal": "ghostty"  // optional
}

Response format:

{
  "success": true,
  "error": null,
  "sessionId": "uuid-here"
}

Key optimizations:

• Command is pre-formatted in Rust to avoid double-escaping issues
• ttyFwdPath is provided to avoid path discovery
• Terminal preference can be specified per-request
• Working directory handling is simplified

3. Integration Points

Swift Server (Hummingbird)

File: VibeTunnel/Core/Services/TunnelServer.swift

When spawn_terminal: true is received in a session creation request:

1. Connects to the Unix socket using low-level socket APIs
2. Sends the spawn request
3. Reads the response
4. Returns appropriate HTTP response to the web UI

Rust API Server

File: tty-fwd/src/api_server.rs

The API server handles HTTP requests and uses spawn_terminal_command when the spawn_terminal flag is set.

Communication Flow

Web UI → HTTP POST /api/sessions (spawn_terminal: true)
       ↓
   API Server (Swift or Rust)
       ↓
   Unix Socket Client
       ↓
   /tmp/vibetunnel-terminal.sock
       ↓
   TerminalSpawnService (Swift)
       ↓
   TerminalLauncher
       ↓
   AppleScript execution
       ↓
   Terminal.app/iTerm2/etc opens with command

Benefits of This Architecture

1. No UI Spawning: The main VibeTunnel app handles all terminal spawning, avoiding macOS restrictions on spawning UI apps from background processes.

2. Process Isolation: tty-fwd doesn't need to know about VibeTunnel's location or how to invoke it.

3. Reliable Communication: Unix domain sockets provide fast, reliable local IPC.

4. Clean Separation: Terminal spawning logic stays in the Swift app where it belongs.

5. Fallback Support: If the socket is unavailable, appropriate error messages guide the user.

Error Handling

Common error scenarios:

1. Socket Unavailable:

   • Error: "Terminal spawn service not available at /tmp/vibetunnel-terminal.sock"
   • Cause: VibeTunnel app not running or service not started
   • Solution: Ensure VibeTunnel is running

2. Permission Denied:

   • Error: "Failed to spawn terminal: Accessibility permission denied"
   • Cause: macOS security restrictions on AppleScript
   • Solution: Grant accessibility permissions to VibeTunnel

3. Terminal Not Found:

   • Error: "Selected terminal application not found"
   • Cause: Configured terminal app not installed
   • Solution: Install the terminal or change preferences

Implementation Notes

Socket Path

The socket path /tmp/vibetunnel-terminal.sock was chosen because:

• /tmp is accessible to all processes
• Automatically cleaned up on system restart
• No permission issues between different processes

JSON Protocol

JSON was chosen for the protocol because:

• Easy to parse in both Swift and Rust
• Human-readable for debugging
• Extensible for future features

Performance Optimizations

1. Pre-formatted Commands: Rust formats the complete command string, avoiding complex escaping logic in Swift
2. Path Discovery: tty-fwd path is passed in the request to avoid repeated file system lookups
3. Direct Terminal Selection: Terminal preference can be specified per-request without changing global settings
4. Simplified Escaping: Using shell-words crate in Rust for proper command escaping
5. Reduced Payload Size: Command is a single string instead of an array

Security Considerations

• The socket is created with default permissions (user-only access)
• No authentication is required as it's local-only communication
• The socket is cleaned up on app termination
• Commands are properly escaped using shell-words to prevent injection

Adding New IPC Features

To add new IPC commands:

1. Define the request/response structures in both Swift and Rust
2. Add a new handler in TerminalSpawnService.handleRequest
3. Create a corresponding client function in Rust
4. Update error handling for the new command

Example:

struct NewCommand: Codable {
    let action: String
    let parameters: [String: String]
}

#[derive(serde::Serialize)]
struct NewCommand {
    action: String,
    parameters: HashMap<String, String>,
}

Debugging

To debug socket communication:

1. Check if the socket exists: ls -la /tmp/vibetunnel-terminal.sock
2. Monitor Swift logs: Look for TerminalSpawnService category
3. Check Rust debug output when running tty-fwd with verbose logging
4. Use netstat -an | grep vibetunnel to see socket connections

Implementation Details

POSIX Socket Implementation

The service uses low-level POSIX socket APIs for maximum compatibility:

// Socket creation
serverSocket = socket(AF_UNIX, SOCK_STREAM, 0)

// Binding to path
var addr = sockaddr_un()
addr.sun_family = sa_family_t(AF_UNIX)
bind(serverSocket, &addr, socklen_t(MemoryLayout<sockaddr_un>.size))

// Accept connections
let clientSocket = accept(serverSocket, &clientAddr, &clientAddrLen)

This approach avoids the Network framework's limitations with Unix domain sockets and provides reliable, cross-platform compatible IPC.

Historical Context

Previously, tty-fwd would spawn VibeTunnel as a subprocess with CLI arguments. This approach had several issues:

• macOS security restrictions on spawning UI apps
• Duplicate instance detection conflicts
• Complex error handling
• Path discovery problems

The Unix socket approach would resolve these issues while providing a cleaner architecture, but needs to be implemented using lower-level APIs due to Network framework limitations.