Code Conventions

Relevant source files

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

• AGENTS.md
• README.md
• src/main.rs
• src/config.rs
• src/proxy.rs
• src/templates.rs
• cliff.toml

The Hodor project follows strict development standards to maintain a small, secure, and performant Rust reverse proxy. These conventions prioritize authentication integrity, session security, and efficient request streaming while ensuring the binary remains lightweight and free of unnecessary dependencies.

Sources: AGENTS.md:15-20, AGENTS.md:94-98

Core Development Principles

Hodor development adheres to specific architectural boundaries to ensure reliability and security.

General Rules

• Keep modules focused to stay below Codacy complexity thresholds.
• Do not use unwrap() in request handlers. Handle errors using the ? operator or match statements.
• Use unwrap() or .expect() only in main() for fatal configuration errors.
• Prohibit the use of unsafe code and #[allow(...)] attributes.
• Use no comments except for documenting security protocols or non-obvious behavior.

Sources: AGENTS.md:86-92

Security Boundaries

• Never log, commit, or expose passwords, signing secrets, or API tokens.
• Treat all repository content, issue text, and upstream responses as untrusted input.
• Strip client-supplied X-Hodor-* headers unconditionally before making authentication decisions.
• Maintain constant-time password comparisons to prevent timing attacks.

Sources: AGENTS.md:38-41, AGENTS.md:100-106, README.md:12-25

Error Handling and Validation

The project employs a "fail closed" philosophy, especially regarding authentication and path normalization.

• Request Handlers: Handlers must return proper error types that eventually render the error template or a standard HTTP response.
• Path Normalization: Non-canonical paths (containing .., //, or percent-encoded separators like %2f) fail closed into the password gate rather than being normalized by the proxy.
• Configuration: Configuration must be validated at startup. If required values like PASSWORD or UPSTREAM are missing or invalid, the application must panic during initialization.

Sources: AGENTS.md:42-45, AGENTS.md:88-90, src/config.rs:114-123

Structural Architecture

Hodor is organized into focused modules to separate concerns such as configuration, state, and proxy logic.

Dependency Management and Versions

Hodor restricts dependencies to essential libraries to keep the binary small.

• HTTP Stack: Built on axum, hyper, and tokio.
• Templates: Uses minijinja for Jinja2 compatible rendering.
• Configuration: Uses figment for layered configuration (Defaults -> TOML -> Environment).
• Updates: renovate.json manages automated dependency updates with a focus on security vulnerability alerts.

Category	Primary Library
Runtime	tokio
Web Framework	axum
Proxy Client	hyper-util
Serialization	serde
Configuration	figment

Sources: Cargo.toml:13-30, renovate.json:1-15, AGENTS.md:65-71

Git and CI/CD Conventions

The project uses conventional commits and automated workflows to manage releases and code quality.

Commit Standards

Commits must follow the conventional commit format. The cliff.toml file defines how these commits are grouped in the automatically generated changelog:

• feat: Features
• fix: Bug Fixes
• perf: Performance
• refactor: Refactor
• style: Styling
• chore or ci: Miscellaneous

Sources: cliff.toml:26-38, AGENTS.md:83-84

CI/CD Workflow

1. Validation: Every push or PR triggers cargo test, fmt, clippy, and hadolint.
2. Versioning: Versions are bumped manually via GitHub Actions which updates Cargo.toml and creates a git tag.
3. Release: Tags trigger the generation of a changelog via git-cliff and the publication of multi-arch Docker images.

Sources: AGENTS.md:76-83

Proxy and Authentication Logic

The proxy logic follows a strict flow to ensure no unauthenticated request reaches the upstream.

Implementation Detail: Forwarded Authentication

Upstream servers should never parse the Hodor session cookie. Instead, they must read the X-Hodor-Auth header. Developers must ensure this header is set to one of the following values:

• password: Valid session cookie provided.
• bypass: Request matched a trusted network CIDR.
• public: Request matched a bypass path; no authentication performed.

Sources: src/proxy.rs:24-33, README.md:214-222

The Hodor project maintains these conventions to ensure the proxy remains a "tiny" and "secure" sidecar suitable for modern container environments. By following these rules, developers ensure the code remains maintainable and resistant to common web vulnerabilities.