Jeena 9d29321806 Fix Gemini protocol status codes and error handling

- Path security violations now return 51 (Not Found) instead of 59 (Bad Request)
- Timeouts return 41 (Server Unavailable) per Gemini spec
- Add comprehensive request validation: empty requests, oversized requests (>1024 bytes), malformed URLs
- Fix CLI argument conflict (config -c vs cert -c)
- Update documentation with status codes, error handling guidelines, and lint checking
- Add environment setup instructions for clippy and cargo PATH

2026-01-16 00:17:34 +00:00

2 KiB

Raw Blame History

Pollux - A Simple Gemini Server

Pollux is a lightweight Gemini server for serving static files securely. It supports TLS, hostname validation, and basic directory serving.

Requirements

Rust 1.70+ and Cargo.

Building

Clone or download the source, then run:

cargo build --release

This produces the target/release/pollux binary.

Running

Create a config file at /etc/pollux/config.toml or use --config to specify a path:

root = "/path/to/static/files"
cert = "/path/to/cert.pem"
key = "/path/to/key.pem"
host = "gemini.example.com"
port = 1965
log_level = "info"

Development Setup

Quick Start with Self-Signed Certs

mkdir -p tmp
openssl req -x509 -newkey rsa:2048 \
  -keyout tmp/key.pem \
  -out tmp/cert.pem \
  -days 365 \
  -nodes \
  -subj "/CN=localhost"

Update config.toml:

cert = "tmp/cert.pem"
key = "tmp/key.pem"

Run the server:

./pollux --config /path/to/config.toml

Or specify options directly (overrides config):

./pollux --root /path/to/static/files --cert cert.pem --key key.pem --host yourdomain.com --port 1965

Access with a Gemini client like Lagrange at gemini://yourdomain.com/.

Development Notes

These certificates are for local testing only
Browsers will show security warnings with self-signed certs
Certificates in the dev/ directory are gitignored for security

Options

--config: Path to config file (default /etc/pollux/config.toml)
--root: Directory to serve files from (required)
--cert: Path to certificate file (required)
--key: Path to private key file (required)
--host: Hostname for validation (required)
--port: Port to listen on (default 1965)

Certificate Management

Never commit certificate files to version control
Use development certificates only for local testing
Production certificates should be obtained via Let's Encrypt or your CA

Testing

Run cargo test for unit tests. Fix warnings before commits.

2 KiB Raw Blame History