From 58fe13cc42d22251e23bd9e1929f710bdad7ef91 Mon Sep 17 00:00:00 2001 From: Vladislav Kunetskiy Date: Wed, 21 Oct 2026 22:11:04 +0300 Subject: [PATCH] =?UTF-8?q?lab4:=20=D0=B4=D0=B5=D1=82=D0=B0=D0=BB=D1=8C?= =?UTF-8?q?=D0=BD=D1=8B=D0=B9=20=D0=BF=D0=BB=D0=B0=D0=BD=20=D1=80=D0=B5?= =?UTF-8?q?=D0=B0=D0=BB=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- LAB4-PLAN.md | 1096 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1096 insertions(+) create mode 100644 LAB4-PLAN.md diff --git a/LAB4-PLAN.md b/LAB4-PLAN.md new file mode 100644 index 00000000..ed28c462 --- /dev/null +++ b/LAB4-PLAN.md @@ -0,0 +1,1096 @@ +# План реализации лабораторной 4 — S3-хранилище и вложения + +Статус: рабочий план для агента-исполнителя. Выполнять фазы по порядку, после каждой — гейт приёмки. +База: ветка `lab4`, коммит `c4e8d48` (реальная история lab1–lab3 + skeleton lab4, контракт 1.4.0). +Цель: оценка **5**, трек **1 (presigned direct upload)**. +Стек: Go 1.27, PostgreSQL, SeaweedFS 3.80, HAProxy, Docker Compose. + +--- + +## 0. Обязательные решения и их обоснование + +### 0.1. MinIO недоступен — используем SeaweedFS + +Проверено 2026-10-21: + +- `docker pull minio/minio` → `pull access denied`, репозиторий удалён с Docker Hub; +- `https://dl.min.io/server/minio/release/linux-arm64/minio.RELEASE.2025-09-07T16-13-09Z` → HTTP 410; +- `quay.io/minio/minio` → `no such manifest`; +- `minio/mc` также отсутствует. + +Контракт `contracts/infrastructure.json` разрешает `choose_one: [MinIO, SeaweedFS, RustFS]`. +Берём **SeaweedFS 3.80**: версия закреплена, multi-arch (amd64/arm64), поддерживает presigned GET/PUT, +декларативные identities с path-level правами, HeadObject, CopyObject, ListObjectsV2, lifecycle. +Spike подтвердил: presigned PUT 200, просроченный URL 403, анонимный GET 403, запрет чужого префикса 403, +CopyObject/Delete/Head/Get работают. + +Пин: `chrislusf/seaweedfs:3.80@sha256:1055999e08eed1789b0ae45d235126e4495e23d3fb9d6396293fd42539b1ae6a`. + +### 0.2. ogen v1.24.0 не умеет генерировать контракт 1.4.0 + +`Message` и `CreateMessage` содержат `anyOf` с двумя безымянными ветвями. ogen падает с +`Feature "sum types with same names" is not implemented`. Включение +`ignore_not_implemented` **молча выкидывает операции `CreateMessage`/`ListMessages`** — так делать нельзя. + +Решение: генерировать из производной спеки, где удалён только `anyOf` у `Message` и `CreateMessage`. +Канонический `contracts/openapi.json` не меняется. Кросс-полевое правило +«text непустой ИЛИ attachment_ids непустой» реализуется в сервисе и проверяется тестами. +Инструмент: `tools/specgen/main.go` (чистый Go, без зависимостей), результат — `.cache/openapi.codegen.json` +(в `.gitignore`). `make generate-api` вызывает `go run ./tools/specgen` перед ogen. +`tools/specgen` обязан упасть, если в контракте появился любой другой `anyOf` — это защита от +молчаливой генерации неверных типов. + +### 0.3. Границы + +- Метаданные — только PostgreSQL; байты — только S3 (временный файл на API допустим и удаляется до 201). +- Обязательный proxy-upload/download сохраняется; presigned-путь — дополнительный. +- lab5 (thumbnail, 202/queued) не реализуем; `variants` всегда `[]`, `status` всегда `ready`. +- Контракт не редактируем; presign-эндпоинты монтируются вне ogen. + +--- + +## 1. Матрица требований контракта + +Каждая строка должна иметь тест и/или evidence-файл. Галочка ставится только после фактического прогона. + +| # | Требование | Реализация | Проверка | +|---|---|---|---| +| 1 | `POST /chats/{id}/attachments?filename=` сырые PNG/JPEG, не multipart | ogen `UploadAttachment`, body streaming | `make test`, `student-tests/attachments_negative.py` | +| 2 | 10 MiB = 10 485 760 байт; превышение — 413 | per-route `MaxBytesReader` + счётчик | тест 10 MiB+1 | +| 3 | MIME по содержимому; чужой/битый формат — 415 | sniff + структурный парсер | подмена MIME, битый PNG | +| 4 | ≤ 40 млн пикселей; превышение — 413; лимит до декодирования | разбор IHDR/SOF, без полного raster | PNG 10000×10000 header | +| 5 | filename 1–255 code points; `/`, `\`, NUL, control — 400 | `utf8.RuneCountInString`, `unicode.IsControl` | табличные тесты + HTTP | +| 6 | 201 `Attachment` `status=ready`, `variants=[]`, `error_code=null` только после S3+БД | pending→S3 put→ready | smoke + сбой между шагами | +| 7 | `Message.attachment_ids` 0–10 уникальных, по умолчанию `[]` | ogen + сервис | smoke, unit | +| 8 | `text=""` разрешён при наличии вложения; пусто и без вложений — 400 | сервис | HTTP-тест | +| 9 | Вложения только из этого чата; чужое/неизвестное — 404 | SQL `chat_id` + membership | тест | +| 10 | Failed-вложение прикреплять нельзя (409) | проверка статуса | unit (failed-строка) | +| 11 | `GET /attachments/{id}` и `/content` только участникам; иначе 404 | один SQL-запрос с `chat_members` | smoke, outsider | +| 12 | Download — байты с истинным Content-Type, без redirect | streaming `GetObject` | сравнение SHA, заголовок | +| 13 | `variant` по умолчанию `original`; отсутствующий вариант — 404 | ogen enum + проверка | тест `?variant=thumbnail` → 404 | +| 14 | Ready metadata: `error_code=null`; sha/размер/тип описывают оригинал | маппинг | smoke | +| 15 | Не раскрывать ключи бакета, адреса, credentials | маппинг + логи | ревью ответов/логов | +| 16 | S3 в общем стенде; bucket приватный | compose + identities без anonymous | anonymous GET 403 | +| 17 | Upload → stop реплики → download другой репликой | stateless S3 + 2 API | `student-tests/attachment_failover.py` | +| 18 | Restart стенда с volumes сохраняет метаданные и оригинал | named volumes | evidence | +| 19 | Уровень 4: негативные тесты | см. §8 | `student-tests/attachments_negative.py` | +| 20 | Отказ между S3 и БД не оставляет вечных объектов; grace period | pending + sweeper | инъекция + evidence | +| 21 | Лимиты/таймауты/стриминг, RAM не растёт неограниченно | temp-file spool + streaming | эксперимент ≥10 загрузок | +| 22 | Bucket bootstrap идемпотентен | `cmd/s3init` | повторный запуск | +| 23 | Отдельные S3 credentials с ограниченными правами | identities admin/app, path-level | 403 на чужой префикс | +| 24 | Админ-консоль не в общей сети | не публикуем порты SeaweedFS, кроме S3 loopback | `docker compose ps` | +| 25 | Трек 1: presigned upload, ownership, size/checksum at complete, incomplete cleanup | §9 | `student-tests/presign_flow.py` | +| 26 | Трек 1: сравнение трафика и RAM на ≥2 размерах | §9.6 | `evidence/lab4/track1/` | + +--- + +## 2. Архитектура + +```mermaid +flowchart LR + C[Client] -->|HTTP API| LB[HAProxy :8080] + LB --> A1[API replica 1] + LB --> A2[API replica 2] + A1 --> PG[(PostgreSQL)] + A2 --> PG + A1 -->|S3 SDK| S3[(SeaweedFS :8333)] + A2 -->|S3 SDK| S3 + A1 -->|presigned PUT URL| C + C -->|PUT по подписи| S3 + A1 -.->|sweep, advisory lock| PG + A1 -.->|sweep| S3 +``` + +- Единственная точка входа для клиента — LB (loopback). S3 опубликован на `127.0.0.1:8333` только для presigned-трека и evidence; анонимный доступ запрещён identities. +- Readiness API проверяет PostgreSQL; S3 в readiness **не входит**. При падении S3 остальные endpoint работают, вложения дают 503. +- Sweep запускается в каждой реплике, но работает только владелец advisory lock. + +--- + +## 3. Фаза 0. Базовая проверка (до изменений) + +```sh +cd /Users/vladislav/Projects/mtusi2026lab4 +git status --short # пусто +go build ./... +go test -race -shuffle=on -count=1 -timeout=5m ./... +cp -n .env.example .env +docker compose --env-file .env up -d --build +curl -fsS http://localhost:8080/health/ready +make test # ожидаемо FAIL: missing required fields (attachment_ids) +docker compose --env-file .env down +``` + +Ожидаемый результат: сборка и unit-тесты зелёные; smoke падает на отсутствии `attachment_ids`. +Это фиксируется в `evidence/lab4/baseline.txt`. + +--- + +## 4. Фаза 1. Стенд SeaweedFS + +### 4.1. Файлы + +- `infra/s3/s3.json` — identities (коммитится, синтетические креды). +- `infra/s3/README.md` — как устроены права и как проверить приватность. +- `cmd/s3init/main.go` — идемпотентный bootstrap bucket. +- `compose.yaml` — сервисы `seaweedfs`, `s3-init`; API получает S3-переменные. +- `Dockerfile` — собрать и скопировать `/usr/local/bin/s3init`. +- `.env.example` — S3-переменные. + +### 4.2. `infra/s3/s3.json` + +```json +{ + "identities": [ + { + "name": "admin", + "credentials": [{"accessKey": "lab4admin", "secretKey": "lab4admin-secret"}], + "actions": ["Admin", "Read", "Write", "List", "Tagging"] + }, + { + "name": "app", + "credentials": [{"accessKey": "lab4app", "secretKey": "lab4app-secret"}], + "actions": [ + "Read:messenger-attachments/attachments/*", + "Write:messenger-attachments/attachments/*", + "Read:messenger-attachments/staging/*", + "Write:messenger-attachments/staging/*", + "List:messenger-attachments" + ] + } + ] +} +``` + +Проверено spike: app-ключ получает 403 на `other/*`, 200 на `attachments/*`; presigned PUT в `staging/*` работает; +анонимный GET — 403. + +### 4.3. `compose.yaml` + +```yaml + seaweedfs: + image: chrislusf/seaweedfs:3.80@sha256:1055999e08eed1789b0ae45d235126e4495e23d3fb9d6396293fd42539b1ae6a + command: + - server + - -s3 + - -s3.config=/etc/seaweedfs/s3.json + - -dir=/data + - -master.volumeSizeLimitMB=64 + volumes: + - ./infra/s3/s3.json:/etc/seaweedfs/s3.json:ro + - seaweedfs-data:/data + ports: + - "127.0.0.1:${S3_PORT:-8333}:8333" + healthcheck: + test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8333/healthz || exit 1"] + interval: 5s + timeout: 3s + retries: 20 + start_period: 60s + restart: unless-stopped + + s3-init: + <<: *app + entrypoint: ["/usr/local/bin/s3init"] + environment: + S3_ENDPOINT: http://seaweedfs:8333 + S3_REGION: us-east-1 + S3_BUCKET: messenger-attachments + S3_ADMIN_ACCESS_KEY: lab4admin + S3_ADMIN_SECRET_ACCESS_KEY: lab4admin-secret + depends_on: + seaweedfs: + condition: service_healthy + restart: "no" +``` + +API: +- `depends_on: s3-init: condition: service_completed_successfully`; +- `S3_ENDPOINT=http://seaweedfs:8333`, `S3_PUBLIC_ENDPOINT=http://127.0.0.1:8333`, + `S3_ACCESS_KEY_ID=lab4app`, `S3_SECRET_ACCESS_KEY=lab4app-secret`, остальные лимиты. + +`seaweedfs-data` добавить в `volumes`. + +### 4.4. `cmd/s3init` + +Алгоритм: +1. Прочитать env `S3_ENDPOINT`, `S3_BUCKET`, admin-креды; таймаут 120 с. +2. Цикл с backoff: `HeadBucket`; 404 → `CreateBucket`; `BucketAlreadyOwnedByYou`/`BucketAlreadyExists` — успех. +3. `PutObject` probe-ключа `staging/.bootstrap/` с телом `ok`, затем `DeleteObject`. +4. Лог `bucket ready` и выход 0; любая другая ошибка — exit 1. +5. Повторный запуск должен завершаться 0 без изменений. + +Использовать AWS SDK v2 (`s3.New` с `BaseEndpoint`, `UsePathStyle: true`, статические креды, регион). +Никаких `mc`/`aws` CLI — их нет в образе. + +### 4.5. Приёмка фазы 1 + +```sh +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +docker compose --env-file .env ps # только lb публикует 8080/8404, seaweedfs — 127.0.0.1:8333 +curl -fsS http://localhost:8080/health/ready +docker compose --env-file .env run --rm s3-init # повторный bootstrap: exit 0 +docker compose --env-file .env exec -T seaweedfs \ + wget -qO- http://127.0.0.1:8333/messenger-attachments/attachments/nope 2>&1 | head +# ожидаем 403 AccessDenied +``` + +--- + +## 5. Фаза 2. Конфигурация и codegen + +### 5.1. `tools/specgen/main.go` + +- Читает `contracts/openapi.json`. +- Проверяет `info.version == "1.4.0"` и `lab.json.contract_version == "1.4.0"`. +- Удаляет `anyOf` только у `components.schemas.Message` и `components.schemas.CreateMessage`. +- Если в документе есть любой другой `anyOf`/`oneOf` — завершается с ошибкой. +- Пишет `.cache/openapi.codegen.json` (pretty JSON, детерминированный порядок ключей не важен). +- Флаг `-check`: проверить, что производная спека соответствует текущей (для CI). + +`Makefile`: + +```make +generate-api: + $(GO) run ./tools/specgen + $(GO) tool ogen --config $(OGEN_CONFIG) --target $(OAS_DIR) --package oas --clean .cache/openapi.codegen.json +``` + +`.gitignore`: добавить `.cache/`. + +### 5.2. Конфиг + +`internal/config/config.go`: + +```go +type S3 struct { + Endpoint string `mapstructure:"endpoint" validate:"required,url"` + PublicEndpoint string `mapstructure:"public_endpoint" validate:"omitempty,url"` + Region string `mapstructure:"region" validate:"required"` + Bucket string `mapstructure:"bucket" validate:"required"` + AccessKeyID string `mapstructure:"access_key_id" validate:"required"` + SecretAccessKey string `mapstructure:"secret_access_key" validate:"required"` + UsePathStyle bool `mapstructure:"use_path_style"` + Timeout time.Duration `mapstructure:"timeout" validate:"required,gt=0"` + + MaxUploadBytes int64 `mapstructure:"max_upload_bytes" validate:"required,gt=0,lte=10485760"` + MaxImagePixels int64 `mapstructure:"max_image_pixels" validate:"required,gt=0,lte=40000000"` + PresignTTL time.Duration `mapstructure:"presign_ttl" validate:"required,gt=0"` + SweepInterval time.Duration `mapstructure:"sweep_interval" validate:"required,gt=0"` + SweepGrace time.Duration `mapstructure:"sweep_grace" validate:"required,gt=0"` +} +type Config struct { ... S3 S3 `mapstructure:"s3"` } +``` + +Defaults: `localhost:8333`, `us-east-1`, bucket `messenger-attachments`, +`max_upload_bytes: 10485760`, `max_image_pixels: 40000000`, `presign_ttl: 5m`, +`sweep_interval: 1m`, `sweep_grace: 10m`, `timeout: 30s`, `use_path_style: true`. +`PublicEndpoint` по умолчанию = `Endpoint`. +Добавить `Server.ReadTimeout` (60s) для загрузок; сохранить `ShutdownTimeout`. + +`.env.example`: `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, `PRESIGN_TTL`, `SWEEP_INTERVAL`, +`SWEEP_GRACE`, `S3_PUBLIC_ENDPOINT`. Синтетические креды совпадают с `infra/s3/s3.json` — добавить +комментарий об этом в оба файла. + +### 5.3. Приёмка фазы 2 + +```sh +make generate-api +go build ./... +go test ./internal/config/... +make check validate PYTHON=.venv/bin/python +``` + +Проверить в сгенерированном коде: `UploadAttachment`, `GetAttachment`, `DownloadAttachment`, +`CreateMessage.AttachmentIds`, `Message.AttachmentIds`, `AttachmentHeaders`. + +--- + +## 6. Фаза 3. Данные + +### 6.1. Миграция `00004_attachments.sql` + +Номер 4 обязателен: версия 2 занята в БД, перенесённой из lab2 (см. комментарий в `00003`). + +```sql +-- +goose Up +CREATE TABLE attachments ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL REFERENCES chats (id) ON DELETE CASCADE, + owner_id uuid NOT NULL REFERENCES users (id) ON DELETE RESTRICT, + object_key text NOT NULL, + filename text NOT NULL, + content_type text NOT NULL, + size_bytes bigint NOT NULL, + sha256 text NOT NULL, + status text NOT NULL, + error_code text, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + CONSTRAINT attachments_object_key_key UNIQUE (object_key), + CONSTRAINT attachments_status_check CHECK (status IN ('pending','ready','failed')), + CONSTRAINT attachments_content_type_check CHECK (content_type IN ('image/png','image/jpeg')), + CONSTRAINT attachments_filename_length CHECK (char_length(filename) BETWEEN 1 AND 255), + CONSTRAINT attachments_size_check CHECK (size_bytes BETWEEN 1 AND 10485760), + CONSTRAINT attachments_sha256_check CHECK (sha256 ~ '^[0-9a-f]{64}$'), + CONSTRAINT attachments_error_consistency CHECK ( + (status = 'ready' AND error_code IS NULL) OR + (status = 'failed' AND error_code IS NOT NULL) OR + status = 'pending' + ) +); +CREATE INDEX attachments_chat_id_created_at_id_idx ON attachments (chat_id, created_at, id); +CREATE INDEX attachments_status_created_at_idx ON attachments (status, created_at); + +CREATE TABLE message_attachments ( + message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE, + attachment_id uuid NOT NULL REFERENCES attachments (id) ON DELETE RESTRICT, + position smallint NOT NULL, + PRIMARY KEY (message_id, attachment_id), + CONSTRAINT message_attachments_position_check CHECK (position BETWEEN 0 AND 9), + CONSTRAINT message_attachments_position_key UNIQUE (message_id, position) +); +CREATE INDEX message_attachments_attachment_id_idx ON message_attachments (attachment_id); + +-- Ключевое: текстовые сообщения lab1–3 остаются валидными, но теперь +-- разрешён text='' при наличии вложений. Правило проверяется в сервисе. +ALTER TABLE messages DROP CONSTRAINT messages_text_not_blank; + +-- +goose Down +-- ВНИМАНИЕ: откат упадёт, если уже есть сообщения только с вложениями. +ALTER TABLE messages ADD CONSTRAINT messages_text_not_blank CHECK (btrim(text) <> ''); +DROP TABLE message_attachments; +DROP TABLE attachments; +``` + +### 6.2. Запросы `queries/attachments.sql` + +Обязательный набор (имена — sqlc): + +```sql +-- name: CreateAttachment :one +INSERT INTO attachments (id, chat_id, owner_id, object_key, filename, content_type, size_bytes, sha256, status) +VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'pending') +RETURNING ...; + +-- name: MarkAttachmentReady :one +UPDATE attachments +SET status='ready', object_key=sqlc.arg(object_key), updated_at=now() +WHERE id=sqlc.arg(id) AND status='pending' +RETURNING ...; + +-- name: GetAttachmentForMember :one +SELECT a.id, a.chat_id, a.owner_id, a.filename, a.content_type, a.size_bytes, + a.sha256, a.status, a.error_code, a.object_key, a.created_at, a.updated_at +FROM attachments a +JOIN chat_members cm ON cm.chat_id = a.chat_id AND cm.user_id = sqlc.arg(user_id) +WHERE a.id = sqlc.arg(id); + +-- name: GetAttachmentForOwnerForUpdate :one +SELECT ... FROM attachments WHERE id=sqlc.arg(id) AND owner_id=sqlc.arg(owner_id) FOR UPDATE; + +-- name: ListAttachmentStatesForChat :many +SELECT id, status FROM attachments +WHERE chat_id=sqlc.arg(chat_id) AND id = ANY(sqlc.arg(ids)::uuid[]); + +-- name: AttachToMessage :exec +INSERT INTO message_attachments (message_id, attachment_id, position) +VALUES ($1,$2,$3); + +-- name: ListMessageAttachments :many +SELECT message_id, attachment_id +FROM message_attachments +WHERE message_id = ANY(sqlc.arg(message_ids)::uuid[]) +ORDER BY message_id, position; + +-- name: DeletePendingAttachment :exec +DELETE FROM attachments WHERE id=sqlc.arg(id) AND status='pending'; + +-- name: ListStalePendingAttachments :many +SELECT ... FROM attachments +WHERE status='pending' AND created_at < now() - sqlc.arg(grace)::interval +ORDER BY created_at LIMIT 100; + +-- name: ListAttachmentKeys :many +SELECT id, object_key, status, created_at FROM attachments ORDER BY id LIMIT sqlc.arg(limit) OFFSET sqlc.arg(offset); +``` + +`GetMessageByID` и `ListMessagesForChat*` не меняются; вложения подтягиваются вторым запросом по `message_id`. +N+1 нет: один запрос на страницу (≤100 сообщений). + +### 6.3. Домен + +`internal/domain/attachment.go`: + +```go +type AttachmentStatus string +const ( + AttachmentPending AttachmentStatus = "pending" + AttachmentReady AttachmentStatus = "ready" + AttachmentFailed AttachmentStatus = "failed" +) + +type Attachment struct { + ID uuid.UUID + ChatID, OwnerID uuid.UUID + Filename string + ContentType string + SizeBytes int64 + SHA256 string + Status AttachmentStatus + ErrorCode *string + CreatedAt, UpdatedAt time.Time + ObjectKey string // только внутри сервиса/хранилища, не в JSON +} + +type Message struct { ... AttachmentIDs []uuid.UUID } +``` + +Новые sentinel-ошибки в `internal/domain/errors.go`: `ErrTooLarge`, `ErrUnsupportedMedia`, +`ErrIncomplete` (для presign complete). Маппинг в `errors.go`: + +| Ошибка | HTTP | +|---|---| +| `ErrValidation`, `ErrUnknownMember`, `ErrInvalidCursor` | 400 | +| `ErrUnauthenticated` | 401 | +| `ErrNotFound` | 404 | +| `ErrConflict`, `ErrIdempotency`, `ErrUsernameTaken` | 409 | +| `ErrTooLarge` | 413 | +| `ErrUnsupportedMedia` | 415 | +| `ErrUnavailable` | 503 | +| всё остальное | 500 | + +`GetAttachment`/`DownloadAttachment` для failed/pending возвращают `ErrConflict` (409). + +--- + +## 7. Фаза 4. Валидация изображений и S3-порт + +### 7.1. `internal/imagecheck` + +```go +type Info struct { ContentType string; Width, Height int64 } +var ErrUnsupported, ErrTooLarge, ErrCorrupt error + +func Validate(r io.Reader, maxPixels int64) (Info, error) +func ValidateFile(path string, maxPixels int64) (Info, error) +``` + +Правила: +- Прочитать сигнатуру. PNG: `\x89PNG\r\n\x1a\n`; JPEG: `FF D8 FF`. +- PNG: цикл чанков (length/type/data/crc), проверять CRC32 каждого чанка; требовать IHDR первым, + минимум один IDAT, IEND; размеры из IHDR; читать до EOF (хвост после IEND допустим, но учитывается в SHA). +- JPEG: SOI; маркеры с длиной; SOF0/1/2 даёт width/height; требовать SOS и EOI; корректно обрабатывать + `FF00` stuffing и RST0–RST7; обрыв до EOI — `ErrCorrupt`. Читать до EOF. +- `maxPixels`: `int64(w)*int64(h) > maxPixels` → `ErrTooLarge`; `w<=0 || h<=0` → `ErrCorrupt`. +- Никакого `image.Decode` и полного растра: память O(1), лимит пикселей проверяется до декодирования. +- Ошибки оборачивать с контекстом (`png chunk crc`, `jpeg segment`), наружу — sentinel. + +Табличные тесты: валидные PNG/JPEG (генерировать через `image/png`/`image/jpeg`), обрезанный PNG, +битый CRC, обрезанный JPEG, подменённая сигнатура, 0×0, 10000×10000 header (пиксельный лимит), +файл с мусором после IEND/EOI. + +### 7.2. S3-порт + +`internal/platform/objectstore`: + +```go +type Object struct { + Key string + Size int64 + ContentType string + LastModified time.Time + Metadata map[string]string +} + +type Store interface { + Put(ctx context.Context, key string, body io.Reader, size int64, contentType string, metadata map[string]string) error + Open(ctx context.Context, key string) (io.ReadCloser, Object, error) + Head(ctx context.Context, key string) (Object, error) + Copy(ctx context.Context, src, dst, contentType string, metadata map[string]string) error + Delete(ctx context.Context, key string) error + List(ctx context.Context, prefix string) ([]Object, error) + PresignPut(ctx context.Context, key string, ttl time.Duration) (string, time.Time, error) +} +``` + +Реализация `objectstore/s3`: +- AWS SDK v2: `s3.New(s3.Options{Region, BaseEndpoint, UsePathStyle: true, Credentials: static})`. +- Отдельный клиент для presign с `PublicEndpoint` (подпись привязана к Host). +- Кастомный `http.Client`: `DialContext` timeout 3s, `TLSHandshakeTimeout` 3s, + `ResponseHeaderTimeout` 15s, без общего `Timeout` (download стримится). +- `Put`: `ContentLength=&size`, `ContentType`, `Metadata`. +- `Open`: вернуть `GetObject.Body`; маппить `NoSuchKey`/`NotFound` в `domain.ErrNotFound`, + остальное — `domain.ErrUnavailable`. +- `Head`: `HeadObject`; `NotFound` → `domain.ErrNotFound`. +- `Copy`: `CopyObject` с `MetadataDirective=REPLACE`, `ContentType`, `Metadata`. +- `List`: пагинация `ListObjectsV2` (`ContinuationToken`), вернуть все объекты. +- `PresignPut`: `s3.NewPresignClient(publicClient).PresignPutObject`, `Expires=ttl`. + Не подписывать Content-Type/checksum: клиент обязан прислать только байты, всё остальное + проверяется на complete. (Проверено: SeaweedFS не валидирует `x-amz-checksum-sha256`, + поэтому complete обязан пересчитать SHA.) +- Все ошибки оборачивать `%w`, логировать без ключей. + +--- + +## 8. Фаза 5. Сервис вложений + +### 8.1. Загрузка (proxy) + +`internal/service/attachment/service.go`, метод `Upload(ctx, UploadInput)`: + +```go +type UploadInput struct { + ChatID uuid.UUID + OwnerID uuid.UUID + Filename string + DeclaredContentType string + Body io.Reader +} +``` + +Шаги строго в этом порядке: +1. `validateFilename`: UTF-8 валиден, 1–255 code points, нет `/`, `\`, NUL, `unicode.IsControl`. +2. `repo.IsChatMember(chatID, ownerID)`; нет — `ErrNotFound`. +3. Spool: `os.CreateTemp("", "lab4-upload-*")`, `defer os.Remove`, `defer Close`. + `io.Copy(io.MultiWriter(file, hasher), body)` с жёстким лимитом `maxUploadBytes`: + - использовать `http.MaxBytesReader` на уровне HTTP; в сервисе — `io.LimitReader(body, max+1)` + и счётчик; `size > max` → `ErrTooLarge`; + - `*http.MaxBytesError` → `ErrTooLarge`; + - `size == 0` → `ErrUnsupportedMedia`. +4. `imagecheck.ValidateFile(path, maxPixels)`; тип из содержимого должен совпасть с заявленным + `Content-Type` (иначе `ErrUnsupportedMedia`); пиксели — `ErrTooLarge`. +5. `id := uuid.Must(uuid.NewV7())`; `key := "attachments//"`. +6. `repo.CreateAttachment(pending)` с size/sha/type/owner. +7. `store.Put(ctx, key, file (Seek(0)), size, contentType, {"sha256": hex})`. + Ошибка → best-effort `repo.DeletePending`; вернуть `ErrUnavailable`. +8. `repo.MarkAttachmentReady(id, key)`. Ошибка → вернуть `ErrUnavailable`; объект и pending-строка + остаются, sweeper разберётся (см. §9). **201 не возвращать**. +9. Вернуть `domain.Attachment` со статусом ready. + +Контекст S3 put: `context.WithTimeout(ctx, s3.Timeout)` (30s). +Память: буферы `io.Copy` 32 KiB; диск ≤10 MiB на загрузку; после 201 файла нет. + +### 8.2. Скачивание + +`Open(ctx, callerID, attachmentID) (domain.Attachment, io.ReadCloser, error)`: +1. `repo.GetAttachmentForMember` (SQL уже проверяет членство) → нет: `ErrNotFound`. +2. `status != ready` → `ErrConflict`. +3. `store.Open(object_key)`; `NotFound` → `ErrNotFound` (метаданные есть, объекта нет — 404), + прочее → `ErrUnavailable`. +4. Вернуть запись и body; транспорт оборачивает body в closer-on-EOF. + +`Get(ctx, callerID, id)` — только метаданные, тот же membership-запрос. + +### 8.3. Сообщения + +`domain.MessageDraft` получает `AttachmentIDs []uuid.UUID`. +`Validate`: +- `len > 10` → `ErrValidation`; +- дубликаты → `ErrValidation`; +- `text` пустой/пробельный **и** нет вложений → `ErrValidation`; +- text > 4000 code points — ogen уже валидирует, сервис дублирует. + +`Service.Send`: +1. `repo.IsChatMember` → 404. +2. `repo.ListAttachmentStatesForChat(chatID, ids)`: + - найдено меньше, чем запрошено → `ErrNotFound`; + - любой статус `failed` → `ErrConflict`; + - любой статус `pending` → `ErrConflict` (в lab4 клиент не может прикрепить незавершённую загрузку). +3. `repo.Create(draft)` в одной транзакции: + - claim idempotency; + - insert message; + - insert links (по порядку, position 0..n-1); + - complete idempotency. +4. Replay: прочитать message + links; сравнить hash; вернуть с `AttachmentIDs`. + +Fingerprint (в `handler.go`, `messageFingerprint`): + +```go +ids := append([]uuid.UUID(nil), req.AttachmentIds...) +slices.SortFunc(ids, func(a, b uuid.UUID) int { return bytes.Compare(a[:], b[:]) }) +payload, _ := json.Marshal(struct { + Text string `json:"text"` + AttachmentIDs []uuid.UUID `json:"attachment_ids"` +}{req.Text, ids}) +``` + +Сортировка делает порядок вложений незначащим для идемпотентности; набор отличается — 409. +Отсутствующий `attachment_ids` и `[]` дают одинаковый fingerprint. +Замечание: записи lab3 в `message_idempotency` хранят старый hash; повтор такого ключа в течение TTL +даст 409. Отразить в REPORT. + +`History`: после выборки страницы одним запросом получить links и разложить по `message_id`. +Всегда возвращать непустой `AttachmentIds` (см. §10.2). + +--- + +## 9. Фаза 6. Консистентность и sweeper + +### 9.1. Состояния + +- `pending` — строка создана, объект ещё не подтверждён. + - proxy: ключ `attachments//`, объект пишется сразу в финальный ключ; + - presign: ключ `staging/presign//`, клиент пишет по подписи. +- `ready` — объект и метаданные согласованы; API отдаёт 201/200. +- `failed` — только для presign-валидации (error_code), в lab4 наружу не отдаётся (409). + +### 9.2. Sweeper + +`internal/service/attachment/sweeper.go`. Запуск из `main` как goroutine с `sweep_interval`, +остановка по контексту. Один владелец: + +```sql +SELECT pg_try_advisory_lock(0x4c414234); -- "LAB4" +``` + +Берётся на выделенном соединении (`pool.Acquire`), снимается в defer; при неудаче цикл пропускается. + +Алгоритм (каждые `sweep_interval`, grace `sweep_grace`): +1. `ListStalePendingAttachments(grace)`: + - proxy-ключ (`attachments/...`): `Head`; если объект есть и size/sha совпадают → `MarkReady` + (восстановление после падения между S3 и UPDATE); иначе `Delete` объекта (best-effort) и строки. + - presign-ключ (`staging/...`): `Delete` объекта и строки (клиент не завершил). +2. `List("attachments/")` и `List("staging/")`; для объектов старше grace: + - собрать множество ключей из `attachments` (батчами; lab-масштаб); + - `staging/*`: удалить, если объекта нет среди pending-строк моложе grace (т.е. брошен); + - `attachments/*`: удалить только если нет строки вообще (orphan) — ready-строки и их объекты + не трогать никогда. +3. Логировать только счётчики: scanned/deleted_objects/deleted_rows/recovered; ID — на debug. + +Гарантии: +- ready-вложения и их объекты не удаляются; +- свежие объекты (< grace) не удаляются, поэтому гонка с идущей загрузкой безопасна; +- повторный запуск идемпотентен; +- при нескольких репликах работает одна. + +Тест с инъекцией: в интеграционном тесте с fake store создать pending-строку без объекта, +pending-строку с объектом, ready-строку, orphan-объект; прогнать sweep; проверить результат. +Отдельный compose-сценарий с `SWEEP_GRACE=2s`, `SWEEP_INTERVAL=1s` и брошенным presign. + +### 9.3. S3 outage + +- `Upload` → `ErrUnavailable` (503), pending-строка удаляется best-effort. +- `Download` → 503. +- `/health/ready` остаётся 200; остальные endpoint работают. Зафиксировать в REPORT и evidence. + +--- + +## 10. Фаза 7. HTTP-слой + +### 10.1. Per-route body limit + +`internal/transport/rest/bodylimit.go`: + +```go +func bodyLimitMiddleware(defaultLimit, uploadLimit int64, log *slog.Logger, next http.Handler) http.Handler { + limit := defaultLimit + if isAttachmentUpload(r) { limit = uploadLimit } + ... +} +func isAttachmentUpload(r *http.Request) bool { + return r.Method == http.MethodPost && attachmentUploadPath.MatchString(r.URL.Path) +} +var attachmentUploadPath = regexp.MustCompile(`^/api/v1/chats/[0-9a-fA-F-]{36}/attachments$`) +``` + +`uploadLimit = cfg.S3.MaxUploadBytes` (ровно 10 MiB). `ContentLength > limit` → 413 до чтения. +`MaxBytesReader(w, body, limit)`; ошибка чтения `*http.MaxBytesError` → 413. +Обновить `NewRouter`/`main` и `router_test.go`. + +### 10.2. Handler + +`internal/transport/rest/handler.go`: + +```go +func (h *Handler) UploadAttachment(ctx context.Context, req oas.UploadAttachmentReq, params oas.UploadAttachmentParams) (oas.UploadAttachmentRes, error) { + body, declared, err := uploadBody(req) // switch по *oas.UploadAttachmentReqImagePNG / *oas.UploadAttachmentReqImageJpeg + att, err := h.attachments.Upload(ctx, attachment.UploadInput{ + ChatID: params.ChatID, OwnerID: caller(ctx), + Filename: params.Filename, DeclaredContentType: declared, Body: body, + }) + ... + return &oas.AttachmentHeaders{ + XRequestID: oas.NewOptString(requestIDFromContext(ctx)), + Response: attachmentResponse(att), + }, nil +} +``` + +`attachmentResponse`: +- `ID`, `ChatID`, `OwnerID`, `Filename`, `ContentType` (`oas.AttachmentContentTypeImagePNG` или + `oas.AttachmentContentTypeImageJpeg`), +- `SizeBytes: int(att.SizeBytes)`, `SHA256`, +- `Status: oas.AttachmentStatusReady`, +- `Variants: []oas.Variant{}` — **не nil**, +- `ErrorCode: oas.NilString{Null: true}`, +- `CreatedAt`, `UpdatedAt`. + +`GetAttachment` — тот же `*oas.AttachmentHeaders`. + +`DownloadAttachment`: +```go +att, body, err := h.attachments.Open(ctx, caller(ctx), params.AttachmentID) +defer? нет: body закроется на EOF +switch att.ContentType { +case "image/png": return &oas.DownloadAttachmentOKImagePNGHeaders{Response: oas.DownloadAttachmentOKImagePNG{Data: closeOnEOF{body}}, XRequestID: ...} +case "image/jpeg": return &oas.DownloadAttachmentOKImageJpegHeaders{...} +default: return nil, fmt.Errorf("unexpected content type %q: %w", att.ContentType, domain.ErrUnavailable) +} +``` +`variant` в lab4 всегда `original`; ogen отклоняет остальные значения 400. Явно проверить +`params.Variant` и вернуть 404, если вариант не `original` (на случай расширения контракта в lab5). +Никаких redirect. + +`closeOnEOF`: +```go +type closeOnEOF struct{ io.ReadCloser } +func (r closeOnEOF) Read(p []byte) (int, error) { + n, err := r.ReadCloser.Read(p) + if err != nil { _ = r.ReadCloser.Close() } + return n, err +} +``` + +### 10.3. Presign-эндпоинты (вне ogen) + +Файл `internal/transport/rest/extensions.go`; монтаж в `NewRouter`: + +```go +mux := http.NewServeMux() +mux.Handle("/api/v1/chats/{chat_id}/attachments/presign", ext.Presign()) +mux.Handle("/api/v1/attachments/{attachment_id}/complete", ext.Complete()) +mux.Handle("/", server) +return requestIDMiddleware(instanceIDMiddleware(bodyLimitMiddleware(default, upload, log, mux))), nil +``` + +Внутри каждого handler: проверить метод (иначе 405 в формате контракта), `Content-Type: application/json`, +лимит тела (уже применён), Bearer-токен через `session.Service.Resolve`, ошибки через `writeError`. +Для 401 выставлять `WWW-Authenticate: Bearer realm="messenger"`. +Логировать method/path/status/duration/user_id/attachment_id, без тел. + +Контракт расширения (описать в `REPORT.md` и `examples/requests.http`): + +```http +POST /api/v1/chats/{chat_id}/attachments/presign +Authorization: Bearer +Content-Type: application/json + +{"filename":"photo.png","content_type":"image/png","size_bytes":12345,"sha256":"<64 hex>"} +``` + +201: +```json +{"attachment_id":"...","method":"PUT","upload_url":"http://127.0.0.1:8333/...", + "expires_at":"2026-10-21T19:00:00Z"} +``` + +```http +POST /api/v1/attachments/{attachment_id}/complete +Authorization: Bearer +Content-Type: application/json + +{"sha256":"<64 hex>"} +``` + +200 — `Attachment` (ready) с теми же полями, что proxy-upload. + +Валидация presign: +- filename — те же правила; +- `content_type` ∈ {image/png, image/jpeg}; +- `size_bytes` 1..maxUpload; +- `sha256` — 64 lowercase hex; +- membership чата → 404; создать pending-строку с ключом `staging/presign//`; +- `PresignPut(publicClient, key, presign_ttl)`; URL и `expires_at` вернуть. + +Complete: +1. Bearer + UUID; `GetAttachmentForOwnerForUpdate` (owner + chat membership); чужой → 404. +2. `ready` → если sha совпадает, вернуть 200; иначе 409. +3. `pending`: + - `Head(staging_key)`; нет объекта → 409 `incomplete`; + - size/type не совпали с заявленными → удалить объект и строку, 400; + - `Open` → `io.TeeReader(body, sha256)` → `imagecheck.Validate` (заодно вычитывает весь объект); + SHA не совпал → удалить объект и строку, 400; структура/пиксели плохие → 415; + - `Copy(staging → attachments//, contentType, {"sha256":...})`; + - `MarkAttachmentReady`; + - `Delete(staging)` best-effort (если не вышло — sweeper удалит по возрасту); + - вернуть 200. +4. Ошибки S3 → 503; partial-состояния разбирает sweeper. + +`examples/requests.http` дополнить presign/complete примерами. + +--- + +## 11. Фаза 8. Тесты + +### 11.1. Go + +- `internal/imagecheck/imagecheck_test.go` — таблица (§7.1). +- `internal/service/attachment/service_test.go` — mock `Store`/`Repository`: + - filename: пусто, 256 code points, `/`, `\`, NUL, `\n`, валидный Unicode; + - размер: 0, max, max+1; + - MIME mismatch, битый файл, пиксельный лимит; + - membership 404; S3 put error → 503 и удаление pending; mark-ready error → 503; + - download: не ready → 409; object missing → 404; S3 down → 503. +- `internal/service/attachment/sweeper_test.go` — fake store: восстановление/удаление/ready неприкосновенен; + повторный запуск идемпотентен; объект моложе grace не трогается. +- `internal/service/message/service_test.go` — пустой text без вложений; text+вложения; >10; дубликаты; + чужое вложение; failed/pending; fingerprint порядка. +- `internal/transport/rest/router_test.go` — per-route лимит: 10 MiB проходит в handler, 10 MiB+1 → 413; + JSON-роуты по-прежнему 256 KiB; download content-type; presign auth/405/415. +- `internal/storage/postgres/attachment_repository_test.go` (`-tags integration`) — миграция, + membership-запрос, links, replay, constraint `messages_text_not_blank` снят. +- `internal/config/config_test.go` — дефолты/валидация S3. + +### 11.2. Публичные и студенческие сценарии + +- `make test` — публичный smoke (LAB=4) PASS. +- `student-tests/attachments_negative.py`: + - 10 MiB+1 → 413; 0 байт → 415; PNG с битым CRC → 415; JPEG, объявленный как PNG → 415; + filename `../x`, `a/b`, `a\b`, с `\x00`, с `\n` → 400; + - чужой chat_id → 404; чужой attachment_id (GET и /content) → 404; + - `?variant=thumbnail` → 404; + - пустой text без вложений → 400; `text=""` + вложение → 201; + - 11 вложений → 400; дубликаты → 400; вложение другого чата → 404; + - после каждого 4xx проверить, что нет 500 и тело — `Error` со `request_id`. +- `student-tests/attachment_failover.py`: + 1. upload через LB, получить `X-Instance-Id` и SHA; + 2. `TARGET_INSTANCE_ID= scripts/stop-one.sh`; + 3. download через LB, сравнить байты/SHA; metadata через GET; + 4. `docker compose up -d --no-deps api` вернуть реплику. +- `student-tests/presign_flow.py`: + - presign → PUT (stdlib) → complete → message → download; SHA совпадает; + - просроченный URL → 403 S3; чужой complete → 404; неверный SHA на complete → 400 и объект удалён; + - presign без PUT → через `SWEEP_GRACE=2s` строка и staging-объект исчезают; + - повторный complete идемпотентен. +- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` и + `make test-persistence ACTION_SCRIPT=scripts/restart.sh` — PASS. + +### 11.3. CI + +`.github/workflows/app.yml`: +- job `stand`: `cp .env.example .env`; `docker compose config --quiet`; `up -d --build`; + wait ready; `make test`; `python3 student-tests/idempotency_parallel.py`; + `python3 student-tests/attachments_negative.py`; `python3 student-tests/presign_flow.py`; + `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`; +- на failure — `docker compose logs --tail 200`; +- `down -v` в `always()`. +- `scripts/stop-one.sh`: проект по умолчанию `mtusi-messenger-lab4` (или `COMPOSE_PROJECT_NAME`). +- `scripts/restart.sh`: переименовать проект, добавить `seaweedfs` в рестарт; volumes не удалять. + +--- + +## 12. Фаза 9. Трек 1 — presigned direct upload + +### 12.1. Что уже сделано в §10.3 + +Эндпоинты, pending-строка, проверка ownership/size/type/SHA, copy в финальный ключ, cleanup. + +### 12.2. Публичный endpoint и безопасность + +- `S3_PUBLIC_ENDPOINT=http://127.0.0.1:8333`; порт публикуется только на loopback. +- Подпись привязана к Host; клиент обязан использовать выданный URL без замены хоста. +- Bucket приватный; анонимный GET → 403. +- URL живёт `presign_ttl=5m`; одноразовость не гарантируется S3 — повторный PUT перезапишет объект + до истечения; complete проверит размер/SHA и либо примет, либо удалит. +- Ключ назначает сервер (`staging/presign//`), filename в ключ не попадает. + +### 12.3. Незавершённые загрузки + +- presign без PUT: pending-строка older than grace → удалить строку (объекта нет). +- PUT без complete: staging-объект older than grace → удалить объект и строку. +- complete, упавший между Copy и MarkReady: pending + staging отсутствует + финальный объект; + sweeper: proxy/presign pending → `Head(final)`? Для presign ключ в строке staging; после Copy + строка ещё staging. Sweeper увидит staging отсутствующим и удалит строку, а финальный объект + останется orphan → второй проход `List("attachments/")` удалит его (нет строки). + Либо, что лучше: в complete обновлять `object_key` на финальный **в той же транзакции**, что и + `status=ready`; при падении между Copy и UPDATE — orphan удаляется. Это соответствует §9.2. +- Рекомендуемая последовательность complete: Copy → `MarkReady(final_key)` (одна UPDATE) → Delete(staging). + +### 12.4. Сравнение proxy vs presign + +Скрипт `scripts/lab4_track1.py` (stdlib): +- размеры: 1 MiB и 9 MiB (валидные PNG, генерируются детерминированно, ≤40 MP); +- 5 итераций на сценарий; прогрев 1 итерация; +- proxy: `POST .../attachments?filename=...` через LB; +- presign: presign → PUT напрямую в `127.0.0.1:8333` → complete через LB; +- метрики на итерацию: + - `lb_rx`/`lb_tx` — `/sys/class/net/eth0/statistics/{rx,tx}_bytes` контейнера `lb`; + - `api_rx` — сумма по контейнерам `api`; + - `api_mem_current` — `/sys/fs/cgroup/memory.current` (и `memory.peak`, если есть); + - latency p50/p95 клиента. +- Вывод: CSV `evidence/lab4/track1/results.csv`, summary `summary.txt`, markdown-таблица в REPORT. +- Честно указать: при presign тело не проходит через API/LB, но complete перечитывает объект + из S3 для проверки SHA, поэтому `api_rx` остаётся ≈ размеру файла; выигрыш — в клиентском плече + и в том, что API не буферизует/не принимает тело. Это ограничение зафиксировать. + +### 12.5. Негативные сценарии трека + +- просроченный URL → 403; +- PUT с другим размером → complete 400 и объект удалён; +- PUT с другим SHA → complete 400 и объект удалён; +- PUT в чужой ключ (без подписи) → 403; +- complete чужого attachment → 404; +- incomplete → 409, затем sweep; +- повторный complete → 200, без дублей. + +--- + +## 13. Фаза 10. Evidence, REPORT, защита + +### 13.1. `evidence/lab4/` + +- `README.md` — как воспроизвести каждый файл, предусловия, версии, время. +- `baseline.txt` — smoke до реализации. +- `smoke.txt` — `make test` PASS. +- `negative.txt` — вывод `attachments_negative.py`. +- `failover.txt` — upload → stop → download, SHA. +- `restart.txt` — restart стенда, метаданные и оригинал на месте. +- `s3-outage.txt` — upload/download 503, остальные endpoint 200; восстановление. +- `private-bucket.txt` — anonymous GET 403, app-ключ 403 на чужой префикс, `docker compose ps` без лишних портов. +- `sweep.txt` — брошенный presign, удаление после grace, ready не тронут. +- `memory/` — CSV + summary (≥10 одновременных загрузок по 10 MiB, пик `memory.current`). +- `track1/` — `results.csv`, `summary.txt`, команды, p50/p95, трафик, RAM. +- `defense.md` — краткие ответы на вопросы README (см. §13.3). + +Никаких секретов и токенов в evidence. + +### 13.2. REPORT.md + +Заполнить по шаблону: +- запуск из чистого clone (версии, `.env`, bootstrap, миграции, тесты, остановка); +- архитектура: процессы, источник истины, транзакционные границы, лимиты; +- таблица «критерий → команда → наблюдаемый результат → файл»; +- эксперименты: гипотеза, методика, железо, данные, p50/p95, RSS, ограничения; +- отказы: S3, реплика, restart, отказ между S3/БД; +- что не реализовано (lab5), где упрощения; +- отдельный раздел про presign-расширение и его отличие от обязательного контракта. + +### 13.3. Ответы на защиту (подготовить в REPORT) + +- Почему файл в volume одной реплики ≠ объектное хранилище: реплики stateless, volume не разделяется, + балансировщик отправит download на другую реплику; S3 — общий источник байтов. +- Когда честно вернуть 201: только после успешной записи оригинала в S3 **и** фиксации метаданных + в PostgreSQL; иначе клиент получит идентификатор без байтов. +- Что при падении S3: upload/download → 503, остальное работает; readiness не включает S3. +- Почему нельзя доверять `Content-Type` и `filename`: заголовок подделывается, имя — не ключ; + проверяем сигнатуру/структуру и генерируем ключ. +- Как ограничена память: тело не буферизуется целиком; temp-файл ≤10 MiB; SHA и структурная + проверка потоковые; 10 конкурентных загрузок не растят RSS пропорционально. +- Как не остаются вечные объекты: pending + sweeper с grace + advisory lock; ready не удаляется. +- Почему presigned URL безопасен: короткий TTL, конкретный ключ, server-side ownership, проверка + размера/SHA/структуры на complete, приватный bucket. + +--- + +## 14. Подводные камни (проверено) + +1. **ogen + anyOf** — не использовать `ignore_not_implemented`; он выкидывает операции. Только производная спека. +2. **`Message.attachment_ids` обязателен**, а ogen-энкодер опускает nil-слайс. Всегда `[]oas...`. +3. **`messages_text_not_blank`** в БД блокирует сообщения только с вложениями — снять constraint. +4. **Глобальный body limit 256 KiB** — иначе upload не пройдёт; сделать per-route. +5. **ogen upload body — `io.Reader`**, не JSON; не пытаться декодировать. +6. **`*http.MaxBytesError`** — единственный надёжный признак 413 при chunked-теле. +7. **Content-Type из заголовка не доверять**; SeaweedFS не валидирует checksum (проверено). +8. **filename — Unicode code points**, не байты; `char_length` в PG считает code points. +9. **Пиксельный лимит до декодирования**; полный `image.Decode` на 40 MP = до 160 MB. +10. **`error_code=null`** — `oas.NilString{Null: true}`, не пустая строка. +11. **`variants=[]`**, не nil. +12. **Membership в SQL** — не выбирать объект, а потом проверять (лишний 403/404 и утечка). +13. **201 только после S3+БД**; pending-строка не должна отдаваться как ready. +14. **Fingerprint идемпотентности** включает отсортированные attachment_ids; старые записи дадут 409. +15. **Claim ключа после валидации**, иначе неудачный запрос оставит занятый ключ без message_id. +16. **Транзакция message + links**; FK и статус вложения проверять до claim. +17. **S3 ключи/креды не логировать**; ошибки наружу — общий `Error`. +18. **S3 down → 503**, не 500; readiness не трогать. +19. **Sweeper не удаляет ready**; grace; advisory lock; идемпотентность. +20. **Presign URL host** должен быть доступен клиенту; подпись привязана к Host. +21. **Complete обязан пересчитать SHA** (SeaweedFS не хранит checksum — HeadObject пуст). +22. **CopyObject + MarkReady**: final_key обновляется в одной UPDATE; иначе orphan. +23. **Temp-файлы** удалять; после 201 на API нет оригинала. +24. **Docker Desktop не шарит `/tmp`** — конфиги монтировать из репозитория (проверено). +25. **SeaweedFS стартует ~20 с** — `start_period: 60s`, s3-init с retry. +26. **Порты SeaweedFS** — только 8333 на loopback; master/volume/filer/console не публиковать. +27. **`scripts/stop-one.sh`** хардкодит проект lab3 — обновить. +28. **CI** должен поднимать S3 и ждать readiness; presign-тест ходит на `127.0.0.1:8333`. +29. **`make validate`** требует `requirements-dev.txt`; локально — `.venv`. +30. **sqlc** требует перегенерации после миграции/запросов; `make sqlc`. +31. **ogen типы**: `AttachmentIds` (не `AttachmentIDs`), `AttachmentHeaders` общий для upload/get, + download — отдельные типы на каждый content-type. +32. **`DownloadAttachmentParams.Variant`** — enum с `original`; остальное ogen отклонит. +33. **Streaming download**: закрывать body на EOF; иначе утечка соединений S3. +34. **ReadTimeout** сервера не должен рвать большие downloads: ставить только на чтение запроса, + не на запись ответа. +35. **Down-миграция** с восстановлением `messages_text_not_blank` упадёт при attachment-only строках — + задокументировать. +36. **Секреты** в `.env` не коммитить; `infra/s3/s3.json` — только синтетические локальные креды. +37. **`make generate-api`** должен быть воспроизводим: `.cache/` в gitignore, версия ogen в `go.mod`. +38. **`AttachmentHeaders.XInstanceID`** не обязателен: заголовок ставит middleware; X-Request-Id — ставить. +39. **Presign-роуты вне ogen** — сами проверяют метод/JSON/401 и формат ошибок. +40. **Трек 1**: не заявлять, что API вообще не читает файл; complete перечитывает его для SHA. + +--- + +## 15. Команды и Definition of Done + +### 15.1. Локальный прогон + +```sh +cp -n .env.example .env +make generate-api +make sqlc +go build ./... +make unit-test +make check validate PYTHON=.venv/bin/python +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +for i in $(seq 1 90); do curl -fsS http://localhost:8080/health/ready && break; sleep 2; done +make test +python3 student-tests/attachments_negative.py --base-url http://localhost:8080 +python3 student-tests/presign_flow.py --base-url http://localhost:8080 +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +make test-persistence ACTION_SCRIPT=scripts/restart.sh +``` + +### 15.2. Definition of Done + +- [ ] `make unit-test` — зелёный, race. +- [ ] `make lint` — без новых замечаний. +- [ ] `make check validate` — PASS. +- [ ] `make test` (публичный smoke, LAB=4) — PASS. +- [ ] Все негативные сценарии возвращают 400/404/409/413/415, ни одного 500. +- [ ] Upload → stop реплики → download через другую: SHA совпадает. +- [ ] Restart стенда: метаданные и оригинал доступны. +- [ ] S3 stop: upload/download 503, остальные endpoint 200; после старта — восстановление. +- [ ] Анонимный GET объекта → 403; app-ключ на чужой префикс → 403. +- [ ] Sweep: брошенный presign исчезает после grace; ready не тронут; повторный запуск безопасен. +- [ ] Эксперимент ≥10 конкурентных загрузок по 10 MiB: пик RSS зафиксирован, без OOM. +- [ ] Presign: успешный сценарий, просроченный URL, неверный SHA, incomplete, чужой complete. +- [ ] `evidence/lab4/` заполнен, все команды воспроизводимы. +- [ ] `REPORT.md` заполнен, таблица критериев без TODO. +- [ ] `git status` чистый; секретов в коммитах нет. + +--- + +## 16. План коммитов + +1. `lab4: стенд SeaweedFS, bucket bootstrap и конфигурация S3` +2. `lab4: codegen-обход anyOf и модель вложений` +3. `lab4: proxy upload/download и attachment_ids в сообщениях` +4. `lab4: негативные тесты, sweeper и эксперимент по памяти` +5. `lab4: presigned upload (трек 1) и доказательства` +6. `lab4: отчёт и CI` + +После каждого коммита: `go build ./... && make unit-test && make check`. +Перед финалом — полный прогон §15.1 и проверка §15.2. + +--- + +## 17. Явные не-цели + +- thumbnail/варианты, статусы queued/processing, worker, 202 — lab5. +- WebSocket, редактирование/удаление сообщений, UI — вне обязательного минимума. +- Kubernetes/Swarm — не требуется; compose достаточно. +- Rate limiting (429) — не обязателен; не добавлять. +- Шифрование S3, versioning, object lock — не требуются.