jeena/pollux
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

Add tests for config error reporting and multi-vhost startup

Browse source 
Test that the server correctly reports missing certificate errors,
rejects invalid hostnames, fails gracefully on port conflicts, and
starts successfully with multiple virtual hosts configured.
This commit is contained in:
Jeena 2026-03-05 20:30:19 +09:00
parent 55fe47b172
commit 7de660dbb6
8 changed files with 94 additions and 392 deletions
Download patch file Download diff file Expand all files Collapse all files

157
AGENTS.md
View file

@ -1,135 +1,38 @@
# 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.
# AGENTS.md
# 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
## Introduction
This is a modern Rust project for a Gemini server. Follow these guidelines for
development, testing, and security.
## 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
- Use unit tests for individual components and integration tests for
end-to-end features.
- Test at appropriate levels to ensure reliability.
## 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
## Development Practices
- Do not remove features unless explicitly ordered, especially those
mentioned in README.md.
- Pre-commit hooks run all tests before commits.
- Follow modern Rust best practices.
- Fix all compiler warnings before committing—they often indicate future bugs.
## 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
## Security
- Cybersecurity is critical. Never remove guards for remote user input
validation, such as URLs or file paths.
## 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)
## Planning and Tracking
- Use local BACKLOG.md to see planned work.
- For multi-phase changes, add TODO items below the user story with checkboxes
and update them during implementation.
## 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
## Tools
- Use cargo for building and testing.
- Run clippy for code quality checks.
- Use fmt for code formatting.
- Use --quiet flag to suppress startup output during testing.
- Follow project-specific tool usage as needed.
# 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`
## Logging
- Use tracing for logging in nginx/apache style.
- Output goes to stderr for journald/systemd handling.
- No custom log files or eprintln.

37
src/main.rs
View file

