feat: add /health endpoint with Docker HEALTHCHECK

Add an HTTP health server that reports upstream Modbus connectivity
status, enabling Docker to monitor container health without external
tools in the scratch-based image.

The health server listens on :8080 (configurable via HEALTH_LISTEN)
and exposes GET /health, which returns 200 when upstream is reachable
or 503 with error details when it is not. Upstream status is tracked
passively from real request results to avoid additional load on the
Modbus device.

The binary's -health flag acts as an HTTP client for the HEALTHCHECK
instruction, since scratch has no curl/wget. Bind failures on the
health port are treated as fatal to prevent Docker from killing an
otherwise-healthy container due to unreachable health checks.

Author: tma

Dockerfile

@@ -31,4 +31,9 @@ FROM scratch
 
 COPY --from=builder /app/mbproxy /mbproxy
 
+EXPOSE 8080
+
+HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=3 \
+  CMD ["/mbproxy", "-health"]
+
 ENTRYPOINT ["/mbproxy"]

cmd/mbproxy/main.go

@@ -2,17 +2,33 @@ package main
 
 import (
 	"context"
+	"flag"
+	"fmt"
 	"log/slog"
 	"os"
 	"os/signal"
 	"syscall"
+	"time"
 
 	"github.com/tma/mbproxy/internal/config"
+	"github.com/tma/mbproxy/internal/health"
 	"github.com/tma/mbproxy/internal/logging"
 	"github.com/tma/mbproxy/internal/proxy"
 )
 
 func main() {
+	healthCheck := flag.Bool("health", false, "run health check and exit")
+	flag.Parse()
+
+	if *healthCheck {
+		addr := config.GetEnv("HEALTH_LISTEN", ":8080")
+		if err := health.CheckHealth(addr); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+		return
+	}
+
 	cfg, err := config.Load()
 	if err != nil {
 		slog.Error("failed to load configuration", "error", err)
@@ -34,6 +50,19 @@ func main() {
 		os.Exit(1)
 	}
 
+	// Start health server
+	hs := health.NewServer(cfg.HealthListen, p, logger)
+	hsLn, err := hs.Listen()
+	if err != nil {
+		logger.Error("failed to start health server", "error", err)
+		os.Exit(1)
+	}
+	go func() {
+		if err := hs.Serve(hsLn); err != nil {
+			logger.Error("health server error", "error", err)
+		}
+	}()
+
 	// Start proxy in background
 	errCh := make(chan error, 1)
 	go func() {
@@ -53,6 +82,13 @@ func main() {
 
 	// Graceful shutdown
 	cancel()
+
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer shutdownCancel()
+	if err := hs.Shutdown(shutdownCtx); err != nil {
+		logger.Error("health server shutdown error", "error", err)
+	}
+
 	if err := p.Shutdown(cfg.ShutdownTimeout); err != nil {
 		logger.Error("shutdown error", "error", err)
 		os.Exit(1)

internal/config/config.go

@@ -30,13 +30,14 @@ type Config struct {
 	RequestDelay    time.Duration
 	ConnectDelay    time.Duration
 	ShutdownTimeout time.Duration
+	HealthListen    string
 	LogLevel        string
 }
 
 // Load reads configuration from environment variables.
 func Load() (*Config, error) {
 	cfg := &Config{
-		Listen:          getEnv("MODBUS_LISTEN", ":5502"),
+		Listen:          GetEnv("MODBUS_LISTEN", ":5502"),
 		Upstream:        os.Getenv("MODBUS_UPSTREAM"),
 		DefaultSlaveID:  1,
 		CacheTTL:        10 * time.Second,
@@ -46,7 +47,8 @@ func Load() (*Config, error) {
 		RequestDelay:    0,
 		ConnectDelay:    0,
 		ShutdownTimeout: 30 * time.Second,
-		LogLevel:        getEnv("LOG_LEVEL", "INFO"),
+		HealthListen:    GetEnv("HEALTH_LISTEN", ":8080"),
+		LogLevel:        GetEnv("LOG_LEVEL", "INFO"),
 	}
 
 	if cfg.Upstream == "" {
@@ -129,7 +131,9 @@ func Load() (*Config, error) {
 	return cfg, nil
 }
 
-func getEnv(key, defaultValue string) string {
+// GetEnv returns the value of the environment variable named by key,
+// or defaultValue if the variable is not set.
+func GetEnv(key, defaultValue string) string {
 	if v := os.Getenv(key); v != "" {
 		return v
 	}

internal/config/config_test.go

@@ -19,6 +19,7 @@ func TestLoad_Defaults(t *testing.T) {
 	os.Unsetenv("MODBUS_READONLY")
 	os.Unsetenv("MODBUS_TIMEOUT")
 	os.Unsetenv("MODBUS_SHUTDOWN_TIMEOUT")
+	os.Unsetenv("HEALTH_LISTEN")
 	os.Unsetenv("LOG_LEVEL")
 
 	cfg, err := Load()
@@ -56,6 +57,9 @@ func TestLoad_Defaults(t *testing.T) {
 	if cfg.ShutdownTimeout != 30*time.Second {
 		t.Errorf("expected 30s shutdown timeout, got %v", cfg.ShutdownTimeout)
 	}
+	if cfg.HealthListen != ":8080" {
+		t.Errorf("expected :8080, got %s", cfg.HealthListen)
+	}
 	if cfg.LogLevel != "INFO" {
 		t.Errorf("expected INFO log level, got %s", cfg.LogLevel)
 	}
@@ -81,6 +85,7 @@ func TestLoad_CustomValues(t *testing.T) {
 	os.Setenv("MODBUS_REQUEST_DELAY", "100ms")
 	os.Setenv("MODBUS_CONNECT_DELAY", "200ms")
 	os.Setenv("MODBUS_SHUTDOWN_TIMEOUT", "60s")
+	os.Setenv("HEALTH_LISTEN", ":9090")
 	os.Setenv("LOG_LEVEL", "DEBUG")
 
 	defer func() {
@@ -94,6 +99,7 @@ func TestLoad_CustomValues(t *testing.T) {
 		os.Unsetenv("MODBUS_REQUEST_DELAY")
 		os.Unsetenv("MODBUS_CONNECT_DELAY")
 		os.Unsetenv("MODBUS_SHUTDOWN_TIMEOUT")
+		os.Unsetenv("HEALTH_LISTEN")
 		os.Unsetenv("LOG_LEVEL")
 	}()
 
@@ -129,6 +135,9 @@ func TestLoad_CustomValues(t *testing.T) {
 	if cfg.ShutdownTimeout != 60*time.Second {
 		t.Errorf("expected 60s shutdown timeout, got %v", cfg.ShutdownTimeout)
 	}
+	if cfg.HealthListen != ":9090" {
+		t.Errorf("expected :9090, got %s", cfg.HealthListen)
+	}
 	if cfg.LogLevel != "DEBUG" {
 		t.Errorf("expected DEBUG log level, got %s", cfg.LogLevel)
 	}

internal/health/health.go

@@ -0,0 +1,133 @@
+// Package health provides an HTTP health check server.
+package health
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net"
+	"net/http"
+	"time"
+)
+
+// Checker reports whether a component is healthy.
+type Checker interface {
+	Healthy() error
+}
+
+// Response is the JSON body returned by the health endpoint.
+type Response struct {
+	Status string `json:"status"`
+	Error  string `json:"error,omitempty"`
+}
+
+// Server is a lightweight HTTP server that exposes a /health endpoint.
+type Server struct {
+	httpServer *http.Server
+	logger     *slog.Logger
+}
+
+// NewServer creates a new health check server.
+// The checker is called on each request to determine upstream health.
+func NewServer(addr string, checker Checker, logger *slog.Logger) *Server {
+	mux := http.NewServeMux()
+	s := &Server{
+		httpServer: &http.Server{
+			Addr:              addr,
+			Handler:           mux,
+			ReadHeaderTimeout: 5 * time.Second,
+		},
+		logger: logger,
+	}
+
+	mux.HandleFunc("/health", s.handleHealth(checker))
+
+	return s
+}
+
+func (s *Server) handleHealth(checker Checker) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+
+		if err := checker.Healthy(); err != nil {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			resp := Response{Status: "unhealthy", Error: err.Error()}
+			if encErr := json.NewEncoder(w).Encode(resp); encErr != nil {
+				s.logger.Error("failed to encode health response", "error", encErr)
+			}
+			return
+		}
+
+		w.WriteHeader(http.StatusOK)
+		resp := Response{Status: "ok"}
+		if err := json.NewEncoder(w).Encode(resp); err != nil {
+			s.logger.Error("failed to encode health response", "error", err)
+		}
+	}
+}
+
+// ListenAndServe starts the health server. It blocks until the server
+// is shut down or encounters a fatal error. Use Listen + Serve to
+// separate binding from serving, which allows detecting bind errors early.
+func (s *Server) ListenAndServe() error {
+	s.logger.Info("health server listening", "addr", s.httpServer.Addr)
+	err := s.httpServer.ListenAndServe()
+	if err == http.ErrServerClosed {
+		return nil
+	}
+	return err
+}
+
+// Listen binds the server to its configured address. Call Serve to
+// start accepting connections after Listen returns successfully.
+func (s *Server) Listen() (net.Listener, error) {
+	ln, err := net.Listen("tcp", s.httpServer.Addr)
+	if err != nil {
+		return nil, err
+	}
+	s.logger.Info("health server listening", "addr", ln.Addr())
+	return ln, nil
+}
+
+// Serve accepts connections on the given listener. It blocks until the
+// server is shut down or encounters a fatal error.
+func (s *Server) Serve(ln net.Listener) error {
+	err := s.httpServer.Serve(ln)
+	if err == http.ErrServerClosed {
+		return nil
+	}
+	return err
+}
+
+// Shutdown gracefully shuts down the health server.
+func (s *Server) Shutdown(ctx context.Context) error {
+	return s.httpServer.Shutdown(ctx)
+}
+
+// CheckHealth performs an HTTP health check against the given address.
+// It returns nil if the endpoint responds with 200 OK.
+func CheckHealth(addr string) error {
+	// Resolve the address so we can build a proper URL.
+	host, port, err := net.SplitHostPort(addr)
+	if err != nil {
+		return fmt.Errorf("invalid address %q: %w", addr, err)
+	}
+	if host == "" {
+		host = "localhost"
+	}
+
+	url := fmt.Sprintf("http://%s:%s/health", host, port)
+
+	client := &http.Client{Timeout: 3 * time.Second}
+	resp, err := client.Get(url)
+	if err != nil {
+		return fmt.Errorf("health check request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("health check returned status %d", resp.StatusCode)
+	}
+	return nil
+}