yeti_types/plugins/
queue.rs

1//! Durable / async job execution.
2//!
3//! Plugins (and the runtime) implement
4//! `tower::Service<JobRequest, Response = JobResponse>` for queue
5//! handlers. The `queue!()` macro emits these Service impls; the
6//! worker pool composes them with `tower::retry::Retry`,
7//! `tower::timeout::Timeout`, and `tower::limit::concurrency` to
8//! get retry / deadline / pool-size semantics for free.
9//!
10//! The runtime calls `service.ready().await?.call(req).await` per
11//! claimed job, with the journal-backed input as `req.payload`.
12
13use serde_json::Value;
14
15/// Input to a queue handler. The `queue` field names the queue
16/// the job came from (also the macro's name); `payload` is the
17/// journaled JSON-shaped input the handler will operate on.
18#[derive(Debug, Clone)]
19pub struct JobRequest {
20    /// Queue name (matches the `queue!()` macro's `name = ...`).
21    pub queue: String,
22    /// Journaled job input.
23    pub payload: Value,
24}
25
26/// Outcome of a single job handler invocation.
27#[derive(Debug, Clone)]
28pub struct JobResponse {
29    /// Terminal status — drives the runtime's journaling decision.
30    pub status: JobStatus,
31    /// Free-form output written back to the journal alongside the
32    /// status. Available to callers that poll on the request id.
33    pub output: Value,
34}
35
36/// Terminal status of a job execution.
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38pub enum JobStatus {
39    /// Job ran to completion. The runtime marks the journal entry
40    /// terminal-success; no retries.
41    Completed,
42    /// Job failed permanently. The runtime marks the journal entry
43    /// terminal-failure; no retries.
44    Failed,
45    /// Handler decided to retry. The runtime requeues per the
46    /// `tower::retry` policy on the worker stack.
47    Retried,
48}
yeti_types/plugins/queue.rs

yeti_types/plugins/
queue.rs
