beanstalkd/roadmap/epics/01-contract.md

01. Контракты И Baseline

Статус: не начат. Зависимости: нет.

Цель

До изменения модели исполнения зафиксировать проверяемые границы совместимости, интерфейсы процессов и условия сравнения производительности. Принятое архитектурное направление не является утверждением всех деталей ниже.

Задачи

1. Сопоставить doc/protocol.txt с prot.c, conn.c, job.c, tube.c и WAL. Зафиксировать значимые расхождения кода и документации, не исправляя их попутно без отдельного решения.
2. Описать роли supervisor, frontend, owner; определить число frontend и способ принятия соединений. Не создавать центрального диспетчера всех queue-операций без измерения его предела.
3. Определить opt-in нового режима, конфигурацию топологии и совместимость со старым запуском, TCP/Unix sockets, socket activation, сменой пользователя и сигналами.
4. Снять baseline существующей версии: CPU, throughput, latency, память и WAL I/O. Сохранить воспроизводимые команды и параметры.
5. Подготовить таблицу состояний сессии, ожидания reserve, передачи ответа, аварии frontend и owner. Указать точки изменения состояния и подтверждения операции.

Решения До Реализации

Вопрос	Ограничение для решения	Где реализуется
Переход и legacy	Выбрать сохранение отдельного legacy с opt-in либо согласованный переход на новую архитектуру. Два режима не являются уже утверждённым обязательством; новый режим с одним owner не равен прежнему серверу по возможностям	04, 05, 06, 07
Multi-watch reserve	Не выбирать первую tube и не выдавать TIMED_OUT как будто очередь пуста. Выбрать документированный отказ/закрытие или явно согласованное расширение; не объявлять такой ответ стандартом 1.13	04
Наблюдение одной tube, резервации нескольких	Сохранить reserve-job, смену watch list и проверки TTR/DEADLINE_SOON по всем резервациям сессии; дополнительное ограничение требует отдельного согласования	03, 04
Неизвестный результат мутации	Не повторять put автоматически. Определить закрытие соединения и судьбу сессии при разрыве IPC; request ID не даёт durable exactly-once	03, 06
Сбой владельца	Выбрать политику затронутых TCP-сессий; безопасная исходная стратегия: закрыть затронутые сессии и очистить их ссылки у остальных владельцев. Не продолжать старые резервации после replay как будто аварии не было	03, 05, 06
Формат топологии	Фиксировать hash/version/seed при наличии, число разделов, карту, slot IDs, fingerprint. Проверять до открытия WAL для записи	02, 05
Job ID	Decimal uint64 на wire; уникальность, маршрутизация, порядок внутри tube, переполнение и частичные перезапуски. Определить импорт старых ID	04, 05
Старый WAL	Выбрать явный offline import либо контролируемый отказ нового режима; исходные данные не изменять автоматически. Если legacy сохраняется, он должен читать прежние данные	05
Диагностика	Определить смысл pid, id, uptime, rusage-*, binlog-полей и счётчиков после частичного перезапуска	04, 06
Платформы	Определить поддерживаемые платформы новой архитектуры и политику остальных; если legacy сохраняется, его существующие платформы не регрессируют. Linux-first допустим только как явная граница	03, 06, 07
Численные лимиты	Утвердить лимиты IPC/body buffering, сроки очистки умерших сессий, restart policy и критерии производительности	03, 06, 07

Открытые решения оформлять в соответствующем документе как выбранный контракт с обоснованием. Внешние ограничения сверх одной наблюдаемой tube выносить на согласование, а не выбирать неявно в коде.

Baseline

• Матрица: одна/много tubes, один/много клиентов, короткие/крупные bodies, ready/delayed workload, WAL off/on, обычный fsync и -f 0.
• Генератор нагрузки не должен насыщать CPU раньше сервера. Фиксировать CPU affinity, оборудование, ОС, compiler/CFLAGS, размеры данных и семя распределения.
• Измерять завершённый lifecycle put -> reserve -> delete и отдельные операции; точно определить единицу throughput.
• Выполнить профилирование: обход tubes в next_awaited_job и soonest_delayed_job, системные вызовы, копирование, WAL. Не считать кандидатов доказанными bottlenecks без профиля.
• Не менять алгоритмы исходной версии в рамках снятия baseline.

Приёмка

• Для каждой строки таблицы есть выбранное поведение либо явно блокируемая ею реализация; блокирующие решения закрыты до начала зависимых изменений.
• Сценарии transient multi-watch, смены tube с живой резервацией и reserve-job другой tube присутствуют в тест-плане.
• Есть спецификация запуска, топологии, session identity, command ownership и ошибок.
• Есть сохранённый baseline и заранее заданные критерии сравнения для эпика 07.

Точки Кода

main.c, util.c:optparse, net.c, serv.c, prot.c:dispatch_cmd, conn.c, dat.h, Makefile, testserv.c.