httpserver

package
v0.7.4 Latest Latest
Warning

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

 Go to latest Published: May 2, 2026 License: BSD-3-Clause Imports: 30 Imported by: 0

Documentation

Overview

Package httpserver can host an HTTP server in the CLI app.

Index

Constants

This section is empty.

Variables

View Source 
var (
	DefaultReadyFunc = ComposeReadyFuncs(
		ReportListening(),
		ReloadServer(),
	)
)

DefaultReadyFunc provides the default behavior when the server starts

View Source 
var (
	// ErrNotListening is reported when the server is not listening
	ErrNotListening = errors.New("server is not listening")
)
View Source 
var HandlerRegistry = &provider.Registry{
	Name: "handlers",
	Providers: provider.Details{
		"ping": {
			Factory:  provider.FactoryOf(newPingHandlerWithOpts),
			HelpText: "Responds simply Generates a ping",
		},
		"file": {
			Factory:  provider.FactoryOf(newFileServerHandlerWithOpts),
			HelpText: "Serve a particular directory as static files",
			Defaults: map[string]string{
				"directory":              ".",
				"hide_directory_listing": "false",
			},
		},
		"reload": {
			Value: HandlerSpec(func(ctx context.Context, _ httpclient.VirtualPath) (http.Handler, error) {
				return NewReloadHandler(FromContext(ctx)), nil
			}),
			HelpText: "Reloads the server",
		},
		"redirect": {
			Factory:  provider.FactoryOf(newRedirectServerHandlerWithOpts),
			HelpText: "Redirect to the given path and provide a status code",
			Defaults: map[string]string{
				"to":   "/",
				"code": strconv.Itoa(http.StatusTemporaryRedirect),
			},
		},
		"echo": {
			Factory:  provider.FactoryOf(newEchoHandlerWithOpts),
			HelpText: "Reflects out the request and connection information",
			Defaults: map[string]string{
				"failsafe": "false",
			},
			Aliases: []string{"reflect"},
		},
	},
}

HandlerRegistry provides the default handler registry.

Functions

func ContextValue 

func ContextValue(s *Server) cli.Action

func ExpandRequest 

func ExpandRequest(r *http.Request, ww wrapResponseWriter) expander.Interface

func FlagsAndArgs 

func FlagsAndArgs() cli.Action

FlagsAndArgs adds numerous flags that can be used to configure the server in the context. The default flags list contains all of the flag actions in this package except for SetHandler and its variants.

func Handle 

func Handle(path string, h http.Handler) cli.Action

Handle registers the given handler with the context server

func HandleFunc added in v0.7.0 

func HandleFunc(path string, h http.HandlerFunc) cli.Action

HandleFunc registers the given handler with the context server

func HandleSpec added in v0.7.1 

func HandleSpec(vpath httpclient.VirtualPath, spec HandlerSpec) cli.Action

HandleSpec registers the given handler spec with the context server

func ListHandlers 

func ListHandlers() cli.Action

ListHandlers provides an action which lists the handlers for the handler flag. When used in the Uses pipeline, also sets reasonable defaults for a flag. This handler is not included in FlagsAndArgs

func NewEchoHandler added in v0.5.4 

func NewEchoHandler(failsafe bool) http.Handler

NewEchoHandler provides a handler which echoes the request back in the response. An option failsafe indicates whether the response will always be 200 OK even if the request is malformed.

func NewHeaderMiddleware 

func NewHeaderMiddleware(name, value string) func(http.Handler) http.Handler

NewHeaderMiddleware provides handler middleware which simply adds the given header

func NewPingHandler 

func NewPingHandler() http.Handler

NewPingHandler provides a handler which simply replies with a message

func NewReloadHandler added in v0.7.4 

func NewReloadHandler(s *Server) http.Handler

NewReloadHandler provides a handler which triggers the server to reload all handlers

func NewRequestLogger 

func NewRequestLogger(format string, out io.Writer, next http.Handler) http.Handler

NewRequestLogger provides handler middleware to write to access log

func RunServer 

func RunServer(actionopt ...cli.Action) cli.Action

RunServer locates the server in context and runs it until interrupt signal is detected. Optional actions run just before the server starts up, typically used to provide context-bound modifications to the server just in time.

