imap-copier/docs/superpowers/specs/2026-07-01-imap-copier-design.md

# imap-copier — Design Spec

**Дата:** 2026-07-01
**Статус:** утверждён к планированию

## Context

Нужна утилита для массового переноса почты между IMAP-провайдерами — «улучшение»
классического imapsync с современным веб-интерфейсом. Задания создаются вручную
или импортом CSV. Перенос должен показываться в реальном времени, быть
идемпотентным (повторный запуск не дублирует письма) и не оседать телами писем на
диске хоста с софтом. Итог — self-hosted контейнер, поднимаемый за Caddy.

## Ключевые решения (зафиксированы с заказчиком)

- **Движок:** нативный Go на `github.com/emersion/go-imap/v2` (не обёртка над Perl-imapsync).
- **Data path:** стриминг в RAM. Тело письма живёт в памяти только на время одного
  `FETCH → APPEND`. Тела писем НИКОГДА не пишутся на диск хоста. Ящик на 500 ГБ
  переносится при near-zero использовании диска.
- **Семантика:** только копирование (недеструктивно). Источник не изменяется.
  `move`/удаление из источника — НЕ реализуется (осознанно отвергнуто как рискованное).
- **Хранилище состояния:** PostgreSQL.
- **Дедуп:** по `Message-ID`, при отсутствии — fallback `md5(From|To|Subject|Date|Size)`.
- **IMAP не умеет server-to-server.** «Напрямую» = один процесс-посредник, стриминг в
  памяти, без спула на диск и без отдельного прокси-хопа. Это физический максимум для IMAP.

## Архитектура

Один Docker-образ: Go-бинарник встраивает собранный React через `embed.FS`
(REST API + WebSocket + статика в одном процессе). Рядом — Postgres. Сверху — Caddy.

```
┌─────────────────── Docker compose ───────────────────┐
│  caddy    (:80, опц. :443 + Let's Encrypt ACME)       │
│    └─ reverse_proxy → app:8080                          │
│  app      (Go): REST + WebSocket + embed(React)        │
│    └─ worker pool → go-imap src/dst соединения          │
│  postgres (внутренняя сеть, volume)                     │
└─────────────────────────────────────────────────────────┘
На диске хоста — только Postgres. Тел писем нет.
```

### Компоненты (границы ответственности)

| Компонент | Что делает | Зависит от |
|---|---|---|
| `httpapi` | REST-роуты, auth-middleware, отдача embed React | store, orchestrator |
| `wshub` | пул WebSocket-подключений, рассылка событий по `task_id` | — |
| `store` | доступ к Postgres (endpoints/tasks/accounts/runs/migrated_messages), шифрование паролей | pgx |
| `imapx` | обёртка go-imap: connect, тест, list folders, stream FETCH→APPEND, вычисление message_key | go-imap/v2 |
| `orchestrator` | worker pool, прогон задания по ящикам/папкам, дедуп-проверка, эмит событий в wshub, запись в runs | store, imapx, wshub |
| `csvimport` | парсинг/валидация CSV → accounts | store |
| `config` | env: AUTH_*, ENC_KEY, SESSION_SECRET, DB DSN, параллелизм | — |

## Модель данных (Postgres)

- **endpoints** — `id, role_label, host, port, tls_mode (ssl|starttls|plain), created_at`.
- **tasks** — `id, name, src_endpoint_id, dst_endpoint_id, status, folder_mapping (jsonb), created_at`.
- **accounts** — `id, task_id, src_login, src_pass_enc, dst_login, dst_pass_enc, test_src_status, test_dst_status, copied_count, skipped_count, error_count, status`.
- **runs** — `id, task_id, started_at, finished_at, status, total_copied, total_skipped, total_errors`.
- **migrated_messages** — `id, account_id, folder, message_key, copied_at`. **UNIQUE(account_id, message_key)**.

Пароли ящиков шифруются AES-256-GCM, ключ — env `ENC_KEY` (32 байта, base64).
Plain-пароли в БД не хранятся. Пароли не логируются и не возвращаются в API.

Миграции — `golang-migrate`, файлы в `migrations/`.

## Дедуп (идемпотентность повторного запуска)

Перед `APPEND`:
1. Вычислить `message_key`: `Message-ID` если есть, иначе `md5(From|To|Subject|Date|Size)`.
2. `SELECT 1 FROM migrated_messages WHERE account_id=$1 AND message_key=$2`.
3. Есть → инкремент `skipped_count`, письмо пропускается.
4. Нет → `APPEND` → `INSERT ... ON CONFLICT DO NOTHING` → инкремент `copied_count`.

