Advanced Topics

Tunneling

Create secure tunnels and proxy connections for exposing local services through WebSocket bridges

dxflow provides powerful tunneling capabilities through its proxy-bridge architecture, enabling you to expose local services securely over WebSocket connections with automatic subdomain allocation.

Secure Access: dxflow tunneling uses authenticated WebSocket connections to route traffic between proxy hubs and bridge nodes, enabling secure access to local services from anywhere.

Architecture Overview

Core Concepts

dxflow tunneling uses a sophisticated proxy-bridge architecture with WebSocket tunnels:

Proxy Mode (Hub)

Central Traffic Router

Provides subdomain allocation to bridge instances
Routes incoming traffic via WebSocket tunnels
Manages authentication and traffic limitations
Maintains connection pools for efficient handling
Uses 12-byte identity system for routing

Bridge Mode (Node)

Local Service Gateway

Connects to proxy hub to obtain subdomain
Establishes bidirectional WebSocket tunnel
Routes traffic between hub and local services
Handles automatic reconnection and recovery
Validates upstream must be private IP

Identity System

Every proxy and bridge connection uses a unique identity:

Aspect	Description
Format	12-byte array (displayed as alphanumeric, e.g., `ab1234567890`)
Generation	Derived from alphanumeric string, zero-padded if needed
Usage	Subdomain allocation and routing identification

Traffic Flow Mechanism

Connection Handling Process:

User connects with subdomain
    ↓
UserConnection → ProxyPool.UserSide → Broadcast to Bridge → Wait for pairing
    ↓
Bridge receives broadcast
    ↓
Bridge WebSocket → Decode Identity → Create Gateway Connection → ProxyPool.BridgeSide
    ↓
Pairing and transfer
    ↓
ProxyPool pairs connections → TcpPair transfers data → Update statistics

Key Components:

Component	Description
Connection Pooling	8-second timeout window for connection pairing
Bidirectional Transfer	TCP traffic flows through WebSocket frames
Traffic Statistics	Real-time tracking of read/write bytes
Hijack Detection	Incoming connections analyzed for subdomain requests

Setting Up Tunnels

Using the Default Hub

dxflow provides dxflow.ai as a ready-to-use public hub:

Zero Setup Required: The default hub is already running and ready to accept bridge connections. No configuration or deployment needed on your part.

Hub Features:

Always available at dxflow.ai
Unlimited connections and traffic from hub perspective
Automatic subdomain allocation for each bridge
Managed infrastructure - no maintenance required

Start Your Own Proxy Hub

For private tunneling with your own infrastructure:

Enterprise Feature: Running your own proxy hub requires a specific license. Contact us for enterprise licensing and private hub deployment. Learn more about licensing.

Private Hub Benefits:

Full control over authentication and traffic limits
Private infrastructure - no shared resources
Custom domain and subdomain allocation

Connect Bridge Nodes

Connect bridge nodes to expose local services:

Requires Bridge-Enabled License: Bridge functionality is not included in the general license. You need a bridge-enabled license to connect bridge nodes. See licensing documentation for details.

# Start bridge connecting to default hub (dxflow.ai)
dxflow boot up --bridge --daemon

# Bridge receives subdomain from hub
# Default: 1 connection, 10MB traffic limit

Manual Management

# List active proxies on hub
dxflow proxy list

# Create new proxy allocation
dxflow proxy create

# Remove unused proxies
dxflow proxy prune

# List bridge connections
dxflow bridge list

# Disconnect bridge temporarily
dxflow bridge disconnect <identity>

# Reconnect bridge
dxflow bridge connect <identity>

# Clean up inactive bridges
dxflow bridge prune

Identity System

Unique Identifiers

Every proxy-bridge connection uses a 12-character alphanumeric identity:

Property	Details
Format	12-byte alphanumeric (e.g., `ab1234567890`)
Usage	Subdomain allocation and traffic routing
Generation	Automatically created during connection

Authentication

Proxy Credentials

Auto-Generated

Username: 6-character random nonce
Password: 24-character random nonce
Required for WebSocket connections

Gateway Authorization

Optional Security

Authorization tokens in query parameters
Prevents unauthorized subdomain allocation
Additional security layer

Traffic Management

Connection Pooling

dxflow optimizes performance through intelligent connection pooling:

8-second pairing window for matching connections
Automatic cleanup of unpaired connections
Thread-safe operations with mutex protection
Connection reuse to reduce overhead

Default Configuration

dxflow tunneling comes with different defaults for hubs and nodes:

dxflow.ai Hub

Default hub: dxflow.ai (public)
Connection limit: Unlimited
Traffic limit: Unlimited
Purpose: Central routing for all users

Security Features

Network Security

dxflow tunneling includes several security measures:

Upstream Validation

Private IP Only

Bridge must connect to private IPs
Prevents exposing public services
Enforces local network boundaries

TLS Support

Encrypted Connections

HTTPS gateway connections
Proper SNI handling for subdomains
Certificate validation for secure tunnels

Protocol Security

The hijack protocol enables efficient routing:

<identity|fingerprint>

Element	Description
`identity`	12-byte bridge identifier
`fingerprint`	UUID for connection tracking

Performance Characteristics

Latency Comparison

Connection Type	Characteristics
Direct Proxy	Minimal overhead, production-ready, low latency
Bridge Tunnel	WebSocket overhead, development/testing scenarios

Traffic Statistics

Hub Metrics

User traffic (incoming from internet)
Bridge traffic (to/from bridge nodes)
Format: (↓ download) (↑ upload)
Real-time bandwidth tracking

Troubleshooting

Common Issues

"Proxy not available"

Identity doesn't exist on hub
Proxy was removed or never created
Check proxy list on hub

"Proxy not connected"

WebSocket connection dropped
Network interruption occurred
Verify bridge status and connectivity

Debugging Steps

Enable debug logging: dxflow --log-level=debug boot up --proxy
Monitor connection pools: Check pool sizes and timeout messages
Track traffic stats: Use API for real-time bandwidth monitoring
Test connectivity: Verify upstream services and WebSocket connections

Best Practices

Production Deployment

Security First

Use HTTPS for all gateway connections
Set appropriate traffic limitations
Rotate credentials regularly
Monitor traffic patterns

Performance

Tune buffer sizes for workload
Optimize timeout values
Use connection pooling effectively
Monitor statistics for bottlenecks

Reliability

Implement retry logic for failures
Monitor connection pool health
Set up automated cleanup tasks
Plan for horizontal scaling

API Integration

The tunneling system provides REST APIs for programmatic control:

Proxy Hub APIs

# List active proxies
curl http://hub/api/proxy/

# Create new proxy
curl -X POST http://hub/api/proxy/

# Remove inactive proxies
curl -X DELETE http://hub/api/proxy/prune/

Bridge Node APIs

# List bridge connections
curl http://node/api/bridge/

# Reconnect specific bridge
curl -X POST http://node/api/bridge/{identity}/connect/

# Clean up inactive bridges
curl -X DELETE http://node/api/bridge/prune/

Production Ready: dxflow tunneling has been tested in production environments, providing reliable secure access to local services with automatic reconnection, traffic management, and comprehensive monitoring.

The tunneling architecture enables secure, scalable access to distributed services while maintaining simplicity in configuration and management.

Streaming

Enable high-performance data streaming for large datasets and real-time updates

Remoting

Control distributed dxflow infrastructure from a single CLI using secure authentication and profile-based management