pollux/AGENTS.md

Overview

This project is a very simple gemini server which only serves static files, nothing else. It is meant to be generic so other people can use it.

Build/Test/Lint Commands

Core Commands

• cargo build - Build the project
• cargo build --release - Build optimized release version
• cargo run - Run the server with default config
• cargo test - Run all unit tests
• cargo test <test_name> - Run a specific test
• cargo test <module>::tests - Run tests in a specific module
• cargo clippy - Run linter checks for code quality
• cargo clippy --fix - Automatically fix clippy suggestions
• cargo clippy --bin <name> - Check specific binary
• cargo fmt - Format code according to Rust standards
• cargo check - Quick compile check without building

Common Test Patterns

• cargo test config::tests - Run config module tests
• cargo test request::tests - Run request handling tests
• cargo test -- --nocapture - Show println output in tests

Code Style Guidelines

Imports

• Group imports: std libs first, then external crates, then local modules
• Use use crate::module::function for internal imports
• Prefer specific imports over use std::prelude::*
• Keep imports at module level, not inside functions

Code Structure

• Use #[tokio::main] for async main function
• Keep functions small and focused (single responsibility)
• Use const for configuration values that don't change
• Error handling with Result<T, E> and ? operator
• Use tracing for logging, not println! in production code

Naming Conventions

• PascalCase for types, structs, enums
• snake_case for functions, variables, modules
• SCREAMING_SNAKE_CASE for constants
• Use descriptive names that indicate purpose

Error Handling

• Use io::Result<()> for I/O operations
• Convert errors to appropriate types with map_err when needed
• Use unwrap() only in tests and main() for unrecoverable errors
• Use expect() with meaningful messages for debugging
• Return early with Err() for validation failures

Security Requirements

• Critical: Always validate file paths with path_security::validate_path
• Never construct paths from user input without validation
• Use timeouts for network operations (tokio::time::timeout)
• Limit request sizes (see MAX_REQUEST_SIZE constant)
• Validate TLS certificates properly
• Never expose directory listings

Testing Guidelines

• Use tempfile::TempDir for temporary directories in tests
• Test both success and error paths
• Use #[cfg(test)] for test modules
• Create temporary test files in tmp/ directory
• Test security boundaries (path traversal, invalid inputs)
• Use assert_eq! and assert! for validations

Lint Checking

• cargo clippy - Run linter checks for code quality
• cargo clippy --fix - Automatically fix clippy suggestions
• cargo clippy --bin <name> - Check specific binary
• cargo fmt - Format code to match Rust standards
• Run clippy before every commit - Address all warnings before pushing code
• Current clippy warnings (2025-01-15):
  • src/server.rs:16-17 - Unnecessary borrows on file_path
  • src/logging.rs:31 - Match could be simplified to let statement

Testing

• Run cargo test before every commit to prevent regressions
• Pre-commit hook automatically runs full test suite
• Rate limiting integration test uses separate port for isolation
• All tests must pass before commits are allowed
• Test suite includes: unit tests, config validation, rate limiting under load

Async Patterns

• Use .await on async calls
• Prefer tokio::fs over std::fs in async contexts
• Handle timeouts for network operations
• Use Arc<Clone> for shared data across tasks

Gemini Protocol Specific

• Response format: "STATUS META\r\n"
• Status 20: Success (follow with MIME type)
• Status 41: Server unavailable (timeout, overload)
• Status 51: Not found (resource doesn't exist)
• Status 59: Bad request (malformed URL, protocol violation)
• Default MIME: "text/gemini" for .gmi files
• Default file: "index.gmi" for directory requests

Error Handling

• Concurrent request limit exceeded: Return status 41 "Server unavailable"
• Timeout: Return status 41 "Server unavailable" (not 59)
• Request too large: Return status 59 "Bad request"
• Empty request: Return status 59 "Bad request"
• Invalid URL format: Return status 59 "Bad request"
• Hostname mismatch: Return status 59 "Bad request"
• Path resolution failure: Return status 51 "Not found" (including security violations)
• File not found: Return status 51 "Not found"
• Reject requests > 1024 bytes (per Gemini spec)
• Reject requests without proper \r\n termination
• Use tokio::time::timeout() for request timeout handling
• Configurable concurrent request limit: max_concurrent_requests (default: 1000)

Configuration

• TOML config files with serde::Deserialize
• CLI args override config file values
• Required fields: root, cert, key, host
• Optional: port, log_level, max_concurrent_requests

Development Notes

• Generate self-signed certificates for local testing in tmp/ directory
• Use CN=localhost for development
• Fix every compiler warning before committing any code
• Create temporary files in the tmp/ directory for your tests like .gem files or images, etc., so they are gitignored
• Use path-security crate for path validation
• Default port: 1965 (standard Gemini port)
• Default host: 0.0.0.0 for listening
• Log level defaults to "info"

Environment Setup

• Install clippy: rustup component add clippy
• Ensure ~/.cargo/bin is in PATH (add source "$HOME/.cargo/env" to ~/.bashrc)
• Verify setup: cargo clippy --version