feat(sqs/admin): SigV4-bypass admin entrypoints + SPA queues pages

Replaces PR #659, which conflicted heavily after main moved (PR #649
squashed; PR #658 added S3 admin endpoints; the Approximate counters
implementation now lives directly in adapter/sqs_catalog.go).

This PR:

Backend (adapter/sqs_admin.go + internal/admin/sqs_handler.go):
- SQSServer.AdminListQueues / AdminDescribeQueue / AdminDeleteQueue
  are SigV4-bypass entrypoints, mirroring the AdminListTables /
  AdminListBuckets pattern.
- AdminDescribeQueue uses the existing scanApproxCounters from
  sqs_catalog.go (already on main) so the admin path returns the
  same Visible / NotVisible / Delayed numbers as
  GetQueueAttributes("All") would, taken at one snapshot read TS.
- sqsQueuesBridge in main_admin.go re-shapes
  adapter.AdminQueueSummary into admin.QueueSummary, keeping
  internal/admin free of the heavy adapter dependency tree —
  same pattern as dynamoTablesBridge / s3BucketsBridge.
- admin.QueuesSource is opt-in; deployments that don't run
  --sqsAddress leave /admin/api/v1/sqs/* off the wire and the
  SPA renders a soft "endpoint pending" notice on the 404.
- Role re-evaluation against the live RoleStore on DELETE so a
  downgraded key cannot keep mutating with a still-valid JWT.
- apiRouteTable.dispatch refactored: resourceHandlerFor extracted
  so the dispatcher stays under cyclop=10 as new resources land
  (Dynamo, S3, SQS, future).

Frontend (web/admin/src/pages/SqsList.tsx, SqsDetail.tsx):
- /sqs queue list with refresh + per-row link to detail.
- /sqs/:name detail showing FIFO badge, counters card (Visible /
  In-flight / Delayed), raw attributes table, and a Delete
  confirmation Modal gated by RequireFullAccess.
- api/client.ts gains listQueues / describeQueue / deleteQueue
  with the same AbortSignal pattern used for cluster / dynamo /
  s3 reads.
- Layout nav adds an SQS tab between DynamoDB and S3.

Out of scope (recorded in the SQS partial design doc §16.2):
- PurgeQueue from the SPA. Underlying purgeQueueWithRetry is on
  main; the admin entrypoint is a trivial follow-up.
- Send / Peek / CreateQueue from the SPA. Each needs its own
  adapter entrypoint and form UX; deferred to keep this PR
  focused.

Verified with go build ./..., go test -race ./internal/admin/...,
go test -race -run TestSQS ./adapter/, go test -run TestStartAdmin .,
golangci-lint run ./adapter/... ./internal/admin/... ./...
(0 issues, no //nolint), and cd web/admin && npm run build.

Author: bootjp

adapter/sqs_admin.go

@@ -0,0 +1,151 @@
+package adapter
+
+import (
+	"context"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/cockroachdb/errors"
+)
+
+// AdminQueueSummary is the per-queue projection the admin dashboard
+// surfaces. It deliberately covers only the fields the SPA renders so
+// the package's wire-format types stay internal.
+//
+// Counters mirror the AWS Approximate* attribute set produced by
+// scanApproxCounters; they are best-effort by AWS contract and stop
+// counting once the catalog's per-call cap is reached (the SPA polls
+// continuously, so an unbounded scan would pin the leader).
+type AdminQueueSummary struct {
+	Name       string
+	IsFIFO     bool
+	Generation uint64
+	CreatedAt  time.Time
+	Attributes map[string]string
+	Counters   AdminQueueCounters
+}
+
+// AdminQueueCounters matches sqsApproxCounters (int64) so the admin
+// bridge does not have to convert between widths. Visible /
+// NotVisible / Delayed are the AWS Approximate* triple.
+type AdminQueueCounters struct {
+	Visible    int64
+	NotVisible int64
+	Delayed    int64
+}
+
+// AdminListQueues returns every queue name this server knows about,
+// in the lexicographic order the queue catalog index produces. Read
+// path; runs on follower or leader and uses the same scanQueueNames
+// helper the SigV4 ListQueues handler does.
+func (s *SQSServer) AdminListQueues(ctx context.Context) ([]string, error) {
+	return s.scanQueueNames(ctx) //nolint:wrapcheck // pure pass-through; the adapter owns the error context.
+}
+
+// AdminDescribeQueue returns a snapshot of name's metadata plus the
+// approximate counters. The triple (result, present, error) lets
+// admin callers distinguish a missing queue from a storage error
+// without sniffing sentinels.
+//
+// Like AdminDescribeTable on the Dynamo side, this entrypoint runs
+// on either the leader or a follower (read-only); the counter scan
+// uses a fresh nextTxnReadTS so the result is consistent with what
+// SigV4 GetQueueAttributes would have returned at the same instant.
+func (s *SQSServer) AdminDescribeQueue(ctx context.Context, name string) (*AdminQueueSummary, bool, error) {
+	if strings.TrimSpace(name) == "" {
+		return nil, false, ErrAdminSQSValidation
+	}
+	readTS := s.nextTxnReadTS(ctx)
+	meta, exists, err := s.loadQueueMetaAt(ctx, name, readTS)
+	if err != nil {
+		return nil, false, errors.WithStack(err)
+	}
+	if !exists {
+		return nil, false, nil
+	}
+	counters, err := s.scanApproxCounters(ctx, name, meta.Generation, readTS)
+	if err != nil {
+		return nil, false, err
+	}
+	summary := &AdminQueueSummary{
+		Name:       name,
+		IsFIFO:     meta.IsFIFO,
+		Generation: meta.Generation,
+		CreatedAt:  hlcToTime(meta.CreatedAtHLC),
+		Attributes: metaAttributesForAdmin(meta),
+		Counters:   AdminQueueCounters(counters),
+	}
+	return summary, true, nil
+}
+
+// AdminDeleteQueue is the SigV4-bypass counterpart to deleteQueue.
+// Returns the same sentinel errors as AdminCreateTable on the Dynamo
+// side: ErrAdminForbidden on a read-only principal, ErrAdminNotLeader
+// on a follower, ErrAdminSQSNotFound when the queue is absent.
+func (s *SQSServer) AdminDeleteQueue(ctx context.Context, principal AdminPrincipal, name string) error {
+	if !principal.Role.canWrite() {
+		return ErrAdminForbidden
+	}
+	if !isVerifiedSQSLeader(s.coordinator) {
+		return ErrAdminNotLeader
+	}
+	if strings.TrimSpace(name) == "" {
+		return ErrAdminSQSValidation
+	}
+	if err := s.deleteQueueWithRetry(ctx, name); err != nil {
+		// deleteQueueWithRetry returns sqsAPIError with
+		// sqsErrQueueDoesNotExist when the queue is missing; map
+		// to the structured ErrAdminSQSNotFound so the admin
+		// handler can render 404 without sniffing the AWS code.
+		if isSQSAdminQueueDoesNotExist(err) {
+			return ErrAdminSQSNotFound
+		}
+		return errors.Wrap(err, "admin delete queue")
+	}
+	return nil
+}
+
+// metaAttributesForAdmin renders the queue meta into the same shape
+// queueMetaToAttributes("All") would, minus the counters (the admin
+// summary surfaces them as a typed struct alongside, not as strings).
+// Kept as a small dedicated helper so the SigV4 path's selection
+// machinery stays untouched.
+func metaAttributesForAdmin(meta *sqsQueueMeta) map[string]string {
+	out := map[string]string{
+		"VisibilityTimeout":             strconv.FormatInt(meta.VisibilityTimeoutSeconds, 10),
+		"MessageRetentionPeriod":        strconv.FormatInt(meta.MessageRetentionSeconds, 10),
+		"DelaySeconds":                  strconv.FormatInt(meta.DelaySeconds, 10),
+		"ReceiveMessageWaitTimeSeconds": strconv.FormatInt(meta.ReceiveMessageWaitSeconds, 10),
+		"MaximumMessageSize":            strconv.FormatInt(meta.MaximumMessageSize, 10),
+		"FifoQueue":                     strconv.FormatBool(meta.IsFIFO),
+		"ContentBasedDeduplication":     strconv.FormatBool(meta.ContentBasedDedup),
+	}
+	if meta.RedrivePolicy != "" {
+		out["RedrivePolicy"] = meta.RedrivePolicy
+	}
+	return out
+}
+
+// ErrAdminSQSValidation is returned when an admin entrypoint receives
+// a request with a missing or syntactically-bad queue name. Maps to
+// 400 in the admin HTTP handler.
+var ErrAdminSQSValidation = errors.New("sqs admin: invalid queue name")
+
+// ErrAdminSQSNotFound is returned by write entrypoints when the
+// target queue does not exist. Maps to 404. The describe path uses
+// the (nil, false, nil) tuple instead of this sentinel for the
+// not-found signal, mirroring AdminDescribeTable.
+var ErrAdminSQSNotFound = errors.New("sqs admin: queue not found")
+
+// isSQSAdminQueueDoesNotExist matches the deleteQueueWithRetry path's
+// "queue does not exist" sqsAPIError so AdminDeleteQueue can normalise
+// it to ErrAdminSQSNotFound. Falls through to false on any unrelated
+// error, which AdminDeleteQueue then wraps and propagates.
+func isSQSAdminQueueDoesNotExist(err error) bool {
+	var apiErr *sqsAPIError
+	if !errors.As(err, &apiErr) || apiErr == nil {
+		return false
+	}
+	return apiErr.errorType == sqsErrQueueDoesNotExist
+}

internal/admin/server.go

@@ -61,6 +61,14 @@ type ServerDeps struct {
 	// off" state instead of an empty matrix.
 	KeyViz KeyVizSource
 
+	// Queues is the SQS admin source — covers list, describe, and
+	// delete via QueuesSource. Optional: a nil value disables
+	// /admin/api/v1/sqs/queues{,/{name}} (the mux answers them
+	// with 404). Same opt-in shape as Tables / Buckets; deployments
+	// that don't run the SQS adapter omit this without breaking the
+	// rest of the admin surface.
+	Queues QueuesSource
+
 	// StaticFS is the embed.FS (or any fs.FS) backing the SPA. May be
 	// nil during early development; the router renders 404 for
 	// /admin/assets/* and the SPA fallback in that case.
@@ -112,7 +120,8 @@ func NewServer(deps ServerDeps) (*Server, error) {
 	// nil it serves a 503 keyviz_disabled, which the SPA renders as
 	// a clearer "feature off" state than an unknown_endpoint 404.
 	keyviz := NewKeyVizHandler(deps.KeyViz).WithLogger(logger)
-	mux := buildAPIMux(auth, deps.Verifier, cluster, dynamo, s3, keyviz, logger)
+	sqs := buildSqsHandlerForDeps(deps, logger)
+	mux := buildAPIMux(auth, deps.Verifier, cluster, dynamo, s3, keyviz, sqs, logger)
 	router := NewRouter(mux, deps.StaticFS)
 	return &Server{deps: deps, router: router, auth: auth, mux: mux}, nil
 }
@@ -177,6 +186,20 @@ func buildS3HandlerForDeps(deps ServerDeps, logger *slog.Logger) http.Handler {
 	return NewS3Handler(deps.Buckets).WithLogger(logger)
 }
 
+// buildSqsHandlerForDeps is the parallel constructor for the SQS
+// admin handler. Read paths are open to any session; the DELETE
+// path re-evaluates the principal's role against the live MapRoleStore
+// on every request, so a downgraded key cannot keep mutating with a
+// still-valid JWT.
+func buildSqsHandlerForDeps(deps ServerDeps, logger *slog.Logger) http.Handler {
+	if deps.Queues == nil {
+		return nil
+	}
+	return NewSqsHandler(deps.Queues).
+		WithLogger(logger).
+		WithRoleStore(MapRoleStore(deps.Roles))
+}
+
 // Handler returns an http.Handler that serves the full admin surface.
 // We wrap the router in BodyLimit at the top level so every endpoint
 // — including /admin/healthz and the static asset / SPA paths — is
@@ -215,14 +238,14 @@ func (s *Server) APIHandler() http.Handler {
 // audit path inside AuthService because the generic Audit middleware
 // cannot see the claimed actor at that point in the chain.
 //
-// dynamoHandler / s3Handler may be nil; in that case the corresponding
-// paths fall through to the unknown-endpoint 404, matching the
-// behaviour of any other unregistered admin path.
+// dynamoHandler / s3Handler / sqsHandler may be nil; in that case
+// the corresponding paths fall through to the unknown-endpoint 404,
+// matching the behaviour of any other unregistered admin path.
 //
 // keyvizHandler is always non-nil even when the sampler is disabled —
 // it serves 503 keyviz_disabled itself so the SPA gets a clearer
 // signal than an unknown_endpoint 404 from the catch-all.
-func buildAPIMux(auth *AuthService, verifier *Verifier, clusterHandler, dynamoHandler, s3Handler, keyvizHandler http.Handler, logger *slog.Logger) http.Handler {
+func buildAPIMux(auth *AuthService, verifier *Verifier, clusterHandler, dynamoHandler, s3Handler, keyvizHandler, sqsHandler http.Handler, logger *slog.Logger) http.Handler {
 	loginHandler := http.HandlerFunc(auth.HandleLogin)
 	logoutHandler := http.HandlerFunc(auth.HandleLogout)
 
@@ -290,6 +313,14 @@ func buildAPIMux(auth *AuthService, verifier *Verifier, clusterHandler, dynamoHa
 	if s3Handler != nil {
 		s3Chain = protect(s3Handler)
 	}
+	// SQS endpoints share the same protect chain rationale: GET
+	// reads are session-gated to keep cross-site fetches from
+	// enumerating queue names; DELETE goes through CSRF + the
+	// in-handler RoleFull check inside SqsHandler.
+	var sqsChain http.Handler
+	if sqsHandler != nil {
+		sqsChain = protect(sqsHandler)
+	}
 
 	routes := apiRouteTable{
 		login:   loginChain,
@@ -298,6 +329,7 @@ func buildAPIMux(auth *AuthService, verifier *Verifier, clusterHandler, dynamoHa
 		dynamo:  dynamoChain,
 		s3:      s3Chain,
 		keyviz:  keyvizChain,
+		sqs:     sqsChain,
 	}
 	return http.HandlerFunc(routes.dispatch)
 }
@@ -309,29 +341,55 @@ func buildAPIMux(auth *AuthService, verifier *Verifier, clusterHandler, dynamoHa
 // would otherwise push buildAPIMux's branch count past the limit.
 type apiRouteTable struct {
 	login, logout, cluster http.Handler
-	dynamo, s3             http.Handler
+	dynamo, s3, sqs        http.Handler
 	keyviz                 http.Handler
 }
 
 // dispatch is the receiver method httpHandlerFunc adapts. Logic is
-// the same path-prefix switch the call site previously inlined.
+// the same path-prefix switch the call site previously inlined; the
+// resource-prefix half of it lives in resourceHandlerFor so this
+// function stays under the cyclop ceiling as new resources land.
 func (t apiRouteTable) dispatch(w http.ResponseWriter, r *http.Request) {
-	switch {
-	case r.URL.Path == "/admin/api/v1/auth/login":
+	switch r.URL.Path {
+	case "/admin/api/v1/auth/login":
 		t.login.ServeHTTP(w, r)
-	case r.URL.Path == "/admin/api/v1/auth/logout":
+		return
+	case "/admin/api/v1/auth/logout":
 		t.logout.ServeHTTP(w, r)
-	case r.URL.Path == "/admin/api/v1/cluster":
+		return
+	case "/admin/api/v1/cluster":
 		t.cluster.ServeHTTP(w, r)
-	case r.URL.Path == "/admin/api/v1/keyviz/matrix":
-		t.keyviz.ServeHTTP(w, r)
-	case t.dynamo != nil && isDynamoPath(r.URL.Path):
-		t.dynamo.ServeHTTP(w, r)
-	case t.s3 != nil && isS3Path(r.URL.Path):
-		t.s3.ServeHTTP(w, r)
+		return
+	}
+	if h := t.resourceHandlerFor(r.URL.Path); h != nil {
+		h.ServeHTTP(w, r)
+		return
+	}
+	writeJSONError(w, http.StatusNotFound, "unknown_endpoint",
+		"no admin API handler is registered for this path")
+}
+
+// resourceHandlerFor returns the handler that owns the URL path's
+// resource family, or nil when no resource matches. Pulled out of
+// dispatch so dispatch stays under cyclop=10 even as new admin
+// resources (Dynamo, S3, SQS, KeyViz, future) get added.
+//
+// KeyViz is *always* registered (the constructor wires a non-nil
+// handler that itself emits 503 keyviz_disabled when the underlying
+// sampler is nil), so the switch matches against an exact path
+// equality and never against a nil receiver.
+func (t apiRouteTable) resourceHandlerFor(path string) http.Handler {
+	switch {
+	case t.keyviz != nil && path == "/admin/api/v1/keyviz/matrix":
+		return t.keyviz
+	case t.dynamo != nil && isDynamoPath(path):
+		return t.dynamo
+	case t.s3 != nil && isS3Path(path):
+		return t.s3
+	case t.sqs != nil && isSqsPath(path):
+		return t.sqs
 	default:
-		writeJSONError(w, http.StatusNotFound, "unknown_endpoint",
-			"no admin API handler is registered for this path")
+		return nil
 	}
 }
 
@@ -343,6 +401,10 @@ func isS3Path(p string) bool {
 	return p == pathS3Buckets || strings.HasPrefix(p, pathPrefixS3Buckets)
 }
 
+func isSqsPath(p string) bool {
+	return p == pathSqsQueues || strings.HasPrefix(p, pathPrefixSqsQueues)
+}
+
 func errMissing(field string) error {
 	return &missingDepError{field: field}
 }