8.8 KiB
src/storage/ — хранилище
base.py — Storage (Protocol): что сервисы могут просить у слоя
данных. postgres.py — PostgresStorage, источник истины.
cached.py — CachedStorage: тот же интерфейс, карточка чата через
Valkey, остальное — делегирование в PostgreSQL. tables.py — схема в
SQLAlchemy Core для запросов и alembic check. Собирает цепочку
main.py: CachedStorage(PostgresStorage(db), cache).
Инварианты PostgresStorage (атомарность и гонки — рубрика «4»)
- Один публичный метод — одна транзакция
self._db.transaction(): проверка → назначениеid/created_at→ все вставки → commit до возврата. 201 уходит клиенту только после commit. Исключение внутри — откат целиком: чат не останется без участников (проверяетtest_members_failure_rolls_back_chat). - Гонки закрывают ограничения PostgreSQL, а не «сначала SELECT,
потом INSERT»: username —
INSERT ... ON CONFLICT (username) DO NOTHING RETURNING(пустой RETURNING →UsernameTaken); отправитель — составной внешний ключ(chat_id, sender_id) → chat_members(нарушение 23503 →NotFound). Явных блокировок нет: пользователи и участники не меняются и не удаляются. created_at—self._clock.now()перед вставкой; у участника — копия времени чата (по ней keyset списка чатов). Время БД (now()) не используется: порядок, который видит клиент, зависит от одних часов.- Запросы — SQLAlchemy Core с параметрами (
select,insert,pg_insert,tuple_). SQL из f-строк и конкатенации запрещён;text()— только без пользовательских значений. - Keyset без OFFSET и count(*):
WHERE chat_id = :id AND (created_at, id) > (:t, :i) ORDER BY created_at, id LIMIT :nпо индексуix_messages_chat_id_created_at_id; список чатов — поix_chat_members_user_id_created_at_chat_id. Страница не читает историю до курсора — это доказали планыEXPLAIN (ANALYZE, BUFFERS)лабы 2 (её репозиторий,evidence/bench/). - Хранилище бросает доменные ошибки там, где сработало
ограничение:
UsernameTaken,InvalidMembers(участника нет),NotFound(внешний ключ сообщения или ключа идемпотентности),IdempotencyConflict(ключ занят другим телом). Бизнес-правил (членство, дубликаты в запросе) здесь нет — они в сервисах. - Отказ базы — не здесь:
Db.transaction()(src/db.py) переводит недоступность (остановлен, завис, пул исчерпан,statement_timeout, обрыв) вUnavailableи пишет одну строкуwarning. ОстальныеDBAPIError(нарушенныйCHECK, синтаксис) — дефект, 500. - Хранилище не логирует и не импортирует
src.log, fastapi, сервисы и API. Наружу — только объектыsrc/domain.py, неRow.
Отправка с ключом идемпотентности (create_message, лаба 3)
Одна транзакция, ключ — раньше сообщения:
- Захват ключа одним выражением:
INSERT INTO idempotency_keys … ON CONFLICT (user_id, chat_id, key) DO UPDATE SET request_hash, message_id, created_at WHERE idempotency_keys.created_at < now − ttl RETURNING message_id. RETURNING не пуст — ключ новый или просроченный (заменён тем же выражением, без DELETE и второй гонки); пуст — ключ действует, а его строка заблокирована до конца транзакции. - Захватили — вставка сообщения с тем же
message_id; внешний ключ ключа на сообщениеDEFERRABLE INITIALLY DEFERREDпроверяется при commit. Итог —SentMessage(message, replayed=False). - Не захватили — чтение сохранённого (
request_hash+ сообщение через JOIN). Хэш совпал —SentMessage(сохранённое, replayed=True): тот жеidиcreated_at, ничего не пишется. Не совпал —IdempotencyConflict, откат снимает блокировку.
Гонки: одновременные запросы с одним ключом (в том числе с разных
реплик) ждут друг друга на уникальном индексе; второй после commit
первого видит его строку и отдаёт повтор. Сбой до commit (отказ БД,
ошибка вставки сообщения) откатывает и ключ, и сообщение: транзиентная
ошибка результатом не фиксируется, повтор с тем же ключом безопасен.
Внешние ключи (chat_id, автор) → chat_members у ключа и сообщения —
страховка членства (нарушение → NotFound). Срок ключа считается по
часам приложения (utc_now()), как срок сессии. Просроченные ключи не
удаляются сами: занятый заново ключ заменяется, остальные копятся
(уборка — DELETE … WHERE created_at < … по индексу; ограничение в
REPORT.md). Ключи — только в PostgreSQL: в кэш их не класть.
CachedStorage (кэш Valkey, уровень «4»)
- Кэшируется только неизменяемое — карточка чата (
id,title,member_idsв порядке создания,created_at), JSON под ключомmessenger:v1:<имя базы>:chat:<id>. Сессии, история и списки — нет: logout должен действовать мгновенно, история меняется с каждой записью. - Чтение: Valkey → при промахе PostgreSQL и запись в кэш. Отсутствующий чат не кэшируется. Новый чат пишется в кэш после commit.
- Инвалидации нет: контракт не меняет и не удаляет чаты. Правка базы в
обход API (восстановление из backup) требует
FLUSHALLпосле неё. - Отказ Valkey — промах (
src/cache.py): ответ тот же, из PostgreSQL. - Новый метод
Storage— делегирование здесь обязательно: класс реализует протокол целиком, явными методами.
Изменение интерфейса
Новый метод — сначала в Storage (base.py) с докстрингом: что
атомарно и какие ошибки, затем реализация в postgres.py (одна
транзакция), делегирование в cached.py. Сигнатура — только domain,
UUID, SortKey, timedelta, примитивы. Новая колонка, индекс,
ограничение — сначала в tables.py и новой ревизии
(migrations/AGENTS.md), alembic check без расхождений.
Проверка
make test-isolated (в том числе test_race.py: 100 сообщений от 10
клиентов, гонка регистрации и гонка одного ключа через реплики) и make failure-checks (откат чата и ключа, отказы БД и Valkey, пул, срок
ключа). Правка запроса истории, записи или индексов — ещё make bench-scaling-quick: стоимость на запрос видна в runs.csv
(db_cpu_us_per_req).