From a37559b93e189fdc245c94673943dd544b50f97f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ask=20Bj=C3=B8rn=20Hansen?= Date: Fri, 6 Jun 2025 19:16:14 -0700 Subject: [PATCH] health: add documentation --- health/health_server.go | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/health/health_server.go b/health/health_server.go index 9603542..f1cf22c 100644 --- a/health/health_server.go +++ b/health/health_server.go @@ -1,3 +1,9 @@ +// Package health provides a standalone HTTP server for health checks. +// +// This package implements a simple health check server that can be used +// to expose health status endpoints for monitoring and load balancing. +// It supports custom health check handlers and provides structured logging +// with graceful shutdown capabilities. package health import ( @@ -11,11 +17,19 @@ import ( "golang.org/x/sync/errgroup" ) +// Server is a standalone HTTP server dedicated to health checks. +// It runs separately from the main application server to ensure health +// checks remain available even if the main server is experiencing issues. +// +// The server includes built-in timeouts, graceful shutdown, and structured +// logging for monitoring and debugging health check behavior. type Server struct { log *slog.Logger healthFn http.HandlerFunc } +// NewServer creates a new health check server with the specified health handler. +// If healthFn is nil, a default handler that returns HTTP 200 "ok" is used. func NewServer(healthFn http.HandlerFunc) *Server { if healthFn == nil { healthFn = basicHealth @@ -27,10 +41,13 @@ func NewServer(healthFn http.HandlerFunc) *Server { return srv } +// SetLogger replaces the default logger with a custom one. func (srv *Server) SetLogger(log *slog.Logger) { srv.log = log } +// Listen starts the health server on the specified port and blocks until ctx is cancelled. +// The server exposes the health handler at "/__health" with graceful shutdown support. func (srv *Server) Listen(ctx context.Context, port int) error { srv.log.Info("starting health listener", "port", port) @@ -72,8 +89,7 @@ func (srv *Server) Listen(ctx context.Context, port int) error { return g.Wait() } -// HealthCheckListener runs simple http server on the specified port for -// health check probes +// HealthCheckListener runs a simple HTTP server on the specified port for health check probes. func HealthCheckListener(ctx context.Context, port int, log *slog.Logger) error { srv := NewServer(nil) srv.SetLogger(log)