Files
mtusi2026lab3/openspec/changes/instance-id-idempotency/design.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- 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>
2026-10-08 19:42:36 +03:00

28 KiB
Raw Blame History

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 (SQLSTATE 57014) is_db_unavailable переводит в 503.

  • FastAPI сначала решает зависимости. Отказ get_current_session — это 401 до проверки параметров и тела. Параметры ручки (path, query, header) и тело проверяются после зависимостей (api-contract.md, раздел «FastAPI»).

  • Стенд compose называется mtusi-lab2 (AGENTS.md, «Переходное состояние»). На машине есть volume mtusi-lab2_postgres_data второй лабы.

Goals / Non-Goals

Goals:

  • Повтор, конфликт и гонка одного ключа решаются транзакцией и ограничениями PostgreSQL. Ничего не держится в памяти процесса, поэтому решение без изменений работает за балансировщиком (replicas-lb).
  • Путь первой отправки дороже лабы 2 не больше чем на одну вставку в той же транзакции. Путь повтора не пишет сообщение.
  • Порядок кодов 401 → 400 → 404 → 409 получается из штатного порядка FastAPI, без своего разбора заголовка.

Non-Goals:

  • Несколько реплик, HAProxy, stop-one.sh, проверка гонки «через разные реплики»: тест в этом change проверяет один процесс, требование ≥2 X-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:

  1. Членство (ChatNotFound → 404). Сессию уже проверила зависимость, повтор проходит обе проверки заново.
  2. Сервис назначает id и created_at сообщения и считает request_hash.
  3. Захват ключа (решение 3) с message_id нового сообщения.
  4. Ключ захвачен: вставка сообщения, commit(). Отложенный внешний ключ проверяется на commit, когда сообщение уже есть.
  5. Ключ занят: чтение сохранённой записи вместе с сообщением, 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.js sendMessage, 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

  1. Переименовать стенд (решение 9), make env_setup, make run_docker: применится новая ревизия alembic поверх двух существующих.
  2. Откат кода: alembic downgrade -1 удаляет таблицу ключей, сообщения не затрагиваются. Код лабы 2 таблицу не знает и работает и без отката.
  3. В существующий config.toml переносится секция [idempotency]. Без неё действует 86400.