xhttpserver

Documentation

Index

• Variables
• func AddressKey() interface{}
• func NewListener(ctx context.Context, o Options, lcfg net.ListenConfig) (net.Listener, error)
• func NewServerChain(o Options, l log.Logger, pb ...xloghttp.ParameterBuilder) alice.Chain
• func NewServerLogger(o Options, base log.Logger, extra ...interface{}) log.Logger
• func NewTlsConfig(t *Tls) (*tls.Config, error)
• func OnStart(o Options, s Interface, logger log.Logger, onExit func()) func(context.Context) error
• func OnStop(s Interface, logger log.Logger) func(context.Context) error
• func ServerKey() interface{}
• func Unmarshal(configKey string, c ...alice.Constructor) func(in ServerIn) (*mux.Router, error)
• func UseTrackingWriter(next http.Handler) http.Handler
• type ChainFactory
• type ChainFactoryFunc
  • func (cff ChainFactoryFunc) New(o Options) (alice.Chain, error)
• type Interface
  • func New(o Options, l log.Logger, h http.Handler) Interface
• type MissingValueError
  • func (mve MissingValueError) Error() string
  • func (mve MissingValueError) StatusCode() int
• type MissingVariableError
  • func (mve MissingVariableError) Error() string
  • func (mve MissingVariableError) StatusCode() int
• type Options
• type ResponseHeaders
  • func (rh ResponseHeaders) Then(next http.Handler) http.Handler
  • func (rh ResponseHeaders) ThenFunc(next http.HandlerFunc) http.Handler
• type ServerIn
• type Tls
• type TrackingWriter
  • func NewTrackingWriter(next http.ResponseWriter) TrackingWriter

Variables

var (
	ErrTlsCertificateRequired         = errors.New("Both a certificateFile and keyFile are required")
	ErrUnableToAddClientCACertificate = errors.New("Unable to add client CA certificate")
)

var (
	// ErrHijackerNotSupported is returned by TrackingWriter.Hijack when the underlying
	// http.ResponseWriter does not implement http.Hijacker.
	ErrHijackerNotSupported = errors.New("http.Hijacker is not supported")
)

Functions

func AddressKey

func AddressKey() interface{}

AddressKey is the logging key for the server's bind address

func NewListener

func NewListener(ctx context.Context, o Options, lcfg net.ListenConfig) (net.Listener, error)

NewListener constructs a net.Listener appropriate for the server configuration. This function binds to the address specified in the options or an autoselected address if that field is one of the values mentioned at https://godoc.org/net#Listen.

func NewServerChain

func NewServerChain(o Options, l log.Logger, pb ...xloghttp.ParameterBuilder) alice.Chain

NewServerChain produces the standard constructor chain for a server, primarily using configuration.

func NewServerLogger

func NewServerLogger(o Options, base log.Logger, extra ...interface{}) log.Logger

NewServerLogger returns a go-kit Logger enriched with information about the server.

func NewTlsConfig

func NewTlsConfig(t *Tls) (*tls.Config, error)

NewTlsConfig produces a *tls.Config from a set of configuration options. If the supplied set of options is nil, this function returns nil with no error.

func OnStart

func OnStart(o Options, s Interface, logger log.Logger, onExit func()) func(context.Context) error

OnStart produces a closure that will start the given server appropriately

func OnStop

func OnStop(s Interface, logger log.Logger) func(context.Context) error

OnStop produces a closure that will shutdown the server appropriately

func ServerKey

func ServerKey() interface{}

ServerKey is the logging key for the server's name

func Unmarshal

func Unmarshal(configKey string, c ...alice.Constructor) func(in ServerIn) (*mux.Router, error)

Unmarshal unmarshals a server from the given configuration key and emits a *mux.Router.

This function provides a default server name if none is supplied in the options. This default name is the last dotted element of the configuration key. This allows multiple servers in a map to naturally take their map keys as default names. For example, unmarshalling a key of "servers.foo" would yield a default name of "foo".

func UseTrackingWriter

func UseTrackingWriter(next http.Handler) http.Handler

UseTrackingWriter is an Alice-style constructor that wraps the response writer as a TrackingWriter

Types

type ChainFactory

type ChainFactory interface {
	New(Options) (alice.Chain, error)
}

ChainFactory is a creation strategy for server-specific alice.Chains that will decorate the server handler. Chains created by this factory will be appended to the core chain created by NewServerChain.

