Health Checks and Probes

Relevant source files

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

• AGENTS.md
• README.md
• src/main.rs
• src/proxy.rs
• src/tests/auth/handlers.rs
• src/config.rs

Hodor provides built-in mechanisms for monitoring the status of the proxy process and the availability of upstream services. These mechanisms allow container orchestrators like Kubernetes or Docker Compose to determine if the service is alive and ready to accept traffic.

The system distinguishes between a internal liveness probe, which monitors the Hodor process itself, and readiness probes, which verify the full path to the upstream application.

Liveness Monitoring

The liveness probe uses the reserved path /_gate/health. This endpoint reports whether the Hodor HTTP server is successfully running and listening for requests.

Behavior and Implementation

The /_gate/health route is wired directly in the application router and handled by the health function. When a request reaches this endpoint, Hodor performs the following actions:

• Bypasses all authentication checks.
• Returns a 200 OK status code.
• Returns the plain text body ok.

This check only validates the Hodor process. It does not attempt to contact the upstream service.

Sources: src/main.rs:25, AGENTS.md:17, README.md:231, src/tests/auth/handlers.rs:77-80

Logic Flow for Health Requests

The following diagram illustrates how the proxy differentiates health check requests from standard traffic.

The diagram shows that health check requests are intercepted before any authentication logic or proxying occurs.
Sources: AGENTS.md:16-21, src/proxy.rs:64-79

Readiness Monitoring

Readiness probes determine if the application is fully prepared to handle user traffic, including connectivity to the backend service. Because the standard health endpoint does not check the upstream, Hodor utilizes BYPASS_PATHS for readiness monitoring.

End-to-End Probes

To perform a readiness check, you must configure a specific path in the upstream application that Hodor allows to bypass authentication. This ensures the probe can reach the upstream without a session cookie or password.

1. Configure Path: Add the target health path to the BYPASS_PATHS configuration (e.g., /api/health).
2. Request Execution: The orchestrator sends a request to the configured path.
3. Upstream Verification: Hodor proxies this request to the upstream. If the upstream responds successfully, the probe passes.

Sources: README.md:281-285, AGENTS.md:29-30

Configuration Reference

The following table summarizes the endpoints and configuration options relevant to health monitoring.

Element	Type	Description
/_gate/health	Endpoint	Internal liveness check; returns 200 ok regardless of upstream status.
BYPASS_PATHS	Config	Comma-separated list of paths (e.g., /health/*) that skip authentication for readiness checks.
X-Hodor-Auth	Header	Set to public when a request hits a bypassed readiness path.

Sources: README.md:95, README.md:168, src/proxy.rs:32

Orchestrator Integration

Hodor is designed to run in environments without a shell (e.g., scratch Docker images). Therefore, orchestrators must use native HTTP probing capabilities rather than executing commands like curl inside the container.

Kubernetes Example

You should use the liveness probe for process health and a bypassed path for readiness.

livenessProbe:
  httpGet:
    path: /_gate/health
    port: 8080
  initialDelaySeconds: 2
  periodSeconds: 10

Sources: README.md:286-295

Summary

Health checks in Hodor ensure high availability by providing a low-overhead liveness endpoint (/_gate/health) and a flexible readiness mechanism via BYPASS_PATHS. The liveness probe confirms the proxy process is functional, while bypassed paths allow external tools to verify that the entire request chain to the upstream service is operational.