homelab-frontend/tasks/8.5-sqs-adapter.md

8.5 — X-Service: sqs adapter, supersedes /sqs/* prefix (GREEN)

Phase: 8 — ServiceAdapter CRD rollout Stage: RED Depends on: 8.1, 8.2, 8.3

Design contract: API_ROUTING_HYBRID_DESIGN.md §2 (queue/{name}/message resource shape), and docs/API-sqs.md for the real upstream contract — six RPCs, base64 bytes fields, lowerCamelCase JSON, 256 KiB body cap, 20s long-poll. Supersedes 7.2; that prefix-based route is retired by this adapter, not extended.

• k8s/serviceadapter-sqs.yaml CR: serviceName: sqs, upstream management-service.sqs.svc.cluster.local:8080, auth.capability: queue:access
• Resource message maps the six RPCs from docs/API-sqs.md's table: POST queue/{name}/message → SendMessage, POST queue/{name}/message:batch → SendMessageBatch, GET queue/{name}/message → ReceiveMessage, DELETE queue/{name}/message/{receiptHandle} → DeleteMessage, POST queue/{name}/message:batchDelete → DeleteMessageBatch, PATCH queue/{name}/message/{receiptHandle} → ChangeMessageVisibility
• {name}/{receiptHandle} path segments resolved the same way 8.2 decided for {id} generally — do not invent a second mechanism here
• requestSchema on SendMessage: messageBody: string (required, base64, the KV+type DSL does not validate base64-ness — that stays a body-content concern, not a schema-type concern), messageAttributes: object, messageGroupId: string, messageDeduplicationId: string, delaySeconds: number
• GET (ReceiveMessage) read timeout exceeds 20s (max waitTimeSeconds) with headroom, and a client disconnect cancels the upstream long-poll (G4)
• Upstream error envelope ({"code": 5, "message": "...", "details": []}) is passed through unchanged, per docs/API-sqs.md's explicit recommendation — not re-rendered as RFC 9457
• kmsvc-redis-master.sqs:6379 (unauthenticated) stays unreachable — the NetworkPolicy carried over from 7.2 grants no egress to it
• Queue lifecycle (create/delete/list) is not exposed — same G2 boundary docs/API-sqs.md already states, unchanged by this adapter
• Old /sqs/* path-mounted route is removed once this adapter is verified live

Verify

Q=agent-worker-queue

curl -s -X POST https://api.riotpiao.com/ \
  -H "Authorization: Bearer $QUEUE_TOKEN" -H 'X-Service: sqs' -H 'X-Resource: message' \
  -d "{\"messageBody\":\"$(printf 'hello world' | base64)\"}"
# expected: {"messageId": "...", "sequenceNumber": ""}

curl -s "https://api.riotpiao.com/?queue=$Q" \
  -H "Authorization: Bearer $QUEUE_TOKEN" -H 'X-Service: sqs' -H 'X-Resource: message' \
  -G --data-urlencode 'maxNumberOfMessages=10' --data-urlencode 'waitTimeSeconds=20'
# expected: 200 within ~20s, {"messages":[...]}, connection not dropped by gateway timeout

kubectl -n api get networkpolicy -o yaml | grep -c 6379
# expected: 0