From 790911092460f332d1b6b7de546dc96a452613d6 Mon Sep 17 00:00:00 2001 From: gwalut <155+gwalut@noreply.gitea.privcloud.tech> Date: Sat, 21 Nov 2026 11:56:57 +0300 Subject: [PATCH 1/2] Implement durable image queue with outbox worker and recovery checks --- .env.example | 29 +--- .gitattributes | 1 + Dockerfile | 27 ++++ REPORT.md | 128 ++++++++++++--- app/__init__.py | 1 + app/__main__.py | 17 ++ app/api.py | 194 +++++++++++++++++++++++ app/attachments.py | 195 +++++++++++++++++++++++ app/config.py | 28 ++++ app/errors.py | 22 +++ app/migrate.py | 37 +++++ app/models.py | 73 +++++++++ app/pipeline.py | 181 +++++++++++++++++++++ app/security.py | 93 +++++++++++ app/store.py | 238 ++++++++++++++++++++++++++++ app/transform.py | 35 ++++ compose.yaml | 213 +++++++++++++++++++++++++ docs/REVIEW.docx | Bin 0 -> 43681 bytes docs/SUBMISSION.md | 17 ++ evidence/after-restart.json | 134 ++++++++++++++++ evidence/before-restart.json | 134 ++++++++++++++++ evidence/failover.txt | 4 + evidence/images.txt | 7 + evidence/last-stop.json | 7 + evidence/persistence.txt | 3 + evidence/pipeline.json | 35 ++++ evidence/pipeline.txt | 138 ++++++++++++++++ evidence/restore.txt | 16 ++ evidence/smoke-final.txt | 2 + evidence/smoke.txt | 4 + evidence/source-integrity.json | 85 ++++++++++ evidence/startup.txt | 70 ++++++++ evidence/verification.json | 12 ++ infra/haproxy.cfg | 39 +++++ infra/redis.conf | 9 ++ infra/s3/Dockerfile | 9 ++ infra/s3/api-policy.json | 1 + infra/s3/bootstrap.sh | 8 + migrations/001_initial.sql | 32 ++++ migrations/002_message_requests.sql | 11 ++ migrations/003_attachments.sql | 11 ++ migrations/004_jobs.sql | 17 ++ requirements.txt | 19 +++ scripts/init_local.py | 35 ++++ scripts/ops.py | 94 +++++++++++ scripts/restart.sh | 4 + scripts/stop-one.sh | 4 + scripts/stop_one.py | 24 +++ scripts/verify.py | 33 ++++ start.ps1 | 13 ++ student-tests/pipeline_checks.py | 136 ++++++++++++++++ student-tests/test_images.py | 27 ++++ 52 files changed, 2658 insertions(+), 48 deletions(-) create mode 100644 .gitattributes create mode 100644 Dockerfile create mode 100644 app/__init__.py create mode 100644 app/__main__.py create mode 100644 app/api.py create mode 100644 app/attachments.py create mode 100644 app/config.py create mode 100644 app/errors.py create mode 100644 app/migrate.py create mode 100644 app/models.py create mode 100644 app/pipeline.py create mode 100644 app/security.py create mode 100644 app/store.py create mode 100644 app/transform.py create mode 100644 compose.yaml create mode 100644 docs/REVIEW.docx create mode 100644 docs/SUBMISSION.md create mode 100644 evidence/after-restart.json create mode 100644 evidence/before-restart.json create mode 100644 evidence/failover.txt create mode 100644 evidence/images.txt create mode 100644 evidence/last-stop.json create mode 100644 evidence/persistence.txt create mode 100644 evidence/pipeline.json create mode 100644 evidence/pipeline.txt create mode 100644 evidence/restore.txt create mode 100644 evidence/smoke-final.txt create mode 100644 evidence/smoke.txt create mode 100644 evidence/source-integrity.json create mode 100644 evidence/startup.txt create mode 100644 evidence/verification.json create mode 100644 infra/haproxy.cfg create mode 100644 infra/redis.conf create mode 100644 infra/s3/Dockerfile create mode 100644 infra/s3/api-policy.json create mode 100755 infra/s3/bootstrap.sh create mode 100644 migrations/001_initial.sql create mode 100644 migrations/002_message_requests.sql create mode 100644 migrations/003_attachments.sql create mode 100644 migrations/004_jobs.sql create mode 100644 requirements.txt create mode 100644 scripts/init_local.py create mode 100644 scripts/ops.py create mode 100755 scripts/restart.sh create mode 100755 scripts/stop-one.sh create mode 100644 scripts/stop_one.py create mode 100644 scripts/verify.py create mode 100644 start.ps1 create mode 100644 student-tests/pipeline_checks.py create mode 100644 student-tests/test_images.py diff --git a/.env.example b/.env.example index 119384b5..182638f5 100644 --- a/.env.example +++ b/.env.example @@ -1,25 +1,6 @@ -# Copy to .env for your LOCAL synthetic test environment; never commit .env. -# These are logical interface suggestions; map actual framework names in REPORT.md. -APP_HOST=0.0.0.0 -APP_PORT=8080 -APP_ENV=lab -SESSION_TTL_SECONDS=3600 -# Choose credentials locally. File paths contain no secret values. -DATABASE_URL_FILE=/run/secrets/database_url -# Optional on 3, required use on 4 in lab2; Redis OR Valkey: -SESSION_STORE=postgres -CACHE_URL_FILE=/run/secrets/cache_url +API_PORT=8085 API_REPLICAS=2 -IDEMPOTENCY_TTL_SECONDS=86400 -S3_ENDPOINT=http://s3:9000 -S3_REGION=us-east-1 -S3_BUCKET=messenger-attachments -S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id -S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key -MAX_UPLOAD_BYTES=10485760 -MAX_IMAGE_PIXELS=40000000 -BROKER_URL_FILE=/run/secrets/broker_url -WORKER_CONCURRENCY=2 -JOB_MAX_ATTEMPTS=5 -JOB_TIMEOUT_SECONDS=60 -STAGING_RETENTION_SECONDS=86400 +SESSION_TTL_SECONDS=3600 +APP_ENV=lab +APP_VERSION=lab5-v1 +MAX_ATTEMPTS=5 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..dfdb8b77 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.sh text eol=lf diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..cb6038c0 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,27 @@ +FROM docker:28.5.1-cli AS docker_cli + +FROM python:3.13.15-slim-bookworm AS runtime +ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 \ + APP_HOST=0.0.0.0 APP_PORT=8080 APP_ENV=lab +WORKDIR /app +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt \ + && useradd --uid 10001 --create-home messenger +COPY app ./app +COPY migrations ./migrations +COPY contracts/openapi.json ./contracts/openapi.json +USER messenger +EXPOSE 8080 +HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=5 \ + CMD python -c "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:' + os.getenv('APP_PORT', '8080') + '/health/ready', timeout=2)" +CMD ["python", "-m", "app"] + +# Optional test operator. The API image does not contain the Docker client/socket. +FROM runtime AS checks +USER root +COPY --from=docker_cli /usr/local/bin/docker /usr/local/bin/docker +COPY --from=docker_cli /usr/local/libexec/docker/cli-plugins/docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose +RUN apt-get update && apt-get install -y --no-install-recommends make \ + && rm -rf /var/lib/apt/lists/* +WORKDIR /checks +CMD ["make", "test-student"] diff --git a/REPORT.md b/REPORT.md index e98f75e9..64274a08 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,117 @@ -# Отчёт — лабораторная 5 +# Лабораторная 5 — очереди и обработка изображений -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +Саламатин, БПИ-2304. Целевая оценка — 4, включая минимум на 3. Треки на 5 не выполнялись. -## Запуск из чистого clone +## Запуск -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны Docker Desktop с Linux containers и Compose. Из каталога лабораторной в PowerShell: -## Архитектура и решения +```powershell +./start.ps1 +``` -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Скрипт создаёт случайные локальные secrets и .env, собирает API, checks и MinIO, применяет миграции и запускает стенд. Повторный запуск сохраняет пароли. Не менять secrets при сохранённых volumes без процедуры смены пароля. HTTP доступен по http://127.0.0.1:8085. API_PORT меняет порт, API_REPLICAS — число API (по умолчанию 2), MAX_ATTEMPTS — предел попыток (5), SESSION_TTL_SECONDS — срок сессии (3600). APP_ENV и APP_VERSION — метки окружения и версии. -## Доказательства критериев +Ручной запуск с Python 3.9+: -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +```powershell +python scripts/init_local.py +docker compose build api checks minio +docker compose up -d --no-build --wait --wait-timeout 180 +``` -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Остановить с сохранением данных: `docker compose stop` или `docker compose down`. Команда намеренного удаления учебных данных — `docker compose down --volumes`; тесты её не вызывают. -## Эксперименты и отказы +Версии закреплены в Dockerfile, requirements.txt и compose.yaml: Python 3.13.15, PostgreSQL 17.6, Redis 7.4.5, HAProxy 3.0.12. MinIO и mc собираются из официальных исходных релизов RELEASE.2025-09-07T16-13-09Z и RELEASE.2025-08-13T08-35-41Z. При первой сборке нужен доступ к реестрам и исходникам; она может занять несколько минут. Собранный ранее локальный MinIO тоже подходит. Минимальная машина — Docker с достаточной памятью для всех контейнеров; проверялось на локальном Docker Desktop. -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +## Что изменилось после lab4 -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +Перенесена собственная lab4: FastAPI, PostgreSQL, scrypt, Redis-сессии с TTL, история с cursor, идемпотентная отправка сообщений, две API-реплики, HAProxy и приватный MinIO. Контракт и публичные tests текущей лабы сохранены. -## Ограничения и следующие шаги +Раньше API возвращал готовое вложение с кодом 201. Теперь он принимает файл, проверяет его и возвращает 202 queued после устойчивого handoff. Клиент может сразу отправить сообщение с queued-вложением; скачивание до ready отвечает 409. GET метаданных доступен во всех четырёх состояниях. Failed нельзя прикрепить к новому сообщению. -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Путь работы: клиент → HAProxy → API → staging MinIO и PostgreSQL jobs → publisher → Redis Streams → worker → конечные объекты MinIO и атомарный результат PostgreSQL. Брокер отделён от Redis сессий, имеет свой volume и AOF с appendfsync always. PostgreSQL, S3, сессии и брокер используют разные именованные volumes. API и worker не публикуют свои порты; снаружи доступен только LB на loopback. + +## Граница 202 и outbox + +API ограничивает тело 10 MiB, принимает его по частям во временный файл, проверяет PNG/JPEG и предел 40 млн пикселей до распаковки. MIME определяется содержимым, filename используется только для отображения. Затем отдельно фиксирует pending-строку, которая учитывает будущий staging key. Под блокировкой этой строки записывает полный оригинал в staging/{attachment_id}, меняет статус на queued и создаёт jobs в одной SQL-транзакции. Ответ 202 формируется из снимка queued и уходит после COMMIT. Временный файл API после запроса не нужен. + +Таблица jobs одновременно служит transactional outbox и реестром выполнения. Publisher выбирает готовые к отправке queued-строки через FOR UPDATE SKIP LOCKED, публикует job и отмечает время отправки. До конечного состояния намерение остаётся в PostgreSQL; если задача не захвачена, публикация повторяется раз в 5 секунд. Это сознательно допускает дубли и восстанавливает намерение даже при потере записи в брокере. Уже готовые и failed задания не публикуются. + +Разрыв после staging до queued оставляет pending, который cleanup удаляет через час под блокировкой строки. Разрыв после SQL COMMIT до publish не теряет принятую задачу: publisher найдёт ту же jobs-строку после восстановления. Сбой после XADD до SQL COMMIT приведёт к повторной публикации с тем же job_id. Redis Streams с AOF always отвечает после записи AOF. Это граница приёма брокером; она отличается от consumer ack. + +Сообщение соответствует contracts/jobs.schema.json: schema_version, job_id, type, attachment_id, pipeline_version=1, attempt и created_at. В нём нет байтов, storage keys, URL, filename и credentials. job_id постоянен при redelivery. БД определяет реальное число попыток; старое значение attempt в дубле не сбрасывает счётчик. + +## Worker и идемпотентность + +Worker читает Streams consumer group по одному сообщению; concurrency=1 и count/prefetch=1. Захват сохраняет processing, номер попытки и lease на 90 секунд. Затем отдельная транзакция держит блокировку jobs-строки на время эффекта. Она не даёт другому worker или восстановителю одновременно опубликовать результат той же работы. После смерти процесса соединение закрывается, а просроченный lease позволяет publisher вернуть задачу в queued. Зависший декодер принудительно завершается по таймауту. + +Оригинал копируется из staging в original/{id} без перекодирования. Варианты записываются в variants/{id}/v1/{name}. Ключ эффекта — attachment_id, pipeline_version=1, variant. После всех S3 PUT одна SQL-транзакция публикует variants с размерами и SHA-256 и ставит attachment/job в ready. Только затем отправляется XACK и удаляется запись Streams. Дубль ready — no-op; он не увеличивает attempts и не возвращает объект в processing. При временной ошибке до ack устойчиво фиксируется намерение retry с available_at. При failed — устойчивый реестр ошибки. Если COMMIT не состоялся, ack не выполняется. + +Если процесс погиб после S3 PUT до SQL COMMIT, повтор пишет в те же ключи. Сбой после COMMIT результата до ack безопасен: дубль увидит ready. Обещается at least once доставка с идемпотентным эффектом; exactly once доставка не заявляется. Версия pipeline только 1; смена версий относится к невыполненному треку на 5. + +## Варианты и ограничения + +Thumbnail — JPEG quality 85, вписан в 256×256 без увеличения, размеры округляются вниз, минимум 1 px. Для исходника 320×200 получается 256×160. Crop — центрированный квадрат JPEG 128×128, quality 85; маленький исходник можно увеличить. Optimized — WebP quality 80, вписан в 1280×1280 без увеличения. EXIF orientation применяется до расчёта размеров; alpha накладывается на белый. Новое RGB-изображение убирает EXIF, ICC и текстовые метаданные. WebP не обязан быть меньше каждого исходника. + +Worker запускает декодирование в отдельном дочернем процессе с таймаутом 30 s. Лимит контейнера — 512 MiB и 1 CPU, одновременно декодируется один файл. Эти ограничения защищают хост, но предельно большие допустимые по пикселям файлы могут не уложиться в память и завершиться failed после ограниченных попыток. API тоже ограничен 512 MiB, одним декодированием на реплику, 10 s ожидания слота, 20 s чтения тела и общим HTTP-бюджетом 35 s. S3 connect/read timeout — 2/3 s. + +Постоянный сбой содержимого даёт invalid_image и сразу failed. Ошибка S3 или таймаут обработки временные: backoff min(60, 2^attempt) секунд плюс jitter 0–1 s. Предел по умолчанию 5 попыток, затем retry_exhausted. Зависшая последняя попытка также переходит в failed после lease. Ошибки наружу не содержат SQL, traceback или секреты. + +Вместо отдельной DLQ используется jobs + attachments со state/status failed. Оператор видит их в БД. Явный replay: + +```powershell +docker compose exec worker python -m app.pipeline replay JOB_UUID "Причина повторной обработки" +``` + +Команда принимает только failed, блокирует строку, создаёт replay_audit и начинает новый ограниченный цикл попыток того же job_id. Ready повторно запустить этой командой нельзя. Staging ready удаляет publisher после безопасного COMMIT; неуспешный исходник хранится 7 дней для replay, затем очищается. Реестр сохраняется, replay после очистки запрещён. Queued/processing очистка не трогает. Неподтверждённые pending очищает отдельный cleanup после часа. Конечные orphan-объекты частично выполненного failed задания автоматически не удаляются; их число ограничено фиксированными ключами. + +## Проверки и воспроизведение + +Полный прогон с Python на хосте: + +```powershell +python scripts/verify.py +``` + +На этом компьютере доступен `../.tools/python/python.exe scripts/verify.py`. Проверки явно останавливают и перезапускают только контейнеры этого Compose-проекта, сохраняют volumes и восстанавливают API. Не запускать два сценария отказа одновременно. + +Отдельные команды: + +```powershell +docker compose run --rm --no-deps checks make check test +docker compose run --rm --no-deps -e PYTHONPATH=/app checks python -m unittest discover -s student-tests -p test_images.py -v +docker compose run --rm --no-deps -e PYTHONPATH=/app checks python student-tests/pipeline_checks.py +docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh' +docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh' +docker compose start api +``` + +Проверки выполнены 21 ноября 2026 года. Исходный skeleton — 276dbdad8a34da4c5b57fbf1879ca169b581d75b, ветка solution/bpi-2304-salamatin. Результаты полного прогона — evidence/verification.json, подробности — pipeline.json и текстовые логи. before-restart.json и after-restart.json показывают реальные контейнеры, время старта и сохранённые volumes. + +| Проверка | Что доказывает | Файл | +| --- | --- | --- | +| Неизменённый публичный smoke | 202, ready, авторизация, оригинал и настоящий JPEG thumbnail | smoke.txt, smoke-final.txt | +| Два теста изображения | EXIF, белый фон, отсутствие увеличения, удаление metadata | images.txt | +| Worker остановлен, API/broker перезапущены | Сообщение с queued-вложением создано, задание сохранено и завершено | pipeline.json | +| API killed между COMMIT и publish при выключенном publisher | Outbox доставляет прежнее задание автоматически | pipeline.json | +| Одноразовый os._exit после копирования original | Восстановление lease, тот же результат, ровно три объекта вариантов | pipeline.json | +| Три дубля ready-job | Attempts и checksums не меняются | pipeline.json | +| Повреждённый staging и replay | invalid_image, аудит, восстановление того же job_id | pipeline.json | +| Выключенный MinIO | Пять попыток с backoff, итоговый retry_exhausted | pipeline.json | +| Негативные загрузки | Размер, повреждение, MIME, filename возвращают 4xx | pipeline.json | +| Persistence и failover | Сохранность прежней сессии и данных; работа через оставшуюся API | persistence.txt, failover.txt | + +Для crash после объекта тест создаёт одноразовый /tmp/crash_after_object в worker. Это тестовый fault injection внутри локального контейнера, через HTTP он недоступен. Первый отладочный запуск выявил ошибку тестового окружения: Compose поднимал MinIO как зависимость worker и мешал проверить outage. Исправленный сценарий запускает существующий worker через docker start по ID контейнера. Также удалён лишний запуск нового контейнера из checks, где host bind paths не совпадают. Публичные tests не менялись. + +## Ограничения + +Стенд локальный и учебный: одиночные PostgreSQL, MinIO, брокер, Redis сессий и LB остаются точками отказа. Проверяется restart с сохранением volumes, а не потеря диска или хоста. Нет резервного копирования и TLS для удалённого доступа. При недоступном брокере API может продолжать приём через outbox, пока работают PostgreSQL и staging; недоступный worker не вызывает синхронный resize в API. Readiness API проверяет PostgreSQL, Redis сессий и S3; брокер и worker не критичны для устойчивого приёма. Нет backpressure по длине очереди; оценка предельной нагрузки не проводилась. + +## Источники и помощь + +Задание, контракт и публичные проверки: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab5 + +Собственная реализация предыдущей работы: ../mtusi2026lab4. Redis Streams: https://redis.io/docs/latest/develop/data-types/streams/ . Pillow: https://pillow.readthedocs.io/en/stable/ . MinIO: https://github.com/minio/minio . + +Использованы FastAPI, Psycopg, redis-py, boto3, Pillow и HAProxy. Codex помог написать реализацию, сценарии проверок и пояснения. Разбор для защиты — docs/REVIEW.docx. diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 00000000..74f4d5ce --- /dev/null +++ b/app/__init__.py @@ -0,0 +1 @@ +"""Laboratory 1: a single-process, in-memory messenger.""" diff --git a/app/__main__.py b/app/__main__.py new file mode 100644 index 00000000..7de06dc9 --- /dev/null +++ b/app/__main__.py @@ -0,0 +1,17 @@ +import logging +import os + +import uvicorn + + +def main(): + logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") + logging.getLogger("psycopg.pool").setLevel(logging.CRITICAL) + logging.info("Starting lab3 environment=%s with shared PostgreSQL and Redis", os.getenv("APP_ENV", "lab")) + uvicorn.run("app.api:app", host=os.getenv("APP_HOST", "0.0.0.0"), + port=int(os.getenv("APP_PORT", "8080")), workers=1, + access_log=False, timeout_graceful_shutdown=5) + + +if __name__ == "__main__": + main() diff --git a/app/api.py b/app/api.py new file mode 100644 index 00000000..12f092c0 --- /dev/null +++ b/app/api.py @@ -0,0 +1,194 @@ +import asyncio +from contextlib import asynccontextmanager +import json +import logging +import os +from pathlib import Path +import re +from time import perf_counter +from uuid import uuid4 + +from fastapi import Depends, FastAPI, Request +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from fastapi.responses import Response +import psycopg +from psycopg_pool import PoolTimeout, TooManyRequests +from redis.exceptions import RedisError +from pydantic import ValidationError +from starlette.exceptions import HTTPException + +from .config import Settings +from .errors import APIError, invalid, unavailable +from .models import CreateChat, CreateMessage, CreateUser +from .security import basic_credentials, identifier +from .store import Store +from .attachments import Attachments, metadata +from botocore.exceptions import BotoCoreError, ClientError +from starlette.requests import ClientDisconnect + +logger = logging.getLogger("messenger") + + +def error_response(request, status, code, message, headers=None): + return JSONResponse(status_code=status, headers=headers, content={"error": { + "code": code, "message": message, "request_id": request.state.request_id}}) + + +async def body(request, model): + content_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower() + if content_type != "application/json": + raise APIError(415, "unsupported_media_type", "Use application/json") + try: + raw = (await request.body()).decode("utf-8") + def reject_constant(value): + raise ValueError("Nonstandard JSON constant") + data = json.loads(raw, parse_constant=reject_constant) + return model.model_validate(data) + except (ValueError, UnicodeError, ValidationError): + raise invalid("Body must be valid UTF-8 JSON with the required fields and types") from None + + +def pagination(request): + raw = request.query_params.get("limit", "50") + if re.fullmatch(r"[0-9]+", raw) is None or len(raw) > 3 or not 1 <= int(raw) <= 100: + raise invalid("Limit must be an integer from 1 to 100") + return int(raw), request.query_params.get("cursor") + + +def create_app(settings=None): + @asynccontextmanager + async def lifespan(app): + store = Store(settings or Settings.load()) + app.state.store = store + app.state.attachments = Attachments(store) + try: + await store.open() + yield + finally: + await store.close() + + instance_id = os.getenv("HOSTNAME", "api") + "-" + uuid4().hex[:12] + app = FastAPI(title="Lab 5 messenger", docs_url=None, redoc_url=None, + openapi_url=None, redirect_slashes=False, lifespan=lifespan) + + @app.middleware("http") + async def request_context(request, call_next): + request.state.request_id = str(uuid4()) + start = perf_counter() + try: + async with asyncio.timeout(35): + response = await call_next(request) + except (psycopg.Error, PoolTimeout, TooManyRequests, RedisError, BotoCoreError, ClientError, TimeoutError, ClientDisconnect): + error = unavailable() + logger.warning("Storage unavailable request_id=%s", request.state.request_id) + response = error_response(request, error.status, error.code, error.message) + except Exception: + logger.error("Unhandled error request_id=%s", request.state.request_id) + response = error_response(request, 500, "internal_error", "Internal server error") + response.headers["X-Request-Id"] = request.state.request_id + response.headers["X-Instance-Id"] = instance_id + response.headers["X-App-Version"] = os.getenv("APP_VERSION", "lab3-v1") + logger.info("request_id=%s method=%s path=%s status=%s duration_ms=%.2f", + request.state.request_id, request.method, request.url.path, + response.status_code, (perf_counter() - start) * 1000) + return response + + @app.exception_handler(APIError) + async def api_error(request, error): + return error_response(request, error.status, error.code, error.message, error.headers) + + @app.exception_handler(RequestValidationError) + async def validation_error(request, error): + return error_response(request, 400, "invalid_request", "Invalid request parameters") + + @app.exception_handler(HTTPException) + async def routing_error(request, error): + code = "not_found" if error.status_code == 404 else "invalid_request" + return error_response(request, error.status_code, code, "Unknown path or unsupported method") + + async def current_user(request: Request): + user, token = await app.state.store.authenticate(request.headers.get("authorization")) + request.state.session_token = token + return user + + @app.get("/health/live") + async def health(): + return {"status": "ok"} + + @app.get("/health/ready") + async def readiness(): + await app.state.store.ready() + await asyncio.to_thread(app.state.attachments.s3.head_bucket, Bucket="attachments") + return {"status": "ok"} + + @app.post("/api/v1/auth/sessions", status_code=201) + async def login(request: Request): + credentials = basic_credentials(request.headers.get("authorization")) + if await request.body(): + raise invalid("Session creation does not accept a body") + return await app.state.store.login(*credentials) + + @app.delete("/api/v1/auth/sessions/current", status_code=204) + async def logout(request: Request, user=Depends(current_user)): + await app.state.store.logout(request.state.session_token) + return Response(status_code=204) + + @app.post("/api/v1/users", status_code=201) + async def create_user(request: Request): + return await app.state.store.create_user(await body(request, CreateUser)) + + @app.get("/api/v1/users/me") + async def me(user=Depends(current_user)): + return user + + @app.post("/api/v1/chats", status_code=201) + async def create_chat(request: Request, user=Depends(current_user)): + return await app.state.store.create_chat(user["id"], await body(request, CreateChat)) + + @app.get("/api/v1/chats") + async def list_chats(request: Request, user=Depends(current_user)): + return await app.state.store.list_chats(user["id"], *pagination(request)) + + @app.get("/api/v1/chats/{chat_id}") + async def get_chat(chat_id: str, user=Depends(current_user)): + return await app.state.store.get_chat(user["id"], identifier(chat_id)) + + @app.post("/api/v1/chats/{chat_id}/messages", status_code=201) + async def create_message(chat_id: str, request: Request, user=Depends(current_user)): + chat_id = identifier(chat_id) + await app.state.store.get_chat(user["id"], chat_id) + key = request.headers.get("idempotency-key", "") + if re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", key, flags=re.ASCII) is None: + raise invalid("A valid Idempotency-Key is required") + return await app.state.store.create_message(user["id"], chat_id, + await body(request, CreateMessage), key) + + @app.get("/api/v1/chats/{chat_id}/messages") + async def list_messages(chat_id: str, request: Request, user=Depends(current_user)): + chat_id = identifier(chat_id) + await app.state.store.get_chat(user["id"], chat_id) + return await app.state.store.list_messages(user["id"], chat_id, *pagination(request)) + + @app.post("/api/v1/chats/{chat_id}/attachments", status_code=202) + async def upload(chat_id: str, request: Request, user=Depends(current_user)): + return await app.state.attachments.upload(user["id"], identifier(chat_id), request) + + @app.get("/api/v1/attachments/{attachment_id}") + async def attachment(attachment_id: str, user=Depends(current_user)): + return metadata(await app.state.attachments.get(user["id"], identifier(attachment_id))) + + @app.get("/api/v1/attachments/{attachment_id}/content") + async def content(attachment_id: str, request: Request, user=Depends(current_user)): + row = await app.state.attachments.get(user["id"], identifier(attachment_id)) + return await app.state.attachments.download(row, request.query_params.get("variant", "original")) + + @app.get("/openapi.json", include_in_schema=False) + async def contract(): + path = Path(__file__).resolve().parents[1] / "contracts" / "openapi.json" + return json.loads(path.read_text(encoding="utf-8")) + + return app + + +app = create_app() diff --git a/app/attachments.py b/app/attachments.py new file mode 100644 index 00000000..780ad370 --- /dev/null +++ b/app/attachments.py @@ -0,0 +1,195 @@ +"""Private S3 originals and durable upload intents.""" +import asyncio +from contextlib import asynccontextmanager +import hashlib +import os +from pathlib import Path +import tempfile +import warnings +from uuid import uuid4, UUID + +import boto3 +from botocore.config import Config +from PIL import Image, UnidentifiedImageError +from starlette.responses import StreamingResponse + +from .errors import APIError, invalid +from .store import public + +MAX_BYTES = 10 * 1024 * 1024 +MAX_PIXELS = 40_000_000 +Image.MAX_IMAGE_PIXELS = MAX_PIXELS +BUCKET = 'attachments' + +def secret(name): + return Path('/run/secrets/' + name).read_text().strip() + +def client(): + return boto3.client('s3', endpoint_url='http://minio:9000', region_name='us-east-1', + aws_access_key_id='messenger-api', aws_secret_access_key=secret('s3_secret_key'), + config=Config(connect_timeout=2, read_timeout=3, retries={'max_attempts': 0}, + s3={'addressing_style': 'path'}, max_pool_connections=4)) + +def validate_image(file, content_type): + try: + with warnings.catch_warnings(): + warnings.simplefilter('error', Image.DecompressionBombWarning) + file.seek(0) + with Image.open(file) as image: + if image.width * image.height > MAX_PIXELS: + raise APIError(413, 'payload_too_large', 'Too many pixels') + if image.format not in ('PNG', 'JPEG') or Image.MIME[image.format] != content_type: + raise APIError(415, 'unsupported_media_type', 'Image MIME does not match') + image.verify() + file.seek(0) + with Image.open(file) as image: + image.load() + except (Image.DecompressionBombError, Image.DecompressionBombWarning): + raise APIError(413, 'payload_too_large', 'Too many pixels') from None + except (UnidentifiedImageError, OSError, SyntaxError, ValueError): + raise APIError(415, 'unsupported_media_type', 'Invalid image') from None + finally: + file.seek(0) + +def metadata(row): + row = dict(row) + row['owner_id'] = row['uploader_id'] + row.setdefault('updated_at', row['created_at']) + return public({k: row[k] for k in ('id','chat_id','owner_id','filename','content_type', + 'size_bytes','sha256','status','created_at','updated_at')}) | {'variants': row['variants'], 'error_code': row['error_code']} + +async def blocking(function, *args, **kwargs): + # Cancellation must not close the spool or release the SQL lock while a thread uses it. + task = asyncio.create_task(asyncio.to_thread(function, *args, **kwargs)) + try: + return await asyncio.shield(task) + except asyncio.CancelledError: + await task + raise + +class Attachments: + def __init__(self, store): + self.store = store + self.s3 = client() + # One decode per replica bounds decoded RGBA memory to about 160 MB. + self.slots = asyncio.Semaphore(1) + + @asynccontextmanager + async def slot(self): + try: + await asyncio.wait_for(self.slots.acquire(), timeout=10) + except TimeoutError: + raise APIError(503, 'unavailable', 'Upload capacity is busy') from None + try: + yield + finally: + self.slots.release() + + async def get(self, actor, attachment_id): + async with self.store.pool.connection() as conn: + cur = await conn.execute('''SELECT a.* FROM attachments a JOIN chat_members m + ON m.chat_id=a.chat_id WHERE a.id=%s AND m.user_id=%s''', + (attachment_id, UUID(actor))) + row = await cur.fetchone() + if row is None: + raise APIError(404, 'not_found', 'Attachment not found') + return row + + async def upload(self, actor, chat_id, request): + await self.store.get_chat(actor, chat_id) + name = request.query_params.get('filename', '') + if not 1 <= len(name) <= 255 or any(c in '/\\' or ord(c) < 32 or ord(c) == 127 for c in name): + raise invalid('Invalid filename') + mime = request.headers.get('content-type', '').strip().lower() + if mime not in ('image/png','image/jpeg'): + raise APIError(415, 'unsupported_media_type', 'Use PNG or JPEG') + length = request.headers.get('content-length') + if length is not None: + if not length.isascii() or not length.isdecimal(): + raise invalid('Invalid Content-Length') + if int(length) > MAX_BYTES: + raise APIError(413, 'payload_too_large', 'File exceeds 10 MiB') + async with self.slot(): + # Temporary spool is only staging, never the source of confirmed originals. + with tempfile.TemporaryFile() as file: + size = 0 + digest = hashlib.sha256() + async with asyncio.timeout(20): + async for chunk in request.stream(): + size += len(chunk) + if size > MAX_BYTES: + raise APIError(413, 'payload_too_large', 'File exceeds 10 MiB') + file.write(chunk) + digest.update(chunk) + await blocking(validate_image, file, mime) + attachment_id = uuid4() + key = 'original/' + attachment_id.hex + # Commit the intent BEFORE PUT: even a killed process leaves a tracked key. + async with self.store.pool.connection() as conn: + await conn.execute('''INSERT INTO attachments + (id,chat_id,uploader_id,object_key,filename,content_type,size_bytes,sha256,status) + VALUES (%s,%s,%s,%s,%s,%s,%s,%s,'pending')''', + (attachment_id,chat_id,UUID(actor),key,name,mime,size,digest.hexdigest())) + # The pending row tracks the staging key before S3 PUT. + async with self.store.pool.connection() as conn: + await conn.execute('SELECT id FROM attachments WHERE id=%s FOR UPDATE', (attachment_id,)) + await blocking(self.s3.put_object, Bucket=BUCKET, Key='staging/'+attachment_id.hex, + Body=file, ContentLength=size, ContentType=mime) + cur = await conn.execute("UPDATE attachments SET status='queued', updated_at=clock_timestamp() WHERE id=%s RETURNING *", + (attachment_id,)) + result = metadata(await cur.fetchone()) + await conn.execute('INSERT INTO jobs(id,attachment_id) VALUES (%s,%s)', (uuid4(),attachment_id)) + # COMMIT of queued + job is the durable handoff; publisher is independent. + return result + + async def download(self, row, variant='original'): + if row['status'] != 'ready': + raise APIError(409, 'conflict', 'Attachment is not ready') + row = dict(row) + if variant != 'original': + info = next((v for v in row['variants'] if v['name']==variant), None) + if info is None: + raise APIError(404, 'not_found', 'Variant not found') + row.update(info) + row['object_key'] = 'variants/'+row['id'].hex+'/v1/'+variant + obj = await asyncio.to_thread(self.s3.get_object, Bucket=BUCKET, Key=row['object_key']) + stream = obj['Body'] + async def chunks(): + try: + while chunk := await asyncio.to_thread(stream.read, 64 * 1024): + yield chunk + finally: + stream.close() + return StreamingResponse(chunks(), media_type=row['content_type'], headers={ + 'Content-Length': str(row['size_bytes']), 'X-Content-Type-Options': 'nosniff'}) + + async def cleanup(self): + removed = 0 + async with self.store.pool.connection() as conn: + cur = await conn.execute("""SELECT id,object_key FROM attachments WHERE status='pending' + AND created_at < clock_timestamp()-interval '1 hour' ORDER BY created_at + LIMIT 100 FOR UPDATE SKIP LOCKED""") + for row in await cur.fetchall(): + await asyncio.to_thread(self.s3.delete_object, Bucket=BUCKET, Key='staging/'+row['id'].hex) + await conn.execute("DELETE FROM attachments WHERE id=%s AND status='pending'", (row['id'],)) + removed += 1 + return removed + +async def cleaner(): + from .config import Settings + from .store import Store + store = Store(Settings.load()) + await store.open() + attachments = Attachments(store) + try: + while True: + try: + print({'removed_pending': await attachments.cleanup()}, flush=True) + except Exception: + print('Cleanup deferred; storage unavailable', flush=True) + await asyncio.sleep(60) + finally: + await store.close() + +if __name__ == '__main__': + asyncio.run(cleaner()) diff --git a/app/config.py b/app/config.py new file mode 100644 index 00000000..f1f93108 --- /dev/null +++ b/app/config.py @@ -0,0 +1,28 @@ +"""Runtime settings; credential values are never logged.""" +from dataclasses import dataclass +import os +from pathlib import Path + + +def secret(name): + return Path(os.environ[name + "_FILE"]).read_text(encoding="utf-8").strip() + + +@dataclass(frozen=True) +class Settings: + database_url: str + cache_url: str + cursor_key: bytes + session_ttl: int + + @classmethod + def load(cls): + ttl = int(os.getenv("SESSION_TTL_SECONDS", "3600")) + if not 1 <= ttl <= 604800: + raise ValueError("SESSION_TTL_SECONDS must be in 1..604800") + if os.getenv("SESSION_STORE", "redis") != "redis": + raise ValueError("This deployment uses SESSION_STORE=redis") + key = secret("CURSOR_KEY").encode() + if len(key) < 32: + raise ValueError("Cursor key must contain at least 32 bytes") + return cls(secret("DATABASE_URL"), secret("CACHE_URL"), key, ttl) diff --git a/app/errors.py b/app/errors.py new file mode 100644 index 00000000..37cbc552 --- /dev/null +++ b/app/errors.py @@ -0,0 +1,22 @@ +class APIError(Exception): + def __init__(self, status: int, code: str, message: str, headers=None): + self.status = status + self.code = code + self.message = message + self.headers = headers or {} + super().__init__(message) + + +def invalid(message="Invalid request"): + return APIError(400, "invalid_request", message) + + +def unauthorized(basic=False): + challenge = ('Basic realm="messenger", charset="UTF-8"' if basic + else 'Bearer realm="messenger"') + return APIError(401, "unauthorized", "Valid credentials required", + {"WWW-Authenticate": challenge}) + + +def unavailable(): + return APIError(503, "unavailable", "Storage temporarily unavailable") diff --git a/app/migrate.py b/app/migrate.py new file mode 100644 index 00000000..8f9a2161 --- /dev/null +++ b/app/migrate.py @@ -0,0 +1,37 @@ +"""Apply numbered migrations atomically; safe to repeat and serialize.""" +import hashlib +from pathlib import Path + +import psycopg + +from .config import secret + +ROOT = Path(__file__).resolve().parents[1] + + +def migrate(): + with psycopg.connect(secret("DATABASE_URL"), connect_timeout=2, + options="-c statement_timeout=10000 -c lock_timeout=5000") as conn: + conn.execute("SELECT pg_advisory_xact_lock(202602)") + conn.execute("""CREATE TABLE IF NOT EXISTS schema_migrations ( + version text PRIMARY KEY, sha256 text NOT NULL, + applied_at timestamptz NOT NULL DEFAULT clock_timestamp())""") + for path in sorted((ROOT / "migrations").glob("[0-9]*.sql")): + # Git checkout may change LF to CRLF on Windows; SQL is unchanged. + content = path.read_text(encoding="utf-8").encode("utf-8") + checksum = hashlib.sha256(content).hexdigest() + row = conn.execute("SELECT sha256 FROM schema_migrations WHERE version=%s", (path.name,)).fetchone() + if row: + if row[0] != checksum: + raise RuntimeError("Applied migration checksum differs: " + path.name) + print("Unchanged:", path.name) + continue + conn.execute(content.decode("utf-8")) + conn.execute("INSERT INTO schema_migrations(version, sha256) VALUES (%s, %s)", + (path.name, checksum)) + print("Applied:", path.name) + print("PASS: migrations committed") + + +if __name__ == "__main__": + migrate() diff --git a/app/models.py b/app/models.py new file mode 100644 index 00000000..42a4d2f4 --- /dev/null +++ b/app/models.py @@ -0,0 +1,73 @@ +"""Strict request models; strings retain their original Unicode content.""" +import re +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator + + +class Input(BaseModel): + model_config = ConfigDict(strict=True, extra="forbid") + + @field_validator("*", check_fields=False) + @classmethod + def valid_text(cls, value): + if isinstance(value, str): + if not value.strip(): + raise ValueError("A string must not be blank") + value.encode("utf-8") + if "\x00" in value: + raise ValueError("NUL is not supported") + return value + + +class CreateUser(Input): + username: str + display_name: str = Field(min_length=1, max_length=100) + password: str = Field(min_length=12, max_length=128) + + @field_validator("username") + @classmethod + def username_format(cls, value): + if re.fullmatch(r"[a-z0-9_]{3,32}", value) is None: + raise ValueError("Invalid username") + return value + + +class CreateChat(Input): + title: str = Field(min_length=1, max_length=100) + member_ids: list[str] = Field(min_length=1, max_length=100) + + @field_validator("member_ids") + @classmethod + def members(cls, values): + normalized = [str(UUID(value)) for value in values] + if len(set(normalized)) != len(normalized): + raise ValueError("Duplicate members") + return normalized + + +class CreateMessage(Input): + text: str = Field(max_length=4000) + attachment_ids: list[str] = Field(default_factory=list, max_length=10) + + @field_validator("text") + @classmethod + def valid_text(cls, value): + value.encode("utf-8") + if "\x00" in value: + raise ValueError("Invalid text") + return value + + @field_validator("attachment_ids") + @classmethod + def attachments(cls, values): + normalized = [str(UUID(value)) for value in values] + if len(set(normalized)) != len(normalized): + raise ValueError("Duplicate attachments") + return normalized + + @model_validator(mode="after") + def not_empty(self): + if not self.text.strip() and not self.attachment_ids: + raise ValueError("Message is empty") + return self diff --git a/app/pipeline.py b/app/pipeline.py new file mode 100644 index 00000000..f5bb70b5 --- /dev/null +++ b/app/pipeline.py @@ -0,0 +1,181 @@ +"""PostgreSQL outbox, Redis Streams at-least-once transport and fenced effects.""" +import asyncio +import hashlib +import json +import os +from pathlib import Path +import random +import sys +import tempfile +from uuid import uuid4, UUID +from psycopg.types.json import Jsonb +from redis.asyncio import Redis +from redis.exceptions import ResponseError +from .attachments import Attachments, BUCKET +from .config import Settings +from .store import Store + +STREAM='images.v1' +GROUP='workers' +MAX_ATTEMPTS=int(os.getenv('MAX_ATTEMPTS','5')) + +def broker(): + return Redis.from_url(Path('/run/secrets/cache_url').read_text().strip().replace('@redis:', '@broker:'), decode_responses=True) + +async def publish(store, queue, attachments): + async with store.pool.connection() as conn: + # Row locks fence stale workers; recovery waits until their connection is gone. + expired=await conn.execute("""SELECT id,attachment_id,attempts FROM jobs WHERE state='processing' + AND lease_until=MAX_ATTEMPTS: + await conn.execute("UPDATE jobs SET state='failed',lease_until=NULL WHERE id=%s",(row['id'],)) + await conn.execute("UPDATE attachments SET status='failed',error_code='retry_exhausted',updated_at=clock_timestamp() WHERE id=%s",(row['attachment_id'],)) + continue + await conn.execute("UPDATE jobs SET state='queued', available_at=clock_timestamp(),last_published=NULL WHERE id=%s",(row['id'],)) + await conn.execute("UPDATE attachments SET status='queued',updated_at=clock_timestamp() WHERE id=%s",(row['attachment_id'],)) + cur=await conn.execute("""SELECT * FROM jobs WHERE state='queued' AND available_at<=clock_timestamp() + AND (last_published IS NULL OR last_publishedMAX_ATTEMPTS: + code='retry_exhausted' + else: + with tempfile.TemporaryDirectory() as directory: + source=Path(directory)/'source' + await asyncio.to_thread(attachments.s3.download_file,BUCKET,'staging/'+row['id'].hex,str(source)) + if source.stat().st_size!=row['size_bytes'] or hashlib.sha256(source.read_bytes()).hexdigest()!=row['sha256']: + code='invalid_image' + else: + child=await asyncio.create_subprocess_exec(sys.executable,'-m','app.transform',str(source),row['content_type'],directory, + stdout=asyncio.subprocess.PIPE,stderr=asyncio.subprocess.DEVNULL) + try: + stdout,_=await asyncio.wait_for(child.communicate(),30) + except BaseException: + child.kill() + await child.wait() + raise + if child.returncode: + code='invalid_image' + else: + variants=json.loads(stdout) + await asyncio.to_thread(attachments.s3.copy_object,Bucket=BUCKET,Key=row['object_key'], + CopySource={'Bucket':BUCKET,'Key':'staging/'+row['id'].hex}) + # Test-only one-shot crash marker on the disposable container filesystem. + if Path('/tmp/crash_after_object').exists(): + Path('/tmp/crash_after_object').unlink() + os._exit(86) + for variant in variants: + body=(Path(directory)/variant['name']).read_bytes() + variant.update(size_bytes=len(body),sha256=hashlib.sha256(body).hexdigest()) + await asyncio.to_thread(attachments.s3.put_object,Bucket=BUCKET, + Key='variants/'+row['id'].hex+'/v1/'+variant['name'],Body=body,ContentType=variant['content_type']) + await conn.execute("UPDATE attachments SET status='ready',variants=%s,error_code=NULL,updated_at=clock_timestamp() WHERE id=%s",(Jsonb(variants),row['id'])) + await conn.execute("UPDATE jobs SET state='ready',lease_until=NULL WHERE id=%s",(job_id,)) + return + except TimeoutError: + code='processing_timeout' + except Exception: + code='storage_unavailable' + terminal=code=='invalid_image' or job['attempts']>=MAX_ATTEMPTS + if terminal and code!='invalid_image': + code='retry_exhausted' + delay=min(60,2**min(job['attempts'],6))+random.uniform(0,1) + state='failed' if terminal else 'queued' + await conn.execute("UPDATE jobs SET state=%s,available_at=clock_timestamp()+(%s*interval '1 second'),lease_until=NULL,last_published=NULL WHERE id=%s",(state,delay,job_id)) + await conn.execute('UPDATE attachments SET status=%s,error_code=%s,updated_at=clock_timestamp() WHERE id=%s',(state,code if terminal else None,row['id'])) + +async def replay(store, job_id, reason): + if not reason.strip(): + raise ValueError('Replay reason required') + async with store.pool.connection() as conn: + cur=await conn.execute('SELECT * FROM jobs WHERE id=%s FOR UPDATE',(UUID(job_id),)) + job=await cur.fetchone() + if not job or job['state']!='failed': + raise ValueError('Only failed jobs can be replayed') + cur=await conn.execute('SELECT staging_cleaned FROM attachments WHERE id=%s',(job['attachment_id'],)) + if (await cur.fetchone())['staging_cleaned']: + raise ValueError('Replay retention expired') + await conn.execute('INSERT INTO replay_audit(job_id,reason) VALUES (%s,%s)',(job['id'],reason)) + await conn.execute("UPDATE jobs SET state='queued',attempts=0,available_at=clock_timestamp(),last_published=NULL WHERE id=%s",(job['id'],)) + await conn.execute("UPDATE attachments SET status='queued',error_code=NULL,updated_at=clock_timestamp() WHERE id=%s",(job['attachment_id'],)) + +async def main(role): + store=Store(Settings.load()); await store.open() + queue=broker(); attachments=Attachments(store) + try: + if role=='replay': + await replay(store,*sys.argv[2:]); return + if role=='worker': + try: await queue.xgroup_create(STREAM,GROUP,id='0',mkstream=True) + except ResponseError as error: + if 'BUSYGROUP' not in str(error): raise + consumer=uuid4().hex + while True: + try: + Path('/tmp/pipeline_alive').touch() + if role=='publisher': + await publish(store,queue,attachments); await asyncio.sleep(.5) + else: + claimed=await queue.xautoclaim(STREAM,GROUP,consumer,5000,'0-0',count=1) + entries=claimed[1] + if not entries: + batches=await queue.xreadgroup(GROUP,consumer,{STREAM:'>'},count=1,block=1000) + entries=batches[0][1] if batches else [] + for message_id, fields in entries: + await process(store,attachments,json.loads(fields['payload'])) + await queue.xack(STREAM,GROUP,message_id) + await queue.xdel(STREAM,message_id) + except Exception: + print(role+': operation deferred',flush=True) + await asyncio.sleep(1) + finally: + await queue.aclose(); await store.close() + +if __name__=='__main__': + asyncio.run(main(sys.argv[1])) diff --git a/app/security.py b/app/security.py new file mode 100644 index 00000000..4bdce617 --- /dev/null +++ b/app/security.py @@ -0,0 +1,93 @@ +"""scrypt passwords, strict Basic credentials and persistent signed cursors.""" +import base64 +from datetime import datetime, timezone +import hashlib +import hmac +import json +import re +import secrets +from uuid import UUID + +from .errors import invalid, unauthorized + + +def password_hash(password, salt=None): + salt = salt or secrets.token_bytes(16) + digest = hashlib.scrypt(password.encode("utf-8"), salt=salt, n=16384, + r=8, p=1, dklen=32, maxmem=64 * 1024 * 1024) + return "scrypt$16384$8$1$" + salt.hex() + "$" + digest.hex() + + +def password_matches(password, encoded): + try: + algorithm, n, r, p, salt, digest = encoded.split("$") + if (algorithm, n, r, p) != ("scrypt", "16384", "8", "1"): + return False + actual = password_hash(password, bytes.fromhex(salt)).rsplit("$", 1)[1] + return hmac.compare_digest(actual, digest) + except (ValueError, UnicodeError): + return False + + +def basic_credentials(header): + try: + scheme, encoded = header.split(" ", 1) + if scheme.lower() != "basic" or len(encoded) > 2048: + raise ValueError + value = base64.b64decode(encoded, validate=True).decode("utf-8") + username, password = value.split(":", 1) + if re.fullmatch(r"[a-z0-9_]{3,32}", username) is None: + raise ValueError + if not 12 <= len(password) <= 128: + raise ValueError + return username, password + except (AttributeError, ValueError, UnicodeError): + raise unauthorized(basic=True) from None + + +def bearer(header): + try: + scheme, token = header.split(" ", 1) + if scheme.lower() != "bearer" or re.fullmatch(r"[A-Za-z0-9_-]{43}", token) is None: + raise ValueError + return token + except (AttributeError, ValueError): + raise unauthorized() from None + + +def identifier(value): + try: + return UUID(value) + except (ValueError, AttributeError, TypeError): + raise invalid("Invalid UUID") from None + + +def stamp(value): + return value.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +class Cursors: + def __init__(self, key): + self.key = key + + def encode(self, scope, item): + payload = json.dumps([scope, item["created_at"], item["id"]], separators=(",", ":")).encode() + signature = hmac.digest(self.key, payload, hashlib.sha256) + return base64.urlsafe_b64encode(signature + payload).decode().rstrip("=") + + def decode(self, scope, token): + try: + if not token or len(token) > 1024: + raise ValueError + raw = base64.b64decode(token + "=" * (-len(token) % 4), altchars=b"-_", validate=True) + signature, payload = raw[:32], raw[32:] + if not hmac.compare_digest(signature, hmac.digest(self.key, payload, hashlib.sha256)): + raise ValueError + parts = json.loads(payload) + if not isinstance(parts, list) or len(parts) != 3 or parts[0] != scope: + raise ValueError + if not all(isinstance(x, str) for x in parts) or not parts[1].endswith("Z"): + raise ValueError + return datetime.fromisoformat(parts[1].replace("Z", "+00:00")), UUID(parts[2]) + except (ValueError, TypeError, UnicodeError): + raise invalid("Invalid cursor for this resource") from None diff --git a/app/store.py b/app/store.py new file mode 100644 index 00000000..0c307819 --- /dev/null +++ b/app/store.py @@ -0,0 +1,238 @@ +"""Persistent business data and durable Redis sessions; no local state cache.""" +import asyncio +from datetime import datetime, timezone +import hashlib +import json +import secrets +from uuid import UUID, uuid4 + +from psycopg.errors import ForeignKeyViolation, UniqueViolation +from psycopg.rows import dict_row +from psycopg_pool import AsyncConnectionPool +import redis.asyncio as redis +from redis.asyncio.retry import Retry +from redis.backoff import NoBackoff + +from .errors import APIError, invalid, unauthorized +from .security import Cursors, bearer, password_hash, password_matches, stamp + +USER_COLUMNS = "id, username, display_name, created_at" +MESSAGE_COLUMNS = "id, chat_id, sender_id, text, created_at, attachment_ids" + + +def public(row): + if "attachment_ids" in row: + row["attachment_ids"] = [str(x) for x in row["attachment_ids"]] + return {key: (str(value) if isinstance(value, UUID) else + stamp(value) if isinstance(value, datetime) else value) + for key, value in row.items()} + + +class Store: + def __init__(self, settings): + self.settings = settings + self.cursors = Cursors(settings.cursor_key) + self.kdf_slots = asyncio.Semaphore(4) + self.dummy_hash = password_hash("dummy-password-for-missing-user", b"0" * 16) + self.pool = AsyncConnectionPool( + settings.database_url, min_size=1, max_size=10, max_waiting=20, + timeout=1, open=False, reconnect_timeout=5, + check=AsyncConnectionPool.check_connection, + kwargs={"row_factory": dict_row, "connect_timeout": 2, + "keepalives": 1, "keepalives_idle": 2, "keepalives_interval": 1, + "keepalives_count": 2, "tcp_user_timeout": 2000, + "options": "-c timezone=UTC -c statement_timeout=2000 -c lock_timeout=1000"}) + self.sessions = redis.Redis.from_url( + settings.cache_url, decode_responses=True, max_connections=10, + socket_connect_timeout=1, socket_timeout=1, + retry=Retry(NoBackoff(), 0), retry_on_timeout=False) + + async def open(self): + await self.pool.open() + await self.pool.wait(timeout=10) + await self.sessions.ping() + + async def close(self): + await self.sessions.aclose() + await self.pool.close() + + async def ready(self): + async with self.pool.connection() as conn: + await conn.execute("SELECT 1") + await self.sessions.ping() + + async def create_user(self, data): + async with self.kdf_slots: + encoded = await asyncio.to_thread(password_hash, data.password) + try: + async with self.pool.connection() as conn: + cur = await conn.execute( + "INSERT INTO users(id, username, display_name, password_hash) " + "VALUES (%s, %s, %s, %s) RETURNING " + USER_COLUMNS, + (uuid4(), data.username, data.display_name, encoded)) + result = public(await cur.fetchone()) + return result + except UniqueViolation: + raise APIError(409, "conflict", "Username is already taken") from None + + async def login(self, username, password): + async with self.pool.connection() as conn: + cur = await conn.execute("SELECT " + USER_COLUMNS + ", password_hash FROM users WHERE username=%s", + (username,)) + row = await cur.fetchone() + async with self.kdf_slots: + valid = await asyncio.to_thread(password_matches, password, + row["password_hash"] if row else self.dummy_hash) + if not valid or row is None: + raise unauthorized(basic=True) + row.pop("password_hash") + token = secrets.token_urlsafe(32) + expires_ms = int(datetime.now(timezone.utc).timestamp() * 1000) + self.settings.session_ttl * 1000 + await self.sessions.set(self.session_key(token), json.dumps( + {"user_id": str(row["id"]), "expires_ms": expires_ms}), pxat=expires_ms) + return {"token": token, "token_type": "Bearer", + "expires_at": stamp(datetime.fromtimestamp(expires_ms / 1000, timezone.utc)), + "user": public(row)} + + @staticmethod + def session_key(token): + return "session:" + hashlib.sha256(token.encode("ascii")).hexdigest() + + async def authenticate(self, header): + token = bearer(header) + value = await self.sessions.get(self.session_key(token)) + if value is None: + raise unauthorized() + session = json.loads(value) + if session["expires_ms"] <= int(datetime.now(timezone.utc).timestamp() * 1000): + raise unauthorized() + async with self.pool.connection() as conn: + cur = await conn.execute("SELECT " + USER_COLUMNS + " FROM users WHERE id=%s", + (UUID(session["user_id"]),)) + row = await cur.fetchone() + if row is None: + raise unauthorized() + return public(row), token + + async def logout(self, token): + await self.sessions.delete(self.session_key(token)) + + async def create_chat(self, actor, data): + if actor not in data.member_ids: + raise invalid("Members must include the current user") + try: + async with self.pool.connection() as conn: + cur = await conn.execute("INSERT INTO chats(id, title) VALUES (%s, %s) " + "RETURNING id, title, created_at", (uuid4(), data.title)) + row = await cur.fetchone() + async with conn.cursor() as cur: + await cur.executemany("INSERT INTO chat_members(chat_id, user_id) VALUES (%s, %s)", + [(row["id"], UUID(member)) for member in data.member_ids]) + result = public(row) + result["member_ids"] = sorted(data.member_ids) + return result + except ForeignKeyViolation: + raise invalid("All members must exist") from None + + async def accessible_chat(self, conn, actor, chat_id): + cur = await conn.execute("""SELECT c.id, c.title, c.created_at FROM chats c + JOIN chat_members m ON m.chat_id=c.id + WHERE c.id=%s AND m.user_id=%s""", (chat_id, UUID(actor))) + row = await cur.fetchone() + if row is None: + raise APIError(404, "not_found", "Chat not found") + return row + + async def get_chat(self, actor, chat_id): + async with self.pool.connection() as conn: + row = await self.accessible_chat(conn, actor, chat_id) + cur = await conn.execute("SELECT user_id FROM chat_members WHERE chat_id=%s ORDER BY user_id", (chat_id,)) + result = public(row) + result["member_ids"] = [str(x["user_id"]) for x in await cur.fetchall()] + return result + + async def create_message(self, actor, chat_id, data, key): + fingerprint = hashlib.sha256(json.dumps({"text": data.text, "attachment_ids": data.attachment_ids}, + ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest() + async with self.pool.connection() as conn: + await self.accessible_chat(conn, actor, chat_id) + # Evaluate clock_timestamp AFTER obtaining the per-chat lock. + await conn.execute("SELECT id FROM chats WHERE id=%s FOR UPDATE", (chat_id,)) + # All replicas share this lock. Replay and side effect commit together. + await conn.execute("DELETE FROM message_requests WHERE user_id=%s AND chat_id=%s " + "AND request_key=%s AND expires_at <= clock_timestamp()", (UUID(actor), chat_id, key)) + replay = await conn.execute("SELECT request_hash, message_id FROM message_requests " + "WHERE user_id=%s AND chat_id=%s AND request_key=%s", (UUID(actor), chat_id, key)) + previous = await replay.fetchone() + if previous: + if previous["request_hash"] != fingerprint: + raise APIError(409, "conflict", "Idempotency key was used with a different message") + saved = await conn.execute("SELECT " + MESSAGE_COLUMNS + " FROM messages WHERE id=%s", + (previous["message_id"],)) + return public(await saved.fetchone()) + for attachment_id in data.attachment_ids: + found = await conn.execute("SELECT status FROM attachments WHERE id=%s AND chat_id=%s", + (UUID(attachment_id), chat_id)) + attachment = await found.fetchone() + if attachment is None: + raise APIError(404, "not_found", "Attachment not found") + if attachment["status"] not in ("ready", "queued", "processing"): + raise APIError(409, "conflict", "Attachment is not ready") + cur = await conn.execute("""UPDATE chats SET last_message_at= + greatest(clock_timestamp(), last_message_at + interval '1 microsecond') + WHERE id=%s RETURNING last_message_at""", (chat_id,)) + created_at = (await cur.fetchone())["last_message_at"] + cur = await conn.execute("INSERT INTO messages(id, chat_id, sender_id, text, created_at, attachment_ids) " + "VALUES (%s, %s, %s, %s, %s, %s) RETURNING " + MESSAGE_COLUMNS, + (uuid4(), chat_id, UUID(actor), data.text, created_at, [UUID(x) for x in data.attachment_ids])) + result = public(await cur.fetchone()) + await conn.execute("INSERT INTO message_requests " + "(user_id, chat_id, request_key, request_hash, message_id) VALUES (%s,%s,%s,%s,%s)", + (UUID(actor), chat_id, key, fingerprint, UUID(result["id"]))) + return result + + def page(self, rows, scope, limit): + items = rows[:limit] + return {"items": items, "next_cursor": self.cursors.encode(scope, items[-1]) + if len(rows) > limit else None} + + async def list_messages(self, actor, chat_id, limit, cursor): + scope = "messages:" + str(chat_id) + boundary = self.cursors.decode(scope, cursor) if cursor is not None else None + async with self.pool.connection() as conn: + await self.accessible_chat(conn, actor, chat_id) + query = "SELECT " + MESSAGE_COLUMNS + " FROM messages WHERE chat_id=%s" + params = [chat_id] + if boundary: + query += " AND (created_at, id) > (%s, %s)" + params.extend(boundary) + query += " ORDER BY created_at, id LIMIT %s" + params.append(limit + 1) + cur = await conn.execute(query, params) + rows = [public(row) for row in await cur.fetchall()] + return self.page(rows, scope, limit) + + async def list_chats(self, actor, limit, cursor): + scope = "chats:" + actor + boundary = self.cursors.decode(scope, cursor) if cursor is not None else None + query = """SELECT c.id, c.title, c.created_at FROM chats c + JOIN chat_members m ON m.chat_id=c.id WHERE m.user_id=%s""" + params = [UUID(actor)] + if boundary: + query += " AND (c.created_at, c.id) > (%s, %s)" + params.extend(boundary) + query += " ORDER BY c.created_at, c.id LIMIT %s" + params.append(limit + 1) + async with self.pool.connection() as conn: + cur = await conn.execute(query, params) + rows = [public(row) for row in await cur.fetchall()] + if rows: + ids = [UUID(row["id"]) for row in rows] + cur = await conn.execute("SELECT chat_id, user_id FROM chat_members WHERE chat_id=ANY(%s) ORDER BY user_id", + (ids,)) + members = {row["id"]: [] for row in rows} + for member in await cur.fetchall(): + members[str(member["chat_id"])].append(str(member["user_id"])) + for row in rows: + row["member_ids"] = members[row["id"]] + return self.page(rows, scope, limit) diff --git a/app/transform.py b/app/transform.py new file mode 100644 index 00000000..90030332 --- /dev/null +++ b/app/transform.py @@ -0,0 +1,35 @@ +"""Isolated decoder: parent enforces a wall-clock timeout, container bounds RAM.""" +import json +from pathlib import Path +import sys +from PIL import Image, ImageOps +from .attachments import validate_image + +def transform(source, mime, destination): + with open(source, 'rb') as file: + validate_image(file, mime) + with Image.open(file) as raw: + oriented = ImageOps.exif_transpose(raw).convert('RGBA') + image = Image.new('RGB', oriented.size, 'white') + image.paste(oriented, mask=oriented.getchannel('A')) + variants = [] + for name, bound, fmt in [('thumbnail',256,'JPEG'),('crop',128,'JPEG'),('optimized',1280,'WEBP')]: + if name == 'crop': + out = ImageOps.fit(image, (128,128), method=Image.Resampling.LANCZOS, centering=(.5,.5)) + else: + w,h = image.size + ratio = min(1, bound/w, bound/h) + out = image.resize((max(1,int(w*ratio)),max(1,int(h*ratio))), Image.Resampling.LANCZOS) + # New RGB image removes EXIF, ICC and text metadata. + clean = Image.new('RGB', out.size) + clean.paste(out) + clean.save(Path(destination)/name, format=fmt, quality=85 if fmt=='JPEG' else 80) + variants.append({'name':name,'width':out.width,'height':out.height, + 'content_type':'image/jpeg' if fmt=='JPEG' else 'image/webp'}) + return variants + +if __name__ == '__main__': + try: + print(json.dumps(transform(*sys.argv[1:]))) + except Exception: + sys.exit(2) diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..79c71f53 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,213 @@ +name: mtusi-lab5 + +x-app: &app + image: mtusi-messenger:lab5 + build: {context: ., target: runtime} + environment: &environment + APP_HOST: 0.0.0.0 + APP_PORT: "8080" + APP_ENV: ${APP_ENV:-lab} + APP_VERSION: ${APP_VERSION:-lab5-v1} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + MAX_ATTEMPTS: ${MAX_ATTEMPTS:-5} + SESSION_STORE: redis + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + CURSOR_KEY_FILE: /run/secrets/cursor_key + secrets: [database_url, cache_url, cursor_key, s3_secret_key] + networks: [data] + cpus: 1.0 + mem_limit: 512m + stop_grace_period: 8s + +services: + postgres: + image: postgres:17.6-bookworm + environment: + POSTGRES_USER: messenger + POSTGRES_DB: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: [postgres_password] + volumes: [postgres_data:/var/lib/postgresql/data] + networks: [data] + healthcheck: + test: [CMD-SHELL, "pg_isready -U messenger -d messenger"] + interval: 2s + timeout: 2s + retries: 30 + cpus: 1.0 + mem_limit: 512m + stop_grace_period: 10s + + redis: + image: redis:7.4.5-bookworm + command: [sh, -ec, 'exec redis-server /usr/local/etc/redis/redis.conf --requirepass "$$(cat /run/secrets/redis_password)"'] + secrets: [redis_password] + volumes: + - redis_data:/data + - ./infra/redis.conf:/usr/local/etc/redis/redis.conf:ro + networks: [data] + healthcheck: + test: [CMD-SHELL, 'REDISCLI_AUTH="$$(cat /run/secrets/redis_password)" redis-cli ping | grep -q PONG'] + interval: 2s + timeout: 2s + retries: 30 + cpus: 0.5 + mem_limit: 192m + stop_grace_period: 10s + + migrate: + <<: *app + command: [python, -m, app.migrate] + depends_on: + postgres: {condition: service_healthy} + restart: "no" + + api: + <<: *app + deploy: + replicas: ${API_REPLICAS:-2} + depends_on: + migrate: {condition: service_completed_successfully} + redis: {condition: service_healthy} + bucket-init: {condition: service_completed_successfully} + networks: [edge, data] + + minio: + image: mtusi-minio:2025-09-07 + build: ./infra/s3 + command: [server, /data, --console-address, "127.0.0.1:9001"] + environment: + MINIO_ROOT_USER: lab-admin + MINIO_ROOT_PASSWORD_FILE: /run/secrets/s3_root_password + secrets: [s3_root_password] + volumes: [s3_data:/data] + networks: [data] + cpus: 1.0 + mem_limit: 512m + healthcheck: + test: [CMD-SHELL, "mc alias set health http://127.0.0.1:9000 lab-admin $$(cat /run/secrets/s3_root_password) >/dev/null && mc ready health"] + interval: 2s + timeout: 2s + retries: 30 + + bucket-init: + image: mtusi-minio:2025-09-07 + build: ./infra/s3 + entrypoint: [/bin/sh, /bootstrap/bootstrap.sh] + secrets: [s3_root_password, s3_secret_key] + volumes: [./infra/s3:/bootstrap:ro] + networks: [data] + depends_on: + minio: {condition: service_healthy} + mem_limit: 128m + restart: "no" + + cleanup: + <<: *app + command: [python, -m, app.attachments] + healthcheck: + test: [CMD, python, -c, "import os; os.kill(1, 0)"] + interval: 5s + timeout: 2s + retries: 3 + depends_on: + migrate: {condition: service_completed_successfully} + redis: {condition: service_healthy} + bucket-init: {condition: service_completed_successfully} + restart: unless-stopped + + broker: + image: redis:7.4.5-bookworm + command: [sh, -ec, 'exec redis-server /usr/local/etc/redis/redis.conf --requirepass "$$(cat /run/secrets/redis_password)"'] + secrets: [redis_password] + volumes: [broker_data:/data, ./infra/redis.conf:/usr/local/etc/redis/redis.conf:ro] + networks: [data] + mem_limit: 192m + healthcheck: + test: [CMD-SHELL, 'REDISCLI_AUTH="$$(cat /run/secrets/redis_password)" redis-cli ping | grep -q PONG'] + interval: 2s + timeout: 2s + retries: 30 + + publisher: + <<: *app + command: [python, -m, app.pipeline, publisher] + healthcheck: + test: [CMD, python, -c, "import time,pathlib; assert time.time()-pathlib.Path('/tmp/pipeline_alive').stat().st_mtime<120"] + interval: 5s + timeout: 2s + retries: 5 + restart: unless-stopped + depends_on: + migrate: {condition: service_completed_successfully} + broker: {condition: service_healthy} + bucket-init: {condition: service_completed_successfully} + + worker: + <<: *app + command: [python, -m, app.pipeline, worker] + healthcheck: + test: [CMD, python, -c, "import time,pathlib; assert time.time()-pathlib.Path('/tmp/pipeline_alive').stat().st_mtime<120"] + interval: 5s + timeout: 2s + retries: 5 + restart: unless-stopped + depends_on: + migrate: {condition: service_completed_successfully} + broker: {condition: service_healthy} + bucket-init: {condition: service_completed_successfully} + + lb: + image: haproxy:3.0.12-alpine + volumes: + - ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro + ports: + - "127.0.0.1:${API_PORT:-8085}:8080" + networks: [edge] + depends_on: + api: {condition: service_healthy} + cpus: 0.5 + mem_limit: 128m + stop_grace_period: 8s + healthcheck: + test: [CMD, wget, -q, -O, /dev/null, "http://127.0.0.1:8080/health/ready"] + interval: 2s + timeout: 2s + retries: 30 + + checks: + profiles: [tools] + image: mtusi-messenger:lab5-checks + build: {context: ., target: checks} + environment: + <<: *environment + BASE_URL: http://lb:8080 + COMPOSE_PROJECT_NAME: ${COMPOSE_PROJECT_NAME:-mtusi-lab5} + secrets: [database_url, cache_url, cursor_key, s3_secret_key] + volumes: + - .:/checks + - /var/run/docker.sock:/var/run/docker.sock + networks: [edge, data] + cpus: 1.0 + mem_limit: 512m + +networks: + edge: + data: + internal: true + +volumes: + postgres_data: + redis_data: + s3_data: + broker_data: + +secrets: + postgres_password: {file: ./secrets/postgres_password} + redis_password: {file: ./secrets/redis_password} + database_url: {file: ./secrets/database_url} + cache_url: {file: ./secrets/cache_url} + cursor_key: {file: ./secrets/cursor_key} + s3_root_password: {file: ./secrets/s3_root_password} + s3_secret_key: {file: ./secrets/s3_secret_key} diff --git a/docs/REVIEW.docx b/docs/REVIEW.docx new file mode 100644 index 0000000000000000000000000000000000000000..6c6c99b73d9e27e1d1dc145296179d56af675384 GIT binary patch literal 43681 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/dev/null +mc mb --ignore-existing local/attachments +mc anonymous set none local/attachments +mc admin user add local messenger-api "$(cat /run/secrets/s3_secret_key)" >/dev/null +mc admin policy create local messenger-api /bootstrap/api-policy.json +mc admin policy attach local messenger-api --user messenger-api diff --git a/migrations/001_initial.sql b/migrations/001_initial.sql new file mode 100644 index 00000000..244f2d4b --- /dev/null +++ b/migrations/001_initial.sql @@ -0,0 +1,32 @@ +CREATE TABLE users ( + id uuid PRIMARY KEY, + username text NOT NULL UNIQUE CHECK (username ~ '^[a-z0-9_]{3,32}$'), + display_name text NOT NULL CHECK (char_length(display_name) BETWEEN 1 AND 100), + password_hash text NOT NULL, + created_at timestamptz NOT NULL DEFAULT clock_timestamp() +); + +CREATE TABLE chats ( + id uuid PRIMARY KEY, + title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100), + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + last_message_at timestamptz NOT NULL DEFAULT '-infinity' +); + +CREATE TABLE chat_members ( + chat_id uuid NOT NULL REFERENCES chats(id), + user_id uuid NOT NULL REFERENCES users(id), + PRIMARY KEY (chat_id, user_id) +); +CREATE INDEX chat_members_user_chat_idx ON chat_members(user_id, chat_id); +CREATE INDEX chats_created_id_idx ON chats(created_at, id); + +CREATE TABLE messages ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL REFERENCES chats(id), + sender_id uuid NOT NULL, + text text NOT NULL CHECK (char_length(text) BETWEEN 1 AND 4000), + created_at timestamptz NOT NULL, + FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members(chat_id, user_id) +); +CREATE INDEX messages_chat_created_id_idx ON messages(chat_id, created_at, id); diff --git a/migrations/002_message_requests.sql b/migrations/002_message_requests.sql new file mode 100644 index 00000000..b9077177 --- /dev/null +++ b/migrations/002_message_requests.sql @@ -0,0 +1,11 @@ +CREATE TABLE message_requests ( + user_id uuid NOT NULL REFERENCES users(id), + chat_id uuid NOT NULL REFERENCES chats(id), + request_key varchar(128) NOT NULL, + request_hash char(64) NOT NULL, + message_id uuid NOT NULL REFERENCES messages(id), + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + expires_at timestamptz NOT NULL DEFAULT (clock_timestamp() + interval '24 hours'), + PRIMARY KEY (user_id, chat_id, request_key) +); +CREATE INDEX message_requests_expiry_idx ON message_requests(expires_at); diff --git a/migrations/003_attachments.sql b/migrations/003_attachments.sql new file mode 100644 index 00000000..6025e308 --- /dev/null +++ b/migrations/003_attachments.sql @@ -0,0 +1,11 @@ +ALTER TABLE messages DROP CONSTRAINT messages_text_check; +ALTER TABLE messages ADD CONSTRAINT messages_text_check CHECK (char_length(text) <= 4000); +ALTER TABLE messages ADD COLUMN attachment_ids uuid[] NOT NULL DEFAULT '{}'; +CREATE TABLE attachments ( + id uuid PRIMARY KEY, chat_id uuid NOT NULL REFERENCES chats(id), + uploader_id uuid NOT NULL REFERENCES users(id), object_key text UNIQUE NOT NULL, + filename text NOT NULL, content_type text NOT NULL, size_bytes bigint NOT NULL, + sha256 text NOT NULL, status text NOT NULL CHECK(status IN ('pending','ready')), + created_at timestamptz NOT NULL DEFAULT clock_timestamp() +); +CREATE INDEX attachments_pending_idx ON attachments(created_at) WHERE status='pending'; diff --git a/migrations/004_jobs.sql b/migrations/004_jobs.sql new file mode 100644 index 00000000..6f8e761c --- /dev/null +++ b/migrations/004_jobs.sql @@ -0,0 +1,17 @@ +ALTER TABLE attachments DROP CONSTRAINT attachments_status_check; +ALTER TABLE attachments ADD CONSTRAINT attachments_status_check CHECK(status IN ('pending','queued','processing','ready','failed')); +ALTER TABLE attachments ADD COLUMN updated_at timestamptz NOT NULL DEFAULT clock_timestamp(); +ALTER TABLE attachments ADD COLUMN variants jsonb NOT NULL DEFAULT '[]'; +ALTER TABLE attachments ADD COLUMN error_code text; +ALTER TABLE attachments ADD COLUMN staging_cleaned boolean NOT NULL DEFAULT false; +CREATE TABLE jobs ( + id uuid PRIMARY KEY, attachment_id uuid UNIQUE NOT NULL REFERENCES attachments(id), + pipeline_version int NOT NULL DEFAULT 1 CHECK(pipeline_version=1), + attempts int NOT NULL DEFAULT 0, state text NOT NULL DEFAULT 'queued', + available_at timestamptz NOT NULL DEFAULT clock_timestamp(), lease_until timestamptz, + last_published timestamptz, created_at timestamptz NOT NULL DEFAULT clock_timestamp() +); +CREATE TABLE replay_audit ( + id bigserial PRIMARY KEY, job_id uuid NOT NULL REFERENCES jobs(id), + reason text NOT NULL, created_at timestamptz NOT NULL DEFAULT clock_timestamp() +); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..8e6bcda4 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,19 @@ +annotated-doc==0.0.5 +annotated-types==0.8.0 +anyio==4.15.1 +click==8.5.0 +colorama==0.4.6; sys_platform == 'win32' +fastapi==0.141.1 +h11==0.16.0 +idna==3.20 +pydantic==2.13.5 +pydantic-core==2.46.5 +starlette==1.6.0 +typing-extensions==4.16.0 +typing-inspection==0.4.4 +uvicorn==0.53.0 +psycopg[binary]==3.2.10 +psycopg-pool==3.2.6 +redis==6.4.0 +boto3==1.40.61 +Pillow==12.0.0 diff --git a/scripts/init_local.py b/scripts/init_local.py new file mode 100644 index 00000000..e88e74e5 --- /dev/null +++ b/scripts/init_local.py @@ -0,0 +1,35 @@ +"""Create local synthetic credentials once without printing secret values.""" +from pathlib import Path +import secrets + +ROOT = Path(__file__).resolve().parents[1] + + +def main(): + directory = ROOT / "secrets" + directory.mkdir(exist_ok=True) + for name in ("postgres_password", "redis_password", "cursor_key", "s3_root_password", "s3_secret_key"): + path = directory / name + if not path.exists(): + path.write_text(secrets.token_hex(32) + "\n", encoding="utf-8", newline="\n") + else: + # Shell command substitution on Linux must not retain a Windows CR. + value = path.read_text(encoding="utf-8").strip() + path.write_text(value + "\n", encoding="utf-8", newline="\n") + pg_password = (directory / "postgres_password").read_text().strip() + redis_password = (directory / "redis_password").read_text().strip() + for name, value in { + "database_url": f"postgresql://messenger:{pg_password}@postgres:5432/messenger", + "cache_url": f"redis://:{redis_password}@redis:6379/0", + }.items(): + path = directory / name + if not path.exists(): + path.write_text(value + "\n", encoding="utf-8", newline="\n") + env = ROOT / ".env" + if not env.exists(): + env.write_bytes((ROOT / ".env.example").read_bytes()) + print("PASS: local .env and secret files exist; existing values preserved") + + +if __name__ == "__main__": + main() diff --git a/scripts/ops.py b/scripts/ops.py new file mode 100644 index 00000000..bfb87e95 --- /dev/null +++ b/scripts/ops.py @@ -0,0 +1,94 @@ +"""Docker operations scoped to the configured local Compose project.""" +import csv +import io +import json +import os +from pathlib import Path +import socket +import subprocess +import time + +ROOT = Path(__file__).resolve().parents[1] + + +def command(args, timeout=120, env=None): + result = subprocess.run(args, cwd=ROOT, capture_output=True, text=True, + encoding="utf-8", errors="replace", timeout=timeout, env=env) + if result.returncode: + # Commands and stderr can contain secrets. Keep detailed errors local. + raise RuntimeError("Local command failed: " + " ".join(args[:3]) + "\n" + result.stderr[-1500:]) + return result.stdout.strip() + + +def compose(*args, timeout=120, env=None): + return command(["docker", "compose", "--env-file", ".env", *args], timeout, env) + + +def project(): + return os.getenv("COMPOSE_PROJECT_NAME") or json.loads(compose("config", "--format", "json"))["name"] + + +def containers(service="api", running=True): + args = ["docker", "ps"] + ([] if running else ["-a"]) + ids = command(args + ["--filter", "label=com.docker.compose.project=" + project(), + "--filter", "label=com.docker.compose.service=" + service, + "--filter", "label=com.docker.compose.oneoff=False", "--format", "{{.ID}}"]) + return json.loads(command(["docker", "inspect", *ids.split()])) if ids else [] + + +def summary(): + result = [] + for service in ("api", "postgres", "redis", "broker", "worker", "publisher", "minio", "lb"): + for row in containers(service, running=False): + result.append({"service": service, "id": row["Id"], "name": row["Name"].lstrip("/"), + "started_at": row["State"]["StartedAt"], "status": row["State"]["Status"], + "image": row["Image"], "user": row["Config"]["User"], + "memory_bytes": row["HostConfig"]["Memory"], "nano_cpus": row["HostConfig"]["NanoCpus"], + "published_ports": row["HostConfig"]["PortBindings"], + "volumes": [m["Name"] for m in row["Mounts"] if m["Type"] == "volume"]}) + return result + + +def runtime(line): + with socket.create_connection(("lb", 9999), timeout=3) as sock: + sock.sendall((line + "\n").encode()) + sock.shutdown(socket.SHUT_WR) + chunks = [] + while True: + data = sock.recv(65536) + if not data: + return b"".join(chunks).decode() + chunks.append(data) + + +def drain(address): + lines = runtime("show servers state messenger").splitlines() + fields = next(line[2:].split() for line in lines if line.startswith("# ")) + for line in lines: + values = line.split() + if not values or line.startswith("#") or len(values) != len(fields): + continue + row = dict(zip(fields, values)) + if row["srv_addr"] == address: + slot = "messenger/" + row["srv_name"] + runtime("set server " + slot + " state drain") + # Let requests already assigned to this replica finish (HTTP budget 5 s). + deadline = time.monotonic() + 7 + while time.monotonic() < deadline: + stats = list(csv.DictReader(io.StringIO(runtime("show stat").lstrip("# ")))) + active = [s for s in stats if s["pxname"] == "messenger" and s["svname"] == row["srv_name"]] + if active and int(active[0]["scur"]) == 0: + return slot + time.sleep(.1) + raise RuntimeError("Replica did not drain within 7 seconds") + raise RuntimeError("Backend address was not found in HAProxy") + + +if __name__ == "__main__": + import sys + if sys.argv[1] == "drain": + print(drain(sys.argv[2])) + elif sys.argv[1] == "ready": + runtime("set server " + sys.argv[2] + " state ready") + elif sys.argv[1] == "summary": + print(json.dumps(summary(), indent=2)) diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..070d8f2d --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,4 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +docker compose --env-file .env restart --timeout 6 api postgres redis broker minio lb worker publisher diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..b6eb8210 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,4 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +exec python scripts/stop_one.py diff --git a/scripts/stop_one.py b/scripts/stop_one.py new file mode 100644 index 00000000..4a61accc --- /dev/null +++ b/scripts/stop_one.py @@ -0,0 +1,24 @@ +"""Stop exactly the replica selected by the public failover scenario.""" +import json +import os +import time +from ops import ROOT, command, containers + + +def main(): + target = os.environ["TARGET_INSTANCE_ID"] + matches = [row for row in containers() if target.startswith(row["Config"]["Hostname"] + "-")] + if len(matches) != 1: + raise RuntimeError("Target does not identify exactly one running API replica") + row = matches[0] + started = time.monotonic() + command(["docker", "stop", "--time", "6", row["Id"]], timeout=9) + state = json.loads(command(["docker", "inspect", row["Id"]]))[0]["State"] + assert not state["Running"] and state["ExitCode"] == 0, "Graceful shutdown failed" + report = {"target_instance": target, "container": row["Id"], "exit_code": state["ExitCode"], + "stop_seconds": round(time.monotonic() - started, 3), "remains_stopped": True} + (ROOT / "evidence" / "last-stop.json").write_text(json.dumps(report, indent=2) + "\n") + + +if __name__ == "__main__": + main() diff --git a/scripts/verify.py b/scripts/verify.py new file mode 100644 index 00000000..5c692ce6 --- /dev/null +++ b/scripts/verify.py @@ -0,0 +1,33 @@ +"""Explicit local verification with sanitized logs; never deletes volumes.""" +import json +from pathlib import Path +import subprocess +import sys +import time + +ROOT=Path(__file__).resolve().parents[1] +EVIDENCE=ROOT/'evidence' +def run(name,args): + start=time.monotonic() + result=subprocess.run(['docker','compose','--env-file','.env',*args],cwd=ROOT, + stdout=subprocess.PIPE,stderr=subprocess.STDOUT,text=True,encoding='utf-8',errors='replace') + (EVIDENCE/name).write_text(result.stdout,encoding='utf-8') + if result.returncode:raise RuntimeError(name+' failed; inspect evidence') + print('PASS',name,flush=True) + return round(time.monotonic()-start,3) +def main(): + EVIDENCE.mkdir(exist_ok=True) + results={} + if '--build' in sys.argv:run('build.txt',['build','api','checks']) + run('startup.txt',['up','-d','--no-build','--wait','--wait-timeout','180']) + results['public']=run('smoke.txt',['run','--rm','--no-deps','checks','make','check','test']) + results['images']=run('images.txt',['run','--rm','--no-deps','-e','PYTHONPATH=/app','checks','python','-m','unittest','discover','-s','student-tests','-p','test_images.py','-v']) + results['pipeline']=run('pipeline.txt',['run','--rm','--no-deps','-e','PYTHONPATH=/app','checks','python','student-tests/pipeline_checks.py']) + run('before-restart.json',['run','--rm','--no-deps','checks','python','scripts/ops.py','summary']) + results['persistence']=run('persistence.txt',['run','--rm','--no-deps','checks','sh','-ec','chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh']) + run('after-restart.json',['run','--rm','--no-deps','checks','python','scripts/ops.py','summary']) + results['failover']=run('failover.txt',['run','--rm','--no-deps','checks','sh','-ec','chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh']) + run('restore.txt',['start','api']) + results['final_smoke']=run('smoke-final.txt',['run','--rm','--no-deps','checks','make','test']) + (EVIDENCE/'verification.json').write_text(json.dumps({'date':'2026-11-21','seconds':results,'result':'PASS'},indent=2)) +if __name__=='__main__':main() diff --git a/start.ps1 b/start.ps1 new file mode 100644 index 00000000..11b9f9a2 --- /dev/null +++ b/start.ps1 @@ -0,0 +1,13 @@ +$ErrorActionPreference = 'Stop' +Set-Location -LiteralPath $PSScriptRoot +docker info --format '{{.ServerVersion}}' +if ($LASTEXITCODE -ne 0) { throw 'Start Docker Desktop first.' } +docker run --rm --mount "type=bind,source=$PSScriptRoot,target=/work" --workdir /work python:3.13.15-slim-bookworm python scripts/init_local.py +if ($LASTEXITCODE -ne 0) { throw 'Local configuration initialization failed.' } +docker compose --env-file .env build api checks minio +if ($LASTEXITCODE -ne 0) { throw 'Image build failed.' } +docker compose --env-file .env up -d --no-build --wait --wait-timeout 180 +if ($LASTEXITCODE -ne 0) { throw 'Stack startup failed; inspect docker compose logs.' } +$taskConfig = docker compose --env-file .env config --format json | ConvertFrom-Json +$taskPort = $taskConfig.services.lb.ports[0].published +Write-Host "Ready: http://127.0.0.1:$taskPort/health/ready" diff --git a/student-tests/pipeline_checks.py b/student-tests/pipeline_checks.py new file mode 100644 index 00000000..0784f28b --- /dev/null +++ b/student-tests/pipeline_checks.py @@ -0,0 +1,136 @@ +"""Explicit fault injection against this lab's disposable Compose project.""" +import asyncio +import hashlib +from io import BytesIO +import json +from pathlib import Path +import subprocess +import sys +import time +from uuid import UUID +sys.path.insert(0,str(Path(__file__).resolve().parents[1]/'tests')) +from client import Client +from PIL import Image +import psycopg +from psycopg.rows import dict_row +from app.pipeline import broker +from app.attachments import client as s3client + +ROOT=Path(__file__).resolve().parents[1] +results=[] +def dc(*args): + subprocess.run(['docker','compose','--env-file','.env',*args],cwd=ROOT,check=True,stdout=subprocess.DEVNULL) +def sql(query,params=(),one=True): + with psycopg.connect(Path('/run/secrets/database_url').read_text().strip(),row_factory=dict_row) as conn: + cur=conn.execute(query,params) + return cur.fetchone() if cur.description and one else cur.fetchall() if cur.description else None +def record(name,**data): + results.append(dict(test=name,result='PASS',**data)) + (ROOT/'evidence/pipeline.json').write_text(json.dumps(results,indent=2)) + print('PASS:',name,flush=True) + +c=Client(); a,b,e,chat=c.bootstrap(); s3=s3client() +def meta(att):return c.call('GET','/api/v1/attachments/'+att['id'],actor=a,schema='Attachment')['json'] +def upload():return c.attachment(a,chat) +def job(att):return sql('SELECT * FROM jobs WHERE attachment_id=%s',(UUID(att['id']),)) +def wait_state(att,state,seconds=120): + end=time.monotonic()+seconds + while time.monotonic()0 + dc('restart','api','broker') + dc('start','worker') + ready=variants(att) + assert c.call('GET','/api/v1/attachments/'+att['id']+'/content',actor=b)['bytes']==original + record('stopped worker and API broker restart',attachment_id=att['id'],queued_messages=before) + + dc('stop','publisher') + att,_=upload() + assert job(att)['last_published'] is None + # API is killed after queued+job COMMIT, before any publisher can execute. + dc('kill','api'); dc('start','api'); dc('start','publisher') + variants(att) + record('crash between COMMIT and publish',attachment_id=att['id']) + + dc('stop','worker') + # Start worker with one-shot marker inserted while it is running, before upload. + dc('start','worker');dc('exec','-T','worker','touch','/tmp/crash_after_object') + att,_=upload() + ready=variants(att) + assert job(att)['attempts']>=2 + original_attempts=job(att)['attempts'] + payload=dict(schema_version=1,job_id=str(job(att)['id']),type='attachment.process.v1',attachment_id=att['id'],pipeline_version=1,attempt=1,created_at=att['created_at']) + async def duplicate(): + q=broker() + for _ in range(3):await q.xadd('images.v1',{'payload':json.dumps(payload)}) + await q.aclose() + asyncio.run(duplicate());time.sleep(3) + assert meta(att)['variants']==ready['variants'] and job(att)['attempts']==original_attempts + listing=s3.list_objects_v2(Bucket='attachments',Prefix='variants/'+UUID(att['id']).hex+'/v1/') + assert listing['KeyCount']==3 + record('crash after S3 write and duplicate delivery',attachment_id=att['id'],attempts=original_attempts,variant_objects=3) + + dc('stop','worker'); att,_=upload() + # Trusted-storage corruption emulates permanent input failure after acceptance. + s3.put_object(Bucket='attachments',Key='staging/'+UUID(att['id']).hex,Body=b'broken') + dc('start','worker');failed=wait_state(att,'failed') + assert failed['error_code']=='invalid_image' + c.call('GET','/api/v1/attachments/'+att['id']+'/content',409,actor=a) + s3.put_object(Bucket='attachments',Key='staging/'+UUID(att['id']).hex,Body=original,ContentType='image/png') + dc('exec','-T','worker','python','-m','app.pipeline','replay',str(job(att)['id']),'restored staging for lab fault test') + variants(att) + assert sql('SELECT count(*) AS n FROM replay_audit WHERE job_id=%s',(job(att)['id'],))['n']==1 + record('permanent failure registry and audited replay',attachment_id=att['id']) + + dc('stop','worker'); att,_=upload() + worker_id=subprocess.check_output(['docker','compose','ps','-aq','worker'],cwd=ROOT,text=True).strip() + dc('stop','minio') + # docker start intentionally avoids Compose restarting the stopped dependency. + subprocess.run(['docker','start',worker_id],check=True,stdout=subprocess.DEVNULL) + # S3 outage intentionally makes API readiness fail, so HAProxy may return 503. + # Observe the durable job directly until storage and routing are restored. + deadline=time.monotonic()+150 + while job(att)['state']!='failed' and time.monotonic() Date: Sat, 21 Nov 2026 12:01:33 +0300 Subject: [PATCH 2/2] Record published lab 5 PR and verified source commit --- docs/SUBMISSION.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/SUBMISSION.md b/docs/SUBMISSION.md index 80b0f258..5c7e78b4 100644 --- a/docs/SUBMISSION.md +++ b/docs/SUBMISSION.md @@ -1,17 +1,13 @@ -# Материалы для сдачи +# Публикация лабораторной 5 -Автор — Саламатин, БПИ-2304. Целевая оценка — 4. Ветка — solution/bpi-2304-salamatin. +Решение опубликовано в [gwalut/mtusi2026lab5](https://gitea.privcloud.tech/gwalut/mtusi2026lab5), ветка `solution/bpi-2304-salamatin`. Открыт [PR №112](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab5/pulls/112) в `mtusi2026/mtusi2026lab5:main`. -Заголовок PR: **ЛР 5 — БПИ-2304 — Саламатин — на 4** +Заголовок: **ЛР 5 — БПИ-2304 — Саламатин — на 4**. Автор — Саламатин, БПИ-2304. Целевая оценка — 4, включая минимум на 3. Треки на 5 не выполнялись. -## Описание для PR +API принимает исходник в устойчивый staging MinIO и фиксирует задание в PostgreSQL до ответа 202. Отдельные publisher, Redis Streams и worker обеспечивают доставку и обработку. Создаются thumbnail, crop и optimized WebP. Реализованы outbox, ограниченные повторы, lease, реестр failed и replay с аудитом. -Перенёс обработку вложений в отдельный worker. API возвращает 202 после сохранения исходника в staging MinIO и записи задания в PostgreSQL. Publisher передаёт задания в отдельный Redis Streams с AOF; transactional outbox восстанавливает отправку после сбоя между COMMIT и publish. +Публичный smoke, два теста изображений, сценарии сбоев pipeline, persistence и failover прошли 21 ноября 2026 года. Команды, результаты и ограничения находятся в REPORT.md и evidence/. Понятное объяснение и сценарий защиты — docs/REVIEW.docx. -Worker сохраняет оригинал без изменений, JPEG thumbnail, центральный crop и WebP. Добавлены конечные состояния, пять попыток с backoff и jitter, lease, реестр failed и replay с аудитом. Повторы используют те же ключи результата, готовая работа повторно не обрабатывается. Staging удаляется после безопасного завершения; failed-исходники доступны для replay семь дней. +Проверенный локальный коммит — `8aab4ad`. Публикация выполнена через применение Git binary patch в веб-интерфейсе: коммит реализации на сервере — `790911092460f332d1b6b7de546dc96a452613d6`. Перед созданием PR подтверждено полное совпадение деревьев файлов. Последующие изменения этой памятки относятся только к документации. -Публичный контракт и tests сохранены. Команды запуска, методика и результаты проверок находятся в REPORT.md и evidence/. Понятный разбор и сценарий защиты — docs/REVIEW.docx. Использованы собственные исходники lab4, FastAPI, PostgreSQL, Redis, MinIO, Pillow и помощь Codex. Треки на 5 не выполнялись. - -## Статус публикации - -Материалы подготовлены локально. Fork и PR этой лабораторной не созданы: Gitea API возвращает 401 для сохранённых Git credentials. После восстановления доступа нужно создать fork mtusi2026/mtusi2026lab5 в своём аккаунте, добавить его как origin, отправить ветку и открыть PR в исходный main. Секреты и .env исключены из Git. +Секреты, .env и Docker volumes в публикацию не включены. README задания, контракт и публичные tests сохранены. Право сопровождающих редактировать ветку отключено. PR открыт для проверки, слияние не выполнялось. -- 2.54.0