Files
mtusi2026lab4/LAB4-PLAN.md
T

1302 lines
83 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План реализации лабораторной 4 — S3-хранилище и вложения
Статус: рабочий план для агента-исполнителя. Выполнять фазы по порядку, после каждой — гейт приёмки.
База: ветка `lab4`, коммит `c4e8d48` (реальная история lab1–lab3 + skeleton lab4, контракт 1.4.0).
Цель: оценка **5**, трек **1 (presigned direct upload)**.
Стек: Go 1.27, PostgreSQL, SeaweedFS 3.80, HAProxy, Docker Compose.
---
## 0. Обязательные решения и их обоснование
### 0.1. MinIO недоступен — используем SeaweedFS
Проверено 2026-10-21:
- `docker pull minio/minio` → `pull access denied`, репозиторий удалён с Docker Hub;
- `https://dl.min.io/server/minio/release/linux-arm64/minio.RELEASE.2025-09-07T16-13-09Z` → HTTP 410;
- `quay.io/minio/minio` → `no such manifest`;
- `minio/mc` также отсутствует;
- публикации об удалении: [MinIO images disappeared from Docker Hub](https://www.stablebuild.com/blog/minio-images-disappeared-from-docker-hub),
[minio/minio no longer available](https://github.com/milvus-io/milvus/issues/53430).
Контракт `contracts/infrastructure.json` разрешает `choose_one: [MinIO, SeaweedFS, RustFS]`.
Берём **SeaweedFS 3.80**: версия закреплена, multi-arch (amd64/arm64), поддерживает presigned GET/PUT,
декларативные identities с path-level правами, HeadObject, CopyObject, ListObjectsV2, lifecycle.
Spike подтвердил: presigned PUT 200, просроченный URL 403, анонимный GET 403, запрет чужого префикса 403,
CopyObject/Delete/Head/Get работают.
Пин: `chrislusf/seaweedfs:3.80@sha256:1055999e08eed1789b0ae45d235126e4495e23d3fb9d6396293fd42539b1ae6a`.
### 0.2. ogen v1.24.0 не умеет генерировать контракт 1.4.0
`Message` и `CreateMessage` содержат `anyOf` с двумя безымянными ветвями. ogen падает с
`Feature "sum types with same names" is not implemented`. Включение
`ignore_not_implemented` **молча выкидывает операции `CreateMessage`/`ListMessages`** — так делать нельзя.
Решение: генерировать из производной спеки, где удалён только `anyOf` у `Message` и `CreateMessage`.
Канонический `contracts/openapi.json` не меняется. Кросс-полевое правило
«text непустой ИЛИ attachment_ids непустой» реализуется в сервисе и проверяется тестами.
Инструмент: `tools/specgen/main.go` (чистый Go, без зависимостей), результат — `.cache/openapi.codegen.json`
(в `.gitignore`). `make generate-api` вызывает `go run ./tools/specgen` перед ogen.
`tools/specgen` обязан упасть, если в контракте появился любой другой `anyOf` — это защита от
молчаливой генерации неверных типов.
### 0.3. Границы
- Метаданные — только PostgreSQL; байты — только S3 (временный файл на API допустим и удаляется до 201).
- Обязательный proxy-upload/download сохраняется; presigned-путь — дополнительный.
- lab5 (thumbnail, 202/queued) не реализуем; `variants` всегда `[]`, `status` всегда `ready`.
- Контракт не редактируем; presign-эндпоинты монтируются вне ogen.
---
## 1. Матрица требований контракта
Каждая строка должна иметь тест и/или evidence-файл. Галочка ставится только после фактического прогона.
| # | Требование | Реализация | Проверка |
|---|---|---|---|
| 1 | `POST /chats/{id}/attachments?filename=` сырые PNG/JPEG, не multipart | ogen `UploadAttachment`, body streaming | `make test`, `student-tests/attachments_negative.py` |
| 2 | 10 MiB = 10 485 760 байт; превышение — 413 | per-route `MaxBytesReader` + счётчик | тест 10 MiB+1 |
| 3 | MIME по содержимому; чужой/битый формат — 415 | sniff + структурный парсер | подмена MIME, битый PNG |
| 4 | ≤ 40 млн пикселей; превышение — 413; лимит до декодирования | разбор IHDR/SOF, без полного raster | PNG 10000×10000 header |
| 5 | filename 1–255 code points; `/`, `\`, NUL, control — 400 | `utf8.RuneCountInString`, `unicode.IsControl` | табличные тесты + HTTP |
| 6 | 201 `Attachment` `status=ready`, `variants=[]`, `error_code=null` только после S3+БД | pending→S3 put→ready | smoke + сбой между шагами |
| 7 | `Message.attachment_ids` 0–10 уникальных, по умолчанию `[]` | ogen + сервис | smoke, unit |
| 8 | `text=""` разрешён при наличии вложения; пусто и без вложений — 400 | сервис | HTTP-тест |
| 9 | Вложения только из этого чата; чужое/неизвестное — 404 | SQL `chat_id` + membership | тест |
| 10 | Failed-вложение прикреплять нельзя (409) | проверка статуса | unit (failed-строка) |
| 11 | `GET /attachments/{id}` и `/content` только участникам; иначе 404 | один SQL-запрос с `chat_members` | smoke, outsider |
| 12 | Download — байты с истинным Content-Type, без redirect | streaming `GetObject` | сравнение SHA, заголовок |
| 13 | `variant` по умолчанию `original`; отсутствующий вариант — 404 | ogen enum + проверка | тест `?variant=thumbnail` → 404 |
| 14 | Ready metadata: `error_code=null`; sha/размер/тип описывают оригинал | маппинг | smoke |
| 15 | Не раскрывать ключи бакета, адреса, credentials | маппинг + логи | ревью ответов/логов |
| 16 | S3 в общем стенде; bucket приватный | compose + identities без anonymous | anonymous GET 403 |
| 17 | Upload → stop реплики → download другой репликой | stateless S3 + 2 API | `student-tests/attachment_failover.py` |
| 18 | Restart стенда с volumes сохраняет метаданные и оригинал | named volumes | evidence |
| 19 | Уровень 4: негативные тесты | см. §11 | `student-tests/attachments_negative.py` |
| 20 | Отказ между S3 и БД не оставляет вечных объектов; grace period | pending + sweeper | инъекция + evidence |
| 21 | Лимиты/таймауты/стриминг, RAM не растёт неограниченно | temp-file spool + streaming | эксперимент ≥10 загрузок |
| 22 | Bucket bootstrap идемпотентен | `cmd/s3init` | повторный запуск |
| 23 | Отдельные S3 credentials с ограниченными правами | identities admin/app, path-level | 403 на чужой префикс |
| 24 | Админ-консоль не в общей сети | не публикуем порты SeaweedFS, кроме S3 loopback | `docker compose ps` |
| 25 | Трек 1: presigned upload, ownership, size/checksum at complete, incomplete cleanup | §10.3, §12 | `student-tests/presign_flow.py` |
| 26 | Трек 1: сравнение трафика и RAM на ≥2 размерах | §12.4 | `evidence/lab4/track1/` |
| 27 | `GET /attachments/{id}` отдаёт метаданные при любом статусе; 409 только `/content` | отдельные `Get`/`Open` | unit/HTTP |
---
## 2. Архитектура
```mermaid
flowchart LR
C[Client] -->|HTTP API| LB[HAProxy :8080]
LB --> A1[API replica 1]
LB --> A2[API replica 2]
A1 --> PG[(PostgreSQL)]
A2 --> PG
A1 -->|S3 SDK| S3[(SeaweedFS :8333)]
A2 -->|S3 SDK| S3
A1 -->|presigned PUT URL| C
C -->|PUT по подписи| S3
A1 -.->|sweep, advisory lock| PG
A1 -.->|sweep| S3
```
- Единственная точка входа для клиента — LB (loopback). S3 опубликован на `127.0.0.1:8333` только для presigned-трека и evidence; анонимный доступ запрещён identities.
- Readiness API проверяет PostgreSQL; S3 в readiness **не входит**. При падении S3 остальные endpoint работают, вложения дают 503.
- Sweep запускается в каждой реплике, но работает только владелец advisory lock.
---
## 3. Фаза 0. Базовая проверка (до изменений)
```sh
cd /Users/vladislav/Projects/mtusi2026lab4
git status --short # пусто
go build ./...
go test -race -shuffle=on -count=1 -timeout=5m ./...
cp -n .env.example .env
docker compose --env-file .env up -d --build
curl -fsS http://localhost:8080/health/ready
make test # ожидаемо FAIL: missing required fields (attachment_ids)
docker compose --env-file .env down
```
Ожидаемый результат: сборка и unit-тесты зелёные; smoke падает на отсутствии `attachment_ids`.
Это фиксируется в `evidence/lab4/baseline.txt`.
---
## 4. Фаза 1. Стенд SeaweedFS
### 4.1. Файлы
- `infra/s3/s3.json` — identities (коммитится, синтетические креды).
- `infra/s3/README.md` — как устроены права и как проверить приватность.
- `cmd/s3init/main.go` — идемпотентный bootstrap bucket.
- `compose.yaml` — сервисы `seaweedfs`, `s3-init`; API получает S3-переменные.
- `Dockerfile` — собрать и скопировать `/usr/local/bin/s3init`.
- `.env.example` — S3-переменные.
### 4.2. `infra/s3/s3.json`
```json
{
"identities": [
{
"name": "admin",
"credentials": [{"accessKey": "lab4admin", "secretKey": "lab4admin-secret"}],
"actions": ["Admin", "Read", "Write", "List", "Tagging"]
},
{
"name": "app",
"credentials": [{"accessKey": "lab4app", "secretKey": "lab4app-secret"}],
"actions": [
"Read:messenger-attachments/attachments/*",
"Write:messenger-attachments/attachments/*",
"Read:messenger-attachments/staging/*",
"Write:messenger-attachments/staging/*",
"List:messenger-attachments"
]
}
]
}
```
Проверено spike: app-ключ получает 403 на `other/*`, 200 на `attachments/*`; presigned PUT в `staging/*` работает;
анонимный GET — 403. Имя bucket `messenger-attachments` валидно (3–63 lowercase); односимвольные
имена SeaweedFS отклоняет с `InvalidBucketName`.
### 4.3. `compose.yaml`
```yaml
seaweedfs:
image: chrislusf/seaweedfs:3.80@sha256:1055999e08eed1789b0ae45d235126e4495e23d3fb9d6396293fd42539b1ae6a
command:
- server
- -s3
- -s3.config=/etc/seaweedfs/s3.json
- -dir=/data
- -master.volumeSizeLimitMB=64
volumes:
- ./infra/s3/s3.json:/etc/seaweedfs/s3.json:ro
- seaweedfs-data:/data
ports:
- "127.0.0.1:${S3_PORT:-8333}:8333"
healthcheck:
test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8333/healthz || exit 1"]
interval: 5s
timeout: 3s
retries: 20
start_period: 60s
restart: unless-stopped
s3-init:
<<: *app
entrypoint: ["/usr/local/bin/s3init"]
environment:
S3_ENDPOINT: http://seaweedfs:8333
S3_REGION: us-east-1
S3_BUCKET: messenger-attachments
S3_ADMIN_ACCESS_KEY: lab4admin
S3_ADMIN_SECRET_ACCESS_KEY: lab4admin-secret
S3_ACCESS_KEY_ID: lab4app
S3_SECRET_ACCESS_KEY: lab4app-secret
depends_on:
seaweedfs:
condition: service_healthy
restart: "no"
```
API:
- `depends_on: s3-init: condition: service_completed_successfully`;
- `S3_ENDPOINT=http://seaweedfs:8333`, `S3_PUBLIC_ENDPOINT=http://127.0.0.1:8333`,
`S3_ACCESS_KEY_ID=lab4app`, `S3_SECRET_ACCESS_KEY=lab4app-secret`, остальные лимиты.
`seaweedfs-data` добавить в `volumes`.
### 4.4. `cmd/s3init`
Алгоритм:
1. Прочитать env `S3_ENDPOINT`, `S3_BUCKET`, admin-креды и app-креды; таймаут 120 с.
2. Цикл с backoff: `HeadBucket` (admin); 404 → `CreateBucket`; `BucketAlreadyOwnedByYou`/
`BucketAlreadyExists` — успех. Проверено на SeaweedFS 3.80: повторный `CreateBucket` даёт
**409 BucketAlreadyExists** (не `BucketAlreadyOwnedByYou`), поэтому `HeadBucket` — основной
идемпотентный путь, а 409 при гонке тоже считается успехом.
3. Проверить app-идентичность: `PutObject` probe-ключа `staging/.bootstrap/<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
```sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps # только lb публикует 8080/8404, seaweedfs — 127.0.0.1:8333
curl -fsS http://localhost:8080/health/ready
docker compose --env-file .env run --rm s3-init # повторный bootstrap: exit 0
docker compose --env-file .env exec -T seaweedfs \
wget -qO- http://127.0.0.1:8333/messenger-attachments/attachments/nope 2>&1 | head
# ожидаем 403 AccessDenied
python3 scripts/check_s3_creds.py # identities == .env.example/.env
```
---
## 5. Фаза 2. Конфигурация и codegen
### 5.1. `tools/specgen/main.go`
- Читает `contracts/openapi.json`.
- Проверяет `info.version == "1.4.0"` и `lab.json.contract_version == "1.4.0"`.
- Удаляет `anyOf` только у `components.schemas.Message` и `components.schemas.CreateMessage`.
- Если в документе есть любой другой `anyOf`/`oneOf` — завершается с ошибкой.
- Пишет `.cache/openapi.codegen.json` (pretty JSON, детерминированный порядок ключей не важен).
- Флаг `-check`: проверить, что производная спека соответствует текущей (для CI).
`Makefile`:
```make
generate-api:
$(GO) run ./tools/specgen
$(GO) tool ogen --config $(OGEN_CONFIG) --target $(OAS_DIR) --package oas --clean .cache/openapi.codegen.json
```
`.gitignore`: добавить `.cache/`.
### 5.2. Конфиг
`internal/config/config.go`:
```go
type S3 struct {
Endpoint string `mapstructure:"endpoint" validate:"required,url"`
PublicEndpoint string `mapstructure:"public_endpoint" validate:"omitempty,url"`
Region string `mapstructure:"region" validate:"required"`
Bucket string `mapstructure:"bucket" validate:"required"`
// Креды НЕ required в общем валидаторе: config.Load используют cmd/migrate и unit-тесты,
// которым S3 не нужен. Наличие ключей проверяет objectstore.New (только в cmd/messenger).
AccessKeyID string `mapstructure:"access_key_id"`
SecretAccessKey string `mapstructure:"secret_access_key"`
UsePathStyle bool `mapstructure:"use_path_style"`
Timeout time.Duration `mapstructure:"timeout" validate:"required,gt=0"`
MaxUploadBytes int64 `mapstructure:"max_upload_bytes" validate:"required,gt=0,lte=10485760"`
MaxImagePixels int64 `mapstructure:"max_image_pixels" validate:"required,gt=0,lte=40000000"`
PresignTTL time.Duration `mapstructure:"presign_ttl" validate:"required,gt=0"`
SweepInterval time.Duration `mapstructure:"sweep_interval" validate:"required,gt=0"`
SweepGrace time.Duration `mapstructure:"sweep_grace" validate:"required,gt=0"`
}
type Config struct { ... S3 S3 `mapstructure:"s3"` }
```
Defaults: `localhost:8333`, `us-east-1`, bucket `messenger-attachments`,
`max_upload_bytes: 10485760`, `max_image_pixels: 40000000`, `presign_ttl: 5m`,
`sweep_interval: 1m`, `sweep_grace: 10m`, `timeout: 30s`, `use_path_style: true`.
`PublicEndpoint` по умолчанию = `Endpoint`.
Добавить `Server.ReadTimeout` (60s) для загрузок; сохранить `ShutdownTimeout`.
Ключи S3 не обязательны для `config.Load`: `cmd/migrate` и unit-тесты не должны требовать S3.
`objectstore.New` возвращает ошибку при пустых ключах/endpoint; `cmd/messenger` вызывает его,
`cmd/migrate` — нет. Это же снимает поломку `internal/config/config_test.go`.
`.env.example`: `S3_ENDPOINT`, `S3_PUBLIC_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`,
`S3_SECRET_ACCESS_KEY`, `S3_PRESIGN_TTL`, `S3_SWEEP_INTERVAL`, `S3_SWEEP_GRACE`, а также
`MAX_UPLOAD_BYTES`/`MAX_IMAGE_PIXELS` (как в skeleton). Viper по умолчанию даст для них
`S3_MAX_UPLOAD_BYTES`/`S3_MAX_IMAGE_PIXELS`, поэтому добавить явные alias-биндинги:
`v.BindEnv("s3.max_upload_bytes", "MAX_UPLOAD_BYTES")` и
`v.BindEnv("s3.max_image_pixels", "MAX_IMAGE_PIXELS")`. Синтетические креды совпадают с
`infra/s3/s3.json` — добавить комментарий об этом в оба файла.
### 5.3. Приёмка фазы 2
```sh
make generate-api
go build ./...
go test ./internal/config/...
make check validate PYTHON=.venv/bin/python
```
Проверить в сгенерированном коде: `UploadAttachment`, `GetAttachment`, `DownloadAttachment`,
`CreateMessage.AttachmentIds`, `Message.AttachmentIds`, `AttachmentHeaders`.
---
## 6. Фаза 3. Данные
### 6.1. Миграция `00004_attachments.sql`
Номер 4 обязателен: версия 2 занята в БД, перенесённой из lab2 (см. комментарий в `00003`).
```sql
-- +goose Up
CREATE TABLE attachments (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
owner_id uuid NOT NULL REFERENCES users (id) ON DELETE RESTRICT,
object_key text NOT NULL,
filename text NOT NULL,
content_type text NOT NULL,
size_bytes bigint NOT NULL,
sha256 text NOT NULL,
status text NOT NULL,
error_code text,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT attachments_object_key_key UNIQUE (object_key),
CONSTRAINT attachments_status_check CHECK (status IN ('pending','ready','failed')),
CONSTRAINT attachments_content_type_check CHECK (content_type IN ('image/png','image/jpeg')),
CONSTRAINT attachments_filename_length CHECK (char_length(filename) BETWEEN 1 AND 255),
CONSTRAINT attachments_size_check CHECK (size_bytes BETWEEN 1 AND 10485760),
CONSTRAINT attachments_sha256_check CHECK (sha256 ~ '^[0-9a-f]{64}$'),
CONSTRAINT attachments_error_consistency CHECK (
(status = 'ready' AND error_code IS NULL) OR
(status = 'failed' AND error_code IS NOT NULL) OR
status = 'pending'
)
);
CREATE INDEX attachments_chat_id_created_at_id_idx ON attachments (chat_id, created_at, id);
CREATE INDEX attachments_status_created_at_idx ON attachments (status, created_at);
CREATE TABLE message_attachments (
message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
attachment_id uuid NOT NULL REFERENCES attachments (id) ON DELETE RESTRICT,
position smallint NOT NULL,
PRIMARY KEY (message_id, attachment_id),
CONSTRAINT message_attachments_position_check CHECK (position BETWEEN 0 AND 9),
CONSTRAINT message_attachments_position_key UNIQUE (message_id, position)
);
CREATE INDEX message_attachments_attachment_id_idx ON message_attachments (attachment_id);
-- Ключевое: текстовые сообщения lab1–3 остаются валидными, но теперь
-- разрешён text='' при наличии вложений. Правило проверяется в сервисе.
ALTER TABLE messages DROP CONSTRAINT messages_text_not_blank;
-- +goose Down
-- ВНИМАНИЕ: откат упадёт, если уже есть сообщения только с вложениями.
ALTER TABLE messages ADD CONSTRAINT messages_text_not_blank CHECK (btrim(text) <> '');
DROP TABLE message_attachments;
DROP TABLE attachments;
```
### 6.2. Запросы `queries/attachments.sql`
Обязательный набор (имена — sqlc):
```sql
-- name: CreateAttachment :one
INSERT INTO attachments (id, chat_id, owner_id, object_key, filename, content_type, size_bytes, sha256, status)
VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'pending')
RETURNING ...;
-- name: MarkAttachmentReady :one
UPDATE attachments
SET status='ready', object_key=sqlc.arg(object_key), updated_at=now()
WHERE id=sqlc.arg(id) AND status='pending'
RETURNING ...;
-- name: GetAttachmentForMember :one
SELECT a.id, a.chat_id, a.owner_id, a.filename, a.content_type, a.size_bytes,
a.sha256, a.status, a.error_code, a.object_key, a.created_at, a.updated_at
FROM attachments a
JOIN chat_members cm ON cm.chat_id = a.chat_id AND cm.user_id = sqlc.arg(user_id)
WHERE a.id = sqlc.arg(id);
-- name: GetAttachmentForOwnerForUpdate :one
SELECT a.* FROM attachments a
JOIN chat_members cm ON cm.chat_id = a.chat_id AND cm.user_id = a.owner_id
WHERE a.id = sqlc.arg(id) AND a.owner_id = sqlc.arg(owner_id)
FOR UPDATE OF a;
-- name: ListAttachmentStatesForChat :many
SELECT id, status FROM attachments
WHERE chat_id=sqlc.arg(chat_id) AND id = ANY(sqlc.arg(ids)::uuid[]);
-- name: AttachToMessage :exec
INSERT INTO message_attachments (message_id, attachment_id, position)
VALUES ($1,$2,$3);
-- name: ListMessageAttachments :many
SELECT message_id, attachment_id
FROM message_attachments
WHERE message_id = ANY(sqlc.arg(message_ids)::uuid[])
ORDER BY message_id, position;
-- name: DeletePendingAttachment :exec
DELETE FROM attachments WHERE id=sqlc.arg(id) AND status='pending';
-- name: ListStalePendingAttachments :many
SELECT ... FROM attachments
WHERE status='pending' AND created_at < now() - sqlc.arg(grace)::interval
ORDER BY created_at LIMIT 100
FOR UPDATE SKIP LOCKED;
-- name: ListAttachmentKeys :many
SELECT id, object_key, status, created_at FROM attachments ORDER BY id LIMIT sqlc.arg(limit) OFFSET sqlc.arg(offset);
```
`GetMessageByID` и `ListMessagesForChat*` не меняются; вложения подтягиваются вторым запросом по `message_id`.
N+1 нет: один запрос на страницу (≤100 сообщений).
### 6.3. Домен
`internal/domain/attachment.go`:
```go
type AttachmentStatus string
const (
AttachmentPending AttachmentStatus = "pending"
AttachmentReady AttachmentStatus = "ready"
AttachmentFailed AttachmentStatus = "failed"
)
type Attachment struct {
ID uuid.UUID
ChatID, OwnerID uuid.UUID
Filename string
ContentType string
SizeBytes int64
SHA256 string
Status AttachmentStatus
ErrorCode *string
CreatedAt, UpdatedAt time.Time
ObjectKey string // только внутри сервиса/хранилища, не в JSON
}
type Message struct { ... AttachmentIDs []uuid.UUID }
```
Новые sentinel-ошибки в `internal/domain/errors.go`: `ErrTooLarge`, `ErrUnsupportedMedia`,
`ErrIncomplete` (для presign complete). Маппинг в `errors.go`:
| Ошибка | HTTP |
|---|---|
| `ErrValidation`, `ErrUnknownMember`, `ErrInvalidCursor` | 400 |
| `ErrUnauthenticated` | 401 |
| `ErrNotFound` | 404 |
| `ErrConflict`, `ErrIdempotency`, `ErrUsernameTaken`, `ErrIncomplete` | 409 |
| `ErrTooLarge` | 413 |
| `ErrUnsupportedMedia` | 415 |
| `ErrUnavailable` | 503 |
| всё остальное | 500 |
`GET /attachments/{id}` (метаданные) отдаёт объект при любом статусе: контракт включает `status` и
`error_code` в Attachment, значит failed/pending должны быть наблюдаемы. Только `/content` для
pending/failed возвращает `ErrConflict` (409). В lab4 pending/failed наружу не появляются, но
поведение зафиксировано тестом.
---
## 7. Фаза 4. Валидация изображений и S3-порт
### 7.1. `internal/imagecheck`
```go
type Info struct { ContentType string; Width, Height int64 }
var ErrUnsupported, ErrTooLarge, ErrCorrupt error
func Validate(r io.Reader, maxPixels int64) (Info, error)
func ValidateFile(path string, maxPixels int64) (Info, error)
```
Правила:
- Прочитать сигнатуру. PNG: `\x89PNG\r\n\x1a\n`; JPEG: `FF D8 FF`.
- PNG: цикл чанков (length/type/data/crc), проверять CRC32 каждого чанка; требовать IHDR первым,
минимум один IDAT, IEND; размеры из IHDR; читать до EOF (хвост после IEND допустим, но учитывается в SHA).
- JPEG: SOI; маркеры с длиной; SOF0/1/2 даёт width/height; требовать SOS и EOI; корректно обрабатывать
`FF00` stuffing и RST0–RST7; обрыв до EOI — `ErrCorrupt`. Читать до EOF.
- `maxPixels`: `int64(w)*int64(h) > maxPixels` → `ErrTooLarge`; `w<=0 || h<=0` → `ErrCorrupt`.
- Никакого `image.Decode` и полного растра: память O(1), лимит пикселей проверяется до декодирования.
- Ошибки оборачивать с контекстом (`png chunk crc`, `jpeg segment`), наружу — sentinel.
Почему не `image.DecodeConfig`: в Go 1.27 `png.DecodeConfig` останавливается на IHDR (проверяет CRC
только прочитанных чанков) и не читает IDAT/IEND; `jpeg.DecodeConfig` разбирает только заголовок до
SOF. Обрезанный файл с валидным заголовком пройдёт их. Полный `image.Decode` на 40 MP аллоцирует
до 160 MB. Поэтому структурный потоковый парсер — осознанный выбор. OWASP рекомендует decode+re-encode,
но в lab4 изображения не обрабатываются и не исполняются, а отдаются как приватные байты, поэтому
структурной проверки достаточно; lab5 добавит контролируемый decode для thumbnail.
Табличные тесты: валидные PNG/JPEG (генерировать через `image/png`/`image/jpeg`), обрезанный PNG,
битый CRC, обрезанный JPEG, подменённая сигнатура, 0×0, 10000×10000 header (пиксельный лимит),
файл с мусором после IEND/EOI.
### 7.2. S3-порт
`internal/platform/objectstore`:
```go
type Object struct {
Key string
Size int64
ContentType string
LastModified time.Time
Metadata map[string]string
}
type Store interface {
Put(ctx context.Context, key string, body io.Reader, size int64, contentType string, metadata map[string]string) error
Open(ctx context.Context, key string) (io.ReadCloser, Object, error)
Head(ctx context.Context, key string) (Object, error)
Copy(ctx context.Context, src, dst, contentType string, metadata map[string]string) error
Delete(ctx context.Context, key string) error
List(ctx context.Context, prefix string) ([]Object, error)
PresignPut(ctx context.Context, key string, 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}, ...)`,
`Expires=ttl`. В input передавать **только** Bucket/Key: если передать ContentType/ChecksumSHA256,
SDK может добавить их в `X-Amz-SignedHeaders`, и клиент будет обязан прислать точные заголовки
(AWS docs прямо предупреждают об этом). Меньше связанных заголовков — меньше `SignatureDoesNotMatch`.
Content-Type и SHA проверяются на complete по фактическим байтам.
Проверено: SeaweedFS не валидирует `x-amz-checksum-sha256` и не возвращает его в HeadObject,
поэтому complete обязан пересчитать SHA.
- Все ошибки оборачивать `%w`, логировать без ключей.
---
## 8. Фаза 5. Сервис вложений
### 8.1. Загрузка (proxy)
`internal/service/attachment/service.go`, метод `Upload(ctx, UploadInput)`:
```go
type UploadInput struct {
ChatID uuid.UUID
OwnerID uuid.UUID
Filename string
DeclaredContentType string
Body io.Reader
}
```
Шаги строго в этом порядке:
1. `validateFilename`: UTF-8 валиден, 1–255 code points, нет `/`, `\`, NUL, `unicode.IsControl`.
2. `repo.IsChatMember(chatID, ownerID)`; нет — `ErrNotFound`.
3. Spool: `os.CreateTemp("", "lab4-upload-*")`, `defer os.Remove`, `defer Close`.
`io.CopyBuffer(io.MultiWriter(file, hasher), body, make([]byte, 32<<10))` с жёстким лимитом
`maxUploadBytes` (фиксированный буфер, размер памяти не зависит от файла):
- использовать `http.MaxBytesReader` на уровне HTTP; в сервисе — `io.LimitReader(body, max+1)`
и счётчик; `size > max` → `ErrTooLarge`;
- `*http.MaxBytesError` → `ErrTooLarge`;
- `size == 0` → `ErrUnsupportedMedia`.
4. `imagecheck.ValidateFile(path, maxPixels)`; тип из содержимого должен совпасть с заявленным
`Content-Type` (иначе `ErrUnsupportedMedia`); пиксели — `ErrTooLarge`.
5. `id := uuid.Must(uuid.NewV7())`; `key := "attachments/<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-запрос; статус не проверяется
(200 для ready/pending/failed, если объект доступен участнику). Проверка ready — только в `Open`
(для `/content`).
### 8.3. Сообщения
`domain.MessageDraft` получает `AttachmentIDs []uuid.UUID`.
`Validate`:
- `len > 10` → `ErrValidation`;
- дубликаты → `ErrValidation`;
- `text` пустой/пробельный **и** нет вложений → `ErrValidation`;
- text > 4000 code points — ogen уже валидирует, сервис дублирует.
`Service.Send`:
1. `repo.IsChatMember` → 404.
2. `repo.ListAttachmentStatesForChat(chatID, ids)`:
- найдено меньше, чем запрошено → `ErrNotFound`;
- любой статус `failed` → `ErrConflict`;
- любой статус `pending` → `ErrConflict` (в lab4 клиент не может прикрепить незавершённую загрузку).
3. `repo.Create(draft)` в одной транзакции:
- claim idempotency;
- insert message;
- insert links (по порядку, position 0..n-1);
- complete idempotency.
4. Replay: прочитать message + links; сравнить hash; вернуть с `AttachmentIDs`.
Fingerprint (в `handler.go`, `messageFingerprint`):
```go
ids := append([]uuid.UUID(nil), req.AttachmentIds...)
slices.SortFunc(ids, func(a, b uuid.UUID) int { return bytes.Compare(a[:], b[:]) })
payload, _ := json.Marshal(struct {
Text string `json:"text"`
AttachmentIDs []uuid.UUID `json:"attachment_ids"`
}{req.Text, ids})
```
Сортировка делает порядок вложений незначащим для идемпотентности; набор отличается — 409.
Отсутствующий `attachment_ids` и `[]` дают одинаковый fingerprint.
Замечание: записи lab3 в `message_idempotency` хранят старый hash; повтор такого ключа в течение TTL
даст 409. Отразить в REPORT.
`History`: после выборки страницы одним запросом получить links и разложить по `message_id`
(при пустой странице второй запрос не выполнять). Всегда возвращать непустой `AttachmentIds`
(см. §10.2). В `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`,
остановка по контексту. Один владелец:
```sql
SELECT pg_try_advisory_lock(0x4c414234); -- "LAB4"
```
Берётся на выделенном соединении (`pool.Acquire`), снимается в defer; при неудаче цикл пропускается.
Соединение нельзя возвращать в пул с удерживаемым session-level lock — unlock обязателен.
При shutdown сначала отменяется контекст sweeper и ждётся WaitGroup, иначе sweep может обратиться
к уже закрытому pool/store. Запуск — после успешных миграций и `s3init`.
Алгоритм (каждые `sweep_interval`, grace `sweep_grace`):
1. `ListStalePendingAttachments(grace)` — выбирать `FOR UPDATE SKIP LOCKED`, чтобы не пересечься
с идущим complete (он держит `FOR UPDATE` на строке). Все действия sweep идемпотентны:
повторный `Delete`/`MarkReady` безопасен, `MarkReady` условен по `status='pending'`.
- proxy-ключ (`attachments/...`): `Head`; если объект есть и size/sha совпадают → `MarkReady`
(восстановление после падения между S3 и UPDATE); иначе `Delete` объекта (best-effort) и строки.
- presign-ключ (`staging/...`): `Delete` объекта и строки (клиент не завершил).
2. `List("attachments/")` и `List("staging/")`; для объектов старше grace. Проверить
path-scoped `List:bucket/attachments/*` и `List:bucket/staging/*`; если SeaweedFS их не принимает —
оставить `List:bucket` и зафиксировать в REPORT (s3init делает пробный `ListObjectsV2` по каждому
prefix и падает, если прав нет):
- собрать множество ключей из `attachments` (батчами; lab-масштаб);
- `staging/*`: удалить, если объекта нет среди pending-строк моложе grace (т.е. брошен);
- `attachments/*`: удалить только если нет строки вообще (orphan) — ready-строки и их объекты
не трогать никогда.
3. Логировать только счётчики: scanned/deleted_objects/deleted_rows/recovered; ID — на debug.
Гарантии:
- ready-вложения и их объекты не удаляются;
- свежие объекты (< grace) не удаляются, поэтому гонка с идущей загрузкой безопасна;
- повторный запуск идемпотентен;
- при нескольких репликах работает одна.
Тест с инъекцией: в интеграционном тесте с fake store создать pending-строку без объекта,
pending-строку с объектом, ready-строку, orphan-объект; прогнать sweep; проверить результат.
Отдельный compose-сценарий с `SWEEP_GRACE=2s`, `SWEEP_INTERVAL=1s` и брошенным presign.
### 9.3. S3 outage
- `Upload` → `ErrUnavailable` (503), pending-строка удаляется best-effort.
- `Download` → 503.
- `/health/ready` остаётся 200; остальные endpoint работают. Зафиксировать в REPORT и evidence.
---
## 10. Фаза 7. HTTP-слой
### 10.1. Per-route body limit
`internal/transport/rest/bodylimit.go`:
```go
func bodyLimitMiddleware(defaultLimit, uploadLimit int64, log *slog.Logger, next http.Handler) http.Handler {
limit := defaultLimit
if isAttachmentUpload(r) { limit = uploadLimit }
...
}
func isAttachmentUpload(r *http.Request) bool {
return r.Method == http.MethodPost && attachmentUploadPath.MatchString(r.URL.Path)
}
var attachmentUploadPath = regexp.MustCompile(`^/api/v1/chats/[0-9a-fA-F-]{36}/attachments$`)
```
`uploadLimit = cfg.S3.MaxUploadBytes` (ровно 10 MiB). `ContentLength > limit` → 413 до чтения.
`MaxBytesReader(w, body, limit)`; ошибка чтения `*http.MaxBytesError` → 413.
Обновить `NewRouter`/`main` и `router_test.go`.
### 10.2. Handler
`internal/transport/rest/handler.go`:
```go
func (h *Handler) UploadAttachment(ctx context.Context, req oas.UploadAttachmentReq, params oas.UploadAttachmentParams) (oas.UploadAttachmentRes, error) {
body, declared, err := uploadBody(req) // switch по *oas.UploadAttachmentReqImagePNG / *oas.UploadAttachmentReqImageJpeg
att, err := h.attachments.Upload(ctx, attachment.UploadInput{
ChatID: params.ChatID, OwnerID: caller(ctx),
Filename: params.Filename, DeclaredContentType: declared, Body: body,
})
...
return &oas.AttachmentHeaders{
XRequestID: oas.NewOptString(requestIDFromContext(ctx)),
Response: attachmentResponse(att),
}, nil
}
```
`attachmentResponse`:
- `ID`, `ChatID`, `OwnerID`, `Filename`, `ContentType` (`oas.AttachmentContentTypeImagePNG` или
`oas.AttachmentContentTypeImageJpeg`),
- `SizeBytes: int(att.SizeBytes)`, `SHA256`,
- `Status: oas.AttachmentStatusReady`,
- `Variants: []oas.Variant{}` — **не nil**,
- `ErrorCode: oas.NilString{Null: true}`,
- `CreatedAt`, `UpdatedAt`.
`GetAttachment` — тот же `*oas.AttachmentHeaders`.
`DownloadAttachment`:
```go
att, body, err := h.attachments.Open(ctx, caller(ctx), params.AttachmentID)
defer? нет: body закроется на EOF
switch att.ContentType {
case "image/png": return &oas.DownloadAttachmentOKImagePNGHeaders{Response: oas.DownloadAttachmentOKImagePNG{Data: closeOnEOF{body}}, XRequestID: ...}
case "image/jpeg": return &oas.DownloadAttachmentOKImageJpegHeaders{...}
default: return nil, fmt.Errorf("unexpected content type %q: %w", att.ContentType, domain.ErrUnavailable)
}
```
`variant` в lab4 всегда `original`; ogen отклоняет остальные значения 400. Явно проверить
`params.Variant` и вернуть 404, если вариант не `original` (на случай расширения контракта в lab5).
Никаких redirect.
`closeOnEOF`:
```go
type closeOnEOF struct{ io.ReadCloser }
func (r closeOnEOF) Read(p []byte) (int, error) {
n, err := r.ReadCloser.Read(p)
if err != nil { _ = r.ReadCloser.Close() }
return n, err
}
```
Дополнительно: `context.AfterFunc(ctx, func(){ _ = body.Close() })` — если клиент оборвёт соединение
до EOF, body закроется по отмене контекста; иначе соединение S3 утечёт. `closeOnEOF` закрывает на
любой ошибке чтения.
### 10.3. Presign-эндпоинты (вне ogen)
Файл `internal/transport/rest/extensions.go`; монтаж в `NewRouter`:
```go
mux := http.NewServeMux()
mux.Handle("/api/v1/chats/{chat_id}/attachments/presign", ext.Presign())
mux.Handle("/api/v1/attachments/{attachment_id}/complete", ext.Complete())
mux.Handle("/", server)
return requestIDMiddleware(instanceIDMiddleware(bodyLimitMiddleware(default, upload, log, mux))), nil
```
Внутри каждого handler: проверить метод (иначе 405 в формате контракта), `Content-Type: application/json`,
лимит тела (уже применён), Bearer-токен через `session.Service.Resolve`, ошибки через `writeError`.
Для 401 выставлять `WWW-Authenticate: Bearer realm="messenger"`.
Логировать method/path/status/duration/user_id/attachment_id, без тел.
Контракт расширения (описать в `REPORT.md` и `examples/requests.http`):
```http
POST /api/v1/chats/{chat_id}/attachments/presign
Authorization: Bearer <token>
Content-Type: application/json
{"filename":"photo.png","content_type":"image/png","size_bytes":12345,"sha256":"<64 hex>"}
```
201:
```json
{"attachment_id":"...","method":"PUT","upload_url":"http://127.0.0.1:8333/...",
"expires_at":"2026-10-21T19:00:00Z","sha256":"<64 hex>","size_bytes":12345}
```
Клиенту не нужно присылать специальные заголовки: URL подписывает только host+key.
```http
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, presign_ttl)`; URL и `expires_at` вернуть.
Ограничения presigned PUT (зафиксировать в REPORT):
- S3 не умеет ограничивать размер при PUT: `size_bytes` проверяется на complete, объект-нарушитель
удаляется. Это соответствует формулировке трека («проверка размера/checksum при complete»);
временное хранение ограничено TTL + grace + приватным bucket.
- 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 → 200 (status/error_code), `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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)
он многоразовый до истечения, а 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 с другим размером → complete 400 и объект удалён;
- PUT с другим SHA → complete 400 и объект удалён;
- PUT в чужой ключ (без подписи) → 403;
- complete чужого attachment → 404;
- incomplete → 409, затем sweep;
- повторный complete → 200, без дублей.
---
## 13. Фаза 10. Evidence, REPORT, защита
### 13.1. `evidence/lab4/`
- `README.md` — как воспроизвести каждый файл, предусловия, версии, время.
- `baseline.txt` — smoke до реализации.
- `smoke.txt` — `make test` PASS.
- `negative.txt` — вывод `attachments_negative.py`.
- `failover.txt` — upload → stop → download, SHA.
- `restart.txt` — restart стенда, метаданные и оригинал на месте.
- `s3-outage.txt` — upload/download 503, остальные endpoint 200; восстановление.
- `private-bucket.txt` — anonymous GET 403, app-ключ 403 на чужой префикс, `docker compose ps` без лишних портов.
- `sweep.txt` — брошенный presign, удаление после grace, ready не тронут.
- `memory/` — CSV + summary (≥10 одновременных загрузок по 10 MiB; пик `anon`, `memory.current`
и `docker stats` с объяснением вклада page cache).
- `track1/` — `results.csv`, `summary.txt`, команды, p50/p95, трафик LB и API, RAM, а также
отдельный вывод: presigned 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; старые записи дадут 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`.
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 не ограничивает размер**; проверка на complete + sweep, зафиксировать в REPORT.
46. **Presigned URL многоразовый и перезаписывает объект**; complete проверяет фактические байты,
после complete повторный PUT создаёт staging-orphan → sweep.
47. **Не подписывать Content-Type в presign** — SDK может добавить его в SignedHeaders, клиент
получит `SignatureDoesNotMatch`; передавать только Bucket/Key.
48. **`memory.current` включает page cache** от temp-файлов; для RAM-эксперимента использовать `anon`.
49. **Sweeper: unlock advisory lock на том же соединении**, иначе lock утечёт в пул; при shutdown
сначала остановить sweeper, потом закрывать pool.
50. **Path-scoped `List` в SeaweedFS** может не поддержаться; проверить в s3init, иначе `List:bucket`.
51. **`http.ServeMux` method/wildcard patterns** требуют Go 1.22+; проект на 1.27 — ок, но не
регистрировать ext-роуты без проверки метода внутри (иначе 405 уйдёт в ogen).
52. **SeaweedFS HeadObject не возвращает checksum**; не строить complete на `ChecksumSHA256`.
53. **`GetAttachment` 200 и `DownloadAttachment` 200 — разные типы** (`AttachmentHeaders` vs
`DownloadAttachmentOKImage*Headers`); не перепутать в type switch.
54. **Readiness без S3** — осознанное решение; обосновать в REPORT (иначе S3-down уберёт все реплики).
55. **SeaweedFS CreateBucket идемпотентность**: повторный вызов → 409 `BucketAlreadyExists`
(проверено), а не `BucketAlreadyOwnedByYou`; сначала `HeadBucket`, 409 при гонке — успех.
56. **SeaweedFS HeadObject missing** → 404 `NotFound` (проверено); маппить в `ErrNotFound`, не 503.
57. **CopyObject metadata**: `MetadataDirective=REPLACE` + `ContentType`/`Metadata` сохраняет
sha256 и тип (проверено); без REPLACE метаданные источника могут не обновиться.
58. **ListObjectsV2 LastModified** возвращается (проверено) — sweeper может сравнивать возраст
с `now-grace`; не полагаться на размер/ETag.
---
## 15. Команды и Definition of Done
### 15.1. Локальный прогон
```sh
cp -n .env.example .env
make generate-api
make sqlc
go build ./...
make unit-test
make check validate PYTHON=.venv/bin/python
python3 scripts/check_s3_creds.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
for i in $(seq 1 90); do curl -fsS http://localhost:8080/health/ready && break; sleep 2; done
make test
python3 student-tests/attachments_negative.py --base-url http://localhost:8080
python3 student-tests/presign_flow.py --base-url http://localhost:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
### 15.2. Definition of Done
- [ ] `make unit-test` — зелёный, race.
- [ ] `make lint` — без новых замечаний.
- [ ] `make check validate` — PASS.
- [ ] `make test` (публичный smoke, LAB=4) — PASS.
- [ ] Все негативные сценарии возвращают 400/404/409/413/415, ни одного 500.
- [ ] `GET /attachments/{id}` для failed/pending — 200 с `status`/`error_code`; `/content` — 409.
- [ ] `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/error_code` | метаданные должны быть наблюдаемы; 409 только `/content` | §6.3, §8.2, §11.1, §15.2 |
| ogen: `InvalidContentTypeError` | `ogen/ogenerrors/handler.go` | маппится в 415 автоматически | подтверждено |
| ogen: `maxItems`/`uniqueItems` | `ogen/validate/array.go`, шаблон валидаторов | поддержаны; сервис дублирует | §11 |
| ogen: `anyOf` | `gen/schema_gen_sum.go` | sum-типы с одинаковыми именами не поддержаны; `ignore_not_implemented` выкидывает операции | §0.2 |
| Go `png.DecodeConfig` | `/usr/local/go/src/image/png/reader.go:993` | останавливается на IHDR, не читает IDAT/IEND | §7.1 |
| Go `jpeg.DecodeConfig` | `/usr/local/go/src/image/jpeg/reader.go:778` | разбирает только заголовок до SOF | §7.1 |
| OWASP upload | [File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) | не доверять Content-Type, генерировать имя, лимит размера, авторизация, хранить вне webroot | подтверждено |
| AWS presigned URLs | [using-presigned-url](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) | bearer-токен, TTL, многоразовый; PUT заменяет объект; SigV4 checksums | §12.2 |
| AWS presigned upload | [PresignedUrlUploadObject](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) | Content-Type может быть частью подписи; URL надо использовать без изменений | §7.2, §10.3 |
| Stripe idempotency | [Idempotent requests](https://docs.stripe.com/api/idempotent_requests) | сравнение параметров, ошибка при отличии, результат после начала выполнения | §8.3 (claim после валидации, 409) |
| Compose startup order | [docs.docker.com](https://docs.docker.com/compose/how-tos/startup-order/) | `service_completed_successfully` поддерживается; уже используется для `migrate` | §4.3 |
| PostgreSQL advisory locks | [functions-admin](https://www.postgresql.org/docs/current/functions-admin.html) | session-level lock живёт на соединении | §9.2 |
| SeaweedFS S3 | [Amazon S3 API wiki](https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API), [S3 Credentials](https://github.com/seaweedfs/seaweedfs/wiki/S3-Credentials) | presigned URL, Head/Copy/List, path-level identities | подтверждено spike |
| SeaweedFS checksum | spike 2026-10-21 | signed `x-amz-checksum-sha256` с неверным телом → 200; HeadObject checksum пуст | §7.2, §10.3 |
| SeaweedFS health | spike | `/healthz` → 200, старт ~20 с | §4.3 |
### 18.2. Осознанные компромиссы
1. **Readiness не включает S3.** S3 общий для всех реплик; его недоступность убрала бы весь стенд
из ротации. Вместо этого attachment-endpoint дают 503, остальные работают. Зафиксировать в REPORT.
2. **Presigned PUT не ограничивает размер на стороне S3.** Проверка на complete + sweep; это ровно
формулировка трека. Для production лучший вариант — presigned POST policy с `content-length-range`,
но SeaweedFS PostObject и его условия сложнее; в lab4 не нужен.
3. **Complete перечитывает объект из S3.** SeaweedFS не валидирует и не хранит checksum, поэтому
честная проверка SHA требует чтения. Трафик API при этом ≈ размеру файла; выигрыш presign —
в клиентском плече и отсутствии приёма тела API. Отражено в §12.4.
4. **Структурная проверка вместо decode+re-encode.** OWASP рекомендует re-encode, но для 40 MP это
дорого по памяти; lab4 не обрабатывает изображения, только хранит и отдаёт. lab5 добавит decode.
5. **Статический `infra/s3/s3.json`.** Синтетические креды дублируются в `.env.example`; дрейф
ловится `scripts/check_s3_creds.py`. Альтернатива — рендерить JSON из env в entrypoint, но это
ухудшает читаемость и аудит политик.
6. **Дополнительные эндпоинты вне ogen.** Контракт не меняется; presign-роуты сами проверяют
auth/JSON/метод и используют общий формат ошибок. Это осознанная цена за неизменный
`contracts/openapi.json`.
7. **SeaweedFS-контейнер — vendor image.** Требование «непривилегированный пользователь» из lab3
относится к контейнеру приложения (API image остаётся `USER 10001`); сторонний S3-образ
запускается как опубликован, его порты не публикуются, кроме loopback S3. Зафиксировать в REPORT.
8. **Attachment ID генерирует приложение (UUIDv7).** Позволяет сформировать S3-ключ до INSERT;
уникальность обеспечивается PK. `uuid.NewV7()` есть в google/uuid v1.6.0.
### 18.3. Остаточные риски и как их ловим
| Риск | Вероятность | Митигация |
|---|---|---|
| `sqlc` неудобно мапит `uuid[]` | средняя | проверить `make sqlc`; fallback — цикл ≤10 запросов |
| SeaweedFS не принимает path-scoped `List` | средняя | s3init проверяет; fallback `List:bucket`, REPORT |
| `CopyObject` с metadata REPLACE ведёт себя иначе | низкая | интеграционный тест presign; проверить Head после copy |
| ogen-генерация из производной спеки разойдётся с контрактом | низкая | `tools/specgen` падает на любом другом `anyOf`; `-check` в CI |
| presign-клиент не дочитывает поток и SHA неполный | низкая | `Validate` обязан читать до EOF; тест с хвостом |
| Sweep удалит объект идущей загрузки | низкая | grace + только объекты старше grace; тест |
| S3-креды в `.env` разойдутся с identities | средняя | `check_s3_creds.py` в `make check` |
| CI не дождётся SeaweedFS | средняя | healthcheck + start_period 60s + retry в s3init |
| `memory.current` искажён page cache | высокая | основная метрика `anon` + `docker stats` |
| 10 MiB тело в unit-тесте замедлит прогон | низкая | в тестах задавать маленькие лимиты через конфиг |
### 18.4. Ссылки
- Контракт: `contracts/openapi.json` (1.4.0), `contracts/README.md` §«Вложения».
- OWASP: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
- AWS presigned URLs: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
- AWS presigned upload: https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html
- AWS object integrity: https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html
- Stripe idempotency: https://docs.stripe.com/api/idempotent_requests
- Compose startup order: https://docs.docker.com/compose/how-tos/startup-order/
- PostgreSQL advisory locks: https://www.postgresql.org/docs/current/functions-admin.html
- SeaweedFS S3 API: https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API
- SeaweedFS credentials: https://github.com/seaweedfs/seaweedfs/wiki/S3-Credentials
- SeaweedFS compose: https://github.com/seaweedfs/seaweedfs/wiki/Docker-Compose-for-S3
- ogen sum types: `github.com/ogen-go/ogen@v1.24.0/gen/schema_gen_sum.go`
- Go PNG config: `image/png/reader.go` (`DecodeConfig`), JPEG: `image/jpeg/reader.go` (`DecodeConfig`)