Tavern

Tavern is a high-performance HTTP caching proxy server implemented in Go. It leverages a modern service framework to deliver a flexible architecture, strong extensibility, and excellent performance.

Other languages: 简体中文

✨ Features

• Core Caching Capabilities:
  • Prefetch
  • Cache Push (URL/DIR Push)
    • URL mark expired
    • URL cache file delete
    • DIR mark expired
    • DIR cache file delete
  • Fuzzy refresh (Fuzzing fetch)
  • Auto refresh
  • Cache validation
  • Hot migration
  • Warm/cold split
  • Upstream collapse request (request coalescing)
  • Image compression adaptation (WebP support)
  • Vary-based versioned cache (Vary cache)
  • Headers rewrite
  • Multiple Range requests support
  • CacheFile verification (CRC checksum / EdgeMode)
    • You may need CRC-Center Service.
• Modern Architecture:
  • Built on the Kratos framework for high extensibility and module reuse
  • Plugin System: Extend core business logic via plugins
  • Storage Layer: Decoupled storage backend with memory, disk, and custom implementations
• Reliability & Operations:
  • Graceful Upgrade: Zero-downtime config reload and binary upgrade
  • Failure Recovery: Built-in panic recovery and error handling
  • Observability: Native Prometheus metrics and PProf profiling
• Traffic Control:
  • Header rewrite (Rewrite)
  • Upstream load balancing (via custom Selector)

🚀 Quick Start

Requirements

• Go 1.24+
• Linux/macOS (Graceful restart may be limited on Windows)

1. Fetch & Configure

Clone the repository and prepare the configuration file:

git clone https://github.com/omalloc/tavern.git
cd tavern

# Initialize with example configuration
cp config.example.yaml config.yaml

2. Run the Service

Development mode:

# Loads config.yaml from the current directory by default
go run main.go

Build and run:

make build
./bin/tavern -c config.yaml

3. Debugging & Monitoring

Once started, you can monitor and debug using the following (ports depend on config.yaml):

• Metrics: Access /metrics for Prometheus metrics (default prefix tr_tavern_)
• PProf: When debug mode is enabled, visit /debug/pprof/ for profiling

🧩 Project Structure

• api/: Protocol and interface definitions
• conf/: Configuration definitions and parsing
• plugin/: Plugin interfaces and implementations
• proxy/: Core proxy and forwarding logic
• server/: HTTP server implementation and middleware
• storage/: Storage engine abstractions and implementations

📝 License

MIT License

🙏 Acknowledgments

This project integrates and is inspired by the following excellent open-source projects. Many thanks:

• Kratos: A powerful microservice framework that inspired Tavern's modern architecture.
• Pebble: A high-performance key-value store by CockroachDB, powering efficient persistent caching.
• tableflip: Cloudflare's graceful upgrade solution enabling zero-downtime restarts.
• Prometheus Go Client: Strong observability support for metrics.