21 KiB
src/ — устройство приложения
Дополняет корневой AGENTS.md. Правила конкретных слоёв — в
api/AGENTS.md, services/AGENTS.md, storage/AGENTS.md.
Слои и направление зависимостей
api/ (routes, deps, identity, request_id, handlers, schemas)
↓ cleaner/ (python -m src.cleaner)
services/ (UserService, SessionService, ChatService, MessageService,
AttachmentService, CleanupService, ReconcileService, access.py)
↓
storage/ (Storage Protocol → CachedStorage → PostgresStorage;
MaintenanceStorage; AttachmentObjects → s3.ObjectStore)
Общие модули нижнего уровня: domain.py, errors.py, pagination.py,
clock.py, constants.py, log.py, config.py, images.py
(структурная проверка PNG/JPEG без декодирования, stdlib). Инфраструктура
— тоже общие модули: db.py (PostgreSQL), cache.py (Valkey), s3.py
(клиент S3, лаба 4), uploads.py (места загрузок процесса API),
passwords.py (Argon2id). В них нет бизнес-правил.
| Модуль | Может импортировать | Не может импортировать |
|---|---|---|
api/* |
services, storage (только типы Storage, AttachmentObjects), uploads.UploadSlots (тип), общие модули, fastapi/starlette |
storage.postgres, storage.cached, db, cache, s3 (их собирает main.py) |
services/* |
storage (Protocol и AttachmentObjects), passwords, uploads, images, общие модули, anyio.to_thread (проверка изображения в потоке) |
api/*, db, cache, s3, fastapi, starlette, pydantic, sqlalchemy |
storage/* |
domain, errors, pagination, clock, constants, db, cache, s3 (типы и клиент), sqlalchemy |
api/*, services/*, fastapi, log |
db, cache, s3, passwords, uploads |
config, constants, errors, log, свой драйвер (asyncpg, redis, aiobotocore) |
api/*, services/*, storage/* |
cleaner/* |
всё, кроме api/*: он собирает свой процесс |
api/* |
domain, clock, constants, images |
только стандартную библиотеку | всё остальное из 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 / 5 / 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 |
срок команды, окно пропуска после отказа, срок карточки, пул |
S3_ENDPOINT / S3_BUCKET / S3_REGION |
http://127.0.0.1:8334 (в compose http://s3:8333) / messenger-attachments / us-east-1 |
адрес API S3, приватный bucket, регион подписи |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY |
пусто (repr=False) |
ключи своего пользователя S3: у реплик — API (S3_API_* из .env), у уборщика — свои (S3_CLEANER_*); административная пара — только у сервера s3 |
S3_TIMEOUT / S3_CONNECT_TIMEOUT / S3_MAX_CONNECTIONS |
5 с / 1 с / 10 |
срок вызова S3 целиком и каждого блока чтения (asyncio.timeout; read_timeout aiohttp выключен), подключение, пул клиента; повторов нет |
UPLOAD_MAX_CONCURRENT / UPLOAD_MAX_WAITING / UPLOAD_WAIT_TIMEOUT / UPLOAD_BODY_TIMEOUT |
4 / 16 / 5 с / 30 с |
мест загрузки на процесс, очередь за местом, ожидание места (затем 429 с Retry-After), срок тела с момента места (затем 400) |
CLEANER_INTERVAL / CLEANER_GRACE / CLEANER_BATCH |
60 с / 900 с / 100 |
уборщик: пауза между проходами, возраст незавершённой загрузки (> границы живой загрузки 21 с, иначе код 2), кандидатов на выборку |
RECONCILE_INTERVAL / RECONCILE_PAGE_SIZE / RECONCILE_MAX_CHANGES / RECONCILE_RATE |
3600 с (0 — плановой нет) / 1000 / 100 / 2000 |
плановая сверка, страница списка и строк, предел изменений за проход, объектов S3 в секунду (0 — без предела) |
Приложение (main.py)
create_app()собираетDb, кэш (create_cache, пространство ключей — имя базы),CachedStorage(PostgresStorage(db), cache),Passwords, с лабы 4 — клиент S3 (create_object_store, пространство ключей — то же имя базы) вAttachmentObjectsиUploadSlots; кладёт их вapp.state. Соединения открываются лениво: без PostgreSQL процесс стартует,/health/readyотвечает 503. S3 готовность не проверяет: без него текст работает, загрузка и скачивание — 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), фиктивный хэш пароля,store.start()(модели botocore, без сети),ready=True; в начале остановкиready=False, затемengine.dispose(), закрытие клиентов Valkey и S3. Пустые ключи S3 — строкаwarningпри старте, а не отказ. Строки «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, реплики взаимозаменяемы).
Уборщик (cleaner/, лаба 4)
python -m src.cleaner — второй процесс на образе API (сервис compose
cleaner), а не задача реплик: N реплик были бы N уборщиками, а
остановка реплики обрывала бы проход. __main__ → early_stop.install()
→ main.run(): настройки (неверные — код 2), проверка CLEANER_GRACE >
границы живой загрузки 2 × (DB_OPERATION_TIMEOUT + 2) + S3_TIMEOUT (21
с; иначе код 2 до соединений), свой пул (на стенде 1 соединение) и
клиент S3 с ключами уборщика. Режимы: сервис (уборка раз в
CLEANER_INTERVAL, плановая сверка batch с исправлением при старте и
раз в RECONCILE_INTERVAL), --once, reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep] [--rate R] (dry-run
по умолчанию; коды 0 / 3 / 1 / 2 — докстринг cleaner/main.py).
SIGTERM: текущий шаг доводится до commit или отката, новых нет.
Точка входа (__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).