nxd_core/adapters/

external_runtime.rs

//! Compose linked first-party providers and configured external runtimes.
//!
//! External executables are identity-bound by path and content. Linked providers
//! are supplied explicitly by the CLI composition root.

use crate::contract::canonical_json;
use crate::contract::{
	CanonicalConfig, PROVIDER_PROTOCOL_V1, ProviderInstance, SECRET_PROTOCOL_V1,
	SecretResolverInstance,
};
use crate::plan::PlanEnvelope;
use crate::plan::sha256_hex_bytes;
use crate::plugin_protocol::v1;
use crate::ports::provider::Provider;
use serde_json::json;
use std::collections::BTreeMap;
use std::ffi::OsString;
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Arc;

type ProviderFactory =
	dyn Fn(&[OsString]) -> Result<Arc<dyn Provider>, CompositionError> + Send + Sync;

/// Explicit linked-provider factories owned by the CLI composition root.
#[derive(Clone, Default)]
pub struct LinkedProviderRegistry {
	factories: BTreeMap<String, Arc<ProviderFactory>>,
}

impl LinkedProviderRegistry {
	pub fn register<F>(&mut self, kind: impl Into<String>, factory: F) -> Result<(), CompositionError>
	where
		F: Fn(&[OsString]) -> Result<Arc<dyn Provider>, CompositionError> + Send + Sync + 'static,
	{
		let kind = kind.into();
		if kind.is_empty() || self.factories.insert(kind.clone(), Arc::new(factory)).is_some() {
			return Err(CompositionError::InvalidConfig(format!(
				"duplicate linked provider kind {kind}"
			)));
		}
		Ok(())
	}

	fn create(
		&self,
		kind: &str,
		arguments: &[OsString],
	) -> Result<Option<Arc<dyn Provider>>, CompositionError> {
		self.factories.get(kind).map(|factory| factory(arguments)).transpose()
	}
}

/// Immutable identity of a composed external executable.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ExecutableIdentity {
	pub path: PathBuf,
	/// `sha256:<hex>` of the executable bytes at composition time.
	pub digest: String,
	pub protocol: String,
}

/// One provider instance registered for protocol-driven sessions.
#[derive(Clone)]
pub struct ProviderExecutable {
	pub instance_id: String,
	pub kind: String,
	pub identity: ExecutableIdentity,
	pub arguments: Vec<OsString>,
	pub linked: Option<Arc<dyn Provider>>,
	pub expected_version: Option<String>,
	pub expected_runtime_digest: Option<String>,
}

impl std::fmt::Debug for ProviderExecutable {
	fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		formatter
			.debug_struct("ProviderExecutable")
			.field("instance_id", &self.instance_id)
			.field("kind", &self.kind)
			.field("identity", &self.identity)
			.field("arguments", &self.arguments)
			.field("linked", &self.linked.is_some())
			.field("expected_version", &self.expected_version)
			.field("expected_runtime_digest", &self.expected_runtime_digest)
			.finish()
	}
}

/// One secret resolver/sink executable registered for action-scoped resolution.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SecretExecutable {
	pub resolver_id: String,
	pub identity: ExecutableIdentity,
	pub arguments: Vec<OsString>,
}

/// Complete external runtime graph for one evaluated configuration.
#[derive(Clone, Debug, Default)]
pub struct ExternalRuntimeGraph {
	/// Provider instance id → executable.
	pub providers: BTreeMap<String, ProviderExecutable>,
	/// Secret resolver id → executable.
	pub secret_resolvers: BTreeMap<String, SecretExecutable>,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum CompositionError {
	InvalidConfig(String),
	MissingExecutable(String),
	CapabilityUnavailable(String),
}

impl std::fmt::Display for CompositionError {
	fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		match self {
			Self::InvalidConfig(message)
			| Self::MissingExecutable(message)
			| Self::CapabilityUnavailable(message) => write!(formatter, "{message}"),
		}
	}
}

impl std::error::Error for CompositionError {}

