17 KiB
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— только из enumError.codeвcontracts/openapi.json. Текст — английский, без id, путей, имён классов, SQL и признаков существования чужого объекта. - Нет чата и чат чужой — одно и то же
NotFound. - Тот же
Idempotency-Keyс другим телом —IdempotencyConflict(409conflict); нет ключа или он не по шаблону — 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добавляет фильтр из contextvarrequest_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.
Рецепт: новая ручка
- Найти путь, схемы и коды в
contracts/openapi.json; если ручки там нет — она не нужна для «4», спросить пользователя. - Модели запроса/ответа — в
api/schemas.pyс именами из контракта. - Операция данных — метод в
storage/base.py(Protocol, докстринг: что атомарно и какие ошибки), реализация вstorage/postgres.py(одна транзакция), делегирование вstorage/cached.py. Нужна новая колонка или индекс — сначала ревизия (migrations/AGENTS.md). - Правила — метод сервиса (keyword-only, async), лог события.
- Роут — в
api/routes/<домен>.py; новый файл роутов — зарегистрировать вapi/routes/__init__.py. Публичная ручка под/api/v1— добавить вPUBLIC_ENDPOINTS(api/identity.py). - Тест в
student-tests/, затем Definition of Done (корневой файл, раздел 8).