hoverfly

README

Dependencies without the sting

Hoverfly is a light-weight open source tool for creating simulations of external services for use in development and testing. This technique is sometimes referred to as service virtualization.

Hoverfly was designed to provide you with the means to create your own "dependency sandbox": a simulated development and test environment that you control.

Documentation

The Hoverfly documentation is available here.

For convenience:

Getting started

• Use cases
• "Modes" and middleware
• Installation and setup

Usage

• Capturing traffic
• Simulating services
• Exporting and importing
• Using middleware
• Creating synthetic services
• Modifying traffic
• Filtering destination URLs and hosts
• Using the metadata API
• Admin UI
• HTTPS & certificate management
• Authentication

Reference

• API
• Flags and environment variables

Further reading

Articles and blog posts with step-by-step Hoverfly tutorials:

• Creating fast versions of slow dependencies
• Modifying traffic on the fly
• Mocking APIs for development and testing
• Virtualizing the Meetup API
• Using Hoverfly to build Spring Boot microservices alongside a Java monolith
• Easy API simulation with the Hoverfly JUnit rule

Contributing

Contributions are welcome!

To submit a pull request you should fork the Hoverfly repository, and make your change on a feature branch of your fork. Then generate a pull request from your branch against master of the Hoverfly repository. Include in your pull request details of your change (why and how, as well as the testing you have performed). To read more about forking model, check out this link: forking workflow.

Hoverfly is a new project, we will soon provide detailed roadmap.

License

Apache License version 2.0 See LICENSE for details.

(c) SpectoLabs 2016.

Documentation

Index

• Constants
• Variables
• func ExecuteMiddleware(middlewares string, payload models.Payload) (models.Payload, error)
• func GetRandomName(n int) []byte
• func Pipeline(cmds ...*exec.Cmd) (pipeLineOutput, collectedStandardError []byte, pipeLineError error)
• func SynthesizeResponse(req *http.Request, middleware string) (*http.Response, error)
• type ActionType
• type ActionTypeHooks
  • func (hooks ActionTypeHooks) Add(hook Hook)
  • func (hooks ActionTypeHooks) Fire(ac ActionType, entry *Entry) error
• type Client
• type Configuration
  • func InitSettings() *Configuration
  • func (c *Configuration) GetMode() (mode string)
  • func (c *Configuration) SetMode(mode string)
• type Constructor
  • func NewConstructor(req *http.Request, payload models.Payload) *Constructor
  • func (c *Constructor) ApplyMiddleware(middleware string) error
  • func (c *Constructor) ReconstructRequest() (*http.Request, error)
  • func (c *Constructor) ReconstructResponse() *http.Response
• type Entry
• type Hook
• type Hoverfly
  • func GetNewHoverfly(cfg *Configuration, requestCache, metadataCache cache.Cache, ...) *Hoverfly
  • func (d *Hoverfly) AddHook(hook Hook)
  • func (d *Hoverfly) AllMetadataHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) AllRecordsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) CurrentStateHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) DeleteAllRecordsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) DeleteMetadataHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) Import(uri string) error
  • func (d *Hoverfly) ImportFromDisk(path string) error
  • func (d *Hoverfly) ImportFromURL(url string) error
  • func (d *Hoverfly) ImportPayloads(payloads []models.PayloadView) error
  • func (d *Hoverfly) ImportRecordsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) ManualAddHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) RecordsCount(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) SetMetadataHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) StartAdminInterface()
  • func (d *Hoverfly) StartProxy() error
  • func (d *Hoverfly) StateHandler(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) StatsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
  • func (d *Hoverfly) StatsWSHandler(w http.ResponseWriter, r *http.Request)
  • func (d *Hoverfly) StopProxy()
  • func (d *Hoverfly) UpdateDestination(destination string) (err error)
  • func (d *Hoverfly) UpdateProxy()
• type StoppableListener
  • func NewStoppableListener(l net.Listener) (*StoppableListener, error)
  • func (sl *StoppableListener) Accept() (net.Conn, error)
  • func (sl *StoppableListener) Stop()

Constants

const (
	HoverflyAuthEnabledEV     = "HoverflyAuthEnabled"
	HoverflySecretEV          = "HoverflySecret"
	HoverflyTokenExpirationEV = "HoverflyTokenExpiration"

	HoverflyAdminPortEV = "AdminPort"
	HoverflyProxyPortEV = "ProxyPort"

	HoverflyDBEV         = "HoverflyDB"
	HoverflyMiddlewareEV = "HoverflyMiddleware"

	HoverflyTLSVerification = "HoverflyTlsVerification"

	HoverflyAdminUsernameEV = "HoverflyAdmin"
	HoverflyAdminPasswordEV = "HoverflyAdminPass"

	HoverflyImportRecordsEV = "HoverflyImport"
)

Environment variables

const ActionTypeConfigurationChanged = "configurationChanged"

