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

2026-04-10 16:51:55 +03:00
parent c3ba2dcae4
commit 6fb160f8ae
1 changed files with 168 additions and 0 deletions
@@ -0,0 +1,168 @@
+# 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 на ВМ:**
+
+```bash
+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 на ВМ
+
+---
+
+## Сборка и деплой
+
+```bash
+# На ВМ:
+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. Обновлять при значимых изменениях.*