170 lines
14 KiB
Markdown
170 lines
14 KiB
Markdown
# МАНУАЛ: что делать дальше (состояние на 2026-10-08)
|
||
|
||
> Файл для НОВОГО чата. Прочитай его первым, затем документы из раздела 2.
|
||
> Репозиторий: `/home/naeel/nubes/SQS_und_IoT/SQS-service` (сервис `shared-sqs`).
|
||
> Всё, что описано как «сделано», уже в ветке `main` и на сервере (`origin/main`).
|
||
|
||
---
|
||
|
||
## 1. Где мы сейчас
|
||
|
||
**Код SQS готов и запушен.** Ветка `main` = `origin/main`, рабочая копия чистая.
|
||
|
||
Что сделано за 2026-10-05…08:
|
||
- закрыт весь план доработок P0/P1/P2 (`doc/thinking/plan-for-flash-2026-10-05.md`);
|
||
- P1.2 — индексация сообщений (tombstone + индексы + амортизированная компакция);
|
||
- полный код-ревью сервиса + исправления (утечка блокировки очереди, DLQ в батче,
|
||
гонка лимита тенантов, потеря `NubesSub`, общий HTTP-клиент);
|
||
- интеграционные прогоны: `api_test.sh` 22/22, `sdk_test.py` 15/15, `fifo_dlq_probe.py` — PASS,
|
||
стресс 3×2000 сообщений — без зависаний.
|
||
|
||
**Прод-сервис никто не использует** (podтверждено владельцем), IoT переделывается с нуля.
|
||
Поэтому мы свободны менять архитектуру без обратной совместимости.
|
||
|
||
## 2. Документы, которые надо прочитать в этом порядке
|
||
|
||
| Документ | Что внутри |
|
||
|---|---|
|
||
| `doc/thinking/architecture-analysis-2026-10-08.md` | **ГЛАВНЫЙ**: решения по размещению и разбиению (публичный SQS, обход через ВМ, модульный монолит data-plane/control-plane) |
|
||
| `doc/thinking/nubes-large-body-workaround-findings-2026-10-08.md` | как та же болезнь платформы обойдена в `~/nubes/drhider` (буфер на ВМ, pull вместо push) — со ссылками «файл:строка» |
|
||
| `doc/thinking/nubes-workaround-applicability-to-sqs-2026-10-08.md` | применимость к SQS: 4 варианта, обязательные замеры, техусловия (Host для подписи, внешние `QueueUrl`, TLS) |
|
||
| `HISTORY/2026-10-07-session-log.md` | журнал правок: что и почему менялось, найденные дефекты, уроки |
|
||
| `doc/thinking/nubes-ticket.md` | исходная диагностика сетевой болезни (MSS/MTU + таймер шлюза). **Тикет отправлять не нужно** — см. `HANDOFF-NEW-CHAT.md`, раздел 7 |
|
||
| `doc/thinking/plan-for-flash-2026-10-05.md` | исходный план доработок (выполнен) |
|
||
| `HANDOFF-NEW-CHAT.md` | доступы, креды, конфигурация кластера, история проекта |
|
||
|
||
## 3. Принятые решения (не пересматривать без причины)
|
||
|
||
1. **SQS — публичный сервис**, как AWS SQS / YMQ. Внешний доступ обязателен,
|
||
совместимость с AWS SDK — обязательна.
|
||
2. **Сетевую болезнь платформы не «лечим» тикетом** — обходим: публичная точка входа
|
||
на ВМ, минуя managed-шлюз.
|
||
3. **Пока — ВМ (сейчас `5.172.178.213`), потом отдельная прод-ВМ.** Девопсов не дёргаем,
|
||
пока не отлажено; затем — уже с доказательствами (tcpdump, период 31–33 с, MSS 1448).
|
||
4. **«Без монолитов» = модульный монолит**: в отдельные процессы выносим только то,
|
||
что живёт по-разному. Для SQS граница одна: **data-plane** (очереди/сообщения/SigV4)
|
||
и **control-plane** (тенанты, креды, админ). Биллинг/метрики/UI — модули, не сервисы.
|
||
5. **Ограничение, которое важнее разбиения**: ядро очередей держит состояние в памяти
|
||
одного пода → одиночка. Пока хранилище не вынесено, «не монолит» ≠ «масштабируется».
|
||
|
||
## 4. План работ (порядок обязателен)
|
||
|
||
### Шаг 1. Проверить гипотезу на ВМ — БЕЗ кода (критерий входа: домен и сертификат)
|
||
Цель: убедиться, что на ВМ болезни нет, **до** вложений в разбиение.
|
||
|
||
1. Собрать бинарник: `make build` (или `CGO_ENABLED=0 go build -o shared-sqs ./app/cmd/`).
|
||
2. Поднять на ВМ (memory-only достаточно): см. команды в разделе 5.
|
||
3. Поставить nginx с TLS на выбранный домен, проксировать на `127.0.0.1:4100`.
|
||
**Обязательно** `proxy_set_header Host $host;` — иначе AWS-подпись не сойдётся
|
||
(сервис берёт хост из запроса: `app/auth/auth_middleware.go:315-317`).
|
||
4. Замерить **с внешней машины** (не с ВМ): малые тела, 1 КБ, 10 КБ, 100 КБ, 256 КБ,
|
||
плюс длинный прогон на таймауты. Инструменты: `tests/tcp_mtu_probe.py`,
|
||
`tests/long_compare_local.py`, `tests/compare_ymq_vs_shared.py`.
|
||
5. **Критерий успеха:** 0 зависаний ~51 с, 0 таймаутов 31–33 с.
|
||
|
||
Если гипотеза не подтвердится — СТОП, вернуться к разбору (раздел 2, документ о применимости).
|
||
|
||
### Шаг 2. Код: разбиение на два процесса
|
||
- `data-plane` — SQS API и очереди (`app/gosqs/*`, `app/router/router.go`, `app/auth/auth_middleware.go`).
|
||
- `control-plane` — админка (`app/admin/admin.go`) и управление тенантами (`app/tenant/*`).
|
||
- Что уже учитывать при разбиении:
|
||
- адреса очередей формируются жёстко: `app/gosqs/tenant_helpers.go:29-37` →
|
||
`http://{region}.{host}:{port}/{tenantID}/{queue}`; хост/порт только из `app/conf/goaws.yaml`
|
||
(`app/conf/config.go:87-90`), env-переменных для Host нет → **внешние `QueueUrl` потребуют правки**;
|
||
- подпись SigV4 считается по заголовку `Host` (см. выше);
|
||
- ключ очереди — `{accessKey}:{queueName}` (`app/gosqs/tenant_helpers.go:15`).
|
||
|
||
### Шаг 3. Код: вынести состояние (стратегический пункт)
|
||
- Сейчас: память — источник истины, Redis — write-through (`app/persistence/redis.go`,
|
||
`LoadAllQueues`), восстановление при старте.
|
||
- На ВМ поставить Redis и решить, как читать: остаться write-through или перейти к Redis
|
||
как источнику истины (тогда появится возможность нескольких экземпляров).
|
||
- Это решение определяет потолок сервиса (сейчас — один под).
|
||
|
||
### Шаг 4. IoT — отдельно, после SQS
|
||
- Внешний MQTT-канал неизбежен (устройства), но там только мелкая телеметрия;
|
||
критичен разрыв wss ~150 с (лечится переподключением).
|
||
- Крупные тела устройств через managed-шлюз не пускать (лимит/дробление/приём на ВМ).
|
||
- IoT переделывается с нуля не монолитом: bridge (MQTT), consumer (→storage), API.
|
||
|
||
## 5. Команды (проверены)
|
||
|
||
**Локальный запуск (memory-only, без Redis):**
|
||
```bash
|
||
cd /home/naeel/nubes/SQS_und_IoT/SQS-service
|
||
go build -o /tmp/shared-sqs ./app/cmd/
|
||
SHARED_SQS_SEED_DEMO=true /tmp/shared-sqs --admin-token=dev-token-123 --port=4100
|
||
# креды демо-тенанта печатаются в лог при старте
|
||
```
|
||
⚠️ Не запускать через `| head` — SIGPIPE убивает процесс на середине теста.
|
||
|
||
**Проверки кода:**
|
||
```bash
|
||
go build ./... && go vet ./... && go test -race ./app/...
|
||
```
|
||
|
||
**Деплой на ВМ:**
|
||
- зеркало репозитория: `naeel@5.172.178.213:~/terra/SQS-service`;
|
||
- SSH: `ssh -i ~/.ssh/naeel_vm_id_ed25519 naeel@5.172.178.213`;
|
||
- ⚠️ порт **443 на 213 занят** (nginx/xray/hysteria), поэтому публичная точка SQS —
|
||
отдельный домен на существующем nginx (виртуальный хост/SNI) или отдельный порт;
|
||
- ⚠️ в образе `Dockerfile` зашит `REDIS_ADDR` внутреннего кластера — на ВМ переопределить
|
||
(или не задавать, чтобы работать memory-only).
|
||
|
||
**Сборка образа (если через Docker):** `make docker-build` (`Makefile`, образ `naeel/shared-sqs`).
|
||
|
||
## 6. Грабли и правила (не наступать повторно)
|
||
|
||
1. `app/cmd` в `.gitignore` → при добавлении файлов `git add -f app/cmd/...`.
|
||
2. `deployments/` в этом репозитории **нет** — не искать.
|
||
3. `Queue.Messages` — tombstone-хранилище: менять только через `AppendMessage`/`RemoveIndex`/
|
||
`Compact`/`Reset`; число живых = `queue.LiveCount()`, а НЕ `len(queue.Messages)`
|
||
(`app/models/models.go`).
|
||
4. После `GetLocked`/`GetRLocked` — `defer Unlock` **до** любых `return` (иначе очередь
|
||
зависает навсегда; было в `receive_message.go`, исправлено).
|
||
5. Интеграционные тесты: `tests/api_test.sh` читает `ENDPOINT`, python-тесты — `ENDPOINT_URL`.
|
||
`boto3` в системе нет (PEP 668) → скачать колеса `pip download boto3`, распаковать в `/tmp`
|
||
и запускать с `PYTHONPATH`.
|
||
6. Лимит очередей тенанта = 10 → после упавших прогонов чистить очереди.
|
||
7. Диагностика зависаний сервиса: стек горутин по `kill -QUIT` (SIGQUIT).
|
||
8. Правки ingress на платформе — только через `ShturvalServiceConfig` (kubectl откатывает ArgoCD).
|
||
|
||
## 7. Правила работы с владельцем (обязательные)
|
||
|
||
- Коммитить после каждой логически завершённой правки; **пуш — только по прямой команде**.
|
||
- Документировать всё, включая собственные ошибки (HISTORY + `doc/thinking/`).
|
||
- Не выполнять `terraform apply`/`destroy`, не менять платформу, не удалять инстансы.
|
||
- Не расширять область работ; не лезть в соседние репозитории без прямой команды.
|
||
- Рекомендация без замера — не рекомендация, а догадка: сначала мерить, потом предлагать.
|
||
- Вопрос от владельца = только ответ (ничего не делать, пока не последует команда).
|
||
|
||
## 8. Открытые вопросы (нужны решения владельца)
|
||
|
||
1. **Домен и сертификат** для публичной точки SQS на ВМ (порт 443 занят → виртуальный хост?).
|
||
2. **Отдельная прод-ВМ** — когда создавать и с какими параметрами (пока хватит 213 для тестов;
|
||
хватит ли 213 — проверить замером: ядра, память, диск, загрузка).
|
||
3. **Redis на ВМ** — ставить сейчас или пока memory-only.
|
||
4. **Вынос состояния** (Шаг 3) — когда начинать; это определяет масштабируемость.
|
||
5. **Клиенты без явного `endpoint_url`** — есть ли такие (влияет на внешние `QueueUrl`).
|
||
|
||
## 9. Карта кода (что где)
|
||
|
||
| Путь | Ответственность |
|
||
|---|---|
|
||
| `app/cmd/goaws.go` | точка входа, флаги, загрузка конфига, periodic tasks, HTTP-сервер |
|
||
| `app/router/router.go` | HTTP-роутинг, лимит тела 3 МБ, биллинг/метрики по операциям |
|
||
| `app/auth/auth_middleware.go` | SigV4 (header + presigned), извлечение тенанта |
|
||
| `app/auth/jwt.go`, `app/auth/cache.go` | валидация JWT через внешний API + кэш |
|
||
| `app/gosqs/*` | SQS-операции (send/receive/delete/visibility/queue/attributes/tags) |
|
||
| `app/gosqs/receive_message.go` | long-polling, выдача сообщений (в т.ч. per-queue лок) |
|
||
| `app/gosqs/gosqs.go` | фоновый тик: retention, дедупликация, видимость, DLQ |
|
||
| `app/models/models.go` | `Queue`/`SqsMessage`, индексация (tombstone), FIFO-состояние |
|
||
| `app/models/globals.go` | `SyncQueues`: map очередей + tenant-индекс + блокировки |
|
||
| `app/persistence/redis.go` | write-through в Redis, загрузка при старте, переподключение |
|
||
| `app/admin/admin.go` | админка (тенанты/очереди/сообщения), UI-API по JWT |
|
||
| `app/tenant/tenant_store.go` | хранилище тенантов, генерация кредов, авто-провижининг по JWT |
|
||
| `app/billing/billing.go` | учёт операций в PostgreSQL (воркер + буфер) |
|
||
| `app/metrics/*` | Prometheus-метрики и gauge-обновление |
|
||
| `app/conf/goaws.yaml` | Host/Port/Region, дефолты очередей (используется для URL) |
|
||
| `tests/*` | интеграционные проверки (aws CLI, boto3, пробы сети/MTU) |
|