Overview

Relevant source files

• README.md
• go.mod
• spec.go

Purpose and Scope

The webteleport/relay system is a multi-protocol relay service that provides secure tunneling capabilities over WebSocket, WebTransport, QUIC, and TCP connections. It functions as a reverse proxy gateway that accepts connections from backend services through various protocols and exposes them to external HTTP/HTTPS clients.

This document provides a high-level introduction to the relay system's architecture, core interfaces, and operational model. For detailed information about specific components:

• Core architectural interfaces and implementations: see Key Interfaces
• Session lifecycle and management: see Store and Session Management
• Protocol-specific server implementations: see Server Implementations
• Request routing logic: see Request Flow

Sources: spec.go1-83 go.mod1-45 README.md1-7

---

System Purpose

The relay serves as a bidirectional tunnel gateway that:

1. Accepts backend connections via multiple transport protocols (WebSocket, WebTransport, QUIC, TCP)
2. Allocates unique identifiers for each connected backend (TCP ports or HTTP onion IDs)
3. Routes incoming HTTP requests from external clients to appropriate backend services
4. Maintains session state including health monitoring and metrics collection
5. Provides management APIs for session inspection and alias management

The system enables backends behind NAT or firewalls to expose HTTP services without requiring inbound network access, using outbound connections to the relay server.

Sources: spec.go12-82

---

Supported Protocols

The relay supports four primary connection protocols for backend services:

Protocol	Port(s)	Server Component	Use Case
WebSocket	8080	WSServer	Browser-compatible, HTTP-based tunneling
WebTransport	8082, 8083	WTServer	Modern HTTP/3 with multiplexing and datagrams
QUIC	8081	quic-go, net-quic upgraders	Native QUIC connections without HTTP/3
TCP	8081	tcp.Upgrader	Raw TCP tunneling

All protocols converge on the edge.Edge abstraction and use tunnel.Session for secure communication with backend services.

Sources: go.mod8-21 spec.go12-22

---

Core Architecture

The relay architecture is built around three fundamental interfaces defined in spec.go12-82:

Diagram: Core Interface Architecture and Implementations

Interface Roles

Relayer Interface spec.go13-22

• Aggregates dispatcher.Dispatcher, edge.HTTPUpgrader, and Ingress capabilities
• Implemented by WSServer and WTServer
• Handles protocol-specific connection upgrades and request dispatching

Ingress Interface spec.go25-43

• Acts as an http.Handler that processes incoming HTTP requests
• Implements edge.Subscriber to receive new backend connections
• Provides GetRoundTripper() for host-to-session resolution
• Exposes management endpoints: AliasHandler(), RecordsHandler()

Storage Interface spec.go46-82

• Manages session lifecycle: Allocate(), Upsert(), RemoveSession()
• Implements health monitoring: Ping(), Scan()
• Maintains host-to-session mappings: GetRecord(), LookupRecord()
• Manages alias system: Alias(), Unalias(), Aliases()

Sources: spec.go1-83

---

Key Components

Session Management

The Store component store.go implements the Storage interface and maintains two core data structures:

• RecordMap: Maps session keys (TCP ports or onion IDs) to *Record instances
• AliasMap: Maps user-defined aliases to session keys for human-friendly addressing

Each Record represents an active backend session and contains:

• Key: Unique identifier (allocated TCP port or derived onion ID)
• Session: tunnel.Session instance for bidirectional communication
• RoundTripper: http.RoundTripper for forwarding HTTP requests over the tunnel
• Metadata: Headers, tags, IP address, path, connection timestamp

Sources: spec.go46-82

Protocol Servers

WSServer wsserver.go

• Listens on port 8080 for WebSocket and HTTP connections
• Dispatches requests based on type: upgrades, internal APIs, or proxied requests
• Uses edge.HTTPUpgrader to convert WebSocket connections to edge.Edge instances

WTServer wtserver.go

• Listens on ports 8082/8083 for WebTransport/HTTP3 connections
• Configures QUIC transport with TLS and datagram support
• Implements webtransport.Upgrader for WebTransport session creation

Both servers embed an Ingress implementation and delegate request handling to it.

Sources: spec.go13-22

---

System Operation Flow

The following diagram illustrates the complete lifecycle from backend connection to request handling:

Diagram: High-Level System Operation Flow

Operational Phases

1. Connection Phase Backend services connect to the relay using one of the supported protocols. The protocol-specific server (WSServer, WTServer, or upgrader) converts the raw connection into an edge.Edge abstraction.

2. Allocation Phase Store.Allocate() generates a unique key:

• For TCP protocol: allocates an available TCP port
• For HTTP protocol: derives an onion ID from connection metadata

3. Registration Phase Store.Upsert() creates a Record containing:

• The allocated key
• A tunnel.Session for bidirectional communication
• An http.RoundTripper for HTTP forwarding
• Connection metadata (headers, tags, IP, timestamp)

