web/admin: SPA Messages tab + Purge button + DLQ chips (Phase 5) (#798)

## Summary

Phase 5 of `docs/design/2026_05_16_proposed_admin_purge_queue.md` —
operator-facing SPA UI for the `AdminPeekQueue` / `AdminPurgeQueue`
endpoints PR #797 wired. The queue detail page now ships:

- **DLQ chip + "DLQ for" sources list** — when another queue's
`RedrivePolicy` points at this queue, a pill in the header marks it as a
DLQ and a section below lists the source queues (each linked to its
detail page so the operator can navigate the topology).
- **Messages section** — paginated table of currently-visible messages:
message-id prefix, sent timestamp, FIFO `MessageGroupId` (column shown
only on FIFO queues), receive count, body preview, original size.
Row-click opens a detail modal showing the full body, every attribute
(typed `String` / `Binary` / `Number` etc.), and a "Copy as JSON" button
writing a schema-versioned payload to the clipboard.
- **Purge button** — labelled `Purge messages` or `Purge DLQ` depending
on `is_dlq`. Confirmation modal requires typing the exact queue name; on
429 `PurgeQueueInProgress` the modal stays open and surfaces the
rate-limit message.

> ⚠️ **Stacked on PR #797.** This branch builds on
`feat/sqs-admin-peek-purge-http` because the SPA needs the Phase 4 HTTP
endpoints. Once #797 merges to main, please rebase (or merge #797 first
then this auto-fast-forwards). I can rebase on request.

## Eager full-body fetch

The list call sets `body_max_bytes = 262144` (= 256 KiB, SQS's
stored-message hard cap) so the detail modal renders directly from the
row already in memory — no re-peek round-trip on modal open. This
eliminates the entire "row disappeared between list and modal" class of
failures: concurrent purge, ReceiveMessage from another client,
visibility timer started, leader step-down (design doc §3.5).

Page size stays at the documented Phase 5 default of 20 rows. Worst
case: 20 × 256 KiB = 5 MiB response, well under typical network and
JSON-parse budgets.

## API client changes (`web/admin/src/api/client.ts`)

- `SqsQueueSummary` gains `is_dlq` + optional `dlq_sources`.
- New types: `SqsPeekedAttribute`, `SqsPeekedMessage`, `SqsPeekResult`,
`SqsPeekOptions`.
- New methods: `api.peekQueue(name, opts, signal)` (signal-aware so
navigation aborts the in-flight peek) and `api.purgeQueue(name)`.

## Handler 429 envelope (`internal/admin/sqs_handler.go`)

The Phase 4 `writePurgeInProgress` was emitting the JSON body with a
`code` key, which diverged from `writeJSONError`'s canonical `error` key
— so `apiFetch.ts` could not extract the AWS-style sentinel into
`ApiError.code` consistently with every other 4xx. Switched to `error`
(with `retry_after_seconds` still in the body alongside the canonical
`Retry-After` header). The matching unit test assertion was updated.

