Search by

fedor / work-orchestrator

wolfcharaa

Finite concurrent and parallel work orchestration with managed subprocess lifecycles

Package info

github.com/wolfcharaa/work-orchestrator

pkg:composer/fedor/work-orchestrator

Statistics

Installs: 10

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.4.1 2026-11-19 12:09 UTC

This package is auto-updated.

Last update: 2026-11-19 12:10:50 UTC


README

English

fedor/work-orchestrator запускает конечный набор задач приложения в нескольких процессах ОС и возвращает единый результат запуска. Библиотека управляет выдачей задач, ограничениями параллелизма, отменой, событиями и завершением worker-процессов. Приложение по-прежнему определяет смысл задачи, работу с БД и файлами, транзакции, повторяемость операций и долговременное хранение состояния.

Библиотека подходит, когда набор работ можно сформировать до запуска и нужно ограниченно распределить его между процессами. Она не является очередью сообщений, планировщиком фоновых заданий или механизмом checkpoint/resume после полной остановки приложения.

Минимальная модель

  • root-процесс — исходный процесс приложения: хранит очередь, решает, какую задачу можно выдать, собирает события и результаты;
  • primary worker — дочерний процесс первого уровня: выполняет пользовательскую Strategy и переиспользует созданные в нём ресурсы;
  • child worker — необязательный процесс второго уровня: выполняет управляемую подзадачу стратегии;
  • admission (допуск) — решение очереди выдать задачу сейчас, подождать условие или сообщить, что задач больше нет;
  • payload (данные задачи) — небольшое сериализуемое сообщение для worker, обычно идентификатор, путь, ключ или диапазон;
  • IPC (inter-process communication, межпроцессное взаимодействие) — канал, по которому передаются задачи, события и результаты;
  • cancellation (отмена) — сигнал прекратить выдачу новой работы и совместно завершить уже начатую.

Полные определения и схема первого запуска находятся в руководстве по началу работы.

Установка и первый результат

Требуются PHP 8.4+ и Composer:

composer require fedor/work-orchestrator:^0.4

В checkout репозитория первый воспроизводимый сценарий запускается так:

composer example:basic

Ожидаемый вывод:

customer:42 => 42
customer:77 => 77
run => succeeded

Сценарий создаёт две задачи с устойчивыми WorkId, допускает их через OrderedWorkQueue, выполняет RebuildCustomerStrategy в двух primary workers и печатает результаты в порядке очереди. Классы payload и стратегии лежат в examples/Basic, поэтому Composer может загрузить их и в новых worker-процессах. В приложении такие классы должны находиться в его собственном PSR-4 namespace; объявлять их только внутри запускаемого скрипта нельзя.

AI skill для интеграции

Пакет поставляет skill work-orchestrator для coding agents. Если проект использует llm/skills, установите plugin как dev dependency и синхронизируйте skill из установленной библиотеки:

composer require --dev llm/skills
composer skills:update fedor/work-orchestrator

Затем вызовите $work-orchestrator. До выбора классов или написания кода skill интерактивно уточнит конечный набор работ, наблюдаемый результат, identity и payload, порядок/барьеры, process-local ресурсы, подзадачи, retry/idempotency, cancellation и владельца durable recovery. После ответов он покажет единый Integration Contract и попросит подтвердить его.

Исходник skill находится в resources/skills/work-orchestrator.

Куда идти дальше

Задача Руководство
Понять сериализацию, WorkId, результат и ограничения первого запуска Начало работы
Выбрать обычную, групповую, файловую или собственную очередь Очереди, барьеры и расширение допуска
Создать process-local ресурсы или разнести подзадачи по Fiber/child workers Управляемые задачи
Подключить hooks, события, диагностику и восстановление Наблюдаемость и восстановление
Найти роль конкретного публичного класса или интерфейса Справочник публичного API
Разобрать протокол root → primary → child Runtime-протокол
Запустить parse-normalize-write для NDJSON Пример импорта записей

Гарантии и границы

Orchestrator одноразовый: после начала run() его нельзя перенастроить или запустить повторно. Возвращаемый RunResult сохраняет успешные и неуспешные исходы уже допущенных задач, ограниченную диагностику и ошибки observers.

Ядро не парсит XML/CSV/JSON, не открывает транзакции, не хранит durable inbox/outbox и не выбирает бизнес-порядок. Большие данные не следует переносить через IPC: worker должен получить рецепт доступа к ним и открыть ресурс локально. После смерти всего runtime решение о новом запуске и защита от повторных эффектов принадлежат приложению или оператору.

Миграция с fedor/async-parser

Линия 0.4 — несовместимое переименование без compatibility aliases. Package и namespace стали fedor/work-orchestrator и Fedor\WorkOrchestrator; AsyncParser::fromFiles() заменён явной композицией Orchestrator::fromQueue(FileWorkQueue::discover(...)); вместо file-specific handler registry используется Strategy с опциональными capability-интерфейсами. Обновляйте constraint, imports и composition одним согласованным изменением.

Изменения релизов: CHANGELOG.md.