feat(telegram): add health HTTP endpoint for monitoring

Adds HealthServer serving /health with JSON status and uptime.
Returns 200 {'status':'ok','uptime_seconds':N} when ready, 503
when starting. Configure via health_addr in config or
ODEK_TELEGRAM_HEALTH_ADDR env var. Disabled by default (empty).

Author: molty3000

cmd/odek/telegram.go

@@ -473,6 +473,19 @@ func telegramCmd(args []string) error {
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
+	// 14b. Start health server if configured.
+	if cfg.HealthAddr != "" {
+		healthSrv := telegram.NewHealthServer(cfg.HealthAddr)
+		healthSrv.SetLogger(rootLog.With("component", "health"))
+		go func() {
+			if err := healthSrv.Start(ctx); err != nil {
+				fmt.Fprintf(os.Stderr, "odek telegram: health server: %v\n", err)
+			}
+		}()
+		// Mark ready once polling begins.
+		defer healthSrv.SetReady()
+	}
+
 	// 15. Handle SIGINT/SIGTERM/SIGHUP.
 	//     SIGHUP spawns a child process then exits (used by /restart and
 	//     agent-triggered restarts). The child's acquireLock kills this

internal/telegram/config.go

@@ -19,6 +19,7 @@ type TelegramConfig struct {
 	DailyTokenBudget int64    `json:"daily_token_budget"` // 0 = unlimited (default)
 	SessionTTL       int      `json:"session_ttl_hours"`  // hours, default 24
 	FallbackURLs     []string `json:"fallback_urls"`
+	HealthAddr       string   `json:"health_addr"`        // e.g. "127.0.0.1:9090" (empty = disabled)
 	LogLevel         string   `json:"log_level"` // "debug","info","warn","error" (default "info")
 	LogFile          string   `json:"log_file"`  // path or empty for stderr
 }
@@ -79,6 +80,9 @@ func ConfigFromEnv(base TelegramConfig) TelegramConfig {
 	if v := os.Getenv("ODEK_TELEGRAM_FALLBACK_URLS"); v != "" {
 		cfg.FallbackURLs = splitAndTrim(v)
 	}
+	if v := os.Getenv("ODEK_TELEGRAM_HEALTH_ADDR"); v != "" {
+		cfg.HealthAddr = v
+	}
 	if v := os.Getenv("ODEK_TELEGRAM_LOG_LEVEL"); v != "" {
 		cfg.LogLevel = v
 	}

internal/telegram/config_test.go

@@ -42,6 +42,9 @@ func TestDefaultConfig(t *testing.T) {
 	if cfg.FallbackURLs != nil {
 		t.Errorf("DefaultConfig().FallbackURLs = %v, want nil", cfg.FallbackURLs)
 	}
+	if cfg.HealthAddr != "" {
+		t.Errorf("DefaultConfig().HealthAddr = %q, want empty string", cfg.HealthAddr)
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -284,6 +287,14 @@ func TestConfigFromEnv_fallbackURLsTrimsEmptyEntries(t *testing.T) {
 	}
 }
 
+func TestConfigFromEnv_healthAddr(t *testing.T) {
+	t.Setenv("ODEK_TELEGRAM_HEALTH_ADDR", "127.0.0.1:9090")
+	cfg := ConfigFromEnv(DefaultConfig())
+	if cfg.HealthAddr != "127.0.0.1:9090" {
+		t.Errorf("HealthAddr = %q, want 127.0.0.1:9090", cfg.HealthAddr)
+	}
+}
+
 func TestConfigFromEnv_multipleOverrides(t *testing.T) {
 	// Multiple env vars set at once.
 	t.Setenv("ODEK_TELEGRAM_BOT_TOKEN", "token:multi")

internal/telegram/health.go

@@ -0,0 +1,101 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"time"
+)
+
+// HealthServer serves a lightweight HTTP health check endpoint.
+// It reports bot liveness and uptime for monitoring systems.
+type HealthServer struct {
+	addr      string
+	startTime time.Time
+	ready     bool
+	log       Logger
+}
+
+// NewHealthServer creates a HealthServer listening on the given address.
+// Use "127.0.0.1:9090" or "0.0.0.0:9090". Empty string disables the server.
+func NewHealthServer(addr string) *HealthServer {
+	return &HealthServer{
+		addr:      addr,
+		startTime: time.Now(),
+		log:       NewNopLogger(),
+	}
+}
+
+// SetLogger sets the logger. If nil, a NopLogger is used.
+func (hs *HealthServer) SetLogger(l Logger) {
+	if l == nil {
+		hs.log = NewNopLogger()
+		return
+	}
+	hs.log = l
+}
+
+// SetReady marks the health server as ready (polling has started).
+func (hs *HealthServer) SetReady() {
+	hs.ready = true
+}
+
+// ServeHTTP implements http.Handler.
+func (hs *HealthServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if r.URL.Path != "/health" {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if !hs.ready {
+		w.WriteHeader(http.StatusServiceUnavailable)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status":  "starting",
+			"message": "bot is initializing, polling not yet started",
+		})
+		return
+	}
+
+	uptime := time.Since(hs.startTime).Truncate(time.Second)
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(map[string]any{
+		"status":         "ok",
+		"uptime_seconds": int(uptime.Seconds()),
+	})
+}
+
+// Start begins listening on the configured address. Blocks until ctx is
+// cancelled, then shuts down the HTTP server gracefully.
+// Returns any error from starting the listener.
+func (hs *HealthServer) Start(ctx context.Context) error {
+	if hs.addr == "" {
+		return nil // disabled
+	}
+
+	ln, err := net.Listen("tcp", hs.addr)
+	if err != nil {
+		return fmt.Errorf("health server: listen %s: %w", hs.addr, err)
+	}
+
+	srv := &http.Server{Addr: hs.addr, Handler: hs}
+	hs.log.Info("health server started", "addr", ln.Addr().String())
+
+	go func() {
+		<-ctx.Done()
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		if err := srv.Shutdown(shutdownCtx); err != nil {
+			fmt.Fprintf(os.Stderr, "health server: shutdown: %v\n", err)
+		}
+	}()
+
+	if err := srv.Serve(ln); err != http.ErrServerClosed {
+		return fmt.Errorf("health server: serve: %w", err)
+	}
+	return nil
+}

internal/telegram/health_test.go

@@ -0,0 +1,94 @@
+package telegram
+
+import (
+	"encoding/json"
+	"net"
+	"net/http"
+	"testing"
+	"time"
+)
+
+func TestHealthServer_Returns200(t *testing.T) {
+	hs := NewHealthServer("127.0.0.1:0")
+	hs.ready = true
+
+	ts := &http.Server{Addr: hs.addr, Handler: hs}
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	defer ln.Close()
+	go ts.Serve(ln)
+
+	time.Sleep(50 * time.Millisecond)
+
+	resp, err := http.Get("http://" + ln.Addr().String() + "/health")
+	if err != nil {
+		t.Fatalf("GET /health: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		t.Errorf("status = %d, want 200", resp.StatusCode)
+	}
+
+	var body map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if body["status"] != "ok" {
+		t.Errorf("status = %q, want ok", body["status"])
+	}
+	if _, ok := body["uptime_seconds"]; !ok {
+		t.Error("missing uptime_seconds")
+	}
+}
+
+func TestHealthServer_NotReady(t *testing.T) {
+	hs := NewHealthServer("127.0.0.1:0")
+	// ready defaults to false
+
+	ts := &http.Server{Addr: hs.addr, Handler: hs}
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	defer ln.Close()
+	go ts.Serve(ln)
+
+	time.Sleep(50 * time.Millisecond)
+
+	resp, err := http.Get("http://" + ln.Addr().String() + "/health")
+	if err != nil {
+		t.Fatalf("GET /health: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 503 {
+		t.Errorf("status = %d, want 503", resp.StatusCode)
+	}
+}
+
+func TestHealthServer_404OnOtherPaths(t *testing.T) {
+	hs := NewHealthServer("127.0.0.1:0")
+
+	ts := &http.Server{Addr: hs.addr, Handler: hs}
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	defer ln.Close()
+	go ts.Serve(ln)
+
+	time.Sleep(50 * time.Millisecond)
+
+	resp, err := http.Get("http://" + ln.Addr().String() + "/metrics")
+	if err != nil {
+		t.Fatalf("GET /metrics: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 404 {
+		t.Errorf("status = %d, want 404", resp.StatusCode)
+	}
+}