podup/quadlet/

mod.rs

//! Translate a parsed compose file into Podman Quadlet unit files.
//!
//! Quadlet is Podman's systemd integration: declarative `.container`,
//! `.network` and `.volume` units placed under
//! `~/.config/containers/systemd/` that a systemd generator turns into
//! services, so systemd owns the lifecycle (boot, restart, dependencies)
//! instead of a long-running `podup` process.
//!
//! This is an additive export path, not a replacement for the runner. It
//! maps the common compose fields and warns — loudly, never silently — for
//! every field that is set but has no Quadlet equivalent yet, so generated
//! units never quietly drop configuration.

mod render;
mod unit;
mod warnings;

use crate::compose::types::ComposeFile;
use unit::{build_unit, container_unit, network_unit, volume_unit};

/// A single generated unit file: its name and full contents.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct QuadletUnit {
	/// File name, e.g. `web.container` or `db-data.volume`.
	pub filename: String,
	/// Full file contents, ending in a newline.
	pub contents: String,
}

/// The result of a generation run: the units plus any warnings about set but
/// unmapped fields.
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct QuadletOutput {
	/// Generated unit files, in a deterministic order.
	pub units: Vec<QuadletUnit>,
	/// Human-readable warnings for compose fields with no Quadlet mapping.
	pub warnings: Vec<String>,
}

impl QuadletOutput {
	/// The first unit file name that two different units share, if any. Distinct
	/// compose keys can sanitize to the same stem (e.g. `web:1` and `web_1` both
	/// become `web_1`); writing them would silently overwrite one unit, dropping
	/// a service/network/volume from the export. Callers surface this as an error
	/// instead of clobbering.
	pub fn duplicate_filename(&self) -> Option<&str> {
		let mut seen = std::collections::HashSet::new();
		self.units
			.iter()
			.find(|u| !seen.insert(u.filename.as_str()))
			.map(|u| u.filename.as_str())
	}
}

/// Write `units` into `dir`, creating it if needed, and return the paths written
/// in order. Defense in depth: refuse any unit whose file name is not a plain path
/// component. The library already sanitizes stems, but a write target must never
/// contain a separator, `.` or `..` that could escape `dir`. Shared by
/// `generate quadlet -o` and `autostart --mode quadlet`, so both place units
/// through the identical safety check.
pub fn write_units(
	dir: &std::path::Path,
	units: &[QuadletUnit],
) -> std::io::Result<Vec<std::path::PathBuf>> {
	std::fs::create_dir_all(dir)?;
	let mut written = Vec::with_capacity(units.len());
	for unit in units {
		if std::path::Path::new(&unit.filename).file_name()
			!= Some(std::ffi::OsStr::new(&unit.filename))
		{
			return Err(std::io::Error::new(
				std::io::ErrorKind::InvalidInput,
				format!("refusing unsafe quadlet unit file name: {}", unit.filename),
			));
		}
		let path = dir.join(&unit.filename);
		std::fs::write(&path, &unit.contents)?;
		written.push(path);
	}
	Ok(written)
}

/// Translate a compose file into Quadlet units for the given project name,
/// resolving relative build contexts against the current directory (the common
/// case: running from the project directory). Use [`generate_at`] to resolve them
/// against an explicit base directory instead.
pub fn generate(file: &ComposeFile, project: &str) -> QuadletOutput {
	generate_at(file, project, &std::env::current_dir().unwrap_or_default())
}

/// As [`generate`], but resolves a service's relative `build:` context against
/// `base_dir` (the compose file's directory) rather than the current directory.
/// The systemd generator runs a `.build` unit with no cwd, so a unit written for
/// it must carry an absolute `SetWorkingDirectory`; pass the compose base here.
///
/// Emits one `.container` per service, one `.network` per declared network,
/// and one `.volume` per declared named volume. Replica scaling, inline-Dockerfile
/// builds, and other fields without a Quadlet mapping are reported as warnings
/// rather than silently dropped.
pub fn generate_at(file: &ComposeFile, project: &str, base_dir: &std::path::Path) -> QuadletOutput {
	let mut out = QuadletOutput::default();

	// External networks/volumes are assumed to pre-exist. Emitting a unit would
	// make systemd try to (re-)create them, so skip them here; the container unit
	// references such resources by their existing name instead.
	for (name, cfg) in &file.networks {
		if cfg.as_ref().is_some_and(|c| c.external == Some(true)) {
			continue;
		}
		out.units.push(network_unit(name, project, cfg.as_ref()));
		// `podman network create` (and therefore Quadlet) exposes no key for IPAM
		// options beyond the IPAM driver, so `ipam.options` cannot be emitted. The
		// live engine forwards them via the libpod API directly, so warn rather than
		// let `generate` silently diverge from `up`.
		if let Some(c) = cfg {
			if let Some(ipam) = &c.ipam {
				if !ipam.options.is_empty() {
					out.warnings.push(format!(
						"network '{name}': ipam.options have no Quadlet key and are not emitted; \
						 the live engine forwards them but `generate` cannot"
					));
				}
			}
		}
	}
	for (name, cfg) in &file.volumes {
		if cfg.as_ref().is_some_and(|c| c.external == Some(true)) {
			continue;
		}
		out.units.push(volume_unit(name, project, cfg.as_ref()));
	}

	let declared_volumes: Vec<&str> = file
		.volumes
		.iter()
		.filter(|(_, cfg)| cfg.as_ref().is_none_or(|c| c.external != Some(true)))
		.map(|(name, _)| name.as_str())
		.collect();
	let declared_networks: Vec<&str> = file
		.networks
		.iter()
		.filter(|(_, cfg)| cfg.as_ref().is_none_or(|c| c.external != Some(true)))
		.map(|(name, _)| name.as_str())
		.collect();
	for (name, service) in &file.services {
		// Emit a `.build` unit first so the systemd generator builds the image
		// before the container that references it via `Image=<stem>.build`.
		if let Some(unit) = build_unit(name, project, service, base_dir, &mut out.warnings) {
			out.units.push(unit);
		}
		out.units.push(container_unit(
			name,
			project,
			service,
			&declared_volumes,
			&declared_networks,
			&file.secrets,
			&mut out.warnings,
		));
	}

	out
}

#[cfg(test)]
mod tests;