- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
28 KiB
Design
Context
Мотивация — proposal.md, «Why». Требования — дельты в specs/,
семантика — contracts/README.md, «Балансировка и повторная
отправка». Правила слоёв уже описывают целевое состояние лабы 3
(api-contract.md, api-layer.md, service-layer.md,
repo-layer.md, migrations.md, logging.md, settings.md). Design
выбирает то, что они оставили открытым, и фиксирует детали.
Текущее состояние кода (лаба 2, commit c6ad34d):
-
MessageService.send_message(*, chat_id, sender_id, text):- членство проверяется по карточке чата из кэша или БД;
- затем
INSERTсообщения и одинcommit(); idиcreated_atназначает сервис.
Составной внешний ключ
messages (chat_id, sender_id) → chat_members— страховка членства на уровне БД. -
RequestContextMiddleware(чистое ASGI) ставитX-Request-Idвhttp.response.start. -
Ответ 500 собирает
ServerErrorMiddlewareснаружи этого middleware, поэтому заголовок ставит обработчикExceptionвerrors.py. -
Логгер: процессор
add_request_contextдобавляетrequest_idиuser_id. Он стоит и в цепочке structlog, и вforeign_pre_chainдля записей uvicorn и alembic. -
Сессия БД — одна на запрос, весь запрос ограничен
request_timeout_seconds= 6 с, серверныйstatement_timeout= 5 с. Изоляция — READ COMMITTED по умолчанию.statement_timeout(SQLSTATE57014)is_db_unavailableпереводит в 503. -
FastAPI сначала решает зависимости. Отказ
get_current_session— это 401 до проверки параметров и тела. Параметры ручки (path, query, header) и тело проверяются после зависимостей (api-contract.md, раздел «FastAPI»). -
Стенд compose называется
mtusi-lab2(AGENTS.md, «Переходное состояние»). На машине есть volumemtusi-lab2_postgres_dataвторой лабы.
Goals / Non-Goals
Goals:
- Повтор, конфликт и гонка одного ключа решаются транзакцией и
ограничениями PostgreSQL. Ничего не держится в памяти процесса,
поэтому решение без изменений работает за балансировщиком
(
replicas-lb). - Путь первой отправки дороже лабы 2 не больше чем на одну вставку в той же транзакции. Путь повтора не пишет сообщение.
- Порядок кодов 401 → 400 → 404 → 409 получается из штатного порядка FastAPI, без своего разбора заголовка.
Non-Goals:
- Несколько реплик, HAProxy,
stop-one.sh, проверка гонки «через разные реплики»: тест в этом change проверяет один процесс, требование ≥2X-Instance-Idдобавитreplicas-lb. - Фоновая очистка просроченных ключей (worker лабы 5).
- Совместимость миграции со старой версией API при rolling update.
Миграция только расширяющая, но проверка смешанного парка — в change
rolling-update. - Запись ключа и сообщения одним SQL-выражением. Это кандидат
улучшения трека 1 (
PLAN.md), а не основа.
Decisions
1. Ключи — отдельная таблица PostgreSQL в транзакции сообщения
Таблица idempotency_keys:
| Колонка | Тип | Зачем |
|---|---|---|
user_id |
uuid |
область ключа |
chat_id |
uuid |
область ключа |
key |
text |
значение заголовка как есть |
request_hash |
bytea |
SHA-256 канонического тела (решение 4) |
message_id |
uuid |
результат: сохранённое сообщение |
created_at |
timestamptz |
начало срока (решение 5) |
Ограничения (имена — по NAMING_CONVENTION):
- первичный ключ
(user_id, chat_id, key)— уникальность области. Метод и путь в ключ не входят: ключ принимает одна ручка; (chat_id, user_id) → chat_members (chat_id, user_id): ключ есть только у участника. Внешние ключи на пользователя и на чат через участника выполнены;message_id → messages (id)DEFERRABLE INITIALLY DEFERRED(решение 2);CHECK char_length(key) BETWEEN 1 AND 128иCHECK key ~ '^[A-Za-z0-9._:-]+$': формат держит и БД;CHECK octet_length(request_hash) = 32;- индекс по
created_at— для ручной очистки просроченных.
Ревизия alembic создаёт таблицу и ничего не меняет в существующих.
Альтернативы:
-
Valkey
SET NX. Ключ и сообщение не попадают в одну транзакцию, а у Valkey выключен persistence: рестарт стирает ключи. Контракт требует атомарности побочного эффекта и записи результата. -
Колонка ключа в
messagesс уникальным индексом(sender_id, chat_id, key). Это одна вставка вместо двух. Но:- метаданные повтора смешиваются с данными домена;
- срок ключа не выразить без
UPDATEгорячей таблицы; - в
messagesпоявляется ещё один индекс, а стоимость записи с индексом истории разбиралась в лабе 2.
Вариант остаётся кандидатом улучшения трека 1, если запись окажется узким местом.
-
SELECT … FOR UPDATE, затемINSERT. Для ещё не существующего ключа блокировать нечего, и две реплики проходят проверку одновременно. Нужен advisory lock, то есть лишний round-trip и коллизии хэша.
2. Сначала ключ, потом сообщение; внешний ключ на сообщение отложен
Порядок в MessageService.send_message:
- Членство (
ChatNotFound→ 404). Сессию уже проверила зависимость, повтор проходит обе проверки заново. - Сервис назначает
idиcreated_atсообщения и считаетrequest_hash. - Захват ключа (решение 3) с
message_idнового сообщения. - Ключ захвачен: вставка сообщения,
commit(). Отложенный внешний ключ проверяется на commit, когда сообщение уже есть. - Ключ занят: чтение сохранённой записи вместе с сообщением,
commit(). Commit нужен, чтобы снять блокировку строки ключа до ответа. Хэш совпал — вернуть сохранённое сообщение. Не совпал —IdempotencyConflict→ 409.
Любая ошибка до commit() — откат: нет ни ключа, ни сообщения
(сценарии «Сбой при записи сообщения», «Отказ БД при отправке»).
Альтернатива — сначала сообщение, при конфликте ключа откат. Внешний ключ тогда не нужно откладывать. Цена:
- каждый повтор вставляет сообщение и откатывает его: WAL и мёртвые
строки в
messages; - после отката для чтения сохранённого результата нужна вторая транзакция.
При make test-failover и под нагрузкой повторов много, поэтому
выбран путь, на котором повтор не трогает messages.
3. Захват ключа — INSERT … ON CONFLICT DO UPDATE … WHERE просрочен
Repo idempotency.claim_key — одно выражение:
INSERT INTO idempotency_keys (...) VALUES (...)
ON CONFLICT (user_id, chat_id, key) DO UPDATE
SET request_hash = excluded.request_hash,
message_id = excluded.message_id,
created_at = excluded.created_at
WHERE idempotency_keys.created_at < :expired_before
RETURNING message_id
Результат:
- строка вернулась — ключ свободен: новый или просроченный, который заменён в той же транзакции;
None— ключ занят и ещё действует.
Сравнение «повтор или 409» и срок ключа — в сервисе, а
expired_before = now - ttl считается по часам приложения, как
expires_at сессий.
Почему это корректно при READ COMMITTED:
- Одновременная первая вставка того же ключа. Вставка ждёт commit или откат чужой транзакции на уникальном индексе. После commit — конфликт. После отката вставка проходит, то есть транзиентная ошибка не фиксируется.
- Ключ занят.
ON CONFLICT DO UPDATEблокирует конфликтующую строку, даже еслиWHEREложно. СледующийSELECTв той же транзакции видит её зафиксированную версию вместе с сообщением: они записаны одной транзакцией. Ручная очистка не удалит строку между захватом и чтением. - Конкурентные повторы одного ключа выстраиваются в очередь на
блокировке строки. Каждый держит её только до своего
commit().
Здесь правила repo-layer.md и service-layer.md («захват — ON CONFLICT DO NOTHING», «просроченный заменяется в той же транзакции»)
уточняются: это DO UPDATE с условием срока, одним выражением. С
DO NOTHING замене просроченного ключа понадобились бы ещё DELETE
и повторная вставка, а значит, ещё одна гонка. Правила обновляются в
этом change.
Чтение — отдельная функция idempotency.get_key_result:
SELECT request_hash, сообщение с JOIN messages по message_id.
Оно возвращает IdempotencyRecordDTO(request_hash, message), где
message — MessageFullDTO. Строка найдена при захвате и
заблокирована, поэтому None здесь — дефект. Сервис бросает
RuntimeError, получается 500.
4. «То же тело» — SHA-256 канонического JSON из аргументов сервиса
Модульная функция в src/core/services/message.py строит словарь всех
полей запроса из именованных аргументов сервиса: сейчас это
{"text": text}, с лабы 4 — и attachment_ids с подставленным
умолчанием []. Дальше
json.dumps(..., sort_keys=True, ensure_ascii=False, separators=(",", ":")) в UTF-8 и hashlib.sha256(...).digest().
Хэш считается от разобранного тела, а не от байтов запроса. Поэтому
пробелы, экранирование \uXXXX и порядок полей не влияют, а
отсутствующее поле с умолчанием равно явному (сценарий «Тот же JSON в
другой записи»). Текст не нормализуется: другой текст — другой хэш. В
таблице хранится хэш, а не тело: текст сообщения не дублируется.
5. Срок — [idempotency] ttl_seconds, просрочка проверяется при захвате
- В
src/config/settings.pyпоявляется секцияIdempotency(BaseModel):ttl_seconds: int = Field(default=86400, gt=0). Её задают строка[idempotency]вconfig_example.tomlи окружениеIDEMPOTENCY__TTL_SECONDS. - Сервис читает
settings.idempotency.ttl_seconds, какSessionServiceчитает срок сессии. - Имя skeleton
IDEMPOTENCY_TTL_SECONDSмостом не заводится: значение читает только приложение (settings.md). Соответствие описывается вREPORT.md. - Фоновой уборки нет. Просроченная строка заменяется при следующем
захвате того же ключа, остальные лежат до ручной очистки:
DELETE FROM idempotency_keys WHERE created_at < now() - interval '24 hours'по индексуcreated_at. Команда и ограничение — вREPORT.md.
6. Idempotency-Key — параметр ручки по схеме контракта
Параметр ручки:
idempotency_key: Annotated[
str,
Header(
alias=IDEMPOTENCY_KEY_HEADER,
min_length=1,
max_length=IDEMPOTENCY_KEY_MAX_LENGTH,
pattern=IDEMPOTENCY_KEY_PATTERN,
),
]
-
Шаблон
^[A-Za-z0-9._:-]+$и длины — те же, что у параметра вcontracts/openapi.json. Константы лежат вsrc/utils/constants.py. -
Отсутствие и неверный формат дают
RequestValidationError→ 400 через общий обработчик. Сообщение ошибки называет место (header.Idempotency-Key) и правило, но не значение. -
Параметр проверяется после зависимостей, поэтому порядок такой:
- нет сессии — 401;
- нет ключа — 400 (и у постороннего тоже, сценарий «Посторонний без ключа»);
- не участник — 404 из сервиса;
- другое тело — 409.
Невалидное тело с занятым ключом — 400: до сервиса запрос не доходит.
-
Ключ уходит в сервис именованным аргументом
idempotency_key.
Альтернатива — разбирать заголовок в зависимости. Тогда ошибку
ключа можно поставить в любое место порядка. Но параметр выпал бы из
/openapi.json, и порядок пришлось бы держать своим кодом против
штатного поведения FastAPI. Согласование 2026-09-26 разрешает этот
порядок, smoke его не проверяет.
7. X-Instance-Id: hostname по умолчанию, одно значение на процесс
- Значение.
App.instance_id: str = Field(default="", validate_default=True). Валидатор поля подставляетsocket.gethostname()вместо пустой строки. Затем проверяется шаблонINSTANCE_ID_PATTERN = ^[A-Za-z0-9._-]{1,64}$: значение безопасно для заголовка и журнала. Ошибка — отказ запуска с именем поля. - Когда считается. Один раз на процесс, при загрузке
settings: поле в рантайме не меняется. - Где не задаётся.
config.tomlмонтируется во все реплики, а.env,environmentсервисаapiи ключhostname:в compose у реплик общие. Значение оттуда получили бы все реплики сразу, иmake test-failoverне увидел бы двух разныхX-Instance-Id. Поэтому вconfig_example.tomlполя нет. Вместо него в секции[app]стоит комментарий: значение не задавать, в консоли переопределять черезAPP__INSTANCE_ID. Так шаблон не подсказывает вписать значение по образцу соседних полей. - В compose hostname — первые 12 символов ID контейнера. Значит,
stop-one.sh(replicas-lb) сопоставитTARGET_INSTANCE_IDконтейнеру без таблиц соответствия. - В консоли это имя машины разработчика, его можно заменить
через
APP__INSTANCE_ID. - В лабе 7 то же поле получит непрозрачный alias.
- Middleware.
RequestContextMiddlewareдобавляетx-instance-idрядом сx-request-idвhttp.response.start. Байты значения готовятся один раз при импорте модуля. - Ответ 500.
handle_unexpected_errorвerrors.pyставит оба заголовка сам. КонстантаINSTANCE_ID_HEADER— вsrc/utils/constants.py. - Журнал.
add_request_contextпишетinstance_idв каждую запись, в обеих цепочках: так он попадает и в «Started API» / «Stopped API», и в строки uvicorn о shutdown, и в журнал сервисаmigrate.reorder_keysставит его послеuser_id.
Альтернативы значения:
- Случайный UUID при старте. Его нельзя сопоставить контейнеру
без таблицы, а
docker restartдал бы новое значение тому же контейнеру. - Переменная в compose. У реплик одного сервиса окружение одинаковое.
8. Клиенты API начинают слать ключ
-
student-tests. Все отправки сообщений идут через новыйApi.post_message(actor, chat_id, *, key=…, **kwargs):- по умолчанию — новый ключ
uuid4().hex; key=None— без заголовка;- явная строка — этот ключ.
Api.send_message(..., key=None)— обёртка, которая проверяет 201 и схему. Прямыеapi.request("POST", …/messages)в тестах заменяются наpost_message. Идентификация по-прежнему только черезActor.headers(). - по умолчанию — новый ключ
-
contract.py.assert_okиassert_errorпроверяют ещё непустойX-Instance-Idдопустимого формата, как smoke проверяет его на каждом ответе. -
Тесты сценариев
idempotencyиapi-conventions.- Новый модуль
test_idempotency.pyс маркерамиspecи тест заголовков вtest_api_conventions.py. - Гонка одного ключа — в
test_race.pyна общемrun_together. Проверки: 10 ответов 201 с однимid, ≥2 запроса в полёте одновременно, одно сообщение в истории.
- Новый модуль
-
Стенд отказов.
fault_hook.pyполучаетfail-messages <text>иclear-fail-messages: триггерBEFORE INSERT ON messagesбросает ошибку для сообщения с этим текстом, какfail-members. Вставка ключа к этому моменту уже выполнена, поэтому тест проверяет откат обоих.- Тесты
fault:- «Сбой при записи сообщения» — 500, затем повтор с тем же ключом → 201, одно сообщение;
- «Отказ БД при отправке» — 503, после возврата повтор → 201, одно сообщение;
- «Ключ после срока» — на «тесном» API.
- В
TIGHT_ENV(run_failures.py) добавляетсяIDEMPOTENCY__TTL_SECONDS=2.
-
spec_coverage.py.idempotency— вCAPABILITIES. Исключения:- «Instance id в ответе 500» — как «Ответ 500»;
- «Повтор после рестарта API» — evidence с пересозданием контейнера API.
-
k6 (
bench/k6/lib.jssendMessage,after_backup.js,restore_check.js). Ключ —crypto.randomUUID()(WebCrypto k6, им уже генерируются синтетические пароли): новый на каждую отправку, алфавит допустим контрактом, внешние модули jslib не нужны. Повторов нет.bench_compareсравнивает метки только внутри этого репозитория, меток лабы 2 здесь нет. Поэтому поле методики не нужно, а запись ключа — часть стоимости записи всех меток лабы 3. -
Драйвер скилла (
driver.py).- Ключ на каждую отправку.
- Шаги потока:
- повтор → тот же JSON;
- другое тело → 409;
- без ключа → 400;
X-Instance-Idна каждом ответе вexpect.
9. Стенд лабы 3 — первым шагом
docker-compose.yml:name: mtusi-lab3,image: mtusi-messenger:lab3уapiиmigrate.- Комментарий
failures.compose.yml: проект<рабочий>-failuresберётся из имени в compose. - Сценарий
container-image— тег:lab3.
Только после этого что-либо запускается. .env и config.toml
создаются заново через make env_setup, со своими паролями. Volume
mtusi-lab3_postgres_data создаётся с нуля. Данные второй лабы не
переносятся, они синтетические.
10. Evidence
| Файл | Что показывает |
|---|---|
evidence/idempotency/replay.md |
curl: отправка, повтор (тот же JSON), другое тело — 409, без ключа и с неверным ключом — 400, X-Instance-Id во всех ответах |
evidence/idempotency/replay-after-restart.md |
отправка, docker compose up -d --force-recreate api, повтор: другой X-Instance-Id и ID контейнера, тот же Message |
evidence/idempotency/keys-table.md |
\d idempotency_keys; число строк ключей и сообщений после гонки и атомарности. Значения ключей не печатаются |
evidence/idempotency/instance-id.md |
X-Instance-Id = начало docker compose ps -q api; строки журнала с instance_id, включая старт и shutdown; в журнале нет ключа (grep по отправленным ключам пуст) |
evidence/tests/test-isolated.md, evidence/tests/failure-checks.md |
выводы make test_isolated (smoke lab3 + набор) и make failure_checks с commit и датой |
evidence/tests/stand-lab3.md |
docker volume ls до и после: mtusi-lab2_postgres_data не тронут |
Risks / Trade-offs
- [Запущенный стенд лабы 2 занимает порты 8080, 5432 и Valkey] →
перед первым
make run_dockerпроверитьdocker ps. Если стендmtusi-lab2работает, спросить пользователя и остановить его (docker compose -p mtusi-lab2 stop) либо взять другие порты в.env. Volume второй лабы не удалять. - [Замороженная реплика держит блокировку строки ключа] (
docker pauseмежду захватом и commit) → повторы того же ключа на других репликах ждут доstatement_timeout(5 с) и получают 503, клиент повторяет позже.idle_in_transaction_session_timeoutпока не ставится, это областьgraceful-failover. Ограничение — вREPORT.md. - [Таблица ключей растёт] до ручной очистки, это строка на каждое
сообщение → ограничение и команда очистки в
REPORT.md. Индекс поcreated_atделает очистку дешёвой. - [Каждая запись дороже на одну вставку и проверку отложенного внешнего ключа] → это цена контракта. Она измеряется в треке 1, и там же есть кандидат «одно SQL-выражение».
- [Порядок кодов зависит от внутреннего порядка FastAPI] → закреплён тестами сценариев «Порядок проверок». Обновление FastAPI с другим порядком уронит тест, а не пройдёт молча.
- [Тест «Одно значение на процесс» верен только против одного
процесса] → в этом change набор запускается против одного
процесса (
make test_isolated, консоль).replicas-lbвводит режим стенда с LB и переписывает тест под несколько реплик. - [Hostname в консоли раскрывает имя машины] → только в
локальной разработке.
APP__INSTANCE_IDего заменяет, в лабе 7 будет alias. - [Запрос на «устаревший» чат после восстановления в стенде
bench_restore] (restore_check.js, этапstale): раньше 500 давала вставка сообщения, теперь — вставка ключа. Статус тот же, это наблюдение этапа, а не ожидание.
Migration Plan
- Переименовать стенд (решение 9),
make env_setup,make run_docker: применится новая ревизия alembic поверх двух существующих. - Откат кода:
alembic downgrade -1удаляет таблицу ключей, сообщения не затрагиваются. Код лабы 2 таблицу не знает и работает и без отката. - В существующий
config.tomlпереносится секция[idempotency]. Без неё действует 86400.