apalis

pub trait Backend {
    /// The type of job arguments this backend delivers to workers.
    type Args;

    /// The type used to uniquely identify each task (e.g. `Uuid`, `i64`).
    type IdType: Clone;

    /// Arbitrary context attached to every task — for example, priority,
    /// scheduled time, or retry count. Must implement `Default` so the
    /// backend can construct context for new tasks.
    type Context: Default;

    /// The error type returned by backend operations such as polling
    /// or heartbeating.
    type Error;

    /// The stream of tasks returned by `poll`. Each item is:
    /// - `Ok(Some(task))` — a task is available for processing
    /// - `Ok(None)`       — the backend is idle (no tasks right now)
    /// - `Err(e)`         — a backend error occurred
    type Stream: Stream
        Item = Result<Option<Task<Self::Args, Self::Context, Self::IdType>>, Self::Error>,
    >;

    /// The stream returned by `heartbeat`. Each `Ok(())` item represents
    /// a successful liveness tick. An `Err` signals that the heartbeat
    /// mechanism has failed.
    type Beat: Stream<Item = Result<(), Self::Error>>;

    /// The middleware layer type for this backend. Used by the Apalis
    /// service builder to compose cross-cutting behaviour (e.g. retries,
    /// timeout, tracing) around task execution.
    type Layer;

    /// Produces a heartbeat stream for the given worker. The worker
    /// drives this stream to periodically register its liveness with
    /// the backend, enabling dead-worker detection and task requeuing.
    fn heartbeat(&self, worker: &WorkerContext) -> Self::Beat;

    /// Returns the backend's middleware layer. This is called once
    /// during worker setup and composed into the service stack.
    fn middleware(&self) -> Self::Layer;

    /// Begins polling the backend for tasks assigned to this worker,
    /// returning a decoded task stream. For most use cases you will
    /// drive this stream inside a [`Worker`].
    ///
    /// If you need access to the raw encoded representation, see
    /// [`BackendExt::poll_compact`].
    fn poll(self, worker: &WorkerContext) -> Self::Stream;
}

pub trait BackendExt: Backend {
    /// The codec used to encode `Args` into `Compact` for storage and
    /// decode them back again on the worker side. See [`Codec`] for details.
    type Codec: Codec<Self::Args, Compact = Self::Compact>;

    /// The encoded representation of task arguments as stored in the
    /// backend — for example, a `Vec<u8>` for binary formats or a
    /// `serde_json::Value` for JSON-based stores.
    type Compact;

    /// Like `Backend::Stream`, but yields tasks in their *encoded* form.
    /// Useful for inspecting or forwarding tasks without a full decode
    /// round-trip, or for implementing custom deserialization paths.
    type CompactStream: Stream
        Item = Result<Option<Task<Self::Compact, Self::Context, Self::IdType>>, Self::Error>,
    >;

    /// Returns the [`Queue`] identifier associated with this backend
    /// instance — typically the queue name or topic the backend is
    /// bound to.
    fn get_queue(&self) -> Queue;

    /// Like `Backend::poll`, but yields tasks in their compact (encoded)
    /// form without deserializing `Args`. Use this when you need direct
    /// access to the raw payload — for example, when routing tasks to
    /// different workers based on the encoded content.
    fn poll_compact(self, worker: &WorkerContext) -> Self::CompactStream;
}

use apalis::prelude::*;

struct MyBackend { /* ... */ }

impl Backend for MyBackend {
    type Args    = MyJob;
    type IdType  = uuid::Uuid;
    type Context = MyJobContext;
    type Error   = MyBackendError;
    type Stream  = /* ... */;
    type Beat    = /* ... */;
    type Layer   = /* ... */;

    fn heartbeat(&self, worker: &WorkerContext) -> Self::Beat { /* ... */ }
    fn middleware(&self) -> Self::Layer { /* ... */ }
    fn poll(self, worker: &WorkerContext) -> Self::Stream { /* ... */ }
}