Documentation
¶
Overview ¶
Package httpserver provides a flexible H1/H2C/H2/H3 server
Index ¶
- Constants
- type BindingConfig
- type Config
- type Server
- func (srv *Server) Cancel()
- func (srv *Server) Cancelled() bool
- func (srv *Server) Close() error
- func (srv *Server) Err() error
- func (srv *Server) Fail(err error)
- func (srv *Server) Handle(pattern string, handler http.Handler)
- func (srv *Server) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
- func (srv *Server) Listen() error
- func (srv *Server) ListenAndServe(h http.Handler) error
- func (srv *Server) ListenWithListener(lc bind.TCPUDPListener) error
- func (srv *Server) NewH2CHandler() http.Handler
- func (srv *Server) NewH2CServer(h http.Handler) *http.Server
- func (srv *Server) NewH2Handler() http.Handler
- func (srv *Server) NewH2Server(h http.Handler) (*http.Server, error)
- func (srv *Server) NewHTTPSRedirectHandler() http.Handler
- func (srv *Server) NewHTTPServer() *http.Server
- func (*Server) NewQuicConfig() *quic.Config
- func (srv *Server) NewTLSConfig() *tls.Config
- func (srv *Server) OnCancel(fn func(error))
- func (srv *Server) QuicHeadersMiddleware(next http.Handler) http.Handler
- func (srv *Server) Serve(h http.Handler) error
- func (srv *Server) SetQuicHeaders(hdr http.Header) error
- func (srv *Server) Wait() error
- func (srv *Server) WithListeners(sl *ServerListeners) error
- type ServerListeners
Constants ¶
const ( // AltSvcHeader is the header label used to advertise // Quic support AltSvcHeader = "Alt-Svc" // GrabQuicHeadersRetry indicates how long we wait to // grab the generated Alt-Svc header GrabQuicHeadersRetry = 10 * time.Millisecond )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BindingConfig ¶
type BindingConfig struct {
Interfaces []string
Addresses []string
Port uint16
PortStrict bool
PortAttempts int
// PortInsecure specifies the port used to listen plain HTTP
// if AllowInsecure is enabled
PortInsecure uint16
// AllowInsecure tells if plain HTTP 1.1 or H2C is allowed
AllowInsecure bool
// KeepAlive specifies the KeepAlive value to use on net.ListenConfig
// when calling Listen()
KeepAlive time.Duration
}
BindingConfig includes the information needed to listen TCP/UDP ports
type Config ¶
type Config struct {
// Logger is an optional slog.Logger used to debug the Server
Logger slog.Logger
// Context is the parent context.Context of the cancellable we use
// with the workers
Context context.Context
// Bind defines the ports and addresses we listen
Bind BindingConfig
// ReadTimeout is the maximum duration for reading the entire
// request, including the body. A zero or negative value means
// there will be no timeout.
//
// Because ReadTimeout does not let Handlers make per-request
// decisions on each request body's acceptable deadline or
// upload rate, most users will prefer to use
// ReadHeaderTimeout. It is valid to use them both.
ReadTimeout time.Duration
// ReadHeaderTimeout is the amount of time allowed to read
// request headers. The connection's read deadline is reset
// after reading the headers and the Handler can decide what
// is considered too slow for the body. If ReadHeaderTimeout
// is zero, the value of ReadTimeout is used. If both are
// zero, there is no timeout.
ReadHeaderTimeout time.Duration
// 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 time.Duration
// IdleTimeout is the maximum amount of time to wait for the
// next request when keep-alive is enabled. If IdleTimeout
// is zero, the value of ReadTimeout is used. If both are
// zero, there is no timeout.
IdleTimeout time.Duration
// MaxHeaderBytes controls the maximum number of bytes the
// server will read parsing the request header's keys and
// values, including the request line. It does not limit the
// size of the request body.
// If zero, http.DefaultMaxHeaderBytes is used.
MaxHeaderBytes int
// MaxRecvBufferSize is the buffer size we will attempt to set to
// UDP listeners
// If zero, bind.DefaultMaxRecvBufferSize is used.
MaxRecvBufferSize int
// TLSConfig optionally serves as starting point allowing the
// use to specify different constraints
TLSConfig *tls.Config
// TLS Callbacks
GetHandlerForClient func(*tls.ClientHelloInfo) sni.Handler
GetConfigForClient func(*tls.ClientHelloInfo) (*tls.Config, error)
GetCertificate func(*tls.ClientHelloInfo) (*tls.Certificate, error)
GetRootCAs func() *x509.CertPool
GetClientCAs func() *x509.CertPool
// Optional resolver for the ACME-HTTP-01 challenge
AcmeHTTP01 acme.HTTP01Resolver
// Handler is the HTTPS application we serve on Bind.Port via H1/H2/H3 mapped
// to `/` on our internal router. This internal router also takes
// responsibility of handling the ACME-HTTP-01 challenge and other special cases
// defined using the Handle() and HandleFunc() methods on the created Server
Handler http.Handler
// HandleInsecure tells us to use the same handler via H1/H2C on Bind.PortInsecure.
// Otherwise the insecure port, if allowed, will only redirect to https and optionally
// handle the ACME-HTTP-01 challenge using the resolver specified on the AcmeHTTP01
// field
HandleInsecure bool
}
Config describes how Server needs to be set up
func (*Config) SetDefaults ¶
SetDefaults attempts to fill any configuration gap
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is an instance of our H1/H2C/H2/H3 server
func (*Server) Cancel ¶
func (srv *Server) Cancel()
Cancel initiates a cancellation if it wasn't cancelled already
func (*Server) Close ¶
Close tries to initiate a cancellation, and returns the reason if it was already cancelled
func (*Server) Handle ¶
Handle registers the handler for the given pattern. If a handler already exists for pattern, Handle panics.
func (*Server) HandleFunc ¶
HandleFunc registers the handler function for the given pattern. If a handler already exists for pattern, Handle panics.
func (*Server) ListenAndServe ¶
ListenAndServe attempts to listen all the necessary port and then start the service as Serve does
func (*Server) ListenWithListener ¶
func (srv *Server) ListenWithListener(lc bind.TCPUDPListener) error
ListenWithListener uses a given TCPUDPListener to listen to the addresses specified on the Config
func (*Server) NewH2CHandler ¶
NewH2CHandler returns the http.Handler to use on the H2C server
func (*Server) NewH2CServer ¶
NewH2CServer creates a new H2C capable http.Server
func (*Server) NewH2Handler ¶
NewH2Handler returns the http.Handler to use on the H2 server
func (*Server) NewH2Server ¶
NewH2Server creates a new HTTP/2 capable http.Server
func (*Server) NewHTTPSRedirectHandler ¶
NewHTTPSRedirectHandler creates a new handler that redirects everything to https, optionally handing ACME-HTTP-01
func (*Server) NewHTTPServer ¶
NewHTTPServer creates a new http.Server
func (*Server) NewQuicConfig ¶
func (*Server) NewQuicConfig() *quic.Config
NewQuicConfig returns the quic.Config to be used on the HTTP/3 server
func (*Server) NewTLSConfig ¶
NewTLSConfig returns the tls.Config to be used on the Server
func (*Server) OnCancel ¶
OnCancel specifies a function to be called when shutdown is initiated, caused by errors or by calling Cancel()/Close()
func (*Server) QuicHeadersMiddleware ¶
QuicHeadersMiddleware creates is a middleware function that injects Alt-Svc on the http.Response headers
func (*Server) Serve ¶
Serve starts running the service. if a handler wasn't set on Server.Handler, you can provide one here. if you do it in both places the underlying http.ServeMux will panic
func (*Server) SetQuicHeaders ¶
SetQuicHeaders appends Quic's Alt-Svc to the headers
func (*Server) WithListeners ¶
func (srv *Server) WithListeners(sl *ServerListeners) error
WithListeners validates and attaches provided listeners
type ServerListeners ¶
type ServerListeners struct {
Insecure []*net.TCPListener
Secure []*net.TCPListener
Quic []*net.UDPConn
}
ServerListeners is the list of all listeners on a Server
func (*ServerListeners) Close ¶
func (sl *ServerListeners) Close() error
Close closes all listeners. Errors are ignored
func (*ServerListeners) IPAddresses ¶
func (sl *ServerListeners) IPAddresses() ([]net.IP, error)
IPAddresses validates the ServerListeners and provides the list of IP Addresses as string
func (*ServerListeners) Ports ¶
func (sl *ServerListeners) Ports() (secure uint16, insecure uint16, ok bool)
Ports returns the port of the first secure listener and optionally the first insecure one
func (*ServerListeners) StringIPAddresses ¶
func (sl *ServerListeners) StringIPAddresses() ([]string, error)
StringIPAddresses validates the ServerListeners and provides the list of IP Addresses as string
Source Files