alien_core/deployment/
state.rs

1//! Deployment state, step results, and runtime metadata.
2
3use crate::{Platform, StackState};
4use alien_error::AlienError;
5use bon::Builder;
6use serde::{Deserialize, Serialize};
7
8use super::{DeploymentStatus, EnvironmentInfo, ReleaseInfo};
9
10/// Runtime metadata for deployment
11///
12/// Stores deployment state that needs to persist across step calls.
13#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
14#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
15#[serde(rename_all = "camelCase")]
16pub struct RuntimeMetadata {
17    /// Hash of the environment variables snapshot that was last synced to the vault
18    /// Used to avoid redundant sync operations during incremental deployment
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub last_synced_env_vars_hash: Option<String>,
21
22    /// The prepared (mutated) stack from the last successful deployment phase
23    /// This is the stack AFTER mutations have been applied (with service accounts, vault, etc.)
24    /// Used for compatibility checks during updates to compare mutated stacks
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub prepared_stack: Option<crate::Stack>,
27
28    /// Whether cross-account registry access has been successfully granted.
29    /// Set to true after the manager successfully sets the ECR/GAR repo policy
30    /// for this deployment's target account. Prevents redundant API calls on
31    /// every reconcile tick.
32    #[serde(default, skip_serializing_if = "is_false")]
33    pub registry_access_granted: bool,
34}
35
36/// Deployment state
37///
38/// Represents the current state of deployed infrastructure, including release tracking.
39/// This is platform-agnostic - no backend IDs or database relationships.
40///
41/// The deployment engine manages releases internally: when a deployment succeeds,
42/// it promotes `target_release` to `current_release` and clears `target_release`.
43#[derive(Debug, Clone, Serialize, Deserialize, Builder)]
44#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
45#[serde(rename_all = "camelCase")]
46pub struct DeploymentState {
47    /// Current lifecycle phase
48    pub status: DeploymentStatus,
49    /// Target cloud platform (AWS, GCP, Azure, Kubernetes)
50    pub platform: Platform,
51    /// Currently deployed release (None for first deployment)
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub current_release: Option<ReleaseInfo>,
54    /// Target release to deploy (None when synced with current)
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub target_release: Option<ReleaseInfo>,
57    /// Infrastructure resource tracking (which resources exist, their status, outputs)
58    #[serde(skip_serializing_if = "Option::is_none")]
59    pub stack_state: Option<StackState>,
60    /// Cloud account details (account ID, project number, region)
61    #[serde(skip_serializing_if = "Option::is_none")]
62    pub environment_info: Option<EnvironmentInfo>,
63    /// Deployment-specific data (prepared stacks, phase tracking, etc.)
64    #[serde(skip_serializing_if = "Option::is_none")]
65    pub runtime_metadata: Option<RuntimeMetadata>,
66    /// Whether a retry has been requested for a failed deployment
67    /// When true and status is a failed state, the deployment system will retry failed resources
68    #[serde(default, skip_serializing_if = "is_false")]
69    pub retry_requested: bool,
70    /// Protocol version for cross-actor compatibility.
71    /// All actors (manager, push client, agent) check this before stepping.
72    /// Mismatched versions produce a clear error instead of silent corruption.
73    /// See docs/02-manager/10-deployment-protocol.md.
74    #[serde(default = "default_protocol_version")]
75    pub protocol_version: u32,
76}
77
78/// Result of a deployment step
79///
80/// Contains the complete next deployment state along with hints for the platform.
81/// This replaces the old delta-based `DeploymentStateUpdate` approach.
82#[derive(Debug, Clone, Serialize, Deserialize)]
83#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
84#[serde(rename_all = "camelCase")]
85pub struct DeploymentStepResult {
86    /// The complete next deployment state
87    pub state: DeploymentState,
88
89    /// Error that occurred during this step (if any)
90    /// - `None`: No error, step succeeded
91    /// - `Some(error)`: Step failed or encountered an error
92    #[serde(skip_serializing_if = "Option::is_none")]
93    pub error: Option<AlienError>,
94
95    /// Suggested delay before next step (optimization hint)
96    /// - `None`: No suggested delay, can poll immediately
97    /// - `Some(ms)`: Wait this many milliseconds before next step
98    #[serde(skip_serializing_if = "Option::is_none")]
99    pub suggested_delay_ms: Option<u64>,
100
101    /// Whether to update heartbeat timestamp (monitoring signal)
102    /// - `false`: Don't update heartbeat (default for most steps)
103    /// - `true`: Update lastHeartbeatAt (for successful health checks in Running state)
104    #[serde(default, skip_serializing_if = "is_false")]
105    pub update_heartbeat: bool,
106}
107
108pub(crate) fn is_false(b: &bool) -> bool {
109    !*b
110}
111
112/// Current deployment protocol version.
113/// Bump when making incompatible changes to DeploymentState semantics.
114pub const DEPLOYMENT_PROTOCOL_VERSION: u32 = 1;
115
116fn default_protocol_version() -> u32 {
117    DEPLOYMENT_PROTOCOL_VERSION
118}
alien_core/deployment/state.rs

alien_core/deployment/
state.rs