ActionTypeConfigurationChanged - default action name for identifying configuration changes

const ActionTypeRequestCaptured = "requestCaptured"

ActionTypeRequestCaptured - default action type name for identifying

const ActionTypeWipeDB = "wipeDatabase"

ActionTypeWipeDB - default action type for wiping database

const CaptureMode = "capture"

CaptureMode - requests are captured and stored in cache

const DefaultAdminPort = "8888"

DefaultAdminPort - default admin interface port

const DefaultDatabasePath = "requests.db"

DefaultDatabasePath - default database name that will be created or used by Hoverfly

const DefaultJWTExpirationDelta = 1 * 24 * 60 * 60

DefaultJWTExpirationDelta - default token expiration if environment variable is no provided

const DefaultPort = "8500"

DefaultPort - default proxy port

const ModifyMode = "modify"

ModifyMode - middleware is applied to outgoing and incoming traffic

const SimulateMode = "simulate"

SimulateMode - default mode when Hoverfly looks for captured requests to respond

const SynthesizeMode = "synthesize"

SynthesizeMode - all requests are sent to middleware to create response

const URL string = `` /* 321-byte string literal not displayed */

URL is regexp to match http urls

Variables

var TestDB *bolt.DB

TestDB - holds connection to database during tests

Functions

func ExecuteMiddleware

func ExecuteMiddleware(middlewares string, payload models.Payload) (models.Payload, error)

ExecuteMiddleware - takes command (middleware string) and payload, which is passed to middleware

func GetRandomName

func GetRandomName(n int) []byte

GetRandomName - provides random name for buckets. Each test case gets it's own bucket

func Pipeline

func Pipeline(cmds ...*exec.Cmd) (pipeLineOutput, collectedStandardError []byte, pipeLineError error)

Pipeline - to provide input to the pipeline, assign an io.Reader to the first's Stdin.

func SynthesizeResponse

func SynthesizeResponse(req *http.Request, middleware string) (*http.Response, error)

SynthesizeResponse calls middleware to populate response data, nothing gets pass proxy

Types

type ActionType

type ActionType string

ActionType - action type can be things such as "RequestCaptured", "GotResponse" - anything

type ActionTypeHooks

type ActionTypeHooks map[ActionType][]Hook

ActionTypeHooks type for storing the hooks

func (ActionTypeHooks) Add

func (hooks ActionTypeHooks) Add(hook Hook)

Add a hook

func (ActionTypeHooks) Fire

func (hooks ActionTypeHooks) Fire(ac ActionType, entry *Entry) error

Fire all the hooks for the passed ActionType

type Client

type Client struct {
	HTTPClient *http.Client
}

Client structure to be injected into functions to perform HTTP calls

type Configuration

type Configuration struct {
	AdminPort    string
	ProxyPort    string
	Mode         string
	Destination  string
	Middleware   string
	DatabasePath string

	TLSVerification bool

	Verbose     bool
	Development bool

	SecretKey          []byte
	JWTExpirationDelta int
	AuthEnabled        bool

	ProxyControlWG sync.WaitGroup
	// contains filtered or unexported fields
}

Configuration - initial structure of configuration

func InitSettings

func InitSettings() *Configuration

InitSettings gets and returns initial configuration from env variables or sets defaults

func (*Configuration) GetMode

func (c *Configuration) GetMode() (mode string)

GetMode - provides safe way to get current mode

func (*Configuration) SetMode

func (c *Configuration) SetMode(mode string)

SetMode - provides safe way to set new mode

type Constructor

type Constructor struct {
	// contains filtered or unexported fields
}

