Prepare verified laboratory 4 implementation and evidence

This commit is contained in:
rey
2026-11-17 17:31:17 +03:00
parent ec540a1a72
commit 4fc1f40099
172 changed files with 15646 additions and 38 deletions
+60
View File
@@ -0,0 +1,60 @@
# Лабораторная 4. Приватные S3-вложения
Автор: Медведев Андрей Михайлович, БПИ2303. Целевая оценка: 5, трек 2 «Согласованность двух хранилищ». Оценка преподавателя не подменяется результатом тестов.
Сохранены обязательные возможности третьей лабы: две API-реплики, HAProxy, PostgreSQL, общие сессии, Valkey и атомарная идемпотентность сообщений. Добавлен RustFS 1.0.0-rc.1 с закреплённым digest, minio-go/v7, доменная модель Attachment, таблицы вложений и связей с сообщениями, ограниченный streaming upload и reconciler. Исходный skeleton: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4. Запуск описан в [RUN.md](RUN.md). Код и отчёт подготовлены с помощью Codex и прошли независимое ревью.
## Данные, доступ и согласованность
Оригинал хранится только в приватном S3, метаданные в PostgreSQL. Имя файла используется для отображения, ключ S3 генерируется из случайного серверного UUID и не переиспользуется. API работает с отдельной IAM-учётной записью: разрешены операции только своего bucket/prefix, создание постороннего bucket запрещено. Root credentials доступны bootstrap, но не API; административный порт наружу не публикуется.
При upload сначала проверяются сессия, членство и filename. Поток сохраняется во временный файл с лимитом 10 МиБ + 1 байт и SHA-256. PNG/JPEG проверяются по содержимому: сначала DecodeConfig и предел 40 млн пикселей, затем полноценный decoder обнаруживает повреждения. Подмена MIME, опасное имя, превышение bytes и pixel bomb не становятся 500. Временный файл удаляется после запроса; локальная файловая система API не является постоянным хранилищем.
До S3 PUT в БД создаётся устойчивое намерение uploading. После успешного PUT метаданные атомарно переводятся в ready, и только затем возвращается 201. Неопределённый ответ S3 или ошибка финализации БД сохраняют намерение для сверки. Сетевых вызовов S3 внутри SQL-транзакции нет.
Состояния uploading, missing и abandoned внутренние: публичная схема этой лабы возвращает только ready. Для missing API возвращает ограниченную ошибку 503, а не ложные готовые метаданные. Download проверяет членство, наличие оригинала и размер до отправки headers, передаёт bytes без redirect и проверяет полноту потока через CopyN. Другой участник чата получает исходные bytes, посторонний получает 404. Привязка файла другого чата запрещена.
Сообщение с пустым text допустимо при наличии вложения. Массив содержит не более десяти уникальных ID. Отсутствующий attachment_ids и [] имеют одинаковую семантику для идемпотентности. Обязательное string-поле text не может быть пропущено или заменено null. История читает ID вложений в SQL, без неограниченного fetch-all.
## Проверенные критерии
| Критерий | Результат | Доказательство |
| --- | --- | --- |
| Обязательный API | Публичный upload/message/download smoke прошёл | evidence/smoke.txt |
| Негативные сценарии | Чужой чат/файл, другой чат, MIME, повреждение, filename, 10 МиБ + 1, JSON null проверены | evidence/acceptance.txt |
| Приватность | Анонимный прямой S3 GET запрещён, посторонний bucket создать нельзя | acceptance и integration |
| Сохранность | Оригинал, метаданные и сессия пережили полный restart | evidence/persistence.txt |
| Другой API | Failover читает оригинал через оставшуюся реплику | evidence/failover-1.txt, evidence/failover-2.txt |
| Ограничение RAM | Десять одновременных попыток upload, контроль исходных bytes и cgroup memory.peak | evidence/concurrent-images/run-r1sasy/ |
| Экстремальное изображение | RGBA64 40 млн × 1, PNG и Adam7, повторы и три KDF-worker | evidence/image-memory-FaWPgn/ |
| Реальные частичные отказы | Ошибка SQL после PUT, потерянный ответ PUT, отсутствующий оригинал, orphan | evidence/reconciliation/run-KKAVrN/ |
| Dry-run и повтор | Dry-run ничего не меняет; повтор после apply ничего не меняет | evidence/reconciliation/run-KKAVrN/tests.txt |
| Защита чужих данных | Cleanup отвергает смешанное членство до удаления оригиналов | отдельный integration regression |
## Память и десять загрузок
Одна реплика одновременно декодирует только одно изображение; общая API-очередь ограничена. Контейнер API имеет hard limit 2 ГиБ и GOMEMLIMIT=1536MiB. Это покрывает worst-case штатного Go PNG decoder: полный 16-bit raster, строки фильтров и Adam7, плюс до трёх параллельных Argon2 по 32 МиБ. Проверялись исходники именно Go 1.27.2, а не только число пикселей.
В отдельном процессе прошли четыре проверки RGBA64 40 000 000 × 1: два обычных PNG и два Adam7, с тремя параллельными KDF-worker. Измеренный VmHWM составил 1 538 856 КиБ, примерно 1,47 ГиБ, ниже hard limit 2 ГиБ. Все входные bytes оставались меньше 10 МиБ; fixture специально сжимает одинаковые пиксели, поэтому проверка декодирования нужна независимо от размера файла.
Другой эксперимент одновременно начал десять PNG-upload по 3 148 214 байт. Восемь завершились 201, две попытки получили документированную 503 из-за ограниченной очереди. Все сохранённые оригиналы скачаны и побайтно проверены. Cgroup memory.peak двух реплик составил 78 458 880 и 78 077 952 байта. Это измерение данного входа; максимальный декодированный PNG проверялся отдельным экспериментом выше.
## Исследование согласованности
Reconciler обходит не более 100 metadata и 100 объектов за вызов, возвращает продолжение только для успешно обработанной страницы. При ошибке continuation очищается: оператор повторяет страницу с начала, а не пропускает неуспешный элемент. По умолчанию выполняется dry-run; apply задаётся явно.
Grace period по умолчанию 10 минут, минимально 60 секунд при upload deadline 20 секунд. Свежие и будущие timestamps не разрешают очистку. Список S3 и HEAD нормализуются к UTC-секундам: RustFS возвращает миллисекунды в inventory и целые секунды в HTTP Last-Modified. Перед удалением дополнительно сверяются ETag, размер, возраст и отсутствие текущих metadata. Любой учтённый объект, включая используемое вложение, защищён от orphan cleanup.
Эксперимент выполнен в отдельном случайном Compose-проекте с собственными volumes и изначально пустыми DB/bucket. Настоящий PostgreSQL trigger вызвал отказ финализации после реального PUT. Также потерян ответ уже выполненного PUT, удалён оригинал используемого вложения, оставлено прерванное намерение и создан старый orphan. Новый объект создан непосредственно перед сверкой, чтобы проверить grace.
Dry-run увидел 5 metadata, 5 объектов, один orphan, два missing и две восстановимые загрузки; изменений не сделал. Apply удалил один старый orphan и изменил четыре metadata, восстановив две загрузки. Свежий объект и используемый оригинал сохранились. Повтор дал ноль удалений и изменений. После возвращения корректного оригинала missing-вложение снова стало ready; metadata и сообщения при этом не удалялись.
Для apply измерено 12 реальных S3 HTTP-запросов и 2227 прочитанных bytes на данном наборе. Это стоимость небольшого сценария и конечный размер одного batch; обход большого bucket потребует последовательного продолжения страниц. Исходные счётчики сохранены. Уборка integration-проекта завершилась до публикации PASS.
## Генерация и ограничения
Нормативный OpenAPI и публичные тесты сохранены. Для oapi-codegen используется его штатный Overlay: два бинарных MIME не должны порождать дублирующиеся Body-поля, а anyOf здесь выражает проверку содержимого, а не разные Go-типы. HTTP-адаптер принимает и проверяет PNG и JPEG; обязательные поля и правило text-or-attachment проверяются runtime и тестами.
Один Docker-host, PostgreSQL, HAProxy и S3 остаются единичными компонентами. Шифрование транспорта относится к следующей лабораторной; этот стенд привязан к localhost и синтетическим данным. Прерванный upload может оставить устойчивое намерение до сверки. Повторный POST загрузки может создать другое вложение; контракт не обещает идемпотентность upload. Сверка orphan/missing не заменяет полный scrub checksum всех ready-объектов.
На защите показать 201 только после устойчивой записи, download через другую реплику, чужой 404 и закрытый прямой S3 GET. Затем объяснить невозможность общей SQL/S3-транзакции, показать dry-run/apply/repeat и границы RAM, не называя один host отказоустойчивым кластером.
+89
View File
@@ -0,0 +1,89 @@
# Запуск лабораторной 4
> Историческая инструкция Compose/HAProxy. Основной путь теперь описан в ../../RUN.md. Для старых action helpers явно задайте VP_RUNTIME=compose; прежние runners сохранены как student-tests/reconciliation-compose.ts и concurrent-images-compose.ts. Числа этого варианта не являются измерениями k3s/Pingap.
Автор: Медведев Андрей Михайлович, БПИ2303. Исходное задание и контракт сохранены в README.md и contracts/. Реализация находится в backend/, дополнительные проверки в student-tests/.
Нужны Docker Engine с Compose, Bun 1.4 и Python 3.9+. Для Go-тестов на хосте нужен Go 1.27.2 или новее. Проверенный стенд: Linux x86_64, Docker 29.9.2, Compose 5.6.1, Bun 1.4.4; образ компилируется Go 1.27.2. Образы PostgreSQL 18.6 и Valkey 9 закреплены digest в compose.yaml.
Команды выполняются из этого каталога. scripts/compose.sh закрепляет manifest и имя vp-lab4-medvedev, чтобы переменные другого проекта не перенаправили операции.
```sh
bun --no-env-file scripts/bootstrap.ts
./scripts/compose.sh up -d --build
BASE_URL=http://127.0.0.1:28204 bun --no-env-file student-tests/wait.ts
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
make check
make validate PYTHON=.venv/bin/python
make test BASE_URL=http://127.0.0.1:28204
BASE_URL=http://127.0.0.1:28204 bun --no-env-file student-tests/acceptance.ts
make test-persistence BASE_URL=http://127.0.0.1:28204 ACTION_SCRIPT=scripts/restart.sh
cd backend
go test -race ./...
go tool golangci-lint run
go generate ./...
```
Bootstrap создаёт отдельные случайные учебные credentials в .local/ и не печатает их. Каталог исключён из git и Docker context. Существующие файлы не перезаписываются. Миграции запускает отдельный service migrate; API не выполняет их конкурентно.
HTTP доступен только через localhost. Все данные тестов синтетические; публичные тесты сохраняют свой набор данных для демонстрации, дополнительные acceptance-тесты удаляют только свой случайный набор. Пароли и сессии не выводятся в отчёты.
Обычная остановка сохраняет volumes:
```sh
./scripts/compose.sh stop
```
Повторный запуск с сохранением данных:
```sh
./scripts/compose.sh up -d
```
Только для намеренного полного сброса собственных учебных данных:
```sh
./scripts/compose.sh down --volumes
```
Для проверки отказа запустите публичный сценарий. Он передаёт реальный TARGET_INSTANCE_ID hook-скрипту; после проверки верните обе реплики и дождитесь готовности.
```sh
make test-failover BASE_URL=http://127.0.0.1:28204 ACTION_SCRIPT=scripts/stop-one.sh
./scripts/compose.sh up -d
BASE_URL=http://127.0.0.1:28204 bun --no-env-file student-tests/wait.ts
```
Чтобы проверить вторую реплику, повторите сценарий после восстановления; фактический остановленный контейнер записывается в evidence/stop-one-after.txt.
Отказ S3 с восстановлением и проверкой подтверждённого оригинала:
```sh
FAIL_S3=1 BASE_URL=http://127.0.0.1:28204 bun --no-env-file student-tests/acceptance.ts
```
Исследование трека 2 запускайте через изолирующий runner. Он создаёт отдельный случайный Compose-проект с пустыми DB/bucket, воспроизводит настоящие частичные отказы и dry-run/apply/repeat, затем удаляет только свой проект. Результаты появляются в новом evidence/reconciliation/run-*.
```sh
bun --no-env-file student-tests/reconciliation.ts
```
Не запускайте integration service напрямую на демонстрационной БД: тест сверяет весь изолированный набор. Для обычной сверки доступен CLI с ограничением 100 metadata и 100 объектов на вызов. Первая команда ничего не меняет; вторая явно применяет безопасные исправления.
```sh
./scripts/compose.sh run --rm --no-deps api -reconcile
./scripts/compose.sh run --rm --no-deps api -reconcile -apply
```
CLI возвращает поля продолжения metadata/object. Для следующей страницы передайте их через -after и -object-after; при ошибке повторите страницу с прежними курсорами. Default grace равен 10 минутам, минимальный -grace равен 60s.
Проверки памяти выполняются на omarchy без игры. Сначала соберите обычный образ и дождитесь готовности. Генератор создаёт только синтетический PNG в .local/; скрипт одновременно начинает десять upload и проверяет исходные bytes всех успешных загрузок. Отдельный процесс декодирует экстремальные PNG вместе с KDF-worker.
```sh
go run ./student-tests/image-fixtures/main.go
BASE_URL=http://127.0.0.1:28204 bun --no-env-file student-tests/concurrent-images.ts
./student-tests/image-memory.sh
```
Команда генератора выполняется из корня лабы. Поля продолжения CLI называются NextMetadata и NextObject. Подтверждённые результаты и ограничения перечислены в REPORT.md. Автоматические проверки не выставляют оценку преподавателя.
+15
View File
@@ -0,0 +1,15 @@
# Implementation plan and boundaries
Archived: this inherited lab2 plan is retained as historical context only. The completed lab4 implementation, results and limitations are documented in ../../REPORT.md; startup instructions are in ../../RUN.md.
This repository carries our lab1 domain, pagination, HTTP/error handling, bounded queue and shutdown code into the original lab2 skeleton. The lab1 memory adapter and its obsolete HTTP identity tests are not carried forward.
PostgreSQL is authoritative for users, passwords, sessions, chats, membership and messages. Valkey caches immutable public profiles for 60 seconds; no chat/message/session cache is used. Authentication always reads the session from PostgreSQL, and cache failure falls back to PostgreSQL within an 80 ms budget. Logout deletes the persisted token hash. Cache contents contain no password or bearer token.
Transactions: chat allocation + chat row + membership; sender quota + message; session owner lock + expiry cleanup + session insertion. PostgreSQL constraints enforce username uniqueness and foreign keys. Maximums: 1000 created chats and 1,000,000 messages per owner; 100 unexpired sessions. No user data is silently deleted. The history index covers `(chat_id,created_at,id)` and queries fetch only `limit+1` rows. Keyset traversal is not a snapshot; writes whose wall-clock timestamps fall before a consumed cursor can be missed during concurrent traversal.
Argon2id uses a random 16-byte salt, 32 MiB, two iterations, one lane, 32-byte result. Tokens use 32 random bytes; PostgreSQL stores only SHA-256 of the token. SHA-256 is appropriate for high-entropy tokens, not passwords. The API gate bounds concurrent KDF calls to four. PostgreSQL pool: eight connections, statement timeout 2 s, lock timeout 1 s, connect timeout 1 s; request context 5 s.
Readiness checks PostgreSQL. Valkey is optional to safe operation; its absence is observable through cache hit statistics and failure tests, not an anonymous-authentication fallback. HTTP is bound to localhost and uses only generated synthetic data.
Research: compare history queries over at least 100,000 skewed messages; restore a backup into a new database, compare row counts and selected message bytes. See `REPORT.md` for actual results; planned experiments are not evidence.