z4j-huey

The Huey engine adapter for z4j.

Streams supported Huey task lifecycle events from your consumers to the z4j brain and accepts operator control actions from the dashboard. Pair with z4j-hueyperiodic to surface @periodic_task schedules.

What it ships

Not supported (Huey's storage model can't back them faithfully, so the adapter declines the capability instead of faking it): bulk retry, queue purge, dead-letter requeue, worker restart, rate limiting. Cancel uses Huey's revoke-by-id primitive. It prevents a pending task from starting but cannot stop running work.

Compatibility

• Huey 2.4 and later, with no upper bound: Huey 2 and Huey 3 are both supported. The package's suite runs a real Huey consumer on Huey 2.4.0 and on Huey 3.4.0 and asserts the exact sequence of events for every lifecycle path on each: one terminal event per task, and never a terminal event and a retry for the same attempt.
• Huey older than 2.5.3 has no enqueue signal. On those releases a task first appears when it starts, and its arguments are not captured.
• Storage backends: redis, sqlite, in-memory
• Python 3.11+

Full per-adapter matrix at https://docs.z4j.com/reference/compatibility/.

Changing the Huey major

Upgrading Huey from 2 to 3 needs nothing from the adapter: a Huey 3 consumer reads the work a Huey 2 process enqueued.

Downgrading Huey from 3 to 2 loses queued work unless you drain first. Huey 3 writes a wider queue message than Huey 2 can read, so a Huey 2 consumer raises TypeError on every task a Huey 3 process enqueued and the task is gone; a scheduled task that has come due is dropped the same way. Before downgrading Huey, stop enqueueing and let the queue and the schedule empty. Run one Huey major in every process that shares a queue, including the process that hosts the z4j agent.

This is Huey's own queue format, and z4j does not change it in either direction: a retry or a schedule fire is enqueued through your Huey instance in that Huey's format, and the adapter reads task state from the result store, which both majors read from each other.

Install

pip install z4j-huey z4j-hueyperiodic

Pair with a framework adapter:

pip install z4j-django  z4j-huey z4j-hueyperiodic   # Django
pip install z4j-flask   z4j-huey z4j-hueyperiodic   # Flask
pip install z4j-fastapi z4j-huey z4j-hueyperiodic   # FastAPI
pip install z4j-bare    z4j-huey z4j-hueyperiodic   # framework-free worker

Pairs with

• z4j-hueyperiodic, schedule adapter for Huey @periodic_task

Reliability

• Lifecycle-capture failures are isolated from Huey hooks and task code; capture hooks make no brain network request inline.
• The in-process event queue and SQLite outbound buffer are bounded. Queue overflow drops new events and buffer pressure evicts oldest rows; both losses are logged.

Documentation

Full docs at docs.z4j.com/engines/huey/.

License

Apache-2.0, see LICENSE.

Links

• Homepage: https://z4j.com
• Documentation: https://docs.z4j.com
• PyPI: https://pypi.org/project/z4j-huey/
• Issues: https://github.com/z4jdev/z4j-huey/issues
• Changelog: CHANGELOG.md
• Security: security@z4j.com (see SECURITY.md)