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.
Go email-relayemail-routinghttp-to-smtpmail-deliverymailchimp-alternativemailgun-alternativemailsendermailservermailtemplatemailtestpostmark-alternativesend-emailsendgrid-alternativesendmailtransactional-emailtransactional-outbox
feat(worker): expose health, readiness and metrics endpoints
Jonas Kaninda600dba99acbb
diff --git a/cmd/posta/worker.go b/cmd/posta/worker.goindex 4681b6d..928aea4 100644--- a/cmd/posta/worker.go+++ b/cmd/posta/worker.go@@ -5,6 +5,8 @@ package mainimport ("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 infoworkermon.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/Dockerfileindex 2b3c224..edd4b69 100644--- a/docker/Dockerfile+++ b/docker/Dockerfile@@ -45,7 +45,7 @@ ARG COMMIT=unknownLABEL 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-healthcheckUSER postaEXPOSE 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.shnew file mode 100755index 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 1diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.tsindex 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.ymlindex 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: 3depends_on:posta-db:condition: service_healthydiff --git a/internal/config/config.go b/internal/config/config.goindex da4ca63..fa3b634 100644--- a/internal/config/config.go+++ b/internal/config/config.go@@ -66,6 +66,16 @@ type Config struct {EmbeddedWorker boolWorkerConcurrency intWorkerMaxRetries 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.goindex 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.goindex 8ac6d00..e894f7a 100644--- a/internal/handlers/health_handler.go+++ b/internal/handlers/health_handler.go@@ -4,16 +4,14 @@package handlersimport (- "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.DBredis *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.gonew file mode 100644index 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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)+}