SQS-service/ONBOARDING.md

ONBOARDING.md — Памятка для нового чата / агента

Дата: 2026-04-10

Автор: GitHub Copilot (Claude Opus 4.6)

---

Что это за проект

SQS-service — multi-tenant сервис очередей сообщений, совместимый с AWS SQS API. Единственный в open source проект такого рода (подтверждено поиском по GitHub: 0 результатов по multi-tenant sqs compatible).

Ближайшие аналоги — ElasticMQ (Scala) и GoAws (Go), но оба single-tenant и предназначены только для local dev/testing.

---

Откуда взялся код

Основан на GoAws (https://github.com/Admiral-Piett/goaws). Первый коммит в sless: shared-sqs: Этап 1 — клон GoAWS, удаление SNS, go build OK Затем поверх GoAws построены: мультитенантность, auth, admin API, WebUI, Redis persistence.

---

Текущая версия

v0.1.14 — работает в кластере iot-naeel

Параметр	Значение
Endpoint	https://qu.kube5s.ru
IP	185.247.187.151
Admin token	sqs-admin-7a7d8bd0c060a75c198d48680f34077a
Demo Access Key	SSAK-demo-shared-sqs
Demo Secret Key	demo-secret-key-shared-sqs-ngcloud-2026
Docker image	naeel/shared-sqs:v0.1.14
Redis	rfrm-redisk8s.54467f74-67f5-4ca7-9b4a-bdd50e8c23d6.svc.cluster.local:6379
Kubeconfig	/home/naeel/.kube/iot-naeel.yaml (на ВМ)
Namespace	shared-sqs

---

Инфраструктура — ВАЖНО

ВМ и монтирование

• ВМ: naeel@5.172.178.213
• SSH-ключ: ~/.ssh/naeel_vm_id_ed25519
• Реальный путь на ВМ: /home/naeel/terra/SQS-service
• Смонтировано как: /home/naeel/remote_dev/SQS-service (sshfs)

⛔ КРИТИЧЕСКОЕ ПРАВИЛО

/home/naeel/remote_dev/SQS-service — это СМОНТИРОВАННАЯ ПАПКА. Физически файлы на ВМ. ВСЕ команды выполнять ТОЛЬКО через SSH на ВМ:

ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 \
    naeel@5.172.178.213 'cd /home/naeel/terra/SQS-service && <КОМАНДА>'

Через IDE — ТОЛЬКО редактирование файлов. Терминальные команды — ТОЛЬКО SSH.

---

Архитектура кода

app/
├── cmd/goaws.go         — точка входа, HTTP сервер
├── cmd/seed.go          — загрузка демо-данных
├── models/              — Queue, Message, Tenant, SyncQueues (глобальный мьютекс!)
├── gosqs/               — реализация SQS API (CreateQueue, SendMessage, ReceiveMessage и т.д.)
├── admin/admin.go       — Admin API: создание/получение тенантов
├── tenant/tenant_store.go — хранилище тенантов (access key → tenant)
├── auth/auth_middleware.go — AWS Signature V4 парсинг credential
├── persistence/redis.go — Redis write-through adapter
├── router/router.go     — маршруты HTTP
├── ui/index.html        — WebUI (встроен через embed.go)
└── utils/, interfaces/  — утилиты

---

Известные проблемы (не трогать пока не попросят)

1. Глобальный мьютекс models.SyncQueues — Lock/Unlock на ВСЕ операции. Bottleneck при нагрузке.
2. Нет DLQ (Dead Letter Queue)
3. Long Polling naïve — sleep loop вместо push
4. Нет rate limiting per tenant
5. Нет метрик (Prometheus)
6. Single pod — нет горизонтального масштабирования

---

Что делать дальше (от пользователя)

1. Статистика для биллинга

Нужен сбор метрик по каждому тенанту:

• Количество отправленных/полученных сообщений
• Количество созданных очередей
• Объём данных (bytes in/out)
• Время жизни сообщений

Где встраивать: app/gosqs/send_message.go, app/gosqs/receive_message.go, app/gosqs/create_queue.go Где хранить: Новый пакет app/billing/ или расширить app/persistence/redis.go Формат: Redis HINCRBY per tenant per day, или отдельная таблица в PostgreSQL

2. Защита конфиденциальности

• Тела сообщений не должны логироваться
• Admin API должен быть доступен только из внутренней сети (или по отдельному порту)
• Тенанты не должны видеть друг друга (уже реализовано на уровне auth)
• Рассмотреть шифрование тел сообщений at rest (в Redis)
• Audit log: кто, когда, что делал

Где встраивать: middleware в app/router/router.go, новый пакет app/audit/

3. Рекомендации по порядку

1. Сначала биллинг — простой счётчик в Redis, можно сделать за 1 сессию
2. Затем audit log — middleware логирует tenant_id + action + timestamp
3. Затем encryption at rest — обёртка над Redis get/set
4. В последнюю очередь — rate limiting (зависит от биллинга)

---

Тесты

Скрипт	Описание	Как запускать
tests/quick_test.sh	6 базовых тестов	bash tests/quick_test.sh
tests/hardcore_test.sh	Суровые тесты	bash tests/hardcore_test.sh
tests/shared_sqs_test.sh	E2E тесты	bash tests/shared_sqs_test.sh

ВАЖНО: В tests/quick_test.sh используются demo credentials (SSAK-demo-shared-sqs). В tests/hardcore_test.sh может быть admin token — НЕ КОММИТИТЬ в публичные репы!

---

Git workflow

• Репо: https://gitea.services.ngcloud.ru/Nail/SQS-service
• Ветка: main
• Коммитить и пушить после каждого завершённого этапа (правило из copilot-instructions)
• Все команды git — через SSH на ВМ

---

Сборка и деплой

# На ВМ:
cd /home/naeel/terra/SQS-service

# Сборка
docker build -t naeel/shared-sqs:v0.1.15 .
docker push naeel/shared-sqs:v0.1.15

# Деплой
export KUBECONFIG=/home/naeel/.kube/iot-naeel.yaml
kubectl set image deployment/shared-sqs shared-sqs=naeel/shared-sqs:v0.1.15 -n shared-sqs
kubectl rollout status deployment/shared-sqs -n shared-sqs

---

Создано: 2026-04-10. Обновлять при значимых изменениях.