beanstalkd/roadmap/epics/05-persistence.md

05. WAL, Job ID И Восстановление

Статус: не начат. Зависимости: 01, 02; интеграция 03, 04.

Цель

Изолировать журналы владельцев и обеспечить восстановление без пересечения ID, появления двух копий tube или незаметной потери совместимости данных.

Задачи

1. Определить layout общего data root, метаданных топологии и отдельных каталогов owner slots. Каждый WAL имеет одного writer и собственную блокировку.
2. Проверять топологию и layout до любых изменяющих операций с журналами; создавать начальные метаданные атомарно с необходимой durability, если сервер запускается с пустыми данными.
3. Задать формат decimal uint64 job ID и маршрутизацию к владельцу без глобального mutable каталога каждого job на критическом пути, если выбранная схема это позволяет.
4. Решить восстановление генератора ID при частичном restart: чтения максимального ID среди живых jobs недостаточно, если большие ID уже удалены. Учитывать старые сообщения/сессии и generation fencing; документировать срок гарантий уникальности.
5. Определить переполнение и исчерпание диапазона ID: контролируемый отказ вместо wraparound и коллизий.
6. Сохранить порядок FIFO внутри tube при изменении ID. Если вводится отдельный sequence, определить момент выдачи и запись/восстановление; не изменять порядок поступления относительно текущей версии без решения.
7. Запускать replay каждого owner отдельно. До готовности replay его partition space недоступен; frontend не перенаправляет операции к соседям.
8. Восстанавливать jobs в соответствии с текущей семантикой WAL, не считать клиентские резервации пережившими restart. Старые frontend-сессии не продолжают работу поверх восстановленных jobs.
9. Проверить compaction, segment rotation, file references, disk-full/short write/fsync errors и взаимодействие с подтверждением команд.
10. Реализовать выбранную в 01 политику старого WAL: отдельный offline import с сохранением оригинала либо явный отказ нового режима. Если отдельный legacy сохраняется, он читает прежний формат.

Ограничения

• Нельзя совместно писать независимыми owners в существующий binlog-каталог, даже если убрать waldirlock.
• Tube descriptor не становится персистентным объектом: имя восстанавливается из живых jobs. Пустые клиентские tubes не обязаны переживать restart.
• Частичный перезапуск без WAL теряет данные только соответствующего owner по заявленному контракту; это нельзя выдавать за восстановление или HA.
• С -b границы потери данных определяются реальной записью и настройками fsync. Не требовать отсутствия любых потерь при -F и не ослаблять -f 0 под видом ускорения.
• При изменении Jobrec следовать процедуре Walver в dat.h, включая чтение старых версий. Многопроцессность сама по себе не требует изменения Jobrec.
• Онлайн-миграция и изменение карты не входят в эпик. Увеличение числа slots с переназначением partitions требует отдельной offline-процедуры, не простого изменения config.

Приёмка

• Два owners одновременно записывают задания, используют разные WAL и не пересекающиеся ID.
• После удаления всех jobs и частичного restart генерация ID не создаёт опасных коллизий по утверждённому контракту; тест включает запоздалые сообщения старого поколения.
• Неизменная топология восстанавливает jobs в правильных tubes и owners; несовместимая карта не меняет существующие файлы при отказе запуска.
• Полный/частичный restart проверен с ready, delayed, buried и ранее reserved jobs; внешние сессии не сохраняют ложное владение восстановленными jobs.
• Ошибка одного WAL не повреждает файлы другого. Реакция логического сервера соответствует 01/06.
• Проверены crash windows до/после записи и подтверждения, compaction, rotation, недостаток места и повреждённый журнал.
• Старые данные остаются пригодны для legacy либо импортируются явным инструментом согласно выбранной политике; исходник не уничтожается автоматически.
• Документированы ID layout, topology metadata, срок гарантий ID, WAL compatibility и ограничения durability.

Точки Кода

job.c:make_job_with_id/next_id/job_pri_less, dat.h:Jobrec/Walver/Wal/File, walg.c, file.c, serv.c:srv_acquire_wal, prot.c:prot_replay, WAL-тесты в testserv.c.