Files
mtusi2026lab3/src/storage/AGENTS.md
T

8.8 KiB
Raw Blame History

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»)

  1. Один публичный метод — одна транзакция self._db.transaction(): проверка → назначение id/created_at → все вставки → commit до возврата. 201 уходит клиенту только после commit. Исключение внутри — откат целиком: чат не останется без участников (проверяет test_members_failure_rolls_back_chat).
  2. Гонки закрывают ограничения PostgreSQL, а не «сначала SELECT, потом INSERT»: username — INSERT ... ON CONFLICT (username) DO NOTHING RETURNING (пустой RETURNING → UsernameTaken); отправитель — составной внешний ключ (chat_id, sender_id) → chat_members (нарушение 23503 → NotFound). Явных блокировок нет: пользователи и участники не меняются и не удаляются.
  3. created_at — self._clock.now() перед вставкой; у участника — копия времени чата (по ней keyset списка чатов). Время БД (now()) не используется: порядок, который видит клиент, зависит от одних часов.
  4. Запросы — SQLAlchemy Core с параметрами (select, insert, pg_insert, tuple_). SQL из f-строк и конкатенации запрещён; text() — только без пользовательских значений.
  5. 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/).
  6. Хранилище бросает доменные ошибки там, где сработало ограничение: UsernameTaken, InvalidMembers (участника нет), NotFound (внешний ключ сообщения или ключа идемпотентности), IdempotencyConflict (ключ занят другим телом). Бизнес-правил (членство, дубликаты в запросе) здесь нет — они в сервисах.
  7. Отказ базы — не здесь: Db.transaction() (src/db.py) переводит недоступность (остановлен, завис, пул исчерпан, statement_timeout, обрыв) в Unavailable и пишет одну строку warning. Остальные DBAPIError (нарушенный CHECK, синтаксис) — дефект, 500.
  8. Хранилище не логирует и не импортирует src.log, fastapi, сервисы и API. Наружу — только объекты src/domain.py, не Row.

Отправка с ключом идемпотентности (create_message, лаба 3)

Одна транзакция, ключ — раньше сообщения:

  1. Захват ключа одним выражением: 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 и второй гонки); пуст — ключ действует, а его строка заблокирована до конца транзакции.
  2. Захватили — вставка сообщения с тем же message_id; внешний ключ ключа на сообщение DEFERRABLE INITIALLY DEFERRED проверяется при commit. Итог — SentMessage(message, replayed=False).
  3. Не захватили — чтение сохранённого (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).