Documentation
¶
Overview ¶
Package server provides the Echo v5 lifecycle shell a service wraps its HTTP surface in: construction, start, graceful stop, and the generic request-logging middlewares.
The package is deliberately thin. It owns no routes and no middleware chain — those are the service's business. What it owns is the part every service would otherwise reimplement: binding a configured address, starting Echo in a way that unblocks on context cancellation, and shutting it down.
The dependency on Echo v5 is hard and intentional: there is no abstraction over the router. Reach the underlying instance with Echo() to register routes, middlewares, a Binder, a Validator or an error handler; pass an already-configured instance in with WithEcho.
Index ¶
Constants ¶
const DefaultGracefulTimeout = 10 * time.Second
DefaultGracefulTimeout bounds how long a shutdown waits for in-flight requests before dropping them.
Variables ¶
This section is empty.
Functions ¶
func BaseMiddlewares ¶
func BaseMiddlewares() []echo.MiddlewareFunc
BaseMiddlewares returns the minimum every server wants: panic recovery and the standard security headers.
func BodyDumpLoggingMiddleware ¶
func BodyDumpLoggingMiddleware() echo.MiddlewareFunc
BodyDumpLoggingMiddleware logs request and response bodies at debug level.
It writes bodies verbatim: passwords from a login, refresh tokens, and whatever secrets an integration endpoint accepts all land in the log in clear text. There is no field redaction. Enable it only where the logs live no longer than the debugging session — behind a dev gate, never in an environment whose logs are shipped somewhere and retained.
The response body is capped; the request body is not, and a large upload is buffered whole in memory before being logged.
func NotFoundHandler ¶
NotFoundHandler is the default handler for unmatched routes. It is exported because a service that registers its own not-found route still wants the same response shape.
func RequestLoggingMiddleware ¶
func RequestLoggingMiddleware() echo.MiddlewareFunc
RequestLoggingMiddleware logs one structured line per request.
The field names and the REQUEST / REQUEST_ERROR message literals are a contract: log queries and alerts are written against them, so renaming one is a breaking change for every dashboard downstream.
Types ¶
type Config ¶
type Config struct {
// Name identifies the server in log lines. A process typically runs more
// than one (a public API and an infra port), and the name is what tells
// their lifecycle messages apart.
Name string
Host string
Port int
// GracefulTimeout bounds the wait for in-flight requests during shutdown.
// Zero means DefaultGracefulTimeout.
//
// It must exceed the slowest expected in-flight request, and a service
// draining behind a load balancer should also keep its own drain window
// longer than the proxy's health-check interval — otherwise the proxy is
// still routing here when the process tears down.
GracefulTimeout time.Duration
}
Config is the bind configuration for a Server.
func (Config) BuildHostPort ¶
BuildHostPort renders the address the server binds to.
type Option ¶
type Option func(*Server)
Option configures a Server.
func WithEcho ¶
WithEcho replaces the Echo instance the server wraps. Use it when the service needs to configure Echo itself (a custom Binder, Validator or HTTPErrorHandler) before any route is registered.
func WithLogger ¶
WithLogger sets the logger Echo uses.
Echo v5 logs through *slog.Logger. A service logging through something else passes an adapter — the lifecycle lines this package writes itself go through xlog and are unaffected by this option.
func WithNotFoundHandler ¶
func WithNotFoundHandler(h echo.HandlerFunc) Option
WithNotFoundHandler overrides the handler used for unmatched routes.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is an Echo instance plus its lifecycle. Construct it with New.
func (*Server) Echo ¶
Echo returns the underlying Echo instance, so the service can register routes and middlewares.
It is meant for configuration between New and Start. Mutating the router after Start is not supported.
func (*Server) NotFoundHandlerFunc ¶
func (s *Server) NotFoundHandlerFunc() echo.HandlerFunc
NotFoundHandlerFunc returns the handler this server uses for unmatched routes — NotFoundHandler unless WithNotFoundHandler replaced it. A service registering the not-found route itself reads it from here rather than hardcoding a choice the option was meant to make.
func (*Server) Start ¶
Start begins listening and blocks until the server stops. Returns an error only if startup fails, otherwise blocks until shutdown. The provided context is used to stop blocking when canceled. Actual shutdown is performed by the Stop method.
func (*Server) Stop ¶
Stop signals the server to shut down.
It does NOT wait for in-flight requests: it cancels the context Start is blocked on and returns immediately, leaving Echo to drain in the goroutine Start launched. A caller that must not tear down its dependencies while requests are still running has to hold its own drain window — closing a database right after Stop returns can fail a request that is still being served.
Source Files