httpserver

package
v0.5.3 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2025 License: BSD-3-Clause Imports: 21 Imported by: 0

Documentation

Overview

Copyright 2025 The Joe-cli Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Copyright 2025 The Joe-cli Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file. Package httpserver can host an HTTP server in the CLI app.

Copyright 2025 The Joe-cli Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Copyright 2023 The Joe-cli Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Index

Constants

This section is empty.

Variables

View Source 
var (
	DefaultReadyFunc = ComposeReadyFuncs(
		ReportListening,
	)

	// ErrNotListening is reported when the server is not listening
	ErrNotListening = errors.New("server is not listening")
)

DefaultReadyFunc provides the default behavior when the server starts

View Source 
var HandlerRegistry = &provider.Registry{
	Name: "handlers",
	Providers: provider.Details{
		"ping": {
			Factory: provider.Factory(newPingHandlerWithOpts),
		},
		"file": {
			Factory: provider.Factory(newFileServerHandlerWithOpts),
		},
		"redirect": {
			Factory: provider.Factory(newRedirectServerHandlerWithOpts),
		},
	},
}

HandlerRegistry provides the default handler registry.

Functions

func ContextValue 

func ContextValue(s *Server) cli.Action

func ExpandRequest 

func ExpandRequest(r *http.Request, ww wrapResponseWriter) expr.Expander

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 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 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 NewRequestLogger 

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

NewRequestLogger provides handler middleware to write to access log

func OpenInBrowser 

func OpenInBrowser(c context.Context)

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

func ReportListening 

func ReportListening(c context.Context)

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

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 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(v ...bool) cli.Action

func SetNoDirectoryListings 

func SetNoDirectoryListings() cli.Action

SetNoDirectoryListings causes directories not to be listed

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 SetServer 

func SetServer(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 func(*Server)

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 WithAddr 

func WithAddr(addr string) Option

WithAddr sets the corresponding server field

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 WithHostname 

func WithHostname(v string) Option

WithHostname sets the server hostname

func WithMiddleware 

func WithMiddleware(m MiddlewareFunc) Option

WithMiddleware adds handler middleware

func WithPort 

func WithPort(v int) Option

WithPort sets the server port

func WithReadyFunc 

func WithReadyFunc(ready ReadyFunc) Option

WithReadyFunc sets a callback for when the server is listening

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 (Option) Execute 

func (o Option) Execute(c 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

ComposeReadyFunc provides a ReadyFunc that combines a sequence

type Server 

type Server struct {
	*http.Server

	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)

AddMiddleware appends additional middleware to the server

func (*Server) Execute 

func (s *Server) Execute(c context.Context) error

func (*Server) Handle 

func (s *Server) Handle(path string, h http.Handler) 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) 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) 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) SetNoAccessLog 

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

func (*Server) SetNoDirectoryListings 

func (s *Server) SetNoDirectoryListings(v bool) 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) SetServer 

func (s *Server) SetServer(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

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.