feat: The Other Dude v9.0.1 — full-featured email system

ci: add GitHub Pages deployment workflow for docs site

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

poller/internal/observability/metrics.go

@@ -0,0 +1,60 @@
+// Package observability provides Prometheus metrics and health endpoints for the poller.
+package observability
+
+import (
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+// PollDuration tracks the duration of individual device poll cycles.
+var PollDuration = promauto.NewHistogram(prometheus.HistogramOpts{
+	Name:    "mikrotik_poll_duration_seconds",
+	Help:    "Duration of a single device poll cycle in seconds.",
+	Buckets: []float64{0.5, 1, 2, 5, 10, 30, 60},
+})
+
+// PollTotal counts the total number of poll cycles by status.
+// Status labels: "success", "error", "skipped".
+var PollTotal = promauto.NewCounterVec(prometheus.CounterOpts{
+	Name: "mikrotik_poll_total",
+	Help: "Total number of poll cycles.",
+}, []string{"status"})
+
+// DevicesActive tracks the number of devices currently being polled.
+var DevicesActive = promauto.NewGauge(prometheus.GaugeOpts{
+	Name: "mikrotik_devices_active",
+	Help: "Number of devices currently being polled.",
+})
+
+// DeviceConnectionErrors counts total device connection failures.
+var DeviceConnectionErrors = promauto.NewCounter(prometheus.CounterOpts{
+	Name: "mikrotik_device_connection_errors_total",
+	Help: "Total device connection failures.",
+})
+
+// NATSPublishTotal counts NATS publish operations by subject and status.
+// Subject labels: "status", "metrics", "firmware".
+// Status labels: "success", "error".
+var NATSPublishTotal = promauto.NewCounterVec(prometheus.CounterOpts{
+	Name: "mikrotik_nats_publish_total",
+	Help: "Total NATS publish operations.",
+}, []string{"subject", "status"})
+
+// RedisLockTotal counts Redis lock operations by status.
+// Status labels: "obtained", "not_obtained", "error".
+var RedisLockTotal = promauto.NewCounterVec(prometheus.CounterOpts{
+	Name: "mikrotik_redis_lock_total",
+	Help: "Total Redis lock operations.",
+}, []string{"status"})
+
+// CircuitBreakerSkips counts polls skipped due to circuit breaker backoff.
+var CircuitBreakerSkips = promauto.NewCounter(prometheus.CounterOpts{
+	Name: "mikrotik_circuit_breaker_skips_total",
+	Help: "Total polls skipped because the device is in circuit breaker backoff.",
+})
+
+// CircuitBreakerResets counts circuit breaker resets (device recovered after failures).
+var CircuitBreakerResets = promauto.NewCounter(prometheus.CounterOpts{
+	Name: "mikrotik_circuit_breaker_resets_total",
+	Help: "Total circuit breaker resets when a device recovers.",
+})

poller/internal/observability/server.go

@@ -0,0 +1,59 @@
+package observability
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+// StartServer starts an HTTP server for Prometheus metrics and health checks.
+//
+// The server exposes:
+//   - GET /metrics  — Prometheus metrics endpoint
+//   - GET /health   — Liveness probe (returns 200 with {"status":"ok"})
+//
+// The server shuts down gracefully when ctx is cancelled. It runs in a
+// goroutine and does not block the caller.
+func StartServer(ctx context.Context, addr string) *http.Server {
+	mux := http.NewServeMux()
+	mux.Handle("/metrics", promhttp.Handler())
+	mux.HandleFunc("/health", healthHandler)
+
+	srv := &http.Server{
+		Addr:              addr,
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	// Start serving in a goroutine.
+	go func() {
+		slog.Info("observability server starting", "addr", addr)
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			slog.Error("observability server error", "error", err)
+		}
+	}()
+
+	// Graceful shutdown when context is cancelled.
+	go func() {
+		<-ctx.Done()
+		slog.Info("observability server shutting down")
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		if err := srv.Shutdown(shutdownCtx); err != nil {
+			slog.Error("observability server shutdown error", "error", err)
+		}
+		slog.Info("observability server stopped")
+	}()
+
+	return srv
+}
+
+// healthHandler returns a simple liveness response.
+func healthHandler(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte(`{"status":"ok"}`))
+}