# 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. Обновлять при значимых изменениях.*