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>
223 lines
14 KiB
Markdown
223 lines
14 KiB
Markdown
# 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 нет.
|