httpserver

Documentation

Overview

Package httpserver provides the small bits of main.go boilerplate that every Go service in the platform re-implements: a /health endpoint, a Prometheus /metrics endpoint, graceful shutdown, and a SIGINT/SIGTERM-aware context.

Index

• Constants
• func HealthHandler() http.Handler
• func MetricsHandler() http.Handler
• func SignalContext() (context.Context, context.CancelFunc)
• type Option
  • func WithIdleTimeout(d time.Duration) Option
  • func WithReadHeaderTimeout(d time.Duration) Option
  • func WithReadTimeout(d time.Duration) Option
  • func WithWriteTimeout(d time.Duration) Option
• type Server
  • func NewHealthServer(addr string, opts ...Option) *Server
  • func NewMetricsServer(addr string, opts ...Option) *Server
  • func (s *Server) Addr() string
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() <-chan error

Constants

const (
	DefaultReadHeaderTimeout = 5 * time.Second
	DefaultReadTimeout       = 5 * time.Second
	DefaultWriteTimeout      = 10 * time.Second
	DefaultIdleTimeout       = 0 // 0 = use ReadTimeout (net/http default behaviour)
)

Default server timeouts applied by NewHealthServer/NewMetricsServer when no overriding option is supplied.

const DefaultShutdownTimeout = 5 * time.Second

DefaultShutdownTimeout bounds graceful shutdown when Shutdown is called without an already-deadlined context.

Functions

func HealthHandler

func HealthHandler() http.Handler

HealthHandler returns an http.Handler that responds to /health (and any other path) with 200 OK and the body "ok".

func MetricsHandler

func MetricsHandler() http.Handler

MetricsHandler returns an http.Handler serving the default Prometheus registry at /metrics.

func SignalContext

func SignalContext() (context.Context, context.CancelFunc)

SignalContext returns a context that is cancelled when the process receives SIGINT or SIGTERM. The returned cancel function should be deferred to release resources and stop intercepting signals.

Types

type Option

type Option func(*http.Server)

Option customises the underlying *http.Server before it starts. Options are applied in order, so a later option wins over an earlier one.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout overrides the server's IdleTimeout. When zero, net/http falls back to ReadTimeout.

func WithReadHeaderTimeout

func WithReadHeaderTimeout(d time.Duration) Option

WithReadHeaderTimeout overrides the server's ReadHeaderTimeout.

func WithReadTimeout

func WithReadTimeout(d time.Duration) Option

WithReadTimeout overrides the server's ReadTimeout. A zero or negative value disables the timeout (net/http semantics).

func WithWriteTimeout

func WithWriteTimeout(d time.Duration) Option

WithWriteTimeout overrides the server's WriteTimeout. A zero or negative value disables the timeout (net/http semantics).

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps an *http.Server with conservative timeouts and a graceful Shutdown helper.

func NewHealthServer

func NewHealthServer(addr string, opts ...Option) *Server

NewHealthServer builds a Server serving /health on addr (e.g. ":8080"). Optional Options override the default read/write/idle timeouts; with no options the conservative defaults are used.

func NewMetricsServer

func NewMetricsServer(addr string, opts ...Option) *Server

NewMetricsServer builds a Server serving Prometheus /metrics on addr (e.g. ":9094"). Optional Options override the default read/write/idle timeouts.

func (*Server) Addr

func (s *Server) Addr() string

Addr reports the address the server is configured to listen on.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts the server down. If ctx has no deadline, DefaultShutdownTimeout is applied.

func (*Server) Start

func (s *Server) Start() <-chan error

Start runs the server in a background goroutine. Any error other than http.ErrServerClosed is delivered on the returned channel; the channel is closed after the server exits so callers can also use it to detect shutdown.