arrangehttp

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 18, 2024 License: Apache-2.0 Imports: 16 Imported by: 7

Documentation

Overview

Package arrangehttp further extends the notion of unmarshaled components to the idea of building http servers and clients from configuration.

Index

Constants

View Source 
const (
	// ServerAbnormalExitCode is the shutdown exit code, returned by the process,
	// when an *http.Server exits with an error OTHER than ErrServerClosed.
	ServerAbnormalExitCode = 255
)

Variables

View Source 
var (
	// ErrClientNameRequired indicates that ProvideClient or ProvideClientCustom was called
	// with an empty client name.
	ErrClientNameRequired = errors.New("A client name is required")
)
View Source 
var (
	// ErrServerNameRequired indicates that ProvideServer or ProvideServerCustom was called
	// with an empty server name.
	ErrServerNameRequired = errors.New("A server name is required")
)

Functions

func ApplyMiddleware added in v0.5.0 

func ApplyMiddleware[T any, M Middleware[T]](t T, m ...M) T

ApplyMiddleware handles decorating a target type T. Middleware executes in the order declared to this function.

func ApplyOptions added in v0.5.0 

func ApplyOptions[T any](t *T, opts ...Option[T]) (result *T, err error)

ApplyOptions applies several options to a target. This function returns the original target t so that it can be used with fx.Decorate.

func NewClient added in v0.5.0 

func NewClient(cc ClientConfig, opts ...Option[http.Client]) (*http.Client, error)

NewClient is the primary client constructor for arrange. Use this when you are creating a client from a (possibly unmarshaled) ClientConfig. The options can be annotated to come from a value group, which is useful when there are multiple clients in a single fx.App.

func NewClientCustom added in v0.5.0 

func NewClientCustom[F ClientFactory](cf F, opts ...Option[http.Client]) (c *http.Client, err error)

NewClientCustom is an *http.Client constructor that allows customization of the concrete ClientFactory used to create the *http.Client. This function is useful when you have a custom (possibly unmarshaled) configuration struct that implements ClientFactory.

If the ClientFactory type also implements Option[http.Client], it is applied after all the other options are applied.

func NewListener added in v0.5.0 

func NewListener(ctx context.Context, lf ListenerFactory, server *http.Server, lm ...ListenerMiddleware) (l net.Listener, err error)

NewListener encapsulates the logic for creating a net.Listener for a server. This function should be called from within a start hook, typically via fx.Hook.OnStart.

The ListenerFactory may be nil, in which case an instance of DefaultListenerFactory will be used.

func NewServer added in v0.5.0 

func NewServer(sc ServerConfig, h http.Handler, opts ...Option[http.Server]) (*http.Server, error)

NewServer is the primary server constructor for arrange. Use this when you are creating a server from a (possibly unmarshaled) ServerConfig. The options can be annotated to come from a value group, which is useful when there are multiple servers in a single fx.App.

ProvideServer gives an opinionated approach to using this function to create an *http.Server. However, this function can be used by itself to allow very flexible binding: 

app := fx.New(
  fx.Provide(
    arrangehttp.NewServer, // all the parameters need to be global, unnamed components
    fx.Annotate(
      arrangehttp.NewServer,
      fx.ResultTags(`name:"myserver"`), // change the component name of the *http.Server
    ),
  ),
)

func NewServerCustom added in v0.5.0 

func NewServerCustom[H http.Handler, F ServerFactory](sf F, h H, opts ...Option[http.Server]) (s *http.Server, err error)

NewServerCustom is a server constructor that allows a client to customize the concrete ServerFactory and http.Handler for the server. This function is useful when you have a custom (possibly unmarshaled) configuration struct that implements ServerFactory.

The ServerFactory may also optionally implement Option[http.Server]. If it does, the factory option is applied after all other options have run.

func ProvideClient added in v0.5.0 

func ProvideClient(clientName string, external ...Option[http.Client]) fx.Option

