Static Upstream Headers

Relevant source files

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

• src/config.rs
• src/proxy.rs
• src/state.rs
• README.md
• src/tests/config.rs
• src/tests/proxy.rs

Static Upstream Headers allow the Hodor proxy to inject a pre-defined HTTP header into every request sent to the backend server. This feature enables the proxy to pass authentication tokens or environment-specific identifiers to the upstream application without requiring the end-user to provide them.

Sources: README.md:105-110, AGENTS.md:36-41

Overview and Configuration

You configure a static header using the UPSTREAM_HEADER environment variable or the upstream_header key in hodor.toml. The system supports exactly one static header, provided in the format Name: value.

Sources: README.md:65-67, src/config.rs:13-15

Configuration Parameters

Key	Env Var	Type	Description
upstream_header	UPSTREAM_HEADER	String	A single header as Name: value to be sent to the upstream.

Sources: README.md:65-67, src/config.rs:13-15

Architectural Logic and Validation

Hodor validates the static header during the configuration loading phase. The parse_upstream_header function ensures the string contains a colon and splits it into a HeaderName and HeaderValue.

Sources: src/config.rs:248-253, src/state.rs:69-72

Reserved Headers and Constraints

To maintain security and proxy integrity, certain headers are reserved. Hodor rejects any configuration that attempts to override these values.

• Authentication Headers: Any header starting with x-hodor- or x-forwarded-.
• Protocol Headers: Host, Content-Length, Connection, Upgrade.
• Hop-by-Hop Headers: Keep-Alive, Proxy-Authenticate, Proxy-Authorization, TE, Trailer, Transfer-Encoding.

Sources: src/config.rs:254-273, README.md:115-118

Validation Flow

This diagram illustrates how the proxy validates a header string before accepting it into the application state.

Request Processing and Injection

When Hodor processes a request that clears the authentication gate, it constructs the upstream request in src/proxy.rs. The proxy logic inserts the configured static header into the request headers before dispatching it to the client.

Sources: src/proxy.rs:118-120, src/proxy.rs:77-80

Overwrite Behavior

If the client provides a header with the same name as the configured UPSTREAM_HEADER, Hodor replaces the client-supplied values entirely. This prevents header smuggling and ensures the upstream only receives the trusted value defined in the proxy configuration.

Sources: README.md:112-114, src/tests/proxy.rs:338-354

Data Flow Diagram

This sequence represents the injection of the static header during the proxying process.

Implementation Details

The AppState struct stores the parsed header as a (HeaderName, HeaderValue) tuple to avoid re-parsing during every request.

// src/state.rs:31
pub(crate) struct AppState {
    // ...
    pub(crate) upstream_header: Option<(HeaderName, HeaderValue)>,
    // ...
}

The injection occurs inside the proxy_request function:

// src/proxy.rs:118
if let Some((name, value)) = &state.upstream_header {
    proxied.headers_mut().insert(name.clone(), value.clone());
}

Sources: src/state.rs:31, src/proxy.rs:118-120

Conclusion

Static Upstream Headers provide a secure method for Hodor to authenticate itself to backend services. By strictly validating configuration and unconditionally replacing client headers, the system ensures that sensitive upstream credentials remain controlled by the proxy administrator.

Sources: README.md:112-118, src/config.rs:248-274