Request Flow

Relevant source files

• ingress.go
• legacy_session_store.go
• metrics.go
• misc.go
• record.go
• store.go

This document describes how HTTP requests are processed through the relay system, from initial reception to backend forwarding. It covers request classification, routing logic, session lookup, reverse proxy creation, and metrics collection. For information about how sessions are established and managed, see Store and Session Management. For details on the transport implementation that carries tunneled traffic, see HTTP Tunneling with RoundTripper.

Overview

The relay processes incoming HTTP requests through multiple stages: request classification (external vs internal), routing (path-based or host-based), session lookup (with alias resolution), reverse proxy creation, and traffic forwarding through established tunnel sessions. Each stage involves different components that collaborate to route traffic to the appropriate backend service.

Request Flow Architecture

Sources: misc.go1-79 ingress.go1-143 High-Level Diagram 4

Request Classification and Entry Points

When a request arrives at the relay, it first enters through protocol-specific servers (WSServer or WTServer) which call their IsUpgrade() method to determine whether the request is a protocol upgrade (WebSocket/WebTransport connection) or a regular HTTP request. Non-upgrade requests are routed through the Dispatch() method based on request characteristics.

Sources: High-Level Diagram 4

External vs Internal Request Routing

The relay distinguishes between external requests (normal traffic) and internal requests (administrative endpoints). Internal requests are identified by a .internal TLD suffix.

Sources: misc.go22-24 misc.go38-55 misc.go58-78 misc.go16-20

The IsInternal() function checks if the request host ends with .internal by calling utils.StripPort() to remove port numbers and then checking with strings.HasSuffix() for the suffix misc.go22-24 Internal requests with the special hostname root.internal (defined as ROOT_INTERNAL constant at misc.go13) are routed to RootInternalHandler(), which serves administrative endpoints. Other .internal hosts are handled by handleInternal() which returns a simple status message misc.go16-20

Administrative Endpoints

The WSServer.RootInternalHandler() serves three administrative endpoints controlled by environment variables:

Endpoint Purpose	Environment Variable	Handler Function	Response Type
Debug variables (expvars)	INTERNAL_DEBUG_VARS_PATH	expvar.Handler()	JSON metrics
Session records API	INTERNAL_API_SESSIONS_PATH	WSServer.RecordsHandler()	JSON array of Record
Alias management API	INTERNAL_ALIASES_PATH	WSServer.AliasHandler()	JSON map or status

Sources: misc.go38-55

The handler checks each environment variable and matches against r.URL.Path:

1. If os.Getenv("INTERNAL_DEBUG_VARS_PATH") matches, serves expvar.Handler() misc.go39-42
2. If os.Getenv("INTERNAL_API_SESSIONS_PATH") matches, serves s.RecordsHandler(w, r) misc.go44-47
3. If os.Getenv("INTERNAL_ALIASES_PATH") matches, serves s.AliasHandler(w, r) misc.go49-52
4. Otherwise, returns http.NotFound(w, r) misc.go54

Path-Based Routing for Root Requests

When a request is sent to the root hostname (without a subdomain), the relay performs path-based routing by extracting the leading path component and treating it as a session key.

Leading Component Extraction

The leadingComponent() function extracts the first segment of the URL path:

Sources: misc.go34-36

The function implementation at misc.go34-36:

func leadingComponent(s string) string {
	return strings.Split(strings.TrimPrefix(s, "/"), "/")[0]
}

For example, a request to http://root/abc/def/page.html extracts "abc" as the session key, and the path /abc/def/page.html is later stripped to /def/page.html before forwarding.

RootHandler Logic

The WSServer.RootHandler() method implements path-based routing:

Sources: misc.go58-78

The handler performs these steps:

1. Extracts the leading path component using leadingComponent(r.URL.Path) misc.go59
2. Calls GetRoundTripper(rpath) to retrieve the session's transport misc.go60
3. If found, creates a LoggedReverseProxy with the RoundTripper misc.go66
4. Configures rewrite rules to set X-Forwarded headers, URL host, and scheme misc.go67-75
5. Wraps the proxy with http.StripPrefix() to remove the leading component misc.go76
6. Increments the WebteleportRelayStreamsClosed counter after serving misc.go77
7. If not found, serves the default index (or 404) misc.go62

Host-Based Routing

For requests with non-root hostnames, the relay uses the hostname as the session key directly.

IngressHandler Dispatch

The IngressHandler.Dispatch() method implements host-based routing:

Sources: ingress.go118-134

The dispatch process:

1. Extracts the host from r.Host ingress.go119
2. Calls GetRoundTripper(r.Host) ingress.go119
3. If not found, returns utils.HostNotFoundHandler() ingress.go121
4. Creates a utils.LoggedReverseProxy(rt) with the RoundTripper ingress.go123
5. Sets rp.Rewrite to configure X-Forwarded headers, host, and scheme ingress.go124-128
6. Sets rp.ModifyResponse callback to increment expvars.WebteleportRelayStreamsClosed ingress.go129-132

Session Lookup and Alias Resolution

