This page documents the Go module dependencies that form the foundation of the webteleport/relay system. It covers both direct and indirect dependencies, their versions, and their specific roles in enabling multi-protocol transport, session management, and request routing.
For information about how these dependencies are used in the deployment configuration, see Main Server Configuration. For details on how protocol-specific libraries integrate with the relay architecture, see Protocol Upgraders.
The relay system uses a dual-module structure to separate library code from executable binaries:
| Module | Path | Purpose |
|---|---|---|
| Main Module | github.com/webteleport/relay | Core relay library, interfaces, and protocol implementations |
| Command Module | github.com/webteleport/relay/cmd | Executable binaries for relay server and client applications |
The command module uses a local replace directive to reference the main module during development:
replace github.com/webteleport/relay => ..
This pattern allows co-development of the library and its consumers without requiring intermediate releases.
Sources: go.mod1-7 cmd/go.mod1-5
Sources: go.mod8-21 go.mod23-43
The relay system depends on two primary webteleport packages that provide tunnel session management and utility functions:
| Package | Version | Role |
|---|---|---|
github.com/webteleport/webteleport | v0.5.40-alpha.9 | Provides tunnel.Session interface, edge connection abstractions, and protocol-agnostic transport layer |
github.com/webteleport/utils | v0.2.19-alpha.8 | Provides utility functions for session handling, logging, and common operations |
These packages form the foundation for session multiplexing and tunnel management across all supported protocols.
The relay uses QUIC as its primary modern transport protocol, with WebTransport providing browser compatibility:
| Package | Version | Purpose |
|---|---|---|
github.com/quic-go/quic-go | v0.56.0 | Core QUIC protocol implementation (UDP-based transport with multiplexing, flow control, and encryption) |
github.com/quic-go/webtransport-go | v0.9.1-0.20251108062013-998e07d8f1b9 | WebTransport protocol over QUIC for browser compatibility |
github.com/quic-go/qpack | v0.5.1 | QPACK header compression for HTTP/3 (indirect dependency) |
The WebTransport dependency uses a specific commit hash (998e07d8f1b9) to ensure compatibility with the relay's requirements.
Sources: go.mod14-15 go.mod35
The btwiuse package family provides request routing, stream multiplexing, and connection utilities:
| Package | Version | Function |
|---|---|---|
github.com/btwiuse/dispatcher | v0.0.0 | Request dispatching based on host patterns and upgrade status |
github.com/btwiuse/muxr | v0.0.1 | Stream multiplexing for QUIC connections |
github.com/btwiuse/proxy | v0.0.0 | HTTP proxy utilities for request forwarding |
github.com/btwiuse/tags | v0.0.2 | Tag-based metadata system for session records |
These packages enable the relay to route requests intelligently and maintain multiplexed connections efficiently.
Sources: go.mod9-12
Additional dependencies support port allocation, DNS resolution, and HTTP handling:
| Package | Version | Purpose |
|---|---|---|
github.com/phayes/freeport | v0.0.0-20220201140144-74d24b5ae9f5 | Dynamic TCP port allocation for new sessions |
golang.org/x/crypto | v0.43.0 | TLS certificate generation and cryptographic operations |
golang.org/x/exp | v0.0.0-20251023183803-a4bb9ffd2546 | Experimental Go features (maps, slices utilities) |
golang.org/x/net | v0.46.0 | Extended networking primitives (HTTP/2, context) |
Sources: go.mod13 go.mod18-20
The relay system includes several indirect dependencies that are transitively required by direct dependencies:
| Package | Version | Brought In By | Purpose |
|---|---|---|---|
github.com/btwiuse/connect | v0.0.5 | webteleport | Connection establishment utilities |
github.com/btwiuse/wsconn | v0.0.6 | webteleport | WebSocket connection adapter |
github.com/btwiuse/forward | v0.0.0 | webteleport | Request forwarding primitives |
github.com/btwiuse/version | v0.0.2 | webteleport | Version information handling |
Sources: go.mod24-27
The relay supports two WebSocket implementations for flexibility:
| Package | Version | Usage |
|---|---|---|
github.com/gorilla/websocket | v1.5.3 | Traditional WebSocket protocol handling |
github.com/coder/websocket | v1.8.14 | Modern WebSocket implementation with improved performance |
github.com/gorilla/handlers | v1.5.2 | HTTP middleware (logging, CORS) |
Sources: go.mod28-30
| Package | Version | Purpose |
|---|---|---|
github.com/hashicorp/yamux | v0.1.3-0.20251104084018-94aaaeac4d7e | TCP-based stream multiplexing (used as fallback) |
The Yamux dependency uses a specific commit (94aaaeac4d7e) for compatibility with the relay's session management.
Sources: go.mod32
| Package | Version | Function |
|---|---|---|
github.com/felixge/httpsnoop | v1.0.3 | HTTP response capture for metrics |
github.com/rs/cors | v1.11.1 | Cross-Origin Resource Sharing support |
github.com/mattn/go-isatty | v0.0.20 | Terminal detection for logging |
github.com/miekg/dns | v1.1.68 | DNS resolution utilities |
k8s.io/apimachinery | v0.32.3 | Kubernetes API machinery (for future integration) |
Sources: go.mod29 go.mod36 go.mod33-34 go.mod42
The command module (cmd/go.mod) adds executable-specific dependencies:
| Package | Version | Purpose |
|---|---|---|
github.com/btwiuse/multicall | v0.0.5 | Multi-call binary pattern (single binary with multiple entry points) |
github.com/alexpantyukhin/go-pattern-match | v0.0.0-20230301210247-d84479c117d7 | Pattern matching for command routing |
github.com/ebi-yade/altsvc-go | v0.1.2-0.20220921153119-0c9cfefbad86 | HTTP Alternative Services header support |
The multicall pattern allows the client binary to act as multiple commands (tcp, quic-go, net-quic) based on invocation name.
Sources: cmd/go.mod7-13 cmd/go.mod16 cmd/go.mod26
The relay uses specific versioning strategies for different dependency types:
| Strategy | Packages | Rationale |
|---|---|---|
| Alpha Versions | webteleport/, relay/ | Active development with frequent breaking changes |
| Stable Versions | quic-go, gorilla/* | Mature libraries with semantic versioning |
| v0.0.x Versions | btwiuse/* | Development libraries maintained alongside relay |
| Commit Hashes | yamux, webtransport-go | Pin specific commits for compatibility |
| Date-Based | golang.org/x/* | Use latest features from extended libraries |
Sources: go.mod14-20 go.mod32
The module includes commented-out replace directives for local development:
These can be uncommented to:
The command module uses an active replace directive for the main relay module:
This ensures the command binaries always use the local relay library during development.
Sources: go.mod5-6 cmd/go.mod5
The command module inherits all dependencies from the main module through its replace directive:
This inheritance model ensures:
Sources: cmd/go.mod15-46
Both modules require Go 1.25:
This version provides:
Sources: go.mod3 cmd/go.mod3
| Category | Package | Version | Importance |
|---|---|---|---|
| Core Transport | quic-go | v0.56.0 | Critical - Primary transport protocol |
| Browser Support | webtransport-go | v0.9.1 | Critical - Browser compatibility |
| Session Management | webteleport | v0.5.40-alpha.9 | Critical - Core tunnel implementation |
| Request Routing | btwiuse/dispatcher | v0.0.0 | High - Request dispatching logic |
| Stream Muxing | btwiuse/muxr | v0.0.1 | High - Connection multiplexing |
| TCP Fallback | hashicorp/yamux | v0.1.3 | Medium - TCP stream multiplexing |
| WebSocket | gorilla/websocket | v1.5.3 | Medium - WebSocket protocol support |
| Port Allocation | phayes/freeport | v0.0.0 | Medium - Dynamic port assignment |
| Multi-Binary | btwiuse/multicall | v0.0.5 | Medium - Command binary structure |
Sources: go.mod8-21 cmd/go.mod7-13
Refresh this wiki