func SetAccessLog 

func SetAccessLog(v ...string) cli.Action

func SetAddr 

func SetAddr(s ...string) cli.Action

SetAddr sets the server address, which either uses the specified value or reads from the corresponding flag/arg to get the value to set.

func SetFileServerHandler 

func SetFileServerHandler(v ...httpclient.VirtualPath) cli.Action

SetFileServerHandler adds the specified file server handler to the mux. This can be called multiple times. This handler is not included in FlagsAndArgs

func SetHandler 

func SetHandler(v ...httpclient.VirtualPath) cli.Action

SetHandler adds the specified handler to the mux. This can be called multiple times. SetHandler only works if a Registry named "handlers" is present in the context to convert the handler spec to the correct implementation. Consider adding HandlerRegistry to the Uses pipeline.. This handler is not included in FlagsAndArgs

func SetHideDirectoryListings added in v0.7.3 

func SetHideDirectoryListings() cli.Action

SetHideDirectoryListings causes directories not to be listed

func SetHostname 

func SetHostname(s ...string) cli.Action

SetHostname sets the server address, which either uses the specified value or reads from the corresponding flag/arg to get the value to set.

func SetIdleTimeout 

func SetIdleTimeout(d ...time.Duration) cli.Action

SetIdleTimeout sets the maximum amount of time to wait for the next request when keep-alives are enabled, which either uses the specified value or reads from the corresponding flag/arg to get the value to set. If zero is set, then the value of read time is used, unless both are zero in which case there is no timeout.

func SetMaxHeaderBytes 

func SetMaxHeaderBytes(v ...int) cli.Action

SetMaxHeaderBytes sets the maximum header size in bytes

func SetNoAccessLog 

func SetNoAccessLog() cli.Action

func SetOpenInBrowser 

func SetOpenInBrowser() cli.Action

SetOpenInBrowser causes the default Web browser to open when the server is ready

func SetPort 

func SetPort(s ...int) cli.Action

SetPort sets the server port, which either uses the specified value or reads from the corresponding flag/arg to get the value to set.

func SetReadHeaderTimeout 

func SetReadHeaderTimeout(d ...time.Duration) cli.Action

SetReadHeaderTimeout sets the amount of time allowed to read request headers, which either uses the specified value or reads from the corresponding flag/arg to get the value to set.

func SetReadTimeout 

func SetReadTimeout(d ...time.Duration) cli.Action

SetReadTimeout sets the maximum duration for reading the entire request, including the body, which either uses the specified value or reads from the corresponding flag/arg to get the value to set.

func SetServerHeader added in v0.7.0 

func SetServerHeader(v ...string) cli.Action

func SetShutdownTimeout 

func SetShutdownTimeout(d ...time.Duration) cli.Action

SetShutdownTimeout sets the maximum duration to wait for shutting down the server.

func SetStaticDirectory 

func SetStaticDirectory(f ...*cli.File) cli.Action

SetStaticDirectory sets the static directory to host

func SetTLSCertFile 

func SetTLSCertFile(v ...*cli.File) cli.Action

func SetTLSKeyFile 

func SetTLSKeyFile(v ...*cli.File) cli.Action

func SetWriteTimeout 

func SetWriteTimeout(d ...time.Duration) cli.Action

SetWriteTimeout sets the maximum duration before timing out writes of the response, which either uses the specified value or reads from the corresponding flag/arg to get the value to set.

func SourceAnnotation 

func SourceAnnotation() (string, string)

SourceAnnotation gets the name and value of the annotation added to the Data of all flags that are initialized from this package

Types

type HandlerSpec 

type HandlerSpec func(context.Context, httpclient.VirtualPath) (http.Handler, error)

HandlerSpec creates a handler from a virtual path. The virtual path defines how the handler works. Typically, the physical path identifies a useful feature or the location of a file, and the options may be used for any purpose of customization.

func FileServerHandlerSpec 

func FileServerHandlerSpec() HandlerSpec

FileServerHandlerSpec creates a file server. The physical path in the virtual path specifies the base directory for the file server. An option named hide_directory_listing controls whether the directory listing response is served. The handler also consults the server for whether directory listings can be served.

func RegistryHandlerSpec 

func RegistryHandlerSpec(name string) HandlerSpec

