Rewrite contributte/scheduler on top of symfony/scheduler

[ohmyfelix]

Goal

Rewrite contributte/scheduler to be a real Nette integration for symfony/scheduler, following the same overall concept that contributte/messenger uses for symfony/messenger.

Why

The current package is still a custom cron/callback runner with its own runtime model (IJob, IScheduler, scheduler:run, lock files, callback jobs).
That works, but it is not aligned with Symfony Scheduler's architecture and misses the richer ecosystem around schedules, recurring messages, Messenger workers, runtime events, stateful execution, and locks.

contributte/messenger is already a strong example of how Contributte integrates a Symfony component into Nette:

• one DI extension as the public entry point
• internal compiler passes by concern
• native Symfony runtime/services exposed in Nette
• good docs and focused DI/E2E tests

contributte/scheduler should move in the same direction.

Current situation

Today contributte/scheduler is centered around:

• IJob and IScheduler
• Scheduler / LockingScheduler
• config-driven scheduler.jobs
• callback jobs and custom job classes
• custom commands:
  • scheduler:run
  • scheduler:list
  • scheduler:force-run
  • scheduler:help

That model is fundamentally different from Symfony Scheduler, which is based on:

• ScheduleProviderInterface
• Schedule
• RecurringMessage
• Messenger-backed scheduler transports
• messenger:consume scheduler_<name>
• debug:scheduler
• optional runtime events, stateful cache, and lock integration

Proposed direction

Rebuild the package as a thin Nette bridge over Symfony Scheduler, similar in spirit to contributte/messenger.

Core design

• Keep a single SchedulerExtension as public DI entry point.
• Split integration into small passes, e.g.:
  • ProviderPass
  • TaskPass
  • TransportPass
  • EventPass
  • ConsolePass
  • DebugPass
• Make Symfony Scheduler concepts the primary API:
  • ScheduleProviderInterface
  • Schedule
  • RecurringMessage
  • #[AsSchedule]
• Support Symfony task attributes as an upper layer:
  • #[AsCronTask]
  • #[AsPeriodicTask]

Runtime integration

• Register a schedule-provider locator.
• Register SchedulerTransportFactory.
• Create one Messenger transport per schedule:
  • scheduler_<name> -> schedule://<name>
• Reuse Messenger worker flow:
  • messenger:consume scheduler_<name>
• Register scheduler event bridge:
  • DispatchSchedulerEventListener
• Register ServiceCallMessageHandler for service/method-based task definitions.
• Expose native scheduler debug tooling:
  • debug:scheduler

Dependencies

Likely runtime direction:

• php >=8.2
• nette/di
• symfony/scheduler
• symfony/messenger
• symfony/console

Optional integrations:

• dragonmantank/cron-expression
• symfony/cache
• symfony/lock
• symfony/event-dispatcher

Migration strategy

This is not a small refactor; it is a model change.

Recommended compatibility layer

Keep the scheduler extension name, but introduce a transition layer that compiles legacy config into Symfony schedules where possible.

Preserve temporarily:

• scheduler.jobs
• callback-based jobs
• service-based jobs
• scheduler.path semantics via a lock adapter

Deprecate:

• IJob
• IScheduler
• Scheduler
• LockingScheduler
• custom imperative runtime access
• legacy custom commands that do not map cleanly to Symfony Scheduler

Command migration

Keep/review:

• debug:scheduler as first-class

Deprecate or replace:

• scheduler:run -> use messenger:consume scheduler_<name>
• scheduler:list -> use debug:scheduler
• scheduler:force-run -> likely no direct equivalent; either drop or reintroduce only as an explicit compatibility tool
• scheduler:help -> not needed once docs and native tooling are in place

Iteration plan

Iteration 1 - Symfony-native MVP

Implement the clean core first:

• explicit ScheduleProviderInterface services
• schedule provider discovery
• scheduler transports
• messenger:consume scheduler_<name>
• debug:scheduler
• minimal docs and tests

This gives the cleanest architecture and proves the bridge works.

Iteration 2 - Compatibility layer

Add migration support for current users:

• compile legacy scheduler.jobs into recurring messages
• support callback/service-based task definitions
• map scheduler.path to Symfony lock support
• emit deprecations for old API/commands

This reduces upgrade pain.

Iteration 3 - High-level ergonomics

Add developer-friendly features:

• #[AsSchedule]
• #[AsCronTask]
• #[AsPeriodicTask]
• config-defined tasks/messages
• optional stateful cache support
• optional event-dispatcher integration
• improved examples and cookbook docs

