nxd_core/domain/contract/

resources.rs

use serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::Value;
use std::collections::BTreeMap;

/// Canonical resource. Only core lifecycle kinds remain first-party. All
/// infrastructure/vendor kinds (PVE, PBS, Headscale, …) that declare a
/// provider instance are [`Resource::ProviderOwned`] envelopes: core sees association
/// and secret fields only; vendor schema is owned by the provider handshake.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Resource {
	Machine(Machine),
	DeploymentTarget(Box<DeploymentTarget>),
	SyntheticResource(SyntheticResource),
	ProviderOwned(ProviderOwnedResource),
}

/// Closed first-party wire kinds (serde). Open provider kinds use envelopes.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "camelCase", deny_unknown_fields)]
enum FirstPartyResource {
	Machine(Machine),
	DeploymentTarget(Box<DeploymentTarget>),
	SyntheticResource(SyntheticResource),
}

impl From<FirstPartyResource> for Resource {
	fn from(value: FirstPartyResource) -> Self {
		match value {
			FirstPartyResource::Machine(v) => Self::Machine(v),
			FirstPartyResource::DeploymentTarget(v) => Self::DeploymentTarget(v),
			FirstPartyResource::SyntheticResource(v) => Self::SyntheticResource(v),
		}
	}
}

impl TryFrom<&Resource> for FirstPartyResource {
	type Error = ();
	fn try_from(value: &Resource) -> Result<Self, Self::Error> {
		Ok(match value {
			Resource::Machine(v) => Self::Machine(v.clone()),
			Resource::DeploymentTarget(v) => Self::DeploymentTarget(v.clone()),
			Resource::SyntheticResource(v) => Self::SyntheticResource(v.clone()),
			Resource::ProviderOwned(_) => return Err(()),
		})
	}
}

impl Serialize for Resource {
	fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
	where
		S: Serializer,
	{
		match self {
			Resource::ProviderOwned(owned) => owned.desired.serialize(serializer),
			other => {
				FirstPartyResource::try_from(other).expect("first-party resource").serialize(serializer)
			}
		}
	}
}

impl<'de> Deserialize<'de> for Resource {
	fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
	where
		D: Deserializer<'de>,
	{
		let value = Value::deserialize(deserializer)?;
		match serde_json::from_value::<FirstPartyResource>(value.clone()) {
			Ok(first_party) => return Ok(first_party.into()),
			Err(error)
				if matches!(
					value.get("kind").and_then(Value::as_str),
					Some("machine" | "deploymentTarget" | "syntheticResource")
				) =>
			{
				return Err(serde::de::Error::custom(error));
			}
			Err(_) => {}
		}
		ProviderOwnedResource::from_wire_value(value)
			.map(Resource::ProviderOwned)
			.map_err(serde::de::Error::custom)
	}
}

/// Provider-owned resource envelope: common fields for core; `desired` is the
/// full wire document for the owning provider (opaque vendor schema).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ProviderOwnedResource {
	/// Provider schema kind (wire `kind`).
	#[serde(rename = "resourceKind")]
	pub resource_kind: String,
	pub id: String,
	pub provider: String,
	#[serde(default)]
	pub depends_on: Vec<String>,
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub deployment_target: Option<String>,
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub secret_binding: Option<String>,
	/// Full desired document returned to the provider (includes kind and fields).
	pub desired: Value,
}

impl ProviderOwnedResource {
	/// Build an envelope from a wire JSON object that was not a first-party kind.
	pub fn from_wire_value(value: Value) -> Result<Self, String> {
		let object = value
			.as_object()
			.ok_or_else(|| "provider-owned resource must be a JSON object".to_string())?;
		let resource_kind = object
			.get("kind")
			.and_then(Value::as_str)
			.filter(|value| !value.is_empty())
			.ok_or_else(|| "provider-owned resource is missing kind".to_string())?
			.to_string();
		let id = object
			.get("id")
			.and_then(Value::as_str)
			.filter(|value| !value.is_empty())
			.ok_or_else(|| "provider-owned resource is missing id".to_string())?
			.to_string();
		// Every infrastructure kind, including pveCluster/qdevice topology, must
		// name a configured provider instance (prompt 03.1 / C.3).
		let provider = object
			.get("provider")
			.and_then(Value::as_str)
			.filter(|value| !value.is_empty())
			.ok_or_else(|| format!("provider-owned resource {id} is missing provider"))?
			.to_string();
		// Only explicit dependsOn edges are graph dependencies. Vendor fields
		// are not resource ids and are not interpreted as associations.
		let depends_on = object
			.get("dependsOn")
			.and_then(Value::as_array)
			.map(|items| items.iter().filter_map(Value::as_str).map(str::to_string).collect::<Vec<_>>())
			.unwrap_or_default();
		// Association is the common field only — never hostname conventions.
		let deployment_target = object
			.get("deploymentTarget")
			.and_then(Value::as_str)
			.filter(|value| !value.is_empty())
			.map(str::to_string);
		let secret_binding = object
			.get("secretBinding")
			.and_then(Value::as_str)
			.filter(|value| !value.is_empty())
			.map(str::to_string);
		Ok(Self {
			resource_kind,
			id,
			provider,
			depends_on,
			deployment_target,
			secret_binding,
			desired: value,
		})
	}

