Scheduler Queues Laravel Package

Technical Evaluation

Architecture fit. liberusoftware/scheduler-queues is a vertical module in the Liberu ecosystem (liberusoftware/module-*), not a standalone library. Its scope — unique/idempotent job policy, schedules, locks, retries, failure handling, monitoring, and graceful-deployment conventions — is a conventions layer over Laravel primitives that already exist in the framework: ShouldBeUnique / ShouldBeUniqueUntilProcessing, WithoutOverlapping middleware, Illuminate\Console\Scheduling\Schedule with onOneServer(), retryUntil(), failed_jobs, and Horizon for visibility. The package's value is therefore not capability but codified opinion: a house style for how a fleet of scheduled and queued work behaves under deploy. That is genuinely useful in a modular monolith with many teams, and near-worthless in a small app that already has tribal conventions.

Fit is good if the application is already a Liberu modular install (module registry, service-provider bootstrapping, shared cache/lock store). Fit is poor if we would be importing the module loader and its conventions purely to get idempotency helpers we could write in an afternoon.

Integration feasibility. Mechanically straightforward: Composer install, service provider registration, publish config, point it at a lock store. The real feasibility question is the lock backend. Deterministic idempotency and non-overlapping execution require a shared atomic store — Redis or a properly configured database/array-free cache driver. On a single-node deploy with file cache, the guarantees degrade silently, which is worse than not having the package. Multi-node and blue/green deployments also require that the lock store survive application restarts, since that is precisely the window "graceful deployment conventions" is meant to cover.

Technical risk (high). The adoption signals are the story here:

Secondary risks: single-maintainer bus factor; API churn while the module set stabilises (pinning is mandatory, no ^ ranges); coupling to a bespoke module bootstrap that can conflict with our own service-provider ordering; and — most insidious — behavioural overlap with native Laravel. Two competing idempotency mechanisms in one codebase produces jobs that are "unique" by one rule and not the other, and nobody can reason about the invariant.

Key questions for the maintainer / spike.

1. Does it require the Liberu module loader, or can it be consumed as a plain Laravel package with a standard service provider?
2. Which lock store does it assume, and what happens under file/array cache — hard fail or silent no-op?
3. How does uniqueness interact with Horizon, queue:restart, and in-flight jobs during a rolling deploy? Are locks TTL-bounded and reclaimable after a crashed worker?
4. Is there a documented migration path off the package (are the conventions expressible as native middleware)?
5. What is the test suite coverage, and is CI green on our Laravel/PHP matrix?
6. Who is on the hook for security patches, and what is the release cadence?

Integration Approach

Stack fit. Target a modern Laravel (11/12) + PHP 8.2+ application on Redis with Horizon, deployed across ≥2 nodes or in blue/green. Below that bar — single node, file cache, no Horizon — the package's guarantees are largely theoretical and the integration cost is not repaid.

Migration path. Do not retrofit existing jobs. Sequence it:

1. Inventory. Catalogue every scheduled command and queued job; mark which are already idempotent, which are unique-by-accident, and which have actually double-fired (check logs and failed_jobs).
2. Spike (1–2 sprints, timeboxed). Install in a sandbox branch. Prove three behaviours in isolation: (a) a duplicate dispatch is rejected under concurrency, (b) a lock is reclaimed after a simulated worker kill, (c) a deploy during a running schedule does not double-execute. Nothing else matters until these are demonstrated.
3. Parallel run. Apply the conventions to one low-risk recurring workload — cache warming, digest email, report generation — with the legacy path retained behind a flag.
4. Abstract. Put our own thin interface (IdempotentJob, ScheduledTask contracts) in front of the package so the vendor dependency is one adapter file, not a hundred job classes. This is the single highest-leverage decision in the integration.
5. Widen to higher-risk workloads only after a full deploy cycle with clean telemetry.

Compatibility. Pin exact versions; no floating constraints. Confirm the module's service provider doesn't reorder or double-register Schedule bootstrapping. Test against the same Redis version as production — lock semantics differ between single Redis, Sentinel, and Cluster (Redlock-style implementations are frequently incorrect on Cluster).

Sequencing relative to native Laravel. Run a deliberate bake-off before committing: implement the same two representative jobs twice, once with native ShouldBeUnique + WithoutOverlapping + Horizon, once with the package. Compare lines of code, clarity for a mid-level engineer, and observability. If native is within ~20% on those axes — likely — the package only pays off if we are adopting the broader Liberu module set for other reasons.

Operational Impact

Maintenance. We become the maintainers of record for a 0-star, 0-dependent, single-vendor dependency. Realistic posture: fork it on day one into our org, track upstream by rebase, and assume we own every bug within a quarter. Budget ~0.1–0.2 FTE ongoing for a fork, plus a CVE-watch entry in the dependency register. MIT makes this clean legally; it does not make it free operationally.

Support. No community, no Stack Overflow corpus, no third-party blog posts. On-call engineers will be debugging unfamiliar middleware at 3 a.m. with the source as the only documentation. Mitigation: an internal runbook covering lock keys, TTLs, and the "how do I safely clear a stuck lock" procedure — written before go-live, not after the first incident.

Scaling. Lock traffic scales with dispatch volume, not job volume; high-fanout dispatch patterns put real load on Redis. At multi-region or Redis Cluster, uniqueness guarantees need re-validation — cluster-aware locking is the most common place these libraries quietly break. Scheduler semantics are also a one-server concern: onOneServer() plus an external lock store is the only configuration that survives horizontal scale-out.

Failure modes to instrument explicitly.

• Silent no-op — misconfigured cache driver causes uniqueness to be skipped rather than to error. Make startup fail loudly if the driver is file/array in a non-local environment.
• Orphaned locks — worker dies mid-job, lock persists, job never runs again. Alert on jobs whose expected cadence is missed, not just on failures.
• Deploy-window double-fire — the exact scenario the package exists to prevent; validate it in staging with a deliberately overlapping deploy.
• Thundering herd on release — locks released en masse after a rollout, producing a burst that saturates the queue.
• Monitoring blind spot — the package's own monitoring must feed our existing alerting (Horizon metrics, APM), not a parallel dashboard nobody opens.

Ramp-up. Half a day for a senior Laravel engineer to read the source and config; one to two sprints to get a team fluent in the conventions and their failure modes. Add explicit onboarding material, because the knowledge is not externally searchable and is entirely contained in whoever did the integration.

Recommendation. Treat as a conditional pilot, not a platform commitment. Worth one timeboxed spike if (a) we are already on the Liberu modular stack, or (b) we have a demonstrated, recurring duplicate-execution problem that native ShouldBeUnique + WithoutOverlapping + Horizon does not solve. Without either condition, the 0/0 adoption profile and future-dated release metadata outweigh the modest opportunity score — implement the conventions in-house behind our own contracts, and revisit if the module set gains real dependents. Gate the decision on the six questions above; if questions 1, 2, and 4 lack written answers, decline.