Python
//! Provider-independent lifecycle rules. Names are selectors, never ownership receipts.
//! Mutation outcome unknown => inspect original identity; do not replay automatically.
use super::*;
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub(super) struct Operation {
pub token: String,
pub arn: Option<String>,
pub status: String,
}
#[derive(Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub(super) struct Journal {
pub schema_version: u16,
pub deployment_id: String,
pub bundle_digest: String,
pub plan: PathBuf,
pub phase: String,
pub operations: BTreeMap<String, Operation>,
pub recovery_history: Vec<(String, Operation)>,
#[serde(default)]
pub resources: BTreeMap<String, Value>,
}
#[derive(Clone)]
pub(super) struct Stack {
pub arn: String,
pub name: String,
pub status: String,
pub role: String,
pub tags: BTreeMap<String, String>,
pub template: Value,
/// Only stack-level events whose StackId/PhysicalResourceId match the ARN.
pub tokens: Vec<String>,
pub outputs: BTreeMap<String, String>,
}
pub(super) trait Provider {
async fn authorize_creation(&mut self) -> Result<()>;
async fn stack(&mut self, selector: &str) -> Result<Option<Stack>>;
async fn create(
&mut self,
name: &str,
token: &str,
template: &Value,
tags: &BTreeMap<String, String>,
) -> Result<String>;
async fn delete(&mut self, arn: &str, token: &str) -> Result<()>;
async fn guard_health(&mut self) -> Result<()>;
}
pub(super) fn save(root: &Path, j: &Journal) -> Result<()> {
let temporary = root.join(format!(".journal-{}", uuid::Uuid::new_v4().simple()));
let mut options = fs::OpenOptions::new();
options.create_new(true).write(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
options.mode(0o600);
}
let mut file = options.open(&temporary)?;
file.write_all(&json_bytes(j)?)?;
file.sync_all()?;
fs::rename(temporary, root.join("cloud-journal.json"))?;
#[cfg(unix)]
fs::File::open(root)?.sync_all()?;
Ok(())
}
pub(super) fn init(plan: &Path, root: &Path) -> Result<Journal> {
let (p, m) = inspect(plan)?;
ensure!(
p.schema_version == 3 && p.infrastructure.is_some(),
"Schema-3 AWS infrastructure plan required"
);
let parent = root
.parent()
.filter(|p| !p.as_os_str().is_empty())
.unwrap_or(Path::new("."))
.canonicalize()?;
ensure!(
!parent.starts_with(plan.canonicalize()?),
"Lifecycle state must be outside the immutable plan"
);
let mut builder = fs::DirBuilder::new();
#[cfg(unix)]
{
use std::os::unix::fs::DirBuilderExt;
builder.mode(0o700);
}
builder
.create(root)
.context("Lifecycle state directory must not exist")?;
let j = Journal {
schema_version: 1,
deployment_id: p.deployment_id,
bundle_digest: m.bundle_digest,
plan: plan.canonicalize()?,
phase: "prepared".into(),
..Default::default()
};
save(root, &j)?;
Ok(j)
}
pub(super) fn load(root: &Path) -> Result<(Journal, Plan, fs::File)> {
let meta = fs::symlink_metadata(root)?;
ensure!(
meta.is_dir() && !meta.file_type().is_symlink(),
"Invalid lifecycle directory"
);
let path = root.join("cloud.lock");
if let Ok(m) = fs::symlink_metadata(&path) {
ensure!(
m.is_file() && !m.file_type().is_symlink(),
"Invalid lifecycle lock"
);
}
let mut options = fs::OpenOptions::new();
options.read(true).write(true).create(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
options.mode(0o600);
}
let lock = options.open(path)?;
lock.try_lock()
.map_err(|_| anyhow::anyhow!("Another command holds the lifecycle lock"))?;
let j: Journal = serde_json::from_slice(&read_file(root, "cloud-journal.json")?)?;
let (p, m) = inspect(&j.plan)?;
ensure!(
j.schema_version == 1
&& p.schema_version == 3
&& j.deployment_id == p.deployment_id
&& j.bundle_digest == m.bundle_digest,
"Lifecycle/plan identity mismatch"
);
Ok((j, p, lock))
}
fn name(p: &Plan, kind: &str) -> String {
format!("{}-{kind}", p.prefix())
}
fn valid_arn(p: &Plan, kind: &str, arn: &str) -> bool {
let Target::Aws { account, region } = &p.target else {
return false;
};
arn.strip_prefix(&format!(
"arn:aws:cloudformation:{region}:{account}:stack/{}/",
name(p, kind)
))
.is_some_and(|id| {
!id.is_empty()
&& id.len() <= 128
&& id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-')
})
}
fn tags(p: &Plan, j: &Journal, token: &str) -> BTreeMap<String, String> {
BTreeMap::from([
("ows:deployment-id".into(), p.deployment_id.clone()),
("ows:bundle-digest".into(), j.bundle_digest.clone()),
("ows:operation-id".into(), token.into()),
("ows:expires-at".into(), p.expires_at_unix.to_string()),
])
}
pub(super) fn verify(p: &Plan, j: &Journal, kind: &str, op: &Operation, s: &Stack) -> Result<()> {
ensure!(
valid_arn(p, kind, &s.arn) && s.name == name(p, kind),
"Cloud stack scope mismatch"
);
ensure!(
s.role
== p.bootstrap
.as_ref()
.context("Executor missing")?
.execution_role_arn,
"Cloud stack executor changed"
);
ensure!(
tags(p, j, &op.token)
.iter()
.all(|(k, v)| s.tags.get(k) == Some(v)),
"Cloud stack ownership/request mismatch"
);
ensure!(
op.arn.as_ref().is_none_or(|arn| arn == &s.arn),
"Cloud stack immutable identity changed"
);
let expected: Value = serde_json::from_slice(&read_file(
&j.plan,
&format!(
"{}.cfn.json",
if kind == "infra" {
"infrastructure"
} else {
"guard"
}
),
)?)?;
ensure!(s.template == expected, "Cloud stack template drift");
ensure!(
s.tokens.contains(&op.token),
"Original creation token not observed in stack events; inspect original operation"
);
Ok(())
}
fn begin(root: &Path, j: &mut Journal, key: &str, arn: Option<String>) -> Result<()> {
ensure!(
!j.operations.contains_key(key),
"Operation already has an intent"
);
j.operations.insert(
key.into(),
Operation {
token: format!("ows-{}", uuid::Uuid::new_v4().simple()),
arn,
status: "intent".into(),
},
);
save(root, j)
}
/// One bounded observation/transition. Caller may invoke again; no hidden mutation retry.
pub(super) async fn provision<P: Provider>(
root: &Path,
j: &mut Journal,
p: &Plan,
api: &mut P,
at: u64,
) -> Result<()> {
ensure!(
!["destroying", "infrastructure_deleted"].contains(&j.phase.as_str()),
"Deployment teardown has begun"
);
for kind in ["guard", "infra"] {
let key = format!("create:{kind}");
let selector = j
.operations
.get(&key)
.and_then(|o| o.arn.clone())
.unwrap_or_else(|| name(p, kind));
let observed = api.stack(&selector).await?;
match observed {
Some(s) => {
let op = j
.operations
.get(&key)
.context("Refusing to adopt a preexisting stack")?;
verify(p, j, kind, op, &s)?;
let op = j.operations.get_mut(&key).unwrap();
op.arn = Some(s.arn.clone());
op.status = s.status.clone();
save(root, j)?;
match s.status.as_str(){
"CREATE_COMPLETE"=>{},
"CREATE_IN_PROGRESS"=>{j.phase=format!("{kind}_creating");save(root,j)?;return Ok(())},
_=>bail!("Cloud stack failed, changed or is being deleted; inspect original operation"),
}
}
None => {
ensure!(
p.created_at_unix <= at && at < p.expires_at_unix,
"Expiry prevents new provisioning; observation/teardown remain available"
);
ensure!(
!j.operations.contains_key(&key),
"Cloud create outcome unknown or original stack missing; no automatic replay"
);
if kind == "infra" {
api.guard_health().await?;
}
api.authorize_creation().await?;
let template: Value = serde_json::from_slice(&read_file(
&j.plan,
if kind == "infra" {
"infrastructure.cfn.json"
} else {
"guard.cfn.json"
},
)?)?;
begin(root, j, &key, None)?;
// Intent is durable before dispatch. A transport error retains this
// token; the next process observes, never silently creates again.
let token = j.operations[&key].token.clone();
let arn = api
.create(&name(p, kind), &token, &template, &tags(p, j, &token))
.await?;
ensure!(
valid_arn(p, kind, &arn),
"Create returned an invalid stack ARN; inspect original request"
);
j.operations.get_mut(&key).unwrap().arn = Some(arn);
j.phase = format!("{kind}_creating");
save(root, j)?;
return Ok(());
}
}
if kind == "guard" {
api.guard_health().await?;
j.phase = "guard_ready".into();
save(root, j)?;
}
}
// Infrastructure readiness is distinct from platform/service qualification.
j.phase = "infrastructure_ready".into();
save(root, j)
}
pub(super) async fn observe<P: Provider>(j: &Journal, p: &Plan, api: &mut P) -> Result<Value> {
let mut rows = BTreeMap::new();
for kind in ["guard", "infra"] {
let key = format!("create:{kind}");
let selector = j
.operations
.get(&key)
.and_then(|o| o.arn.clone())
.unwrap_or_else(|| name(p, kind));
let s = api.stack(&selector).await?;
if let Some(s) = s {
let op = j
.operations
.get(&key)
.context("Unbound preexisting stack observed")?;
verify(p, j, kind, op, &s)?;
rows.insert(kind,json!({"arn":s.arn,"status":s.status,"originalCreationTokenVerified":true,"outputs":s.outputs}));
} else {
rows.insert(
kind,
json!({"absent":true,"priorIntent":j.operations.contains_key(&key)}),
);
}
}
Ok(json!({"deploymentId":j.deployment_id,"phase":j.phase,"observed":rows,"readOnly":true}))
}
pub(super) async fn confirm_no_effect<P: Provider>(
root: &Path,
j: &mut Journal,
p: &Plan,
api: &mut P,
kind: &str,
) -> Result<()> {
ensure!(
["guard", "infra"].contains(&kind),
"Only an unconfirmed create may be reset"
);
ensure!(
j.recovery_history.len() < 16,
"Recovery history limit reached"
);
let key = format!("create:{kind}");
let old = j.operations.get(&key).context("No original intent")?;
ensure!(
old.status == "intent" && old.arn.is_none(),
"A bound/observed operation cannot be reset"
);
ensure!(
api.stack(&name(p, kind)).await?.is_none(),
"Original stack exists; reconcile it instead"
);
j.recovery_history
.push((key.clone(), j.operations.remove(&key).unwrap()));
save(root, j)
}
/// Installation and data cleanup is a separate precondition, checked by caller.
/// Guard/bootstrap intentionally remain; they must outlive all owned infrastructure.
pub(super) async fn destroy<P: Provider>(
root: &Path,
j: &mut Journal,
p: &Plan,
api: &mut P,
) -> Result<()> {
ensure!(p.expires_workload(), "Persistent deployment data is retained. Review a separate data-retention/teardown plan before destruction.");
let key = "create:infra";
let Some(mut op) = j.operations.get(key).cloned() else {
bail!("Infrastructure has no original intent; inspect incomplete bootstrap")
};
if op.arn.is_none() {
let s = api
.stack(&name(p, "infra"))
.await?
.context("Infrastructure outcome unknown; original stack absent")?;
verify(p, j, "infra", &op, &s)?;
op.arn = Some(s.arn);
j.operations.insert(key.into(), op.clone());
save(root, j)?;
}
let arn = op.arn.as_ref().unwrap();
let stack = api.stack(arn).await?;
let delete_key = "delete:infra";
if let Some(s) = stack {
verify(p, j, "infra", &op, &s)?;
if s.status == "DELETE_COMPLETE" {
ensure!(
j.operations.contains_key(delete_key),
"Deletion occurred without recorded intent; inspect"
);
j.phase = "infrastructure_deleted".into();
save(root, j)?;
return Ok(());
}
if let Some(d) = j.operations.get(delete_key) {
ensure!(d.arn.as_ref() == Some(arn), "Delete receipt changed");
ensure!(
s.status == "DELETE_IN_PROGRESS" && s.tokens.contains(&d.token),
"Prior delete outcome unknown/failed; inspect instead of retrying"
);
return Ok(());
}
ensure!(
!s.status.ends_with("IN_PROGRESS") && !s.status.starts_with("DELETE_"),
"Stack is busy/failed deletion; inspect original operation"
);
begin(root, j, delete_key, Some(arn.clone()))?;
j.phase = "destroying".into();
save(root, j)?;
api.delete(arn, &j.operations[delete_key].token).await?;
} else {
ensure!(
j.operations.contains_key(delete_key),
"Original stack absent without deletion intent; inspect"
);
j.phase = "infrastructure_deleted".into();
save(root, j)?;
}
Ok(())
}