use std::collections::{BTreeMap, BTreeSet};
use std::io::Read;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use tempfile::TempDir;
use crate::{
Adapter, Artifact, BackendStatus, ContentKind, ContentProfile, 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>,
pub params: BTreeMap<String, String>,
pub verify: bool,
pub reencode: bool,
pub preserve: Vec<String>,
pub inspect_content: bool,
}
impl ConversionOptions {
fn validate(&self) -> Result<()> {
if let Some(quality) = self.params.get("quality") {
let value: u8 = quality
.trim()
.parse()
.map_err(|_| Error::Invalid(format!("quality must be 0-100, got {quality}")))?;
if value > 100 {
return Err(Error::Invalid(format!(
"quality must be 0-100, got {value}"
)));
}
}
if self.reencode && self.forced_plan.is_some() {
return Err(Error::Invalid(
"reencode replaces route search and cannot combine with a forced plan".into(),
));
}
if self.inspect_content && self.forced_plan.is_some() {
return Err(Error::Invalid(
"inspect_content drives route search and cannot combine with a forced plan".into(),
));
}
Ok(())
}
fn check_forced_retention(&self, plan: &Plan) -> Result<()> {
for step in &plan.steps {
for wanted in &self.preserve {
let wanted = wanted.trim().to_ascii_lowercase();
if wanted.is_empty() {
continue;
}
if !step.retained.iter().any(|held| held == &wanted) {
return Err(Error::Security(format!(
"step {} via {} does not declare it preserves {wanted}",
step.operation, step.backend
)));
}
}
}
Ok(())
}
fn check_forced_content(
&self,
plan: &Plan,
target: &Format,
profile: Option<&ContentProfile>,
require: &[ContentKind],
require_content: bool,
) -> Result<()> {
for wanted in require {
let delivered = profile
.filter(|found| found.format == target.id)
.is_some_and(|found| found.declares(wanted))
|| plan
.produced()
.iter()
.any(|produced| wanted.matches(produced))
|| (!require_content
&& target
.payloads
.iter()
.any(|declared| wanted.matches(declared)));
if !delivered {
return Err(Error::Security(format!(
"forced plan does not deliver required content {wanted} in {target}",
target = target.id
)));
}
}
Ok(())
}
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct RouteAttempt {
pub index: usize,
pub route: String,
pub plan: Plan,
pub error: Option<String>,
}
impl RouteAttempt {
#[must_use]
pub fn new(index: usize, route: String, plan: Plan, error: Option<String>) -> Self {
Self {
index,
route,
plan,
error,
}
}
}
#[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)]
#[non_exhaustive]
pub struct ConversionReport {
workspace: TempDir,
pub plan: Plan,
pub artifacts: Vec<Artifact>,
pub warnings: Vec<Warning>,
pub costs: Vec<StepCost>,
pub attempts: Vec<RouteAttempt>,
pub ignored_params: Vec<String>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum CapabilityReason {
Planned {
cost: u64,
},
PolicyBlocked,
BackendUnavailable {
backends: Vec<String>,
},
NoRoute,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct TargetCapability {
pub format: String,
pub reason: CapabilityReason,
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct InputReport {
pub identification: Identification,
pub path: PathBuf,
pub decodable_as: Vec<String>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ProfileSource {
Observed,
NoOpinion,
Timeout,
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct ProfileReport {
pub identification: Identification,
pub profile: Option<ContentProfile>,
pub source: ProfileSource,
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct StepCost {
pub step: usize,
pub backend: String,
pub operation: String,
pub kind: ConversionKind,
pub cost: u32,
pub note: String,
}
impl StepCost {
#[must_use]
pub fn new(
step: usize,
backend: &str,
operation: &str,
kind: ConversionKind,
cost: u32,
note: Option<&str>,
) -> Self {
Self {
step,
backend: backend.to_owned(),
operation: operation.to_owned(),
kind,
cost,
note: note
.unwrap_or("no fidelity note declared by this adapter")
.to_owned(),
}
}
}
impl ConversionReport {
#[must_use]
pub fn directory(&self) -> &Path {
self.workspace.path()
}
pub fn write_all_to(&self, dir: &Path) -> Result<Vec<PathBuf>> {
std::fs::create_dir_all(dir)?;
let mut written = Vec::with_capacity(self.artifacts.len());
for name in self.suggested_names() {
let destination = unique_destination(dir, &name);
let artifact = &self.artifacts[written.len()];
let temporary = dir.join(format!(".convert-rs-{}.tmp", uuid_like(written.len())));
let result = (|| -> Result<()> {
std::fs::copy(&artifact.path, &temporary)?;
std::fs::rename(&temporary, &destination)?;
Ok(())
})();
if result.is_err() {
let _ = std::fs::remove_file(&temporary);
}
result?;
written.push(destination);
}
Ok(written)
}
#[must_use]
pub fn suggested_names(&self) -> Vec<String> {
self.artifacts
.iter()
.enumerate()
.map(|(index, artifact)| match &artifact.logical_name {
Some(name) => sanitize_suggested_name(name),
None => {
let extension = artifact
.format
.chars()
.filter(|c| c.is_ascii_lowercase() || c.is_ascii_digit())
.collect::<String>();
let extension = if extension.is_empty() {
"bin"
} else {
&extension
};
format!("converted-{index}.{extension}")
}
})
.collect()
}
}
fn unique_destination(dir: &Path, name: &str) -> PathBuf {
let candidate = dir.join(name);
if !candidate.exists() {
return candidate;
}
let (stem, extension) = name.rsplit_once('.').unwrap_or((name, ""));
(1u32..)
.map(|index| {
if extension.is_empty() {
dir.join(format!("{stem}-{index}"))
} else {
dir.join(format!("{stem}-{index}.{extension}"))
}
})
.find(|renamed| !renamed.exists())
.unwrap_or(candidate)
}
fn uuid_like(seed: usize) -> String {
use std::hash::{Hash, Hasher};
let mut hasher = std::collections::hash_map::DefaultHasher::new();
(std::process::id(), seed, std::time::SystemTime::now()).hash(&mut hasher);
format!("{:016x}", hasher.finish())
}
fn sanitize_suggested_name(name: &str) -> String {
let basename = name.rsplit(['/', '\\']).next().unwrap_or(name);
let cleaned: String = basename
.chars()
.take(128)
.map(|c| {
if c.is_control() || matches!(c, ':' | '<' | '>' | '"' | '|' | '?' | '*' | '\0') {
'_'
} else {
c
}
})
.collect();
let trimmed = cleaned.trim_matches(['.', ' ']);
if trimmed.is_empty() {
"file".to_owned()
} else {
trimmed.to_owned()
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct Identification {
pub format: String,
pub method: IdentificationMethod,
}
impl Identification {
#[must_use]
pub fn new(format: impl Into<String>, method: IdentificationMethod) -> Self {
Self {
format: format.into(),
method,
}
}
}
#[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 {
if !self.policy.allow_empty_inputs {
return Err(Error::Security("input is empty".into()));
}
return Ok(Identification {
format: "bin".into(),
method: IdentificationMethod::Unknown,
});
}
if let Some(id) = extensions_of(path)
.iter()
.find_map(|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 probe(&self, path: &Path) -> Result<InputReport> {
let identification = self.identify(path)?;
let mut decodable = BTreeSet::new();
for adapter in self.adapters.values() {
if !adapter.status().available {
continue;
}
for format in adapter.formats() {
if decodable.contains(&format.id) {
continue;
}
if adapter.accepts_input(path, &format.id, &self.limits) == Some(true) {
decodable.insert(format.id);
}
}
}
Ok(InputReport {
identification,
path: path.to_path_buf(),
decodable_as: decodable.into_iter().collect(),
})
}
pub async fn profile(&self, path: &Path) -> Result<ProfileReport> {
let identification = self.identify(path)?;
let (profile, timed_out) = self.inspect(path, &identification.format).await;
Ok(ProfileReport {
source: match (&profile, timed_out) {
(Some(_), _) => ProfileSource::Observed,
(None, true) => ProfileSource::Timeout,
(None, false) => ProfileSource::NoOpinion,
},
identification,
profile,
})
}
async fn inspect(&self, path: &Path, format: &str) -> (Option<ContentProfile>, bool) {
let mut timed_out = false;
for adapter in self.adapters.values() {
if !adapter.status().available {
continue;
}
if !adapter
.formats()
.into_iter()
.any(|declared| declared.id == format)
{
continue;
}
let job = adapter.inspect(path, format, &self.limits);
match tokio::time::timeout(self.limits.timeout, job).await {
Ok(Some(Ok(mut profile))) if profile.format == format => {
profile.deduplicate();
return (Some(profile), false);
}
Ok(_) => continue,
Err(_elapsed) => timed_out = true,
}
}
(None, timed_out)
}
pub fn capabilities(&self, source: &str, targets: &[String]) -> Result<Vec<TargetCapability>> {
let source = self
.graph
.resolve(source)
.ok_or_else(|| Error::Invalid(format!("unknown source format: {source}")))?
.id
.clone();
let available: Vec<String> = self
.adapters
.values()
.filter(|adapter| adapter.status().available)
.map(|adapter| adapter.name().to_owned())
.collect();
let unrestricted = Policy {
allow_bridges: true,
allow_lossy: true,
allow_reinterpret: true,
allow_packaging: true,
allow_external: true,
allow_external_packaging: true,
allow_decode_only: true,
reencode_same_format: true,
allow_creative: true,
..self.policy.clone()
};
let mut reports = Vec::with_capacity(targets.len());
for target in targets {
let target = self
.graph
.resolve(target)
.ok_or_else(|| Error::Invalid(format!("unknown target format: {target}")))?
.id
.clone();
reports.push(TargetCapability {
reason: self.classify(&source, &target, &available, &unrestricted),
format: target,
});
}
Ok(reports)
}
fn classify(
&self,
source: &str,
target: &str,
available: &[String],
unrestricted: &Policy,
) -> CapabilityReason {
if let Ok(plans) = self.graph.routes(source, target, &self.policy)
&& let Some(cheapest) = plans.iter().map(|plan| plan.cost).min()
{
return CapabilityReason::Planned { cost: cheapest };
}
let permissive_available = Policy {
backends: available.to_vec(),
..unrestricted.clone()
};
if matches!(
self.graph.routes(source, target, &permissive_available),
Ok(plans) if !plans.is_empty()
) {
return CapabilityReason::PolicyBlocked;
}
match self.graph.routes(source, target, unrestricted) {
Ok(plans)
if plans.iter().any(|plan| {
plan.steps
.iter()
.all(|step| available.iter().any(|backend| backend == &step.backend))
}) =>
{
CapabilityReason::PolicyBlocked
}
Ok(plans) => {
let mut missing: Vec<String> = plans
.iter()
.flat_map(|plan| plan.steps.iter())
.map(|step| step.backend.clone())
.filter(|backend| !available.contains(backend))
.collect();
missing.sort();
missing.dedup();
CapabilityReason::BackendUnavailable { backends: missing }
}
_ => CapabilityReason::NoRoute,
}
}
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> {
options.validate()?;
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 inspect = options.inspect_content || self.policy.inspect_content;
let profile = if inspect && options.from.is_none() && options.forced_plan.is_none() {
self.inspect(&paths[0], &source).await.0
} else {
None
};
let plans = match &options.forced_plan {
Some(plan) => vec![plan.clone()],
None => {
if source == target && options.reencode {
let reencode_policy = Policy {
reencode_same_format: true,
backends: options.backend.iter().cloned().collect(),
retain: normalized_retain(&options.preserve),
..self.policy.clone()
};
match self.graph.routes_with_profile(
&source,
&target,
&reencode_policy,
profile.as_ref(),
) {
Ok(plans) => plans,
Err(convert_rs_core::PlanError::NoRoute { .. }) => {
return Err(Error::Invalid(format!(
"no same-format re-encode route exists for {source}; \
the copy path would ignore the reencode request"
)));
}
Err(error) => return Err(error.into()),
}
} else {
let mut policy = self.policy.clone();
if let Some(backend) = &options.backend {
policy.backends = vec![backend.clone()];
}
if !options.preserve.is_empty() {
policy.retain = normalized_retain(&options.preserve);
}
let search =
self.graph
.routes_with_profile(&source, &target, &policy, profile.as_ref());
match (search, options.backend.as_ref()) {
(Ok(plans), _) => plans,
(Err(convert_rs_core::PlanError::NoRoute { .. }), Some(backend)) => {
return Err(Error::Invalid(format!(
"no route from {source} to {target} uses only backend {backend}"
)));
}
(Err(error), _) => return Err(error.into()),
}
}
}
};
let mut attempts: Vec<RouteAttempt> = Vec::new();
let mut failures = Vec::new();
let target_format = self.graph.format(&target);
for plan in plans {
let forced = options.forced_plan.as_ref().is_some();
let rejected = options
.check_forced_retention(&plan)
.and_then(|()| {
if forced {
match target_format {
Some(format) => options.check_forced_content(
&plan,
format,
profile.as_ref(),
&self.policy.require,
self.policy.require_content,
),
None => Ok(()),
}
} else {
Ok(())
}
})
.err();
if let Some(error) = rejected {
let index = attempts.len();
attempts.push(RouteAttempt::new(
index,
render_route(&plan),
plan.clone(),
Some(error.to_string()),
));
failures.push(format!("{}: {error}", attempts[index].route));
continue;
}
let index = attempts.len();
let rendered = render_route(&plan);
let attempt = self.execute(&plan, &source, &target, paths, options).await;
match attempt {
Ok(mut report) => {
let accepted = RouteAttempt::new(index, rendered, plan.clone(), None);
report.attempts = attempts;
report.attempts.push(accepted);
return Ok(report);
}
Err(error) => {
attempts.push(RouteAttempt::new(
index,
rendered,
plan.clone(),
Some(error.to_string()),
));
failures.push(format!("{}: {error}", attempts[index].route));
}
}
}
Err(Error::RoutesFailed(failures.join("; ")))
}
pub async fn convert_bytes(
&self,
input: &[u8],
from: &str,
to: &str,
options: &ConversionOptions,
) -> Result<Vec<u8>> {
let source_format = self
.graph
.resolve(from)
.ok_or_else(|| Error::Invalid(format!("unknown source format: {from}")))?
.id
.clone();
let workspace = TempDir::new()?;
let staged_path = workspace.path().join("input");
std::fs::write(&staged_path, input)?;
let options = ConversionOptions {
from: Some(source_format),
..options.clone()
};
let report = self
.convert(std::slice::from_ref(&staged_path), to, &options)
.await?;
let [artifact] = report.artifacts.as_slice() else {
return Err(Error::Conversion(format!(
"route produced {} artifacts; convert_bytes needs exactly one",
report.artifacts.len()
)));
};
Ok(std::fs::read(&artifact.path)?)
}
pub fn convert_blocking(
&self,
input: &[u8],
from: &str,
to: &str,
options: &ConversionOptions,
) -> Result<Vec<u8>> {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.map_err(|error| Error::Invalid(format!("cannot build a blocking runtime: {error}")))?;
runtime.block_on(self.convert_bytes(input, from, to, options))
}
async fn execute(
&self,
plan: &Plan,
source: &str,
target: &str,
paths: &[PathBuf],
options: &ConversionOptions,
) -> Result<ConversionReport> {
let pinned = &options.backend;
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();
let mut costs = Vec::new();
let mut spent_total = 0u64;
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::new(
artifacts.clone(),
step_dir.clone(),
step.from.clone(),
step.to.clone(),
step.operation.clone(),
self.limits.clone(),
)
.with_params(&options.params)
.with_spent_output_bytes(spent_total);
match adapter.convert(&request).await {
Ok(produced) => {
let (validated, produced_bytes) = validate_artifacts(
produced,
&step_dir,
step,
&self.limits,
&self.graph,
options,
&self.adapters,
)?;
artifacts = validated;
spent_total = spent_total.saturating_add(produced_bytes);
if self.limits.max_total_output_bytes > 0
&& spent_total > self.limits.max_total_output_bytes
{
return Err(Error::Limit(
"combined step outputs exceed the total byte budget".into(),
));
}
}
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 step.kind != ConversionKind::Lossless {
costs.push(StepCost::new(
index,
&step.backend,
&step.operation,
step.kind,
step.cost,
step.note.as_deref(),
));
}
}
if artifacts.iter().any(|artifact| artifact.format != *target) {
return Err(Error::Conversion(
"final artifacts do not match the target".into(),
));
}
if options.verify && plan.steps.is_empty() {
let identity = crate::Conversion::new(
source,
target,
"engine",
"identity",
crate::ConversionKind::Lossless,
0,
);
for artifact in &artifacts {
verify_artifact_bytes(
&artifact.path,
&identity,
&self.graph,
&self.adapters,
&self.limits,
)?;
}
}
let ignored_params = ignored_param_keys(plan, options, &self.adapters);
Ok(ConversionReport {
workspace,
plan: plan.clone(),
artifacts,
warnings,
costs,
attempts: Vec::new(),
ignored_params,
})
}
}
fn ignored_param_keys(
plan: &Plan,
options: &ConversionOptions,
adapters: &BTreeMap<String, Arc<dyn crate::Adapter>>,
) -> Vec<String> {
if options.params.is_empty() {
return Vec::new();
}
let mut supported: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
for step in &plan.steps {
if let Some(adapter) = adapters.get(&step.backend) {
supported.extend(
adapter
.param_keys(&step.operation)
.iter()
.map(|key| key.trim().to_ascii_lowercase()),
);
}
}
options
.params
.keys()
.filter(|key| !supported.contains(&key.trim().to_ascii_lowercase()))
.cloned()
.collect()
}
fn step_dir_name(index: usize) -> Result<String> {
Ok(format!("step-{index:04}"))
}
fn normalized_retain(values: &[String]) -> Vec<String> {
let mut normalized: Vec<String> = values
.iter()
.map(|value| value.trim().to_ascii_lowercase())
.filter(|value| !value.is_empty())
.collect();
normalized.sort();
normalized.dedup();
normalized
}
fn render_route(plan: &Plan) -> String {
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(" | ")
}
}
fn warning_for(index: usize, step: &crate::Conversion) -> Option<Warning> {
let generic = match step.kind {
ConversionKind::Lossless => return None,
ConversionKind::Lossy => format!(
"{} re-encoded through {}; expect quality or metadata loss",
step.to, step.operation
),
ConversionKind::Reencode => format!(
"{} re-encoded in place 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(),
};
let message = match &step.note {
Some(note) => format!("{generic}: {note}"),
None => generic,
};
Some(Warning {
step: index,
backend: step.backend.clone(),
operation: step.operation.clone(),
kind: step.kind,
message,
})
}
fn extensions_of(path: &Path) -> Vec<String> {
let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
return Vec::new();
};
let Some(dotted) = name.split_once('.').map(|(_, rest)| rest) else {
return Vec::new();
};
let mut candidates = Vec::new();
let mut rest = dotted;
while let Some(index) = rest.rfind('.') {
candidates.push(rest.to_ascii_lowercase());
rest = &rest[index + 1..];
}
if !rest.is_empty() {
candidates.push(rest.to_ascii_lowercase());
}
candidates
}
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::new(destination, format.to_owned()))
}
fn validate_artifacts(
produced: Vec<Artifact>,
step_dir: &Path,
step: &crate::Conversion,
limits: &Limits,
graph: &Graph,
options: &ConversionOptions,
adapters: &BTreeMap<String, Arc<dyn Adapter>>,
) -> Result<(Vec<Artifact>, u64)> {
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(),
));
}
if options.verify {
verify_artifact_bytes(&canonical, step, graph, adapters, limits)?;
}
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()));
}
let mut validated = Artifact::new(canonical, artifact.format);
validated.logical_name = artifact.logical_name;
artifacts.push(validated);
}
Ok((artifacts, total))
}
fn verify_artifact_bytes(
path: &Path,
step: &crate::Conversion,
graph: &Graph,
adapters: &BTreeMap<String, Arc<dyn Adapter>>,
limits: &Limits,
) -> Result<()> {
if step.to != "bin"
&& step.from != step.to
&& let Some(contradiction) = sniff_contradiction(path, step, graph)?
{
return Err(contradiction);
}
for adapter in adapters.values() {
if adapter.name() == step.backend || !adapter.status().available {
continue;
}
if adapter.accepts_input(path, &step.to, limits) == Some(false) {
return Err(Error::Conversion(format!(
"verification failed: {} cannot decode what {} wrote as {}",
adapter.name(),
step.backend,
step.to
)));
}
}
Ok(())
}
fn sniff_contradiction(
path: &Path,
step: &crate::Conversion,
graph: &Graph,
) -> Result<Option<Error>> {
let mut header = [0u8; 1024];
let mut file = std::fs::File::open(path)
.map_err(|_| Error::Security("artifact became unreadable during verification".into()))?;
let count = file.read(&mut header).map_err(|_| {
Error::Security(format!(
"artifact {} cannot be re-read for verification",
path.display()
))
})?;
if count == 0 {
return Ok(None);
}
let Some(name) = detect(&header[..count]) else {
return Ok(None);
};
let Some(resolved) = graph.resolve(name) else {
return Ok(None);
};
if resolved.id == step.to || step.to.ends_with(&format!(".{}", resolved.id)) {
return Ok(None);
}
Ok(Some(Error::Conversion(format!(
"verification failed: {} wrote a {} file while the step claims {}",
step.backend, resolved.id, step.to
))))
}
#[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();
let graph = Graph::new();
let defaults = ConversionOptions::default();
std::fs::write(dir.path().join("escape.png"), b"x").unwrap();
let escape = Artifact::new(dir.path().join("escape.png"), "png");
assert!(matches!(
validate_artifacts(
vec![escape],
&step_dir,
&step,
&limits,
&graph,
&defaults,
&BTreeMap::new()
),
Err(Error::Security(_))
));
let directory = Artifact::new(step_dir.clone(), "png");
assert!(matches!(
validate_artifacts(
vec![directory],
&step_dir,
&step,
&limits,
&graph,
&defaults,
&BTreeMap::new(),
),
Err(Error::Security(_))
));
let wrong = Artifact::new(step_dir.join("wrong.jpg"), "jpeg".to_owned());
std::fs::write(&wrong.path, b"x").unwrap();
assert!(matches!(
validate_artifacts(
vec![wrong],
&step_dir,
&step,
&limits,
&graph,
&defaults,
&BTreeMap::new()
),
Err(Error::Conversion(_))
));
std::fs::write(step_dir.join("real.png"), b"x").unwrap();
let good = Artifact::new(step_dir.join("real.png"), "png");
assert_eq!(
validate_artifacts(
vec![good],
&step_dir,
&step,
&limits,
&graph,
&defaults,
&BTreeMap::new()
)
.unwrap()
.0
.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()),
..ConversionOptions::default()
};
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 { .. })
));
}
}