feat(sqs): /sqs_health capability JSON (Phase 3.D PR 4-B-1)

Adds the JSON capability-advertisement shape to /sqs_health that the
Phase 3.D §8.5 mixed-version gate requires before the data plane
can safely accept partitioned FIFO queues.

What changes

- /sqs_health now returns JSON when Accept: application/json is set:
    {"status":"ok","capabilities":[...]}
  The capabilities slice is built deterministically off
  htfifoCapabilityAdvertised, a package-level constant that stays
  false in this PR — the data plane and the §8 leadership-refusal
  hook are not yet wired, so advertising "htfifo" would let peers
  build partitioned queues this binary cannot safely serve.

- The legacy "ok\n" text body is preserved byte-identical for any
  caller that does not signal application/json (no Accept header,
  bare "*/*" wildcard, text/plain). Existing k8s liveness probes
  and curl integrations stay unchanged.

What does NOT change yet

This is the first slice of the PR 4-B work. Two follow-ups complete
the design's "advertise htfifo only when routing AND leadership-
refusal are both in place" rule:

- PR 4-B-2: routing resolver in kv/shard_router.go that consumes
  --sqsFifoPartitionMap to dispatch (queue, partition) keys to the
  operator-chosen Raft group.
- PR 4-B-3: §8 leadership-refusal hook that calls TransferLeadership
  when a non-htfifo binary holds an SQS Raft group hosting a
  partitioned queue + the catalog-polling helper for the CreateQueue
  capability gate (PR 5 lifts the dormancy and starts using it).

PR 4-B-3 also flips htfifoCapabilityAdvertised to true.

Self-review (per CLAUDE.md)

1. Data loss — health endpoint only; no FSM/Pebble/retention path.
   No issue.
2. Concurrency — single-shot read off a const; no shared state.
   No issue.
3. Performance — JSON marshal of a 2-field struct on a low-QPS
   endpoint. No issue.
4. Data consistency — the gate constant is the single source of
   truth for the capability list; sqsAdvertisedCapabilities() is the
   only producer. Tests pin both true/false branches. No issue.
5. Test coverage — TestServeSQSHealthz_LegacyTextPath (3 sub-tests),
   TestServeSQSHealthz_JSONShape (3 sub-tests),
   TestServeSQSHealthz_HEAD_JSONOmitsBody,
   TestServeSQSHealthz_RejectsNonGETHEAD (2 sub-tests),
   TestSQSAdvertisedCapabilities_TracksFlag (true/false guard),
   TestClientAcceptsSQSHealthJSON_Boundaries (9 sub-tests).

Author: bootjp

adapter/sqs.go

