docs: Record level-four reconciliation evidence
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
# Отчёт — лабораторная 4
|
||||
|
||||
- Автор, группа: Самохвалов Андрей Ремович, БПИ-2302.
|
||||
- Целевая оценка: 5, трек 2 «Согласованность двух хранилищ». Перенос lab3, приватное S3, синхронный upload, доступ к вложениям и связь с сообщениями проверены; reconciler и эксперимент трека выполняются далее.
|
||||
- Целевая оценка: 5, трек 2 «Согласованность двух хранилищ». Уровни 3 и 4 проверены; повторяемый эксперимент трека 5 выполняется далее.
|
||||
- Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации.
|
||||
- Источники: `README.md`, `COURSE.md`, `contracts/README.md`, `contracts/openapi.json`, публичные тесты, [MinIO release](https://github.com/minio/minio/releases/tag/RELEASE.2025-10-15T17-29-55Z), [образ](https://hub.docker.com/r/alpine/minio/tags), документация MinIO для IAM. Python/FastAPI, PostgreSQL, MinIO Python SDK; проект подготовлен с помощью ИИ Codex с локальной проверкой ниже.
|
||||
|
||||
@@ -35,13 +35,16 @@ make test
|
||||
| `s3` | MinIO security release, 0,5 CPU/384 MiB | `/minio/health/ready`, `s3_data` | только root credentials, наружный порт и консоль не опубликованы |
|
||||
| `s3-bootstrap` | одноразовый MinIO Client | завершение 0 | root и создаваемые ограниченные credentials |
|
||||
| `s3-volume-init` | одноразовая настройка владельца volume | завершение 0 | секретов нет |
|
||||
| `reconcile` | одноразовый Python, профиль `maintenance` | завершение 0, без порта и volume | DB URL и отдельные S3 maintenance credentials |
|
||||
|
||||
`infra/minio-api-policy.json` разрешает только операции над объектами одного bucket и чтение его location; создание bucket, изменение IAM и административные операции не разрешены. Отдельная maintenance policy добавляет list для будущей сверки. Bucket не имеет анонимного чтения. Приватность bucket не заменяет проверку членства в чате на API: upload проверяет его до чтения тела, metadata/content — до доступа к S3. Публичный ответ не содержит object key, endpoint и credentials.
|
||||
|
||||
Upload читает raw body в `SpooledTemporaryFile` с порогом RAM 1 MiB и останавливается после 10 MiB; проверяет формат и MIME через Pillow, до декодирования отклоняет свыше 40 млн пикселей, затем полностью проверяет PNG/JPEG. Имя файла применяется только для отображения, object key — случайный UUID в `originals/`. S3 PUT предшествует INSERT/COMMIT в PostgreSQL; `201 ready` возвращается лишь после обоих успехов. При достоверной ошибке до COMMIT объект удаляется. Если подтверждение COMMIT потеряно, удалять небезопасно: объект остаётся кандидатом для сверки после grace period. Если и компенсационное DELETE отказало, key записывается во внутренний лог; U5 добавит повторяемый reconciler. Клиенту при ошибке зависимости приходит `503`, а прозрачный retry POST не выполняется. Для S3 заданы connect/read timeouts 2/10 с без внутренних повторов; `/health/ready` проверяет БД и доступ к приватному S3 через разрешённый HEAD отсутствующего probe key.
|
||||
Upload читает raw body в `SpooledTemporaryFile` с порогом RAM 1 MiB и останавливается после 10 MiB; проверяет формат и MIME через Pillow, до декодирования отклоняет свыше 40 млн пикселей, затем полностью проверяет PNG/JPEG. Имя файла применяется только для отображения, object key — случайный UUID в `originals/`. S3 PUT предшествует INSERT/COMMIT в PostgreSQL; `201 ready` возвращается лишь после обоих успехов. При достоверной ошибке до COMMIT объект удаляется. Если подтверждение COMMIT потеряно, удалять небезопасно: объект остаётся кандидатом для сверки после grace period. Если и компенсационное DELETE отказало, key записывается во внутренний лог; reconciler позднее удаляет только старый объект без metadata. Клиенту при ошибке зависимости приходит `503`, а прозрачный retry POST не выполняется. Для S3 заданы connect/read timeouts 2/10 с без внутренних повторов; `/health/ready` проверяет БД и доступ к приватному S3 через разрешённый HEAD отсутствующего probe key.
|
||||
|
||||
POST сообщения принимает до 10 уникальных ID из этого чата, включая пустой текст с вложением. Проверка вложений, запись сообщения, связей и результата идемпотентности выполняются в одной транзакции; порядок ID сохраняется. Повтор ключа с тем же содержимым возвращает прежний Message. `GET` metadata и content сначала проверяют действующую сессию и членство в чате; неизвестный и чужой ID одинаково дают 404. Исходник отдаётся потоково через API, отсутствующий вариант — 404, недоступный S3-объект — 503.
|
||||
|
||||
`docker compose --profile maintenance run --rm reconcile` выполняет **dry-run по умолчанию**. `--apply` удаляет только объекты `originals/<uuid>` без metadata старше 3600 с: перед DELETE повторно проверяются запись БД, размер, ETag, время изменения и возраст. Неизвестные ключи не удаляются. Для metadata без S3-объекта выдаётся ручной инцидент; metadata сохраняется. Восстановление требует `--restore-id` и read-only fixture с точным размером и SHA-256. Файл проверяется до любых удалений при `--apply`; несоответствие останавливает run. Повторный apply не меняет уже восстановленный объект. У API нет `ListBucket`, у отдельной maintenance-учётной записи он есть; обе не имеют прав создавать bucket или менять IAM.
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство |
|
||||
@@ -51,15 +54,19 @@ POST сообщения принимает до 10 уникальных ID из
|
||||
| Миграция и транзакции | `docker compose exec -T api python - < student-tests/test_database.py`; `... test_auth.py` | Миграции 1–5 применены повторяемо, 2 DB и 3 auth теста PASS | `evidence/storage-bootstrap-2026-10-02.txt` |
|
||||
| Raw PNG/JPEG upload и ограничения | `BASE_URL=http://localhost:8084 python3 -m unittest discover -s student-tests -p 'test_attachment_upload.py' -v` | 4 набора PASS: PNG/JPEG `201 ready`, корректные hash/size/type; 10 MiB+1 и >40 млн px — 413; повреждение/MIME spoof — 415; опасное имя — 400, чужой чат — 404 | `student-tests/test_attachment_upload.py`, синтетический JPEG fixture |
|
||||
| Отказ S3 | `docker compose stop s3`; `docker compose exec -T api python - < student-tests/test_s3_outage.py`; `docker compose start s3` | При реально остановленном S3 readiness=503, upload=503, число metadata строк не изменилось; S3 восстановлен и healthy | `student-tests/test_s3_outage.py` |
|
||||
| Промежуток S3/БД и обрыв потока | `docker compose exec -T api python - < student-tests/test_upload_failure.py` | PUT failure не вызывает SQL; ошибка БД до INSERT вызывает компенсацию DELETE; оборванный поток не начинает PUT. Добавленный случай неоднозначного COMMIT требует отдельного контрольного прогона | `student-tests/test_upload_failure.py` |
|
||||
| Промежуток S3/БД и обрыв потока | `docker compose exec -T api python - < student-tests/test_upload_failure.py` | 4/4 PASS: PUT failure не вызывает SQL; ошибка до INSERT компенсируется DELETE; оборванный поток не начинает PUT; неоднозначный COMMIT оставляет объект для сверки | `evidence/reconcile-u5-2026-10-02.txt` |
|
||||
| Ограничение RAM | `BASE_URL=http://localhost:8084 python3 scripts/measure-upload-memory.py` | 10/10 одновременных upload одного PNG 9 441 653 байт, 10 разных ready ID и верный SHA-256, 6,145 с; sampled peak API-1/2 114,7/115,5 MiB при лимите 256 MiB | `evidence/upload-memory-2026-10-02.csv` |
|
||||
| Сообщения, ACL и скачивание | `python3 -m unittest discover -s student-tests -p test_attachment_access.py -v`; `make test BASE_URL=http://127.0.0.1:8084` | 3 собственных теста OK; публичный сценарий PASS; link/replay и bytes на обеих репликах, чужой объект 404 | `evidence/attachment-access-2026-10-02.txt` |
|
||||
| Сохранность S3 и отказ API | `make test-persistence ... ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ... ACTION_SCRIPT=scripts/stop-one.sh`; `python3 student-tests/test_attachment_failover.py` | Токен, Message, metadata и bytes пережили restart API/DB/S3; публичный failover восстановил запись за 2,826 и 3,020 с; адресный тест остановил каждую загрузившую реплику и скачал те же bytes через другую | `evidence/attachment-access-2026-10-02.txt` |
|
||||
| Сверка orphan/missing | `docker compose --profile maintenance run --rm reconcile`; `student-tests/test_reconcile.py` в maintenance-контейнере | 2/2 PASS: old orphan после PG rollback удалён по истечении grace; fresh и привязанный сохранены; missing дал 503, неверный fixture не изменил данные, верный восстановил bytes/200; повтор идемпотентен | `evidence/reconcile-u5-2026-10-02.txt`, три JSON результата |
|
||||
| Права S3 | `student-tests/test_storage_permissions.py` в API и maintenance-контейнерах | 1/1 PASS для каждой роли; API не может list, обе не могут создавать bucket, анонимный GET 403, консоль не опубликована | `evidence/reconcile-u5-2026-10-02.txt` |
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
Граница PUT/COMMIT проверена fault-инъекциями; полный reconciler и проверка восстановления при неизвестном результате COMMIT выполняются в U5/U6. Замер RAM проводился на локальном Colima/arm64, 2 CPU и 2 GiB, API ×2 с 0,5 CPU/256 MiB на экземпляр, 10 потоков с барьером старта. CSV содержит baseline и два Docker stats снимка во время 6,145 с серии: peak означает максимум **наблюдённых** снимков, а не точный аппаратный high-water mark. Все 10 ответов 201 имели уникальные ID и совпадающий SHA-256. Создание body по `os.urandom` оставляет воспроизводимыми размер/разрешение/алгоритм, но не конкретные байты и hash между прогонами.
|
||||
Граница PUT/COMMIT проверена fault-инъекциями; U5 сверяет реальные расхождения, а U6 отдельно измерит повторяемость и стоимость. Для теста удаления grace уменьшался до 5 секунд только на синтетическом наборе; обычный запуск использует 3600 секунд. Список объектов MinIO содержит миллисекунды, а HEAD округляет время до секунд: перед удалением сверяются секунды, ETag и размер, затем возраст и ссылка в БД. После канонического dry-run 28 metadata, 29 objects, 1 свежий orphan был защищён и ни один объект не удалён.
|
||||
|
||||
Замер RAM проводился на локальном Colima/arm64, 2 CPU и 2 GiB, API ×2 с 0,5 CPU/256 MiB на экземпляр, 10 потоков с барьером старта. CSV содержит baseline и два Docker stats снимка во время 6,145 с серии: peak означает максимум **наблюдённых** снимков, а не точный аппаратный high-water mark. Все 10 ответов 201 имели уникальные ID и совпадающий SHA-256. Создание body по `os.urandom` оставляет воспроизводимыми размер/разрешение/алгоритм, но не конкретные байты и hash между прогонами.
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
Публичный `make test` проходит; он не доказывает все отказные сценарии. Проверки уровня 4 и трека 5 не заявляются завершёнными до повторяемой сверки. Один MinIO/PostgreSQL/LB и один Docker-host остаются одиночными точками отказа. Локальный HTTP допустим только для изолированного стенда с синтетическими данными; удалённой демонстрации нужен TLS.
|
||||
Публичный `make test` проходит; он не доказывает все отказные сценарии. Уровень 4 подтверждён отдельными проверками. Трек 5 ещё не заявляется завершённым до повторяемой серии и измерения стоимости. Missing без проверенного источника остаётся ручным инцидентом, автоматической реконструкции чужих байтов нет. Один MinIO/PostgreSQL/LB и один Docker-host остаются одиночными точками отказа. Локальный HTTP допустим только для изолированного стенда с синтетическими данными; удалённой демонстрации нужен TLS.
|
||||
|
||||
Reference in New Issue
Block a user