whclient

whclient

-- import "github.com/taskcluster/webhooktunnel/whclient"

Package whclient wraps a wsmux client session in a net.Listener interface. It attempts to reconnect to the proxy in case of a connection failure. It can be configured by setting the appropriate parameters in the Config object passed to whclient.New().

Usage

var (
	// ErrRetryTimedOut is returned when Reconnect() time exceeds MaxElapsedTime.
	ErrRetryTimedOut = clientError{timeout: true, errString: "retry timed out"}

	// ErrBadToken is returned when a usable token can not be generated by the authorizer.
	ErrBadToken = clientError{errString: "bad auth token"}

	// ErrRetryFailed is returned when retry attempts fail.
	ErrRetryFailed = clientError{errString: "retry failed"}

	// ErrClientReconnecting is returned when the connection is reconnecting.
	// This is a temporary error.
	ErrClientReconnecting = clientError{errString: "client reconnecting", reconnect: true}

	// ErrClientClosed is returned from an Accept call when the client is closed.
	ErrClientClosed = clientError{errString: "client closed"}

	// ErrAuthorizerNotProvided is returned from New when an Authorizer is not provided.
	ErrAuthorizerNotProvided = clientError{errString: "authorizer function was not provided to client"}
)

func New

func New(config Config) (net.Listener, error)

New returns a new net.Listener instance using the provided Config object.

type Authorizer

type Authorizer func(id string) (string, error)

Authorizer is a function which accepts a string id and returns a signed JWT (JSON Web Token). If an error occurs, the return values must be ("", ErrorGenerated).

type Config

type Config struct {
	// ID is the worker-id of the client. This field must match the "tid" claim of the
	// JWT.
	ID string

	// ProxyAddr is the websocket address of the proxy to which the client should connect.
	ProxyAddr string

	// Logger is an optional field. This logger is passed to the session created by
	// the GetListener method. This defaults to `&util.NilLogger{}`.
	Logger util.Logger

	Authorize Authorizer

	// Retry contains the retry parameters to use in case of reconnects.
	// The default values are specified in RetryConfig.
	Retry RetryConfig
}

Config is used for creating a new client.

type RetryConfig

type RetryConfig struct {
	// InitialDelay is the delay after which the first reconnect
	// attempt takes place.
	// Default = 500 * time.Millisecond
	InitialDelay time.Duration

	// MaxDelay is the maximum possible delay between two consecutive
	// reconnect attempts.
	// Default = 60 * time.Second
	MaxDelay time.Duration

	// MaxElapsedTime is the time after which reconnect will time out
	// Default = 3 * time.Minute
	MaxElapsedTime time.Duration

	// Multplier is the rate at which the delay will increase
	//Default = 1.5
	Multiplier float64

	// RandomizationFactor is the extent to which the delay values will be randomized
	// Default = 0.5
	RandomizationFactor float64
}

RetryConfig contains exponential backoff parameters for retrying connections