impl ExternalRuntimeGraph {
	/// Rehydrate only the executable identities authorized by a reviewed plan.
	/// Every executable is reread and its digest checked before mutation.
	pub fn from_plan(plan: &PlanEnvelope) -> Result<Self, CompositionError> {
		Self::from_plan_with_linked(plan, &LinkedProviderRegistry::default())
	}

	pub fn from_plan_with_linked(
		plan: &PlanEnvelope,
		linked: &LinkedProviderRegistry,
	) -> Result<Self, CompositionError> {
		let mut graph = Self::default();
		for runtime in &plan.spec.provider_runtimes {
			let arguments = runtime.arguments.iter().map(OsString::from).collect::<Vec<_>>();
			if runtime.nxd_revision.is_some() {
				if runtime.nxd_revision.as_deref() != Some(env!("NXD_GIT_REVISION")) {
					return Err(CompositionError::CapabilityUnavailable(format!(
						"linked provider {} NXD revision differs from the reviewed plan",
						runtime.provider_instance
					)));
				}
				let provider = linked.create(&runtime.provider_kind, &arguments)?.ok_or_else(|| {
					CompositionError::CapabilityUnavailable(format!(
						"linked provider kind {} is not registered",
						runtime.provider_kind
					))
				})?;
				graph.providers.insert(
					runtime.provider_instance.clone(),
					ProviderExecutable {
						instance_id: runtime.provider_instance.clone(),
						kind: runtime.provider_kind.clone(),
						identity: ExecutableIdentity {
							path: PathBuf::new(),
							digest: runtime.runtime_digest.clone(),
							protocol: "linked".into(),
						},
						arguments,
						linked: Some(provider),
						expected_version: Some(runtime.provider_version.clone()),
						expected_runtime_digest: Some(runtime.runtime_digest.clone()),
					},
				);
				continue;
			}
			let protocol = runtime.protocol.as_deref().ok_or_else(|| {
				CompositionError::InvalidConfig(format!(
					"external provider {} is missing protocol",
					runtime.provider_instance
				))
			})?;
			let executable_path = runtime.executable_path.as_deref().ok_or_else(|| {
				CompositionError::InvalidConfig(format!(
					"external provider {} is missing executablePath",
					runtime.provider_instance
				))
			})?;
			let identity = executable_identity(
				executable_path,
				protocol,
				&format!("provider {}", runtime.provider_instance),
			)?;
			if Some(identity.digest.as_str()) != runtime.executable_digest.as_deref()
				|| identity.digest != runtime.runtime_digest
			{
				return Err(CompositionError::CapabilityUnavailable(format!(
					"provider {} executable digest differs from the reviewed plan",
					runtime.provider_instance
				)));
			}
			graph.providers.insert(
				runtime.provider_instance.clone(),
				ProviderExecutable {
					instance_id: runtime.provider_instance.clone(),
					kind: runtime.provider_kind.clone(),
					identity,
					arguments,
					linked: None,
					expected_version: Some(runtime.provider_version.clone()),
					expected_runtime_digest: None,
				},
			);
		}
		for runtime in &plan.spec.secret_runtimes {
			let identity = executable_identity(
				&runtime.executable_path,
				&runtime.protocol,
				&format!("secret resolver {}", runtime.resolver_id),
			)?;
			if identity.digest != runtime.executable_digest {
				return Err(CompositionError::CapabilityUnavailable(format!(
					"secret resolver {} executable digest differs from the reviewed plan",
					runtime.resolver_id
				)));
			}
			graph.secret_resolvers.insert(
				runtime.resolver_id.clone(),
				SecretExecutable {
					resolver_id: runtime.resolver_id.clone(),
					identity,
					arguments: runtime.arguments.iter().map(OsString::from).collect(),
				},
			);
		}
		Ok(graph)
	}

	/// Build the graph from evaluated canonical configuration.
	///
	/// Declared provider executable commands and secret resolvers are
	/// verified immediately.
	pub fn from_canonical(config: &CanonicalConfig) -> Result<Self, CompositionError> {
		Self::from_canonical_with_linked(config, &LinkedProviderRegistry::default())
	}

