Skip to content

armgit / posta

Public Imported from GitHub
0

Self-hosted email delivery platform that enables applications to send emails via HTTP APIs while handling SMTP delivery, templates, storage, security, and analytics. Fully self-hostable alternative to services like SendGrid or Mailgun.

feat(worker): expose health, readiness and metrics endpoints

Jonas Kaninda600dba99acbb
diff --git a/cmd/posta/worker.go b/cmd/posta/worker.go
index 4681b6d..928aea4 100644
--- a/cmd/posta/worker.go
+++ b/cmd/posta/worker.go
@@ -5,6 +5,8 @@ package main
import (
"context"
+ "fmt"
+ "time"
"github.com/goposta/posta/internal/config"
"github.com/goposta/posta/internal/cron/jobs"
@@ -207,10 +209,32 @@ func runWorker() error {
// Publish worker's build info
workermon.StartHeartbeat(context.Background(), cfg.Redis.Client, config.Version, config.CommitID)
+ var healthSrv *worker.HealthServer
+ if cfg.WorkerHealthEnabled {
+ addr := fmt.Sprintf(":%d", cfg.WorkerHealthPort)
+ healthSrv = worker.NewHealthServer(addr, db, cfg.Redis.Client)
+ stop := healthSrv.Start()
+ defer func() {
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+ stop(ctx)
+ }()
+ logger.Info("worker health endpoints listening",
+ "addr", addr, "paths", "/healthz /readyz /metrics")
+ }
+
logger.Info("Posta worker started",
"version", config.Version,
"concurrency", cfg.WorkerConcurrency,
)
+ // Readiness flips before Run blocks and back once it returns, so a draining
+ // or stopped worker stops advertising itself as ready and an orchestrator
+ // routes nothing new at it.
+ if healthSrv != nil {
+ healthSrv.SetProcessing(true)
+ defer healthSrv.SetProcessing(false)
+ }
+
return srv.Run(mux)
}
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 2b3c224..edd4b69 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -45,7 +45,7 @@ ARG COMMIT=unknown
LABEL org.opencontainers.image.title="posta" \
org.opencontainers.image.description="Posta is a self-hosted email delivery platform" \
- org.opencontainers.image.licenses="Apache" \
+ org.opencontainers.image.licenses="AGPL-3.0-or-later" \
org.opencontainers.image.authors="Jonas Kaninda" \
org.opencontainers.image.version="${VERSION}" \
org.opencontainers.image.source="https://github.com/goposta/posta" \
@@ -57,9 +57,13 @@ RUN apk add --no-cache ca-certificates tzdata \
# Single self-contained binary: the dashboard is embedded, so there are no
# static files to copy and no POSTA_WEB_DIR to set.
COPY --from=builder /bin/posta /bin/posta
-RUN ln -s /bin/posta /posta
+COPY docker/healthcheck.sh /usr/local/bin/posta-healthcheck
+RUN ln -s /bin/posta /posta && chmod +x /usr/local/bin/posta-healthcheck
USER posta
EXPOSE 9000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+ CMD ["/usr/local/bin/posta-healthcheck"]
+
ENTRYPOINT ["/bin/posta"]
diff --git a/docker/healthcheck.sh b/docker/healthcheck.sh
new file mode 100755
index 0000000..69c931d
--- /dev/null
+++ b/docker/healthcheck.sh
@@ -0,0 +1,18 @@
+#!/bin/sh
+# SPDX-FileCopyrightText: 2026 Jonas Kaninda
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Container health check for both Posta roles.
+#
+set -eu
+
+PORT="${POSTA_WORKER_HEALTH_PORT:-${POSTA_PORT:-9000}}"
+PATH_="${POSTA_HEALTHCHECK_PATH:-/healthz}"
+URL="http://127.0.0.1:${PORT}${PATH_}"
+
+if wget --quiet --spider --timeout=3 --tries=1 "$URL" 2>/dev/null; then
+ exit 0
+fi
+
+echo "posta healthcheck failed: ${URL}" >&2
+exit 1
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 0e86948..d8144e5 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -11,7 +11,7 @@ const config: Config = {
v4: true,
},
- url: 'https://docs.posta.dev',
+ url: 'https://docs.goposta.dev',
baseUrl: '/',
organizationName: 'goposta',
@@ -99,7 +99,7 @@ const config: Config = {
},
{
label: 'Website',
- href: 'https://posta.dev',
+ href: 'https://goposta.dev',
},
],
},
diff --git a/examples/docker-compose-full.yml b/examples/docker-compose-full.yml
index 85e5513..1bac737 100644
--- a/examples/docker-compose-full.yml
+++ b/examples/docker-compose-full.yml
@@ -56,6 +56,14 @@ services:
POSTA_REDIS_ADDR: "posta-redis:6379"
POSTA_WORKER_CONCURRENCY: "10"
POSTA_WORKER_MAX_RETRIES: "5"
+ # The worker serves /healthz, /readyz and /metrics on the same port as the
+ # server. They are separate containers, so the shared number never collides.
+ healthcheck:
+ test: ["CMD", "posta-healthcheck"]
+ interval: 30s
+ timeout: 5s
+ start_period: 10s
+ retries: 3
depends_on:
posta-db:
condition: service_healthy
diff --git a/internal/config/config.go b/internal/config/config.go
index da4ca63..fa3b634 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -66,6 +66,16 @@ type Config struct {
EmbeddedWorker bool
WorkerConcurrency int
WorkerMaxRetries int
+ // WorkerHealthEnabled and WorkerHealthPort control the probe and metrics
+ // listener a dedicated worker exposes. It is on by default: a worker with no
+ // probes cannot be health-checked by an orchestrator, which is the reason
+ // the listener exists.
+ //
+ // The port defaults to POSTA_PORT, the same one the server uses. Server and
+ // worker run as separate containers, so there is nothing to collide with,
+ // and one port means one health check command and one EXPOSE for both.
+ WorkerHealthEnabled bool
+ WorkerHealthPort int
// AutoSuppressOnReject adds a recipient to the suppression list when an
// outbound send is permanently rejected (5xx at RCPT TO, e.g. 550 user
@@ -230,6 +240,9 @@ func New() *Config {
if err := godotenv.Load(); err != nil {
logger.Debug("no .env file found, using environment variables")
}
+ // Resolved first so the worker's probe listener can default to it.
+ port := goutils.EnvInt("POSTA_PORT", 9000)
+
return &Config{
Database: DatabaseConfig{
host: goutils.Env("POSTA_DB_HOST", "localhost"),
@@ -241,7 +254,7 @@ func New() *Config {
url: goutils.Env("POSTA_DB_URL", ""),
},
Redis: newRedisConfig(),
- Port: goutils.EnvInt("POSTA_PORT", 9000),
+ Port: port,
Env: goutils.Env("POSTA_ENV", "production"),
JWTSecret: goutils.Env("POSTA_JWT_SECRET", "change-me-in-production"),
DevMode: goutils.EnvBool("POSTA_DEV_MODE", false),
@@ -271,6 +284,8 @@ func New() *Config {
EmbeddedWorker: goutils.EnvBool("POSTA_EMBEDDED_WORKER", false),
WorkerConcurrency: goutils.EnvInt("POSTA_WORKER_CONCURRENCY", 10),
WorkerMaxRetries: goutils.EnvInt("POSTA_WORKER_MAX_RETRIES", 5),
+ WorkerHealthEnabled: goutils.EnvBool("POSTA_WORKER_HEALTH_ENABLED", true),
+ WorkerHealthPort: goutils.EnvInt("POSTA_WORKER_HEALTH_PORT", port),
AutoSuppressOnReject: goutils.EnvBool("POSTA_AUTO_SUPPRESS_ON_REJECT", true),
WebhookMaxRetries: goutils.EnvInt("POSTA_WEBHOOK_MAX_RETRIES", 3),
diff --git a/internal/config/security.go b/internal/config/security.go
index 67a216e..3ced6ad 100644
--- a/internal/config/security.go
+++ b/internal/config/security.go
@@ -175,6 +175,13 @@ func (c *Config) workerProblems() []secretProblem {
true,
})
}
+ if c.WorkerHealthEnabled && (c.WorkerHealthPort <= 0 || c.WorkerHealthPort > 65535) {
+ problems = append(problems, secretProblem{
+ "POSTA_WORKER_HEALTH_PORT",
+ fmt.Sprintf("is %d, which is not a usable port, so the worker would expose no probes or metrics", c.WorkerHealthPort),
+ true,
+ })
+ }
if c.MessagesEnabled && !c.SystemSMTP.IsConfigured() {
problems = append(problems, secretProblem{
"POSTA_SYSTEM_SMTP_HOST",
diff --git a/internal/handlers/health_handler.go b/internal/handlers/health_handler.go
index 8ac6d00..e894f7a 100644
--- a/internal/handlers/health_handler.go
+++ b/internal/handlers/health_handler.go
@@ -4,16 +4,14 @@
package handlers
import (
- "context"
- "time"
+ "net/http"
+ "github.com/goposta/posta/internal/health"
"github.com/jkaninda/okapi"
"github.com/redis/go-redis/v9"
"gorm.io/gorm"
)
-const statusNotReady = "not ready"
-
type HealthHandler struct {
db *gorm.DB
redis *redis.Client
@@ -27,47 +25,20 @@ type HealthResponse struct {
Status string `json:"status" example:"ok"`
}
-type ReadyResponse struct {
- Status string `json:"status" example:"ready"`
- Database string `json:"database" example:"ok"`
- Redis string `json:"redis" example:"ok"`
-}
+// ReadyResponse is the shared readiness payload, so a probe pointed at a server
+// and one pointed at a dedicated worker read the same.
+type ReadyResponse = health.Status
// Healthz is a lightweight liveness probe.
func (h *HealthHandler) Healthz(c *okapi.Context) error {
- return c.OK(HealthResponse{Status: "ok"})
+ return c.OK(HealthResponse{Status: health.StatusOK})
}
// Readyz checks that all dependencies are reachable.
func (h *HealthHandler) Readyz(c *okapi.Context) error {
- resp := ReadyResponse{
- Status: "ready",
- Database: "ok",
- Redis: "ok",
- }
-
- sqlDB, err := h.db.DB()
- if err != nil {
- resp.Status = statusNotReady
- resp.Database = err.Error()
- } else {
- ctx, cancel := context.WithTimeout(c.Request().Context(), 2*time.Second)
- defer cancel()
- if err := sqlDB.PingContext(ctx); err != nil {
- resp.Status = statusNotReady
- resp.Database = err.Error()
- }
- }
-
- ctx, cancel := context.WithTimeout(c.Request().Context(), 2*time.Second)
- defer cancel()
- if err := h.redis.Ping(ctx).Err(); err != nil {
- resp.Status = statusNotReady
- resp.Redis = err.Error()
- }
-
- if resp.Status != "ready" {
- return c.JSON(503, resp)
+ status := health.Check(c.Request().Context(), h.db, h.redis)
+ if !status.Ready() {
+ return c.JSON(http.StatusServiceUnavailable, status)
}
- return c.OK(resp)
+ return c.OK(status)
}
diff --git a/internal/health/health.go b/internal/health/health.go
new file mode 100644
index 0000000..1c53260
--- /dev/null
+++ b/internal/health/health.go
@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Jonas Kaninda
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Package health answers "can this process do its job right now?" for both the
+// server and a dedicated worker.
+//
+// It lives here rather than in either caller so the two cannot drift: an
+// operator pointing the same probe at a server pod and a worker pod should get
+// the same shape and the same meaning of "ready".
+package health
+
+import (
+ "context"
+ "errors"
+ "time"
+
+ "github.com/redis/go-redis/v9"
+ "gorm.io/gorm"
+)
+
+// probeTimeout bounds a single dependency check. A probe that hangs is a failed
+// probe: an orchestrator is asking whether to send work here, and no answer for
+// thirty seconds is worse than a quick "no".
+const probeTimeout = 2 * time.Second
+
+const (
+ StatusOK = "ok"
+ StatusReady = "ready"
+ StatusNotReady = "not ready"
+)
+
+// Status is the readiness payload. The field names are part of the operator
+// contract — probes and dashboards read them — so they are kept stable.
+type Status struct {
+ Status string `json:"status" example:"ready"`
+ Database string `json:"database" example:"ok"`
+ Redis string `json:"redis" example:"ok"`
+}
+
+// Ready reports whether every dependency answered.
+func (s Status) Ready() bool { return s.Status == StatusReady }
+
+// Check pings each dependency and reports what it found. A nil dependency is
+// reported as unconfigured rather than skipped: a worker with no Redis cannot
+// take a job, and saying "ready" would be a lie.
+func Check(ctx context.Context, db *gorm.DB, rdb *redis.Client) Status {
+ s := Status{Status: StatusReady, Database: StatusOK, Redis: StatusOK}
+
+ if err := pingDatabase(ctx, db); err != nil {
+ s.Status, s.Database = StatusNotReady, err.Error()
+ }
+ if err := pingRedis(ctx, rdb); err != nil {
+ s.Status, s.Redis = StatusNotReady, err.Error()
+ }
+ return s
+}
+
+func pingDatabase(ctx context.Context, db *gorm.DB) error {
+ if db == nil {
+ return errors.New("not configured")
+ }
+ sqlDB, err := db.DB()
+ if err != nil {
+ return err
+ }
+ ctx, cancel := context.WithTimeout(ctx, probeTimeout)
+ defer cancel()
+ return sqlDB.PingContext(ctx)
+}
+
+func pingRedis(ctx context.Context, rdb *redis.Client) error {
+ if rdb == nil {
+ return errors.New("not configured")
+ }
+ ctx, cancel := context.WithTimeout(ctx, probeTimeout)
+ defer cancel()
+ return rdb.Ping(ctx).Err()
+}
diff --git a/internal/metrics/metrics.go b/internal/metrics/metrics.go
index 0f573db..8c1e7fe 100644
--- a/internal/metrics/metrics.go
+++ b/internal/metrics/metrics.go
@@ -297,6 +297,12 @@ func PrometheusMiddleware() okapi.Middleware {
}
+// HTTPHandler returns the Prometheus handler for a plain net/http mux — the
+// dedicated worker, which has no okapi router.
+func HTTPHandler() http.Handler {
+ return promhttp.Handler()
+}
+
// MetricsHandler returns the Prometheus metrics handler.
func MetricsHandler() okapi.HandlerFunc {
handler := promhttp.Handler()
diff --git a/internal/worker/health.go b/internal/worker/health.go
new file mode 100644
index 0000000..b0bbe48
--- /dev/null
+++ b/internal/worker/health.go
@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Jonas Kaninda
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package worker
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "net/http"
+ "sync/atomic"
+ "time"
+
+ "github.com/goposta/posta/internal/health"
+ "github.com/goposta/posta/internal/metrics"
+ "github.com/jkaninda/logger"
+ "github.com/redis/go-redis/v9"
+ "gorm.io/gorm"
+)
+
+// HealthServer exposes liveness, readiness, and Prometheus metrics for a
+// dedicated worker process.
+//
+// A worker has no HTTP surface of its own, which left an orchestrator with no
+// way to tell a wedged worker from a busy one, and left the Prometheus counters
+// the worker increments with nothing to scrape them.
+type HealthServer struct {
+ db *gorm.DB
+ redis *redis.Client
+ srv *http.Server
+
+ // processing is set once the queue consumer is running and cleared when it
+ // stops. Dependencies being reachable is not the same as the worker doing
+ // its job: a process that answered every ping but had stopped consuming
+ // would keep reporting ready while the queue backed up behind it.
+ processing atomic.Bool
+}
+
+// WorkerStatus is the worker's readiness payload: the same fields the server's
+// /readyz returns, plus whether this process is actually consuming from the
+// queue. It is spelled out rather than embedding health.Status, which would make
+// the field reachable as status.Status.Status.
+type WorkerStatus struct {
+ Status string `json:"status"`
+ Database string `json:"database"`
+ Redis string `json:"redis"`
+ Processing bool `json:"processing"`
+}
+
+func NewHealthServer(addr string, db *gorm.DB, rdb *redis.Client) *HealthServer {
+ h := &HealthServer{db: db, redis: rdb}
+
+ mux := http.NewServeMux()
+ mux.HandleFunc("/healthz", h.healthz)
+ mux.HandleFunc("/readyz", h.readyz)
+ mux.Handle("/metrics", metrics.HTTPHandler())
+
+ h.srv = &http.Server{
+ Addr: addr,
+ Handler: mux,
+ ReadHeaderTimeout: 5 * time.Second,
+ }
+ return h
+}
+
+// SetProcessing records whether the queue consumer is running.
+func (h *HealthServer) SetProcessing(running bool) { h.processing.Store(running) }
+
+// Start serves in the background and returns a shutdown function.
+//
+// A failure to bind is logged, not fatal. The worker's job is delivering mail;
+// taking a healthy worker down because its probe port is occupied would trade a
+// monitoring problem for an outage.
+func (h *HealthServer) Start() func(context.Context) {
+ go func() {
+ if err := h.srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+ logger.Error("worker health server stopped; probes and metrics are unavailable",
+ "addr", h.srv.Addr, "error", err)
+ }
+ }()
+
+ return func(ctx context.Context) {
+ if err := h.srv.Shutdown(ctx); err != nil {
+ logger.Warn("worker health server did not shut down cleanly", "error", err)
+ }
+ }
+}
+
+// healthz answers whether the process is alive. It deliberately touches nothing
+// else: a liveness probe that fails when the database is briefly unreachable
+// gets the worker restarted, which does not help and loses in-flight work.
+func (h *HealthServer) healthz(w http.ResponseWriter, _ *http.Request) {
+ // Only the status field: health.Status would also serialise empty database
+ // and redis entries, which read as failed checks rather than unasked ones,
+ // and would not match what the server's /healthz returns.
+ writeJSON(w, http.StatusOK, map[string]string{"status": health.StatusOK})
+}
+
+func (h *HealthServer) readyz(w http.ResponseWriter, r *http.Request) {
+ deps := health.Check(r.Context(), h.db, h.redis)
+ processing := h.processing.Load()
+
+ status := WorkerStatus{
+ Status: deps.Status,
+ Database: deps.Database,
+ Redis: deps.Redis,
+ Processing: processing,
+ }
+ if !processing {
+ status.Status = health.StatusNotReady
+ }
+
+ code := http.StatusOK
+ if status.Status != health.StatusReady {
+ code = http.StatusServiceUnavailable
+ }
+ writeJSON(w, code, status)
+}
+
+func writeJSON(w http.ResponseWriter, code int, v any) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(code)
+ _ = json.NewEncoder(w).Encode(v)
+}
diff --git a/internal/worker/health_test.go b/internal/worker/health_test.go
new file mode 100644
index 0000000..a10aa94
--- /dev/null
+++ b/internal/worker/health_test.go
@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 Jonas Kaninda
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package worker
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+)
+
+func get(t *testing.T, h *HealthServer, path string) (*httptest.ResponseRecorder, WorkerStatus) {
+ t.Helper()
+ rec := httptest.NewRecorder()
+ h.srv.Handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+
+ var body WorkerStatus
+ if strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
+ if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+ t.Fatalf("%s returned invalid JSON: %v (%s)", path, err, rec.Body.String())
+ }
+ }
+ return rec, body
+}
+
+// Liveness must not depend on anything else. A probe that fails when the
+// database blips gets the worker restarted, which loses in-flight work and does
+// not fix the database.
+func TestHealthzIsIndependentOfDependencies(t *testing.T) {
+ h := NewHealthServer(":0", nil, nil)
+
+ rec, body := get(t, h, "/healthz")
+ if rec.Code != http.StatusOK {
+ t.Fatalf("expected 200 with no dependencies at all, got %d", rec.Code)
+ }
+ if body.Status != "ok" {
+ t.Errorf("expected status ok, got %q", body.Status)
+ }
+
+ // Liveness reports only its own status. Empty database and redis fields
+ // would read as failed checks rather than checks that were never made.
+ var raw map[string]any
+ if err := json.Unmarshal(rec.Body.Bytes(), &raw); err != nil {
+ t.Fatalf("invalid JSON: %v", err)
+ }
+ if len(raw) != 1 || raw["status"] != "ok" {
+ t.Errorf("liveness payload should be exactly {\"status\":\"ok\"}, got %v", raw)
+ }
+}
+
+// Unreachable dependencies must not read as ready.
+func TestReadyzFailsWithoutDependencies(t *testing.T) {
+ h := NewHealthServer(":0", nil, nil)
+ h.SetProcessing(true)
+
+ rec, body := get(t, h, "/readyz")
+ if rec.Code != http.StatusServiceUnavailable {
+ t.Fatalf("expected 503 when nothing is reachable, got %d", rec.Code)
+ }
+ if body.Status != "not ready" {
+ t.Errorf("expected 'not ready', got %q", body.Status)
+ }
+ if body.Database == "ok" || body.Redis == "ok" {
+ t.Errorf("dependencies should report why they failed, got db=%q redis=%q", body.Database, body.Redis)
+ }
+}
+
+// A process that answers pings but has stopped consuming is not ready: work
+// routed to it would sit in the queue behind a worker that looks healthy.
+func TestReadyzRequiresProcessing(t *testing.T) {
+ h := NewHealthServer(":0", nil, nil)
+
+ _, stopped := get(t, h, "/readyz")
+ if stopped.Processing {
+ t.Fatal("a worker that has not started must not report processing")
+ }
+
+ h.SetProcessing(true)
+ _, running := get(t, h, "/readyz")
+ if !running.Processing {
+ t.Fatal("SetProcessing(true) should be reflected in the payload")
+ }
+
+ h.SetProcessing(false)
+ rec, drained := get(t, h, "/readyz")
+ if drained.Processing {
+ t.Error("a drained worker must stop reporting processing")
+ }
+ if rec.Code != http.StatusServiceUnavailable {
+ t.Errorf("a drained worker must not be ready, got %d", rec.Code)
+ }
+}
+
+// The counters the worker increments are useless if nothing can scrape them.
+func TestMetricsAreExposed(t *testing.T) {
+ h := NewHealthServer(":0", nil, nil)
+
+ rec := httptest.NewRecorder()
+ h.srv.Handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+
+ if rec.Code != http.StatusOK {
+ t.Fatalf("expected 200 from /metrics, got %d", rec.Code)
+ }
+ if !strings.Contains(rec.Body.String(), "# HELP") {
+ t.Error("expected Prometheus exposition format")
+ }
+}
+
+// The payload is an operator contract: probes and dashboards read these names.
+func TestReadyzPayloadShape(t *testing.T) {
+ h := NewHealthServer(":0", nil, nil)
+
+ rec := httptest.NewRecorder()
+ h.srv.Handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/readyz", nil))
+
+ var raw map[string]any
+ if err := json.Unmarshal(rec.Body.Bytes(), &raw); err != nil {
+ t.Fatalf("invalid JSON: %v", err)
+ }
+ for _, key := range []string{"status", "database", "redis", "processing"} {
+ if _, ok := raw[key]; !ok {
+ t.Errorf("readiness payload is missing %q: %v", key, raw)
+ }
+ }
+ // Nothing beyond the documented contract.
+ if len(raw) != 4 {
+ t.Errorf("unexpected fields in the payload: %v", raw)
+ }
+}
+
+// Shutting down must not leave the listener holding the port.
+func TestStartAndStop(t *testing.T) {
+ h := NewHealthServer("127.0.0.1:0", nil, nil)
+ stop := h.Start()
+
+ ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer cancel()
+ stop(ctx)
+
+ // A second shutdown is a no-op rather than a panic; deferred cleanup can run
+ // twice on some exit paths.
+ stop(ctx)
+}