4. Active Phase Two concurrent goroutines maintain session health:

• Ping: Sends newline characters at regular intervals to detect connection failures
• Scan: Reads commands from the backend (e.g., CLOSE to terminate session)

The main thread handles incoming HTTP requests.

5. Request Phase When an external client makes an HTTP request:

1. Protocol server's Dispatch() method routes to appropriate handler
2. Handler calls GetRoundTripper() to resolve host to Record
3. ReverseProxy forwards request via Record.RoundTripper
4. MetricsTransport collects traffic statistics
5. Response returns through same path

6. Termination Phase Sessions end via:

• Explicit CLOSE command from backend
• Ping/Scan goroutine detecting connection failure
• Network errors or timeouts

Store.RemoveSession() removes the Record from RecordMap and cleans up associated aliases.

Sources: spec.go1-83 go.mod8-21

---

Module Dependencies

The relay leverages several key external modules:

Module	Version	Purpose
quic-go/quic-go	v0.59.0	Native QUIC protocol implementation
quic-go/webtransport-go	v0.10.0	WebTransport over HTTP/3
gorilla/websocket	v1.5.3	WebSocket protocol (indirect via btwiuse/wsconn)
hashicorp/yamux	v0.1.3+	Stream multiplexing over single connection
btwiuse/muxr	v0.0.1	HTTP request routing and middleware
btwiuse/dispatcher	v0.0.0	Request dispatch pattern
btwiuse/proxy	v0.0.0	Reverse proxy utilities
webteleport/webteleport	v0.5.40-alpha.12	Core tunnel and edge abstractions
webteleport/utils	v0.2.19-alpha.10	Utility functions

For detailed dependency analysis and protocol stack details, see Module Dependencies.

Sources: go.mod8-44

---

Architecture Highlights

Interface-Based Design

The system uses Go interfaces extensively to separate concerns:

• Relayer defines protocol server behavior
• Ingress defines HTTP handling behavior
• Storage defines session management behavior

This allows multiple implementations and easy testing.

Protocol Convergence

All transport protocols (WebSocket, WebTransport, QUIC, TCP) converge on the edge.Edge abstraction from the webteleport/webteleport package. This unified interface enables protocol-agnostic session management.

Dual Protocol Support

The relay supports both TCP-based (WebSocket) and UDP-based (QUIC/WebTransport) transports, providing flexibility for different network conditions and client capabilities.

Health Monitoring

Each session maintains continuous health monitoring through:

• Periodic ping messages to detect stale connections
• Stream scanning for control commands
• Automatic cleanup on connection failure

Metrics Collection

All HTTP traffic flows through MetricsTransport, which tracks:

• Request/response byte counts
• Request counts
• Response durations
• Status code distributions

For metrics details, see Metrics and Monitoring.

Sources: spec.go1-83 go.mod8-44

---

Request Routing

The relay implements sophisticated request routing through multiple dispatch stages:

1. Protocol Detection: WSServer.Dispatch() or WTServer.Dispatch() determines request type
2. Upgrade Check: WebSocket/WebTransport upgrade requests handled by protocol upgraders
3. Internal Path Check: Requests to /debug/* or /api/* routed to internal handlers
4. Host Lookup: Storage.GetRecord() or Storage.LookupRecord() resolves host to session
5. Proxy Creation: ReverseProxy configured with request rewriting rules
6. Backend Forward: Request sent via http.RoundTripper over tunnel.Session

For detailed routing logic, see Request Flow.

Sources: spec.go25-43

---

Session Identifiers

The relay uses two types of session identifiers:

TCP Port Allocation

For TCP-protocol backends, Store.Allocate() assigns an available TCP port. External clients connect to relay.host:<port> to reach the backend.

HTTP Onion ID

For HTTP-protocol backends, Store.Allocate() derives an onion ID (e.g., abc123.relay.host) based on connection metadata. External clients use HTTP Host headers to route requests.

Alias System

The relay supports user-friendly aliases that map to session keys. The AliasHandler API enables:

• POST /api/aliases - Create alias mappings
• GET /api/aliases - List all aliases
• DELETE /api/aliases/:name - Remove alias

For alias management details, see Alias Management.

Sources: spec.go46-82

---

Security Model

The relay provides:

1. TLS Encryption: All WebTransport and QUIC connections use TLS 1.3
2. Tunnel Security: Backend connections use tunnel.Session from the webteleport package
3. No Direct Exposure: Backend services never listen on public ports; all connections are outbound
4. Session Isolation: Each backend session has isolated routing and cannot access other sessions

The relay itself does not implement authentication; it relies on the security model of the underlying tunnel.Session protocol.

Sources: spec.go1-83 go.mod17

---

This overview provides the foundation for understanding the webteleport/relay architecture. Subsequent sections dive deeper into specific components and their implementations.