	pub fn from_canonical_with_linked(
		config: &CanonicalConfig,
		linked: &LinkedProviderRegistry,
	) -> Result<Self, CompositionError> {
		let mut identities = BTreeMap::new();
		let mut providers = BTreeMap::new();
		for instance in &config.spec.provider_instances {
			if let Some(executable) = provider_executable(instance, &mut identities, linked)?
				&& providers.insert(executable.instance_id.clone(), executable).is_some()
			{
				return Err(CompositionError::InvalidConfig(format!(
					"duplicate provider instance {}",
					instance.id
				)));
			}
		}

		let mut secret_resolvers = BTreeMap::new();
		for resolver in &config.spec.secret_resolvers {
			let executable = secret_executable(resolver, &mut identities)?;
			if secret_resolvers.insert(executable.resolver_id.clone(), executable).is_some() {
				return Err(CompositionError::InvalidConfig(format!(
					"duplicate secret resolver {}",
					resolver.id
				)));
			}
		}

		// Fail closed when a binding names a resolver that was not composed.
		for binding in &config.spec.secret_bindings {
			if !secret_resolvers.contains_key(&binding.resolver) && !secret_resolvers.is_empty() {
				return Err(CompositionError::CapabilityUnavailable(format!(
					"secret binding {} requires secret resolver {} which is not configured",
					binding.id, binding.resolver
				)));
			}
		}

		Ok(Self { providers, secret_resolvers })
	}

	pub fn provider(&self, instance_id: &str) -> Option<&ProviderExecutable> {
		self.providers.get(instance_id)
	}

	pub fn secret_resolver(&self, resolver_id: &str) -> Option<&SecretExecutable> {
		self.secret_resolvers.get(resolver_id)
	}

	/// Require a composed provider instance.
	pub fn require_provider(
		&self,
		instance_id: &str,
	) -> Result<&ProviderExecutable, CompositionError> {
		self.provider(instance_id).ok_or_else(|| {
			CompositionError::CapabilityUnavailable(format!(
				"provider instance {instance_id} is not composed"
			))
		})
	}

	/// Require a secret resolver executable for action-scoped resolution.
	pub fn require_secret_resolver(
		&self,
		resolver_id: &str,
	) -> Result<&SecretExecutable, CompositionError> {
		self.secret_resolver(resolver_id).ok_or_else(|| {
			CompositionError::CapabilityUnavailable(format!(
				"secret resolver {resolver_id} is not configured"
			))
		})
	}
}

fn provider_executable(
	instance: &ProviderInstance,
	identities: &mut BTreeMap<(String, String), ExecutableIdentity>,
	linked: &LinkedProviderRegistry,
) -> Result<Option<ProviderExecutable>, CompositionError> {
	match (&instance.command, &instance.protocol) {
		(None, None) => {
			let arguments = instance.arguments.iter().map(OsString::from).collect::<Vec<_>>();
			let Some(provider) = linked.create(&instance.kind, &arguments)? else { return Ok(None) };
			Ok(Some(ProviderExecutable {
				instance_id: instance.id.clone(),
				kind: instance.kind.clone(),
				identity: ExecutableIdentity {
					path: PathBuf::new(),
					digest: linked_identity_digest(&instance.kind),
					protocol: "linked".into(),
				},
				arguments,
				linked: Some(provider),
				expected_version: None,
				expected_runtime_digest: None,
			}))
		}
		(Some(command), Some(protocol)) => {
			if protocol != PROVIDER_PROTOCOL_V1 {
				return Err(CompositionError::InvalidConfig(format!(
					"provider {} protocol must be {PROVIDER_PROTOCOL_V1}",
					instance.id
				)));
			}
			let identity = executable_identity_cached(
				identities,
				command,
				protocol,
				&format!("provider {}", instance.id),
			)?;
			Ok(Some(ProviderExecutable {
				instance_id: instance.id.clone(),
				kind: instance.kind.clone(),
				identity,
				arguments: instance.arguments.iter().map(OsString::from).collect(),
				linked: None,
				expected_version: None,
				expected_runtime_digest: None,
			}))
		}
		_ => Err(CompositionError::InvalidConfig(format!(
			"provider {} must declare both command and protocol",
			instance.id
		))),
	}
}

