Files

83 KiB
Raw Permalink Blame History

План реализации лабораторной 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, minio/minio no longer available.

Контракт 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. Архитектура

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. Базовая проверка (до изменений)

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

{
  "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

  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/<uuid> с телом ok, HeadObject, ListObjectsV2(prefix="staging/"), затем DeleteObject. Все операции — app-кредами. Так bootstrap проверяет не только наличие bucket, но и реальные права API.
  4. Проверить, что app-креды не могут писать вне разрешённых префиксов (PutObject в forbidden/<uuid> → ожидается 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

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:

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:

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

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).

-- +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):

-- 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:

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

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:

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):

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/<chat_id>/<id>".
  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):

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/<chat>/<id>, объект пишется сразу в финальный ключ;
    • presign: ключ staging/presign/<chat>/<id>, клиент пишет по подписи.
  • ready — объект и метаданные согласованы; API отдаёт 201/200.
  • failed — только для presign-валидации (error_code), в lab4 наружу не отдаётся (409).

9.2. Sweeper

internal/service/attachment/sweeper.go. Запуск из main как goroutine с sweep_interval, остановка по контексту. Один владелец:

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:

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:

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:

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:

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:

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):

POST /api/v1/chats/{chat_id}/attachments/presign
Authorization: Bearer <token>
Content-Type: application/json

{"filename":"photo.png","content_type":"image/png","size_bytes":12345,"sha256":"<64 hex>"}

201:

{"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 подписан); остальные заголовки не обязательны.

POST /api/v1/attachments/{attachment_id}/complete
Authorization: Bearer <token>
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/<chat>/<id>;
  • 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/<chat>/<id>, 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=<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 он многоразовый до истечения, а PUT заменяет объект по тому же ключу. Complete проверит размер/SHA и либо примет, либо удалит; отозвать URL можно только отзывом кредов (не делаем). Минимальный TTL и приватный bucket — основные компенсации.
  • Ключ назначает сервер (staging/presign/<chat>/<id>), 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. Локальный прогон

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 не доверять Content-Type, генерировать имя, лимит размера, авторизация, хранить вне webroot подтверждено
AWS presigned URLs using-presigned-url bearer-токен, TTL, многоразовый; PUT заменяет объект; SigV4 checksums §12.2
AWS presigned upload PresignedUrlUploadObject Content-Type может быть частью подписи; URL надо использовать без изменений §7.2, §10.3
Stripe idempotency Idempotent requests сравнение параметров, ошибка при отличии, результат после начала выполнения §8.3 (claim после валидации, 409)
Compose startup order docs.docker.com service_completed_successfully поддерживается; уже используется для migrate §4.3
PostgreSQL advisory locks functions-admin session-level lock живёт на соединении §9.2
SeaweedFS S3 Amazon S3 API 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. Ссылки