# План реализации лабораторной 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` также отсутствует; - публикации об удалении: [MinIO images disappeared from Docker Hub](https://www.stablebuild.com/blog/minio-images-disappeared-from-docker-hub), [minio/minio no longer available](https://github.com/milvus-io/milvus/issues/53430). Контракт `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: негативные тесты | см. §11 | `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 | §10.3, §12 | `student-tests/presign_flow.py` | | 26 | Трек 1: сравнение трафика и RAM на ≥2 размерах | §12.4 | `evidence/lab4/track1/` | | 27 | `GET /attachments/{id}` и `/content` для non-ready — 409 (enum 1.4.0 только `ready`) | проверка статуса в `Get`/`Open` | unit/HTTP | --- ## 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. Имя bucket `messenger-attachments` валидно (3–63 lowercase); односимвольные имена SeaweedFS отклоняет с `InvalidBucketName`. ### 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 S3_ACCESS_KEY_ID: lab4app S3_SECRET_ACCESS_KEY: lab4app-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-креды и app-креды; таймаут 120 с. 2. Цикл с backoff: `HeadBucket` (admin); 404 → `CreateBucket`; `BucketAlreadyOwnedByYou`/ `BucketAlreadyExists` — успех. Проверено на SeaweedFS 3.80: повторный `CreateBucket` даёт **409 BucketAlreadyExists** (не `BucketAlreadyOwnedByYou`), поэтому `HeadBucket` — основной идемпотентный путь, а 409 при гонке тоже считается успехом. 3. Проверить app-идентичность: `PutObject` probe-ключа `staging/.bootstrap/` с телом `ok`, `HeadObject`, `ListObjectsV2(prefix="staging/")`, затем `DeleteObject`. Все операции — app-кредами. Так bootstrap проверяет не только наличие bucket, но и реальные права API. 4. Проверить, что app-креды **не** могут писать вне разрешённых префиксов (`PutObject` в `forbidden/` → ожидается 403); иначе конфигурация identities небезопасна — exit 1. 5. Лог `bucket ready` и выход 0; любая другая ошибка — exit 1. 6. Повторный запуск должен завершаться 0 без изменений. Использовать AWS SDK v2 (`s3.New` с `BaseEndpoint`, `UsePathStyle: true`, статические креды, регион). Никаких `mc`/`aws` CLI — их нет в образе. `cmd/s3init` не вызывает `config.Load()`: он читает только `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ADMIN_ACCESS_KEY`, `S3_ADMIN_SECRET_ACCESS_KEY` своим маленьким загрузчиком, иначе общий валидатор потребует app-креды, ненужные bootstrap-у. Дополнительно: `scripts/check_s3_creds.py` сверяет `infra/s3/s3.json` с `.env.example`/`.env` (admin/app accessKey/secretKey) и вызывается из `make check`. Это исключает дрейф между identities SeaweedFS и конфигурацией API. ### 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 python3 scripts/check_s3_creds.py # identities == .env.example/.env ``` --- ## 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"` // Креды НЕ required в общем валидаторе: config.Load используют cmd/migrate и unit-тесты, // которым S3 не нужен. Наличие ключей проверяет objectstore.New (только в cmd/messenger). AccessKeyID string `mapstructure:"access_key_id"` SecretAccessKey string `mapstructure:"secret_access_key"` 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`. Ключи S3 не обязательны для `config.Load`: `cmd/migrate` и unit-тесты не должны требовать S3. `objectstore.New` возвращает ошибку при пустых ключах/endpoint; `cmd/messenger` вызывает его, `cmd/migrate` — нет. Это же снимает поломку `internal/config/config_test.go`. `.env.example`: `S3_ENDPOINT`, `S3_PUBLIC_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_PRESIGN_TTL`, `S3_SWEEP_INTERVAL`, `S3_SWEEP_GRACE`, а также `MAX_UPLOAD_BYTES`/`MAX_IMAGE_PIXELS` (как в skeleton). Viper по умолчанию даст для них `S3_MAX_UPLOAD_BYTES`/`S3_MAX_IMAGE_PIXELS`, поэтому добавить явные alias-биндинги: `v.BindEnv("s3.max_upload_bytes", "MAX_UPLOAD_BYTES")` и `v.BindEnv("s3.max_image_pixels", "MAX_IMAGE_PIXELS")`. Синтетические креды совпадают с `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 a.* FROM attachments a JOIN chat_members cm ON cm.chat_id = a.chat_id AND cm.user_id = a.owner_id WHERE a.id = sqlc.arg(id) AND a.owner_id = sqlc.arg(owner_id) FOR UPDATE OF a; -- 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 FOR UPDATE SKIP LOCKED; -- 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`, `ErrIncomplete` | 409 | | `ErrTooLarge` | 413 | | `ErrUnsupportedMedia` | 415 | | `ErrUnavailable` | 503 | | всё остальное | 500 | `GET /attachments/{id}` тоже возвращает 409 для pending/failed: в контракте 1.4.0 `Attachment.status` — enum из одного значения `ready`, поэтому 200 с `status=pending/failed` нарушил бы схему. Наблюдаемость этих состояний появится в lab5 вместе с расширением enum. В lab4 pending/failed наружу не появляются. --- ## 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. Почему не `image.DecodeConfig`: в Go 1.27 `png.DecodeConfig` останавливается на IHDR (проверяет CRC только прочитанных чанков) и не читает IDAT/IEND; `jpeg.DecodeConfig` разбирает только заголовок до SOF. Обрезанный файл с валидным заголовком пройдёт их. Полный `image.Decode` на 40 MP аллоцирует до 160 MB. Поэтому структурный потоковый парсер — осознанный выбор. OWASP рекомендует decode+re-encode, но в lab4 изображения не обрабатываются и не исполняются, а отдаются как приватные байты, поэтому структурной проверки достаточно; lab5 добавит контролируемый decode для thumbnail. Табличные тесты: валидные 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, size int64, 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(ctx, &s3.PutObjectInput{Bucket, Key, ContentLength: size}, ...)`, `Expires=ttl`. `ContentLength` попадает в `X-Amz-SignedHeaders` (проверено), поэтому S3 отклоняет PUT другого размера с 403 — write-time лимит. ContentType/ChecksumSHA256 не подписывать: Content-Type не нужен, а checksums SeaweedFS не валидирует; complete проверяет фактические байты. Проверено: SeaweedFS не валидирует `x-amz-checksum-sha256` и не возвращает его в HeadObject, поэтому 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.CopyBuffer(io.MultiWriter(file, hasher), body, make([]byte, 32<<10))` с жёстким лимитом `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-запрос; статус проверяется: non-ready → `ErrConflict`, потому что enum 1.4.0 допускает только `ready`. ### 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}) ``` Порядок вложений входит в payload: перестановка — другой body и 409. Отсутствующий `attachment_ids` и `[]` дают одинаковый fingerprint. Замечание: записи lab3 в `message_idempotency` хранят старый hash; повтор такого ключа в течение TTL даст 409. Отразить в REPORT. `History`: после выборки страницы одним запросом получить links и разложить по `message_id` (при пустой странице второй запрос не выполнять). Всегда возвращать непустой `AttachmentIds` (см. §10.2). В `createClaimed` вставить links после message, в той же транзакции; при ошибке любого INSERT транзакция откатывается вместе с claim. --- ## 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; при неудаче цикл пропускается. Соединение нельзя возвращать в пул с удерживаемым session-level lock — unlock обязателен. При shutdown сначала отменяется контекст sweeper и ждётся WaitGroup, иначе sweep может обратиться к уже закрытому pool/store. Запуск — после успешных миграций и `s3init`. Алгоритм (каждые `sweep_interval`, grace `sweep_grace`): 1. `ListStalePendingAttachments(grace)` — выбирать `FOR UPDATE SKIP LOCKED`, чтобы не пересечься с идущим complete (он держит `FOR UPDATE` на строке). Все действия sweep идемпотентны: повторный `Delete`/`MarkReady` безопасен, `MarkReady` условен по `status='pending'`. - proxy-ключ (`attachments/...`): `Head`; если объект есть и size/sha совпадают → `MarkReady` (восстановление после падения между S3 и UPDATE); иначе `Delete` объекта (best-effort) и строки. - presign-ключ (`staging/...`): `Delete` объекта и строки (клиент не завершил). 2. `List("attachments/")` и `List("staging/")`; для объектов старше grace. Проверить path-scoped `List:bucket/attachments/*` и `List:bucket/staging/*`; если SeaweedFS их не принимает — оставить `List:bucket` и зафиксировать в REPORT (s3init делает пробный `ListObjectsV2` по каждому prefix и падает, если прав нет): - собрать множество ключей из `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 } ``` Дополнительно: `context.AfterFunc(ctx, func(){ _ = body.Close() })` — если клиент оборвёт соединение до EOF, body закроется по отмене контекста; иначе соединение S3 утечёт. `closeOnEOF` закрывает на любой ошибке чтения. ### 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","sha256":"<64 hex>","size_bytes":12345} ``` Клиент обязан отправить ровно `size_bytes` (Content-Length подписан); остальные заголовки не обязательны. ```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, size_bytes, presign_ttl)`; URL и `expires_at` вернуть. URL подписывает `content-length`, поэтому клиент обязан отправить ровно `size_bytes`. Ограничения presigned PUT (зафиксировать в REPORT): - Write-time лимит обеспечен подписанным `Content-Length`: PUT другого размера получает 403. Complete дополнительно сверяет размер, SHA и структуру; это соответствует формулировке трека. - URL — bearer-токен: он многоразовый до `expires_at` и перезаписывает объект по тому же ключу (AWS docs). Complete проверяет фактические байты; повторный PUT после complete создаёт staging-orphan, который удалит sweeper. - Complete не доверяет Content-Type, который сохранил S3 (клиент мог его не прислать): используется `content_type` из presign-строки, байты проверяются структурно. Complete: 1. Bearer + UUID; `GetAttachmentForOwnerForUpdate` (owner + chat membership); чужой → 404. 2. `ready` → если sha совпадает, вернуть 200; иначе 409. 3. `pending`: - `Head(staging_key)`; нет объекта → 409 `incomplete`; - `ContentLength` не совпал с `size_bytes` → удалить объект и строку, 400; - `Open` → `io.TeeReader(body, sha256)` → `imagecheck.Validate` (парсер обязан дочитать поток до EOF, чтобы хеш покрыл все байты); SHA не совпал → удалить объект и строку, 400; структура/пиксели плохие → 415; - Content-Type из S3 не сравниваем (клиент мог его не прислать); используем `content_type` из presign-строки; - `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; - `Get` метаданных для pending/failed → 409 (enum 1.4.0); `Open` → 409; - 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 порядка; `History` возвращает `attachment_ids` в порядке `position` и `[]` для сообщений без вложений. - `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; отдельный тест, что `config.Load()` без S3-кредов не падает (совместимость с `cmd/migrate`). - `tools/specgen/specgen_test.go` — удаляются только два `anyOf`; любой другой `anyOf`/`oneOf` приводит к ошибке; производная спека детерминирована. ### 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 идемпотентен; - повторный PUT в тот же URL до complete перезаписывает объект: complete принимает только последнюю версию, если её SHA/размер совпали; иначе 400 и очистка. - `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. В реальном развёртывании это должен быть адрес, доступный клиенту (не `127.0.0.1`); при смене `S3_PORT` синхронно менять `S3_PUBLIC_ENDPOINT`. - Подпись привязана к Host; клиент обязан использовать выданный URL без замены хоста. - Bucket приватный; анонимный GET → 403. - URL живёт `presign_ttl=5m`; это bearer-токен: по [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) он многоразовый до истечения, а PUT заменяет объект по тому же ключу. Complete проверит размер/SHA и либо примет, либо удалит; отозвать URL можно только отзывом кредов (не делаем). Минимальный TTL и приватный bucket — основные компенсации. - Ключ назначает сервер (`staging/presign//`), filename в ключ не попадает. ### 12.3. Незавершённые загрузки - presign без PUT: pending-строка older than grace → удалить строку (объекта нет). - PUT без complete: staging-объект older than grace → удалить объект и строку. - complete, упавший между Copy и MarkReady: в БД строка всё ещё pending со staging-ключом, staging-объект уже удалён (или ещё нет), финальный объект существует. Разбор: sweeper видит pending старше grace; `Head(staging)` → нет объекта; удаляет строку. Финальный объект остаётся без строки → второй проход `List("attachments/")` удаляет его как orphan. Потерь подтверждённых данных нет: 200 клиенту не вернули. - Рекомендуемая последовательность complete: Copy → `MarkReady(final_key)` (одна UPDATE) → Delete(staging). `MarkReady` меняет и `object_key`, и `status` атомарно; при падении до UPDATE финальный объект — молодой orphan, который удалится только после grace (окно восстановления). ### 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_anon` — `/sys/fs/cgroup/memory.stat` (`anon`), `api_mem_current` — `memory.current`, `memory.peak` если есть; `anon` — основная метрика, потому что `memory.current` включает page cache от temp-файлов; дополнительно `docker stats --no-stream` (RSS); - 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 с другим размером → 403 от S3, complete — 409 (объекта нет); - 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; пик `anon`, `memory.current` и `docker stats` с объяснением вклада page cache). - `track1/` — `results.csv`, `summary.txt`, команды, p50/p95, трафик LB и API, RAM, а также отдельный вывод: Content-Length подписан, oversized PUT отклоняется S3; complete перепроверяет. - `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 в порядке запроса (перестановка — другой payload, 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. 41. **S3-креды не делать `required` в общем конфиге** — иначе `cmd/migrate` и unit-тесты падают без S3; проверять в `objectstore.New`. При этом ключи должны быть **в `defaults`** (пустыми), иначе viper `Unmarshal` не увидит `S3_ACCESS_KEY_ID`/`S3_SECRET_ACCESS_KEY` (проверено). 42. **`cmd/s3init` не должен звать `config.Load`** — у него только admin-переменные. 43. **sqlc и `uuid[]`**: проверить сгенерированный тип для `ANY($1::uuid[])`; при проблеме заменить на цикл точечных запросов (≤10 вложений) или `pgtype.Array`. 44. **`GET /attachments/{id}` не должен отдавать 409** для pending/failed: контракт требует наблюдаемые `status`/`error_code`; 409 — только `/content`. 45. **Presigned PUT**: подписывать `Content-Length` (S3 вернёт 403 на другой размер); complete всё равно перепроверяет размер/SHA. 46. **Presigned URL многоразовый и перезаписывает объект**; complete проверяет фактические байты, после complete повторный PUT создаёт staging-orphan → sweep. 47. **Не подписывать Content-Type в presign** — SDK может добавить его в SignedHeaders, клиент получит `SignatureDoesNotMatch`; передавать только Bucket/Key. 48. **`memory.current` включает page cache** от temp-файлов; для RAM-эксперимента использовать `anon`. 49. **Sweeper: unlock advisory lock на том же соединении**, иначе lock утечёт в пул; при shutdown сначала остановить sweeper, потом закрывать pool. 50. **Path-scoped `List` в SeaweedFS** может не поддержаться; проверить в s3init, иначе `List:bucket`. 51. **`http.ServeMux` method/wildcard patterns** требуют Go 1.22+; проект на 1.27 — ок, но не регистрировать ext-роуты без проверки метода внутри (иначе 405 уйдёт в ogen). 52. **SeaweedFS HeadObject не возвращает checksum**; не строить complete на `ChecksumSHA256`. 53. **`GetAttachment` 200 и `DownloadAttachment` 200 — разные типы** (`AttachmentHeaders` vs `DownloadAttachmentOKImage*Headers`); не перепутать в type switch. 54. **Readiness без S3** — осознанное решение; обосновать в REPORT (иначе S3-down уберёт все реплики). 55. **SeaweedFS CreateBucket идемпотентность**: повторный вызов → 409 `BucketAlreadyExists` (проверено), а не `BucketAlreadyOwnedByYou`; сначала `HeadBucket`, 409 при гонке — успех. 56. **SeaweedFS HeadObject missing** → 404 `NotFound` (проверено); маппить в `ErrNotFound`, не 503. 57. **CopyObject metadata**: `MetadataDirective=REPLACE` + `ContentType`/`Metadata` сохраняет sha256 и тип (проверено); без REPLACE метаданные источника могут не обновиться. 58. **ListObjectsV2 LastModified** возвращается (проверено) — sweeper может сравнивать возраст с `now-grace`; не полагаться на размер/ETag. --- ## 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 python3 scripts/check_s3_creds.py 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. - [ ] `GET /attachments/{id}` и `/content` для failed/pending — 409 (enum 1.4.0). - [ ] `config.Load()` без S3-кредов не падает; `cmd/migrate` работает. - [ ] `scripts/check_s3_creds.py` — PASS (identities == env). - [ ] 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 — не требуются. --- ## 18. Валидация плана и внешние практики ### 18.1. Что проверено и что исправлено | Проверка | Источник | Результат | Правка плана | |---|---|---|---| | `GET /attachments/{id}` при failed/pending | контракт 1.4.0: `Attachment.status` enum = только `ready` | 200 с non-ready нарушил бы схему; 409 на metadata и content | §6.3, §8.2, §11.1, §15.2 | | ogen: `InvalidContentTypeError` | `ogen/ogenerrors/handler.go` | маппится в 415 автоматически | подтверждено | | ogen: `maxItems`/`uniqueItems` | `ogen/validate/array.go`, шаблон валидаторов | поддержаны; сервис дублирует | §11 | | ogen: `anyOf` | `gen/schema_gen_sum.go` | sum-типы с одинаковыми именами не поддержаны; `ignore_not_implemented` выкидывает операции | §0.2 | | Go `png.DecodeConfig` | `/usr/local/go/src/image/png/reader.go:993` | останавливается на IHDR, не читает IDAT/IEND | §7.1 | | Go `jpeg.DecodeConfig` | `/usr/local/go/src/image/jpeg/reader.go:778` | разбирает только заголовок до SOF | §7.1 | | OWASP upload | [File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) | не доверять Content-Type, генерировать имя, лимит размера, авторизация, хранить вне webroot | подтверждено | | AWS presigned URLs | [using-presigned-url](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) | bearer-токен, TTL, многоразовый; PUT заменяет объект; SigV4 checksums | §12.2 | | AWS presigned upload | [PresignedUrlUploadObject](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) | Content-Type может быть частью подписи; URL надо использовать без изменений | §7.2, §10.3 | | Stripe idempotency | [Idempotent requests](https://docs.stripe.com/api/idempotent_requests) | сравнение параметров, ошибка при отличии, результат после начала выполнения | §8.3 (claim после валидации, 409) | | Compose startup order | [docs.docker.com](https://docs.docker.com/compose/how-tos/startup-order/) | `service_completed_successfully` поддерживается; уже используется для `migrate` | §4.3 | | PostgreSQL advisory locks | [functions-admin](https://www.postgresql.org/docs/current/functions-admin.html) | session-level lock живёт на соединении | §9.2 | | SeaweedFS S3 | [Amazon S3 API wiki](https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API), [S3 Credentials](https://github.com/seaweedfs/seaweedfs/wiki/S3-Credentials) | presigned URL, Head/Copy/List, path-level identities | подтверждено spike | | SeaweedFS checksum | spike 2026-10-21 | signed `x-amz-checksum-sha256` с неверным телом → 200; HeadObject checksum пуст | §7.2, §10.3 | | SeaweedFS health | spike | `/healthz` → 200, старт ~20 с | §4.3 | ### 18.2. Осознанные компромиссы 1. **Readiness не включает S3.** S3 общий для всех реплик; его недоступность убрала бы весь стенд из ротации. Вместо этого attachment-endpoint дают 503, остальные работают. Зафиксировать в REPORT. 2. **Presigned PUT ограничен подписанным `Content-Length`.** S3 отклоняет другой размер (403); complete повторно проверяет размер/SHA/структуру. Квоты и rate limiting не входят в lab4. 3. **Complete перечитывает объект из S3.** SeaweedFS не валидирует и не хранит checksum, поэтому честная проверка SHA требует чтения. Трафик API при этом ≈ размеру файла; выигрыш presign — в клиентском плече и отсутствии приёма тела API. Отражено в §12.4. 4. **Структурная проверка вместо decode+re-encode.** OWASP рекомендует re-encode, но для 40 MP это дорого по памяти; lab4 не обрабатывает изображения, только хранит и отдаёт. lab5 добавит decode. 5. **Статический `infra/s3/s3.json`.** Синтетические креды дублируются в `.env.example`; дрейф ловится `scripts/check_s3_creds.py`. Альтернатива — рендерить JSON из env в entrypoint, но это ухудшает читаемость и аудит политик. 6. **Дополнительные эндпоинты вне ogen.** Контракт не меняется; presign-роуты сами проверяют auth/JSON/метод и используют общий формат ошибок. Это осознанная цена за неизменный `contracts/openapi.json`. 7. **SeaweedFS-контейнер — vendor image.** Требование «непривилегированный пользователь» из lab3 относится к контейнеру приложения (API image остаётся `USER 10001`); сторонний S3-образ запускается как опубликован, его порты не публикуются, кроме loopback S3. Зафиксировать в REPORT. 8. **Attachment ID генерирует приложение (UUIDv7).** Позволяет сформировать S3-ключ до INSERT; уникальность обеспечивается PK. `uuid.NewV7()` есть в google/uuid v1.6.0. ### 18.3. Остаточные риски и как их ловим | Риск | Вероятность | Митигация | |---|---|---| | `sqlc` неудобно мапит `uuid[]` | средняя | проверить `make sqlc`; fallback — цикл ≤10 запросов | | SeaweedFS не принимает path-scoped `List` | средняя | s3init проверяет; fallback `List:bucket`, REPORT | | `CopyObject` с metadata REPLACE ведёт себя иначе | низкая | интеграционный тест presign; проверить Head после copy | | ogen-генерация из производной спеки разойдётся с контрактом | низкая | `tools/specgen` падает на любом другом `anyOf`; `-check` в CI | | presign-клиент не дочитывает поток и SHA неполный | низкая | `Validate` обязан читать до EOF; тест с хвостом | | Sweep удалит объект идущей загрузки | низкая | grace + только объекты старше grace; тест | | S3-креды в `.env` разойдутся с identities | средняя | `check_s3_creds.py` в `make check` | | CI не дождётся SeaweedFS | средняя | healthcheck + start_period 60s + retry в s3init | | `memory.current` искажён page cache | высокая | основная метрика `anon` + `docker stats` | | 10 MiB тело в unit-тесте замедлит прогон | низкая | в тестах задавать маленькие лимиты через конфиг | ### 18.4. Ссылки - Контракт: `contracts/openapi.json` (1.4.0), `contracts/README.md` §«Вложения». - OWASP: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html - AWS presigned URLs: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html - AWS presigned upload: https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html - AWS object integrity: https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html - Stripe idempotency: https://docs.stripe.com/api/idempotent_requests - Compose startup order: https://docs.docker.com/compose/how-tos/startup-order/ - PostgreSQL advisory locks: https://www.postgresql.org/docs/current/functions-admin.html - SeaweedFS S3 API: https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API - SeaweedFS credentials: https://github.com/seaweedfs/seaweedfs/wiki/S3-Credentials - SeaweedFS compose: https://github.com/seaweedfs/seaweedfs/wiki/Docker-Compose-for-S3 - ogen sum types: `github.com/ogen-go/ogen@v1.24.0/gen/schema_gen_sum.go` - Go PNG config: `image/png/reader.go` (`DecodeConfig`), JPEG: `image/jpeg/reader.go` (`DecodeConfig`)