fn linked_identity_digest(kind: &str) -> String {
	let identity = format!("{}\n{kind}", env!("NXD_GIT_REVISION"));
	format!("sha256:{}", sha256_hex_bytes(identity.as_bytes()))
}

pub fn linked_runtime_digest(
	kind: &str,
	provider_version: &str,
	capabilities: impl IntoIterator<Item = impl AsRef<str>>,
	resource_kinds: &[v1::ResourceKindDescriptor],
) -> Result<String, serde_json::Error> {
	let mut capabilities =
		capabilities.into_iter().map(|value| value.as_ref().to_string()).collect::<Vec<_>>();
	capabilities.sort();
	let mut resource_schema_digests = resource_kinds
		.iter()
		.map(|descriptor| {
			format!("{}:sha256:{}", descriptor.kind, sha256_hex_bytes(&descriptor.schema_json))
		})
		.collect::<Vec<_>>();
	resource_schema_digests.sort();
	Ok(format!(
		"sha256:{}",
		sha256_hex_bytes(
			canonical_json(&json!({
				"nxdRevision": env!("NXD_GIT_REVISION"),
				"providerKind": kind,
				"providerVersion": provider_version,
				"capabilities": capabilities,
				"resourceSchemaDigests": resource_schema_digests,
			}))?
			.as_bytes()
		)
	))
}

fn secret_executable(
	resolver: &SecretResolverInstance,
	identities: &mut BTreeMap<(String, String), ExecutableIdentity>,
) -> Result<SecretExecutable, CompositionError> {
	if resolver.protocol != SECRET_PROTOCOL_V1 {
		return Err(CompositionError::InvalidConfig(format!(
			"secret resolver {} protocol must be {SECRET_PROTOCOL_V1}",
			resolver.id
		)));
	}
	let identity = executable_identity_cached(
		identities,
		&resolver.command,
		&resolver.protocol,
		&format!("secret resolver {}", resolver.id),
	)?;
	Ok(SecretExecutable {
		resolver_id: resolver.id.clone(),
		identity,
		arguments: resolver.arguments.iter().map(OsString::from).collect(),
	})
}

fn executable_identity_cached(
	identities: &mut BTreeMap<(String, String), ExecutableIdentity>,
	command: &str,
	protocol: &str,
	label: &str,
) -> Result<ExecutableIdentity, CompositionError> {
	let key = (command.to_string(), protocol.to_string());
	if let Some(identity) = identities.get(&key) {
		return Ok(identity.clone());
	}
	let identity = executable_identity(command, protocol, label)?;
	identities.insert(key, identity.clone());
	Ok(identity)
}

fn executable_identity(
	command: &str,
	protocol: &str,
	label: &str,
) -> Result<ExecutableIdentity, CompositionError> {
	let path = PathBuf::from(command);
	if !path.is_absolute() {
		return Err(CompositionError::InvalidConfig(format!(
			"{label} command must be an absolute path: {command}"
		)));
	}
	if !path.is_file() {
		return Err(CompositionError::MissingExecutable(format!(
			"{label} executable is missing or not a file: {}",
			path.display()
		)));
	}
	let digest = file_digest(&path).map_err(|error| {
		CompositionError::MissingExecutable(format!(
			"{label} executable at {} could not be read for identity: {error}",
			path.display()
		))
	})?;
	Ok(ExecutableIdentity { path, digest, protocol: protocol.to_string() })
}

fn file_digest(path: &Path) -> Result<String, String> {
	let bytes = fs::read(path).map_err(|error| error.to_string())?;
	Ok(format!("sha256:{}", sha256_hex_bytes(&bytes)))
}

#[cfg(test)]
#[path = "external_runtime_tests.rs"]
mod tests;