Documentation
¶
Overview ¶
Package server provides a production-ready HTTP server wrapping a rux.Router.
The Server adds sensible timeouts, graceful shutdown, lifecycle hooks, and liveness/readiness endpoints on top of the bare router. Defaults are tuned for containerized deployments; override any field before calling Run.
Index ¶
- Constants
- func MountEchoRoutes(r *rux.Router)
- type Server
- func (s *Server) Err() error
- func (s *Server) MountHealthChecks()
- func (s *Server) Run() error
- func (s *Server) SetAddr(host string, port uint)
- func (s *Server) SetHostPort(host string, port uint)
- func (s *Server) Shutdown(ctx context.Context) error
- func (s *Server) Start() error
- func (s *Server) Stop()
- func (s *Server) String() string
Constants ¶
const ( DefaultAddr = ":8080" DefaultReadHeaderTimeout = 2 * time.Second DefaultReadTimeout = 10 * time.Second DefaultWriteTimeout = 30 * time.Second DefaultIdleTimeout = 120 * time.Second DefaultMaxHeaderBytes = 1 << 20 // 1 MiB DefaultShutdownTimeout = 25 * time.Second DefaultDrainDelay = 5 * time.Second )
Default configuration values applied by New. All durations are conservative enough to defend against common slow-attacks while remaining friendly to typical request/response cycles.
Variables ¶
This section is empty.
Functions ¶
func MountEchoRoutes ¶
MountEchoRoutes attaches all httpbin-style endpoints to an existing router. Use this when embedding echo functionality into a larger app (e.g. as a debug helper under /debug prefix via Router.Group).
Types ¶
type Server ¶
type Server struct {
*rux.Router
// Addr is the listen address ("host:port" or ":port"). Defaults to ":8080".
Addr string
// Host is kept for backward compatibility; New does not populate it.
// SetHostPort writes both Host/Port and Addr.
Host string
Port uint
// Optional TLS. If both files are set, Start uses ListenAndServeTLS.
TLSCertFile string
TLSKeyFile string
// HTTP server timeouts. Zero means "use net/http default" (NOT recommended).
ReadHeaderTimeout time.Duration // default: 2s (slowloris defense)
ReadTimeout time.Duration // default: 10s
WriteTimeout time.Duration // default: 30s
IdleTimeout time.Duration // default: 120s
MaxHeaderBytes int // default: 1 << 20 (1 MiB)
// ShutdownTimeout bounds how long Shutdown waits for in-flight requests.
ShutdownTimeout time.Duration // default: 25s
// DrainDelay is how long after receiving a stop signal Run keeps serving
// before calling Shutdown. During drain, /readyz reports 503 so the
// upstream LB can drain traffic. Set to 0 to skip drain.
DrainDelay time.Duration // default: 5s
// StopSignals received by Run trigger graceful shutdown.
StopSignals []os.Signal // default: SIGINT, SIGTERM
// Lifecycle hooks. Hooks of the same kind run in slice order.
// PreStart errors abort startup; other hook errors are logged.
PreStart []func(ctx context.Context) error
PostStart []func(ctx context.Context) error
PreShutdown []func(ctx context.Context) error
PostShutdown []func(ctx context.Context) error
// ReadyChecks evaluate /readyz. /readyz returns 503 if any returns error
// OR if the server is draining. Liveness (/healthz) is independent — it's
// 200 as long as the process is alive. Use MountHealthChecks() to attach.
ReadyChecks []func(ctx context.Context) error
// Logger receives lifecycle and error messages. Defaults to log.Printf.
Logger func(format string, args ...any)
// contains filtered or unexported fields
}
Server is a production-ready HTTP server wrapping a rux.Router. Defaults are sane for containerized deployments; override fields before Run().
func New ¶
New constructs a Server with sane defaults plus PanicsHandler middleware. When debugMode is true, also installs RequestLogger and enables rux.Debug.
func NewEchoServer ¶
func NewEchoServer() *Server
NewEchoServer builds a Server with httpbin-style echo endpoints pre-mounted. Use Server.Run() to start with graceful shutdown / lifecycle hooks.
func (*Server) MountHealthChecks ¶
func (s *Server) MountHealthChecks()
MountHealthChecks attaches GET /healthz (liveness) and GET /readyz (readiness) to the router. Call this before Run() — the router freezes on first request.
/healthz: always 200 "ok" if the process is alive. /readyz: 200 if ready && !draining && all ReadyChecks pass; else 503 with details.
func (*Server) Run ¶
Run is the one-shot lifecycle: PreStart → Start (background) → PostStart → wait for stop signal → PreShutdown → drain → Shutdown → PostShutdown.
Returns:
- the first PreStart error (startup aborted before listening), OR
- the Start error (if Start returned anything other than http.ErrServerClosed), OR
- the Shutdown error, OR
- nil on clean shutdown.
Hook errors after PreStart are logged but do not affect the return value.
func (*Server) SetHostPort ¶
SetHostPort is kept for backward compatibility — same as SetAddr.
func (*Server) Shutdown ¶
Shutdown gracefully stops the server, bounded by ShutdownTimeout if ctx has no deadline. Idempotent. Does NOT call any hooks; use Run() for full lifecycle.
func (*Server) Start ¶
Start begins serving in the current goroutine. Blocks until the underlying http.Server.Serve returns (typically only after Shutdown).
Returns http.ErrServerClosed on clean shutdown, or another error on failure.
Note: Start does NOT call any hooks. Use Run() for the full lifecycle.
Source Files