HTTP & Web Proxy Handler

Relevant source files

The following files were used as context for generating this wiki page:

• warpgate-protocol-http/src/proxy.rs
• warpgate-protocol-http/src/lib.rs
• warpgate-protocol-http/src/api.rs (implied by module structure in lib.rs)
• warpgate-protocol-http/src/middleware.rs (referenced in lib.rs)
• warpgate-core/src/lib.rs
• warpgate-common/src/lib.rs
• README.md

The HTTP & Web Proxy Handler is a core component of Warpgate that enables the secure proxying of web traffic and provides a built-in administrative interface. It acts as a smart bastion for HTTPS connections, allowing users to authenticate locally before being forwarded to internal URLs or hosts within a protected network.

This module leverages the poem web framework for routing and middleware, reqwest for client-side proxying, and tokio-tungstenite for WebSocket support. It handles request rewriting, header injection, and session management, ensuring that internal targets receive the necessary context (such as the authenticated user's identity) while maintaining security through TLS and protocol-specific validations.

Sources: README.md:1-25, warpgate-protocol-http/src/lib.rs:40-100

Architecture and Request Flow

The HTTP handler operates by nesting various sub-routes under specialized prefixes. The /@warpgate prefix is reserved for internal operations, including the User API, Admin API, and the Web UI assets. Any request not matching this prefix is directed to a "catch-all" endpoint that proxies the request to the user's selected target.

Request Processing Flow

The following diagram illustrates how an incoming HTTP request is processed through the middleware stack and routed to either the internal API or an external target.

Key Components

Component	Description
HTTPProtocolServer	The main entry point that implements the ProtocolServer trait and runs the Poem server.
ProxyHandler	Logic found in proxy.rs that executes the actual forwarding of HTTP and WebSocket data.
SessionStore	Manages active HTTP sessions and provides vacuuming for expired sessions.
TicketMiddleware	Handles authentication via pre-generated access tickets.
Catchall	The endpoint that intercepts standard web traffic to forward it to the active target.

Sources: warpgate-protocol-http/src/lib.rs:43-60, warpgate-protocol-http/src/proxy.rs:205-210

Proxy Logic and Request Rewriting

When a request is proxied to a target, Warpgate performs several transformations to ensure compatibility and pass along security context. This is primarily handled by proxy_normal_request for standard HTTP and proxy_websocket_request for persistent connections.

Header Injection and Sanitization

Warpgate sanitizes sensitive headers that should not be forwarded (e.g., HOST, CONNECTION, UPGRADE, and WebSocket keys) and injects its own metadata headers.

• X-Forwarded Headers: Standard headers like x-forwarded-for, x-forwarded-host, and x-forwarded-proto are added to preserve the original client's connection info.
• Warpgate Identity: The proxy injects x-warpgate-username and x-warpgate-authentication-type to inform the target of the authenticated user.

Sources: warpgate-protocol-http/src/proxy.rs:56-82, warpgate-protocol-http/src/proxy.rs:188-203

URI Construction

The proxy constructs a new URI based on the configured TargetHTTPOptions. It maps the incoming path and query parameters to the target URL while adjusting the scheme (HTTP vs HTTPS) based on the target's TLS mode.

// Simplified URI construction logic
fn construct_uri(req: &Request, options: &TargetHTTPOptions, websocket: bool) -> Result<Uri> {
    let target_uri = Uri::try_from(options.url.clone())?;
    let source_uri = req.uri().clone();
    
    let mut uri = http::uri::Builder::new()
        .authority(target_uri.authority().unwrap().clone())
        .path_and_query(source_uri.path_and_query().unwrap().clone());
    // ... scheme selection logic ...
    Ok(uri.build()?)
}

Sources: warpgate-protocol-http/src/proxy.rs:92-125

Response Rewriting

To prevent "leaking" the internal structure of the target, Warpgate rewrites specific response headers:

1. Location: Redirect headers are rewritten to point back to the proxy's authority if the target tries to redirect the user within its own domain.
2. Set-Cookie: Cookies are modified to ensure they are treated as session cookies and parsed correctly for the proxy context.

Sources: warpgate-protocol-http/src/proxy.rs:150-178

WebSocket Proxying

Warpgate supports bidirectional WebSocket proxying using a split-stream architecture. It establishes a connection to the target server and then bridges the client-side poem WebSocket with the target-side tungstenite connection.

WebSocket Proxy Flow

The following sequence diagram represents the bridging of a WebSocket connection.

Protocol Configuration

The HTTP handler behavior is governed by HttpConfig and individual TargetHTTPOptions.

Target HTTP Options

These options define how Warpgate connects to a specific backend web service.

Field	Type	Description
url	String	The base URL of the internal target.
tls.mode	TlsMode	Security for the target connection: Disabled, Preferred, or Required.
tls.verify	bool	Whether to verify the target's TLS certificate.
external_host	Option<String>	An optional domain used for domain-based routing to this target.
headers	HashMap	Custom headers to inject into requests sent to this target.

Sources: warpgate-protocol-http/src/proxy.rs:92-100, warpgate-web/src/admin/Target.svelte:180-200

Implementation Detail: HTML Embedding

When proxying HTML content (text/html), Warpgate can optionally inject its own scripts and stylesheets into the <head> of the page. This is used to provide the Warpgate overlay or management bar within the target application.

The proxy looks for the </head> tag and replaces it with the injected assets followed by the original tag.

// HTML injection logic in proxy.rs
let mut inject = format!(
    r#"<script type="module" src="/@warpgate/{}"></script>"#,
    script_manifest.file
);
// ... inject CSS ...
let content = content.replacen("</head>", &format!("{inject}</head>"), 1);

Sources: warpgate-protocol-http/src/proxy.rs:310-330

Summary

The HTTP & Web Proxy Handler provides the primary interface for web-based access within Warpgate. By acting as a sophisticated reverse proxy, it abstracts the complexity of authentication, TLS termination, and session management. It ensures that internal web applications remain hidden behind the bastion while providing the necessary user context to the backend via injected headers, supporting both standard HTTP requests and real-time WebSocket communication.