Files
mtusi2026lab3/openspec/changes/strict-id-validation/tasks.md
T
ricoromaandClaude Opus 5.5 8fe467ace0 fix: check cursor fields instead of re-encoding
628b5f2 accepted a cursor only if re-encoding the parsed key gave the
same string. That closed the format both ways: any encoding change, even
a compatible one (an optional field, key order, to_rfc3339 shared with
API responses), would turn cursors issued by a replica of the other
version into 400 during make rolling_update, which the tests cannot see.

decode_cursor now checks the fields one by one: v must be exactly the
integer 1, t and i must be strings, i must be in the server's notation
(lowercase 8-4-4-4-12). Unknown fields are ignored, so a tampered cursor
is still a 400 while the format stays open for compatible changes. The
rule records how to change the format: a new CURSOR_VERSION, with both
versions accepted while replicas are replaced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 13:11:57 +03:00

223 lines
14 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.
# Tasks
Как строить — `design.md` (дальше «решение N»). Что должно получиться —
дельты `specs/api-conventions`, `specs/pagination`, `specs/chats`.
**Правила.**
- **Правила слоёв.** Перед первым файлом слоя — Read его правила и
одного файла из каталога, чтобы правило подгрузилось:
| Что правим | Правила |
|---|---|
| `student-tests/` | `student-tests.md`, `api-contract.md` |
| `src/api/schemas/` | `dto.md`, `api-contract.md` |
| `src/api/routers/` | `api-layer.md`, `api-contract.md` |
| `src/utils/` | `api-contract.md` (пагинация), `service-layer.md` (курсор) |
- **Только Edit и Write.** Файлы меняются только ими. Перед правкой —
Read файла. Для проверок `uv run python -c …` запускать можно.
- **Коммиты — только после подтверждения пользователя:** показать
изменения, предложить сообщение (английский, conventional style,
последняя строка `Co-Authored-By: Claude Opus 5.5
<noreply@anthropic.com>`), ждать ок. Push, checkout, reset, stash —
нельзя.
- **Упавший тест или прогон** — сначала разбор и названная причина,
потом правка (AGENTS.md). Тест не ослабляется под ответ.
- **Прогоны по одному.** `make test_isolated` и `make failure_checks` не
запускать параллельно друг с другом и с другой сессией
(`student-tests.md`).
## 1. Подготовка
- [x] 1.1 Прочитать правила из таблицы и по одному файлу каждого слоя:
`student-tests/test_pagination.py`, `src/api/schemas/common.py`,
`src/api/routers/v1/chat.py`, `src/utils/cursor.py`. Проверка: правила
слоёв подгрузились.
- [x] 1.2 `openspec validate strict-id-validation --strict` — без
ошибок.
## 2. Тесты на текущем коде (решения 4 и 5)
- [x] 2.1 `test_pagination.py`, сценарий `pagination` «Изменённый
курсор»:
- хелпер подмены одного поля выданного курсора; кодирует так же, как
сервер (компактный JSON, base64url без `=`);
- в хелпере — утверждение, что без изменений он возвращает ту же
строку;
- фикстура на оба списка: история (два сообщения, `limit=1`) и список
чатов (два чата, `limit=1`);
- варианты:
- `"i"` = `[]`, `{}`, `123`, `false`;
- тот же id без дефисов и в верхнем регистре;
- `"v": true`;
- лишнее поле;
- контроль: перекодированный без изменений курсор даёт 200.
Проверка: `uv run pytest student-tests/test_pagination.py --collect-only
-q` показывает тест для обоих списков.
- [x] 2.2 `test_chats.py`, сценарии `chats`:
- «Участник в верхнем регистре» — 201, `member_ids` в нижнем регистре
равен `[alice.id, bob.id]`, Боб видит чат;
- «Повтор участника в другом регистре» — 400, чат не создан;
- «member_ids не массив» — `{}`, `123`, `false`, строка с id Алисы →
400, чат не создан (`listed_titles`).
Проверка: тесты собираются, маркеры дословно совпадают со сценариями
дельты.
- [x] 2.3 `test_api_conventions.py`, сценарии `api-conventions`:
- «UUID другого типа в теле» — `member_ids` = `[alice.id, X]`, где X —
`[]`, `{}`, `123`, `false`; 400, чат не создан;
- «Не UUID в пути» — `chat_id` = `123`, `false`, `[]`, `{}` (через
`urllib.parse.quote(…, safe="")`) у `GET` чата, `GET` истории и
`POST` сообщения с ключом; 400;
- «Другая запись UUID»:
- id своего чата без дефисов, с `urn:uuid:` и в `{…}` на тех же
трёх ручках — 400, история не изменилась;
- id Боба в тех же записях в `member_ids` — 400, чат не создан;
- «UUID в верхнем регистре в пути» — ответы трёх ручек равны ответам
на нижний регистр, `id` и `chat_id` в нижнем регистре.
Проверка: тесты собираются.
- [x] 2.4 Синхронизировать дельты в основные спеки (`/opsx:sync`):
сверка покрытия читает только `openspec/specs/`, и без этого маркеры
новых сценариев — ссылка на неизвестный сценарий. Проверка:
- `openspec validate --specs` без ошибок;
- в основных спеках есть новые сценарии.
- [x] 2.5 `make lint`, затем commit тестов и синхронизированных спеков
(после подтверждения; сообщение вроде `test: cover tampered cursors
and UUID input forms`). Проверка: `git status` чист.
- [x] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание
(решение 5):
- красные: «Изменённый курсор» на обоих списках (500 у `"i"` не того
типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201);
- зелёные — все остальные новые тесты и `test_coverage.py`.
Расхождение с ожиданием — разбор (AGENTS.md). Если красный тест
типов — это дефект, чинить в разделе 3. Вывод с commit, числом тестов
и причинами падений — в журнал этапа для 5.1.
## 3. Исправление (решения 1–2)
- [x] 3.1 `UUID_PATTERN` (8-4-4-4-12, шестнадцатеричные цифры в любом
регистре) в `src/utils/constants.py`. В `src/api/schemas/common.py` —
тип UUID входа: `Annotated[UUID, BeforeValidator(...)]` с
`re.fullmatch`; не-строку пропускает дальше. Проверка: `uv run python
-c` с `TypeAdapter`:
- канон в обоих регистрах принимается;
- запись без дефисов, `urn:uuid:`, `{…}`, пробел, `\n` в конце,
`[]`, `{}`, `123`, `false`, `null` — ошибка валидации.
- [x] 3.2 Тип UUID входа у `member_ids` (`src/api/schemas/chat.py`) и у
`chat_id` трёх ручек (`src/api/routers/v1/chat.py`, `message.py`).
Модели ответов не меняются. Проверка: `make run_dev`, в
`/openapi.json` у `chat_id` по-прежнему `{"type": "string",
"format": "uuid"}`.
- [x] 3.3 `decode_cursor` (`src/utils/cursor.py`):
- `t` и `i` — строки;
- `except` только `ValueError`;
- обратная сборка через `encode_cursor` и сравнение со входом;
- докстринг модуля и функции — под новое правило.
Проверка: `uv run python -c` — на всех вариантах 2.1 и на
`garbage`, `eyJ4IjoxfQ`, `!!!` только `CursorError`, другого
исключения нет; на выданном курсоре — тот же ключ.
- [x] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста
реплик пропущены с причиной «one API process». Вывод — в журнал
этапа.
- [x] 3.5 Правило `.claude/rules/api-contract.md`:
- «Валидация → 400»: pydantic принимает UUID шире `format: uuid`;
вход с UUID (путь и тело) — только через тип UUID входа из
`common.py`, ответы — `UUID`;
- «Пагинация (keyset)»: курсор принимается только в записи сервера
(обратная сборка).
Проверка: названные в правиле файлы и тип существуют.
- [x] 3.6 Commit исправления и правила (после подтверждения; сообщение
вроде `fix: reject tampered cursors and non-canonical UUIDs`).
Проверка: `git status` чист.
## 4. Стенд и регрессия (решение 6)
- [x] 4.1 `make replicas`, затем `make rolling_update`. Проверка:
`make lb_stats` — оба слота `UP` на новом образе, `make instances` —
`instances: 2`.
- [x] 4.2 `make test` и `make student_test` через LB. Проверка:
- `PASS` и все тесты прошли, включая тесты реплик;
- в журнале реплик за время прогона нет ответов 500 (`make logs`,
access-лог, поле статуса).
- [x] 4.3 `make failure_checks`. Проверка: все проверки отказов прошли,
сводка журнала PostgreSQL стенда без признаков аварии, стенд отказов
удалён.
- [x] 4.4 Чистый clone во временном проекте compose на нестандартных
портах, по процедуре `evidence/replicas/clean-clone-ports.md`:
`git clone` commit 3.6, `make run_docker`, `make test`, `make
student_test` через LB клона, затем `down -v` клона. Проверка:
всё код 0, рабочий стенд `mtusi-lab3` не тронут.
- [x] 4.5 Спросить пользователя о полной проверке из чистого clone на
портах по умолчанию (`evidence/tests/clean-clone-final.md`): она
удаляет рабочий стенд с volume. Без согласия — не делать и записать
в 5.1, что не делалась.
## 5. Документы
- [x] 5.1 `evidence/tests/strict-id-validation-checks.md`:
- красный прогон 2.6 и зелёный 3.4 — commit, число тестов, причины
падений;
- 4.1–4.4 и решение по 4.5.
Только обезличенные выводы, без токенов и паролей
(`evidence/README.md`).
- [x] 5.2 `REPORT.md`:
- строка в таблице доказательств: строгий вход с UUID и курсор, red →
green, ссылка на 5.1;
- расхождение с прежним поведением: запись UUID без дефисов,
`urn:uuid:` и `{…}` → 400;
- число тестов там, где отчёт говорит о текущем коде.
Проверка: Read раздела после правки; числа совпадают с 4.2 и 3.4.
- [ ] 5.3 `AGENTS.md`:
- абзац о состоянии лабы: change `strict-id-validation`;
- карта кода: тип UUID входа в `common.py`, обратная сборка в
`cursor.py`.
Проверка: Read абзаца и карты.
- [ ] 5.4 `graphify update .` — граф собран без ошибок.
- [ ] 5.5 Commit документов (после подтверждения; сообщение вроде `docs:
record strict-id-validation checks`). Проверка: `git status` чист.
## 7. Пересмотр в apply: проверка полей курсора (до 5.5)
По просьбе пользователя обратная сборка из 3.3 заменена проверкой полей
(design, решение 2 и «Пересмотр в apply»).
- [x] 7.1 Артефакты: дельта и основной спек `pagination` (незнакомые
поля игнорируются; «добавляет поле» — не 400, а 200 и та же страница),
design, proposal. Проверка: `openspec validate strict-id-validation
--strict` и `openspec validate --specs` без ошибок.
- [x] 7.2 `decode_cursor`: `type(v) is int`, `t`/`i` — строки,
`str(UUID(i)) == i`, без обратной сборки. Проверка: `uv run python -c`
— 19 подмен дают только `CursorError`, без изменений / лишнее поле /
padding / пробелы / порядок ключей — тот же ключ.
- [x] 7.3 `test_pagination.py`: `CURSOR_CHANGES` (+ `v=1.0`, без
лишнего поля) и `CURSOR_KEPT` (без изменений, лишнее поле → 200 и та
же страница).
- [x] 7.4 Правило `api-contract.md`: проверка полей, почему без обратной
сборки, смена формата — новая `CURSOR_VERSION` и приём обеих на время
замены.
- [x] 7.5 `make lint`, `make test_isolated` — все тесты зелёные.
- [x] 7.6 Commit смягчения (сообщение вроде `fix: check cursor fields
instead of re-encoding`).
- [ ] 7.7 Регрессия на этом commit, как 4.1–4.4: `make rolling_update`
с `628b5f2`, `make test` и `make student_test` через LB (0 ответов 5xx),
`make failure_checks`, `git clone` во временном проекте на
нестандартных портах.
- [ ] 7.8 evidence (5.1) и `REPORT.md` (5.2) — под проверку полей и
числа 7.5–7.7.
## 6. Завершение
- [ ] 6.1 `/opsx:verify strict-id-validation`. Найденное исправить
новым commit с повтором затронутых проверок.
- [ ] 6.2 `/opsx:archive strict-id-validation` после ок пользователя.
Проверка: change в `openspec/changes/archive/`, активных changes нет.