clickstream-data-platform/docs/adr/0009-world-control.md

ADR 0009. Пульт мира: работники, выключатель и канонический контейнер

Дата: 13 августа 2026 года. Статус: принято. Реализация — тикет #79.

Решение

Ось модельного времени двигают даги пульта, и они двух родов.

Работники — без расписания и без паузы, запускаются руками:

• world_next_day — день пачкой; параметр «сколько дней» (умолчание 1) даёт разгон вперёд одним нажимом;
• world_live_day — один день в темпе живого режима.

Выключатель — без своей работы: world_live несёт расписание около двадцати пяти минут, создаётся на паузе и дёргает world_live_day через TriggerDagRunOperator, дожидаясь его завершения. Снят с паузы — стенд живёт день за днём; поставлен на паузу — мир встал на границе модельных суток.

Генератор задача зовёт через DockerOperator: тот поднимает образ clickstream-generator:local — тот самый канонический контейнер, внутри которого спека генератора обещает побайтовую воспроизводимость, — в сети стенда, командой batch или live.

Позиция на оси живёт переменной Airflow, как обещает раздел 8 той же спеки. Ставит её тот, кто сыграл день — работник, и только по успеху, значением «последний сыгранный день + 1». Выключатель к переменной не прикасается. День работник берёт из переменной, а не из логической даты прогона: календарь Airflow к оси мира отношения не имеет.

Пакетная автоматика — второй выключатель, дёргающий world_next_day, — отложена, а не отвергнута.

Почему

Работники без расписания, выключатели без работы. Иначе кнопка паузы значит две вещи разом: «мир не едет сам» и «даг выключен». Расписание на самом работнике формально живёт с ручным запуском — пауза, по документации Airflow 3, запрещает планирование, но ручной запуск разрешает, — только в списке дагов работник выглядит выключенным, а нажимают его каждый день. У предшественника стоит ровно эта форма: world_next_day с расписанием и на паузе, к ней объясняющий комментарий в коде и сторож assert_target_dag_not_paused на случай триггера в спящий даг. Разделение снимает и комментарий, и сторожа: работника никогда не ставят на паузу, поэтому дёргать спящего некому.

Канонический контейнер — условие обещания, а не вкус. Детерминизм генератора обещан внутри зафиксированного образа, и обещание держится только там. Поставить пакет прямо в образ Airflow, как делал предшественник, здесь нельзя даже механически: генератор требует Python 3.14, а apache/airflow:3.3.0 несёт 3.13. Собрать в образе Airflow второе окружение из того же uv.lock — можно, но это второе место установки генератора, пересборка образа Airflow на каждую правку мира и раскладка каталога товаров, повторённая монтированиями руками: образ генератора делает эту работу сам. Заодно DockerOperator держит генератор отдельной и заменяемой сущностью, как решил раздел 8 спеки, и показывает приём, у которого есть боевой родственник — так в бою запускают шаг подом.

Выключатель ждёт, и от этого зависит устойчивость. Не ждущий выключатель тикает по расписанию независимо от хода дня: живой день длится около двадцати четырёх минут, а у работника max_active_runs = 1, поэтому лишние триггеры скопились бы очередью прогонов, и мир потом промчался бы по ней без темпа. С ожиданием каденцию задаёт сама длина дня, а расписание остаётся грубым тиком «не пора ли снова»: пауза между днями равна остатку до следующего тика, до минуты.

Ждём триггером, а не сенсором. Различаются они тем, чем опознают прогон. TriggerDagRunOperator с wait_for_completion ждёт тот прогон, который сам и создал, — опрос идёт по его идентификатору. ExternalTaskSensor ждёт задачу чужого дага за конкретную логическую дату: пришлось бы передать работнику логическую дату и повторить её в сенсоре, то есть завести вторую бухгалтерию времени сразу после того, как решение выше её запретило. Сенсор здесь и как урок был бы поддельным: его дом там, где ждут события, которого сам не производишь, а у пульта производитель и потребитель — свои же даги. Тем же доводом ADR 0008 снял сенсор дневного батча. Настоящая механика показана и без него: родитель, ждущий чужого прогона, со ссылкой на дочерний прогон в интерфейсе и явными состояниями отказа — упал день, покраснел и выключатель. Это ADR 0003 в действии: зелёный конец графа не должен переживать отказ выше.

Позиция ставится, а не увеличивается. Правило дешевле сторожа. Если прогон выключателя наложится на ручной, худшее — день сыгран дважды: номера событий детерминированы, повтор схлопнет ReplacingMergeTree, а позиция останется верной. Увеличение на единицу в том же случае молча проглотило бы день, и мир получил бы дыру, которую никто не заметит. Ни пул как мьютекс, ни проверка «а не идёт ли другой прогон» после этого не нужны.

