83 KiB
План реализации лабораторной 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
Алгоритм:
- Прочитать env
S3_ENDPOINT,S3_BUCKET, admin-креды и app-креды; таймаут 120 с. - Цикл с backoff:
HeadBucket(admin); 404 →CreateBucket;BucketAlreadyOwnedByYou/BucketAlreadyExists— успех. Проверено на SeaweedFS 3.80: повторныйCreateBucketдаёт 409 BucketAlreadyExists (неBucketAlreadyOwnedByYou), поэтомуHeadBucket— основной идемпотентный путь, а 409 при гонке тоже считается успехом. - Проверить app-идентичность:
PutObjectprobe-ключаstaging/.bootstrap/<uuid>с теломok,HeadObject,ListObjectsV2(prefix="staging/"), затемDeleteObject. Все операции — app-кредами. Так bootstrap проверяет не только наличие bucket, но и реальные права API. - Проверить, что app-креды не могут писать вне разрешённых префиксов (
PutObjectвforbidden/<uuid>→ ожидается 403); иначе конфигурация identities небезопасна — exit 1. - Лог
bucket readyи выход 0; любая другая ошибка — exit 1. - Повторный запуск должен завершаться 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; корректно обрабатывать
FF00stuffing и 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:DialContexttimeout 3s,TLSHandshakeTimeout3s,ResponseHeaderTimeout15s, без общего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
}
Шаги строго в этом порядке:
validateFilename: UTF-8 валиден, 1–255 code points, нет/,\, NUL,unicode.IsControl.repo.IsChatMember(chatID, ownerID); нет —ErrNotFound.- 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.
- использовать
imagecheck.ValidateFile(path, maxPixels); тип из содержимого должен совпасть с заявленнымContent-Type(иначеErrUnsupportedMedia); пиксели —ErrTooLarge.id := uuid.Must(uuid.NewV7());key := "attachments/<chat_id>/<id>".repo.CreateAttachment(pending)с size/sha/type/owner.store.Put(ctx, key, file (Seek(0)), size, contentType, {"sha256": hex}). Ошибка → best-effortrepo.DeletePending; вернутьErrUnavailable.repo.MarkAttachmentReady(id, key). Ошибка → вернутьErrUnavailable; объект и pending-строка остаются, sweeper разберётся (см. §9). 201 не возвращать.- Вернуть
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):
repo.GetAttachmentForMember(SQL уже проверяет членство) → нет:ErrNotFound.status != ready→ErrConflict.store.Open(object_key);NotFound→ErrNotFound(метаданные есть, объекта нет — 404), прочее →ErrUnavailable.- Вернуть запись и 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:
repo.IsChatMember→ 404.repo.ListAttachmentStatesForChat(chatID, ids):- найдено меньше, чем запрошено →
ErrNotFound; - любой статус
failed→ErrConflict; - любой статус
pending→ErrConflict(в lab4 клиент не может прикрепить незавершённую загрузку).
- найдено меньше, чем запрошено →
repo.Create(draft)в одной транзакции:- claim idempotency;
- insert message;
- insert links (по порядку, position 0..n-1);
- complete idempotency.
- 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>, клиент пишет по подписи.
- proxy: ключ
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):
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объекта и строки (клиент не завершил).
- proxy-ключ (
List("attachments/")иList("staging/"); для объектов старше grace. Проверить path-scopedList:bucket/attachments/*иList:bucket/staging/*; если SeaweedFS их не принимает — оставитьList:bucketи зафиксировать в REPORT (s3init делает пробныйListObjectsV2по каждому prefix и падает, если прав нет):- собрать множество ключей из
attachments(батчами; lab-масштаб); staging/*: удалить, если объекта нет среди pending-строк моложе grace (т.е. брошен);attachments/*: удалить только если нет строки вообще (orphan) — ready-строки и их объекты не трогать никогда.
- собрать множество ключей из
- Логировать только счётчики: 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_bytes1..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:
- Bearer + UUID;
GetAttachmentForOwnerForUpdate(owner + chat membership); чужой → 404. ready→ если sha совпадает, вернуть 200; иначе 409.pending:Head(staging_key); нет объекта → 409incomplete;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.
- Ошибки 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— mockStore/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.
- filename: пусто, 256 code points,
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, constraintmessages_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.
- 10 MiB+1 → 413; 0 байт → 415; PNG с битым CRC → 415; JPEG, объявленный как PNG → 415;
filename
student-tests/attachment_failover.py:- upload через LB, получить
X-Instance-Idи SHA; TARGET_INSTANCE_ID=<id> scripts/stop-one.sh;- download через LB, сравнить байты/SHA; metadata через GET;
docker compose up -d --no-deps apiвернуть реплику.
- upload через LB, получить
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, summarysummary.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 testPASS.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. Подводные камни (проверено)
- ogen + anyOf — не использовать
ignore_not_implemented; он выкидывает операции. Только производная спека. Message.attachment_idsобязателен, а ogen-энкодер опускает nil-слайс. Всегда[]oas....messages_text_not_blankв БД блокирует сообщения только с вложениями — снять constraint.- Глобальный body limit 256 KiB — иначе upload не пройдёт; сделать per-route.
- ogen upload body —
io.Reader, не JSON; не пытаться декодировать. *http.MaxBytesError— единственный надёжный признак 413 при chunked-теле.- Content-Type из заголовка не доверять; SeaweedFS не валидирует checksum (проверено).
- filename — Unicode code points, не байты;
char_lengthв PG считает code points. - Пиксельный лимит до декодирования; полный
image.Decodeна 40 MP = до 160 MB. error_code=null—oas.NilString{Null: true}, не пустая строка.variants=[], не nil.- Membership в SQL — не выбирать объект, а потом проверять (лишний 403/404 и утечка).
- 201 только после S3+БД; pending-строка не должна отдаваться как ready.
- Fingerprint идемпотентности включает attachment_ids в порядке запроса (перестановка — другой payload, 409); отсутствующий список = [].
- Claim ключа после валидации, иначе неудачный запрос оставит занятый ключ без message_id.
- Транзакция message + links; FK и статус вложения проверять до claim.
- S3 ключи/креды не логировать; ошибки наружу — общий
Error. - S3 down → 503, не 500; readiness не трогать.
- Sweeper не удаляет ready; grace; advisory lock; идемпотентность.
- Presign URL host должен быть доступен клиенту; подпись привязана к Host.
- Complete обязан пересчитать SHA (SeaweedFS не хранит checksum — HeadObject пуст).
- CopyObject + MarkReady: final_key обновляется в одной UPDATE; иначе orphan.
- Temp-файлы удалять; после 201 на API нет оригинала.
- Docker Desktop не шарит
/tmp— конфиги монтировать из репозитория (проверено). - SeaweedFS стартует ~20 с —
start_period: 60s, s3-init с retry. - Порты SeaweedFS — только 8333 на loopback; master/volume/filer/console не публиковать.
scripts/stop-one.shхардкодит проект lab3 — обновить.- CI должен поднимать S3 и ждать readiness; presign-тест ходит на
127.0.0.1:8333. make validateтребуетrequirements-dev.txt; локально —.venv.- sqlc требует перегенерации после миграции/запросов;
make sqlc. - ogen типы:
AttachmentIds(неAttachmentIDs),AttachmentHeadersобщий для upload/get, download — отдельные типы на каждый content-type. DownloadAttachmentParams.Variant— enum сoriginal; остальное ogen отклонит.- Streaming download: закрывать body на EOF; иначе утечка соединений S3.
- ReadTimeout сервера не должен рвать большие downloads: ставить только на чтение запроса, не на запись ответа.
- Down-миграция с восстановлением
messages_text_not_blankупадёт при attachment-only строках — задокументировать. - Секреты в
.envне коммитить;infra/s3/s3.json— только синтетические локальные креды. make generate-apiдолжен быть воспроизводим:.cache/в gitignore, версия ogen вgo.mod.AttachmentHeaders.XInstanceIDне обязателен: заголовок ставит middleware; X-Request-Id — ставить.- Presign-роуты вне ogen — сами проверяют метод/JSON/401 и формат ошибок.
- Трек 1: не заявлять, что API вообще не читает файл; complete перечитывает его для SHA.
- S3-креды не делать
requiredв общем конфиге — иначеcmd/migrateи unit-тесты падают без S3; проверять вobjectstore.New. При этом ключи должны быть вdefaults(пустыми), иначе viperUnmarshalне увидитS3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY(проверено). cmd/s3initне должен зватьconfig.Load— у него только admin-переменные.- sqlc и
uuid[]: проверить сгенерированный тип дляANY($1::uuid[]); при проблеме заменить на цикл точечных запросов (≤10 вложений) илиpgtype.Array. GET /attachments/{id}не должен отдавать 409 для pending/failed: контракт требует наблюдаемыеstatus/error_code; 409 — только/content.- Presigned PUT: подписывать
Content-Length(S3 вернёт 403 на другой размер); complete всё равно перепроверяет размер/SHA. - Presigned URL многоразовый и перезаписывает объект; complete проверяет фактические байты, после complete повторный PUT создаёт staging-orphan → sweep.
- Не подписывать Content-Type в presign — SDK может добавить его в SignedHeaders, клиент
получит
SignatureDoesNotMatch; передавать только Bucket/Key. memory.currentвключает page cache от temp-файлов; для RAM-эксперимента использоватьanon.- Sweeper: unlock advisory lock на том же соединении, иначе lock утечёт в пул; при shutdown сначала остановить sweeper, потом закрывать pool.
- Path-scoped
Listв SeaweedFS может не поддержаться; проверить в s3init, иначеList:bucket. http.ServeMuxmethod/wildcard patterns требуют Go 1.22+; проект на 1.27 — ок, но не регистрировать ext-роуты без проверки метода внутри (иначе 405 уйдёт в ogen).- SeaweedFS HeadObject не возвращает checksum; не строить complete на
ChecksumSHA256. GetAttachment200 иDownloadAttachment200 — разные типы (AttachmentHeadersvsDownloadAttachmentOKImage*Headers); не перепутать в type switch.- Readiness без S3 — осознанное решение; обосновать в REPORT (иначе S3-down уберёт все реплики).
- SeaweedFS CreateBucket идемпотентность: повторный вызов → 409
BucketAlreadyExists(проверено), а неBucketAlreadyOwnedByYou; сначалаHeadBucket, 409 при гонке — успех. - SeaweedFS HeadObject missing → 404
NotFound(проверено); маппить вErrNotFound, не 503. - CopyObject metadata:
MetadataDirective=REPLACE+ContentType/Metadataсохраняет sha256 и тип (проверено); без REPLACE метаданные источника могут не обновиться. - 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. План коммитов
lab4: стенд SeaweedFS, bucket bootstrap и конфигурация S3lab4: codegen-обход anyOf и модель вложенийlab4: proxy upload/download и attachment_ids в сообщенияхlab4: негативные тесты, sweeper и эксперимент по памятиlab4: presigned upload (трек 1) и доказательства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. Осознанные компромиссы
- Readiness не включает S3. S3 общий для всех реплик; его недоступность убрала бы весь стенд из ротации. Вместо этого attachment-endpoint дают 503, остальные работают. Зафиксировать в REPORT.
- Presigned PUT ограничен подписанным
Content-Length. S3 отклоняет другой размер (403); complete повторно проверяет размер/SHA/структуру. Квоты и rate limiting не входят в lab4. - Complete перечитывает объект из S3. SeaweedFS не валидирует и не хранит checksum, поэтому честная проверка SHA требует чтения. Трафик API при этом ≈ размеру файла; выигрыш presign — в клиентском плече и отсутствии приёма тела API. Отражено в §12.4.
- Структурная проверка вместо decode+re-encode. OWASP рекомендует re-encode, но для 40 MP это дорого по памяти; lab4 не обрабатывает изображения, только хранит и отдаёт. lab5 добавит decode.
- Статический
infra/s3/s3.json. Синтетические креды дублируются в.env.example; дрейф ловитсяscripts/check_s3_creds.py. Альтернатива — рендерить JSON из env в entrypoint, но это ухудшает читаемость и аудит политик. - Дополнительные эндпоинты вне ogen. Контракт не меняется; presign-роуты сами проверяют
auth/JSON/метод и используют общий формат ошибок. Это осознанная цена за неизменный
contracts/openapi.json. - SeaweedFS-контейнер — vendor image. Требование «непривилегированный пользователь» из lab3
относится к контейнеру приложения (API image остаётся
USER 10001); сторонний S3-образ запускается как опубликован, его порты не публикуются, кроме loopback S3. Зафиксировать в REPORT. - 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)