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 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 UseTrackingWriter(next http.Handler) http.Handler
• type ChainFactory
• type ChainFactoryFunc
  • func (cff ChainFactoryFunc) New(n string, 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 ServerNotConfiguredError
  • func (e ServerNotConfiguredError) Error() string
• type Tls
• type TrackingWriter
  • func NewTrackingWriter(next http.ResponseWriter) TrackingWriter
• type Unmarshal
  • func (u Unmarshal) Annotated() fx.Annotated
  • func (u Unmarshal) Provide(in ServerIn) (*mux.Router, error)

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 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 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(string, 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(string, Options) (alice.Chain, error)

func (ChainFactoryFunc) New

func (cff ChainFactoryFunc) New(n string, 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 {
	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

	// 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 ServerNotConfiguredError

type ServerNotConfiguredError struct {
	Key string
}

ServerNotConfiguredError is returned when a required server has no configuration key

func (ServerNotConfiguredError) Error

func (e ServerNotConfiguredError) Error() string

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.

type Unmarshal

type Unmarshal struct {
	// Key is the viper configuration key containing the server Options
	Key string

	// Name is the string that identifies this server from others within the same application.  If unset,
	// the Key is used.
	Name string

	// Optional indicates whether the configuration is required.  If this field is false (the default),
	// and there is no such configuration Key, an error is returned.
	Optional bool

	// Chain is an optional set of constructors that will decorate the *mux.Router.  This field is useful for static
	// decorators, such as inserting known headers into every response.
	//
	// This chain cannot depend on components.  In order to leverage dependency injection, create a ChainFactory instead.
	Chain alice.Chain
}

Unmarshal describes how to unmarshal an HTTP server. This type contains all the non-component information related to server instantiation.

func (Unmarshal) Annotated

func (u Unmarshal) Annotated() fx.Annotated

Annotated is like Unmarshal, save that it emits a named *mux.Router. This method is appropriate for applications with multiple servers. The name of the returned *mux.Router is either the Name field (if set) or the Key field (if Name is empty).

func (Unmarshal) Provide

func (u Unmarshal) Provide(in ServerIn) (*mux.Router, error)

Provide unmarshals a server using the Key field and creates a *mux.Router which is the root handler for that server's requests. This *mux.Router will be decorated with the constructors from NewServerChain as well as any ChainFactory's constructors.