Constructor - holds information about original request (which is needed to create response and also holds payload

func NewConstructor

func NewConstructor(req *http.Request, payload models.Payload) *Constructor

NewConstructor - returns constructor instance

func (*Constructor) ApplyMiddleware

func (c *Constructor) ApplyMiddleware(middleware string) error

ApplyMiddleware - activates given middleware, middleware should be passed as string to executable, can be full path.

func (*Constructor) ReconstructRequest

func (c *Constructor) ReconstructRequest() (*http.Request, error)

ReconstructRequest replaces original request with details provided in Constructor Payload.Request

func (*Constructor) ReconstructResponse

func (c *Constructor) ReconstructResponse() *http.Response

ReconstructResponse changes original response with details provided in Constructor Payload.Response

type Entry

type Entry struct {
	// Contains encoded data
	Data []byte

	// Time at which the action entry was fired
	Time time.Time

	ActionType ActionType

	// Message, can carry additional information
	Message string
}

Entry - holds information about action, based on action type - other clients will be able to decode the data field.

type Hook

type Hook interface {
	ActionTypes() []ActionType
	Fire(*Entry) error
}

Hook - an interface to add dynamic hooks to extend functionality

type Hoverfly

type Hoverfly struct {
	RequestCache   cache.Cache
	MetadataCache  cache.Cache
	Authentication authBackend.Authentication
	HTTP           *http.Client
	Cfg            *Configuration
	Counter        *metrics.CounterByMode
	Hooks          ActionTypeHooks

	Proxy *goproxy.ProxyHttpServer
	SL    *StoppableListener
	// contains filtered or unexported fields
}

Hoverfly provides access to hoverfly - updating/starting/stopping proxy, http client and configuration, cache access

func GetNewHoverfly

func GetNewHoverfly(cfg *Configuration, requestCache, metadataCache cache.Cache, authentication backends.Authentication) *Hoverfly

GetNewHoverfly returns a configured ProxyHttpServer and DBClient

func (*Hoverfly) AddHook

func (d *Hoverfly) AddHook(hook Hook)

AddHook - adds a hook to DBClient

func (*Hoverfly) AllMetadataHandler

func (d *Hoverfly) AllMetadataHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

AllMetadataHandler returns JSON content type http response

func (*Hoverfly) AllRecordsHandler

func (d *Hoverfly) AllRecordsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

AllRecordsHandler returns JSON content type http response

func (*Hoverfly) CurrentStateHandler

func (d *Hoverfly) CurrentStateHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

CurrentStateHandler returns current state

func (*Hoverfly) DeleteAllRecordsHandler

func (d *Hoverfly) DeleteAllRecordsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

DeleteAllRecordsHandler - deletes all captured requests

func (*Hoverfly) DeleteMetadataHandler

func (d *Hoverfly) DeleteMetadataHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

DeleteMetadataHandler - deletes all metadata

func (*Hoverfly) Import

func (d *Hoverfly) Import(uri string) error

Import is a function that based on input decides whether it is a local resource or whether it should fetch it from remote server. It then imports given payload into the database or returns an error

func (*Hoverfly) ImportFromDisk

func (d *Hoverfly) ImportFromDisk(path string) error

ImportFromDisk - takes one string value and tries to open a file, then parse it into recordedRequests structure (which is default format in which Hoverfly exports captured requests) and imports those requests into the database

func (*Hoverfly) ImportFromURL

func (d *Hoverfly) ImportFromURL(url string) error

ImportFromURL - takes one string value and tries connect to a remote server, then parse response body into recordedRequests structure (which is default format in which Hoverfly exports captured requests) and imports those requests into the database

func (*Hoverfly) ImportPayloads

func (d *Hoverfly) ImportPayloads(payloads []models.PayloadView) error

ImportPayloads - a function to save given payloads into the database.

func (*Hoverfly) ImportRecordsHandler

func (d *Hoverfly) ImportRecordsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

ImportRecordsHandler - accepts JSON payload and saves it to cache

func (*Hoverfly) ManualAddHandler

func (d *Hoverfly) ManualAddHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

ManualAddHandler - manually add new request/responses, using a form

func (*Hoverfly) RecordsCount

func (d *Hoverfly) RecordsCount(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

RecordsCount returns number of captured requests as a JSON payload

func (*Hoverfly) SetMetadataHandler

func (d *Hoverfly) SetMetadataHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

SetMetadataHandler - sets new metadata

func (*Hoverfly) StartAdminInterface

func (d *Hoverfly) StartAdminInterface()

StartAdminInterface - starts admin interface web server

func (*Hoverfly) StartProxy

func (d *Hoverfly) StartProxy() error

StartProxy - starts proxy with current configuration, this method is non blocking.

func (*Hoverfly) StateHandler

func (d *Hoverfly) StateHandler(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)

StateHandler handles current proxy state

func (*Hoverfly) StatsHandler

func (d *Hoverfly) StatsHandler(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)

StatsHandler - returns current stats about Hoverfly (request counts, record count)

func (*Hoverfly) StatsWSHandler

func (d *Hoverfly) StatsWSHandler(w http.ResponseWriter, r *http.Request)

StatsWSHandler - returns current stats about Hoverfly (request counts, record count) through the websocket

func (*Hoverfly) StopProxy

func (d *Hoverfly) StopProxy()

StopProxy - stops proxy

func (*Hoverfly) UpdateDestination

func (d *Hoverfly) UpdateDestination(destination string) (err error)

UpdateDestination - updates proxy with new destination regexp

func (*Hoverfly) UpdateProxy

func (d *Hoverfly) UpdateProxy()

UpdateProxy - applies hooks

type StoppableListener

type StoppableListener struct {
	*net.TCPListener
	// contains filtered or unexported fields
}

StoppableListener - wrapper for tcp listener that can stop

func NewStoppableListener

func NewStoppableListener(l net.Listener) (*StoppableListener, error)

NewStoppableListener returns new StoppableListener listener

func (*StoppableListener) Accept

func (sl *StoppableListener) Accept() (net.Conn, error)

Accept - TCPListener waits for the next call, implements default interface method

func (*StoppableListener) Stop

func (sl *StoppableListener) Stop()

Stop - stops listener