azums 1.0.1

Embedded durable execution runtime for Rust, from Memory and SQLite to PostgreSQL and Redis
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

use chrono::{DateTime, Utc};
use serde::Serialize;
use uuid::Uuid;

use crate::jobs::{AttemptsRepo, JobsRepo, PolicyDecisionsRepo};

#[derive(Debug, Serialize)]
/// Operator-oriented interpretation of what can happen to a job next.
/// # Examples
///
/// ```rust
/// use azums::jobs::debug_view::NextAction;
///
/// let action = NextAction::Queued;
/// assert!(matches!(action, NextAction::Queued));
/// ```
pub enum NextAction {
    /// Job is waiting for a retry at the included time.
    RetryAt(DateTime<Utc>),
    /// Job is terminal in the dead-letter queue.
    Dlq {
        /// Machine-readable DLQ reason when available.
        reason: Option<String>,
    },
    /// Historical job may be replayed as new work.
    Replayable,
    /// Job currently has a running lease.
    Running,
    /// Job is queued or scheduled.
    Queued,
    /// Job completed successfully.
    Succeeded,
    /// Persisted state is not recognized by this unstable view.
    Unknown,
}

#[derive(Debug, Serialize)]
/// Unstable aggregate for debugging job state, history, and policy decisions.
/// # Examples
///
/// ```rust
/// use azums::jobs::debug_view::NextAction;
///
/// let action = NextAction::Queued;
/// assert!(matches!(action, NextAction::Queued));
/// ```
pub struct DebugView {
    /// Job being inspected.
    pub job_id: Uuid,
    /// Current persisted job status.
    pub status: String,
    /// Serialized attempt timeline.
    pub attempts: serde_json::Value,
    /// Serialized policy-decision narrative.
    pub decisions: serde_json::Value,
    /// Operator-oriented next action inferred from current state.
    pub next_action: NextAction,
}

/// Builds an unstable debug aggregate for `job_id`, or `None` when absent.
/// # Examples
///
/// ```rust
/// use azums::jobs::debug_view::NextAction;
///
/// let action = NextAction::Queued;
/// assert!(matches!(action, NextAction::Queued));
/// ```
pub async fn build_debug_view(
    jobs: &JobsRepo,
    attempts: &AttemptsRepo,
    decisions: &PolicyDecisionsRepo,
    job_id: Uuid,
) -> anyhow::Result<Option<DebugView>> {
    let Some(job) = jobs.get_job(job_id).await? else {
        return Ok(None);
    };

    let tl = crate::jobs::timeline::build_timeline(jobs, attempts, decisions, job_id).await?;
    let attempts_json = serde_json::to_value(tl.as_ref().map(|t| &t.attempts)).unwrap_or_default();
    let decisions_json = serde_json::to_value(tl.as_ref().map(|t| &t.story)).unwrap_or_default();

    let next_action = match job.status.as_str() {
        "queued" => NextAction::Queued,
        "running" => NextAction::Running,
        "succeeded" => NextAction::Succeeded,
        "dlq" => NextAction::Dlq {
            reason: job.dlq_reason_code.clone(),
        },
        "failed" => NextAction::Replayable,
        _ => NextAction::Unknown,
    };

    Ok(Some(DebugView {
        job_id,
        status: job.status.clone(),
        attempts: attempts_json,
        decisions: decisions_json,
        next_action,
    }))
}