Testing plan

Add real coverage, not only config parsing:

• DI compile tests
• provider discovery tests
• legacy config migration tests
• attribute-based task tests
• lock integration tests
• stateful schedule tests
• console command tests
• E2E worker/schedule scenarios

Docs plan

Update docs to include:

• installation
• Messenger dependency/integration story
• minimal setup
• schedule providers
• task attributes
• locks and stateful mode
• consuming schedules
• debugging
• migration guide from legacy scheduler.jobs

Open questions

• Should contributte/messenger become a hard dependency, or should contributte/scheduler wire symfony/messenger directly?
• How much of the old scheduler.jobs config should be preserved during transition?
• Should scheduler:force-run exist in the new world at all?
• Is this rewrite released as the next major version only?

Acceptance criteria

• Package is centered on symfony/scheduler, not a custom in-process scheduler loop.
• Nette users can define schedules/providers and consume them via Messenger workers.
• debug:scheduler works in Nette apps.
• There is a documented upgrade path from current contributte/scheduler.
• Tests cover DI, runtime wiring, and realistic schedule execution scenarios.

[ohmyfelix]

Adding a more detailed implementation plan with phases and actionable TODOs.

Detailed plan

Phase 0 - Architecture decisions and scope freeze

Goal: lock the public direction before writing code.

TODOs:

• Decide whether contributte/messenger becomes a hard dependency or whether contributte/scheduler wires symfony/messenger directly.
• Confirm target support matrix: PHP, Nette, Symfony component versions.
• Confirm whether this rewrite ships only in the next major version.
• Freeze the current legacy surface that we intentionally support during migration:
  • scheduler.jobs
  • scheduler.path
  • callback jobs
  • service/class jobs
  • legacy commands
• Decide which legacy commands are deprecated immediately vs. temporarily bridged.
• Decide whether IJob / IScheduler remain as soft-compat interfaces for one transition release.

Definition of done:

• one agreed direction for dependency model
• one agreed BC/deprecation policy
• one agreed versioning/release target

---

Phase 1 - Project skeleton and dependency alignment

Goal: prepare the package structure for a Symfony-style integration.

TODOs:

• Update composer.json requirements to the new target stack.
• Add/align optional packages used in tests/examples:
  • symfony/messenger
  • symfony/console
  • symfony/event-dispatcher
  • symfony/cache
  • symfony/lock
  • dragonmantank/cron-expression
• Replace the current monolithic DI setup with pass-based architecture.
• Introduce src/DI/Pass/ and shared DI utilities similar in concept to contributte/messenger.
• Add extension constants for internal tags/service contracts.
• Define deterministic service naming conventions (provider.*, transport.*, console.*, etc.).
• Prepare test toolkit/helpers for compiling containers with multiple scheduler scenarios.

Definition of done:

• extension compiles with the new internal structure
• no runtime features yet required, but foundation is ready

---

Phase 2 - Native Symfony Scheduler core

Goal: support the real Symfony Scheduler model first.

TODOs:

• Introduce provider discovery around ScheduleProviderInterface.
• Register named schedule providers into a locator/container.
• Add config for explicit providers, e.g. scheduler.providers.
• Register SchedulerTransportFactory.
• Register one scheduler transport per schedule using schedule://<name>.
• Define the transport naming convention exposed to users (scheduler_<name> or equivalent).
• Register ServiceCallMessageHandler for service-call based scheduled tasks.
• Add support for explicit generated schedules/messages from config.
• Validate duplicate schedule names and invalid provider references at compile time.
• Fail early with good messages when required optional features are configured without their packages.

Definition of done:

• Nette app can register schedule providers
• Scheduler transports are available
• schedules can be consumed through Messenger worker flow

---

Phase 3 - Config model for Nette users

Goal: provide an ergonomic Nette-first API on top of Symfony concepts.

TODOs:

• Design final config schema for:
  • scheduler.providers
  • scheduler.schedules
  • generated recurring messages/tasks
  • per-schedule lock configuration
  • per-schedule stateful cache configuration
  • processOnlyLastMissedRun
• Support recurring message definitions for:
  • cron-based tasks
  • periodic tasks
  • custom trigger services/statements
• Support service/method tasks with arguments.
• Support named schedules beyond default.
• Decide config precedence between explicit NEON config and discovered attributes/providers.
• Make validation strict and compile-time oriented.

Definition of done:

• minimal and full config examples are both representable in NEON
• invalid config fails during container compilation with actionable errors

