How perbu/hazelnut works
Main Components
• CLI / Entrypoint (main.go)
• Configuration Loader (config package)
• Service Orchestrator (service/server.go)
• Frontend HTTP Server (frontend package)
• Cache Layer (cache package with lrucache and mapcache implementations)
• Backend Reverse-Proxy (backend package)
• Metrics Exporter (metrics package)
• External Systems
– Upstream HTTP/HTTPS target
– Prometheus scraper
Relationships & Data Flow
– Startup:
• main.go reads config via config.Config
• main calls service.New(ctx, cfg, logger) → returns a Server object
• Server.Run starts two listeners:
– Frontend listener (default port 8080)
– Metrics listener (default port 9091)
– Request handling chain (decorate pattern):
1. Client → Frontend HTTP listener (frontend package)
2. Metrics middleware (metrics package) increments request counter
3. Cache middleware (cache package) checks for a hit:
• Hit → return cached response + increment cache_hits metric
• Miss → pass request to backend
4. Backend reverse proxy (backend package) forwards request to target (config.BackendConfig.Target, Scheme)
5. Backend response → cache.Store (on CacheConfig.MaxObj/MaxCost) → return to client
6. Metrics middleware logs misses, errors
– Metrics endpoint: Prometheus scrapes /metrics on metrics port
Architectural Patterns & Principles
• Layered / modular design: clear separation of config, service orchestration, HTTP I/O, caching, backend proxy, metrics.
• Decorator / middleware chain for caching and metrics around the core reverse-proxy handler.
• Interface abstraction for cache.Backend (allows lrucache vs mapcache).
• Single binary with embedded library mode (examples/embed shows embedding via server.New).
Technologies & Libraries
• Go’s net/http for server & client
• Ristretto-based high-performance cache (cache/lrucache)
• YAML configuration (config/config.go)
• Prometheus Go client (metrics/metrics.go)
• Go modules (go.mod)
Detail Checklist
– main.go / CLI → config loader → service.New
– service.Run → starts frontend + metrics servers
– Frontend handler → metrics.Middleware → cache.Middleware → backend.Proxy
– cache package: interface, lrucache & mapcache implementations
– backend package: HTTP client & reverse-proxy logic
– metrics package: Prometheus counters/gauges exposed on /metrics
– External: Upstream target (configurable), Prometheus scrape