RegistryHandlerSpec creates a handler by looking it up as a provider in the registry that is named. The physical path in the virtual path specifies the name of the provider which is used. The virtual path's options are propagated to the registry factory function.

type MiddlewareFunc 

type MiddlewareFunc func(next http.Handler) http.Handler

MiddlewareFunc defines a function that creates a middleware wrapper around another handler

type Option 

type Option interface {
	cli.Action
	// contains filtered or unexported methods
}

Option is an option to configure the server Option can be used as an Action, typically within the Uses or Before pipeline.

func AddReadyFunc 

func AddReadyFunc(ready ReadyFunc) Option

AddReadyFunc appends a callback for when the server is ready

func AddShutdownFunc 

func AddShutdownFunc(shutdown ReadyFunc) Option

AddShutdownFunc adds a callback for when the server is shutting down

func WithAccessLog added in v0.7.0 

func WithAccessLog(s string) Option

WithAccessLog sets the format string for the access log

func WithAction added in v0.7.3 

func WithAction(a cli.Action) Option

WithAction sets the action

func WithAddr 

func WithAddr(addr string) Option

WithAddr sets the corresponding server field

func WithDefaultAction added in v0.7.3 

func WithDefaultAction() Option

WithDefaultAction sets the action to the default

func WithHandler 

func WithHandler(handler http.Handler) Option

WithHandler sets the handler which will run on the server

func WithHandlerFactory 

func WithHandlerFactory(f func(*Server) (http.Handler, error)) Option

WithHandlerFactory sets how to create the handler which will run on the server

func WithHideDirectoryListings added in v0.7.3 

func WithHideDirectoryListings(v bool) Option

WithHideDirectoryListings disables directory listings

func WithHostname 

func WithHostname(v string) Option

WithHostname sets the server hostname

func WithIdleTimeout added in v0.7.0 

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout sets the amount of time to allow for idling

func WithMaxHeaderBytes added in v0.7.0 

func WithMaxHeaderBytes(n int) Option

WithMaxHeaderBytes sets the amount max header bytes

func WithMiddleware 

func WithMiddleware(m MiddlewareFunc) Option

WithMiddleware adds handler middleware

func WithNoAccessLog added in v0.7.0 

func WithNoAccessLog() Option

WithNoAccessLog disables the access log

func WithPort 

func WithPort(v int) Option

WithPort sets the server port

func WithReadHeaderTimeout added in v0.7.0 

func WithReadHeaderTimeout(d time.Duration) Option

WithReadHeaderTimeout sets the amount of time to allow for reading headers

func WithReadTimeout added in v0.7.0 

func WithReadTimeout(d time.Duration) Option

WithReadTimeout sets the amount of time to allow for reading requests

func WithReadyFunc 

func WithReadyFunc(ready ReadyFunc) Option

WithReadyFunc sets a callback for when the server is listening

func WithServerHeader added in v0.7.0 

func WithServerHeader(s string) Option

WithServerHeader sets the contents of the server header

func WithShutdownFunc 

func WithShutdownFunc(shutdown ReadyFunc) Option

WithShutdownFunc sets a callback for when the server is shutting down

func WithShutdownTimeout 

func WithShutdownTimeout(d time.Duration) Option

WithShutdownTimeout sets the amount of time to allow the server to shutdown

func WithStaticDirectory added in v0.7.0 

func WithStaticDirectory(path string) Option

WithStaticDirectory hosts a static directory

func WithTLSCertFile added in v0.7.0 

func WithTLSCertFile(filename string) Option

WithTLSCertFile sets the file to use for the TLS cert

func WithTLSKeyFile added in v0.7.0 

func WithTLSKeyFile(filename string) Option

WithTLSKeyFile sets the file to use for the TLS key

func WithWriteTimeout added in v0.7.0 

func WithWriteTimeout(d time.Duration) Option

WithWriteTimeout sets the amount of time to allow for writing responses

type Options added in v0.7.4 

