moq-relay

A server that routes broadcasts between publishers and subscribers, performing caching, deduplication, and fan-out.

Overview

moq-relay is designed to run in datacenters, relaying media across multiple hops to improve quality of service and enable massive scale.

Features:

• Fan-out to multiple subscribers
• Caching and deduplication
• Cross-region clustering
• JWT-based authentication
• HTTP debugging endpoints

Installation

From Source

git clone https://github.com/moq-dev/moq
cd moq
cargo build --release --bin moq-relay

The binary will be in target/release/moq-relay.

Using Cargo

cargo install moq-relay

Using winget (Windows)

winget install moq-dev.moq-relay

Using Nix

# Run directly
nix run github:moq-dev/moq#moq-relay

# Or build and find the binary in ./result/bin/
nix build github:moq-dev/moq#moq-relay

Using Docker

docker pull moqdev/moq-relay
docker run -p 4443:4443/udp -v "$(pwd)/relay.toml:/app/relay.toml:ro" moqdev/moq-relay -- /app/relay.toml

Multi-arch images (linux/amd64 and linux/arm64) are published to Docker Hub.

Configuration

Create a relay.toml configuration file:

[server]
bind = "[::]:4443"  # Listen on all interfaces, port 4443

[server.tls]
cert = "/path/to/cert.pem"  # TLS certificate
key = "/path/to/key.pem"    # TLS private key

[auth]
public = "anon"     # Allow anonymous access to anon/**
key = "root.jwk"    # JWT key for authenticated paths

See localhost.toml for a complete example.

Running

Pass the config path as the only positional argument:

moq-relay relay.toml

HTTP Endpoints

The relay exposes HTTP/HTTPS endpoints for debugging, health checks, and late-join. See HTTP for details.

TLS Setup

The relay requires TLS certificates. Use Let's Encrypt:

# Install certbot
sudo apt install certbot  # Ubuntu/Debian
brew install certbot      # macOS

# Generate certificate
sudo certbot certonly --standalone -d relay.example.com

Update relay.toml:

[server.tls]
cert = "/etc/letsencrypt/live/relay.example.com/fullchain.pem"
key = "/etc/letsencrypt/live/relay.example.com/privkey.pem"

Monitoring

Logging

Set log level via environment variable:

RUST_LOG=info moq-relay relay.toml
RUST_LOG=debug moq-relay relay.toml
RUST_LOG=moq_relay=trace moq-relay relay.toml

Metrics

Metrics (Prometheus format) are planned but not yet implemented.

Current visibility:

• Check logs for connection count
• Use HTTP endpoints for track inspection
• Monitor system resources (CPU, memory, bandwidth)

Performance

Current Status

• Single-threaded - Quinn uses one UDP receive thread
• In-memory caching - Recent groups stored in RAM
• Mesh clustering - All relays connect to all others

Scaling

• Vertical - Fast CPU matters more than core count
• Horizontal - Deploy multiple relays in different regions
• Cluster size - 3-5 nodes optimal with current implementation

Future Improvements

• Multi-threaded UDP processing
• Tree-based clustering topology
• Improved memory management
• Metrics and observability

Troubleshooting

Port Already in Use

# Check what's using port 4443
lsof -i :4443

# Kill the process or use a different port

Certificate Errors

Ensure:

• Certificate is valid and not expired
• Certificate matches domain name
• Private key has correct permissions
• Certificate includes full chain

Connection Timeouts

Check:

• UDP port is open in firewall
• Cloud provider allows UDP traffic
• TLS certificate is valid
• Relay is actually running

Next Steps

• Set up Authentication
• Configure Clustering
• Deploy to Production
• Use moq-net client library
• Build media apps with hang