Documentation
¶
Overview ¶
Package server provides HTTP server implementation with production features.
This package implements a production-ready HTTP server with built-in security features, graceful shutdown, panic recovery, and comprehensive event emission for monitoring and observability.
Index ¶
- Constants
- func DefaultHTTPServer(handler *Handler, port int, endpoints []endpoint.Endpoint) *http.Server
- func QueryMap(r *http.Request) map[string]any
- func RouteParams(r *http.Request) map[string]string
- func StartServer(handler *Handler, server HTTPServer, shutdownTimeout *time.Duration) error
- type HTTPServer
- type Handler
- type HandlerOption
- func WithBodyLimit(limit int64) HandlerOption
- func WithEventEmitter(em event.EventEmitter) HandlerOption
- func WithNotFound(nf http.Handler) HandlerOption
- func WithQueryDecoder(d querydec.Decoder) HandlerOption
- func WithRecoverer(wrap func(http.Handler) http.Handler) HandlerOption
- func WithRouter(r router.Router) HandlerOption
Constants ¶
const ( EventRegisterURL event.EventType = "event_register_url" EventNotFound event.EventType = "event_not_found" EventMethodNotAllowed event.EventType = "event_method_not_allowed" EventPanic event.EventType = "event_panic" EventStart event.EventType = "event_start" EventErrorStart event.EventType = "event_error_start" EventShutDownStarted event.EventType = "event_shutdown_started" EventShutDown event.EventType = "event_shutdown" EventShutDownError event.EventType = "event_shutdown_error" )
Define events.
Variables ¶
This section is empty.
Functions ¶
func DefaultHTTPServer ¶
DefaultHTTPServer returns the default HTTP server implementation. It sets default request read and write timeouts of 10 seconds, idle timeout of 60 seconds, and a max header size of 64KB.
Parameters:
- handler: HTTP server handler.
- port: Port for the HTTP server.
- endpoints: Endpoints to register.
Returns:
- *http.Server: A configured http.Server instance.
func RouteParams ¶ added in v1.0.0
RouteParams extracts the route parameters from the request context.
func StartServer ¶
func StartServer( handler *Handler, server HTTPServer, shutdownTimeout *time.Duration, ) error
StartServer sets up an HTTP server with the specified port and endpoints, using optional event emitter. The handler listens for OS interrupt signals to gracefully shut down. If no shutdown timeout is provided, 60 seconds will be used by default.
Parameters:
- handler: HTTP server handler.
- server: Server implementation to use.
- shutdownTimeout: Optional shutdown timeout.
Returns:
- error: An error if starting the server fails.
Types ¶
type HTTPServer ¶
type HTTPServer interface {
ListenAndServe() error // Start the server.
Shutdown(ctx context.Context) error // Shut down the server.
}
HTTPServer represents an HTTP server.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler represents an HTTP server handler.
func NewHandler ¶
func NewHandler( emitter event.EventEmitter, opts ...HandlerOption, ) *Handler
NewHandler creates a new HTTPServer. If an event emitter is provided, it will be used to emit events. Otherwise, logging will be used. If no logger is provided, log.Default() will be used. If no event emitter is provided, no events will be emitted or logged.
Parameters:
- emitter: Event emitter logger.
- opts: Optional handler options.
Returns:
- *Handler: A new Handler instance.
func (*Handler) Register ¶ added in v1.0.0
Register registers endpoints with the handler.
Parameters:
- endpoints: The endpoints to register.
Returns:
- error: An error if the endpoint registration fails.
func (*Handler) ServeHTTP ¶ added in v1.0.0
func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler.
Parameters:
- w: The response writer.
- r: The request.
Returns:
- error: An error if the request serving fails.
func (*Handler) Unregister ¶ added in v1.0.0
Unregister removes a method+path route from the router and tracking map.
Parameters:
- method: The HTTP method of the route.
- path: The path of the route.
Returns:
- error: An error if the endpoint unregistration fails.
type HandlerOption ¶ added in v1.0.0
type HandlerOption func(*Handler)
HandlerOption configures a Handler.
func WithBodyLimit ¶ added in v1.0.0
func WithBodyLimit(limit int64) HandlerOption
WithBodyLimit sets the maximum request body size in bytes.
Parameters:
- limit: The maximum request body size in bytes.
Returns:
- HandlerOption: A handler option function.
func WithEventEmitter ¶ added in v1.0.0
func WithEventEmitter(em event.EventEmitter) HandlerOption
WithEventEmitter overrides the handler event emitter.
func WithNotFound ¶ added in v1.0.0
func WithNotFound(nf http.Handler) HandlerOption
WithNotFound sets the not found handler.
Parameters:
- nf: The not found handler to use.
Returns:
- HandlerOption: A handler option function.
func WithQueryDecoder ¶ added in v1.0.0
func WithQueryDecoder(d querydec.Decoder) HandlerOption
WithQueryDecoder sets the query decoder for the handler.
Parameters:
- d: The query decoder to use.
Returns:
- HandlerOption: A handler option function.
func WithRecoverer ¶ added in v1.0.0
func WithRecoverer(wrap func(http.Handler) http.Handler) HandlerOption
WithRecoverer sets the recoverer function.
Parameters:
- wrap: The recoverer function to use.
Returns:
- HandlerOption: A handler option function.
func WithRouter ¶ added in v1.0.0
func WithRouter(r router.Router) HandlerOption
WithRouter sets the router for the handler.
Parameters:
- r: The router implementation to use.
Returns:
- HandlerOption: A handler option function.
Source Files