type Options struct {
	Addr                  *string        `toml:"addr"                    json:"addr,omitempty"`
	Hostname              *string        `toml:"hostname"                json:"hostname,omitempty"`
	Port                  *int           `toml:"port"                    json:"port,omitempty"`
	TLSCertFile           *string        `toml:"tls-cert-file"           json:"tlsCertFile,omitempty"`
	TLSKeyFile            *string        `toml:"tls-key-file"            json:"tlsKeyFile,omitempty"`
	ServerHeader          *string        `toml:"server-header"           json:"serverHeader,omitempty"`
	AccessLog             *string        `toml:"access-log"              json:"accessLog,omitempty"`
	StaticDirectory       *string        `toml:"static-directory"        json:"staticDirectory,omitempty"`
	HideDirectoryListings *bool          `toml:"hide-directory-listings" json:"hideDirectoryListings,omitempty"`
	ShutdownTimeout       *time.Duration `toml:"shutdown-timeout"        json:"shutdownTimeout,omitempty"`
	ReadTimeout           *time.Duration `toml:"read-timeout"            json:"readTimeout,omitempty"`
	ReadHeaderTimeout     *time.Duration `toml:"read-header-timeout"     json:"readHeaderTimeout,omitempty"`
	WriteTimeout          *time.Duration `toml:"write-timeout"           json:"writeTimeout,omitempty"`
	IdleTimeout           *time.Duration `toml:"idle-timeout"            json:"idleTimeout,omitempty"`
	MaxHeaderBytes        *int           `toml:"max-header-bytes"        json:"maxHeaderBytes,omitempty"`
}

Options contains settings for the server which have data representations. Each non-nil field is applied when Options is used as an Option.

func (*Options) Execute added in v0.7.4 

func (o *Options) Execute(ctx context.Context) error

type ReadyFunc 

type ReadyFunc func(context.Context)

ReadyFunc provides a function for when the server has started or stopped

func ComposeReadyFuncs 

func ComposeReadyFuncs(v ...ReadyFunc) ReadyFunc

ComposeReadyFuncs provides a ReadyFunc that combines a sequence

func OpenInBrowser 

func OpenInBrowser(path ...string) ReadyFunc

OpenInBrowser is a function to open the server in the browser. This function is passed as a value to WithReadyFunc

func ReloadServer added in v0.7.1 

func ReloadServer() ReadyFunc

ReloadServer provides a function which reloads reloadable handlers. This is included in the default ready function for the server. To defer loading to the first time a handler is invoked, you should remove this ready func from the server. If the server does not support reloading, this operation fails silently

func ReportListening 

func ReportListening() ReadyFunc

ReportListening is a ready func that prints a message to stderr that the server is listening

func (ReadyFunc) Execute added in v0.7.0 

func (r ReadyFunc) Execute(c context.Context) error

type ReloadableHandler added in v0.7.1 

type ReloadableHandler interface {
	http.Handler

	Invalidate()
}

ReloadableHandler provides a handler whose internal state can be invalidated so that the next time it serves, it recomputes it

func NewReloadableHandler added in v0.7.1 

func NewReloadableHandler(fn func(context.Context) (http.Handler, error)) ReloadableHandler

NewReloadableHandler provides a handler which is reloadable. When the server starts or when the server is restarted, the function is invoked to generate the actual handler that is called. If an error is returned, the server will respond with 503 Service Unavailable.

type Server 

type Server struct {
	*http.Server
	cli.Action

	TLSCertFile string
	TLSKeyFile  string

	// ShutdownTimeout specifies how long to wait for the server to shutdown
	// when a signal is received
	ShutdownTimeout time.Duration
	// contains filtered or unexported fields
}

Server provides an HTTP server (indeed http.Server is embedded) that can be initialized and hosted within a CLI app. The server is used within the Uses pipeline where it registers itself as a context service. The action RunServer is used to actually run the server.

The simplest action to use is RunServer(), which runs the server: 

&cli.App{
   Name: "goserv",
   Uses: &httpserver.New(httpserver.WithHandler(...)),
   Action: httpserver.RunServer(),
}

This simple app has numerous flags to configure connection handling and to dynamically construct the server's router. Many dynamic server routing actions depend upon the server having a handler which is also a mux that contains a method Handle(string, http.Handler) to register additional handlers. (This is the same API provided by the built-in Go mux, http.ServeMux). There are other APIs provided by convention, documented in their respective contexts.

The cmd/weave package provides weave, which is a command line utility that hosts a server for files and some built-in handlers, which is similar to what the DefaultServer() does.

