This document describes the three fundamental interfaces that define the WebTeleport Relay system's core architecture: Relayer, Ingress, and Storage. These interfaces establish the contract between protocol handlers, HTTP request processing, and session management. Understanding these interfaces is essential for comprehending how the system components interact.
For implementation details of the Storage interface, see Store and Session Management. For the Ingress implementation, see Ingress Handler and HTTP Processing. For protocol-specific server implementations of Relayer, see Server Implementations.
Sources: spec.go1-83
The relay system is built around three core interfaces defined in spec.go that form a layered architecture:
Diagram: Three-Layer Interface Architecture
The architecture separates concerns across three layers:
Relayer handles protocol-specific connection upgradesIngress manages HTTP request routing and middlewareStorage maintains session state and record lifecycleSources: spec.go13-82
The Relayer interface represents an edge multiplexer with a built-in HTTP upgrader. It combines three capabilities through interface composition:
Diagram: Relayer Interface Composition
| Capability | Interface | Purpose |
|---|---|---|
| Request Dispatch | dispatcher.Dispatcher | Routes requests to appropriate handlers via Dispatch(r *http.Request) http.Handler |
| Protocol Upgrade | edge.HTTPUpgrader | Upgrades HTTP connections to WebSocket, WebTransport, or other protocols |
| Edge Consumption | Ingress | Processes incoming edge connections and serves HTTP traffic |
The Relayer interface is implemented by protocol-specific servers (WSServer, WTServer) that handle different transport mechanisms while providing a unified interface for connection management.
Sources: spec.go12-22
The Ingress interface exposes session storage as an HTTP server. It provides the primary mechanism for processing HTTP requests and managing the middleware pipeline.
Diagram: Ingress Interface Method Structure
| Method | Signature | Purpose |
|---|---|---|
ServeHTTP | (w http.ResponseWriter, r *http.Request) | Implements http.Handler to process all HTTP requests |
Use | (middlewares ...muxr.Middleware) | Applies middleware to the request processing pipeline |
GetRoundTripper | (h string) (http.RoundTripper, bool) | Retrieves the HTTP transport for a session by hostname |
AliasHandler | (w http.ResponseWriter, r *http.Request) | Handles /api/aliases endpoint for alias management |
RecordsHandler | (w http.ResponseWriter, r *http.Request) | Handles /api/sessions endpoint for session information |
Subscribe | (u edge.Upgrader) | Registers a protocol upgrader to receive edge connections |
The Ingress interface serves as the bridge between the HTTP layer and the underlying session storage, providing both request handling and session lookup capabilities.
Sources: spec.go24-43
The Storage interface defines the edge multiplexer responsible for managing session lifecycle, from allocation through removal. It maintains the mapping between session keys and active connections.
Diagram: Storage Interface Method Categories
| Method | Signature | Purpose |
|---|---|---|
Allocate | (r *edge.Edge) (string, error) | Generates a unique session key (TCP port or onion ID) |
Upsert | (k string, r *edge.Edge) | Creates or updates a session record in storage |
RemoveSession | (tssn tunnel.Session) | Removes a session and cleans up associated resources |
| Method | Signature | Purpose |
|---|---|---|
GetRecord | (h string) (*Record, bool) | Retrieves record by hostname, checking both direct and alias mappings |
LookupRecord | (k string) (*Record, bool) | Retrieves record directly by session key |
Records | () []*Record | Returns all active session records |
| Method | Signature | Purpose |
|---|---|---|
Ping | (r *edge.Edge) | Starts goroutine sending periodic keepalive newlines to maintain connection |
Scan | (r *edge.Edge) | Starts goroutine reading edge stream for commands (CLOSE, ALIAS, UNALIAS) |
| Method | Signature | Purpose |
|---|---|---|
Alias | (k string, v string) | Maps a user-friendly alias to a session key |
Unalias | (k string) | Removes an alias mapping |
Aliases | () map[string]string | Returns all current alias-to-key mappings |
Sources: spec.go45-82
The three interfaces work together in a coordinated flow from connection establishment through request processing:
Diagram: Interface Interaction Sequence
The request flow through the interfaces follows this pattern:
Relayer.Dispatch() determines request typeedge.HTTPUpgrader creates edge connectionStorage.Subscribe() receives edge, calls Allocate() and Upsert()Ingress.ServeHTTP() handles routingStorage.GetRecord() or Storage.LookupRecord() finds sessionRoundTripper forwards request through tunnelSources: spec.go13-82
The following diagram shows how concrete types implement these interfaces:
Diagram: Interface Implementation Hierarchy
| Interface | Implementation | File | Description |
|---|---|---|---|
Relayer | WSServer | wsserver.go | WebSocket and HTTP server implementation |
Relayer | WTServer | wtserver.go | WebTransport and HTTP/3 server implementation |
Ingress | IngressHandler | ingress.go | HTTP request processor with routing logic |
Storage | Store | store.go | Session storage with RecordMap and AliasMap |
Both WSServer and WTServer embed an Ingress implementation (typically IngressHandler), which in turn uses a Storage implementation (typically Store). This composition enables protocol servers to delegate HTTP processing and session management while focusing on protocol-specific concerns.
Sources: spec.go13-82
dispatcher.Dispatcher, edge.HTTPUpgrader, and Ingresshttp.Handler and edge.Subscriber/api/sessions (RecordsHandler), /api/aliases (AliasHandler)edge.Subscriber to receive new connectionsGetRecord() for hostname-based, LookupRecord() for key-basedSources: spec.go13-82
Refresh this wiki