Home

Next

Spooky is a modern edge runtime for high-trust APIs. This documentation set is organized so readers can quickly answer five questions:

  • what Spooky is
  • where to start
  • where to deploy and operate it
  • where to troubleshoot issues
  • where exact product reference lives

Start Here

Goal Go to
Understand the product README and Getting Started Overview
Install and run Spooky Getting Started
Prepare for deployment Operations Overview and Production Deployment
Troubleshoot issues Common Issues and Runbook
Find exact supported behavior Reference Overview

Documentation Paths

Operator — install, configure, run in production

Document What you'll find
Installation Debian package, build from source, system requirements, TLS certificate layout
Docker Container image, Compose bootstrap, smoke-test scripts
Configuration Reference Every config key, type, default, and constraint in one place
TLS Setup Certificate generation, mTLS client auth, key ownership and permissions
Production Deployment Systemd unit, privilege drop, sysctl tuning, canary rollout guidance
Production Readiness Canonical statement of what is production-ready today and what still blocks GA
Operations Overview Main entry point for deployment, rollout, observability, and failure handling
Troubleshooting Symptom-driven diagnostics and operator checks
Limitations The current hard product limits, without marketing language

Architecture — understand the runtime and subsystem ownership

Document What you'll find
Architecture Overview Architecture entry point, shared product flow, ingress model, and runtime boundaries
Request Lifecycle Canonical flow from intake through admission, routing, transport, and outcome recording
Bootstrap vs QUIC Exact boundary between the native HTTP/3 path and the compatibility ingress path
Transport Boundary What transport owns, what edge owns, and how H1/H2 execution stays hidden behind one facade
Backend Lifecycle Backend identity, resolution, health, membership, and operator-visible lifecycle state
Runtime Generation Model How runtime reload, active generations, and shared services work
Component Breakdown Per-crate responsibilities, inter-crate boundaries, key types
Distributed Quota Contract Semantic contract for quota semantics, selector composition, and distributed counter behavior
Codebase Map Current crate/module map and where major logic lives
Development Invariants Core runtime invariants, ownership assumptions, and rules the code depends on
Public API Surface Inventory Current canonical public surfaces, hidden internals, and remaining intentional exports

Control API and Operations — runtime control, observability, and failure handling

Document What you'll find
API Overview Metrics endpoint and Control API surfaces at a high level
Control API Reference Endpoint-by-endpoint control API contract
Metrics Reference Metric names, labels, and exported runtime signals
Operations Overview Operator map for deployment, sizing, tuning, and failure handling
Distributed Quota Distributed quota policy examples, Redis setup, degraded-mode guidance, and operator interpretation
Runbook Day-2 operational procedures and troubleshooting flow
Failure Modes Expected degraded behaviors and what they mean operationally
Sizing and Capacity Capacity planning and scaling guidance

Protocol, traffic, and policy reference

Document What you'll find
Load Balancing Current balancing strategies, selection behavior, and config examples
HTTP/3 HTTP/3 behavior and protocol-specific operational notes
QUIC QUIC transport behavior, constraints, and terminology
Security Model Current trust boundaries, admin-plane assumptions, and missing security layers
Terminology Canonical definitions for listener, upstream, backend, route, drain, and related terms

Developer — contribute safely against the current architecture

Document What you'll find
Contributing Guide Dev setup, build commands, test matrix, PR conventions
Development Overview Contributor-oriented guide to working in the repo
Testing Strategy Contract, regression, and parity test expectations
Benchmarking Benchmark crate, micro/macro suites, and regression-gate workflow
Adding Features Expectations for new features against the current architecture

Reference — schema, maturity, roadmap, and release state

Document What you'll find
Reference Overview Main entry point for exact behavior, product limits, and authoritative reference pages
Configuration Reference Authoritative schema reference for every configuration block
Feature Matrix Strict feature-by-feature inventory of what is done, partial, and missing
Roadmap Planned features, GA exit criteria, known limitations
Changelog Version history with added, fixed, and changed entries

Status

Field Value
Version v0.5.1-beta
Maturity Beta
License GPLv3

Beta means core proxying, routing, load balancing, and health-check features are implemented and actively validated, but the project remains pre-GA — extended soak validation and broader failure-mode hardening are still in progress.

Controlled production rollout is supported. See release-maturity.md for operator expectations, environment guidance, and GA exit criteria.

Quick reference

If you are in a hurry:

For the canonical examples and exact commands:

External standards

Overview