	pub fn associated_deployment_target(&self) -> Option<String> {
		if let Some(target) = &self.deployment_target
			&& !target.is_empty()
		{
			return Some(target.clone());
		}
		self
			.desired
			.get("deploymentTarget")
			.and_then(Value::as_str)
			.filter(|v| !v.is_empty())
			.map(str::to_string)
	}
}

#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct DeploymentTarget {
	pub id: String,
	#[serde(default)]
	pub depends_on: Vec<String>,
	#[serde(default)]
	pub labels: BTreeMap<String, String>,
	pub metadata: crate::domain::deployment_metadata::FlakeMetadata,
}

#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Machine {
	pub id: String,
	#[serde(default)]
	pub labels: BTreeMap<String, String>,
}

#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SyntheticResource {
	pub id: String,
	pub provider: String,
	pub desired: serde_json::Value,
	#[serde(default)]
	pub depends_on: Vec<String>,
}

/// Stable resource id for any resource variant.
pub fn resource_id(resource: &Resource) -> &str {
	match resource {
		Resource::Machine(value) => &value.id,
		Resource::DeploymentTarget(value) => &value.id,
		Resource::SyntheticResource(value) => &value.id,
		Resource::ProviderOwned(value) => &value.id,
	}
}

/// Owning provider instance id when the resource is provider-routed.
pub fn resource_provider(resource: &Resource) -> Option<&str> {
	match resource {
		Resource::SyntheticResource(value) => Some(&value.provider),
		Resource::ProviderOwned(value) if !value.provider.is_empty() => Some(&value.provider),
		_ => None,
	}
}

/// Wire kind for a provider-owned envelope (`guest`, `backupJob`, …).
pub fn resource_kind(resource: &Resource) -> Option<&str> {
	match resource {
		Resource::ProviderOwned(value) => Some(value.resource_kind.as_str()),
		Resource::SyntheticResource(_) => Some("syntheticResource"),
		Resource::DeploymentTarget(_) => Some("deploymentTarget"),
		Resource::Machine(_) => Some("machine"),
	}
}

/// Full desired JSON document for provider-owned resources.
pub fn resource_desired(resource: &Resource) -> Option<&Value> {
	match resource {
		Resource::ProviderOwned(value) => Some(&value.desired),
		Resource::SyntheticResource(value) => Some(&value.desired),
		_ => None,
	}
}

/// Declared dependency edges for graph validation / action rewrite.
pub fn resource_depends_on(resource: &Resource) -> &[String] {
	match resource {
		Resource::DeploymentTarget(value) => &value.depends_on,
		Resource::SyntheticResource(value) => &value.depends_on,
		Resource::ProviderOwned(value) => &value.depends_on,
		_ => &[],
	}
}

/// Explicit lifecycle association to a deployment target, if any.
pub fn resource_associated_deployment_target(resource: &Resource) -> Option<String> {
	match resource {
		Resource::ProviderOwned(value) => value.associated_deployment_target(),
		Resource::SyntheticResource(value) => value
			.desired
			.get("deploymentTarget")
			.and_then(Value::as_str)
			.filter(|v| !v.is_empty())
			.map(str::to_string),
		_ => None,
	}
}

/// Optional confidential binding declared on the resource (ensure/mint producers).
pub fn resource_secret_binding(resource: &Resource) -> Option<&str> {
	match resource {
		Resource::ProviderOwned(value) => value.secret_binding.as_deref(),
		Resource::SyntheticResource(value) => {
			value.desired.get("secretBinding").and_then(Value::as_str)
		}
		_ => None,
	}
}