How spectolabs/hoverfly works
Project Type and Purpose
• This is an open-source API simulation tool (Hoverfly) written in Go. It comprises two primary deliverables:
a. A long-running “core” service that acts as an HTTP proxy and exposes a REST-style admin API.
b. A CLI client (hoverctl) that invokes the core’s admin API to configure, control and query simulations.
• Use cases include capturing live HTTP traffic, simulating API endpoints with delays/matchers/middleware, and exporting/importing simulation definitions.
High-Level File Structure & Architectural Clues
• Directories:
• core/ – the headless proxy + REST API server
• hoverctl/ – the CLI front-end
• docs/, examples/, functional-tests/ – documentation, usage examples and end-to-end tests
• core/ is organized by feature layers: HTTP handlers (core/handlers), business logic (core/modes, core/matching, core/cache, core/templating, core/postserveactions), persistence (core/cache, core/journal), authentication (core/authentication), metrics and middleware.
• hoverctl/ contains command definitions (cobra-style), client wrappers (hoverctl/wrapper) that talk to the core via HTTP, and config management.
Main Components
A. CLI Client (hoverctl)
• hoverctl commands → HTTP calls → Core Admin API
• Configuration loader → selects target hoverfly instance
B. Core Service
1. HTTP Layer
• Proxy Listener (captures/forwards client traffic)
• Admin API Listener (CRUD on simulations, modes, cache, journal, metrics)
2. Business Logic
• Modes Engine (capture/simulate/diff/modify/spy/synthesize)
• Matching Engine (match incoming requests to simulation pairs)
• Delay Generator (static, log-normal, random)
• Templating & DataSources
• Post-Serve Actions (callbacks to arbitrary HTTP endpoints)
• Middleware Module (local binaries or remote services)
3. Persistence & State
• In-memory & BoltDB caches
• Journal store & indexing
• Simulation definitions (in memory, exportable as JSON)
4. Cross-cutting Services
• Authentication & Authorization (JWT or custom storage backend)
• CORS handling
• Metrics collection & exposition (Prometheus style)
• TLS/Certificates management
C. External Integrations
• Upstream real APIs (in capture mode)
• Middleware services (local scripts, remote HTTP services)
• Post-serve webhook endpoints
Component Interactions & Data Flows
• In capture mode: Proxy → Upstream API → Response → Save to Journal/Cache
• In simulate mode: Proxy → Matching Engine → Cached Response → Delay & Templating → Response
• Middleware & Post-serve callbacks may intercept/modify both directions.
• Core persists journal events and cache items; these backends (memory or BoltDB) feed the Matching and Journal Index modules.
Architectural Patterns & Design Principles
• Layered (Transport → Handlers → Business Logic → Persistence)
• Hexagonal/Ports-and-Adapters for Middleware & DataSources (core/interfaces + core/templating)
• Plugin-style extensibility for middleware and post-serve actions
• Separation of concerns between capture vs simulate vs modify vs diff modes
• Single binary deployable service, stateless except for optional BoltDB files
Additional Deployment & Extension Points
• How examples or functional-tests spin up the core service and execute HTTP calls.
• Extensibility hooks: storage backends, middleware adapters, templating datasources.