ProvideClient assembles a client out of application components in a standard, opinionated way. The clientName parameter is used as both the name of the *http.Client component and a prefix for that server's dependencies:

  • NewClient is used to create the client as a component named clientName
  • ClientConfig is an optional dependency with the name clientName+".config"
  • []ClientOption is an value group dependency with the name clientName+".options"

The external set of options, if supplied, is applied to the client after any injected options. This allows for options that come from outside the enclosing fx.App, as might be the case for options driven by the command line.

func ProvideClientCustom added in v0.5.0 

func ProvideClientCustom[F ClientFactory](clientName string, external ...Option[http.Client]) fx.Option

ProvideClientCustom is like ProvideClient, but it allows customization of the concrete ClientFactory dependency.

func ProvideServer added in v0.5.0 

func ProvideServer(serverName string, external ...any) fx.Option

ProvideServer assembles a server out of application components in a standard, opinionated way. The serverName parameter is used as both the name of the *http.Server component and a prefix for that server's dependencies:

  • NewServer is used to create the server as a component named serverName
  • ServerConfig is an optional dependency with the name serverName+".config"
  • http.Handler is an optional dependency with the name serverName+".handler"
  • []Option[http.Server] is a value group dependency with the name serverName+".options"
  • []ListenerMiddleware is a value group dependency with the name serverName+".listener.middleware"

The external slice contains items that come from outside the enclosing fx.App that are applied to the server and listener. Each element of external must be either an Option[http.Server] or a ListenerMiddleware. Any other type short circuits application startup with an error.

func ProvideServerCustom added in v0.5.0 

func ProvideServerCustom[H http.Handler, F ServerFactory](serverName string, external ...any) fx.Option

ProvideServerCustom is like ProvideServer, but it allows customization of the concrete ServerFactory and http.Handler dependencies.

Types

type BaseContextFunc added in v0.5.0 

type BaseContextFunc interface {
	~func(context.Context, net.Listener) context.Context
}

BaseContextFunc is a composable type that is used to build http.Server.BaseContext functions.

type ClientConfig added in v0.1.3 

type ClientConfig struct {
	Timeout   time.Duration
	Transport TransportConfig
	Header    http.Header
	TLS       *arrangetls.Config
}

ClientConfig holds unmarshaled client configuration options. It is the built-in ClientFactory implementation in this package.

func (ClientConfig) Apply added in v0.5.0 

func (cc ClientConfig) Apply(c *http.Client) error

Apply allows a ClientConfig to be used as an Option[http.Client]. This method decorates the client's transport so that the configured headers are supplied with every request.

func (ClientConfig) NewClient added in v0.1.3 

func (cc ClientConfig) NewClient() (client *http.Client, err error)

NewClient produces an http.Client given these unmarshaled configuration options

type ClientFactory added in v0.1.3 

type ClientFactory interface {
	NewClient() (*http.Client, error)
}

ClientFactory is the interface implemented by unmarshaled configuration objects that produces an http.Client. The default implementation of this interface is ClientConfig.

type ConnContextFunc added in v0.5.0 

type ConnContextFunc interface {
	~func(context.Context, net.Conn) context.Context
}

ConnContextFunc is the type of function required by net/http.Server.ConnContext.

type DefaultListenerFactory added in v0.1.6 

type DefaultListenerFactory struct {
	// ListenConfig is the object used to create the net.Listener
	ListenConfig net.ListenConfig

	// Network is the network to listen on, which must always be a TCP network.
	// If not set, "tcp" is used.
	Network string
}

DefaultListenerFactory is the default implementation of ListenerFactory. The zero value of this type is a valid factory.

func (DefaultListenerFactory) Listen added in v0.1.6 

func (f DefaultListenerFactory) Listen(ctx context.Context, server *http.Server) (net.Listener, error)

Listen provides the default ListenerFactory behavior for this package. It essentially does the same thing as net/http, but allows the network to be configured externally and ensures that the listen address matches the server address.

