1302 lines
83 KiB
Markdown
1302 lines
83 KiB
Markdown
# План реализации лабораторной 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`)
|