Files
mtusi2026lab3/evidence/idempotency/keys-table.md
T
ricoromaandClaude Opus 5.5 c5840bfaa8 docs: add idempotency and X-Instance-Id evidence to the report
- evidence for replay, conflict, replay through a new API process and
  after restarting API and storages, keys table, key race,
  X-Instance-Id in responses and logs, explicit and invalid
  instance_id and key TTL, test runs
- stand evidence: make wipe_data leaves the lab 2 volume intact, build
  from a fresh git clone passes smoke, bench restore stage sends with
  Idempotency-Key
- REPORT.md: X-Instance-Id, idempotency design, IDEMPOTENCY_TTL_SECONDS
  mapping, limitations and evidence rows
- tasks.md: mark the change tasks done, add follow-ups from verify

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 17:08:47 +03:00

6.4 KiB
Raw Blame History

Таблица ключей идемпотентности и гонка одного ключа

Спеки idempotency «Гонка одного ключа», «Ключ хранится вне процесса API»; student-tests «Гонка одного ключа»
Change instance-id-idempotency, задача 9.1; схема — design, решение 1
Дата 2026-10-08 16:45:09 UTC
Commit af4bca0
Стенд make run_docker: проект mtusi-lab3, один контейнер api (образ из af4bca0), 127.0.0.1:8080; рабочая база messenger
Хост Docker Desktop 29.8.1, macOS arm64; ВМ Docker: 12 CPU, 7,7 GiB RAM; лимиты контейнерам не задавались

Значения ключей и хэши тел не печатаются: только схема и счётчики.

Схема

$ docker compose exec -T postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c '\d idempotency_keys'
                     Table "public.idempotency_keys"
    Column    |           Type           | Collation | Nullable | Default
--------------+--------------------------+-----------+----------+---------
 user_id      | uuid                     |           | not null |
 chat_id      | uuid                     |           | not null |
 key          | text                     |           | not null |
 request_hash | bytea                    |           | not null |
 message_id   | uuid                     |           | not null |
 created_at   | timestamp with time zone |           | not null |
Indexes:
    "pk_idempotency_keys" PRIMARY KEY, btree (user_id, chat_id, key)
    "ix_idempotency_keys_created_at" btree (created_at)
Check constraints:
    "ck_idempotency_keys_key_format" CHECK (key ~ '^[A-Za-z0-9._:-]+$'::text)
    "ck_idempotency_keys_key_length" CHECK (char_length(key) >= 1 AND char_length(key) <= 128)
    "ck_idempotency_keys_request_hash_length" CHECK (octet_length(request_hash) = 32)
Foreign-key constraints:
    "fk_idempotency_keys_chat_id_user_id_chat_members" FOREIGN KEY (chat_id, user_id) REFERENCES chat_members(chat_id, user_id)
    "fk_idempotency_keys_message_id_messages" FOREIGN KEY (message_id) REFERENCES messages(id) DEFERRABLE INITIALLY DEFERRED
  • первичный ключ — область ключа: пользователь, чат, ключ;
  • ключ есть только у участника чата (внешний ключ на chat_members);
  • ссылка на сообщение проверяется на commit: ключ вставляется первым в той же транзакции;
  • формат и длину ключа держит и сама БД; хранится SHA-256 тела (32 байта), а не текст.

Проверка CHECK (ключ с пробелом, транзакция с откатом; задача 4.2, та же ревизия 7652184b7016):

ERROR:  new row for relation "idempotency_keys" violates check constraint "ck_idempotency_keys_key_format"

Чтение сохранённого результата на 10 000 синтетических ключах (транзакция с откатом, ANALYZE внутри; задача 5.2, тот же запрос get_key_result): Index Scan using pk_idempotency_keys on idempotency_keys, затем Index Scan using pk_messages on messages. На трёх строках планировщик выбирал Seq Scan — таблица меньше страницы.

Гонка одного ключа против контейнера

$ BASE_URL=http://localhost:8080 uv run pytest student-tests/test_race.py -s -k same_key
key race: 10 clients, statuses {201: 10}, max in flight 10; history: 1 messages
1 passed, 2 deselected in 0.39s

10 клиентов по своим соединениям за threading.Barrier, одно тело и один ключ: 10 ответов 201 с одним и тем же Message, в истории одно сообщение. Один процесс API — гонку решает PostgreSQL (уникальный первичный ключ, вставка ждёт commit конкурента), то же самое будет и между репликами; ответы ≥2 реплик проверит change replicas-lb.

Тест гонки к этому моменту прогонялся на этой базе 10 раз (консоль и контейнер): ни в одном чате текст гонки не встречается дважды.

SELECT count(*) FROM (SELECT chat_id FROM messages WHERE text = 'один раз'
                      GROUP BY chat_id HAVING count(*) > 1) d;   -- 0
SELECT count(DISTINCT chat_id) FROM messages WHERE text = 'один раз'; -- 10

Каждое сообщение — со своим ключом

 messages | keys | messages_without_key | keys_without_message
----------+------+----------------------+----------------------
     1352 | 1336 |                   16 |                    0

 hash_bytes | count
------------+-------
         32 |  1336

16 сообщений без ключа — не дефект, а история этой базы:

             period             | messages | without_key
--------------------------------+----------+-------------
 1: до таблицы ключей           |        6 |           6
 2: реализация и мутации 7.2    |      892 |          10
 3: после мутаций (код af4bca0) |      454 |           0
  1. 6 сообщений — публичный smoke на коде без ключей (задачи 3.1–3.2, 13:51–13:53 UTC), до миграции 7652184b7016 (первый ключ — 13:57).
  2. 10 сообщений — проверка тестов на ошибочном коде (задача 7.2): временная мутация сервиса вставляла сообщение и при занятом ключе; пять упавших тестов прогнаны дважды. Мутация откачена, в коммит не попала.
  3. На закоммиченном коде у каждого сообщения есть ключ, ключей без сообщения нет (keys_without_message = 0 держит и внешний ключ).