@@ -6,6 +6,7 @@ import (
 	"net"
 	"net/http"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/bootjp/elastickv/kv"
@@ -43,6 +44,45 @@ const (
 	sqsLeaderHealthPath = "/sqs_leader_health"
 )
 
+// sqsCapabilityHTFIFO is the capability string a binary advertises on
+// /sqs_health (when Accept: application/json) once it has the runtime
+// pieces required to safely host a partitioned FIFO queue: the routing
+// layer is wired through --sqsFifoPartitionMap (see main.go), and the
+// leadership-refusal hook in kv refuses leadership for an SQS Raft
+// group that hosts a partitioned queue when the binary itself does
+// not advertise this string.
+//
+// CreateQueue's catalog-polling gate (Phase 3.D PR 5 lifts the
+// dormancy and starts checking) reads this list off /sqs_health on
+// every peer; a CreateQueue with PartitionCount > 1 is rejected
+// unless every peer reports "htfifo" — fail-closed against rolling
+// upgrades that have not yet finished.
+const sqsCapabilityHTFIFO = "htfifo"
+
+// htfifoCapabilityAdvertised gates whether this binary lists
+// "htfifo" on /sqs_health. The flag is set to true only when the
+// binary contains BOTH the routing-layer wiring AND the
+// leadership-refusal safeguard from §8 — the design's "marked
+// htfifo-eligible" bar (§11 PR 4). Lower-numbered PRs in the rollout
+// keep this false so a partial deploy never advertises a capability
+// it cannot safely back up. Phase 3.D PR 4-B flips this to true in
+// the same commit that wires routing + leadership-refusal together.
+const htfifoCapabilityAdvertised = false
+
+// sqsAdvertisedCapabilities returns the capability list emitted on
+// /sqs_health (JSON mode). Stable iteration order is significant —
+// catalog peers may diff capability lists across nodes when checking
+// rollout uniformity, so the list is built deterministically. The
+// returned slice is freshly allocated per call so the caller may
+// mutate it without aliasing the package-level state.
+func sqsAdvertisedCapabilities() []string {
+	caps := make([]string, 0, 1)
+	if htfifoCapabilityAdvertised {
+		caps = append(caps, sqsCapabilityHTFIFO)
+	}
+	return caps
+}
+
 const (
 	sqsHealthMaxRequestBodyBytes = 1024
 	sqsMaxRequestBodyBytes       = 1 << 20
@@ -251,9 +291,70 @@ func serveSQSHealthz(w http.ResponseWriter, r *http.Request) {
 	if !writeSQSHealthMethod(w, r) {
 		return
 	}
+	if clientAcceptsSQSHealthJSON(r) {
+		writeSQSHealthJSONBody(w, r, http.StatusOK, sqsHealthBody{
+			Status:       "ok",
+			Capabilities: sqsAdvertisedCapabilities(),
+		})
+		return
+	}
 	writeSQSHealthBody(w, r, http.StatusOK, "ok\n")
 }
 
+// sqsHealthBody is the JSON shape returned by /sqs_health when the
+// caller passes Accept: application/json. Stable across binary
+// versions — catalog peers diff this body during the CreateQueue
+// gate (Phase 3.D PR 5).
+type sqsHealthBody struct {
+	Status       string   `json:"status"`
+	Capabilities []string `json:"capabilities"`
+}
+
+// clientAcceptsSQSHealthJSON reports whether the caller signalled
+// JSON in the Accept header. Treat the absence of an Accept header
+// (and a bare "*/*" wildcard) as the legacy "ok\n" client to keep
+// the existing health-check integrations (curl, k8s liveness probes)
+// byte-identical.
+//
+// A substring check for "application/json" is sufficient — q-factor
+// and parameter parsing would be overkill for a health endpoint, and
+// any JSON-aware client passes the literal token in a comma-separated
+// list. False matches against media types like "application/jsonseq"
+// are accepted: a client that explicitly types out a JSON-adjacent
+// media type is opting in to the JSON shape on purpose.
+func clientAcceptsSQSHealthJSON(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+	for _, raw := range r.Header.Values("Accept") {
+		if raw == "" || raw == "*/*" {
+			continue
+		}
+		if strings.Contains(raw, "application/json") {
+			return true
+		}
+	}
+	return false
+}
+
+func writeSQSHealthJSONBody(w http.ResponseWriter, r *http.Request, statusCode int, body sqsHealthBody) {
+	encoded, err := json.Marshal(body)
+	if err != nil {
+		// json.Marshal of a fixed shape with a string + []string
+		// cannot realistically fail; fall back to the legacy text
+		// path so a misconfigured client still gets a 200.
+		writeSQSHealthBody(w, r, statusCode, "ok\n")
+		return
+	}
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(statusCode)
+	if r.Method == http.MethodHead {
+		return
+	}
+	_, _ = w.Write(encoded)
+	_, _ = io.WriteString(w, "\n")
+}
+
 func (s *SQSServer) serveSQSLeaderHealthz(w http.ResponseWriter, r *http.Request) {
 	if !writeSQSHealthMethod(w, r) {
 		return

adapter/sqs_health_test.go

@@ -0,0 +1,169 @@
+package adapter
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	json "github.com/goccy/go-json"
+	"github.com/stretchr/testify/require"
+)
+
+// TestServeSQSHealthz_LegacyTextPath pins the byte-identical legacy
+// behaviour: a GET / HEAD with no Accept header (or a bare "*/*"
+// wildcard) returns "ok\n" with text/plain content-type. The
+// existing k8s liveness probe and curl-style integrations rely on
+// this body, so the JSON capability extension MUST NOT alter it.
+func TestServeSQSHealthz_LegacyTextPath(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name   string
+		accept string
+	}{
+		{"no Accept header", ""},
+		{"wildcard Accept", "*/*"},
+		{"text/plain Accept", "text/plain"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			req := httptest.NewRequest(http.MethodGet, sqsHealthPath, nil)
+			if tc.accept != "" {
+				req.Header.Set("Accept", tc.accept)
+			}
+			rec := httptest.NewRecorder()
+			serveSQSHealthz(rec, req)
+			require.Equal(t, http.StatusOK, rec.Code)
+			require.Equal(t, "text/plain; charset=utf-8", rec.Header().Get("Content-Type"))
+			require.Equal(t, "ok\n", rec.Body.String())
+		})
+	}
+}
+
+// TestServeSQSHealthz_JSONShape pins the JSON capability response
+// shape returned when the caller signals Accept: application/json.
+// The CreateQueue capability gate (Phase 3.D PR 5) decodes this
+// body on every peer, so a regression that drops the field or
+// changes the field name would silently break the rolling-upgrade
+// guard.
+func TestServeSQSHealthz_JSONShape(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name   string
+		accept string
+	}{
+		{"plain JSON", "application/json"},
+		{"JSON with q-factor", "application/json;q=1.0"},
+		{"comma-separated list with JSON", "text/plain, application/json;q=0.9"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			req := httptest.NewRequest(http.MethodGet, sqsHealthPath, nil)
+			req.Header.Set("Accept", tc.accept)
+			rec := httptest.NewRecorder()
+			serveSQSHealthz(rec, req)
+			require.Equal(t, http.StatusOK, rec.Code)
+			require.Equal(t, "application/json; charset=utf-8", rec.Header().Get("Content-Type"))
+
+			var got sqsHealthBody
+			require.NoError(t, json.Unmarshal([]byte(strings.TrimSpace(rec.Body.String())), &got))
+			require.Equal(t, "ok", got.Status)
+			require.Equal(t, sqsAdvertisedCapabilities(), got.Capabilities)
+		})
+	}
+}
+
+// TestServeSQSHealthz_HEAD_JSONOmitsBody pins that a HEAD request on
+// the JSON path emits the JSON content-type but no body bytes —
+// matching the existing legacy-path HEAD behaviour. Liveness probes
+// often use HEAD to avoid log spam; the JSON path MUST behave the
+// same way.
+func TestServeSQSHealthz_HEAD_JSONOmitsBody(t *testing.T) {
+	t.Parallel()
+	req := httptest.NewRequest(http.MethodHead, sqsHealthPath, nil)
+	req.Header.Set("Accept", "application/json")
+	rec := httptest.NewRecorder()
+	serveSQSHealthz(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.Equal(t, "application/json; charset=utf-8", rec.Header().Get("Content-Type"))
+	require.Empty(t, rec.Body.String())
+}
+
+// TestServeSQSHealthz_RejectsNonGETHEAD pins that POST / PUT / DELETE
+// are still rejected with 405 in both the legacy and JSON modes —
+// the JSON extension MUST NOT widen the method surface of the
+// endpoint.
+func TestServeSQSHealthz_RejectsNonGETHEAD(t *testing.T) {
+	t.Parallel()
+	for _, accept := range []string{"", "application/json"} {
+		t.Run("Accept="+accept, func(t *testing.T) {
+			t.Parallel()
+			req := httptest.NewRequest(http.MethodPost, sqsHealthPath, nil)
+			if accept != "" {
+				req.Header.Set("Accept", accept)
+			}
+			rec := httptest.NewRecorder()
+			serveSQSHealthz(rec, req)
+			require.Equal(t, http.StatusMethodNotAllowed, rec.Code)
+			require.Equal(t, "GET, HEAD", rec.Header().Get("Allow"))
+		})
+	}
+}
+
+// TestSQSAdvertisedCapabilities_TracksFlag pins the relationship
+// between htfifoCapabilityAdvertised and the emitted list. If a
+// future change flips the constant, the JSON response must reflect
+// it without further wiring — the constant is the single source of
+// truth.
+func TestSQSAdvertisedCapabilities_TracksFlag(t *testing.T) {
+	t.Parallel()
+	caps := sqsAdvertisedCapabilities()
+	if htfifoCapabilityAdvertised {
+		require.Contains(t, caps, sqsCapabilityHTFIFO,
+			"htfifo must be in the list when the flag is true")
+	} else {
+		require.NotContains(t, caps, sqsCapabilityHTFIFO,
+			"htfifo must NOT be in the list when the flag is false; "+
+				"a partial deploy that advertised the capability without "+
+				"the routing + leadership-refusal pair would create new "+
+				"partitioned queues that this binary cannot safely host")
+	}
+}
+
+// TestClientAcceptsSQSHealthJSON_Boundaries pins the substring
+// matcher's edge cases — these are the inputs the catalog-polling
+// caller in Phase 3.D PR 5 will produce, and a regression that
+// silently flips one of these to a wrong answer would either return
+// the legacy body to a JSON peer (PR 5 decode error) or the JSON
+// body to a curl client (UI noise).
+func TestClientAcceptsSQSHealthJSON_Boundaries(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name   string
+		accept []string
+		want   bool
+	}{
+		{"nil request", nil, false},
+		{"empty header value", []string{""}, false},
+		{"bare wildcard", []string{"*/*"}, false},
+		{"text/plain only", []string{"text/plain"}, false},
+		{"plain JSON", []string{"application/json"}, true},
+		{"JSON with parameters", []string{"application/json; charset=utf-8"}, true},
+		{"multi-value with JSON last", []string{"text/plain", "application/json"}, true},
+		{"multi-value with JSON first", []string{"application/json", "text/plain"}, true},
+		{"comma-list with JSON", []string{"text/plain, application/json;q=0.9"}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			var req *http.Request
+			if tc.accept != nil {
+				req = httptest.NewRequest(http.MethodGet, sqsHealthPath, nil)
+				req.Header["Accept"] = tc.accept
+			}
+			require.Equal(t, tc.want, clientAcceptsSQSHealthJSON(req))
+		})
+	}
+}