Files
mtusi2026lab3/src/AGENTS.md
T

17 KiB
Raw Blame History

src/ — устройство приложения

Дополняет корневой AGENTS.md. Правила конкретных слоёв — в api/AGENTS.md, services/AGENTS.md, storage/AGENTS.md.

Слои и направление зависимостей

api/ (routes, deps, identity, request_id, handlers, schemas)
  ↓
services/ (UserService, SessionService, ChatService, MessageService, access.py)
  ↓
storage/ (Storage Protocol → CachedStorage → PostgresStorage)

Общие модули нижнего уровня: domain.py, errors.py, pagination.py, clock.py, constants.py, log.py, config.py. Инфраструктура — тоже общие модули: db.py (PostgreSQL), cache.py (Valkey), passwords.py (Argon2id). В них нет бизнес-правил.

Модуль Может импортировать Не может импортировать
api/* services, storage (только тип Storage), общие модули, fastapi/starlette storage.postgres, storage.cached, db, cache (их собирает main.py)
services/* storage.Storage, passwords, общие модули api/*, db, cache, fastapi, starlette, pydantic, sqlalchemy
storage/* domain, errors, pagination, clock, constants, db, cache, sqlalchemy api/*, services/*, fastapi, log
db, cache, passwords config, constants, errors, log, свой драйвер api/*, services/*, storage/*
domain, clock, constants только стандартную библиотеку всё остальное из src
errors constants остальное
pagination domain, errors остальное
main.py всё: он собирает приложение —
healthcheck.py только стандартную библиотеку src.* (проверка должна быть дешёвой)
early_stop.py только стандартную библиотеку src.*: работает до импорта приложения и настройки журнала

Цикл импортов или импорт «вверх» — признак, что код лежит не в том слое. migrations/env.py импортирует config, db.database_url, log и storage.tables — и ничего, что создаёт engine при импорте.

Кто за что отвечает

  • Роут: принять запрос (pydantic-модель, параметры пути и query), взять сессию и сервис из зависимостей, вызвать сервис именованными аргументами, превратить доменный объект в модель ответа. Бизнес-правил нет.
  • Сервис: правила контракта, которые не выражаются схемой (дубликаты участников, вызывающий в чате, членство, курсор), пароль и сессия, вызов хранилища, логи бизнес-событий.
  • Хранилище: атомарная операция над данными — одна транзакция PostgreSQL; назначение id и created_at; уникальность и внешние ключи; перевод сработавшего ограничения в доменную ошибку. Кэш — обёртка CachedStorage над тем же интерфейсом.
  • Инфраструктура: пул, сроки, обход отказов, журнал отказов. Отказ PostgreSQL → Unavailable (503) в db.py; отказ Valkey → промах в cache.py.

Ошибки (errors.py)

  • У каждого класса свои status_code, code, default_message и, у 401, challenge (значение WWW-Authenticate). Перевод в ответ — один обработчик api/handlers.py (app_error_response), его же зовёт AuthenticationMiddleware через identity.on_auth_error.
  • Новая ошибка: наследник подходящего класса (InvalidRequest → 400, NotFound → 404, ...), code — только из enum Error.code в contracts/openapi.json. Текст — английский, без id, путей, имён классов, SQL и признаков существования чужого объекта.
  • Нет чата и чат чужой — одно и то же NotFound.
  • Тот же Idempotency-Key с другим телом — IdempotencyConflict (409 conflict); нет ключа или он не по шаблону — 400 из валидации заголовка ручки. Ключ в текст ошибки не попадает.
  • Вход: InvalidCredentials (вызов Basic) — одна ошибка на неверный пароль, неизвестный username и битый Basic. Остальное: Unauthorized (вызов Bearer). Недоступность хранилища — Unavailable (503), никогда не 401.

Время (clock.py)

  • created_at назначает MonotonicClock внутри хранилища, перед вставкой: строго возрастающее aware-время UTC с шагом ≥ 1 мкс внутри процесса. С лабы 3 процессов несколько (реплики): между репликами монотонности нет, порядок задают часы ВМ Docker (у реплик одного хоста общие) и id при равенстве. Транзакции фиксируются не в порядке времени: запись с меньшим created_at может стать видимой позже соседней (REPORT.md, «Пагинация»).
  • Срок сессии сравнивается с utc_now() — без монотонной поправки.
  • Наружу — только to_rfc3339(): 2026-09-01T12:00:00.000000Z; обратно (значение из кэша) — from_rfc3339(). datetime.now() без UTC и isoformat() в ответах не использовать: smoke требует суффикс Z.

Пагинация (pagination.py)

  • Порядок (created_at, id) по возрастанию; sort_key() — единственное место, где он задан в Python; в SQL — ORDER BY created_at, id и сравнение кортежей.
  • Сервис просит у хранилища limit + 1 строк и отдаёт их в make_page(): лишняя строка значит, что есть следующая страница. Страница ровно из limit при пустом остатке даёт next_cursor=None.
  • Курсор — ключ последнего элемента страницы плюс область (history_scope(chat_id), chat_list_scope(user_id)). Курсор чужой области, битый base64, не та структура → InvalidCursor (400). Формат курсора внутренний: клиенты и тесты его не разбирают.

Логи (log.py)

  • Логгер модуля: log = get_logger(__name__) сразу после импортов. logging.getLogger напрямую, print и traceback.print_exc не использовать (исключение — строка configuration error в stderr при неверном окружении, до настройки логов).
  • Формат задаёт logging_config(), его применяет uvicorn (uvicorn.run(log_config=...)); у процесса миграций — migrations/env.py. Второй dictConfig/basicConfig в коде приложения не добавлять.
  • Сообщение — английский, нижний регистр, данные — key=value через %-подстановку: log.info("chat created chat_id=%s members=%d", ...). Не f-string: форматирование ленивое.
  • rid добавляет фильтр из contextvar request_id_var; ставит его только RequestIdMiddleware.
  • Уровни: info — бизнес-событие (создан пользователь, сессия, чат, сообщение; отказ по бизнес-правилу), старт и остановка, возврат кэша; warning — обработано, но требует внимания (неудачный вход, отказ БД или Valkey); error — операция не выполнена. 4xx — не ошибки сервера.
  • Нельзя в лог: text сообщения, display_name, title, username, пароль, токен, их хэши, Authorization, Idempotency-Key (его выбирает клиент, в нём может быть что угодно; повтор виден по replayed=true), тела, query-строку, параметры SQL. Engine создан с hide_parameters=True: текст ошибки драйвера содержит SQL, но не параметры. Вместо текста — length=len(text).

Конфигурация (config.py)

  • Settings.from_env() читает только os.environ, без .env и файлов. Экземпляр создаётся в run() и кладётся в app.state.settings; модульного глобала settings нет.
  • Подключения — вложенные Database и Cache (переменные DB_*, CACHE_*). Пароли — поля с repr=False: в repr() настроек их нет.
  • У dataclass со slots=True атрибут класса — дескриптор, а не значение: умолчания в from_env берутся у экземпляра (default = cls()).
  • Неверное значение — ConfigError с именем переменной; run() печатает её в stderr и выходит с кодом 2.
  • Новая настройка — поле Settings (или Database/Cache) с безопасным дефолтом и границами, environment в compose.yaml (если её задают контейнеру), строка в .env.example (если она приходит из .env), строка в таблице ниже.
Переменная По умолчанию Смысл
APP_HOST / APP_PORT 127.0.0.1 (в образе 0.0.0.0) / 8080 адрес и порт прослушивания
APP_INSTANCE_ID hostname (в контейнере — начало его ID) значение X-Instance-Id; [A-Za-z0-9._-]{1,64}; по нему scripts/stop-one.sh находит реплику
LOG_LEVEL INFO DEBUG/INFO/WARNING/ERROR
SHUTDOWN_TIMEOUT 5 секунды дожидания запросов после SIGTERM, 1..9 (< stop_grace_period 10 с)
KEEP_ALIVE_TIMEOUT 60 секунды простаивающего keep-alive соединения uvicorn; больше timeout http-keep-alive HAProxy (10 с) — закрывает LB, а не реплика (infra/AGENTS.md)
SESSION_TTL_SECONDS 3600 срок сессии (контракт); в тесте истечения — 2
IDEMPOTENCY_TTL_SECONDS 86400 сколько повтор с тем же Idempotency-Key отдаёт прежний результат (контракт: ≥ 24 ч); в тесте срока — 2
KDF_CONCURRENCY 4 одновременных хэшей Argon2id (64 MiB на каждый)
DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD 127.0.0.1 / 5432 / messenger / messenger / пусто подключение к PostgreSQL
DB_POOL_SIZE / DB_POOL_OVERFLOW / DB_POOL_TIMEOUT 10 / 0 / 5 с постоянный пул на процесс без переполнения и ожидание соединения
DB_CONNECT_TIMEOUT / DB_STATEMENT_TIMEOUT_MS / DB_OPERATION_TIMEOUT 3 с / 5000 / 6 с подключение, серверный срок запроса, срок операции хранилища целиком
CACHE_HOST / CACHE_PORT / CACHE_PASSWORD 127.0.0.1 / 6379 / пусто подключение к Valkey
CACHE_TIMEOUT / CACHE_RETRY_AFTER / CACHE_CHAT_TTL / CACHE_MAX_CONNECTIONS 0.2 с / 5 с / 3600 с / 10 срок команды, окно пропуска после отказа, срок карточки, пул

Приложение (main.py)

  • create_app() собирает Db, кэш (create_cache, пространство ключей — имя базы), CachedStorage(PostgresStorage(db), cache) и Passwords; кладёт их в app.state. Соединения открываются лениво: без PostgreSQL процесс стартует, /health/ready отвечает 503.
  • Порядок middleware (снаружи внутрь): ServerErrorMiddleware → RequestIdMiddleware → AuthenticationMiddleware → роутер. add_middleware добавляет снаружи, поэтому RequestIdMiddleware регистрируется последним. Порядок не менять: иначе ответы 401/503 от аутентификации не попадут в access-лог и получат случайный id вместо входящего X-Request-Id (ловит student-tests/test_request_id.py).
  • lifespan: первой строкой early_stop.disarm() (дальше сигналы — забота uvicorn), фиктивный хэш пароля, ready=True; в начале остановки ready=False, затем engine.dispose() и закрытие клиента Valkey. Строки «messenger started instance=…» (там же пул, сроки, keep-alive) и «messenger stopped instance=…»: по ним реплика в журнале сопоставляется с X-Instance-Id. Долгих операций в остановке нет: SIGTERM укладывается в SHUTDOWN_TIMEOUT.
  • RequestIdMiddleware(instance_id=...) ставит X-Request-Id и X-Instance-Id каждому ответу; ответам 500 их ставит handlers.error_response (они формируются снаружи middleware).
  • uvicorn.run(app, ...) — экземпляр, без workers и reload, с timeout_keep_alive: один процесс, пул соединений считан на него. Масштабирование — числом реплик за HAProxy, а не --workers.
  • В памяти процесса нет ничего, от чего зависит корректность: сессии, данные и ключи идемпотентности — в PostgreSQL, Valkey — общий кэш неизменяемых карточек (лаба 3, реплики взаимозаменяемы).

Точка входа (__main__.py, early_stop.py)

python -m src → early_stop.install() до импорта приложения → main.run(). В контейнере сервер — PID 1, а ядро не доставляет PID 1 сигнал без обработчика: пока идёт импорт (почти весь старт), SIGTERM терялся бы, и docker stop стартующей реплики ждал бы 10 с и SIGKILL. Ранний обработчик пишет одну строку «stopped before startup» (формат log.py, без rid) и завершает процесс с кодом 0. early_stop.py — только stdlib. Проверка — evidence/stand/early-stop.txt.

Рецепт: новая ручка

  1. Найти путь, схемы и коды в contracts/openapi.json; если ручки там нет — она не нужна для «4», спросить пользователя.
  2. Модели запроса/ответа — в api/schemas.py с именами из контракта.
  3. Операция данных — метод в storage/base.py (Protocol, докстринг: что атомарно и какие ошибки), реализация в storage/postgres.py (одна транзакция), делегирование в storage/cached.py. Нужна новая колонка или индекс — сначала ревизия (migrations/AGENTS.md).
  4. Правила — метод сервиса (keyword-only, async), лог события.
  5. Роут — в api/routes/<домен>.py; новый файл роутов — зарегистрировать в api/routes/__init__.py. Публичная ручка под /api/v1 — добавить в PUBLIC_ENDPOINTS (api/identity.py).
  6. Тест в student-tests/, затем Definition of Done (корневой файл, раздел 8).