The GetRoundTripper() method is the key abstraction for retrieving a session's HTTP transport.

Record Lookup Flow

Sources: ingress.go45-51 store.go140-149 store.go114-125

The IngressHandler.GetRoundTripper() method:

1. Calls storage.GetRecord(h) with the hostname ingress.go46
2. Returns nil, false if not found ingress.go47-48
3. Returns rec.RoundTripper, true if found ingress.go50

The underlying Store.GetRecord() performs store.go140-149:

1. Calls utils.StripPort(h) to remove port number store.go141
2. Calls idna.ToASCII(k) to convert internationalized domain names store.go142
3. Calls strings.Split(k, ".")[0] to extract first component store.go143
4. Calls LookupRecord(k) with normalized key store.go144

The Store.LookupRecord() method store.go114-125:

1. First checks RecordMap[k] for direct match store.go116
2. If not found, checks AliasMap[k] for alias mapping store.go118
3. If alias exists, checks RecordMap[aliasKey] store.go120
4. Returns the Record if found at either step

Record Structure

Each Record contains the metadata and transport for a session:

Field	Type	Purpose
Key	string	Unique session identifier
Session	tunnel.Session	Underlying tunnel connection
RoundTripper	http.RoundTripper	HTTP transport (with metrics)
Header	tags.Tags	Request headers
Tags	tags.Tags	Session tags for filtering
Since	time.Time	Session start time
IP	string	Client IP address
Path	string	Original request path

Sources: record.go13-22

The RoundTripper field is wrapped with MetricsTransport during record creation, enabling automatic statistics collection for all traffic through this session.

Reverse Proxy Configuration

Once a RoundTripper is obtained, the relay creates a reverse proxy to forward traffic.

Proxy Rewrite Rules

The Rewrite function modifies outgoing requests:

Sources: misc.go67-75 ingress.go124-128

Both RootHandler and IngressHandler.Dispatch() use the same rewrite pattern:

1. Call req.SetXForwarded() to populate X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto headers misc.go68 ingress.go125
2. Set req.Out.URL.Host to preserve the original host misc.go70 ingress.go126
3. Set req.Out.URL.Scheme to "http" misc.go74 ingress.go127

The scheme is hardcoded to "http" because the tunnel itself handles the transport encryption; the backend service receives plain HTTP traffic over the secure tunnel.

Path Stripping for Root Requests

For path-based routing through RootHandler, the leading component is stripped before forwarding:

Original:  GET /abc/def/ghi
Extracted: "abc" (session key)
Stripped:  GET /def/ghi (forwarded to backend)

This is accomplished by wrapping the reverse proxy with http.StripPrefix("/"+rpath, rp) misc.go76

Sources: misc.go76

Metrics Collection During Request Forwarding

The MetricsTransport wrapper intercepts all HTTP traffic to collect statistics.

MetricsTransport RoundTrip Flow

Sources: metrics.go102-141

Statistics Tracked

The TransportStats structure maintains comprehensive metrics:

Metric	Type	Description
BytesSent	int64	Total bytes sent to backend
BytesReceived	int64	Total bytes received from backend
RequestCount	int64	Number of requests initiated
ResponseCount	int64	Number of successful responses
FailedRequests	int64	Number of failed requests
ActiveRequests	int64	Current in-flight requests
TotalRequestDuration	time.Duration	Cumulative request time
LastRequestTime	time.Time	Timestamp of last request
MaxRequestDuration	time.Duration	Longest request time
MinRequestDuration	time.Duration	Shortest request time

Sources: metrics.go11-22

Byte Counting Mechanism

The transport wraps request and response bodies with metric readers/writers:

Sources: metrics.go76-88

The wrapBody() function checks if the body implements io.ReadWriteCloser metrics.go77 and wraps it with either metricsReadWriteCloser metrics.go78-82 or metricsReadCloser metrics.go84-87 to count bytes as they're read or written.

Error Handling and Fallbacks

The relay provides multiple fallback mechanisms when sessions are not found.

404 Handler Chain

Sources: misc.go26-32 ingress.go121

When a session is not found:

1. IngressHandler.Dispatch() returns utils.HostNotFoundHandler() ingress.go121
2. RootHandler() calls DefaultIndex().ServeHTTP() misc.go62
3. DefaultIndex() checks the INDEX environment variable misc.go28
4. If set, creates a reverse proxy to the specified index URL misc.go29
5. Wraps the handler with WellKnownHealthMiddleware misc.go31
6. Otherwise, returns a basic 404 handler misc.go27

Stream Closure Tracking

After serving each proxied request, the relay increments expvar counters:

• RootHandler increments WebteleportRelayStreamsClosed misc.go77
• IngressHandler.Dispatch increments the same counter in ModifyResponse ingress.go130

This tracks the number of HTTP streams (requests) that have been completed through the relay.

Sources: misc.go77 ingress.go129-132

Complete Request Flow Example

Here is an end-to-end example of a request being processed:

Sources: misc.go58-78 ingress.go45-51 metrics.go102-141