Nail/SQS-service

Fork 0

Files

T

Naeel 6fb160f8ae docs: add ONBOARDING.md — full context memo for new chat sessions

2026-04-10 16:51:55 +03:00

7.2 KiB

Raw Blame History

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/  — утилиты

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

Глобальный мьютекс models.SyncQueues — Lock/Unlock на ВСЕ операции. Bottleneck при нагрузке.
Нет DLQ (Dead Letter Queue)
Long Polling naïve — sleep loop вместо push
Нет rate limiting per tenant
Нет метрик (Prometheus)
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. Рекомендации по порядку

Сначала биллинг — простой счётчик в Redis, можно сделать за 1 сессию
Затем audit log — middleware логирует tenant_id + action + timestamp
Затем encryption at rest — обёртка над Redis get/set
В последнюю очередь — 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. Обновлять при значимых изменениях.

7.2 KiB Raw Blame History Unescape Escape