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

112 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Таблица ключей идемпотентности и гонка одного ключа
| | |
|---|---|
| Спеки | `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; лимиты контейнерам не задавались |
Значения ключей и хэши тел не печатаются: только схема и счётчики.
## Схема
```text
$ 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`):
```text
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` — таблица меньше страницы.
## Гонка одного ключа против контейнера
```text
$ 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 раз (консоль и
контейнер): ни в одном чате текст гонки не встречается дважды.
```sql
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
```
## Каждое сообщение — со своим ключом
```text
messages | keys | messages_without_key | keys_without_message
----------+------+----------------------+----------------------
1352 | 1336 | 16 | 0
hash_bytes | count
------------+-------
32 | 1336
```
16 сообщений без ключа — не дефект, а история этой базы:
```text
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 держит и внешний ключ).