From 1716a845eb78a9d2ee39dddc0941d3981bf543ab Mon Sep 17 00:00:00 2001
From: Luis Pater <webmaster@idotorg.org>
Date: Tue, 21 Apr 2026 20:16:18 +0800
Subject: [PATCH] feat(api): add support for `HEAD` requests to `/healthz`
 endpoint

- Refactored `/healthz` handler to support `HEAD` requests alongside `GET`.
- Updated tests to include validation for `HEAD` requests with expected status and empty body.

Closes: #2929
---
 internal/api/server.go      | 11 +++++++--
 internal/api/server_test.go | 45 ++++++++++++++++++++++++-------------
 2 files changed, 39 insertions(+), 17 deletions(-)

diff --git a/internal/api/server.go b/internal/api/server.go
index 075455ba8..9b7452555 100644
--- a/internal/api/server.go
+++ b/internal/api/server.go
@@ -319,9 +319,16 @@ func NewServer(cfg *config.Config, authManager *auth.Manager, accessManager *sdk
 // setupRoutes configures the API routes for the server.
 // It defines the endpoints and associates them with their respective handlers.
 func (s *Server) setupRoutes() {
-	s.engine.GET("/healthz", func(c *gin.Context) {
+	healthzHandler := func(c *gin.Context) {
+		if c.Request.Method == http.MethodHead {
+			c.Status(http.StatusOK)
+			return
+		}
+
 		c.JSON(http.StatusOK, gin.H{"status": "ok"})
-	})
+	}
+	s.engine.GET("/healthz", healthzHandler)
+	s.engine.HEAD("/healthz", healthzHandler)
 
 	s.engine.GET("/management.html", s.serveManagementControlPanel)
 	openaiHandlers := openai.NewOpenAIAPIHandler(s.handlers)
diff --git a/internal/api/server_test.go b/internal/api/server_test.go
index dbc2cd5a8..db1ef27d1 100644
--- a/internal/api/server_test.go
+++ b/internal/api/server_test.go
@@ -50,23 +50,38 @@ func newTestServer(t *testing.T) *Server {
 func TestHealthz(t *testing.T) {
 	server := newTestServer(t)
 
-	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
-	rr := httptest.NewRecorder()
-	server.engine.ServeHTTP(rr, req)
+	t.Run("GET", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+		rr := httptest.NewRecorder()
+		server.engine.ServeHTTP(rr, req)
 
-	if rr.Code != http.StatusOK {
-		t.Fatalf("unexpected status code: got %d want %d; body=%s", rr.Code, http.StatusOK, rr.Body.String())
-	}
+		if rr.Code != http.StatusOK {
+			t.Fatalf("unexpected status code: got %d want %d; body=%s", rr.Code, http.StatusOK, rr.Body.String())
+		}
 
-	var resp struct {
-		Status string `json:"status"`
-	}
-	if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
-		t.Fatalf("failed to parse response JSON: %v; body=%s", err, rr.Body.String())
-	}
-	if resp.Status != "ok" {
-		t.Fatalf("unexpected response status: got %q want %q", resp.Status, "ok")
-	}
+		var resp struct {
+			Status string `json:"status"`
+		}
+		if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response JSON: %v; body=%s", err, rr.Body.String())
+		}
+		if resp.Status != "ok" {
+			t.Fatalf("unexpected response status: got %q want %q", resp.Status, "ok")
+		}
+	})
+
+	t.Run("HEAD", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodHead, "/healthz", nil)
+		rr := httptest.NewRecorder()
+		server.engine.ServeHTTP(rr, req)
+
+		if rr.Code != http.StatusOK {
+			t.Fatalf("unexpected status code: got %d want %d; body=%s", rr.Code, http.StatusOK, rr.Body.String())
+		}
+		if rr.Body.Len() != 0 {
+			t.Fatalf("expected empty body for HEAD request, got %q", rr.Body.String())
+		}
+	})
 }
 
 func TestAmpProviderModelRoutes(t *testing.T) {