Home

Next

Spooky lets HAProxy, NGINX, and Apache environments adopt QUIC/HTTP/3 in days instead of quarters.

Technical documentation for the Spooky HTTP/3 edge proxy and load balancer.

Quick Navigation

Getting Started

Configuration

User Guides

Architecture

Deployment

Development

Protocol Reference

API and Observability

Planning

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
  • tutorials/: Quickstart walkthroughs
  • protocols/: HTTP/3 and QUIC protocol notes
  • api/: API and observability overview

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 can be configured per-upstream and also at the top level as a fallback default.

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 (session stickiness, cache locality) - least-connections - Routes to backend with fewest active requests - latency-aware - Routes to fastest backends using EWMA latency scoring - sticky-cid - QUIC connection-ID affinity via consistent hashing

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

Getting Help

License

GNU General Public License v3.0 (GPLv3) - see LICENSE for details.

Overview