Testing Strategy

Relevant source files

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

• src/tests/auth/handlers.rs
• src/tests/auth/session.rs
• src/tests/auth/form.rs
• src/tests/config.rs
• src/tests/proxy.rs
• src/tests/templates.rs
• src/tests/auth/bypass_path.rs
• AGENTS.md

The hodor project employs a multi-layered testing strategy to verify the security, configuration, and proxying capabilities of the reverse proxy. Tests ensure that authentication remains intact, brute-force protection works as intended, and the streaming proxy correctly handles various protocols including WebSockets.

The test suite is built primarily using Rust's built-in test framework along with tokio for asynchronous integration tests.

Sources: AGENTS.md:92-102, src/main.rs:114

Integration Testing Architecture

Hodor uses integration tests to simulate real-world request flows. These tests spawn a local instance of the gate and, when necessary, a mock upstream server to verify end-to-end connectivity and header manipulation.

Mock Server Interaction

The project uses spawn_gate to launch an axum server on a random local port. For proxy verification, a mock upstream listener is created using tokio::net::TcpListener to capture and inspect the exact headers forwarded by hodor.

The diagram shows how integration tests differentiate between blocked unauthenticated requests and successful proxied requests.
Sources: src/tests/auth/handlers.rs:24-40, src/tests/proxy.rs:232-260

Core Test Modules

The test suite is organized into functional areas corresponding to the application's modules.

Module	Focus Area	Key Verification Points
Auth Handlers	HTTP Endpoints	Redirects, health checks, login/logout behavior, and rate limiting.
Session	Cryptography	Token signing, HMAC validation, expiry handling, and cookie security flags.
Proxy	Traffic Routing	Path joining, hop-by-hop header stripping, and WebSocket tunneling.
Config	Input Validation	Env override logic, CIDR parsing, and mandatory field checks.
Templates	UI Rendering	Jinja2 syntax validation, CSS injection, and XSS prevention via auto-escaping.

Sources: src/tests/auth/handlers.rs, src/tests/auth/session.rs, src/tests/proxy.rs, src/tests/config.rs, src/tests/templates.rs

Security and Authentication Testing

Security tests focus on preventing unauthorized access and ensuring the integrity of the session mechanism.

Session Integrity

Tests verify that the SECRET correctly signs tokens and that any tampering with the signature or expiry results in a validation failure.

• sign_and_validate_token_roundtrip: Ensures valid tokens are accepted.
• validate_token_rejects_tampered_signature: Confirms that modified signatures are rejected.
• validate_token_rejects_expired: Verifies that tokens with past timestamps are invalid.

Brute-Force Protection

Integration tests simulate repeated login attempts to trigger the rate limiter. The route_enforces_the_login_rate_limit test ensures that after RATE_LIMIT_ATTEMPTS, the server returns a 429 Too Many Requests status with a RETRY_AFTER header.

Sources: src/tests/auth/session.rs:11-45, src/tests/auth/handlers.rs:142-154

Proxy and Protocol Testing

The proxy tests verify that hodor behaves as a transparent yet secure intermediary.

Header Manipulation

Hodor must strip sensitive or hop-by-hop headers before forwarding requests. Tests verify:

• Stripping: Client-supplied X-Hodor-* headers are removed to prevent spoofing.
• Injection: The correct X-Hodor-Auth value (password, bypass, or public) is injected.
• Forwarding: X-Forwarded-For and X-Forwarded-Proto are correctly appended or preserved based on TRUST_PROXY settings.

WebSocket Tunneling

Integration tests verify bidirectional byte-copying for WebSockets. The test proxy_preserves_host_and_tunnels_websocket_bytes simulates a WebSocket handshake and confirms that data sent through the proxy is echoed correctly by the mock upstream.

The flow demonstrates the logic used to establish a WebSocket tunnel.
Sources: src/tests/proxy.rs:188-210, src/tests/proxy.rs:326-340, src/proxy.rs:207-220

Configuration Validation Testing

Tests for the configuration system ensure that invalid environment variables or TOML files fail early with descriptive errors.

• Mandatory Fields: Tests confirm that missing PASSWORD or UPSTREAM triggers a panic or error during startup.
• CIDR Parsing: Validates that both IPv4 and IPv6 CIDR strings are correctly parsed into IpNet objects.
• Bypass Paths: Validates path matching logic, ensuring that trailing wildcards (/*) work but interior wildcards are rejected.

Sources: src/tests/config.rs:77-105, src/tests/config.rs:146-160, src/tests/auth/bypass_path.rs:81-98

Continuous Integration and Coverage

The project uses GitHub Actions for automated testing and quality assurance.

1. CI Workflow: Runs cargo test, cargo fmt, and cargo clippy on every push and pull request.
2. Coverage: Uses cargo-llvm-cov to generate LCOV reports, which are uploaded to Codacy for tracking.
3. Linting: Includes hadolint for Dockerfile validation.

Sources: AGENTS.md:104-110, README.md:387-397

Hodor's testing strategy ensures that the "tiny" proxy remains robust by strictly validating every component from low-level token signing to high-level HTTP request handling and protocol upgrades.