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

14 KiB
Raw Blame History

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. Подготовка

  • 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 показывает тест для обоих списков.

  • 2.2 test_chats.py, сценарии chats:

    • «Участник в верхнем регистре» — 201, member_ids в нижнем регистре равен [alice.id, bob.id], Боб видит чат;
    • «Повтор участника в другом регистре» — 400, чат не создан;
    • «member_ids не массив» — {}, 123, false, строка с id Алисы → 400, чат не создан (listed_titles).

    Проверка: тесты собираются, маркеры дословно совпадают со сценариями дельты.

  • 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 в нижнем регистре.

    Проверка: тесты собираются.

  • 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.

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)»: курсор принимается только в записи сервера (обратная сборка).

    Проверка: названные в правиле файлы и тип существуют.

  • 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 clone commit 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 абзаца и карты.

  • 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 нет.