health: add documentation

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)