Internal Error Handling

Relevant source files

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

• src/templates.rs
• src/error_template.html
• src/proxy.rs
• src/auth/form.rs
• src/config.rs
• src/state.rs

Internal error handling in Hodor manages failures during configuration loading, template rendering, and request proxying. The system ensures that errors result in user-friendly HTML pages or appropriate HTTP status codes rather than silent failures or raw stack traces.

The system categorizes errors into startup-time validation failures and runtime request processing errors. Startup errors usually trigger a process panic to prevent running with an invalid state, while runtime errors render styled error pages using Jinja2 templates.
Sources: src/templates.rs:115-139, src/config.rs:103-110

Startup Error Handling

Hodor validates its configuration and templates during the initialization phase in main.rs. If the configuration is invalid or the required environment variables are missing, the application panics with a descriptive message.

Configuration Validation

The validate_config function checks for mandatory settings and proper formatting.
Sources: src/config.rs:112-143

Check	Error Condition	Result
Password	PASSWORD is empty	Panic
Upstream	UPSTREAM is empty	Panic
Session TTL	SESSION_TTL is 0	Panic
Timeouts	Connect or Header timeouts are 0	Panic
CIDRs	Invalid network format in BYPASS_CIDRS	Panic

Template Validation

Before starting the server, Hodor attempts to render both the login and error templates. This ensures that any syntax errors in custom Jinja2 templates are caught immediately.
Sources: src/templates.rs:34-56, src/state.rs:72-88

Runtime Error Rendering

When a runtime error occurs—such as an upstream timeout or a failed proxy request—Hodor renders an HTML error page. The error_page_response function handles this process by injecting error details into the error.html template.

Error Template Variables

The following variables are passed to the error template for rendering:
Sources: src/templates.rs:88-100, src/error_template.html

Variable	Description
title	The page title from configuration
status_code	The numerical HTTP status code (e.g., 502)
heading	A short, bold description of the error
message	A human-readable explanation
custom_css	Verbatim CSS injected into the page
disable_default_css	Boolean to toggle built-in styles

Standard Error Responses

The system provides helper functions for common failure scenarios:

• Bad Gateway (502): Used when the upstream service is unreachable or the response headers time out.
• Internal Server Error (500): Used for generic failures during request processing.
  Sources: src/templates.rs:125-141, src/proxy.rs:114-142

Proxy and Body Errors

The proxy module and authentication handlers manage specific errors related to HTTP traffic and data collection.

Upstream Failures

Hodor monitors upstream interactions and converts failures into 502 Bad Gateway responses. This happens if:

1. The upstream connection cannot be established within upstream_connect_timeout.
2. Upstream response headers do not arrive within upstream_header_timeout.
3. The request builder fails to construct a valid proxied request.
   Sources: src/proxy.rs:114-142, src/state.rs:89-91

Request Body Errors

During login, Hodor enforces strict limits on the request body to prevent resource exhaustion.
Sources: src/auth/form.rs:71-94

Conclusion

Hodor's error handling strategy prioritizes fail-fast behavior during startup and informative, styled feedback during runtime. By validating components like templates and CIDRs before the server binds to a port, Hodor ensures that runtime errors are restricted to external factors like upstream availability.