**Caller audit (semantic-change rule):** the wire-shape adjustment has
no other consumer yet — Phase 4 (#797) introduced the endpoint and the
test was the sole reader. Updated.

## Risk

Low. New SPA UI only; the handler change is a 1-key rename matching the
existing admin error envelope.

## Self-review (5 passes)

1. **Data loss** — read endpoint (peek) plus the existing
`AdminPurgeQueue` wrapper. No new write paths.
2. **Concurrency** — eager full-body fetch eliminates the modal re-peek
race. AbortController cancels in-flight peek on navigation / unmount;
`DOMException name=AbortError` is filtered before setError to avoid
stale-component warnings.
3. **Performance** — page size capped at 20 (default; server clamps to ≤
100). Body cap 256 KiB. No hot-path allocations.
4. **Consistency** — Purge button reuses the queue's name as the
confirmation token, matching the existing Delete confirmation. The 429
response shape now matches every other admin 4xx so the SPA error
handling is uniform.
5. **Test coverage** — `npm run lint` (tsc -b --noEmit) passes. `npm run
build` (vite) passes. Go-side `TestSqsHandler_PurgeQueue_RateLimited429`
updated for the `error`-key envelope. No frontend test infra in the
project (intentional; the `lint` script is the contract).

## Test plan

- [x] `cd web/admin && npm run lint` (tsc -b --noEmit) passes
- [x] `cd web/admin && npm run build` (vite build) passes
- [x] `go test -race -count=1 ./internal/admin/...` passes (12 existing
+ the 429 envelope update)
- [x] `golangci-lint run ./internal/admin/...` 0 issues
- [ ] CI on this PR
- [ ] Manual smoke: navigate to a queue detail page, peek messages, open
the modal, copy-as-JSON, attempt purge twice (second attempt should hit
429)

## Out of scope (follow-ups)

- **Throttle integration**: dedicated per-queue admin-peek bucket
(`bucketActionAdminPeek` + `resolveActionConfig` explicit case + typed
`adminPeekThrottledError` / `PeekThrottledError`). Leader-only + `Limit
≤ 100` already bound the steady-state cost; the dedicated bucket adds a
per-queue cap.
- **Audit logging & Prometheus counters** (design doc §3.6):
`admin.sqs.purge_queue` audit line +
`elastickv_sqs_admin_purge_queue_total{queue, outcome}` /
`elastickv_sqs_admin_peek_queue_total{queue, outcome}`.
- **Page-size selector** (20 / 50 / 100) + cumulative-response-size
warning. The MVP defaults to 20 to keep the worst-case at 5 MiB; larger
sizes can land as a follow-up if operators request them.
- **`principalForReadSensitive` live `RoleStore` re-check** (design doc
Goal 8) — blocked on the wider live-role plumbing.
- **Design doc rename** `_proposed_` → `_implemented_` once Phase 6
lands (just the rename — Phases 2/3/4/5 are functionally complete).


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
  * Added message peeking with pagination for SQS queues
* Introduced Dead Letter Queue (DLQ) indicators and source queue
references
  * Added queue purge workflow with confirmation modal
  * Added "Copy as JSON" functionality for message details

* **Updates**
  * Enhanced SQS error response formatting for improved API consistency

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/bootjp/elastickv/pull/798?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: bootjp

internal/admin/sqs_handler.go

@@ -40,16 +40,9 @@ type QueueSummary struct {
 	CreatedAt  *time.Time        `json:"created_at,omitempty"`
 	Attributes map[string]string `json:"attributes,omitempty"`
 	Counters   QueueCounters     `json:"counters"`
-	// IsDLQ is true when at least one other queue's RedrivePolicy
-	// resolves its deadLetterTargetArn to this queue. The SPA uses
-	// the flag to switch the Messages-tab framing and the Purge
-	// button label between "Purge messages" and "Purge DLQ".
+	// True when another queue's RedrivePolicy points at this one.
 	IsDLQ bool `json:"is_dlq"`
-	// DLQSources lists the names of queues whose RedrivePolicy
-	// points at this queue, sorted lexicographically. Empty when
-	// IsDLQ is false; the SPA renders these as chips on the queue
-	// detail page so the operator confirms what feeds the DLQ
-	// before purging.
+	// Source queue names that point at this DLQ, sorted lex.
 	DLQSources []string `json:"dlq_sources,omitempty"`
 }
 
@@ -698,10 +691,9 @@ func writeQueuesError(w http.ResponseWriter, err error, logger *slog.Logger, r *
 	}
 }
 
