- 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>
112 lines
6.4 KiB
Markdown
112 lines
6.4 KiB
Markdown
# Таблица ключей идемпотентности и гонка одного ключа
|
||
|
||
| | |
|
||
|---|---|
|
||
| Спеки | `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 держит и внешний ключ).
|