RQ

Requires RQ 1.10.1+ and <3, Python 3.11+. See the compatibility matrix for the full pin string.

Install

pip install z4j-rq

What it captures

RQ does not expose a worker middleware system. z4j wraps the class that owns Worker.execute_job, the parent-side execution boundary, and also provides optional per-job callback functions.

Hook	z4j event
Before `Worker.execute_job`	`task.started`
Finished job status after `Worker.execute_job`	`task.succeeded`
Failed or stopped status after `Worker.execute_job`	`task.failed`
Explicit per-job stopped callback	`task.revoked`

Actions

Verb	How
`submit`	enqueue the import-path task name on the selected queue
`retry`	requeue a failed job by reference; complete operator-supplied replacements use a new enqueue
`cancel`	`send_stop_job_command` if running; `job.cancel()` if queued, deferred, or scheduled
`purge_queue`	guarded `queue.empty()`
`bulk_retry`	retry explicit project-owned task IDs only, capped at 10,000
`requeue_dead_letter`	requeue from RQ's `FailedJobRegistry`

Multiple queues

RQ uses many queues per app. The adapter discovers queues through Queue.all(connection) when it builds queue and task snapshots. Each queue appears separately in the dashboard with its own counts.

RQ-worker-pool

rq-worker-pool works fine - each worker in the pool registers as its own agent. Use agent_name with $PID to distinguish.

Caveats

Failed queue - RQ moves failures to a FailedJobRegistry. z4j uses that registry for retry and dead-letter requeue actions; lifecycle visibility comes from the worker hook.
Scheduler actions - the rq-scheduler companion supports list, trigger, destructive disable, and delete. It does not support create, update, or enable; re-enable by registering the job again from application code.
Dependencies - job.depends_on chains show in the dashboard as "waiting on".

Config

Pass the application's queue, scheduler, or another object that exposes its Redis connection to the adapter:

from z4j_rq import RqEngineAdapter

adapter = RqEngineAdapter(rq_app=queue)

See scheduler: rq-scheduler.