Порядок: сначала `APPEND`, затем запись ключа. При падении между ними — на следующем
запуске письмо считается новым и переносится снова; возможный редкий дубль на приёмнике
приемлемее, чем потеря письма. (Документируется как известный trade-off.)

## Тесты подключения (обязательны перед запуском)

- **Test endpoints:** TCP + TLS handshake + `CAPABILITY` к src и dst. Результат per-endpoint.
- **Test accounts:** `LOGIN` в каждый src- и dst-ящик, `LIST` папок, `STATUS` (кол-во писем).
  Результат per-account (`test_src_status`, `test_dst_status`).
- **Гейт:** `POST /api/tasks/:id/run` возвращает 409, если не все аккаунты прошли обе проверки.

## Движок переноса

Worker pool (дефолт 4 параллельных ящика, `WORKER_CONCURRENCY`). На ящик:
1. Connect src (read-only) + dst.
2. `LIST` папок src → применить `folder_mapping` (дефолт 1:1; спецпапки Gmail — через маппинг).
3. Для каждой папки: `SELECT` src (EXAMINE), стриминговый `FETCH` (UID+Envelope) → дедуп-фильтр.
4. Для новых писем: `FETCH BODY[]` через `.Next()` (без буферизации крупных литералов) →
   `APPEND` в dst с сохранением флагов и internal date → запись ключа → эмит прогресса.
5. Ошибка на письме → лог + `error_count`, продолжаем со следующего (не валим весь ящик).

Тело письма держится в памяти только на время одной итерации FETCH→APPEND.

## WebSocket (реалтайм)

- Подключение: `GET /ws?task_id=…` (под auth).
- События (JSON): `run_started`, `account_started`, `folder_progress` (folder, done/total),
  `progress` (батч скопированных, throttle ~1/сек на аккаунт), `account_done`,
  `error`, `run_done`.
- Начальное состояние при (пере)подключении — `GET /api/tasks/:id` (REST), затем поток WS.

## Импорт CSV

Endpoints src/dst задаются в UI один раз. CSV: по строке на ящик —
`src_login,src_pass,dst_login,dst_pass`. Парсинг → валидация (формат, дубли логинов,
пустые поля) → предпросмотр → создание `accounts` для задания. Пароли сразу шифруются.

## Логирование

`slog` (JSON) в stdout контейнера. Per-account и суммарные счётчики (copied/skipped/errors)
пишутся в `accounts`/`runs` и доступны в UI (экран лога задания). Пароли/тела писем в лог не попадают.

## Авторизация UI

Логин/пароль из env (`AUTH_USER`, `AUTH_PASS`). После логина — signed cookie
(HMAC-SHA256, `SESSION_SECRET`). Всё под auth, кроме `/login`, `/api/login`, `/healthz`.

## Стек и инфраструктура

- **Backend:** Go 1.22+, `emersion/go-imap/v2`, стандартный `net/http` (роут-паттерны 1.22),
  `coder/websocket`, `jackc/pgx/v5`, `golang-migrate`, `slog`.
- **Frontend:** React + TypeScript + Vite, встраивается в бинарник (`embed.FS`).
- **Инфра:** multi-stage Dockerfile (node build → go build → scratch/distroless),
  `docker-compose.yml` (app + caddy + postgres), `Caddyfile` с профилями `:80` (дефолт)
  и `:443` + `tls` (ACME Let's Encrypt) через env-переключатель домена.

## Тестирование (verification)

- **Unit:** дедуп-ключ (Message-ID и fallback), шифрование паролей, CSV-парсер,
  folder-mapping, session-cookie sign/verify.
- **Integration:** поднять тестовый IMAP-сервер (greenmail в контейнере или
  `go-imap` server) → прогнать перенос → проверить идемпотентность (второй запуск =
  0 copied, N skipped).
- **E2E (prod):** деплой через docker-compose → логин в UI → создать endpoints →
  импорт CSV → тесты подключения → запуск → наблюдать WebSocket-прогресс →
  повторный запуск не дублирует.

## Осознанно НЕ делаем (YAGNI)

- Move/удаление из источника.
- Спул писем на диск, отдельный прокси-сервис.
- Мульти-юзер/RBAC (один env-аккаунт).
- Внешняя очередь/брокер — worker pool в процессе достаточно.

## Открытые дефолты (принимаются, если не оспорены)

- Роутер: стандартный `net/http`.
- Миграции: `golang-migrate`.
- Параллелизм: 4 ящика, конфигурируемо.