pachecoc/sqs-ui repository overview

⁠📨 SQS UI

A lightweight web UI + Go backend to inspect and interact with AWS SQS queues.

⁠✨ 0.2.0 Highlights (since 0.1.x)

• Runtime queue switch dialog (update queue name or full queue URL without restarting).
• Improved message sending flow with countdown + advisory about AWS SQS metric lag.
• UI advisory about eventual consistency (counts may lag or exclude in-flight messages).
• Consistent error panels and simplified Tailwind classes for readability.
• Purge + config update actions auto-clear message panel.
• Optional labels & OCI metadata in Dockerfile.

⁠🗂️ Project Structure

⁠💻 UI Features

• Fetch queue info (region, URL, approximate counts, status).
• Receive (peek) messages (non-destructive unless backend deletes—see notes).
• Send a message with post-send automatic refresh.
• Purge all messages (dangerous, explicit confirmation).
• Change queue at runtime (name or full URL).
• Advisory on SQS eventual consistency after refresh.
• Responsive Tailwind layout, no frameworks.

⁠🔌 API Endpoints (Current Assumed Set)

⁠⚙️ Configuration (Env Vars)

⁠🏃 Run Locally

# Using Makefile (ensure a queue exists or credentials allow create)
export QUEUE_NAME=my-queue
export AWS_REGION=us-east-1
export AWS_PROFILE=example
make run-local
# Open:
http://localhost:8080

Direct go build:

go build -o sqs-ui ./cmd/server
./sqs-ui

⁠🐳 Docker Usage

Pull & run:

# Full configs if they are already exported; if not, add them explicitly
docker run --rm -p 8080:8080 \
  -e QUEUE_NAME=my-queue \
  -e AWS_REGION \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  --name sqs-ui \
  pachecoc/sqs-ui:0.2.0

# If AWS SSO / temp creds, you can still start without queue name or URL but UI will show an error until set
docker run --rm -p 8080:8080 \
  -e AWS_REGION \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_SESSION_TOKEN \
  --name sqs-ui \
  pachecoc/sqs-ui:0.2.0

⁠🔐 Credentials & Security

• Best: Use EKS Pod Identities or IAM roles (EC2, ECS, IRSA, etc.).
• Avoid committing credentials.
• Distroless image runs as non-root.
• Consider a read-only role if you do not need Send/Purge in certain deployments.

⁠⏱️ SQS Semantics & Consistency

• NumberOfMessages is eventually consistent; newly sent or received messages may not reflect instantly.
• Receiving messages makes them temporarily invisible for their visibility timeout; they are not deleted unless explicitly deleted (or your server logic deletes on receive—verify your implementation[...]
• Purge is asynchronous; large queues may take seconds to clear.

⁠🧭 (Future Work / Suggestions)

⁠🧪 Development

(If tests are added later, integrate make test.)

⁠🏗️ Build Metadata

Injected at build time (see Dockerfile):

• Version
• Commit
• BuildTime

⁠❓ FAQ

Why do counts not update immediately after sending a message?
SQS attributes are approximate and eventually consistent; refresh again after a few seconds.

Why did a fetched message “disappear”?
It’s in-flight (invisible) due to receive; it reappears after the visibility timeout unless deleted.

Can I view messages without impacting visibility?
Pure “peek” isn’t natively supported by SQS. Standard receive temporarily hides messages.

⁠📄 License

MIT © Gustavo Pacheco