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>
14 KiB
Tasks
Как строить — design.md (дальше «решение N»). Что должно получиться —
дельты specs/api-conventions, specs/pagination, specs/chats.
Правила.
-
Правила слоёв. Перед первым файлом слоя — Read его правила и одного файла из каталога, чтобы правило подгрузилось:
Что правим Правила student-tests/student-tests.md,api-contract.mdsrc/api/schemas/dto.md,api-contract.mdsrc/api/routers/api-layer.md,api-contract.mdsrc/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. Подготовка
- 1.1 Прочитать правила из таблицы и по одному файлу каждого слоя:
student-tests/test_pagination.py,src/api/schemas/common.py,src/api/routers/v1/chat.py,src/utils/cursor.py. Проверка: правила слоёв подгрузились. - 1.2
openspec validate strict-id-validation --strict— без ошибок.
2. Тесты на текущем коде (решения 4 и 5)
-
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показывает тест для обоих списков. - хелпер подмены одного поля выданного курсора; кодирует так же, как
сервер (компактный JSON, base64url без
-
2.2
test_chats.py, сценарииchats:- «Участник в верхнем регистре» — 201,
member_idsв нижнем регистре равен[alice.id, bob.id], Боб видит чат; - «Повтор участника в другом регистре» — 400, чат не создан;
- «member_ids не массив» —
{},123,false, строка с id Алисы → 400, чат не создан (listed_titles).
Проверка: тесты собираются, маркеры дословно совпадают со сценариями дельты.
- «Участник в верхнем регистре» — 201,
-
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, чат не создан;
- id своего чата без дефисов, с
- «UUID в верхнем регистре в пути» — ответы трёх ручек равны ответам
на нижний регистр,
idиchat_idв нижнем регистре.
Проверка: тесты собираются.
- «UUID другого типа в теле» —
-
2.4 Синхронизировать дельты в основные спеки (
/opsx:sync): сверка покрытия читает толькоopenspec/specs/, и без этого маркеры новых сценариев — ссылка на неизвестный сценарий. Проверка:openspec validate --specsбез ошибок;- в основных спеках есть новые сценарии.
-
2.5
make lint, затем commit тестов и синхронизированных спеков (после подтверждения; сообщение вродеtest: cover tampered cursors and UUID input forms). Проверка:git statusчист. -
2.6 Красный прогон на этом commit:
make test_isolated. Ожидание (решение 5):- красные: «Изменённый курсор» на обоих списках (500 у
"i"не того типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201); - зелёные — все остальные новые тесты и
test_coverage.py.
Расхождение с ожиданием — разбор (AGENTS.md). Если красный тест типов — это дефект, чинить в разделе 3. Вывод с commit, числом тестов и причинами падений — в журнал этапа для 5.1.
- красные: «Изменённый курсор» на обоих списках (500 у
3. Исправление (решения 1–2)
-
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— ошибка валидации.
-
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"}. -
3.3
decode_cursor(src/utils/cursor.py):tиi— строки;exceptтолькоValueError;- обратная сборка через
encode_cursorи сравнение со входом; - докстринг модуля и функции — под новое правило.
Проверка:
uv run python -c— на всех вариантах 2.1 и наgarbage,eyJ4IjoxfQ,!!!толькоCursorError, другого исключения нет; на выданном курсоре — тот же ключ. -
3.4
make lint,make test_isolated— все тесты зелёные, 4 теста реплик пропущены с причиной «one API process». Вывод — в журнал этапа. -
3.5 Правило
.claude/rules/api-contract.md:- «Валидация → 400»: pydantic принимает UUID шире
format: uuid; вход с UUID (путь и тело) — только через тип UUID входа изcommon.py, ответы —UUID; - «Пагинация (keyset)»: курсор принимается только в записи сервера (обратная сборка).
Проверка: названные в правиле файлы и тип существуют.
- «Валидация → 400»: pydantic принимает UUID шире
-
3.6 Commit исправления и правила (после подтверждения; сообщение вроде
fix: reject tampered cursors and non-canonical UUIDs). Проверка:git statusчист.
4. Стенд и регрессия (решение 6)
- 4.1
make replicas, затемmake rolling_update. Проверка:make lb_stats— оба слотаUPна новом образе,make instances—instances: 2. - 4.2
make testиmake student_testчерез LB. Проверка:PASSи все тесты прошли, включая тесты реплик;- в журнале реплик за время прогона нет ответов 500 (
make logs, access-лог, поле статуса).
- 4.3
make failure_checks. Проверка: все проверки отказов прошли, сводка журнала PostgreSQL стенда без признаков аварии, стенд отказов удалён. - 4.4 Чистый clone во временном проекте compose на нестандартных
портах, по процедуре
evidence/replicas/clean-clone-ports.md:git clonecommit 3.6,make run_docker,make test,make student_testчерез LB клона, затемdown -vклона. Проверка: всё код 0, рабочий стендmtusi-lab3не тронут. - 4.5 Спросить пользователя о полной проверке из чистого clone на
портах по умолчанию (
evidence/tests/clean-clone-final.md): она удаляет рабочий стенд с volume. Без согласия — не делать и записать в 5.1, что не делалась.
5. Документы
-
5.1
evidence/tests/strict-id-validation-checks.md:- красный прогон 2.6 и зелёный 3.4 — commit, число тестов, причины падений;
- 4.1–4.4 и решение по 4.5.
Только обезличенные выводы, без токенов и паролей (
evidence/README.md). -
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 абзаца и карты.
- абзац о состоянии лабы: change
-
5.4
graphify update .— граф собран без ошибок. -
5.5 Commit документов (после подтверждения; сообщение вроде
docs: record strict-id-validation checks). Проверка:git statusчист.
7. Пересмотр в apply: проверка полей курсора (до 5.5)
По просьбе пользователя обратная сборка из 3.3 заменена проверкой полей (design, решение 2 и «Пересмотр в apply»).
- 7.1 Артефакты: дельта и основной спек
pagination(незнакомые поля игнорируются; «добавляет поле» — не 400, а 200 и та же страница), design, proposal. Проверка:openspec validate strict-id-validation --strictиopenspec validate --specsбез ошибок. - 7.2
decode_cursor:type(v) is int,t/i— строки,str(UUID(i)) == i, без обратной сборки. Проверка:uv run python -c— 19 подмен дают толькоCursorError, без изменений / лишнее поле / padding / пробелы / порядок ключей — тот же ключ. - 7.3
test_pagination.py:CURSOR_CHANGES(+v=1.0, без лишнего поля) иCURSOR_KEPT(без изменений, лишнее поле → 200 и та же страница). - 7.4 Правило
api-contract.md: проверка полей, почему без обратной сборки, смена формата — новаяCURSOR_VERSIONи приём обеих на время замены. - 7.5
make lint,make test_isolated— все тесты зелёные. - 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 нет.