If you only want to add the Server to the context (typically in advanced scenarios where you are deeply customizing the behavior), you only use the action httpserver.ContextValue() with the server you want to add instead of add the server to the pipeline directly.

func DefaultServer 

func DefaultServer() *Server

func FromContext 

func FromContext(ctx context.Context) *Server

FromContext obtains the server from the context.

func New 

func New(options ...Option) *Server

New creates a new HTTP server with the given handler creation callback.

func (*Server) AddMiddleware 

func (s *Server) AddMiddleware(m MiddlewareFunc) error

AddMiddleware appends additional middleware to the server

func (*Server) AddReadyFunc added in v0.7.0 

func (s *Server) AddReadyFunc(ready ReadyFunc) error

AddReadyFunc appens additional ready functions

func (*Server) AddShutdownFunc added in v0.7.0 

func (s *Server) AddShutdownFunc(shutdown ReadyFunc) error

AddShutdownFunc appends additional shutdown functions

func (*Server) Apply added in v0.7.0 

func (s *Server) Apply(opts ...Option)

func (*Server) Handle 

func (s *Server) Handle(path string, h http.Handler) (err error)

func (*Server) HideDirectoryListing 

func (s *Server) HideDirectoryListing() bool

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe() error

func (*Server) OpenInBrowser 

func (s *Server) OpenInBrowser(path ...string) error

OpenInBrowser opens in the browser. The request path can also be specified

func (*Server) Pipeline added in v0.7.3 

func (s *Server) Pipeline() cli.Action

func (*Server) ReloadAll added in v0.7.1 

func (s *Server) ReloadAll()

ReloadAll causes the server to reload all reloadable handlers. To support reloading, the built-in mux must be used. In particular, you can't specify a handler or handler factory directly.

func (*Server) ReportListening 

func (s *Server) ReportListening() error

func (*Server) SetAccessLog 

func (s *Server) SetAccessLog(v string) error

func (*Server) SetAddr 

func (s *Server) SetAddr(addr string) error

func (*Server) SetHideDirectoryListings added in v0.7.3 

func (s *Server) SetHideDirectoryListings(v bool) error

func (*Server) SetHostname 

func (s *Server) SetHostname(name string) error

func (*Server) SetIdleTimeout 

func (s *Server) SetIdleTimeout(v time.Duration) error

func (*Server) SetMaxHeaderBytes 

func (s *Server) SetMaxHeaderBytes(v int) error

func (*Server) SetPort 

func (s *Server) SetPort(port int) error

func (*Server) SetReadHeaderTimeout 

func (s *Server) SetReadHeaderTimeout(v time.Duration) error

func (*Server) SetReadTimeout 

func (s *Server) SetReadTimeout(v time.Duration) error

func (*Server) SetServerHeader added in v0.7.0 

func (s *Server) SetServerHeader(name string) error

func (*Server) SetShutdownTimeout 

func (s *Server) SetShutdownTimeout(d time.Duration) error

func (*Server) SetStaticDirectory 

func (s *Server) SetStaticDirectory(path string) error

func (*Server) SetTLSCertFile 

func (s *Server) SetTLSCertFile(v string) error

func (*Server) SetTLSKeyFile 

func (s *Server) SetTLSKeyFile(v string) error

func (*Server) SetWriteTimeout 

func (s *Server) SetWriteTimeout(v time.Duration) error

func (*Server) WithHandler added in v0.7.0 

func (s *Server) WithHandler(handler http.Handler) error

WithHandler sets the handler for the server

func (*Server) WithHandlerFactory added in v0.7.0 

func (s *Server) WithHandlerFactory(f func(*Server) (http.Handler, error)) error

WithHandlerFactory sets the handler factory for the server

func (*Server) WithReadyFunc added in v0.7.0 

func (s *Server) WithReadyFunc(ready ReadyFunc) error

WithReadyFunc sets the ready function for the server

func (*Server) WithShutdownFunc added in v0.7.0 

func (s *Server) WithShutdownFunc(shutdown ReadyFunc) error

WithShutdownFunc sets the shutdown function

Source Files

View all Source files

Directories

Path Synopsis
Code generated by counterfeiter.
 Code generated by counterfeiter.

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.