Technical documentation for the Spooky HTTP/3 to HTTP/2 reverse proxy and load balancer.

Quick Navigation

Getting Started

• Overview - Project introduction and capabilities
• Installation - System requirements and installation procedures
• Quick Start Tutorial - Step-by-step guide to get running

Configuration

• Configuration Reference - Complete configuration documentation
• TLS Setup - Certificate generation and management

User Guides

• Basic Usage - Core concepts and usage patterns
• Load Balancing - Load balancing algorithms and health checks

Architecture

• Architecture Overview - System design and component interaction
• Component Details - High-level architectural principles
• Component Breakdown - Detailed crate documentation

Deployment

• Production Deployment - Production deployment guide
• Troubleshooting - Common issues and solutions

Development

• Contributing Guide - Development setup and guidelines

Protocol Reference

• HTTP/3 Protocol - HTTP/3 overview and implementation
• QUIC Protocol - QUIC fundamentals and usage

API and Observability

• API Overview - Metrics, logging, and future admin API

Planning

• Roadmap - Feature roadmap and priorities

Documentation Structure

• README.md: Documentation index (this page)
• architecture.md: Main architecture document
• roadmap.md: Project roadmap
• getting-started/: Overview and installation guides
• configuration/: Configuration reference and TLS setup
• user-guide/: Basic usage and load balancing guide
• architecture/: High-level design and component details
• deployment/: Production deployment guidance
• troubleshooting/: Common issues and fixes
• development/: Development and contribution guidance
• tutorials/: Quickstart walkthroughs
• protocols/: HTTP/3 and QUIC protocol notes
• api/: API and observability overview
• internal/: Internal architecture notes

Quick References

Common Configuration Tasks

Basic upstream pool:

upstream:
  backend:
    route:
      path_prefix: "/"
    backends:
      - id: "backend-1"
        address: "127.0.0.1:8080"
        weight: 100
        health_check:
          path: "/health"
          interval: 5000

Note: Load balancing strategy is configured globally, not per upstream.

Path-based routing:

upstream:
  api:
    route:
      path_prefix: "/api"
    # ... backends

  web:
    route:
      path_prefix: "/"
    # ... backends

Load balancing algorithms: - random - Random selection - round-robin - Sequential rotation - consistent-hash - Hash-based affinity

Common Commands

Start Spooky:

spooky --config /etc/spooky/config.yaml

Test HTTP/3 connection:

curl --http3-only -k \
  --resolve proxy.example.com:9889:127.0.0.1 \
  https://proxy.example.com:9889/health

Check configuration:

spooky --config config.yaml  # Starts serving after validation

View logs:

# All logs
RUST_LOG=info spooky --config config.yaml

# Debug QUIC only
RUST_LOG=spooky_edge=debug spooky --config config.yaml

# Trace everything
RUST_LOG=trace spooky --config config.yaml

Documentation Guidelines

This documentation follows these principles:

1. Technical Accuracy: All examples are based on the actual codebase
2. Honest Status: Capabilities and limitations are documented as-is
3. Direct Communication: Clear, concise technical writing
4. Complete Coverage: All configuration options documented
5. Practical Examples: Working code and configuration samples

Contributing to Documentation

To improve documentation:

1. Check accuracy against source code
2. Test all examples and commands
3. Use clear, technical language
4. Include practical examples
5. Update this index when adding new docs

See Contributing Guide for more details.

External Resources

• QUIC RFC 9000
• HTTP/3 RFC 9114
• quiche Documentation
• Rust Documentation

Getting Help

• Review troubleshooting guide: docs/troubleshooting/common-issues.md
• Check GitHub issues for community discussions
• Read protocol documentation for HTTP/3 and QUIC specifics

License

Elastic License 2.0 (ELv2) - see LICENSE for details.