use std::collections::BTreeMap;
use std::io::Read;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use tempfile::TempDir;
use crate::{
Adapter, Artifact, BackendStatus, ConversionKind, Error, Format, Graph, Limits, Plan, Policy,
Result, StepRequest,
};
use crate::builtin::{BuiltinAdapter, detect};
#[cfg(feature = "archives")]
use crate::archives::ArchivesAdapter;
#[cfg(feature = "media")]
use crate::media::MediaAdapter;
#[derive(Clone, Debug, Default)]
pub struct ConversionOptions {
pub from: Option<String>,
pub backend: Option<String>,
pub forced_plan: Option<Plan>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Warning {
pub step: usize,
pub backend: String,
pub operation: String,
pub kind: ConversionKind,
pub message: String,
}
#[derive(Debug)]
pub struct ConversionReport {
workspace: TempDir,
pub plan: Plan,
pub artifacts: Vec<Artifact>,
pub warnings: Vec<Warning>,
}
impl ConversionReport {
#[must_use]
pub fn directory(&self) -> &Path {
self.workspace.path()
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Identification {
pub format: String,
pub method: IdentificationMethod,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum IdentificationMethod {
Override,
Extension,
Magic,
Unknown,
}
pub struct Converter {
graph: Graph,
adapters: BTreeMap<String, Arc<dyn Adapter>>,
order: Vec<String>,
policy: Policy,
limits: Limits,
}
impl std::fmt::Debug for Converter {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("Converter")
.field("adapters", &self.order)
.field("formats", &self.graph.formats().count())
.finish()
}
}
impl Default for Converter {
fn default() -> Self {
Self::new()
}
}
impl Converter {
#[must_use]
pub fn new() -> Self {
let mut converter = Self {
graph: Graph::new(),
adapters: BTreeMap::new(),
order: Vec::new(),
policy: Policy::default(),
limits: Limits::default(),
};
let _ = converter.register(Arc::new(BuiltinAdapter));
#[cfg(feature = "media")]
{
let _ = converter.register(Arc::new(MediaAdapter));
}
#[cfg(feature = "archives")]
{
let _ = converter.register(Arc::new(ArchivesAdapter));
}
converter
}
#[cfg(feature = "external")]
pub async fn discover() -> Self {
let mut converter = Self::new();
let adapters = crate::external::discover().await;
for adapter in adapters {
if adapter.status().available {
let _ = converter.register(adapter);
}
}
converter
}
pub fn register(&mut self, adapter: Arc<dyn Adapter>) -> Result<()> {
let name = adapter.name().to_owned();
if name.is_empty() || name.len() > 64 {
return Err(Error::Invalid("invalid adapter name".into()));
}
let formats = adapter.formats();
let conversions = adapter.conversions();
if formats.is_empty() || formats.len() > 8192 || conversions.len() > 1_000_000 {
return Err(Error::Invalid("adapter registration rejected".into()));
}
let mut previous = self.adapters.clone();
let mut ordered = self.order.clone();
ordered.retain(|existing| existing != &name);
ordered.push(name.clone());
previous.insert(name.clone(), Arc::clone(&adapter));
let mut graph = Graph::new();
for key in &ordered {
for format in previous[key].formats() {
graph.add_format(format).map_err(Error::Plan)?;
}
}
for key in &ordered {
for conversion in previous[key].conversions() {
graph.add_conversion(conversion).map_err(Error::Plan)?;
}
}
self.graph = graph;
self.adapters = previous;
self.order = ordered;
Ok(())
}
#[must_use]
pub fn limits(mut self, limits: Limits) -> Self {
self.limits = limits;
self
}
#[must_use]
pub fn with_policy(mut self, policy: Policy) -> Self {
self.policy = policy;
self
}
pub fn set_policy(&mut self, policy: Policy) {
self.policy = policy;
}
#[must_use]
pub fn graph(&self) -> &Graph {
&self.graph
}
#[must_use]
pub fn policy(&self) -> &Policy {
&self.policy
}
#[must_use]
pub fn formats(&self) -> Vec<Format> {
self.graph.formats().cloned().collect()
}
#[must_use]
pub fn backends(&self) -> Vec<BackendStatus> {
self.adapters
.values()
.map(|adapter| adapter.status())
.collect()
}
#[must_use]
pub fn resolve(&self, value: &str) -> Option<&Format> {
self.graph.resolve(value)
}
pub fn identify(&self, path: &Path) -> Result<Identification> {
let metadata = std::fs::symlink_metadata(path)
.map_err(|_| Error::Invalid(format!("cannot inspect {}", path.display())))?;
if !metadata.file_type().is_file() {
return Err(Error::Security("input is not a regular file".into()));
}
if metadata.len() == 0 {
return Err(Error::Security("input is empty".into()));
}
if let Some(id) = extension_of(path).and_then(|value| self.graph.resolve(&value)) {
return Ok(Identification {
format: id.id.clone(),
method: IdentificationMethod::Extension,
});
}
let mut header = [0u8; 1024];
let mut file =
std::fs::File::open(path).map_err(|_| Error::Invalid("input is unreadable".into()))?;
let count = file
.read(&mut header)
.map_err(|_| Error::Invalid("input is unreadable".into()))?;
if let Some(id) = detect(&header[..count]).and_then(|name| self.graph.resolve(name)) {
return Ok(Identification {
format: id.id.clone(),
method: IdentificationMethod::Magic,
});
}
Ok(Identification {
format: "bin".into(),
method: IdentificationMethod::Unknown,
})
}
pub fn plan(&self, from: &str, to: &str, policy: &Policy) -> Result<Vec<Plan>> {
Ok(self.graph.routes(from, to, policy)?)
}
pub async fn convert(
&self,
paths: &[PathBuf],
to: &str,
options: &ConversionOptions,
) -> Result<ConversionReport> {
if paths.is_empty() {
return Err(Error::Invalid("no input files given".into()));
}
if paths.len() > self.limits.max_artifacts {
return Err(Error::Limit("input file count".into()));
}
let target = self
.graph
.resolve(to)
.ok_or_else(|| Error::Invalid(format!("unknown target format: {to}")))?
.id
.clone();
let identification = match &options.from {
Some(value) => {
let format = self
.graph
.resolve(value)
.ok_or_else(|| Error::Invalid(format!("unknown source format: {value}")))?
.id
.clone();
Identification {
format,
method: IdentificationMethod::Override,
}
}
None => self.identify(&paths[0])?,
};
if options.from.is_none() {
for path in &paths[1..] {
let other = self.identify(path)?;
if other.format != identification.format {
return Err(Error::Invalid(format!(
"inputs have different formats: {} and {}",
identification.format, other.format
)));
}
}
}
let source = identification.format;
let plans = match &options.forced_plan {
Some(plan) => vec![plan.clone()],
None => {
let mut plans = self.graph.routes(&source, &target, &self.policy)?;
if let Some(backend) = &options.backend {
plans.retain(|plan| {
plan.steps.is_empty()
|| plan.steps.iter().all(|step| &step.backend == backend)
});
if plans.is_empty() {
return Err(Error::Invalid(format!(
"no route from {source} to {target} uses only backend {backend}"
)));
}
}
plans
}
};
let mut failures = Vec::new();
for plan in plans {
let attempt = self
.execute(&plan, &source, &target, paths, &options.backend)
.await;
match attempt {
Ok(report) => return Ok(report),
Err(error) => {
let rendered = if plan.steps.is_empty() {
"identity".to_owned()
} else {
plan.steps
.iter()
.map(|step| format!("{}→{} via {}", step.from, step.to, step.backend))
.collect::<Vec<_>>()
.join(" | ")
};
failures.push(format!("{rendered}: {error}"));
}
}
}
Err(Error::RoutesFailed(failures.join("; ")))
}
async fn execute(
&self,
plan: &Plan,
source: &str,
target: &str,
paths: &[PathBuf],
pinned: &Option<String>,
) -> Result<ConversionReport> {
let workspace = TempDir::new()?;
let mut artifacts = Vec::with_capacity(paths.len());
for (index, path) in paths.iter().enumerate() {
artifacts.push(stage_input(
path,
workspace.path(),
index,
source,
&self.limits,
)?);
}
let mut warnings = Vec::new();
for (index, step) in plan.steps.iter().enumerate() {
if !self.policy.allows(step.kind) {
return Err(Error::Security(format!(
"{:?} steps are disabled",
step.kind
)));
}
if step.external && !self.policy.allow_external {
return Err(Error::Security(format!(
"{} uses a native external tool; enable Policy::allow_external",
step.backend
)));
}
if pinned
.as_ref()
.is_some_and(|backend| &step.backend != backend)
{
return Err(Error::Invalid("plan uses a disallowed backend".into()));
}
if artifacts
.iter()
.any(|artifact| artifact.format != step.from)
{
return Err(Error::Conversion(format!(
"step {index} expected {} inputs",
step.from
)));
}
let adapter = self.adapters.get(&step.backend).ok_or_else(|| {
Error::Conversion(format!("backend {} is not registered", step.backend))
})?;
let step_dir = workspace.path().join(step_dir_name(index)?);
tokio::fs::create_dir_all(&step_dir).await?;
let request = StepRequest {
inputs: artifacts.clone(),
output_dir: step_dir.clone(),
from: step.from.clone(),
to: step.to.clone(),
operation: step.operation.clone(),
limits: self.limits.clone(),
};
match adapter.convert(&request).await {
Ok(produced) => {
artifacts = validate_artifacts(produced, &step_dir, step, &self.limits)?
}
Err(error) => {
let _ = tokio::fs::remove_dir_all(&step_dir).await;
return Err(error);
}
}
if let Some(warning) = warning_for(index, step) {
warnings.push(warning);
}
}
if artifacts.iter().any(|artifact| artifact.format != *target) {
return Err(Error::Conversion(
"final artifacts do not match the target".into(),
));
}
Ok(ConversionReport {
workspace,
plan: plan.clone(),
artifacts,
warnings,
})
}
}
fn step_dir_name(index: usize) -> Result<String> {
Ok(format!("step-{index:04}"))
}
fn warning_for(index: usize, step: &crate::Conversion) -> Option<Warning> {
let message = match step.kind {
ConversionKind::Lossless => return None,
ConversionKind::Lossy => format!(
"{} re-encoded through {}; expect quality or metadata loss",
step.to, step.operation
),
ConversionKind::Bridge => format!(
"{} bridged through {}; the result expresses {} differently",
step.from, step.operation, step.to
),
ConversionKind::Reinterpret => format!(
"bytes were reinterpreted as {} by {}",
step.to, step.backend
),
ConversionKind::Package => "files were packaged; contents were not converted".into(),
ConversionKind::Extract => "archive members were extracted as separate files".into(),
};
Some(Warning {
step: index,
backend: step.backend.clone(),
operation: step.operation.clone(),
kind: step.kind,
message,
})
}
fn extension_of(path: &Path) -> Option<String> {
let name = path.file_name()?.to_str()?;
let (_, suffix) = name.split_once('.')?;
let suffix = suffix.to_ascii_lowercase();
(!suffix.is_empty() && !suffix.contains('.')).then_some(suffix)
}
fn stage_input(
path: &Path,
dir: &Path,
index: usize,
format: &str,
limits: &Limits,
) -> Result<Artifact> {
let metadata = std::fs::symlink_metadata(path)?;
if !metadata.file_type().is_file() {
return Err(Error::Security("input is not a regular file".into()));
}
if metadata.len() > limits.max_input_bytes {
return Err(Error::Limit("input bytes exceed budget".into()));
}
let destination = dir.join(format!("input-{index}"));
std::fs::copy(path, &destination)?;
let staged = std::fs::symlink_metadata(&destination)?;
if !staged.file_type().is_file() || staged.len() != metadata.len() {
return Err(Error::Security("staged input changed during copy".into()));
}
Ok(Artifact {
path: destination,
format: format.to_owned(),
})
}
fn validate_artifacts(
produced: Vec<Artifact>,
step_dir: &Path,
step: &crate::Conversion,
limits: &Limits,
) -> Result<Vec<Artifact>> {
if produced.len() > limits.max_artifacts {
return Err(Error::Limit("adapter produced too many artifacts".into()));
}
let root = step_dir
.canonicalize()
.map_err(|_| Error::Security("step directory disappeared".into()))?;
let mut artifacts = Vec::with_capacity(produced.len());
let mut total = 0u64;
for artifact in produced {
if artifact.format != step.to {
return Err(Error::Conversion(format!(
"{} returned a {} artifact for a {} step",
step.backend, artifact.format, step.to
)));
}
let metadata = std::fs::symlink_metadata(&artifact.path)
.map_err(|_| Error::Security("adapter artifact does not exist".into()))?;
if !metadata.file_type().is_file() {
return Err(Error::Security(
"adapter returned a non-regular file".into(),
));
}
let canonical = artifact.path.canonicalize().map_err(|_| {
Error::Security("adapter returned a path that cannot be resolved".into())
})?;
if !canonical.starts_with(&root) {
return Err(Error::Security(
"adapter wrote outside its step directory".into(),
));
}
total = total
.checked_add(metadata.len())
.ok_or_else(|| Error::Limit("artifact byte overflow".into()))?;
if total > limits.max_output_bytes {
return Err(Error::Limit("artifact bytes exceed budget".into()));
}
artifacts.push(Artifact {
path: canonical,
format: artifact.format,
});
}
Ok(artifacts)
}
#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
use super::*;
fn graph_backend_converter() -> Converter {
Converter::new()
}
#[test]
fn registration_is_idempotent_by_name() {
let converter = graph_backend_converter();
assert_eq!(
converter
.order
.iter()
.filter(|name| name.as_str() == "builtin")
.count(),
1
);
}
#[test]
#[cfg(feature = "media")]
fn extension_detection_wins_and_magic_is_fallback() {
let converter = graph_backend_converter();
let dir = TempDir::new().unwrap();
std::fs::write(dir.path().join("note.txt"), b"plain text").unwrap();
assert_eq!(
converter
.identify(&dir.path().join("note.txt"))
.unwrap()
.method,
IdentificationMethod::Extension
);
std::fs::write(dir.path().join("payload.dat"), b"\x89PNG\r\n\x1a\nxx").unwrap();
let found = converter.identify(&dir.path().join("payload.dat")).unwrap();
assert_eq!(found.format, "png");
assert_eq!(found.method, IdentificationMethod::Magic);
std::fs::write(dir.path().join("random"), [1, 2, 3, 250, 7]).unwrap();
let found = converter.identify(&dir.path().join("random")).unwrap();
assert_eq!(found.format, "bin");
assert_eq!(found.method, IdentificationMethod::Unknown);
}
#[test]
fn identify_rejects_nonregular_and_empty() {
let converter = graph_backend_converter();
let dir = TempDir::new().unwrap();
std::fs::create_dir(dir.path().join("adir")).unwrap();
assert!(matches!(
converter.identify(&dir.path().join("adir")),
Err(Error::Security(_))
));
std::fs::write(dir.path().join("empty.txt"), b"").unwrap();
assert!(matches!(
converter.identify(&dir.path().join("empty.txt")),
Err(Error::Security(_))
));
}
#[tokio::test]
async fn unknown_files_require_reinterpretation_opt_in() {
let converter = graph_backend_converter();
let dir = TempDir::new().unwrap();
let path = dir.path().join("mystery");
std::fs::write(&path, [7u8; 40]).unwrap();
let default = converter
.convert(
std::slice::from_ref(&path),
"txt",
&ConversionOptions::default(),
)
.await;
assert!(matches!(default, Err(Error::Plan(_))), "{default:?}");
let policy = Policy {
allow_reinterpret: true,
..Policy::default()
};
let report = Converter::default()
.with_policy(policy)
.convert(&[path], "txt", &ConversionOptions::default())
.await
.unwrap();
assert_eq!(report.plan.steps.len(), 1);
assert!(
report
.warnings
.iter()
.any(|warning| warning.kind == ConversionKind::Reinterpret)
);
}
#[tokio::test]
async fn same_format_requests_stage_a_copy() {
let converter = graph_backend_converter();
let dir = TempDir::new().unwrap();
let path = dir.path().join("data.txt");
std::fs::write(&path, b"unchanged").unwrap();
let report = converter
.convert(&[path], "txt", &ConversionOptions::default())
.await
.unwrap();
assert!(report.plan.steps.is_empty());
assert_eq!(
std::fs::read_to_string(&report.artifacts[0].path).unwrap(),
"unchanged"
);
}
#[tokio::test]
async fn mixed_format_inputs_are_rejected() {
let converter = graph_backend_converter();
let dir = TempDir::new().unwrap();
std::fs::write(dir.path().join("a.txt"), b"a").unwrap();
std::fs::write(dir.path().join("b.gz"), b"\x1f\x8brest").unwrap();
let error = converter
.convert(
&[dir.path().join("a.txt"), dir.path().join("b.gz")],
"tar",
&ConversionOptions::default(),
)
.await
.err();
assert!(matches!(error, Some(Error::Invalid(_))));
}
#[test]
fn validating_artifacts_rejects_escapes_and_mismatch() {
let dir = TempDir::new().unwrap();
let step_dir = dir.path().join("step");
std::fs::create_dir(&step_dir).unwrap();
let step = crate::Conversion::new(
"a",
"png",
"backend",
"convert",
ConversionKind::Lossless,
1,
);
let limits = Limits::default();
std::fs::write(dir.path().join("escape.png"), b"x").unwrap();
let escape = Artifact {
path: dir.path().join("escape.png"),
format: "png".into(),
};
assert!(matches!(
validate_artifacts(vec![escape], &step_dir, &step, &limits),
Err(Error::Security(_))
));
let directory = Artifact {
path: step_dir.clone(),
format: "png".into(),
};
assert!(matches!(
validate_artifacts(vec![directory], &step_dir, &step, &limits),
Err(Error::Security(_))
));
let wrong = Artifact {
path: step_dir.join("wrong.jpg"),
format: "jpeg".into(),
};
std::fs::write(&wrong.path, b"x").unwrap();
assert!(matches!(
validate_artifacts(vec![wrong], &step_dir, &step, &limits),
Err(Error::Conversion(_))
));
std::fs::write(step_dir.join("real.png"), b"x").unwrap();
let good = Artifact {
path: step_dir.join("real.png"),
format: "png".into(),
};
assert_eq!(
validate_artifacts(vec![good], &step_dir, &step, &limits)
.unwrap()
.len(),
1
);
}
#[test]
fn stage_input_rejects_nonregular_and_oversize() {
let limits = Limits {
max_input_bytes: 4,
..Limits::default()
};
let dir = TempDir::new().unwrap();
let path = dir.path().join("in");
std::fs::write(&path, b"payload").unwrap();
assert!(matches!(
stage_input(&path, dir.path(), 0, "bin", &limits),
Err(Error::Limit(_))
));
std::fs::create_dir(dir.path().join("adir")).unwrap();
assert!(matches!(
stage_input(
&dir.path().join("adir"),
dir.path(),
1,
"bin",
&Limits::default()
),
Err(Error::Security(_))
));
}
#[tokio::test]
async fn backend_constraint_selects_or_rejects_routes() {
let converter = graph_backend_converter();
let dir = TempDir::new().unwrap();
std::fs::write(dir.path().join("data.txt"), b"[1, 2, 3]").unwrap();
let options = ConversionOptions {
from: Some("txt".into()),
backend: Some("builtin".into()),
forced_plan: None,
};
let report = converter
.convert(&[dir.path().join("data.txt")], "csv", &options)
.await
.err();
assert!(report.is_some(),);
}
#[test]
#[cfg(feature = "media")]
fn graph_routes_honor_policy() {
let converter = graph_backend_converter();
let strict = converter
.plan("bin", "png", &Policy::default())
.unwrap_err();
assert!(matches!(
strict,
Error::Plan(convert_rs_core::PlanError::NoRoute { .. })
));
}
}