imagegen-bridge-core 0.1.0

Provider-neutral domain contract for Imagegen Bridge
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
102
103
104
105
106
107
108
109
110
111
112
113
114
115

//! Durable asynchronous generation job contracts.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::{BridgeError, ImageRequest, ImageResponse};

/// Durable lifecycle state for one asynchronous image operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ImageJobStatus {
    /// Accepted and waiting for bounded worker capacity.
    Queued,
    /// Claimed by a worker; provider completion may be ambiguous after a crash.
    Running,
    /// Completed with a verified response.
    Succeeded,
    /// Completed with a structured bridge error.
    Failed,
    /// Cancelled before or during execution.
    Cancelled,
    /// Process stopped while a paid provider call may have been in flight.
    Interrupted,
}

impl ImageJobStatus {
    /// Whether no more execution will occur without a new submission.
    #[must_use]
    pub const fn terminal(self) -> bool {
        matches!(
            self,
            Self::Succeeded | Self::Failed | Self::Cancelled | Self::Interrupted
        )
    }
}

/// Bounded latest progress snapshot for a durable job.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ImageJobProgress {
    /// Stable stage label without prompt or image content.
    pub stage: String,
    /// Number of bounded partial-image events observed.
    pub partial_images: u32,
}

/// List-safe durable job state without request image bodies.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ImageJobSummary {
    /// Stable `UUIDv7` job identifier.
    pub id: String,
    /// Current durable lifecycle state.
    pub status: ImageJobStatus,
    /// Unix creation timestamp.
    pub created: u64,
    /// Unix timestamp of the last durable transition.
    pub updated: u64,
    /// Worker claim timestamp.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub started: Option<u64>,
    /// Terminal transition timestamp.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub completed: Option<u64>,
    /// Latest bounded progress snapshot.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub progress: Option<ImageJobProgress>,
    /// User-selected gallery favorite state.
    pub favorite: bool,
    /// Soft-delete timestamp; deleted jobs are hidden from ordinary lists.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deleted: Option<u64>,
}

/// Complete durable job record returned by detail lookup.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ImageJob {
    /// List-safe lifecycle summary.
    #[serde(flatten)]
    pub summary: ImageJobSummary,
    /// Original normalized request retained for recovery and inspection.
    pub request: ImageRequest,
    /// Verified terminal result.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result: Option<ImageResponse>,
    /// Structured terminal error.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<BridgeError>,
    /// Whether cancellation has been durably requested.
    pub cancel_requested: bool,
}

/// Cursor-paginated job/history result.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ImageJobPage {
    /// Stable newest-first page.
    pub items: Vec<ImageJobSummary>,
    /// Opaque cursor for the next page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<String>,
}

/// Mutable gallery fields for one retained durable job.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ImageJobUpdate {
    /// Set or clear the favorite marker.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub favorite: Option<bool>,
    /// Soft-delete or restore a terminal history item.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deleted: Option<bool>,
}