---

Phase 4 - Attribute support

Goal: add high-level developer ergonomics.

TODOs:

• Support #[AsSchedule] discovery.
• Support #[AsCronTask] discovery.
• Support #[AsPeriodicTask] discovery.
• Add reflection utilities to collect task metadata from classes/methods.
• Compile discovered attributes into generated provider/task definitions.
• Define precedence rules:
  • explicit NEON overrides attributes
  • duplicate declarations fail clearly
• Validate method signatures and task argument mapping.

Definition of done:

• users can build schedules either explicitly in NEON or with Symfony attributes
• behavior is deterministic and covered by tests

---

Phase 5 - Runtime integration: events, locks, state, execution

Goal: make the bridge production-usable.

TODOs:

• Register scheduler event integration via DispatchSchedulerEventListener.
• Reuse existing event dispatcher service when present; otherwise register a fallback if needed.
• Map old scheduler.path behavior to a symfony/lock-based compatibility strategy.
• Add per-schedule lock support for native schedules.
• Add per-schedule stateful cache support.
• Support processOnlyLastMissedRun() where configured.
• Document and test the new runtime behavior differences vs legacy scheduler loop.
• Ensure failure behavior is clear when message handlers throw.

Definition of done:

• schedules can run with locks/state support
• runtime events are dispatched correctly
• behavior is documented and testable

---

Phase 6 - Legacy compatibility layer

Goal: reduce upgrade pain for existing contributte/scheduler users.

TODOs:

• Compile legacy scheduler.jobs into generated recurring messages where possible.
• Support callback job config:
  • [ @service, method ]
  • Class::method
• Support service/class job config:
  • class name
  • service reference
  • {class: ..., inject: true} transitional form
• Decide and implement the fate of IJob custom jobs:
  • adapter bridge, or
  • deprecation with limited support
• Emit deprecations for old config keys and runtime APIs.
• Keep compatibility code isolated so it can be removed in the next major cleanup.

Definition of done:

• common old setups can be upgraded with minimal breakage
• unsupported legacy patterns fail clearly with migration hints

---

Phase 7 - Console and DX

Goal: provide the correct operational tooling.

TODOs:

• Register debug:scheduler.
• Ensure scheduler transports work with Messenger consume commands.
• Decide whether to keep wrappers for any old commands:
  • scheduler:run
  • scheduler:list
  • scheduler:force-run
  • scheduler:help
• If wrappers are kept temporarily, mark them as deprecated and delegate to the new model where sensible.
• Ensure command registration works nicely with contributte/console.
• Add examples for local/dev/prod execution patterns.

Definition of done:

• correct commands are available in Nette apps
• users understand the new execution model

---

Phase 8 - Tests

Goal: cover both the new model and the migration path.

TODOs:

• Add DI tests for valid minimal setup.
• Add DI tests for invalid config and compile-time errors.
• Add provider discovery tests.
• Add attribute discovery tests.
• Add generated schedule/task config tests.
• Add lock integration tests.
• Add stateful cache tests.
• Add console wiring tests.
• Add E2E tests for worker-driven schedule execution.
• Add migration tests for legacy scheduler.jobs and deprecated commands.

Definition of done:

• core integration and migration behavior are both covered
• test suite protects the next refactors

---

Phase 9 - Docs and release preparation

Goal: make the rewrite adoptable.

TODOs:

• Rewrite .docs/README.md around Symfony Scheduler concepts.
• Add installation/setup docs with companion packages.
• Add minimal config example.
• Add advanced config example.
• Add attribute-based examples.
• Add worker/consume examples.
• Add lock/stateful examples.
• Add migration guide from current scheduler.jobs model.
• Add changelog / upgrade notes.
• Tag remaining follow-up improvements as separate issues.

Definition of done:

• users can install, configure, run, and migrate without reading source code

---

Suggested implementation order

1. Phase 0
2. Phase 1
3. Phase 2
4. Phase 8 for core coverage in parallel with Phase 2/3
5. Phase 3
6. Phase 4
7. Phase 5
8. Phase 6
9. Phase 7
10. Phase 9

Suggested first milestone

A good first implementation milestone would be:

• Phase 1
• minimal slice of Phase 2
• minimal slice of Phase 8

That means:

• pass-based extension skeleton
• explicit ScheduleProviderInterface registration
• scheduler transport factory wiring
• one working schedule consumed through Messenger
• one or two compile/E2E tests proving the concept

Once that lands, the rest can iterate safely.