ipam_control/docs/changes/029-prefix-tree-lock/SUMMARY.md

Итог: целостность дерева префиксов при параллельных изменениях (изменение 029)

Что сделано

• app/api/v1/prefixes.py: константа VRF_LOCK_NS = 7033 и хелпер _lock_vrf(db, *vrf_ids) — pg_advisory_xact_lock(VRF_LOCK_NS, vrf_id) для каждого VRF, отсортированных по возрастанию id (исключает взаимную блокировку при операциях над несколькими VRF).
• Вызов добавлен в начале каждой операции, меняющей дерево или раскладку адресов, до любых чтений дерева:
  • create_prefix — по body.vrf_id, первой строкой обработчика;
  • allocate_subnet — сначала обычный SELECT vrf_id префикса-родителя (без блокировки строки), затем _lock_vrf, затем уже существующий SELECT … FOR UPDATE;
  • update_prefix при смене VRF — по исходному и целевому VRF, до вызова _move_to_vrf;
  • delete_prefix — по VRF префикса, до переподвешивания детей;
  • create_address — по VRF префикса, до проверки «самый узкий префикс»;
  • allocate_next — обычный SELECT vrf_id, затем _lock_vrf, затем существующий SELECT … FOR UPDATE по префиксу.
• Чтения (GET) не блокируются; операции над разными VRF друг друга не блокируют (независимые ключи advisory-lock).
• README.md, раздел «Модель данных»: одно предложение о сериализации изменений дерева одного VRF.

Отклонения от плана

Нет.

Как проверено

1. venv/bin/python -c 'import app.main' — без ошибок.
2. Стенд пересобран, healthy.
3. Сценарий из плана (20 повторов, временная организация rv3-tree-test, скрипт в scratchpad): в каждой итерации — свой /24-родитель, и параллельно (два потока) — явное создание .0/29 и автовыделение /30 из родителя (POST …/subnets/next {length:30}). Оба запроса каждый раз завершились без ошибок (0 ошибок из 40 запросов). Итоговое состояние дерева (отдельный GET после завершения обоих запросов пары — не тело ответа гонки, оно отражает лишь момент собственного commit) проверено на всех 20 итерациях: во всех случаях, когда выделенный /30 оказался внутри .0/29, его parent_id равен id .0/29, а не .0/24. 0 из 20 неверных parent_id. PASS.
   • Первый прогон теста дал 5 ложных срабатываний из-за ошибки самого теста (сверка велась по телу HTTP-ответа каждого из двух конкурентных запросов, которое отражает состояние дерева на момент commit именно этого запроса, а не финальное состояние после обоих); после исправления теста (повторный GET уже обоих префиксов после завершения гонки) все 20 итераций прошли успешно, а прямая проверка в БД (SELECT … FROM prefixes) подтвердила, что для всех 5 «проблемных» по первому прогону итераций конечное состояние в базе уже было верным (гонка не оставляла ошибочных данных, ошибался только клиентский тест).
4. Временная организация и все её префиксы удалены по завершении.

Не проверено

• Гонка при update_prefix (смена VRF, две блокировки) и при одновременном create_address/allocate_next в одном VRF — проверялась только комбинация create_prefix + allocate_subnet, явно описанная в плане; остальные точки вызова _lock_vrf проверены только чтением кода.
• Поведение под большей степенью параллелизма (более двух одновременных запросов) и при конкурентных операциях над разными VRF (что они не блокируют друг друга) — не измерялось.