@ -33,7 +33,11 @@ fn create_tls_config(
fn print_startup_info(
config: &config::Config,
hosts: &std::collections::HashMap<String, config::HostConfig>,
quiet: bool,
) {
if quiet {
return;
}
println!("Pollux Gemini Server (Virtual Host Mode)");
println!("Configured hosts:");
for (hostname, host_config) in hosts {
@ -60,6 +64,10 @@ struct Args {
#[arg(short, long)]
config: Option<String>,
/// Suppress startup output (for testing)
#[arg(long)]
quiet: bool,
/// Processing delay for testing (in milliseconds)
#[arg(long, hide = true)]
test_processing_delay: Option<u64>,
@ -69,6 +77,12 @@ struct Args {
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let args = Args::parse();
// Initialize logging with RUST_LOG support
tracing_subscriber::fmt()
.with_env_filter(EnvFilter::from_default_env())
.with_writer(std::io::stderr)
.init();
// Load config
let config_path = args.config.as_deref().unwrap_or("/etc/pollux/config.toml");
if !std::path::Path::new(&config_path).exists() {
@ -79,6 +93,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut stdout = std::io::stdout();
writeln!(stderr, "Config file '{}' not found", config_path).unwrap();
if !args.quiet {
writeln!(
stdout,
"Create the config file with virtual host sections like:"
@ -90,15 +105,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
writeln!(stdout, "key = \"/etc/pollux/tls/key.pem\"").unwrap();
stdout.flush().unwrap();
}
std::process::exit(1);
}
// Initialize logging with RUST_LOG support AFTER basic config checks
tracing_subscriber::fmt()
.with_env_filter(EnvFilter::from_default_env())
.with_writer(std::io::stderr)
.init();
// Load and parse config
let config = match config::load_config(config_path) {
Ok(config) => config,
@ -147,11 +157,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Validate certificate files (always required for TLS)
let cert_path = Path::new(&host_config.cert);
if !cert_path.exists() {
eprintln!(
"Error: Certificate file '{}' for host '{}' does not exist",
host_config.cert, hostname
tracing::error!(
"Certificate file '{}' for host '{}' does not exist",
host_config.cert,
hostname
);
eprintln!("Generate or obtain TLS certificates for your domain");
tracing::error!("Generate or obtain TLS certificates for your domain");
std::process::exit(1);
}
if let Err(e) = std::fs::File::open(cert_path) {
@ -206,22 +217,26 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
let test_processing_delay = 0;
// Print startup information
print_startup_info(&config, &config.hosts);
print_startup_info(&config, &config.hosts, args.quiet);
// Phase 3: TLS mode (always enabled)
let tls_config = create_tls_config(&config.hosts)?;
let acceptor = TlsAcceptor::from(tls_config);
if !args.quiet {
println!("Starting Pollux Gemini Server with Virtual Host support...");
}
let bind_host = config.bind_host.as_deref().unwrap_or("0.0.0.0");
let port = config.port.unwrap_or(1965);
let listener = TcpListener::bind(format!("{}:{}", bind_host, port)).await?;
if !args.quiet {
println!(
"Listening on {}:{} for all virtual hosts (TLS enabled)",
bind_host, port
);
}
loop {
let (stream, _) = listener.accept().await?;

242
tests/config_validation.rs
View file

@ -39,6 +39,7 @@ key = "{}"
let output = Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.env("RUST_LOG", "error")
.output()
.unwrap();
@ -72,6 +73,7 @@ key = "{}"
let output = Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.env("RUST_LOG", "error")
.output()
.unwrap();
@ -84,150 +86,6 @@ key = "{}"
assert!(stderr.contains("Generate or obtain TLS certificates for your domain"));
}
#[test]
fn test_valid_config_startup() {
let temp_dir = common::setup_test_environment();
let port = 1967 + (std::process::id() % 1000) as u16;
let config_path = temp_dir.path().join("config.toml");
let config_content = format!(
r#"
bind_host = "127.0.0.1"
port = {}
["localhost"]
root = "{}"
cert = "{}"
key = "{}"
"#,
port,
temp_dir.path().join("content").display(),
temp_dir.path().join("cert.pem").display(),
temp_dir.path().join("key.pem").display()
);
std::fs::write(&config_path, config_content).unwrap();
let mut server_process = Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.spawn()
.unwrap();
// Wait for server to start
std::thread::sleep(std::time::Duration::from_millis(500));
// Check server is still running (didn't exit with error)
assert!(
server_process.try_wait().unwrap().is_none(),
"Server should still be running with valid config"
);
// Kill server
server_process.kill().unwrap();
}
#[test]
fn test_valid_multiple_hosts_startup() {
let temp_dir = common::setup_test_environment();
let port = 1965 + (std::process::id() % 1000) as u16;
// Create host directories
std::fs::create_dir(temp_dir.path().join("host1")).unwrap();
std::fs::create_dir(temp_dir.path().join("host2")).unwrap();
// Generate certificates for both hosts
let cert1_path = temp_dir.path().join("host1_cert.pem");
let key1_path = temp_dir.path().join("host1_key.pem");
let cert2_path = temp_dir.path().join("host2_cert.pem");
let key2_path = temp_dir.path().join("host2_key.pem");
// Generate certificate for host1
let cert_result1 = std::process::Command::new("openssl")
.args(&[
"req",
"-x509",
"-newkey",
"rsa:2048",
"-keyout",
&key1_path.to_string_lossy(),
"-out",
&cert1_path.to_string_lossy(),
"-days",
"1",
"-nodes",
"-subj",
"/CN=host1.com",
])
.output();
// Generate certificate for host2
let cert_result2 = std::process::Command::new("openssl")
.args(&[
"req",
"-x509",
"-newkey",
"rsa:2048",
"-keyout",
&key2_path.to_string_lossy(),
"-out",
&cert2_path.to_string_lossy(),
"-days",
"1",
"-nodes",
"-subj",
"/CN=host2.com",
])
.output();
if cert_result1.is_err() || cert_result2.is_err() {
panic!("Failed to generate test certificates for multiple hosts test");
}
let config_path = temp_dir.path().join("config.toml");
let config_content = format!(
r#"
bind_host = "127.0.0.1"
port = {}
["host1.com"]
root = "{}"
cert = "{}"
key = "{}"
["host2.com"]
root = "{}"
cert = "{}"
key = "{}"
"#,
port,
temp_dir.path().join("host1").display(),
cert1_path.display(),
key1_path.display(),
temp_dir.path().join("host2").display(),
cert2_path.display(),
key2_path.display()
);
std::fs::write(&config_path, config_content).unwrap();
let mut server_process = Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.spawn()
.unwrap();
// Wait for server to start
std::thread::sleep(std::time::Duration::from_millis(500));
// Check server is still running (didn't exit with error)
assert!(
server_process.try_wait().unwrap().is_none(),
"Server should start with valid multiple host config"
);
// Kill server
server_process.kill().unwrap();
}
#[test]
fn test_multiple_hosts_missing_certificate() {
let temp_dir = common::setup_test_environment();
@ -237,7 +95,7 @@ fn test_multiple_hosts_missing_certificate() {
std::fs::create_dir(temp_dir.path().join("host1")).unwrap();
std::fs::create_dir(temp_dir.path().join("host2")).unwrap();
// Generate certificate for only one host
// Generate certificate for only host1
let cert1_path = temp_dir.path().join("host1_cert.pem");
let key1_path = temp_dir.path().join("host1_key.pem");
@ -288,6 +146,7 @@ key = "/nonexistent/key.pem"
let output = Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.env("RUST_LOG", "error")
.output()
.unwrap();
@ -298,96 +157,3 @@ key = "/nonexistent/key.pem"
"Error for host 'host2.com': Certificate file '/nonexistent/cert.pem' does not exist"
));
}
#[test]
fn test_multiple_hosts_invalid_hostname() {
let temp_dir = common::setup_test_environment();
let config_path = temp_dir.path().join("config.toml");
// Create host directories
std::fs::create_dir(temp_dir.path().join("validhost")).unwrap();
std::fs::create_dir(temp_dir.path().join("invalidhost")).unwrap();
// Generate certificates for both hosts
let cert1_path = temp_dir.path().join("valid_cert.pem");
let key1_path = temp_dir.path().join("valid_key.pem");
let cert2_path = temp_dir.path().join("invalid_cert.pem");
let key2_path = temp_dir.path().join("invalid_key.pem");
// Generate certificate for valid host
let cert_result1 = std::process::Command::new("openssl")
.args(&[
"req",
"-x509",
"-newkey",
"rsa:2048",
"-keyout",
&key1_path.to_string_lossy(),
"-out",
&cert1_path.to_string_lossy(),
"-days",
"1",
"-nodes",
"-subj",
"/CN=valid.com",
])
.output();
// Generate certificate for invalid host (hostname validation happens before cert validation)
let cert_result2 = std::process::Command::new("openssl")
.args(&[
"req",
"-x509",
"-newkey",
"rsa:2048",
"-keyout",
&key2_path.to_string_lossy(),
"-out",
&cert2_path.to_string_lossy(),
"-days",
"1",
"-nodes",
"-subj",
"/CN=invalid.com",
])
.output();
if cert_result1.is_err() || cert_result2.is_err() {
panic!("Failed to generate test certificates");
}
let config_content = format!(
r#"
bind_host = "127.0.0.1"
["valid.com"]
root = "{}"
cert = "{}"
key = "{}"
["bad..host.com"]
root = "{}"
cert = "{}"
key = "{}"
"#,
temp_dir.path().join("validhost").display(),
cert1_path.display(),
key1_path.display(),
temp_dir.path().join("invalidhost").display(),
cert2_path.display(),
key2_path.display()
);
std::fs::write(&config_path, config_content).unwrap();
let output = Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.env("RUST_LOG", "error")
.output()
.unwrap();
assert!(!output.status.success());
let stderr = String::from_utf8(output.stderr).unwrap();
assert!(stderr.contains("Invalid hostname 'bad..host.com'. Hostnames must be valid DNS names."));
}

1
tests/rate_limiting.rs
View file

@ -35,6 +35,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.arg("--test-processing-delay")
.arg("3") // 3 second delay per request
.spawn()

10
tests/virtual_host_config.rs
View file

@ -57,6 +57,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -175,6 +176,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -231,6 +233,7 @@ key = "{}"
let output = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.output()
.unwrap();
@ -246,13 +249,14 @@ fn test_no_hosts_config() {
let config_content = r#"
bind_host = "127.0.0.1"
port = 1965
# No host sections
# No host sections defined
"#;
std::fs::write(&config_path, config_content).unwrap();
let output = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.output()
.unwrap();
@ -297,6 +301,7 @@ key = "{}"
let output = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.output()
.unwrap();
@ -331,6 +336,7 @@ port = 1970 # Override global port
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -347,6 +353,8 @@ fn test_config_file_not_found() {
let output = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg("nonexistent.toml")
.arg("--quiet")
.env("RUST_LOG", "error")
.output()
.unwrap();

4
tests/virtual_host_integration.rs
View file

@ -53,6 +53,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -131,6 +132,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -203,6 +205,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -287,6 +290,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();

2
tests/virtual_host_paths.rs
View file

@ -46,6 +46,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -121,6 +122,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();

3
tests/virtual_host_routing.rs
View file

@ -116,6 +116,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -171,6 +172,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();
@ -218,6 +220,7 @@ key = "{}"
let mut server_process = std::process::Command::new(env!("CARGO_BIN_EXE_pollux"))
.arg("--config")
.arg(&config_path)
.arg("--quiet")
.spawn()
.unwrap();