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

## Summary

First slice of Phase 3.D PR 4-B — adds the JSON capability-advertisement
shape to `/sqs_health` that the §8.5 mixed-version gate requires.
`htfifoCapabilityAdvertised` stays `false` in this PR; subsequent PRs
(4-B-2 routing, 4-B-3 leadership-refusal + catalog polling) flip it to
`true` once the rest of §11 PR 4 is in place.

## What changes

- `/sqs_health` returns JSON when `Accept: application/json` is set:
  ```
  {"status":"ok","capabilities":[...]}
  ```
The capabilities slice is built deterministically off
`htfifoCapabilityAdvertised`. Stays empty in this PR — advertising
`htfifo` before the routing + leadership-refusal pair lands would let
peers build partitioned queues this binary cannot safely serve.
- Legacy `ok\n` text body preserved byte-identical for any caller that
does not signal `application/json` (no Accept header, bare `*/*`
wildcard, `text/plain`).

## What does NOT change yet

- Routing dispatch through `--sqsFifoPartitionMap` → PR 4-B-2 (resolver
hook in `kv/shard_router.go`).
- §8 leadership-refusal hook + `htfifoCapabilityAdvertised = true` flip
→ PR 4-B-3 (with the catalog-polling helper for the CreateQueue
capability gate that PR 5 will start using).

PR 5 still rejects `PartitionCount > 1` per the §11 PR 2 dormancy gate,
so no data-plane risk from this PR.

## Test plan

- [x] `TestServeSQSHealthz_LegacyTextPath` — 3 sub-tests pinning
byte-identical legacy body.
- [x] `TestServeSQSHealthz_JSONShape` — 3 sub-tests covering plain JSON,
q-factor, comma-list.
- [x] `TestServeSQSHealthz_HEAD_JSONOmitsBody` — HEAD on JSON path emits
content-type but no body.
- [x] `TestServeSQSHealthz_RejectsNonGETHEAD` — POST returns 405 in both
legacy and JSON modes.
- [x] `TestSQSAdvertisedCapabilities_TracksFlag` — both branches of the
gate constant.
- [x] `TestClientAcceptsSQSHealthJSON_Boundaries` — 9 Accept-header edge
cases.
- [x] `go test -race ./adapter/...` pass.
- [x] `golangci-lint ./adapter/...` clean.

## Self-review (per CLAUDE.md)

1. **Data loss** — health endpoint only; no FSM/Pebble/retention path.
No issue.
2. **Concurrency / distributed failures** — 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** — `htfifoCapabilityAdvertised` is the single
source of truth for the capability list; `sqsAdvertisedCapabilities()`
is the only producer. Both true/false branches are pinned by tests. No
issue.
5. **Test coverage** — 19 sub-tests across 6 top-level functions. Both
Accept paths and both gate-constant branches are pinned.

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))
+		})
+	}
+}