Худший исход у правила всё-таки есть, и он мягкий: работник, кончивший позже, ставит позицию по своему последнему дню и может отодвинуть её назад — так бывает, если долгий живой день закончится после разгона на три дня вперёд. Тогда часть дней переигрывается. Это дешевле дыры: переигранный день склеится, пропущенный не найдётся никогда.

Плата — сокет докера внутри Airflow. Доступ к нему равен праву root на машине, и пользователю airflow он открывается добавлением GID группы docker в контейнер. GID у каждой машины свой, поэтому он — локальная настройка и живёт в .env рядом с остальными такими, а не в описании стенда. Для локального учебного стенда размен принят — тот же, что уже принят для пароля в trace-журнале пробника, — но плата называется вслух и в README. Вторая плата мелкая: пока стенд живёт, из четырёх слотов parallelism заняты два, ждущий выключатель и работающий контейнер. Освободить слот ожидания умеет deferrable, но он требует компонент triggerer, которого стенд не поднимает; заводить службу ради одного ожидания дороже занятого слота.

Пакетная автоматика отложена, потому что своего желания у неё пока одно. «Шагни и стой» закрывает кнопка, «уедь на неделю сейчас» — параметр «сколько дней», «живи, пока я смотрю» — выключатель. Ей остаётся «едь сам быстрее, чем живёшь»: день за пять минут, часами, — каденция, которой у живого темпа нет (ускорение сверх ×60 спека отвергла как перемотку). Желание правдоподобное, но пока не названное, а форма известна и стоит тридцать строк: второй экземпляр выключателя на второго работника. Отложить дешевле, чем завести и объяснять.

Что отвергнуто ещё. Пульт на make с позицией в файле: дёшево сегодня, но раздел 8 спеки уже отдал позицию переменной Airflow, а этап 3 без дага не существует вовсе (ADR 0008) — платить пришлось бы дважды, и второй хранитель позиции разошёлся бы с первым. Один долгий прогон live на много дней: поток без швов, но позиция двигается только по успеху всего прогона, а такой прогон всегда обрывают — переменная не сдвинулась бы никогда, и обрыв на десятом дне откатывал бы все десять. Цепочка на ресурсах Airflow 3 (работник выпускает событие, выключатель на него подписан): каденция вышла бы точной и без ожидания, но снять выключатель с паузы недостаточно — цепочку надо толкнуть первым ручным прогоном, а читателю разбирать петлю «работник → ресурс → выключатель → работник». Цена расшифровки выше урока.

Следствия

Этапы 3 и 5 зовут генератор тем же приёмом: пакетный забор слепка заказов (ADR 0008) прирастает к тому же работнику, а etl_pipeline этапа 5 получает готовую обвязку DockerOperator и готовое правило позиции.

Расхождения, внесённые тем же коммитом: раздел 8 спеки генератора (позицию двигал «только даг next_day»; теперь — всякий, кто сыграл день, значением «сыгранный + 1») и раздел 1 там же вместе со словарём (живой день «не постоянный фон»; теперь фон у него есть, и у фона есть выключатель).

Что проверено

По документации Airflow 3 через MCP Context7 и живым замером образа, 13 августа 2026 года.

• Пауза дага запрещает планирование, но разрешает ручной запуск (core-concepts/dags.rst).
• TriggerDagRunOperator с wait_for_completion опрашивает прогон, который сам создал, по его идентификатору; без этого флага allowed_states, failed_states и poke_interval не действуют вовсе. Вариант deferrable требует компонент triggerer.
• ExternalTaskSensor ждёт задачу чужого дага за конкретные логические даты; сдвиги задаются execution_delta и execution_date_fn.
• Сенсор в режиме poke держит слот всё время, в режиме reschedule — только на время проверки.
• У DockerOperator network_mode принимает имя пользовательской сети, есть auto_remove и skip_on_exit_code.
• Образ apache/airflow:3.3.0 несёт Python 3.13.14 (замер запуском образа); генератор требует >=3.14,<3.15.
• Сокет докера на машине стенда — root:docker с правами 660, GID группы 127; пользователь образа Airflow — uid=50000(airflow) gid=0(root), в группе docker его нет. Значит доступ открывается добавлением GID в контейнер, а правка прав на хосте не нужна.

Осталось проверить при исполнении, и это работа тикета: какая версия провайдера apache-airflow-providers-docker встаёт к 3.3.0; что имя сети стенда (${COMPOSE_PROJECT_NAME}_default) достаётся дагу без ручной подстановки; что триггер доходит и дочерний прогон виден из выключателя; что два запуска подряд двигают позицию на два дня, а обрыв — ни на один.