type ListenerFactory 

type ListenerFactory interface {
	// Listen creates the appropriate net.Listener, binding to a TCP address in
	// the process
	Listen(context.Context, *http.Server) (net.Listener, error)
}

ListenerFactory is a strategy for creating net.Listener instances. Since any applied options may have changed the http.Server instance, this strategy is passed that server instance.

The http.Server.Addr field should used as the address of the listener. If the given server has a tls.Config set, the returned listener should create TLS connections with that configuration.

The returned net.Listener may be decorated arbitrarily. Callers cannot assume the actual type will be *net.TCPListener, although that will always be the ultimate listener that accepts connections.

The built-in implementation of this type is DefaultListenerFactory.

type ListenerMiddleware added in v0.5.0 

type ListenerMiddleware func(net.Listener) net.Listener

ListenerMiddleware represents a strategy for decorating net.Listener instances.

type Middleware added in v0.1.5 

type Middleware[T any] interface {
	~func(T) T
}

Middleware is the underlying type for decorators.

type Option added in v0.5.0 

type Option[T any] interface {
	Apply(*T) error
}

Option represents something that can modify a target object.

func AsOption added in v0.5.0 

func AsOption[T any, F OptionClosure[T]](f F) Option[T]

AsOption converts a closure into an Option for a given target type.

func BaseContext added in v0.1.9 

func BaseContext[BCF BaseContextFunc](ctxFns ...BCF) Option[http.Server]

BaseContext returns a server option that sets or replaces the http.Server.BaseContext function. Each individual context function is composed to produce the context for the given listener.

func ClientMiddleware added in v0.5.0 

func ClientMiddleware[M Middleware[http.RoundTripper]](fns ...M) Option[http.Client]

ClientMiddleware returns a ClientOption that applies the given middleware to the Transport (http.RoundTripper).

func ConnContext added in v0.1.9 

func ConnContext[CCF ConnContextFunc](ctxFns ...CCF) Option[http.Server]

ConnContext returns a server option that sets or augments the http.Server.ConnContext function. Any existing ConnContext on the server is merged with the given functions to create a single ConnContext closure that uses each function to build the context for each server connection.

func ConnState added in v0.1.9 

func ConnState(fn func(net.Conn, http.ConnState)) Option[http.Server]

ConnState returns a server option that sets or replaces the http.Server.ConnState function.

func ErrorLog added in v0.1.9 

func ErrorLog(l *log.Logger) Option[http.Server]

ErrorLog returns a server option that sets or replaces the http.Server.ErrorLog

func InvalidOption added in v0.5.0 

func InvalidOption[T any](err error) Option[T]

InvalidOption returns an Option that returns the given error. Useful instead of nil or a panic to indicate that something in the setup of an Option went wrong.

func ServerMiddleware added in v0.5.0 

func ServerMiddleware[M Middleware[http.Handler]](fns ...M) Option[http.Server]

ServerMiddleware returns an option that applies any number of middleware functions to a server's handler.

type OptionClosure added in v0.5.0 

type OptionClosure[T any] interface {
	~func(*T) | ~func(*T) error
}

OptionClosure represents the closure types that are convertible into Option objects.

type OptionFunc added in v0.5.0 

type OptionFunc[T any] func(*T) error

OptionFunc is a closure type that can act as an Option.

func (OptionFunc[T]) Apply added in v0.5.0 

func (of OptionFunc[T]) Apply(t *T) error

type Options added in v0.5.0 

type Options[T any] []Option[T]

Options is an aggregate Option that allows several options to be grouped together.

func (Options[T]) Apply added in v0.5.0 

func (o Options[T]) Apply(t *T) (err error)

Apply applies all the options in this slice, returning an aggregate error if any errors occurred.

type ServerConfig 

