httppool

Documentation

Overview

Package httppool provides a simple, configurable worker pool for dispatching HTTP transactions to servers.

Index

• Constants
• Variables
• func BreakerClient(timeout time.Duration, threshold int64, logger log.Logger, ...) *circuit.HTTPClient
• type Client
  • func (client *Client) Start() (dispatcher DispatchCloser)
• type Consumer
• type DispatchCloser
• type Dispatcher
• type Event
• type EventType
• type Listener
• type RequestFilter
• type Task
  • func FilteredTask(filter RequestFilter, delegate Task) Task
  • func PerishableTask(expiry time.Time, delegate Task) Task
  • func RequestTask(request *http.Request, consumer Consumer) Task

Constants

const (
	DefaultWorkers   = 10
	DefaultQueueSize = 100
)

Variables

var (
	ErrorTaskExpired  = errors.New("Task has expired")
	ErrorTaskFiltered = errors.New("Task has been rejected by a RequestFilter")
)

var (
	ErrorClosed = errors.New("Dispatcher has been closed")
)

Functions

func BreakerClient

func BreakerClient(timeout time.Duration, threshold int64, logger log.Logger, delegate *http.Client) *circuit.HTTPClient

Types

type Client

type Client struct {
	// Name is a human-readable label for dispatchers created via this Client instance.
	// This name shows up in logs to distinguish one pool from another.  If this string
	// has length 0, a default name using the address of this Client instance is generated.
	Name string

	// Handler is any type that has a method with the signature Do(*http.Request) (*http.Response, error)
	// If not supplied, the http.DefaultClient is used.
	Handler transactionHandler

	// Listeners is the slice of Listener instances that will be notified of task events.
	// Each Dispatcher will use a distinct copy created with Start() is called.
	Listeners []Listener

	// Logger is the logging strategy used by this client.  If not supplied, logging is discarded.
	Logger log.Logger

	// QueueSize specifies that maximum number of requests that can be queued.
	// If this value is zero or negative, DefaultQueueSize is used.
	QueueSize int

	// Workers is the number of pooled goroutines that handle tasks.
	// If this value is less than one (1), DefaultWorkers is used.
	Workers int

	// Period is the interval between requests on EACH worker.  If this
	// value is zero or negative, the workers will not be rate-limited.
	Period time.Duration
}

Client is factory for asynchronous, pooled HTTP transaction dispatchers. An optional Period may be specified which limits the rate at which each worker goroutine sends requests.

func (*Client) Start

func (client *Client) Start() (dispatcher DispatchCloser)

Start starts the pool of goroutines and returns a DispatchCloser which can be used to send tasks and shut down the pool.

type Consumer

type Consumer func(*http.Response, *http.Request)

Consumer is a function type which is invoked with the results of an HTTP transaction. Normally, this function will be invoked asynchronously.

Dispatchers will never invoke this function if either parameter is nil.

type DispatchCloser

type DispatchCloser interface {
	Dispatcher
	io.Closer
}

DispatchCloser is a Dispatcher that can be closed. The Close() method implemented by any DispatchCloser must be idempotent. It should not panic when called multiple times.

type Dispatcher

type Dispatcher interface {
	// Send uses the task to create a request and sends that along to a server.
	// This method may be asynchronous or synchronous, depending on the underlying implementation.
	// The caller will block until the Dispatcher is able to handle the task.
	Send(Task) error

	// Offer is similar to Send, except that the Dispatcher can reject the task.  A false
	// return value indicates that the task was not executed, regardless of the error return value.
	// Typically, Offer will reject tasks because an underlying queue or buffer is full.
	// This method will never block.
	Offer(Task) (bool, error)
}

Dispatcher represents anything that can receive and process tasks.

type Event

type Event interface {
	// Type is the type of this event
	Type() EventType

	// Error stores any error that occurred as part of this event
	Err() error
}

Event represents an interesting occurrence in an httppool

type EventType

type EventType int

const (
	// EventTypeQueue indicates that a task has been successfully queued
	EventTypeQueue EventType = iota

	// EventTypeReject indicates that a task was not queued, either because the
	// queue was full or because the pool was closed.
	EventTypeReject

	// EventTypeStart is sent when a task has been dequeued and is about to be processed
	EventTypeStart

	// EventTypeFinish indicates that a task has finished
	EventTypeFinish
)

type Listener

type Listener interface {
	// On is a callback method for events
	On(Event)
}

Listener is a consumer of Events

type RequestFilter

type RequestFilter interface {
	Accept(*http.Request) bool
}

RequestFilter provides a way to accept or reject requests. This is useful to determine if a task should proceed based on current conditions of the application, e.g. queues backed up, chatty clients, etc.

type Task

type Task func() (*http.Request, Consumer, error)

Task is a constructor function type that creates http.Request objects A task is used, rather than a request directly, to allow lazy instantiation of requests at the time the request is to be sent.

Each Task may optionally return a Consumer. If non-nil, this function is invoked with the request/response pair. The Dispatcher will always cleanup the http.Response, regardless of whether the Consumer does anything with the response body.

func FilteredTask

func FilteredTask(filter RequestFilter, delegate Task) Task

FilteredTask is a constructor that produces a decorator Task that checks if a given delegate's request should be allowed to proceed. If the delegate panics or returns an error, the returned Task will do the same.

func PerishableTask

func PerishableTask(expiry time.Time, delegate Task) Task

PerishableTask is a constructor that returns a decorator Task that returns ErrorTaskExpired if the given expiry has been reached.

func RequestTask

func RequestTask(request *http.Request, consumer Consumer) Task

RequestTask allows an already-formed http.Request to be used as a Task.