Request Routing

Relevant source files

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

• src/main.rs
• src/proxy.rs
• src/config.rs
• src/state.rs
• README.md
• AGENTS.md

Request Routing in Hodor determines how incoming HTTP traffic is handled based on the request path, client origin, and authentication state. The system either routes requests to internal administrative endpoints, proxies them to a configured upstream service, or intercepts them to display a login gate.

Sources: src/main.rs:24-30, README.md:129-138

Internal Endpoint Routing

Hodor reserves specific paths under the /_gate/ prefix for internal operations. These routes bypass the standard proxy logic and are handled directly by the application.

Path	Method	Function	Description
/_gate/login	GET	login_get	Redirects to the root or displays the login form.
/_gate/login	POST	login_post	Processes password submissions and issues session cookies.
/_gate/logout	GET	logout	Clears the session cookie and redirects the user.
/_gate/health	GET	health	Returns a 200 OK status for liveness probes.

Sources: src/main.rs:25-28, README.md:214-218

Routing Logic and Flow

The fallback handler proxy_or_login manages all requests not matching reserved internal paths. The routing decision follows a strict hierarchy of bypass rules and authentication checks.

Request Flow Diagram

The following diagram illustrates the decision matrix used to route an incoming request.

Authentication Resolution

The resolve_auth_method function evaluates the request against three criteria to determine the AuthMethod:

1. Public Paths: Checked via is_bypass_path. Matches configured exact paths or prefix patterns (e.g., /static/*).
2. Session Validity: Checked via is_authenticated. Validates the HMAC-SHA256 signature of the session cookie.
3. Network Bypass: Checked via is_bypass_ip. Compares the resolved client IP against BYPASS_CIDRS.

Sources: src/proxy.rs:68-81, src/config.rs:189-191

Upstream Proxy Routing

When a request is approved for proxying, Hodor transforms the request before forwarding it to the UPSTREAM destination.

URI Reconstruction

Hodor constructs the target URI by joining the upstream_base_path with the incoming request path. It preserves the original query string during this process.

// src/proxy.rs:105-106
let path = join_paths(&state.upstream_base_path, parts.uri.path());
let uri = build_upstream_uri(&state, &path, parts.uri.query());

Sources: src/proxy.rs:105-106, src/proxy.rs:260-269

Header Manipulation

Routing includes significant header modifications to ensure security and provide context to the upstream:

• Auth Identification: Injects X-Hodor-Auth with values password, bypass, or public.
• Header Stripping: Removes any client-supplied X-Hodor-* headers to prevent authentication forgery.
• Forwarding Headers: Appends the client IP to X-Forwarded-For and sets X-Forwarded-Proto.
• Hop-by-Hop Headers: Removes standard hop-by-hop headers (e.g., Connection, Keep-Alive) before proxying.

Sources: src/proxy.rs:125-132, src/proxy.rs:188-201, AGENTS.md:31-33

WebSocket Routing

If the request contains a WebSocket upgrade header, Hodor establishes a bidirectional tunnel between the client and the upstream.

Conclusion

Request Routing in Hodor acts as a secure gateway, prioritizing internal management routes before evaluating authentication for proxied traffic. By combining path-based bypasses, network-based trust, and signed session cookies, Hodor ensures that upstream services only receive authorized traffic while providing them with verified metadata via custom headers.