type ServerConfig struct {
	// Network is the tcp network to listen on.  The default is "tcp".
	Network string `json:"network" yaml:"network"`

	// Address is the bind address of the server.  If unset, the server binds to
	// the first port available.  In that case, CaptureListenAddress can be used
	// to obtain the bind address for the server.
	Address string `json:"address" yaml:"address"`

	// ReadTimeout corresponds to http.Server.ReadTimeout
	ReadTimeout time.Duration `json:"readTimeout" yaml:"readTimeout"`

	// ReadHeaderTimeout corresponds to http.Server.ReadHeaderTimeout
	ReadHeaderTimeout time.Duration `json:"readHeaderTimeout" yaml:"readHeaderTimeout"`

	// WriteTime corresponds to http.Server.WriteTimeout
	WriteTimeout time.Duration `json:"writeTimeout" yaml:"writeTimeout"`

	// IdleTimeout corresponds to http.Server.IdleTimeout
	IdleTimeout time.Duration `json:"idleTimeout" yaml:"idleTimeout"`

	// MaxHeaderBytes corresponds to http.Server.MaxHeaderBytes
	MaxHeaderBytes int `json:"maxHeaderBytes" yaml:"maxHeaderBytes"`

	// KeepAlive corresponds to net.ListenConfig.KeepAlive.  This value is
	// only used for listeners created via Listen.
	KeepAlive time.Duration `json:"keepAlive" yaml:"keepAlive"`

	// Header supplies HTTP headers to emit on every response from this server
	Header http.Header `json:"header" yaml:"header"`

	// TLS is the optional unmarshaled TLS configuration.  If set, the resulting
	// server will use HTTPS.
	TLS *arrangetls.Config `json:"tls" yaml:"tls"`
}

ServerConfig is the built-in ServerFactory implementation for this package. This struct can be unmarshaled from an external source, or supplied literally to the *fx.App.

func (ServerConfig) Apply added in v0.5.0 

func (sc ServerConfig) Apply(s *http.Server) error

Apply allows this configuration object to be seen as an Option[http.Server]. This method adds the configured headers to every response.

func (ServerConfig) Listen added in v0.1.6 

func (sc ServerConfig) Listen(ctx context.Context, s *http.Server) (net.Listener, error)

Listen is the ListenerFactory implementation driven by ServerConfig

func (ServerConfig) NewServer 

func (sc ServerConfig) NewServer() (server *http.Server, err error)

NewServer is the built-in implementation of ServerFactory in this package. This should serve most needs. Nothing needs to be done to use this implementation. By default, a Fluent Builder chain begun with Server() will use ServerConfig.

type ServerFactory 

type ServerFactory interface {
	ListenerFactory

	// NewServer constructs an *http.Server.
	NewServer() (*http.Server, error)
}

ServerFactory is the strategy for instantiating an *http.Server and an associated net.Listener. ServerConfig is this package's implementation of this interface, and allows a ServerFactory instance to be read from an external source.

A custom ServerFactory implementation can be injected and used via NewServerCustom or ProvideServerCustom.

type TransportConfig added in v0.1.3 

type TransportConfig struct {
	TLSHandshakeTimeout    time.Duration
	DisableKeepAlives      bool
	DisableCompression     bool
	MaxIdleConns           int
	MaxIdleConnsPerHost    int
	MaxConnsPerHost        int
	IdleConnTimeout        time.Duration
	ResponseHeaderTimeout  time.Duration
	ExpectContinueTimeout  time.Duration
	ProxyConnectHeader     http.Header
	MaxResponseHeaderBytes int64
	WriteBufferSize        int
	ReadBufferSize         int
	ForceAttemptHTTP2      bool
}

TransportConfig holds the unmarshalable configuration options for building an http.Transport. Fields in this struct correspond almost entirely with those in http.Transport.

func (TransportConfig) NewTransport added in v0.1.3 

func (tc TransportConfig) NewTransport(c *arrangetls.Config) (transport *http.Transport, err error)

NewTransport creates an http.Transport using this unmarshaled configuration together with TLS information

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