MoosicBox Tunnel Server

Basic WebSocket-based tunneling server for MoosicBox remote access.

Overview

The MoosicBox Tunnel Server provides:

• WebSocket Tunneling: Basic tunneling through WebSocket connections
• Client Registration: Simple client authentication and registration
• Database Integration: PostgreSQL backend for client management
• HTTP API: REST endpoints for tunnel management
• Health Monitoring: Basic health check endpoint

Features

Core Functionality

• WebSocket Server: Handles WebSocket connections for tunneling
• Authentication: Basic client registration and token-based auth
• Database Storage: Client data stored in PostgreSQL
• HTTP Endpoints: REST API for tunnel operations
• CORS Support: Cross-origin resource sharing enabled

Available Endpoints

• Health Check: /health endpoint for service monitoring
• WebSocket: /ws endpoint for tunnel connections
• Client Registration: Authentication and client management
• Magic Token Auth: /auth/magic-token and /auth/validate-signature-token
• Track/Album/Artist: Media proxy endpoints
• Tunnel Management: Basic tunnel lifecycle operations

Installation

From Source

# Install dependencies
sudo apt update
sudo apt install build-essential libssl-dev pkg-config libpq-dev

# Clone and build
git clone https://github.com/MoosicBox/MoosicBox.git
cd MoosicBox
TUNNEL_ACCESS_TOKEN=your-secure-token cargo build --release --bin moosicbox_tunnel_server

# Install binary
sudo cp target/release/moosicbox_tunnel_server /usr/local/bin/

Database Setup

# Install and setup PostgreSQL
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres createdb moosicbox_tunnel
sudo -u postgres createuser moosicbox

Usage

Running the Tunnel Server

# Start tunnel server on default port 8000
moosicbox_tunnel_server

# Start on custom port
moosicbox_tunnel_server 8443

# With environment variables
export PORT=8443
export BIND_ADDR=0.0.0.0
export DATABASE_URL=postgresql://user:pass@localhost/moosicbox_tunnel
moosicbox_tunnel_server

Environment Variables

Build-Time Variables

• TUNNEL_ACCESS_TOKEN: Required access token for general authorization (must be set during compilation)

Runtime Variables

• PORT: Server port (default: 8000)
• BIND_ADDR: Bind address (default: 0.0.0.0)
• DATABASE_URL: PostgreSQL connection string
• MAX_THREADS: Maximum blocking threads (default: 64)
• ACTIX_WORKERS: Number of Actix workers

API Reference

Health Check

curl http://localhost:8000/health

WebSocket Connection

const ws = new WebSocket('ws://localhost:8000/ws?clientId=my-client&signature=your-signature-token');
ws.onopen = () => console.log('Connected');
ws.onmessage = (event) => console.log('Message:', event.data);

Client Authentication

# Register client (requires TUNNEL_ACCESS_TOKEN in Authorization header)
curl -X POST "http://localhost:8000/auth/register-client?clientId=my-client" \
  -H "Authorization: Bearer your-tunnel-access-token"

# Get signature token (requires client access token in Authorization header)
curl -X POST "http://localhost:8000/auth/signature-token?clientId=my-client" \
  -H "Authorization: Bearer your-client-access-token"

# Validate a signature token
curl -X POST "http://localhost:8000/auth/validate-signature-token?clientId=my-client&signature=your-signature-token"

# Register a magic token for a client (requires client access token)
curl -X POST "http://localhost:8000/auth/magic-token?clientId=my-client&magicToken=your-magic-token" \
  -H "Authorization: Bearer your-client-access-token"

# Use a magic token
curl "http://localhost:8000/auth/magic-token?magicToken=your-magic-token"

Tunnel Proxy Request

# Proxy an HTTP request through the tunnel (requires client access token)
curl -X GET "http://localhost:8000/library/albums?clientId=my-client" \
  -H "Authorization: Bearer your-client-access-token"

Configuration

The server can be configured via environment variables:

# Basic configuration
export PORT=8443
export BIND_ADDR=0.0.0.0
export DATABASE_URL=postgresql://localhost/moosicbox_tunnel

# Performance tuning
export MAX_THREADS=64
export ACTIX_WORKERS=4

# Logging
export RUST_LOG=info
export TOKIO_CONSOLE=1  # For tokio console debugging

Development

Building

# Build with all features
TUNNEL_ACCESS_TOKEN=your-secure-token cargo build --release --bin moosicbox_tunnel_server

# Build with specific features
TUNNEL_ACCESS_TOKEN=your-secure-token cargo build --release --bin moosicbox_tunnel_server --features postgres-raw

Running in Development

# Run with debug logging
TUNNEL_ACCESS_TOKEN=your-secure-token RUST_LOG=debug cargo run --bin moosicbox_tunnel_server

# Run with tokio console
TUNNEL_ACCESS_TOKEN=your-secure-token TOKIO_CONSOLE=1 cargo run --bin moosicbox_tunnel_server

Implementation Notes

• The server is built with Actix Web framework
• Uses PostgreSQL for data persistence
• WebSocket connections are managed through a dedicated service
• CORS is configured for web client access
• Supports graceful shutdown with proper cleanup
• Includes basic telemetry and metrics collection