This interface is useful when particular servers need custom chains based on configuration. The most common example of this is metrics, as server metrics might need the name of the server as a label.

type ChainFactoryFunc

type ChainFactoryFunc func(Options) (alice.Chain, error)

func (ChainFactoryFunc) New

func (cff ChainFactoryFunc) New(o Options) (alice.Chain, error)

type Interface

type Interface interface {
	// Serve handles both TLS and non-TLS listeners.  Code in this package takes care of creating
	// a *tls.Config and TLS listener.
	Serve(l net.Listener) error

	// Shutdown gracefully shuts down the server
	Shutdown(context.Context) error
}

Interface is the expected behavior of a server

func New

func New(o Options, l log.Logger, h http.Handler) Interface

New constructs a basic HTTP server instance. The supplied logger is enriched with information about the server and returned for use by higher-level code.

type MissingValueError

type MissingValueError struct {
	Header    string
	Parameter string
}

MissingValueError indicates a missing header or parameter in a request (or both)

func (MissingValueError) Error

func (mve MissingValueError) Error() string

func (MissingValueError) StatusCode

func (mve MissingValueError) StatusCode() int

type MissingVariableError

type MissingVariableError struct {
	Variable string
}

MissingVariableError indicates a missing URI variable, which is a misconfiguration

func (MissingVariableError) Error

func (mve MissingVariableError) Error() string

func (MissingVariableError) StatusCode

func (mve MissingVariableError) StatusCode() int

type Options

type Options struct {
	Name    string
	Address string
	Network string
	Tls     *Tls

	LogConnectionState    bool
	DisableHTTPKeepAlives bool
	MaxHeaderBytes        int

	IdleTimeout       time.Duration
	ReadHeaderTimeout time.Duration
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration

	DisableTCPKeepAlives bool
	TCPKeepAlivePeriod   time.Duration

	Header               http.Header
	DisableTracking      bool
	DisableHandlerLogger bool
}

Options represent the configurable options for creating a server, typically unmarshalled from an external source.

type ResponseHeaders

type ResponseHeaders struct {
	Header http.Header
}

func (ResponseHeaders) Then

func (rh ResponseHeaders) Then(next http.Handler) http.Handler

func (ResponseHeaders) ThenFunc

func (rh ResponseHeaders) ThenFunc(next http.HandlerFunc) http.Handler

type ServerIn

type ServerIn struct {
	fx.In

	Logger       log.Logger
	Unmarshaller config.Unmarshaller
	Shutdowner   fx.Shutdowner
	Lifecycle    fx.Lifecycle

	// Chain is an optional component which, if present, decorates all server handlers in the container
	// Both this field and ChainFactory may be used simultaneously.
	Chain alice.Chain `optional:"true"`

	// ChainFactory is an optional component which is used to build an alice.Chain for each particular
	// server based on configuration.  Both this field and Chain may be used simultaneously.
	ChainFactory ChainFactory `optional:"true"`

	// ParameterBuiders is an optional component which is used to create contextual request loggers
	// for use by http.Handler code.
	ParameterBuilders xloghttp.ParameterBuilders `optional:"true"`
}

ServerIn holds the set of dependencies required to create an HTTP server in the context of a uber/fx application.

type Tls

type Tls struct {
	CertificateFile         string
	KeyFile                 string
	ClientCACertificateFile string
	ServerName              string
	NextProtos              []string
	MinVersion              uint16
	MaxVersion              uint16
}

Tls represents the set of configurable options for a serverside tls.Config associated with a server.

type TrackingWriter

type TrackingWriter interface {
	http.ResponseWriter
	http.Hijacker
	http.Pusher
	http.Flusher
	kithttp.StatusCoder

	// Hijacked returns true if the underlying network connection has been hijacked
	Hijacked() bool

	// BytesWritten returns the total bytes written to the response body via Write.
	BytesWritten() int
}

TrackingWriter is a decorated http.ResponseWriter that allows visibility into various items written to the response.

Implementations always implement the optional interfaces. In cases where the underlying http.ResponseWriter does not implement that interface, e.g. http.Pusher, either an error is returned or the method is a no-op.

This interface implements go-kit's StatusCoder to allow client code to narrowly cast to the desired type.

func NewTrackingWriter

func NewTrackingWriter(next http.ResponseWriter) TrackingWriter

NewTrackingWriter decorates an existing response writer and allows visibility into certain items written to the response.