Documentation
¶
Overview ¶
Package http provides an HTTP server implementation. It provides an HTTP1, HTTP2, and HTTP3 server, the first two enabled by default.
One server contains multiple entrypoints, with one entrypoint being one address to listen on. Each entrypoint with start its own HTTP2 server, and optionally also an HTTP3 server. Each entrypoint can be customized individually, but default options are provided, and can be tweaked.
The architecture is based on the Traefik server implementation.
Index ¶
- Constants
- Variables
- func New(serviceName string, serviceVersion string, epName string, acfg any, ...) (server.Entrypoint, error)
- func NewGRPCHandler[Tin any, Tout any](srv *Server, fHandler func(context.Context, *Tin) (*Tout, error), ...) http.HandlerFunc
- func Provide(serviceName string, serviceVersion string, epName string, ...) (server.Entrypoint, error)
- func WithAddress(addr string) server.Option
- func WithAllowH2C() server.Option
- func WithDisableHTTP2() server.Option
- func WithGzip() server.Option
- func WithHTTP3() server.Option
- func WithHandlers(h ...server.RegistrationFunc) server.Option
- func WithIdleTimeout(timeout time.Duration) server.Option
- func WithInsecure() server.Option
- func WithLogLevel(level string) server.Option
- func WithLogPlugin(plugin string) server.Option
- func WithMaxConcurrentStreams(value int) server.Option
- func WithNetwork(network string) server.Option
- func WithReadTimeout(timeout time.Duration) server.Option
- func WithTLS(config *tls.Config) server.Option
- func WithWriteTimeout(timeout time.Duration) server.Option
- func WriteError(w http.ResponseWriter, err error)
- type Config
- type Router
- type Server
- func (s *Server) AddHandler(handler server.RegistrationFunc)
- func (s *Server) Address() string
- func (s *Server) Config() Config
- func (s *Server) Enabled() bool
- func (s *Server) Name() string
- func (s *Server) Network() string
- func (s *Server) Register(register server.RegistrationFunc)
- func (s *Server) Router() *Router
- func (s *Server) ServeHTTP(resp http.ResponseWriter, req *http.Request)
- func (s *Server) Start(ctx context.Context) error
- func (s *Server) Stop(ctx context.Context) error
- func (s *Server) String() string
- func (s *Server) Transport() string
- func (s *Server) Type() string
Constants ¶
const ( // DefaultNetwork to use for new HTTP servers. DefaultNetwork = "tcp" // DefaultAddress to use for new HTTP servers. DefaultAddress = ":0" // DefaultInsecure will create an HTTP server without TLS, for insecure connections. // Note: as a result you can only make insecure HTTP requests, and no HTTP2 // unless you set WithH2C. // // WARNING: don't use this in production, unless you really know what you are // doing. this will result in unencrypted traffic. Really, it is even advised // against using this in testing environments. DefaultInsecure = false // DefaultAllowH2C allows insecure, unencrypted traffic to HTTP2 servers. // Don't use this, see the notes at DefaultInsecure for more details. DefaultAllowH2C = false // DefaultMaxConcurrentStreams for HTTP2. DefaultMaxConcurrentStreams = 512 // DefaultHTTP2 dicates whether to also allow HTTP/2 and HTTP/3 connections. DefaultHTTP2 = true // DefaultHTTP3 dicates whether to also start an HTTP/3.0 server. DefaultHTTP3 = false // DefaultReadTimeout see net/http pkg for more details. DefaultReadTimeout = 5 * time.Second // DefaultWriteTimeout see net/http pkg for more details. DefaultWriteTimeout = 5 * time.Second // DefaultIdleTimeout see net/http pkg for more details. DefaultIdleTimeout = 5 * time.Second // DefaultEnableGzip enables gzip response compression server wide onall responses. // Only use this if your messages are sufficiently large. For small messages // the compute overhead is not worth the reduction in transport time. // // Alternatively, you can send a gzip compressed request, and the server // will send back a gzip compressed respponse. DefaultEnableGzip = false // DefaultConfigSection is the section key used in config files used to // configure the server options. DefaultConfigSection = Plugin // DefaultMaxHeaderBytes is the maximum size to parse from a client's // HTTP request headers. DefaultMaxHeaderBytes = 1024 * 64 )
const Plugin = "http"
Plugin is the plugin name.
Variables ¶
var ( // ErrContentTypeNotSupported is returned when there is no matching codec. ErrContentTypeNotSupported = errors.New("content type not supported") ErrInvalidConfigType = errors.New("http server: invalid config type provided, not of type http.Config") )
Errors.
var ( ErrRouterHandlerInterface = errors.New("router does not implement http.Handler interface") ErrNoTLS = errors.New("no TLS config provided") )
Errors.
var (
ErrNoMatchingCodecs = errors.New("no matching codecs found, did you register the codec plugins?")
)
Errors.
var (
ErrNoTLSConfig = errors.New("no tls config")
)
Errors returned by the HTTP3 server.
var (
ErrNotHTTPServer = errors.New("server provider is not of type *http.Server")
)
Errors.
Functions ¶
func New ¶
func New( serviceName string, serviceVersion string, epName string, acfg any, logger log.Logger, reg registry.Type, ) (server.Entrypoint, error)
New creates a http server by options.
func NewGRPCHandler ¶
func NewGRPCHandler[Tin any, Tout any]( srv *Server, fHandler func(context.Context, *Tin) (*Tout, error), service string, method string, ) http.HandlerFunc
NewGRPCHandler will wrap a gRPC function with a HTTP handler.
func Provide ¶
func Provide( serviceName string, serviceVersion string, epName string, configData map[string]any, logger log.Logger, reg registry.Type, opts ...server.Option, ) (server.Entrypoint, error)
Provide creates a new entrypoint for a single address. You can create multiple entrypoints for multiple addresses and ports. One entrypoint can serve a HTTP1, HTTP2 and HTTP3 server. If you enable HTTP3 it will listen on both TCP and UDP on the same port.
func WithAddress ¶
WithAddress specifies the address to listen on. If you want to listen on all interfaces use the format ":8080" If you want to listen on a specific interface/address use the full IP.
func WithAllowH2C ¶
WithAllowH2C will allow H2C connections on the entrypoint. H2C is HTTP2 without TLS. It is not recommended to turn this on.
func WithDisableHTTP2 ¶
WithDisableHTTP2 will prevent the creation of an HTTP2 server on the entrypoint.
func WithGzip ¶
WithGzip enables gzip response compression server wide onall responses. Only use this if your messages are sufficiently large. For small messages the compute overhead is not worth the reduction in transport time.
Alternatively, you can send a gzip compressed request, and the server will send back a gzip compressed respponse.
func WithHandlers ¶
func WithHandlers(h ...server.RegistrationFunc) server.Option
WithHandlers adds custom handlers.
func WithIdleTimeout ¶
WithIdleTimeout is the maximum amount of time to wait for the next request when keep-alives are enabled. If IdleTimeout is zero, the value of ReadTimeout is used. If both are zero, there is no timeout.
func WithInsecure ¶
WithInsecure will create the entrypoint without using TLS. Note: as a result you can only make insecure HTTP requests, and no HTTP2 unless you set WithH2C.
WARNING: don't use this in production, unless you really know what you are doing. this will result in unencrypted traffic. Really, it is even advised against using this in testing environments.
func WithLogLevel ¶
WithLogLevel changes the log level from the inherited logger.
func WithLogPlugin ¶
WithLogPlugin changes the log level from the inherited logger.
func WithMaxConcurrentStreams ¶
WithMaxConcurrentStreams sets the concurrent streams limit for HTTP2.
func WithNetwork ¶ added in v0.2.0
WithNetwork specifies the network to listen on.
func WithReadTimeout ¶
WithReadTimeout sets the maximum duration for reading the entire request, including the body. A zero or negative value means there will be no timeout.
func WithWriteTimeout ¶
WithWriteTimeout sets the maximum duration before timing out writes of the response. It is reset whenever a new request's header is read. Like ReadTimeout, it does not let Handlers make decisions on a per-request basis. A zero or negative value means there will be no timeout.
func WriteError ¶
func WriteError(w http.ResponseWriter, err error)
WriteError returns an error response to the HTTP request.
Types ¶
type Config ¶
type Config struct { server.EntrypointConfig `yaml:",inline"` // Network to listen on. // Either 'tcp' or 'unix'. // Defaults to 'tcp'. Network string `json:"network" yaml:"network"` // Address to listen on. // If no IP is provided, an interface will be selected automatically. Private // interfaces are preferred, if none are found a public interface will be used. // // If no port is provided, a random port will be selected. To listen on a // specific interface, but with a random port, you can use '<IP>:0'. // // If network is "unix", the address is the path to the unix socket. Address string `json:"address" yaml:"address"` // Insecure will create an HTTP server without TLS, for insecure connections. // Note: as a result you can only make insecure HTTP1 requests, no HTTP2 // unless you set WithH2C. // // WARNING: don't use this in production, unless you really know what you are // doing. this will result in unencrypted traffic. Really, it is even advised // against using this in testing environments. Insecure bool `json:"insecure" yaml:"insecure"` // TLS config, if none is provided a self-signed certificates will be generated. // // You can load a tls config from yaml/json with the following options: // // “`yaml // rootCAFiles: // - xxx // clientCAFiles: // - xxx // clientAuth: "none" | "request" | "require" | "verify" | "require+verify" // certificates: // - certFile: xxx // keyFile: xxx // “` TLS *mtls.Config `json:"tls,omitempty" yaml:"tls,omitempty"` // H2C allows h2c connections; HTTP2 without TLS. H2C bool `json:"h2c" yaml:"h2c"` // HTTP2 dicates whether to also allow HTTP/2 connections. Defaults to true. HTTP2 bool `json:"http2" yaml:"http2"` // HTTP3 dicates whether to also start an HTTP/3.0 server. Defaults to false. HTTP3 bool `json:"http3" yaml:"http3"` // Gzip enables gzip response compression server wide onall responses. // Only use this if your messages are sufficiently large. For small messages // the compute overhead is not worth the reduction in transport time. // // Alternatively, you can send a gzip compressed request, and the server // will send back a gzip compressed respponse. Gzip bool `json:"gzip" yaml:"gzip"` // MaxConcurrentStreams for HTTP2. MaxConcurrentStreams int `json:"maxConcurrentStreams" yaml:"maxConcurrentStreams"` // MaxHeaderBytes is the maximum size to parse from a client's // HTTP request headers. MaxHeaderBytes int `json:"maxHeaderBytes" yaml:"maxHeaderBytes"` // ReadTimeout is the maximum duration for reading the entire // request, including the body. A zero or negative value means // there will be no timeout. ReadTimeout config.Duration `json:"readTimeout" yaml:"readTimeout"` // WriteTimeout is the maximum duration before timing out // writes of the response. It is reset whenever a new // request's header is read. Like ReadTimeout, it does not // let Handlers make decisions on a per-request basis. // A zero or negative value means there will be no timeout. WriteTimeout config.Duration `json:"writeTimeout" yaml:"writeTimeout"` // IdleTimeout is the maximum amount of time to wait for the // next request when keep-alives are enabled. If IdleTimeout // is zero, the value of ReadTimeout is used. If both are // zero, there is no timeout. IdleTimeout config.Duration `json:"idleTimeout" yaml:"idleTimeout"` // Logger allows you to dynamically change the log level and plugin for a // specific entrypoint. Logger log.Config `json:"logger" yaml:"logger"` }
Config provides options to the entrypoint.
type Router ¶ added in v0.2.0
type Router struct {
// contains filtered or unexported fields
}
Router is a router based on httprouter.
func (*Router) Post ¶ added in v0.2.0
func (r *Router) Post(path string, handler http.HandlerFunc)
Post registers a new route for POST requests.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server represents a listener on one address. You can create multiple entrypoints for multiple addresses and ports. This is e.g. useful if you want to listen on multiple interfaces, or multiple ports in parallel, even with the same handler.
func (*Server) AddHandler ¶ added in v0.2.0
func (s *Server) AddHandler(handler server.RegistrationFunc)
AddHandler adds a handler for later registration.
func (*Server) Network ¶ added in v0.2.0
Network returns the network the entrypoint is listening on.
func (*Server) Register ¶
func (s *Server) Register(register server.RegistrationFunc)
Register executes a registration function on the entrypoint.
func (*Server) Router ¶
Router returns the router used by the HTTP server. You can use this to register extra handlers, or mount additional routers.
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
Package headers contains common headers
|
Package headers contains common headers |
tests
|
|
handler
Package handler provdes a test handler.
|
Package handler provdes a test handler. |
proto
Package proto ...
|
Package proto ... |
util/http
Package http provides testing utilities.
|
Package http provides testing utilities. |
utils
|
|
header
Package header implements header manipulation utilities
|
Package header implements header manipulation utilities |
ip
Package ip provides validation and parsing utilities.
|
Package ip provides validation and parsing utilities. |
tcp
Package tcp offers tcp utilities.
|
Package tcp offers tcp utilities. |
tls
Package tls provides a function to create a self signed certificate.
|
Package tls provides a function to create a self signed certificate. |
udp
Package udp offers UDP utilities.
|
Package udp offers UDP utilities. |