fedor / work-orchestrator
Finite concurrent and parallel work orchestration with managed subprocess lifecycles
Requires
- php: ^8.4.1
- amphp/amp: ^3.1
- amphp/parallel: ^2.4
- psr/container: ^2.0
- symfony/finder: ^8.1
Requires (Dev)
- amphp/file: ^4.0
- friendsofphp/php-cs-fixer: ^3.89
- llm/skills: ^1.20
- phpstan/phpstan: ^2.3
- phpstan/phpstan-strict-rules: ^2.1
- testo/testo: ^0.10
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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.