hedgehog

README

Hedgehog 🦔: http hedged transport in go

go get -u github.com/1pkg/hedgehog

Details

Hedgehog provides hedged http transport decorator to reduce tail latency at scale. Hedged transport makes hedged http calls for matching http resource up to calls+1 times, where initial http call starts right away and then all hedged calls start together after delay calculated by resource. Hedged transport processes and returns first successful http response all other requests in flight are canceled, in case all hedged response failed it simply returns first occurred error. If no matching resources were found - hedged transport simply calls underlying transport.

hedgehog.NewHTTPClient(
    http.DefaultClient,
    // will initiate 2+1 hedged http request.
    2,
    // for GET /profile/[0-9] initiate hedged request only after flat 1ms.
    NewResourceStatic(http.MethodGet, regexp.MustCompile(`profile/[0-9]`), ms_1, http.StatusOK),
    // for POST /profile initiate hedged request starting with flat 5ms, but after 40/4 calls use aggregated average latency.
    NewResourceAverage(http.MethodPost, regexp.MustCompile(`profile`), ms_5, 40, http.StatusOK),
    // for Delete /profile initiate hedged request starting with flat 5ms, but after 50/2 calls use aggregated p30 latency.
    NewResourcePercentiles(http.MethodDelete, regexp.MustCompile(`profile`), ms_5, 0.3, 50, http.StatusOK),
).Get("http://example.com/profile/5")

There are multiple different http hedged resource types to control hedging behavior.

Resource	Definition	Description
static	func NewResourceStatic(method string, url *regexp.Regexp, delay time.Duration, allowedCodes ...int) Resource	Returned resource always waits for static specified delay. The resource matches each request against both provided http method and full url regexp. The resource checks if response result http code is included in provided allowed codes, if it is not it returnes ErrResourceUnexpectedResponseCode.
average	func NewResourceAverage(method string, url *regexp.Regexp, delay time.Duration, capacity int, allowedCodes ...int) Resource	Returned resource dynamically adjusts wait delay based on received successful responses average delays. The resource is starting to use dynamically adjusted wait delay only after capacity/4 calls. The resource matches each request against both provided http method and full url regexp. The resource checks if response result http code is included in provided allowed codes, if it is not it returnes ErrResourceUnexpectedResponseCode.
percentiles	func NewResourcePercentiles(method string, url *regexp.Regexp, delay time.Duration, percentile float64, capacity int, allowedCodes ...int) Resource	Returned resource dynamically adjusts wait delay based on received successful responses delays percentiles. The resource is starting to use dynamically adjusted wait delay only after capacity/2 calls, if more than provided capacity calls were received, first half of delay percentiles buffer will be flushed. Returned resource matches each request against both provided http method and full url regexp. Returned resource checks if response result http code is included in provided allowed codes, if it is not it returnes ErrResourceUnexpectedResponseCode.

Licence

Hedgehog is licensed under the MIT License.
See LICENSE for the full license text.

Documentation

Index

• func NewHTTPClient(client *http.Client, calls uint64, resources ...Resource) *http.Client
• func NewRoundTripper(internal http.RoundTripper, calls uint64, resources ...Resource) http.RoundTripper
• type ErrResourceUnexpectedResponseCode
  • func (err ErrResourceUnexpectedResponseCode) Error() string
• type Resource
  • func NewResourceAverage(method string, url *regexp.Regexp, delay time.Duration, capacity int, ...) Resource
  • func NewResourcePercentiles(method string, url *regexp.Regexp, delay time.Duration, percentile float64, ...) Resource
  • func NewResourceStatic(method string, url *regexp.Regexp, delay time.Duration, allowedCodes ...int) Resource

Functions

func NewHTTPClient

func NewHTTPClient(client *http.Client, calls uint64, resources ...Resource) *http.Client

NewHTTPClient wraps provided http client with hedged transport. If nil client is provided default client will be used, if nil transport is provided default transport will be used.

func NewRoundTripper

func NewRoundTripper(internal http.RoundTripper, calls uint64, resources ...Resource) http.RoundTripper

NewRoundTripper returns new http hedged transport with provided resources. Returned transport makes hedged http calls in case of resource matching http request up to calls+1 times, original http call starts right away and then all hedged calls start together after delay specified by resource. Returned transport processes and returns first successful http response all other requests in flight are canceled, in case all hedged response failed it simply returns first occurred error. If no matching resources were found - the transport simply calls underlying transport.

Types

type ErrResourceUnexpectedResponseCode

type ErrResourceUnexpectedResponseCode struct {
	StatusCode int
}

ErrResourceUnexpectedResponseCode defines resource response check error that is returned on non matching response code.

func (ErrResourceUnexpectedResponseCode) Error

func (err ErrResourceUnexpectedResponseCode) Error() string

type Resource

type Resource interface {
	After() <-chan time.Time
	Match(*http.Request) bool
	Check(*http.Response) error
	Hook(*http.Request) func(*http.Response)
}

Resource defines abstract http resource that is capable of: - matching http request applicability - checking http request validity - and returning delay which should be accounted before executing this resource request

func NewResourceAverage

func NewResourceAverage(method string, url *regexp.Regexp, delay time.Duration, capacity int, allowedCodes ...int) Resource

NewResourceAverage returns new resource instance that dynamically adjusts wait delay based on received successful responses average delays. Returned resource is starting to use dynamically adjusted wait delay only after capacity/4 calls. Returned resource matches each request against both provided http method and full url regexp. Returned resource checks if response result http code is included in provided allowed codes, if it is not it returnes `ErrResourceUnexpectedResponseCode`.

func NewResourcePercentiles

func NewResourcePercentiles(method string, url *regexp.Regexp, delay time.Duration, percentile float64, capacity int, allowedCodes ...int) Resource

NewResourcePercentiles returns new resource instance that dynamically adjusts wait delay based on received successful responses delays percentiles. Returned resource is starting to use dynamically adjusted wait delay only after capacity/2 calls, if more than provided capacity calls were received, first half of delay percentiles buffer will be flushed. Returned resource matches each request against both provided http method and full url regexp. Returned resource checks if response result http code is included in provided allowed codes, if it is not it returnes `ErrResourceUnexpectedResponseCode`.

func NewResourceStatic

func NewResourceStatic(method string, url *regexp.Regexp, delay time.Duration, allowedCodes ...int) Resource

NewResourceStatic returns new resource instance that always waits for static specified delay. Returned resource matches each request against both provided http method and full url regexp. Returned resource checks if response result http code is included in provided allowed codes, if it is not it returnes `ErrResourceUnexpectedResponseCode`.