Struct QueueJob 

pub struct QueueJob<T>
where
    T: Serialize + DeserializeOwned + Clone + Send + Sync,
{
    pub id: String,
    pub trace_id: Option<String>,
    pub trace_ctx: Option<TraceCtx>,
    pub attempt_id: Option<AttemptId>,
    pub trial_id: Option<TrialId>,
    pub priority: QueuePriority,
    pub status: QueueJobStatus,
    pub data: T,
    pub created_at: Option<String>,
    pub started_at: Option<String>,
    pub completed_at: Option<String>,
    pub error_message: Option<String>,
}

A generic queue job carrying a custom data payload.

The data field is stored as JSON in SQLite and deserialized back when the executor picks up the job. Your data type must implement Serialize, DeserializeOwned, Clone, Send, and Sync.

When creating jobs via QueueJob::new, only id, priority, and data are meaningful — the remaining fields (status, created_at, started_at, completed_at, error_message) are set to defaults and populated by the database when reading job records back.

Trace and retry primitives

The canonical trace/retry fields are:

• trace_ctx: canonical stack_ids::TraceCtx for end-to-end correlation
• attempt_id: one per re-enqueue (this crate is the retry owner)
• trial_id: one per concrete execution attempt

The legacy trace_id: Option<String> field is preserved for backward compatibility and is kept in sync with trace_ctx automatically.

Fields

id: String

trace_id: Option<String>

Phase status: compatibility / migration-only.

Legacy trace identifier for end-to-end correlation. The canonical replacement is trace_ctx. Use stack_ids::TraceCtx::from_legacy_trace_id() to convert. Removal condition: replaced when all callers migrate.

trace_ctx: Option<TraceCtx>

Canonical trace context for end-to-end correlation.

Replaces the legacy trace_id field. The trace ID string is extractable via trace_ctx.trace_id for DB storage (the DB schema stores trace_id TEXT and is NOT changed).

attempt_id: Option<AttemptId>

Canonical attempt identity — one per re-enqueue.

This crate is the retry owner: each re-enqueue creates a new AttemptId. Retries within the same attempt use different TrialIds.

trial_id: Option<TrialId>

Canonical trial identity — one per concrete execution.

Each time the executor picks up a job for execution, a new TrialId is generated. Multiple trials may share the same AttemptId.

priority: QueuePriority

status: QueueJobStatus

data: T

created_at: Option<String>

Only populated when reading from DB.

started_at: Option<String>

Only populated when reading from DB.

completed_at: Option<String>

Only populated when reading from DB.

error_message: Option<String>

Only populated when reading from DB.

Implementations

impl<T> QueueJob<T>

where T: Serialize + DeserializeOwned + Clone + Send + Sync,

pub fn new(data: T) -> QueueJob<T>

Create a new job with a generated UUID and Normal priority.

A fresh AttemptId is generated automatically (this crate is the retry owner — each enqueue is a new attempt).

pub fn with_priority(self, priority: QueuePriority) -> QueueJob<T>

Set the priority for this job (builder pattern).

pub fn with_id(self, id: String) -> QueueJob<T>

Set a custom ID for this job (builder pattern).

pub fn with_trace_id(self, trace_id: impl Into<String>) -> QueueJob<T>

Phase status: compatibility / migration-only.

Attach an optional trace ID string for end-to-end correlation. Prefer with_trace_ctx() for new code. Removal condition: replaced when all callers migrate.

pub fn with_trace_ctx(self, ctx: TraceCtx) -> QueueJob<T>

Attach a canonical stack_ids::TraceCtx for end-to-end correlation.

Also sets the legacy trace_id string for DB storage compatibility (the DB schema stores trace_id TEXT and is NOT changed).

pub fn with_attempt_id(self, attempt_id: AttemptId) -> QueueJob<T>

Set a pre-existing AttemptId (e.g., when reconstructing from DB).

Normally callers do not need this — new() generates a fresh AttemptId automatically.

pub fn with_trial_id(self, trial_id: TrialId) -> QueueJob<T>

Set a TrialId (normally assigned by the executor, not callers).

pub fn resolve_trace_ctx(&self) -> Option<TraceCtx>

Get the canonical TraceCtx, preferring the canonical field, falling back to reconstruction from the legacy trace_id string.

Returns None if neither field is set.

pub fn trace_ctx_compat(&self) -> Option<TraceCtx>

Phase status: compatibility / migration-only.

Convert the stored trace ID to a canonical stack_ids::TraceCtx. Returns None if no trace ID is set. Prefer resolve_trace_ctx() for new code.

Trait Implementations

impl<T> Clone for QueueJob<T>

where T: Clone + Serialize + DeserializeOwned + Send + Sync,

fn clone(&self) -> QueueJob<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for QueueJob<T>

where T: Debug + Serialize + DeserializeOwned + Clone + Send + Sync,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for QueueJob<T>

where T: Serialize + DeserializeOwned + Clone + Send + Sync,

fn deserialize<__D>( __deserializer: __D, ) -> Result<QueueJob<T>, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Serialize for QueueJob<T>

where T: Serialize + DeserializeOwned + Clone + Send + Sync,

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.