Python Periodic Application Worker Writing

Периодический воркер application-операции

Реализуй тонкую долгоживущую задачу планирования, которая владеет собственным циклом, периодически вызывает уже собранную application-операцию и не знает её внутренних зависимостей.

Порядок работы

1. Изучи требования к ответственности конкретного воркера.
2. Определи режим расписания, единицы времени, интервалы, timeout, влияние публичного результата и политику ошибок.
3. Получи готовую application-операцию из composition root.
4. Реализуй внутри задачи один stop-aware цикл без бизнес-логики.
5. Добавь unit-тесты с управляемыми часами.

Если требования уже заданы, следуй им без дополнительного проектирования. Не придумывай расписание или политику повторов.

Граница ответственности

• Ответственность конкретного воркера определяется требованиями.
• Не объединяй независимые операции по умолчанию.
• Несколько операций допустимы только как одна связная ответственность с общими lifecycle, расписанием, масштабированием и политикой отказа.
• Разные интервалы, зависимости или правила масштабирования обычно означают разные воркеры.
• Ответственность воркера должна описываться одной короткой фразой.
• Публикатор, синхронизатор и очистка могут использовать один паттерн, но остаются разными конкретными воркерами.
• Каждая задача владеет только своим циклом. Не создавай общий цикл, который на каждой итерации последовательно вызывает все задачи процесса.
• Runtime запускает долгоживущие задачи и наблюдает их завершение, но не планирует отдельные итерации.
• В новом сервисе называть класс <OperationName>Task, размещать его в presentation/background/<operation_name>.py и предоставлять публичный run(). Не использовать суффикс Worker для задачи общего runtime.
• Получать готовые operation, stop event, heartbeat/readiness и параметры расписания через конструктор; не создавать внутри task composition root.

Application-операция

• Composition root собирает операцию со всеми портами и передаёт воркеру готовый callable.
• Воркер не создаёт Unit of Work, репозитории, адаптеры или use case внутри итерации.
• Воркер не знает, какие порты нужны операции.
• Воркер не интерпретирует предметные данные результата.
• Воркер может сопоставлять варианты публичного DTO-перечисления с заранее заданными действиями планирования, readiness и наблюдаемости.
• Допустимы None, DTO-перечисление или небольшой публичный результат с техническими показателями, если это предусмотрено контрактом.
• Отсутствие работы является нормальным успешным результатом.
• Результат влияет на следующий момент запуска только при явно заданной таблице вариантов; не выводи политику из имени или внутреннего смысла операции.
• Для каждого варианта результата отдельно определить влияние на readiness. Не считать любой нормально возвращённый DTO техническим успехом автоматически: результат, требующий повтора из-за невыполненной операции, может увеличивать счётчик ошибок без выбрасывания исключения.

Расписание

• Поддерживай явно выбранный требованиями fixed-delay, fixed-rate или result-aware delay.
• Не выбирай режим по умолчанию, если он не определён.
• Не допускай одновременных запусков одной операции.
• При fixed-delay отсчитывай интервал после завершения операции.
• При fixed-rate используй монотонные часы и не накапливай пропущенные запуски.
• Startup delay и jitter добавляй только по требованиям.
• Все ожидания должны прерываться stop event.
• Retry backoff не подменяет рабочий интервал.
• При result-aware delay для каждого варианта публичного результата явно задай немедленный запуск или stop-aware задержку. Ошибочный исход и timeout описывай отдельно от успешных вариантов DTO.
• В именах конфигурационных полей всегда указывай единицу времени. Преобразуй её в секунды только у вызова API asyncio, не смешивая значения разных единиц.

Подробная семантика приведена в periodic-worker-design.md.

Timeout и отмена

• Timeout одной итерации задавай только по требованиям и храни отдельно от интервала и shutdown timeout.
• После timeout полностью заверши или отмени текущую операцию до следующего запуска.
• Не подавляй CancelledError.
• При остановке дай текущей операции согласованное время на завершение; дальнейшая принудительная отмена принадлежит runtime.
• Не повторяй автоматически операцию, если результат внешнего побочного эффекта неизвестен.

Политика ошибок

Политика определяется публичным контрактом operation и требованиями:

• какие ожидаемые ошибки завершают только текущую итерацию;
• какие допускают повтор с отдельным backoff;
• какие являются фатальными для задачи;
• как обрабатывается timeout.

Если иное не задано, неожиданная ошибка должна завершать задачу, чтобы runtime сработал fail-fast. Не создавай скрытый бесконечный retry. Внутренние ошибки нижних слоёв не должны пересекать публичную границу application-операции.

Логирование

Применяй python-service-logging-writing и профиль конкретного процесса. Периодическая task владеет итогом каждой выполненной итерации и переходами readiness, которые вычисляет из результата operation.

• Создавай operation context только после получения идентификаторов текущей работы и очищай его в finally.
• Измеряй длительность итерации монотонными часами.
• Сопоставляй каждый публичный результат, ожидаемую ошибку и timeout с одним согласованным событием, уровнем, outcome и следующей задержкой.
• Записывай неожиданный окончательный сбой один раз перед его пробросом в runtime; runtime не должен повторять этот stack trace.
• Записывай переход readiness только при изменении состояния, не на каждой итерации.
• Не логируй полный DTO результата, пустой цикл, каждое ожидание и progress heartbeat, если профиль прямо этого не требует.
• Не логируй transport-детали исходящего адаптера как итог application-операции.

Progress heartbeat и readiness

• Если heartbeat означает завершение итерации, обновляй его после каждого завершённого цикла согласно требованиям. Не подменяй его независимым таймером.
• Счётчик последовательных ошибок и переходы readiness храни внутри конкретной задачи. Ожидаемый успешный вариант, включая отсутствие работы, не считай ошибкой.
• Технические порты heartbeat и readiness получай готовыми из composition root; не связывай задачу с HTTP, файлом или конкретной системой метрик.

Границы

В область скила входят:

• фабрика периодической task;
• fixed-delay и fixed-rate;
• stop-aware ожидание;
• отсутствие overlap;
• timeout итерации;
• политика ошибок и retry backoff;
• технические показатели результата;
• сопоставление DTO-результата с задержкой, progress heartbeat и readiness;
• unit-тесты расписания и вызова операции.

Не входят:

• lifecycle процесса, сигналы и управление ресурсами;
• NATS, HTTP, PostgreSQL и другие технологии;
• реализация application-операции и её портов;
• Unit of Work, outbox и репозитории;
• domain-логика.

Проверка результата

• Граница ответственности соответствует требованиям.
• Операция передаётся готовой извне.
• Режим расписания задан явно.
• Запуски не перекрываются, пропущенные fixed-rate интервалы не накапливаются.
• Остановка прерывает ожидание.
• Timeout и retry отделены от рабочего интервала.
• Неожиданные ошибки не скрываются.
• Итоги итераций, длительности и переходы readiness соответствуют logging-профилю и имеют по одной записи.
• Unit-тесты покрывают оба расписания, остановку, отсутствие overlap, пропуски, no-work, ошибки, timeout и отмену.
• Для result-aware delay тесты покрывают каждый вариант DTO, progress heartbeat и переходы readiness.
• Имя, размещение и публичный run() соответствуют общему runtime-каркасу.