Files
mtusi2026lab4/REPORT.md
T

149 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 4
- Автор, группа: Черников Дмитрий, БВТ2304.
- Целевая оценка: 4; исследовательский трек 5 не заявлен.
- Commit/PR: заполняется после публикации.
- Основа — собственная лабораторная 3. При разработке lab4 использовался Codex (OpenAI).
- Библиотеки: psycopg 3.3.6, psycopg-pool 3.3.3, Valkey client 6.1.1, argon2-cffi 25.1.0, boto3 1.43.123, Pillow 13.0.0. Транзитивные зависимости и хеши закреплены в `requirements.txt`.
## Запуск из чистого clone
Требуются Docker с Compose v2 и Python 3.9+ для тестов. Команды выполняются из корня clone `mtusi2026lab4`. UI не требуется.
| Компонент | Образ | Хранилище | Доступ |
| --- | --- | --- | --- |
| API × 2 | Python 3.14.7, собственный `mtusi-messenger:lab4` | постоянных файлов нет | только HAProxy |
| HAProxy | 3.4.5-trixie | нет | 127.0.0.1:8080; статистика 127.0.0.1:8404 |
| PostgreSQL | 18.6-trixie | `pgdata` | только Compose |
| Valkey | 9.0.6-trixie | `valkeydata`, AOF | только Compose |
| SeaweedFS | 3.85 | `s3data`: master, volume и индекс filer | только Compose; S3 :8333 |
| migrate, bucket | образ приложения | одноразовые операции | портов нет |
| cleanup | образ приложения, профиль tools | запуск оператором | портов нет |
Образы закреплены версиями и digest в Dockerfile/Compose, включая SeaweedFS 3.85 (`sha256:493129…`). Все зависимости поднимаются из этого репозитория.
```sh
python scripts/init_secrets.py
cp .env.example .env # PowerShell: Copy-Item .env.example .env
docker compose config --quiet
docker compose up -d --build --wait
docker compose ps -a
python -X utf8 scripts/check_contract.py
python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080
python -X utf8 -m unittest discover -s student-tests -v
python -X utf8 scripts/lab4_checks.py
```
В Linux можно использовать `python3`. В Windows `-X utf8` нужен для чтения контракта публичными скриптами. Адрес 127.0.0.1 исключает задержки при попытках IPv6. Краткий сценарий защиты — [DEMO.md](DEMO.md).
`init_secrets.py` создаёт случайные пароли только при отсутствии файлов; значения не печатаются. `secrets/` и `.env` исключены из Git и Docker build context. При сохранённом PostgreSQL volume нужно сохранять исходные секреты.
`migrate` применяет SQL-миграции до запуска API. `bucket` ожидает S3 и идемпотентно создаёт приватный bucket административным ключом. Повторный `docker compose run --rm bucket` безопасен.
Остановка: `docker compose stop` либо `docker compose down` сохраняют volumes. **`docker compose down -v` намеренно удаляет все учебные данные lab4.**
## Архитектура и решения
```text
Клиент -> HAProxy -> API x2 -> PostgreSQL: пользователи, чаты, сообщения, attachment metadata
-> Valkey: долговечные сессии с TTL
-> приватный SeaweedFS S3: оригиналы изображений
```
Из lab3 перенесены аутентификация, Argon2id, общие сессии, keyset pagination, транзакционная идемпотентность сообщений, readiness и плавная остановка API. Публичный контракт и публичные тесты сохранены.
Миграция `0004_attachments.sql` добавляет метаданные, связь сообщения с файлами и `attachment_ids`. Внешние ключи защищают принадлежность вложения чату; API проверяет список до INSERT. `attachment_ids=[]` и отсутствие поля имеют одинаковый fingerprint. Порядок IDs сохраняется; перестановка списка считается другим телом. Подтверждённые сообщения читаются любой репликой из PostgreSQL. Строка чата блокируется на запись, время следующего сообщения строго больше предыдущего.
Оригинал находится в S3. Ключ `originals/<случайный UUID>` создаёт сервер; filename используется лишь в метаданных. Метаданные и content доступны после проверки Bearer-сессии и членства в чате; постороннему возвращается 404. API не выдаёт object key, внутренний URL или redirect в S3.
Upload требует один Content-Length, Transfer-Encoding не поддерживается. Размер проверяется до чтения; тело принимается блоками до 64 KiB во временный `/tmp`. На реплику допускается один decoder, ожидание слота ограничено 8 с. Чтение ограничено общим сроком 10 с; процесс Pillow — 8 с. До распаковки проверяется предел 40 миллионов пикселей. Выполняются `verify()` и полное `load()`, тип из содержимого сверяется с MIME. Отдельный процесс освобождает память декодера после завершения.
У API лимит 512 MiB, `/tmp` — tmpfs 32 MiB. Временный оригинал удаляется после запроса; устойчивый экземпляр хранится в S3. Download читает S3 блоками по 64 KiB.
У boto3 connect timeout 1 с, read timeout 3 с, одна попытка. Пользовательские ошибки дают 400/413/415, отказ хранилища — 503. Readiness зависит от PostgreSQL, Valkey и S3: все нужны обязательному синхронному пути.
## Приватность и конфигурация
В `secrets/s3_config` две identity, анонимной identity нет. Bootstrap/cleanup имеют административный ключ; API получает только Read, Write, List для `messenger-attachments`. API не может создать bucket или читать другой bucket. В SeaweedFS 3.85 Write допускает также удаление объектов; отдельное ограничение Delete не заявляется. Приложение не предоставляет endpoint удаления.
S3 и административные порты не опубликованы на хосте. Внутренняя сеть Compose считается доверенной учебной сетью. Прямая проверка анонимного GET выполняется из контейнера API, независимо от недоступности S3 с хоста.
`S3_ENDPOINT=http://s3:8333`, `S3_REGION=us-east-1`, `S3_BUCKET=messenger-attachments` соответствуют Compose. `.env` настраивает TTL, число реплик и лимиты изображения; параметры хранилищ задаёт Compose. При изменении bucket нужно согласованно изменить scope identity в `init_secrets.py`. `SESSION_STORE=valkey` в примере описательный: реализация использует Valkey напрямую.
## Согласованность S3 и БД
Порядок: приём и проверка -> PostgreSQL transaction/advisory lock по object key -> S3 PUT -> INSERT -> COMMIT -> HTTP 201 ready. Сообщение с вложением создаётся отдельной транзакцией. Доступное вложение можно использовать в нескольких сообщениях того же чата.
Если PUT не удался, метаданные не фиксируются. Если PUT прошёл, а INSERT/COMMIT нет, 201 не возвращается; возможен orphan в S3. При неопределённом COMMIT немедленно удалять объект опасно: транзакция могла зафиксироваться.
Сборщик перечисляет `originals/`, игнорирует объекты моложе часа, для каждого старого объекта берёт ту же advisory lock, повторно проверяет отсутствие метаданных и лишь затем удаляет. Upload держит lock от PUT до COMMIT; сборщик не удалит объект на этой границе. Повторные запуски безопасны. Отказ БД/S3 прерывает обход. Любые метаданные защищают файл независимо от наличия сообщения.
```sh
docker compose --profile tools run --rm cleanup # dry-run
docker compose --profile tools run --rm cleanup --apply # только старые orphan
```
**Действие оператора:** запускать `cleanup --apply` раз в час планировщиком ОС и сохранять summary. Без этого orphan автоматически не исчезают. Grace нельзя уменьшить ниже 3600 с. Обнаружение missing объектов и полноценный reconciler уровня 5 не заявлены.
## Доказательства критериев
Результаты в этой таблице не заменяются предположениями. Логи сохраняются в `evidence/`.
| Критерий | Команда | Результат |
| --- | --- | --- |
| Контракт и синтаксис | `python -X utf8 scripts/check_contract.py`; `python -X utf8 -m compileall -q src student-tests scripts` | PASS |
| Compose | `docker compose config --quiet` | PASS |
| Smoke, checksum, ACL | `python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080` | PASS, `evidence/smoke.txt` |
| Предыдущие возможности, негативные файлы | `python -X utf8 -m unittest discover -s student-tests -v` | PASS: 95 тестов, 32,356 с; `evidence/tests.txt` |
| Bootstrap, порты, private bucket | `python -X utf8 scripts/lab4_checks.py --only stack private` | PASS: повтор bootstrap; анонимный GET 403, создание bucket ключом API 403; `evidence/lab4-checks.txt` |
| Остановка загрузившей реплики | `python -X utf8 scripts/lab4_checks.py --only failover` | PASS: другой X-Instance-Id, байты совпали; `evidence/lab4-checks.txt` |
| Restart всех хранилищ | `python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080` | PASS: прежние токен, сообщение, metadata и bytes сохранены; `evidence/persistence.txt` |
| Отказ S3 | `python -X utf8 scripts/lab4_checks.py --only outage` | PASS: 503, после восстановления тот же токен и оригинал; `evidence/lab4-checks.txt` |
| Прерывание upload, отказ INSERT после PUT | `python -X utf8 scripts/lab4_checks.py --only compensation` | PASS: метаданные не зафиксированы, свежие объекты не удалены; `evidence/lab4-checks.txt` |
| 10 одновременных загрузок и RAM | `python -X utf8 scripts/lab4_checks.py --only memory` | PASS: 10/10, 2 реплики, checksum всех файлов совпал; `evidence/lab4-checks.txt` |
## Эксперименты и отказы
Гипотеза: потоковый приём и один decoder на реплику ограничивают RAM при десяти параллельных запросах. Десять потоков стартуют через barrier и загружают реальный PNG 1024×1024 с несжимаемыми RGB-пикселями (~3 MiB). Затем каждый оригинал скачивается и сверяется по SHA-256.
Скрипт выводит размер, все задержки, successful RPS, число реплик, memory.current до нагрузки и kernel memory.peak после. Пик включает decoder и tmpfs, относится к жизни контейнера и может учитывать предыдущие запросы; для отдельного эксперимента сначала перезапустите API.
Фактический прогон 04.11.2026: Windows, Docker Desktop engine 29.8.1, Linux containers, Docker VM 22 CPU / 16 464 138 240 байт RAM. У API по 0,5 CPU и 512 MiB. Перед экспериментом выполнены функциональные проверки; отдельного прогрева и повторов нет. Размер PNG — 3 147 780 байт, 1024×1024.
| Метрика | Результат |
| --- | --- |
| Одновременные запросы / успешные / ошибки | 10 / 10 / 0 |
| Длительность / successful RPS | 6,880 с / 1,453 |
| p50 / p95 / p99 (nearest rank, n=10) | 3,682 / 6,876 / 6,876 с |
| Реплика 1: RAM до / lifetime peak | 289 738 752 / 330 678 272 байт (315,4 MiB peak) |
| Реплика 2: RAM до / lifetime peak | 91 824 128 / 130 723 840 байт (124,7 MiB peak) |
| Проверка оригиналов | все 10 скачаны, SHA-256 совпал |
Высокая исходная память первой реплики включает предыдущие тесты; этот прогон доказывает успешную обработку десяти загрузок в заданном лимите, но не точную добавочную стоимость одного upload. Один короткий прогон не является production benchmark и не доказывает throughput для 40M pixels. Фактическая загрузка CPU не измерялась, заданы только лимиты.
| Воздействие | Наблюдение |
| --- | --- |
| Остановка реплики, ответившей на upload | другая реплика отдала исходные bytes; SHA-256 `99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75` |
| Остановка S3 | ожидаемый 503; команда stop и проверка суммарно 4,699 с; после start исходный токен и файл сохранены |
| Ошибка INSERT после PUT, временный DB trigger | 500 вместо 201; число метаданных не выросло; orphan моложе часа оставлен grace period |
| Закрытие соединения до конца upload | метаданные не созданы |
| Restart API, PostgreSQL, Valkey, S3 и HAProxy | публичный persistence PASS: подтверждённые данные, ещё действующая сессия и оригинал сохранены |
Dry-run сборщика просмотрел 19 объектов и оставил все 19 как свежие; удалено 0. Реальное удаление объекта старше часа в этом коротком прогоне не проверялось. Лог — `evidence/lab4-checks.txt`. Проверка синтетического INSERT временно создаёт trigger только для `lab4-force-rollback.png` и удаляет его в `finally`.
## Ограничения и следующие шаги
- Один хост, по одному PostgreSQL, Valkey, S3, HAProxy: отказ узла/диска не решён.
- HTTP используется для локальных синтетических данных. Для удалённого доступа нужен TLS.
- При перегрузке upload возможен 503. Upload не идемпотентен; повтор после неопределённого ответа может создать ещё один файл.
- Плавная остановка lab3 сохранена, но долгий upload может не уложиться в 10 с остановки контейнера. До 201 сохранение не гарантируется; orphan обрабатывает сборщик.
- Неиспользованные, но учтённые вложения не удаляются. Полного lifecycle и исследования уровня 5 нет.
## Источники
- Задание, контракт и публичные тесты этого репозитория.
- [Pillow Image: verify, load, MAX_IMAGE_PIXELS](https://pillow.readthedocs.io/en/stable/reference/Image.html).
- [Boto3 put_object](https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/put_object.html).
- [SeaweedFS S3 credentials](https://github.com/seaweedfs/seaweedfs/wiki/S3-Credentials).
- [Compose services](https://docs.docker.com/reference/compose-file/services/).