-// writePurgeInProgress emits the 429 response shape the design doc
-// §3.4 specifies: Retry-After header (rounded up to whole seconds so
-// a client retrying exactly at the deadline is guaranteed to clear)
-// + JSON body { code, message, retry_after_seconds }.
+// writePurgeInProgress emits the 429 wire shape (Retry-After header
+// + JSON body { error, message, retry_after_seconds }). Whole-second
+// rounding-up so a deadline-exact retry is guaranteed to clear.
 func writePurgeInProgress(w http.ResponseWriter, err *PurgeInProgressError) {
 	secs := int64(err.RetryAfter / time.Second)
 	if err.RetryAfter%time.Second != 0 {
@@ -712,10 +704,11 @@ func writePurgeInProgress(w http.ResponseWriter, err *PurgeInProgressError) {
 	}
 	w.Header().Set("Retry-After", strconv.FormatInt(secs, 10))
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.Header().Set("X-Content-Type-Options", "nosniff")
 	w.Header().Set("Cache-Control", "no-store")
 	w.WriteHeader(http.StatusTooManyRequests)
 	_ = json.NewEncoder(w).Encode(map[string]any{
-		"code":                "PurgeQueueInProgress",
+		"error":               "PurgeQueueInProgress",
 		"message":             "only one PurgeQueue operation on each queue is allowed every 60 seconds",
 		"retry_after_seconds": secs,
 	})

internal/admin/sqs_handler_test.go

@@ -347,7 +347,10 @@ func TestSqsHandler_PurgeQueue_RateLimited429(t *testing.T) {
 	require.Equal(t, "43", rec.Header().Get("Retry-After"))
 	var body map[string]any
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
-	require.Equal(t, "PurgeQueueInProgress", body["code"])
+	// The "error" key (not "code") matches writeJSONError's envelope
+	// so apiFetch.ts can extract the AWS-style sentinel consistently
+	// with every other 4xx error.
+	require.Equal(t, "PurgeQueueInProgress", body["error"])
 	require.EqualValues(t, 43, body["retry_after_seconds"])
 }
 

web/admin/src/api/client.ts

@@ -210,12 +210,48 @@ export interface SqsQueueSummary {
   created_at?: string;
   attributes?: Record<string, string>;
   counters: SqsQueueCounters;
+  // True when another queue's RedrivePolicy points at this one.
+  is_dlq: boolean;
+  // Source queue names that point at this DLQ, sorted lex.
+  dlq_sources?: string[];
 }
 
 export interface SqsQueueList {
   queues: string[];
 }
 
+// SqsPeekedAttribute mirrors AWS's typed MessageAttribute shape;
+// binary_value arrives base64-encoded.
+export interface SqsPeekedAttribute {
+  data_type: string;
+  string_value?: string;
+  binary_value?: string;
+}
+
+export interface SqsPeekedMessage {
+  message_id: string;
+  body: string;
+  body_truncated: boolean;
+  body_original_size: number;
+  sent_timestamp: string;
+  receive_count: number;
+  group_id?: string;
+  deduplication_id?: string;
+  attributes?: Record<string, SqsPeekedAttribute>;
+}
+
+export interface SqsPeekResult {
+  messages: SqsPeekedMessage[];
+  // Omitted when the walk has fully completed for this MVCC snapshot.
+  next_cursor?: string;
+}
+
+export interface SqsPeekOptions {
+  limit?: number;
+  cursor?: string;
+  body_max_bytes?: number;
+}
+
 // KeyViz wire shapes mirror internal/admin/keyviz_handler.go
 // (KeyVizMatrix / KeyVizRow). Go []byte fields arrive as
 // base64-encoded strings via encoding/json — keep them as `string` on
@@ -311,6 +347,21 @@ export const api = {
     apiFetch<SqsQueueSummary>(`/sqs/queues/${encodeURIComponent(name)}`, { signal }),
   deleteQueue: (name: string) =>
     apiFetch<void>(`/sqs/queues/${encodeURIComponent(name)}`, { method: "DELETE" }),
+  // Non-destructive peek of currently-visible messages. Server clamps
+  // limit to [1, 100] and body_max_bytes to [256, 262144].
+  peekQueue: (name: string, opts?: SqsPeekOptions, signal?: AbortSignal) =>
+    apiFetch<SqsPeekResult>(`/sqs/queues/${encodeURIComponent(name)}/messages`, {
+      query: {
+        limit: opts?.limit,
+        cursor: opts?.cursor,
+        body_max_bytes: opts?.body_max_bytes,
+      },
+      signal,
+    }),
+  // Drains the queue's messages while leaving meta/ARN/RedrivePolicy intact.
+  // 60-second rate limit per queue: second purge inside the window → 429.
+  purgeQueue: (name: string) =>
+    apiFetch<void>(`/sqs/queues/${encodeURIComponent(name)}/messages`, { method: "DELETE" }),
   keyVizMatrix: (params: KeyVizParams, signal?: AbortSignal) =>
     apiFetch<KeyVizMatrix>("/keyviz/matrix", {
       query: {