convert_rs/engine.rs
1//! Adapter registry, route execution, and per-step output validation.
2//!
3//! Every step receives a private output directory, and every artifact an adapter
4//! returns is checked: regular file, inside its step directory, declared
5//! format matches the step target, and total bytes respect the budget. A step
6//! that fails validation abandons the route and the engine tries the next.
7//! The workspace is a file ownership boundary, not an execution sandbox.
8
9use std::collections::{BTreeMap, BTreeSet};
10use std::io::Read;
11use std::path::{Path, PathBuf};
12use std::sync::Arc;
13
14use tempfile::TempDir;
15
16use crate::{
17 Adapter, Artifact, BackendStatus, ContentKind, ContentProfile, ConversionKind, Error, Format,
18 Graph, Limits, Plan, Policy, Result, StepRequest,
19};
20
21use crate::builtin::{BuiltinAdapter, detect};
22
23#[cfg(feature = "archives")]
24use crate::archives::ArchivesAdapter;
25#[cfg(feature = "media")]
26use crate::media::MediaAdapter;
27
28/// Per-conversion identification and route-selection choices.
29///
30/// Defaults use file identification and normal planning without a backend filter
31/// or quality params. Resource budgets are configured separately through
32/// [`Converter::limits`]. All fields are public; construct with
33/// `ConversionOptions { field: value, ..ConversionOptions::default() }`.
34#[derive(Clone, Debug, Default)]
35pub struct ConversionOptions {
36 /// Override format identification for every input (a format ID or extension).
37 ///
38 /// Skips content identification, including its empty-file rejection. Staging
39 /// still requires regular files within the per-file input budget. This is a
40 /// caller assertion, not a content validation request.
41 pub from: Option<String>,
42 /// Require every executed step to use this backend.
43 ///
44 /// Normal planning first finds a bounded set of routes, then filters it; a
45 /// matching route outside that set is not searched for. Identity plans have
46 /// no steps and pass any backend filter. Forced plans are checked step by step.
47 pub backend: Option<String>,
48 /// Skip route search and attempt only this caller-supplied plan.
49 ///
50 /// Prefer a plan obtained from [`Converter::plan`]. Steps must have concrete
51 /// format IDs. Execution checks kind gates, the `external` flag against
52 /// [`Policy::allow_external`], backend filtering, format continuity, and
53 /// returned artifacts. It does not verify edge membership in the graph,
54 /// recompute cost, enforce search budgets or decode-only gates, or apply
55 /// [`Policy::allow_external_packaging`]. Metadata is trusted: forced plans
56 /// are not a safe boundary for untrusted callers.
57 pub forced_plan: Option<Plan>,
58 /// Quality knobs forwarded verbatim to every executed step.
59 ///
60 /// The reserved key `quality` carries a 0-100 integer string; the engine
61 /// validates that range and adapters map it onto their closest encoder
62 /// control (JPEG/WebP quality, ffmpeg `-q`, imageMagick `-quality`).
63 /// Unknown keys are ignored by adapters, so passing knobs for a backend
64 /// that is not selected is harmless. Params never select paths or tools:
65 /// values are opaque strings and are never interpolated into argv as
66 /// executable or filesystem locations.
67 pub params: BTreeMap<String, String>,
68 /// Re-sniff every step's artifacts by content magic before accepting them.
69 ///
70 /// When enabled, the engine reads the first bytes of each returned file and
71 /// compares the detected format with the step target. A contradiction fails
72 /// the route and the engine falls back to the next plan. Bytes with no known
73 /// signature are accepted, because absence of evidence is not evidence of
74 /// a mismatch. Disabled by default because detection only covers formats
75 /// with registered signatures.
76 pub verify: bool,
77 /// Request a genuine re-encode when source and target formats match.
78 ///
79 /// By default a same-format request stages a byte-for-byte copy with an
80 /// empty plan. When set, planning searches for nonempty routes that return
81 /// to the requested format (image recompression, codec change inside a
82 /// container) and the identity copy is not offered. If no re-encode route
83 /// exists with the registered adapters, conversion fails with an explanatory
84 /// [`Error::Invalid`] rather than silently copying.
85 pub reencode: bool,
86 /// Content properties every executed step must declare it preserves.
87 ///
88 /// Names are adapter vocabulary (`pixels`, `alpha`, `metadata`, `structure`,
89 /// ...), matched case-insensitively against [`crate::Conversion::retained`] during
90 /// planning and enforced again for forced plans at execution. An empty list
91 /// (the default) adds no requirement. The zero-step identity copy satisfies
92 /// any retention request because it preserves bytes.
93 pub preserve: Vec<String>,
94 /// Ask adapters to inspect this input's content before planning.
95 ///
96 /// When set (and no [`Self::from`] override is given), [`Converter::convert`]
97 /// profiles the first identified input through [`Converter::profile`] and
98 /// searches with [`Graph::routes_with_profile`](convert_rs_core::Graph::routes_with_profile),
99 /// so edges with [`crate::Conversion::requires`] content are gated on the
100 /// observed streams. With an override, format identification (and any
101 /// inspection) is the caller's job and no profile is taken. The converter's
102 /// [`Policy::inspect_content`] sets the same behavior for every request;
103 /// this field overrides it per call.
104 pub inspect_content: bool,
105}
106
107impl ConversionOptions {
108 /// Validate caller-supplied params, returning a descriptive error.
109 ///
110 /// # Errors
111 ///
112 /// Returns [`Error::Invalid`] when `quality` is present but not an integer
113 /// within 0-100, or when `reencode` is combined with a forced plan.
114 fn validate(&self) -> Result<()> {
115 if let Some(quality) = self.params.get("quality") {
116 let value: u8 = quality
117 .trim()
118 .parse()
119 .map_err(|_| Error::Invalid(format!("quality must be 0-100, got {quality}")))?;
120 if value > 100 {
121 return Err(Error::Invalid(format!(
122 "quality must be 0-100, got {value}"
123 )));
124 }
125 }
126 if self.reencode && self.forced_plan.is_some() {
127 return Err(Error::Invalid(
128 "reencode replaces route search and cannot combine with a forced plan".into(),
129 ));
130 }
131 if self.inspect_content && self.forced_plan.is_some() {
132 return Err(Error::Invalid(
133 "inspect_content drives route search and cannot combine with a forced plan".into(),
134 ));
135 }
136 Ok(())
137 }
138
139 /// Enforce requested retention claims on a caller-supplied forced plan.
140 ///
141 /// Search applies [`Policy::retain`] pruning, but forced plans bypass search,
142 /// so every nonempty step must declare it preserves at least the properties
143 /// named in [`Self::preserve`] (matched case-insensitively). Plans with no
144 /// steps are identity copies and always satisfy the request.
145 fn check_forced_retention(&self, plan: &Plan) -> Result<()> {
146 for step in &plan.steps {
147 for wanted in &self.preserve {
148 let wanted = wanted.trim().to_ascii_lowercase();
149 if wanted.is_empty() {
150 continue;
151 }
152 if !step.retained.iter().any(|held| held == &wanted) {
153 return Err(Error::Security(format!(
154 "step {} via {} does not declare it preserves {wanted}",
155 step.operation, step.backend
156 )));
157 }
158 }
159 }
160 Ok(())
161 }
162
163 /// Enforce the caller's content policy on a caller-supplied forced plan.
164 ///
165 /// Mirrors the planner's [`Policy::require`] gate: each required kind must
166 /// appear in the observed profile (when one exists), in the final step's
167 /// [`crate::Conversion::produces`] claim, or in the target format's declared
168 /// payloads when [`Policy::require_content`] is off.
169 fn check_forced_content(
170 &self,
171 plan: &Plan,
172 target: &Format,
173 profile: Option<&ContentProfile>,
174 require: &[ContentKind],
175 require_content: bool,
176 ) -> Result<()> {
177 for wanted in require {
178 let delivered = profile
179 .filter(|found| found.format == target.id)
180 .is_some_and(|found| found.declares(wanted))
181 || plan
182 .produced()
183 .iter()
184 .any(|produced| wanted.matches(produced))
185 || (!require_content
186 && target
187 .payloads
188 .iter()
189 .any(|declared| wanted.matches(declared)));
190 if !delivered {
191 return Err(Error::Security(format!(
192 "forced plan does not deliver required content {wanted} in {target}",
193 target = target.id
194 )));
195 }
196 }
197 Ok(())
198 }
199}
200
201/// One attempted route during a single [`Converter::convert`] call.
202///
203/// The report's `attempts` list records every route try in order, including the
204/// successful one, so callers can explain to users why a preferred route was
205/// skipped instead of silently falling back.
206#[derive(Clone, Debug)]
207#[non_exhaustive]
208pub struct RouteAttempt {
209 /// Zero-based position of this attempt in the fallback order.
210 pub index: usize,
211 /// Human-readable rendering of the route, e.g. `txt→json via builtin`.
212 pub route: String,
213 /// Adapter-declared plan that was executed (or attempted).
214 pub plan: Plan,
215 /// Rendered failure for rejected routes; `None` for the accepted route.
216 pub error: Option<String>,
217}
218
219impl RouteAttempt {
220 /// Construct an attempt record.
221 #[must_use]
222 pub fn new(index: usize, route: String, plan: Plan, error: Option<String>) -> Self {
223 Self {
224 index,
225 route,
226 plan,
227 error,
228 }
229 }
230}
231
232/// An informational warning derived from an executed step's declared kind.
233///
234/// The engine emits one warning for each non-lossless step of the successful
235/// route, including packaging and extraction. It does not measure actual loss
236/// or collect every adapter diagnostic. Failed attempts' warnings are discarded.
237#[derive(Clone, Debug, PartialEq, Eq)]
238pub struct Warning {
239 /// Zero-based index into the successful report's plan, not an artifact index.
240 pub step: usize,
241 /// Adapter that executed the step.
242 pub backend: String,
243 /// Adapter operation ID.
244 pub operation: String,
245 /// Adapter-declared semantic classification of the step.
246 pub kind: ConversionKind,
247 /// Explanation suitable for logs or a user interface.
248 pub message: String,
249}
250
251/// A resolved conversion: the accepted route, its warnings, and the artifacts.
252///
253/// Artifacts live in a private directory owned by this report. Dropping the
254/// report deletes them, so copy final files out before the report is dropped.
255/// Moving or cloning artifact paths does not transfer workspace ownership.
256/// Use [`Self::write_all_to`] to persist artifacts, or [`Self::directory`] to
257/// access the workspace directly.
258#[derive(Debug)]
259#[non_exhaustive]
260pub struct ConversionReport {
261 workspace: TempDir,
262 /// Route selected and executed by the converter, or the supplied forced plan.
263 pub plan: Plan,
264 /// Final artifacts, in adapter output order, or input order for identity copies.
265 ///
266 /// Format labels were checked against the target, not independently decoded,
267 /// unless [`ConversionOptions::verify`] was enabled for this conversion.
268 pub artifacts: Vec<Artifact>,
269 /// One warning per non-lossless step in this report's plan.
270 ///
271 /// An empty list is not a guarantee of complete quality or metadata preservation.
272 pub warnings: Vec<Warning>,
273 /// Cost-ordered notes for every non-lossless step that actually ran,
274 /// carrying the adapter-declared fidelity note when the step supplied one.
275 ///
276 /// This is the quality/cost view a UI should render next to warnings:
277 /// what each lossy step discards, straight from the adapter, rather than
278 /// the engine's generic sentence.
279 pub costs: Vec<StepCost>,
280 /// Structured log of every route attempted while producing this report.
281 ///
282 /// Every attempt is included, including earlier fallbacks that failed and
283 /// the accepted route (the final entry). Empty only when conversion itself
284 /// failed before planning, because a failed [`Converter::convert`] returns
285 /// [`Error::RoutesFailed`] only as a rendered string.
286 pub attempts: Vec<RouteAttempt>,
287 /// Requested [`ConversionOptions::params`] keys no executed step declared support for.
288 ///
289 /// Adapters ignore unknown keys by contract, so a typo would otherwise
290 /// silently change nothing. After each successful route the engine unions
291 /// [`crate::Adapter::param_keys`] over its steps and reports the difference.
292 /// A nonempty list is informational: the conversion succeeded, but those
293 /// knobs had no effect.
294 pub ignored_params: Vec<String>,
295}
296
297/// How reachable a requested target format is from a probed source format.
298#[derive(Clone, Debug, PartialEq, Eq)]
299pub enum CapabilityReason {
300 /// A route exists under the current policy and adapter availability.
301 Planned {
302 /// Cost of the cheapest found route.
303 cost: u64,
304 },
305 /// A route exists but the policy gate (lossy, bridges, external, ...) blocks it.
306 PolicyBlocked,
307 /// The only routes need backends that are not registered or report unavailable.
308 BackendUnavailable {
309 /// Backend names that exist but are unusable on this host.
310 backends: Vec<String>,
311 },
312 /// No graph route exists with the registered adapters under any gate setting.
313 NoRoute,
314}
315
316/// One target format's reachability from a source format.
317#[derive(Clone, Debug, PartialEq, Eq)]
318pub struct TargetCapability {
319 /// Resolved target format ID.
320 pub format: String,
321 /// Why or whether conversion to this format is currently possible.
322 pub reason: CapabilityReason,
323}
324
325/// Identification plus per-format deep-decode results for one input file.
326#[derive(Clone, Debug)]
327#[non_exhaustive]
328pub struct InputReport {
329 /// Identification found for the file.
330 pub identification: Identification,
331 /// Path checked.
332 pub path: PathBuf,
333 /// Formats whose registered adapters confirmed the file decodes.
334 ///
335 /// Populated by [`Converter::probe`] only for formats adapters answered
336 /// about; absence means no adapter gave an opinion, which is not rejection.
337 pub decodable_as: Vec<String>,
338}
339
340/// Where a [`Converter::profile`] profile came from.
341#[derive(Clone, Copy, Debug, PartialEq, Eq)]
342pub enum ProfileSource {
343 /// An available adapter described the file's streams.
344 Observed,
345 /// No claiming adapter answered; planning falls back to declared payloads.
346 NoOpinion,
347 /// An adapter's inspection exceeded [`Limits::timeout`] and nobody answered.
348 Timeout,
349}
350
351/// Identification plus an optional content profile for one input file.
352///
353/// Returned by [`Converter::profile`]. `profile` is `Some` only when an
354/// adapter actually described the file: an observed profile with no streams is
355/// real evidence (the file carries nothing describable), while `None` means no
356/// adapter answered and the graph's declared [`Format::payloads`] stand in.
357/// [`Self::identification`] is the [`Converter::identify`] result the profile
358/// was taken for.
359#[derive(Clone, Debug)]
360#[non_exhaustive]
361pub struct ProfileReport {
362 /// Format identification for the file.
363 pub identification: Identification,
364 /// Adapter-observed profile, or `None` when nothing answered.
365 pub profile: Option<ContentProfile>,
366 /// Which kind of outcome produced [`Self::profile`].
367 pub source: ProfileSource,
368}
369
370/// A note explaining what an executed step costs or discards.
371#[derive(Clone, Debug)]
372#[non_exhaustive]
373pub struct StepCost {
374 /// Zero-based step index in the executed plan.
375 pub step: usize,
376 /// Adapter that ran the step.
377 pub backend: String,
378 /// Adapter operation ID.
379 pub operation: String,
380 /// Adapter-declared semantic classification.
381 pub kind: ConversionKind,
382 /// The step's declared cost contribution.
383 pub cost: u32,
384 /// Adapter-supplied fidelity sentence, falling back to an engine default.
385 pub note: String,
386}
387
388impl StepCost {
389 /// Build a cost note for one executed step.
390 #[must_use]
391 pub fn new(
392 step: usize,
393 backend: &str,
394 operation: &str,
395 kind: ConversionKind,
396 cost: u32,
397 note: Option<&str>,
398 ) -> Self {
399 Self {
400 step,
401 backend: backend.to_owned(),
402 operation: operation.to_owned(),
403 kind,
404 cost,
405 note: note
406 .unwrap_or("no fidelity note declared by this adapter")
407 .to_owned(),
408 }
409 }
410}
411
412impl ConversionReport {
413 /// The workspace directory holding this report's artifacts.
414 ///
415 /// It also contains staged inputs and intermediate outputs. The returned
416 /// path is valid only while this report's temporary directory exists; this
417 /// method does not persist or transfer ownership of that directory.
418 #[must_use]
419 pub fn directory(&self) -> &Path {
420 self.workspace.path()
421 }
422
423 /// Copy the final artifacts into `dir`, creating it when missing.
424 ///
425 /// Files are named from [`Self::suggested_names`] and never overwritten: an
426 /// existing destination gains a `-<n>` suffix, matching the collision naming
427 /// inside the batch itself. Each file is written through a temporary path
428 /// and renamed, so a failed copy leaves no partial output. Returns the
429 /// written paths in artifact order. The report keeps ownership of the
430 /// workspace; dropping the report does not remove these copies. Calling
431 /// this method twice persists a second, rename-deduplicated set.
432 ///
433 /// # Errors
434 ///
435 /// Returns [`Error::Io`] for filesystem failures.
436 pub fn write_all_to(&self, dir: &Path) -> Result<Vec<PathBuf>> {
437 std::fs::create_dir_all(dir)?;
438 let mut written = Vec::with_capacity(self.artifacts.len());
439 for name in self.suggested_names() {
440 let destination = unique_destination(dir, &name);
441 let artifact = &self.artifacts[written.len()];
442 let temporary = dir.join(format!(".convert-rs-{}.tmp", uuid_like(written.len())));
443 let result = (|| -> Result<()> {
444 std::fs::copy(&artifact.path, &temporary)?;
445 std::fs::rename(&temporary, &destination)?;
446 Ok(())
447 })();
448 if result.is_err() {
449 let _ = std::fs::remove_file(&temporary);
450 }
451 result?;
452 written.push(destination);
453 }
454 Ok(written)
455 }
456
457 /// Stable artifact file names, `converted-<index>.<target>`.
458 ///
459 /// The report does not retain input paths, so batch output directories get
460 /// positional names; rename after writing if the original basename matters.
461 /// Artifacts that carry an [`Artifact::logical_name`] instead suggest a
462 /// sanitized form of it, preserving the member names extraction produced.
463 #[must_use]
464 pub fn suggested_names(&self) -> Vec<String> {
465 self.artifacts
466 .iter()
467 .enumerate()
468 .map(|(index, artifact)| match &artifact.logical_name {
469 Some(name) => sanitize_suggested_name(name),
470 None => {
471 let extension = artifact
472 .format
473 .chars()
474 .filter(|c| c.is_ascii_lowercase() || c.is_ascii_digit())
475 .collect::<String>();
476 let extension = if extension.is_empty() {
477 "bin"
478 } else {
479 &extension
480 };
481 format!("converted-{index}.{extension}")
482 }
483 })
484 .collect()
485 }
486}
487
488/// Choose a destination path that exists nowhere yet, appending `-<n>` on a clash.
489fn unique_destination(dir: &Path, name: &str) -> PathBuf {
490 let candidate = dir.join(name);
491 if !candidate.exists() {
492 return candidate;
493 }
494 let (stem, extension) = name.rsplit_once('.').unwrap_or((name, ""));
495 (1u32..)
496 .map(|index| {
497 if extension.is_empty() {
498 dir.join(format!("{stem}-{index}"))
499 } else {
500 dir.join(format!("{stem}-{index}.{extension}"))
501 }
502 })
503 .find(|renamed| !renamed.exists())
504 .unwrap_or(candidate)
505}
506
507/// A short, deterministic pseudo-unique token for temp file names.
508fn uuid_like(seed: usize) -> String {
509 use std::hash::{Hash, Hasher};
510 let mut hasher = std::collections::hash_map::DefaultHasher::new();
511 (std::process::id(), seed, std::time::SystemTime::now()).hash(&mut hasher);
512 format!("{:016x}", hasher.finish())
513}
514
515/// Reduce a logical name to one safe file-name component for persistence.
516fn sanitize_suggested_name(name: &str) -> String {
517 let basename = name.rsplit(['/', '\\']).next().unwrap_or(name);
518 let cleaned: String = basename
519 .chars()
520 .take(128)
521 .map(|c| {
522 if c.is_control() || matches!(c, ':' | '<' | '>' | '"' | '|' | '?' | '*' | '\0') {
523 '_'
524 } else {
525 c
526 }
527 })
528 .collect();
529 let trimmed = cleaned.trim_matches(['.', ' ']);
530 if trimmed.is_empty() {
531 "file".to_owned()
532 } else {
533 trimmed.to_owned()
534 }
535}
536
537/// A resolved input format with the evidence used to determine it.
538///
539/// Identification is a heuristic label, not proof that a decoder accepts the file.
540/// [`Converter::identify`] never returns [`IdentificationMethod::Override`]; that
541/// variant represents a source override applied internally during conversion.
542#[derive(Clone, Debug, PartialEq, Eq)]
543#[non_exhaustive]
544pub struct Identification {
545 /// Resolved format ID.
546 pub format: String,
547 /// Evidence used to identify the input.
548 pub method: IdentificationMethod,
549}
550
551impl Identification {
552 /// Construct an identification record.
553 #[must_use]
554 pub fn new(format: impl Into<String>, method: IdentificationMethod) -> Self {
555 Self {
556 format: format.into(),
557 method,
558 }
559 }
560}
561
562/// Evidence source used by [`Converter::identify`].
563#[derive(Clone, Copy, Debug, PartialEq, Eq)]
564pub enum IdentificationMethod {
565 /// Caller supplied the format override.
566 Override,
567 /// A single filename suffix matched a registered ID or extension alias.
568 Extension,
569 /// Up to the first 1,024 bytes matched a known signature for a registered format.
570 Magic,
571 /// No known signature or extension matched; the input is treated as binary.
572 Unknown,
573}
574
575/// Adapter registry, routing configuration, and file conversion entry point.
576///
577/// [`Self::new`] and [`Default`] register compiled-in pure-Rust adapters with
578/// default [`Policy`] and [`Limits`]. Native tools require explicit discovery
579/// (with the `external` feature) and policy opt-in. Execution requires a Tokio
580/// runtime; registration, lookup, and planning do not.
581///
582/// Plans describe format-level operations, not codec selection. A route can
583/// fail because of input contents or adapter limitations despite valid metadata.
584pub struct Converter {
585 graph: Graph,
586 adapters: BTreeMap<String, Arc<dyn Adapter>>,
587 order: Vec<String>,
588 policy: Policy,
589 limits: Limits,
590}
591
592impl std::fmt::Debug for Converter {
593 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
594 formatter
595 .debug_struct("Converter")
596 .field("adapters", &self.order)
597 .field("formats", &self.graph.formats().count())
598 .finish()
599 }
600}
601
602impl Default for Converter {
603 fn default() -> Self {
604 Self::new()
605 }
606}
607
608impl Converter {
609 /// Construct a converter with every compiled-in pure-Rust adapter.
610 ///
611 /// Always includes byte/text operations. Optional `data`, `media`, and
612 /// `archives` features add their operations. Does not probe native tools.
613 #[must_use]
614 pub fn new() -> Self {
615 let mut converter = Self {
616 graph: Graph::new(),
617 adapters: BTreeMap::new(),
618 order: Vec::new(),
619 policy: Policy::default(),
620 limits: Limits::default(),
621 };
622 let _ = converter.register(Arc::new(BuiltinAdapter));
623 #[cfg(feature = "media")]
624 {
625 let _ = converter.register(Arc::new(MediaAdapter));
626 }
627 #[cfg(feature = "archives")]
628 {
629 let _ = converter.register(Arc::new(ArchivesAdapter));
630 }
631 converter
632 }
633
634 /// Construct a converter and register native-tool adapters whose probes succeed.
635 ///
636 /// Available only with the `external` feature. Starts from [`Self::new`];
637 /// unavailable tools are omitted rather than returned as errors. Probes do
638 /// not establish that every advertised format or codec works for a file.
639 /// Native tools are invoked per operation, not kept running by discovery.
640 ///
641 /// The default policy still disallows external routes. Set
642 /// [`Policy::allow_external`] to use them. The library does not sandbox native
643 /// tools; use operating-system isolation for hostile inputs.
644 #[cfg(feature = "external")]
645 pub async fn discover() -> Self {
646 let mut converter = Self::new();
647 let adapters = crate::external::discover().await;
648 for adapter in adapters {
649 if adapter.status().available {
650 let _ = converter.register(adapter);
651 }
652 }
653 converter
654 }
655
656 /// Add an adapter. Registration by name is idempotent; re-registering the
657 /// same name replaces the previous adapter and rebuilds the graph.
658 ///
659 /// Formats from all adapters are registered before edges, allowing references
660 /// to other adapters' formats. No availability probe is required. Metadata
661 /// must remain stable across calls. Failed registration leaves the current
662 /// registry and graph unchanged.
663 ///
664 /// # Errors
665 ///
666 /// Returns [`Error::Invalid`] for an empty name, a name longer than 64 bytes,
667 /// no format declarations, more than 8,192 formats, or more than 1,000,000
668 /// conversions from the incoming adapter. Returns [`Error::Plan`] if the
669 /// rebuilt graph rejects format or edge metadata. Backend names in edges
670 /// are not checked against the adapter's registration name.
671 pub fn register(&mut self, adapter: Arc<dyn Adapter>) -> Result<()> {
672 let name = adapter.name().to_owned();
673 if name.is_empty() || name.len() > 64 {
674 return Err(Error::Invalid("invalid adapter name".into()));
675 }
676 let formats = adapter.formats();
677 let conversions = adapter.conversions();
678 if formats.is_empty() || formats.len() > 8192 || conversions.len() > 1_000_000 {
679 return Err(Error::Invalid("adapter registration rejected".into()));
680 }
681 // Rebuild from every registered adapter so a replacement never leaves
682 // edges whose backend no longer exists, and so a rejected registration
683 // cannot leave a converter with an emptied registry.
684 let mut previous = self.adapters.clone();
685 let mut ordered = self.order.clone();
686 ordered.retain(|existing| existing != &name);
687 ordered.push(name.clone());
688 previous.insert(name.clone(), Arc::clone(&adapter));
689 let mut graph = Graph::new();
690 for key in &ordered {
691 for format in previous[key].formats() {
692 graph.add_format(format).map_err(Error::Plan)?;
693 }
694 }
695 for key in &ordered {
696 for conversion in previous[key].conversions() {
697 graph.add_conversion(conversion).map_err(Error::Plan)?;
698 }
699 }
700 self.graph = graph;
701 self.adapters = previous;
702 self.order = ordered;
703 Ok(())
704 }
705
706 #[must_use]
707 /// Replace resource limits using builder-style ownership.
708 ///
709 /// Does not validate the values. See [`Limits`] for adapter-dependent checks
710 /// and the distinction between budgets and hard resource isolation.
711 pub fn limits(mut self, limits: Limits) -> Self {
712 self.limits = limits;
713 self
714 }
715
716 #[must_use]
717 /// Replace the routing and execution policy using builder-style ownership.
718 ///
719 /// The policy is not validated here; invalid search settings fail at planning.
720 pub fn with_policy(mut self, policy: Policy) -> Self {
721 self.policy = policy;
722 self
723 }
724
725 /// Replace the routing policy at runtime.
726 ///
727 /// Affects later conversions, including kind checks on forced plans. It does
728 /// not alter previously returned plans or validate the new policy immediately.
729 pub fn set_policy(&mut self, policy: Policy) {
730 self.policy = policy;
731 }
732
733 #[must_use]
734 /// Return the immutable route graph used by this converter.
735 ///
736 /// Use [`Self::register`] to contribute formats and conversions.
737 pub fn graph(&self) -> &Graph {
738 &self.graph
739 }
740
741 #[must_use]
742 /// Return the current routing policy.
743 pub fn policy(&self) -> &Policy {
744 &self.policy
745 }
746
747 #[must_use]
748 /// Clone all registered formats in ascending format-ID order.
749 ///
750 /// Includes custom registrations, not just compiled-in or discovered adapters.
751 /// Presence does not imply a permitted route or a working encoder.
752 pub fn formats(&self) -> Vec<Format> {
753 self.graph.formats().cloned().collect()
754 }
755
756 /// Return registered adapters' status reports in ascending backend-name order.
757 ///
758 /// Calls [`Adapter::status`], which may return cached probe results. Tools
759 /// omitted during discovery are not listed; status does not re-plan routes.
760 #[must_use]
761 pub fn backends(&self) -> Vec<BackendStatus> {
762 self.adapters
763 .values()
764 .map(|adapter| adapter.status())
765 .collect()
766 }
767
768 #[must_use]
769 /// Resolve a format ID or extension alias without inspecting a file.
770 ///
771 /// Trims whitespace, folds ASCII case, and accepts leading dots. IDs take
772 /// precedence over aliases; ambiguous aliases choose the smallest format ID.
773 /// Returns `None` for unknown values. Does not parse paths or MIME types.
774 pub fn resolve(&self, value: &str) -> Option<&Format> {
775 self.graph.resolve(value)
776 }
777
778 /// Identify one nonempty regular input file by extension, then signature.
779 ///
780 /// Multi-dot names strip every alphanumeric suffix (`archive.tar.gz` looks
781 /// up `tar.gz`, then `gz`). A recognized suffix wins without opening or
782 /// validating the contents. Otherwise, up to 1,024 bytes are read for
783 /// magic detection. Unknown content becomes `bin`; built-in conversion
784 /// from `bin` to text requires reinterpretation opt-in, but identity does not.
785 ///
786 /// Zero-byte files are rejected unless [`Policy::allow_empty_inputs`] is
787 /// enabled; with the policy open, empty inputs identify as `bin`.
788 ///
789 /// # Errors
790 ///
791 /// Returns [`Error::Invalid`] when metadata cannot be inspected or a needed
792 /// header read fails. Returns [`Error::Security`] for nonregular paths
793 /// (including symlinks) and for empty files under the default policy.
794 /// Input byte budgets are checked later during staging, not by this method.
795 pub fn identify(&self, path: &Path) -> Result<Identification> {
796 let metadata = std::fs::symlink_metadata(path)
797 .map_err(|_| Error::Invalid(format!("cannot inspect {}", path.display())))?;
798 if !metadata.file_type().is_file() {
799 return Err(Error::Security("input is not a regular file".into()));
800 }
801 if metadata.len() == 0 {
802 if !self.policy.allow_empty_inputs {
803 return Err(Error::Security("input is empty".into()));
804 }
805 return Ok(Identification {
806 format: "bin".into(),
807 method: IdentificationMethod::Unknown,
808 });
809 }
810 if let Some(id) = extensions_of(path)
811 .iter()
812 .find_map(|value| self.graph.resolve(value))
813 {
814 return Ok(Identification {
815 format: id.id.clone(),
816 method: IdentificationMethod::Extension,
817 });
818 }
819 let mut header = [0u8; 1024];
820 let mut file =
821 std::fs::File::open(path).map_err(|_| Error::Invalid("input is unreadable".into()))?;
822 let count = file
823 .read(&mut header)
824 .map_err(|_| Error::Invalid("input is unreadable".into()))?;
825 if let Some(id) = detect(&header[..count]).and_then(|name| self.graph.resolve(name)) {
826 return Ok(Identification {
827 format: id.id.clone(),
828 method: IdentificationMethod::Magic,
829 });
830 }
831 Ok(Identification {
832 format: "bin".into(),
833 method: IdentificationMethod::Unknown,
834 })
835 }
836
837 /// Identify a file, then ask available decoders what it really holds.
838 ///
839 /// Runs [`Self::identify`] first, then calls [`Adapter::accepts_input`] on
840 /// every format declared by an available adapter. Formats an adapter confirms
841 /// are listed in [`InputReport::decodable_as`]; formats nobody answered
842 /// about are absent, which is not a rejection. The full byte budget applies
843 /// per answer, so probing a large adversarial file costs at most one decode
844 /// per declared format.
845 ///
846 /// # Errors
847 ///
848 /// As [`Self::identify`].
849 pub fn probe(&self, path: &Path) -> Result<InputReport> {
850 let identification = self.identify(path)?;
851 let mut decodable = BTreeSet::new();
852 for adapter in self.adapters.values() {
853 if !adapter.status().available {
854 continue;
855 }
856 for format in adapter.formats() {
857 if decodable.contains(&format.id) {
858 continue;
859 }
860 if adapter.accepts_input(path, &format.id, &self.limits) == Some(true) {
861 decodable.insert(format.id);
862 }
863 }
864 }
865 Ok(InputReport {
866 identification,
867 path: path.to_path_buf(),
868 decodable_as: decodable.into_iter().collect(),
869 })
870 }
871
872 /// Identify a file, then ask one available adapter to describe its streams.
873 ///
874 /// [`Policy::inspect_content`] is a directive for engines like this one:
875 /// when it is set, [`Self::convert`] profiles the first identified input
876 /// before planning and routes through
877 /// [`Graph::routes_with_profile`](convert_rs_core::Graph::routes_with_profile).
878 /// This method performs that profiling step and describes the outcome.
879 ///
880 /// Runs [`Self::identify`], then asks available adapters that declare the
881 /// identified format, in registration order, for [`Adapter::inspect`]. The
882 /// first adapter answering `Ok(Some(profile))` whose `profile.format`
883 /// matches the identification wins. Adapters that decline (`Ok(None)`),
884 /// fail (`Err`), or claim a different format express no opinion; the engine
885 /// asks the next one. An inspection exceeding [`Limits::timeout`] is
886 /// abandoned and recorded.
887 ///
888 /// When nobody answered, [`ProfileReport::profile`] is `None`: planning
889 /// falls back to declared [`Format::payloads`] unless
890 /// [`Policy::require_content`] demands observed evidence.
891 ///
892 /// # Errors
893 ///
894 /// As [`Self::identify`]. Adapter failures and timeouts are reported
895 /// through [`ProfileReport::source`], never as an error.
896 pub async fn profile(&self, path: &Path) -> Result<ProfileReport> {
897 let identification = self.identify(path)?;
898 let (profile, timed_out) = self.inspect(path, &identification.format).await;
899 Ok(ProfileReport {
900 source: match (&profile, timed_out) {
901 (Some(_), _) => ProfileSource::Observed,
902 (None, true) => ProfileSource::Timeout,
903 (None, false) => ProfileSource::NoOpinion,
904 },
905 identification,
906 profile,
907 })
908 }
909
910 /// Ask declaring available adapters for a profile of `path` as `format`.
911 ///
912 /// Shared by [`Self::profile`] and [`Self::convert`]. Returns the first
913 /// well-formed observed profile plus whether any inspection timed out.
914 async fn inspect(&self, path: &Path, format: &str) -> (Option<ContentProfile>, bool) {
915 let mut timed_out = false;
916 for adapter in self.adapters.values() {
917 if !adapter.status().available {
918 continue;
919 }
920 if !adapter
921 .formats()
922 .into_iter()
923 .any(|declared| declared.id == format)
924 {
925 continue;
926 }
927 let job = adapter.inspect(path, format, &self.limits);
928 match tokio::time::timeout(self.limits.timeout, job).await {
929 Ok(Some(Ok(mut profile))) if profile.format == format => {
930 profile.deduplicate();
931 return (Some(profile), false);
932 }
933 Ok(_) => continue,
934 Err(_elapsed) => timed_out = true,
935 }
936 }
937 (None, timed_out)
938 }
939
940 /// Classify how reachable each target format is from a source format.
941 ///
942 /// A target is [`CapabilityReason::Planned`] when the current policy and
943 /// registered adapters route to it. Otherwise the method re-searches with
944 /// every gate open, once restricted to available backends and once without:
945 /// a route that only the open search finds is [`CapabilityReason::PolicyBlocked`],
946 /// one that needs a registered-but-unavailable or missing backend is
947 /// [`CapabilityReason::BackendUnavailable`], and a format nothing routes to
948 /// is [`CapabilityReason::NoRoute`]. Planning only; no files are read.
949 ///
950 /// # Errors
951 ///
952 /// Returns [`Error::Invalid`] for an unknown source or target format name.
953 pub fn capabilities(&self, source: &str, targets: &[String]) -> Result<Vec<TargetCapability>> {
954 let source = self
955 .graph
956 .resolve(source)
957 .ok_or_else(|| Error::Invalid(format!("unknown source format: {source}")))?
958 .id
959 .clone();
960 let available: Vec<String> = self
961 .adapters
962 .values()
963 .filter(|adapter| adapter.status().available)
964 .map(|adapter| adapter.name().to_owned())
965 .collect();
966 let unrestricted = Policy {
967 allow_bridges: true,
968 allow_lossy: true,
969 allow_reinterpret: true,
970 allow_packaging: true,
971 allow_external: true,
972 allow_external_packaging: true,
973 allow_decode_only: true,
974 reencode_same_format: true,
975 allow_creative: true,
976 ..self.policy.clone()
977 };
978 let mut reports = Vec::with_capacity(targets.len());
979 for target in targets {
980 let target = self
981 .graph
982 .resolve(target)
983 .ok_or_else(|| Error::Invalid(format!("unknown target format: {target}")))?
984 .id
985 .clone();
986 reports.push(TargetCapability {
987 reason: self.classify(&source, &target, &available, &unrestricted),
988 format: target,
989 });
990 }
991 Ok(reports)
992 }
993
994 fn classify(
995 &self,
996 source: &str,
997 target: &str,
998 available: &[String],
999 unrestricted: &Policy,
1000 ) -> CapabilityReason {
1001 if let Ok(plans) = self.graph.routes(source, target, &self.policy)
1002 && let Some(cheapest) = plans.iter().map(|plan| plan.cost).min()
1003 {
1004 return CapabilityReason::Planned { cost: cheapest };
1005 }
1006 let permissive_available = Policy {
1007 backends: available.to_vec(),
1008 ..unrestricted.clone()
1009 };
1010 if matches!(
1011 self.graph.routes(source, target, &permissive_available),
1012 Ok(plans) if !plans.is_empty()
1013 ) {
1014 return CapabilityReason::PolicyBlocked;
1015 }
1016 match self.graph.routes(source, target, unrestricted) {
1017 Ok(plans)
1018 if plans.iter().any(|plan| {
1019 plan.steps
1020 .iter()
1021 .all(|step| available.iter().any(|backend| backend == &step.backend))
1022 }) =>
1023 {
1024 CapabilityReason::PolicyBlocked
1025 }
1026 Ok(plans) => {
1027 let mut missing: Vec<String> = plans
1028 .iter()
1029 .flat_map(|plan| plan.steps.iter())
1030 .map(|step| step.backend.clone())
1031 .filter(|backend| !available.contains(backend))
1032 .collect();
1033 missing.sort();
1034 missing.dedup();
1035 CapabilityReason::BackendUnavailable { backends: missing }
1036 }
1037 _ => CapabilityReason::NoRoute,
1038 }
1039 }
1040
1041 /// Enumerate policy-filtered routes between two formats.
1042 ///
1043 /// Uses the supplied policy, not necessarily [`Self::policy`]. Does not inspect
1044 /// files or filter by backend availability. See [`Graph::routes`] for ordering,
1045 /// bounded search, and partial-result behavior.
1046 ///
1047 /// # Examples
1048 ///
1049 /// ```rust
1050 /// use convert_rs::{ConversionKind, Converter, Policy};
1051 /// let converter = Converter::new();
1052 /// let plans = converter.plan("txt", "bin", converter.policy())?;
1053 /// assert_eq!(plans[0].steps[0].kind, ConversionKind::Lossless);
1054 /// assert!(converter.plan("bin", "txt", converter.policy()).is_err());
1055 /// let policy = Policy { allow_reinterpret: true, ..Policy::default() };
1056 /// let plans = converter.plan("bin", "txt", &policy)?;
1057 /// assert_eq!(plans[0].steps[0].operation, "decode-text");
1058 /// # Ok::<(), convert_rs::Error>(())
1059 /// ```
1060 ///
1061 /// # Errors
1062 ///
1063 /// Returns [`Error::Plan`] for unknown formats, invalid search settings, no
1064 /// route, or an exhausted search budget before any route is found.
1065 pub fn plan(&self, from: &str, to: &str, policy: &Policy) -> Result<Vec<Plan>> {
1066 Ok(self.graph.routes(from, to, policy)?)
1067 }
1068
1069 /// Convert files through the first successful route in the planned set.
1070 ///
1071 /// All inputs must resolve to one format. Routes are attempted in cost
1072 /// order, and every attempt re-stages fresh copies of inputs that adapters
1073 /// must not mutate. Search is bounded, so not every graph route is attempted.
1074 /// Backend filtering occurs after this bounded search. A forced plan bypasses
1075 /// search and is attempted once; see [`ConversionOptions::forced_plan`].
1076 ///
1077 /// With normal planning, same-format requests produce staged copies with an
1078 /// empty plan and no warnings. They do not validate content, re-encode, or
1079 /// choose codecs. File extensions and overrides are declarations, not decoder validation.
1080 /// Successful outputs remain temporary until copied out of the report.
1081 ///
1082 /// # Execute a reviewed plan
1083 ///
1084 /// ```rust
1085 /// use convert_rs::{ConversionKind, ConversionOptions, Converter, Policy};
1086 /// # #[tokio::main(flavor = "current_thread")]
1087 /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
1088 /// let policy = Policy { allow_reinterpret: true, ..Policy::default() };
1089 /// let converter = Converter::new().with_policy(policy);
1090 /// let plans = converter.plan("bin", "txt", converter.policy())?;
1091 /// let chosen = plans.into_iter().next().ok_or("no plan")?;
1092 /// assert_eq!(chosen.steps[0].kind, ConversionKind::Reinterpret);
1093 /// let options = ConversionOptions {
1094 /// from: Some("bin".into()),
1095 /// backend: Some("builtin".into()),
1096 /// forced_plan: Some(chosen),
1097 /// ..ConversionOptions::default()
1098 /// };
1099 /// let inputs = tempfile::tempdir()?;
1100 /// let source = inputs.path().join("payload");
1101 /// std::fs::write(&source, "valid UTF-8")?;
1102 /// let report = converter.convert(&[source], "txt", &options).await?;
1103 /// assert_eq!(std::fs::read_to_string(&report.artifacts[0].path)?, "valid UTF-8");
1104 /// assert_eq!(report.warnings[0].kind, ConversionKind::Reinterpret);
1105 /// # Ok(())
1106 /// # }
1107 /// ```
1108 ///
1109 /// # Errors
1110 ///
1111 /// Returns [`Error::Invalid`] for empty input lists, unknown overrides or
1112 /// targets, mixed identified formats, or no route remaining after backend
1113 /// filtering; [`Error::Limit`] for too many inputs; and identification or
1114 /// planning errors before execution. Staging, adapter, execution-policy,
1115 /// and output-validation failures are accumulated into [`Error::RoutesFailed`]
1116 /// if all attempted routes fail. A successful fallback omits earlier errors.
1117 pub async fn convert(
1118 &self,
1119 paths: &[PathBuf],
1120 to: &str,
1121 options: &ConversionOptions,
1122 ) -> Result<ConversionReport> {
1123 options.validate()?;
1124 if paths.is_empty() {
1125 return Err(Error::Invalid("no input files given".into()));
1126 }
1127 if paths.len() > self.limits.max_artifacts {
1128 return Err(Error::Limit("input file count".into()));
1129 }
1130 let target = self
1131 .graph
1132 .resolve(to)
1133 .ok_or_else(|| Error::Invalid(format!("unknown target format: {to}")))?
1134 .id
1135 .clone();
1136
1137 let identification = match &options.from {
1138 Some(value) => {
1139 let format = self
1140 .graph
1141 .resolve(value)
1142 .ok_or_else(|| Error::Invalid(format!("unknown source format: {value}")))?
1143 .id
1144 .clone();
1145 Identification {
1146 format,
1147 method: IdentificationMethod::Override,
1148 }
1149 }
1150 None => self.identify(&paths[0])?,
1151 };
1152 if options.from.is_none() {
1153 for path in &paths[1..] {
1154 let other = self.identify(path)?;
1155 if other.format != identification.format {
1156 return Err(Error::Invalid(format!(
1157 "inputs have different formats: {} and {}",
1158 identification.format, other.format
1159 )));
1160 }
1161 }
1162 }
1163 let source = identification.format;
1164
1165 let inspect = options.inspect_content || self.policy.inspect_content;
1166 let profile = if inspect && options.from.is_none() && options.forced_plan.is_none() {
1167 self.inspect(&paths[0], &source).await.0
1168 } else {
1169 None
1170 };
1171
1172 let plans = match &options.forced_plan {
1173 Some(plan) => vec![plan.clone()],
1174 None => {
1175 if source == target && options.reencode {
1176 let reencode_policy = Policy {
1177 reencode_same_format: true,
1178 backends: options.backend.iter().cloned().collect(),
1179 retain: normalized_retain(&options.preserve),
1180 ..self.policy.clone()
1181 };
1182 match self.graph.routes_with_profile(
1183 &source,
1184 &target,
1185 &reencode_policy,
1186 profile.as_ref(),
1187 ) {
1188 Ok(plans) => plans,
1189 Err(convert_rs_core::PlanError::NoRoute { .. }) => {
1190 return Err(Error::Invalid(format!(
1191 "no same-format re-encode route exists for {source}; \
1192 the copy path would ignore the reencode request"
1193 )));
1194 }
1195 Err(error) => return Err(error.into()),
1196 }
1197 } else {
1198 let mut policy = self.policy.clone();
1199 if let Some(backend) = &options.backend {
1200 policy.backends = vec![backend.clone()];
1201 }
1202 if !options.preserve.is_empty() {
1203 policy.retain = normalized_retain(&options.preserve);
1204 }
1205 let search =
1206 self.graph
1207 .routes_with_profile(&source, &target, &policy, profile.as_ref());
1208 match (search, options.backend.as_ref()) {
1209 (Ok(plans), _) => plans,
1210 (Err(convert_rs_core::PlanError::NoRoute { .. }), Some(backend)) => {
1211 return Err(Error::Invalid(format!(
1212 "no route from {source} to {target} uses only backend {backend}"
1213 )));
1214 }
1215 (Err(error), _) => return Err(error.into()),
1216 }
1217 }
1218 }
1219 };
1220
1221 let mut attempts: Vec<RouteAttempt> = Vec::new();
1222 let mut failures = Vec::new();
1223 let target_format = self.graph.format(&target);
1224 for plan in plans {
1225 let forced = options.forced_plan.as_ref().is_some();
1226 let rejected = options
1227 .check_forced_retention(&plan)
1228 .and_then(|()| {
1229 if forced {
1230 match target_format {
1231 Some(format) => options.check_forced_content(
1232 &plan,
1233 format,
1234 profile.as_ref(),
1235 &self.policy.require,
1236 self.policy.require_content,
1237 ),
1238 None => Ok(()),
1239 }
1240 } else {
1241 Ok(())
1242 }
1243 })
1244 .err();
1245 if let Some(error) = rejected {
1246 let index = attempts.len();
1247 attempts.push(RouteAttempt::new(
1248 index,
1249 render_route(&plan),
1250 plan.clone(),
1251 Some(error.to_string()),
1252 ));
1253 failures.push(format!("{}: {error}", attempts[index].route));
1254 continue;
1255 }
1256 let index = attempts.len();
1257 let rendered = render_route(&plan);
1258 let attempt = self.execute(&plan, &source, &target, paths, options).await;
1259 match attempt {
1260 Ok(mut report) => {
1261 let accepted = RouteAttempt::new(index, rendered, plan.clone(), None);
1262 report.attempts = attempts;
1263 report.attempts.push(accepted);
1264 return Ok(report);
1265 }
1266 Err(error) => {
1267 attempts.push(RouteAttempt::new(
1268 index,
1269 rendered,
1270 plan.clone(),
1271 Some(error.to_string()),
1272 ));
1273 failures.push(format!("{}: {error}", attempts[index].route));
1274 }
1275 }
1276 }
1277 Err(Error::RoutesFailed(failures.join("; ")))
1278 }
1279
1280 /// Convert one in-memory buffer, returning its converted bytes.
1281 ///
1282 /// Writes the input to a staged temporary file, runs
1283 /// [`Self::convert`] with these options, verifies that exactly one
1284 /// artifact was produced, and reads it back. The report is dropped
1285 /// afterwards, so nothing to clean up. Requires a Tokio runtime; use
1286 /// [`Self::convert_blocking`] from synchronous code.
1287 ///
1288 /// # Errors
1289 ///
1290 /// Identifies the buffer by content (extension-based lookup cannot apply);
1291 /// returns [`Error::Conversion`] when a multi-output route (for example
1292 /// archive extraction) is selected, plus any error from [`Self::convert`].
1293 pub async fn convert_bytes(
1294 &self,
1295 input: &[u8],
1296 from: &str,
1297 to: &str,
1298 options: &ConversionOptions,
1299 ) -> Result<Vec<u8>> {
1300 let source_format = self
1301 .graph
1302 .resolve(from)
1303 .ok_or_else(|| Error::Invalid(format!("unknown source format: {from}")))?
1304 .id
1305 .clone();
1306 let workspace = TempDir::new()?;
1307 let staged_path = workspace.path().join("input");
1308 std::fs::write(&staged_path, input)?;
1309 let options = ConversionOptions {
1310 from: Some(source_format),
1311 ..options.clone()
1312 };
1313 let report = self
1314 .convert(std::slice::from_ref(&staged_path), to, &options)
1315 .await?;
1316 let [artifact] = report.artifacts.as_slice() else {
1317 return Err(Error::Conversion(format!(
1318 "route produced {} artifacts; convert_bytes needs exactly one",
1319 report.artifacts.len()
1320 )));
1321 };
1322 Ok(std::fs::read(&artifact.path)?)
1323 }
1324
1325 /// Synchronous [`Self::convert_bytes`] for callers without a Tokio runtime.
1326 ///
1327 /// Builds a single-threaded runtime internally and blocks the current
1328 /// thread; calling it from an existing async context deadlocks.
1329 ///
1330 /// # Errors
1331 ///
1332 /// As [`Self::convert`], plus [`Error::Invalid`] if the runtime cannot be
1333 /// constructed (for example nested inside another Tokio runtime).
1334 pub fn convert_blocking(
1335 &self,
1336 input: &[u8],
1337 from: &str,
1338 to: &str,
1339 options: &ConversionOptions,
1340 ) -> Result<Vec<u8>> {
1341 let runtime = tokio::runtime::Builder::new_current_thread()
1342 .enable_all()
1343 .build()
1344 .map_err(|error| Error::Invalid(format!("cannot build a blocking runtime: {error}")))?;
1345 runtime.block_on(self.convert_bytes(input, from, to, options))
1346 }
1347
1348 async fn execute(
1349 &self,
1350 plan: &Plan,
1351 source: &str,
1352 target: &str,
1353 paths: &[PathBuf],
1354 options: &ConversionOptions,
1355 ) -> Result<ConversionReport> {
1356 let pinned = &options.backend;
1357 let workspace = TempDir::new()?;
1358 let mut artifacts = Vec::with_capacity(paths.len());
1359 for (index, path) in paths.iter().enumerate() {
1360 artifacts.push(stage_input(
1361 path,
1362 workspace.path(),
1363 index,
1364 source,
1365 &self.limits,
1366 )?);
1367 }
1368
1369 let mut warnings = Vec::new();
1370 let mut costs = Vec::new();
1371 let mut spent_total = 0u64;
1372 for (index, step) in plan.steps.iter().enumerate() {
1373 if !self.policy.allows(step.kind) {
1374 return Err(Error::Security(format!(
1375 "{:?} steps are disabled",
1376 step.kind
1377 )));
1378 }
1379 if step.external && !self.policy.allow_external {
1380 return Err(Error::Security(format!(
1381 "{} uses a native external tool; enable Policy::allow_external",
1382 step.backend
1383 )));
1384 }
1385 if pinned
1386 .as_ref()
1387 .is_some_and(|backend| &step.backend != backend)
1388 {
1389 return Err(Error::Invalid("plan uses a disallowed backend".into()));
1390 }
1391 if artifacts
1392 .iter()
1393 .any(|artifact| artifact.format != step.from)
1394 {
1395 return Err(Error::Conversion(format!(
1396 "step {index} expected {} inputs",
1397 step.from
1398 )));
1399 }
1400 let adapter = self.adapters.get(&step.backend).ok_or_else(|| {
1401 Error::Conversion(format!("backend {} is not registered", step.backend))
1402 })?;
1403 let step_dir = workspace.path().join(step_dir_name(index)?);
1404 tokio::fs::create_dir_all(&step_dir).await?;
1405 let request = StepRequest::new(
1406 artifacts.clone(),
1407 step_dir.clone(),
1408 step.from.clone(),
1409 step.to.clone(),
1410 step.operation.clone(),
1411 self.limits.clone(),
1412 )
1413 .with_params(&options.params)
1414 .with_spent_output_bytes(spent_total);
1415 match adapter.convert(&request).await {
1416 Ok(produced) => {
1417 let (validated, produced_bytes) = validate_artifacts(
1418 produced,
1419 &step_dir,
1420 step,
1421 &self.limits,
1422 &self.graph,
1423 options,
1424 &self.adapters,
1425 )?;
1426 artifacts = validated;
1427 spent_total = spent_total.saturating_add(produced_bytes);
1428 if self.limits.max_total_output_bytes > 0
1429 && spent_total > self.limits.max_total_output_bytes
1430 {
1431 return Err(Error::Limit(
1432 "combined step outputs exceed the total byte budget".into(),
1433 ));
1434 }
1435 }
1436 Err(error) => {
1437 let _ = tokio::fs::remove_dir_all(&step_dir).await;
1438 return Err(error);
1439 }
1440 }
1441 if let Some(warning) = warning_for(index, step) {
1442 warnings.push(warning);
1443 }
1444 if step.kind != ConversionKind::Lossless {
1445 costs.push(StepCost::new(
1446 index,
1447 &step.backend,
1448 &step.operation,
1449 step.kind,
1450 step.cost,
1451 step.note.as_deref(),
1452 ));
1453 }
1454 }
1455 if artifacts.iter().any(|artifact| artifact.format != *target) {
1456 return Err(Error::Conversion(
1457 "final artifacts do not match the target".into(),
1458 ));
1459 }
1460 if options.verify && plan.steps.is_empty() {
1461 let identity = crate::Conversion::new(
1462 source,
1463 target,
1464 "engine",
1465 "identity",
1466 crate::ConversionKind::Lossless,
1467 0,
1468 );
1469 for artifact in &artifacts {
1470 verify_artifact_bytes(
1471 &artifact.path,
1472 &identity,
1473 &self.graph,
1474 &self.adapters,
1475 &self.limits,
1476 )?;
1477 }
1478 }
1479 let ignored_params = ignored_param_keys(plan, options, &self.adapters);
1480 Ok(ConversionReport {
1481 workspace,
1482 plan: plan.clone(),
1483 artifacts,
1484 warnings,
1485 costs,
1486 attempts: Vec::new(),
1487 ignored_params,
1488 })
1489 }
1490}
1491
1492/// Requested param keys that no executed step's adapter declared support for.
1493fn ignored_param_keys(
1494 plan: &Plan,
1495 options: &ConversionOptions,
1496 adapters: &BTreeMap<String, Arc<dyn crate::Adapter>>,
1497) -> Vec<String> {
1498 if options.params.is_empty() {
1499 return Vec::new();
1500 }
1501 let mut supported: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
1502 for step in &plan.steps {
1503 if let Some(adapter) = adapters.get(&step.backend) {
1504 supported.extend(
1505 adapter
1506 .param_keys(&step.operation)
1507 .iter()
1508 .map(|key| key.trim().to_ascii_lowercase()),
1509 );
1510 }
1511 }
1512 options
1513 .params
1514 .keys()
1515 .filter(|key| !supported.contains(&key.trim().to_ascii_lowercase()))
1516 .cloned()
1517 .collect()
1518}
1519
1520fn step_dir_name(index: usize) -> Result<String> {
1521 Ok(format!("step-{index:04}"))
1522}
1523
1524/// Lowercase and trim requested retention property names, dropping blanks.
1525fn normalized_retain(values: &[String]) -> Vec<String> {
1526 let mut normalized: Vec<String> = values
1527 .iter()
1528 .map(|value| value.trim().to_ascii_lowercase())
1529 .filter(|value| !value.is_empty())
1530 .collect();
1531 normalized.sort();
1532 normalized.dedup();
1533 normalized
1534}
1535
1536/// Render a plan's route as a single line, e.g. `identity` or `a→b via x | b→c via y`.
1537fn render_route(plan: &Plan) -> String {
1538 if plan.steps.is_empty() {
1539 "identity".to_owned()
1540 } else {
1541 plan.steps
1542 .iter()
1543 .map(|step| format!("{}→{} via {}", step.from, step.to, step.backend))
1544 .collect::<Vec<_>>()
1545 .join(" | ")
1546 }
1547}
1548
1549fn warning_for(index: usize, step: &crate::Conversion) -> Option<Warning> {
1550 let generic = match step.kind {
1551 ConversionKind::Lossless => return None,
1552 ConversionKind::Lossy => format!(
1553 "{} re-encoded through {}; expect quality or metadata loss",
1554 step.to, step.operation
1555 ),
1556 ConversionKind::Reencode => format!(
1557 "{} re-encoded in place through {}; expect quality or metadata loss",
1558 step.to, step.operation
1559 ),
1560 ConversionKind::Bridge => format!(
1561 "{} bridged through {}; the result expresses {} differently",
1562 step.from, step.operation, step.to
1563 ),
1564 ConversionKind::Reinterpret => format!(
1565 "bytes were reinterpreted as {} by {}",
1566 step.to, step.backend
1567 ),
1568 ConversionKind::Package => "files were packaged; contents were not converted".into(),
1569 ConversionKind::Extract => "archive members were extracted as separate files".into(),
1570 };
1571 let message = match &step.note {
1572 Some(note) => format!("{generic}: {note}"),
1573 None => generic,
1574 };
1575 Some(Warning {
1576 step: index,
1577 backend: step.backend.clone(),
1578 operation: step.operation.clone(),
1579 kind: step.kind,
1580 message,
1581 })
1582}
1583
1584/// Candidate suffix lookups for a file name, longest first.
1585///
1586/// `archive.tar.gz` yields `["tar.gz", "gz"]`; `note.txt` yields `["txt"]`.
1587/// Each candidate is matched only when a registered extension equals it, so
1588/// unknown suffixes fall through to signature detection.
1589fn extensions_of(path: &Path) -> Vec<String> {
1590 let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
1591 return Vec::new();
1592 };
1593 let Some(dotted) = name.split_once('.').map(|(_, rest)| rest) else {
1594 return Vec::new();
1595 };
1596 let mut candidates = Vec::new();
1597 let mut rest = dotted;
1598 while let Some(index) = rest.rfind('.') {
1599 candidates.push(rest.to_ascii_lowercase());
1600 rest = &rest[index + 1..];
1601 }
1602 if !rest.is_empty() {
1603 candidates.push(rest.to_ascii_lowercase());
1604 }
1605 candidates
1606}
1607
1608fn stage_input(
1609 path: &Path,
1610 dir: &Path,
1611 index: usize,
1612 format: &str,
1613 limits: &Limits,
1614) -> Result<Artifact> {
1615 let metadata = std::fs::symlink_metadata(path)?;
1616 if !metadata.file_type().is_file() {
1617 return Err(Error::Security("input is not a regular file".into()));
1618 }
1619 if metadata.len() > limits.max_input_bytes {
1620 return Err(Error::Limit("input bytes exceed budget".into()));
1621 }
1622 let destination = dir.join(format!("input-{index}"));
1623 std::fs::copy(path, &destination)?;
1624 let staged = std::fs::symlink_metadata(&destination)?;
1625 if !staged.file_type().is_file() || staged.len() != metadata.len() {
1626 return Err(Error::Security("staged input changed during copy".into()));
1627 }
1628 Ok(Artifact::new(destination, format.to_owned()))
1629}
1630
1631/// Ensure an adapter produced only bounded regular files inside its own step
1632/// directory and that no intermediate directory contains path-traversal names.
1633///
1634/// Returns the validated artifacts and their total byte count so the caller can
1635/// track the cumulative [`Limits::max_total_output_bytes`] budget.
1636fn validate_artifacts(
1637 produced: Vec<Artifact>,
1638 step_dir: &Path,
1639 step: &crate::Conversion,
1640 limits: &Limits,
1641 graph: &Graph,
1642 options: &ConversionOptions,
1643 adapters: &BTreeMap<String, Arc<dyn Adapter>>,
1644) -> Result<(Vec<Artifact>, u64)> {
1645 if produced.len() > limits.max_artifacts {
1646 return Err(Error::Limit("adapter produced too many artifacts".into()));
1647 }
1648 let root = step_dir
1649 .canonicalize()
1650 .map_err(|_| Error::Security("step directory disappeared".into()))?;
1651 let mut artifacts = Vec::with_capacity(produced.len());
1652 let mut total = 0u64;
1653 for artifact in produced {
1654 if artifact.format != step.to {
1655 return Err(Error::Conversion(format!(
1656 "{} returned a {} artifact for a {} step",
1657 step.backend, artifact.format, step.to
1658 )));
1659 }
1660 let metadata = std::fs::symlink_metadata(&artifact.path)
1661 .map_err(|_| Error::Security("adapter artifact does not exist".into()))?;
1662 if !metadata.file_type().is_file() {
1663 return Err(Error::Security(
1664 "adapter returned a non-regular file".into(),
1665 ));
1666 }
1667 let canonical = artifact.path.canonicalize().map_err(|_| {
1668 Error::Security("adapter returned a path that cannot be resolved".into())
1669 })?;
1670 if !canonical.starts_with(&root) {
1671 return Err(Error::Security(
1672 "adapter wrote outside its step directory".into(),
1673 ));
1674 }
1675 if options.verify {
1676 verify_artifact_bytes(&canonical, step, graph, adapters, limits)?;
1677 }
1678 total = total
1679 .checked_add(metadata.len())
1680 .ok_or_else(|| Error::Limit("artifact byte overflow".into()))?;
1681 if total > limits.max_output_bytes {
1682 return Err(Error::Limit("artifact bytes exceed budget".into()));
1683 }
1684 let mut validated = Artifact::new(canonical, artifact.format);
1685 validated.logical_name = artifact.logical_name;
1686 artifacts.push(validated);
1687 }
1688 Ok((artifacts, total))
1689}
1690
1691/// Re-sniff an artifact's first bytes and ask available decoders to confirm them.
1692///
1693/// Detection covers registered magic signatures; when no signature matches the
1694/// content, verification defers to the adapters. A signature that resolves to
1695/// a different registered format is a contradiction and fails the route. After
1696/// the signature check passes, available adapters that can judge the declared
1697/// format through [`crate::Adapter::accepts_input`] get a say: `Some(false)`
1698/// rejects the artifact, and `None` (the default) expresses no opinion.
1699fn verify_artifact_bytes(
1700 path: &Path,
1701 step: &crate::Conversion,
1702 graph: &Graph,
1703 adapters: &BTreeMap<String, Arc<dyn Adapter>>,
1704 limits: &Limits,
1705) -> Result<()> {
1706 // bin holds arbitrary bytes and identity relabels are caller assertions;
1707 // a signature hit on either target is expected, not a contradiction.
1708 if step.to != "bin"
1709 && step.from != step.to
1710 && let Some(contradiction) = sniff_contradiction(path, step, graph)?
1711 {
1712 return Err(contradiction);
1713 }
1714 for adapter in adapters.values() {
1715 if adapter.name() == step.backend || !adapter.status().available {
1716 continue;
1717 }
1718 if adapter.accepts_input(path, &step.to, limits) == Some(false) {
1719 return Err(Error::Conversion(format!(
1720 "verification failed: {} cannot decode what {} wrote as {}",
1721 adapter.name(),
1722 step.backend,
1723 step.to
1724 )));
1725 }
1726 }
1727 Ok(())
1728}
1729
1730/// Return the error describing a signature contradiction, or `None` when the
1731/// bytes agree with (or say nothing about) the declared target format.
1732fn sniff_contradiction(
1733 path: &Path,
1734 step: &crate::Conversion,
1735 graph: &Graph,
1736) -> Result<Option<Error>> {
1737 let mut header = [0u8; 1024];
1738 let mut file = std::fs::File::open(path)
1739 .map_err(|_| Error::Security("artifact became unreadable during verification".into()))?;
1740 let count = file.read(&mut header).map_err(|_| {
1741 Error::Security(format!(
1742 "artifact {} cannot be re-read for verification",
1743 path.display()
1744 ))
1745 })?;
1746 if count == 0 {
1747 return Ok(None);
1748 }
1749 let Some(name) = detect(&header[..count]) else {
1750 return Ok(None);
1751 };
1752 let Some(resolved) = graph.resolve(name) else {
1753 return Ok(None);
1754 };
1755 // A compound container is allowed to sniff as its inner format: a valid
1756 // `tar.gz` file begins with the gzip signature, so `tar.gz` accepts a `gz`
1757 // detection. Anything else that contradicts the declared format fails.
1758 if resolved.id == step.to || step.to.ends_with(&format!(".{}", resolved.id)) {
1759 return Ok(None);
1760 }
1761 Ok(Some(Error::Conversion(format!(
1762 "verification failed: {} wrote a {} file while the step claims {}",
1763 step.backend, resolved.id, step.to
1764 ))))
1765}
1766
1767#[cfg(test)]
1768#[allow(clippy::unwrap_used, clippy::expect_used)]
1769mod tests {
1770 use super::*;
1771
1772 fn graph_backend_converter() -> Converter {
1773 Converter::new()
1774 }
1775
1776 #[test]
1777 fn registration_is_idempotent_by_name() {
1778 let converter = graph_backend_converter();
1779 assert_eq!(
1780 converter
1781 .order
1782 .iter()
1783 .filter(|name| name.as_str() == "builtin")
1784 .count(),
1785 1
1786 );
1787 }
1788
1789 #[test]
1790 #[cfg(feature = "media")]
1791 fn extension_detection_wins_and_magic_is_fallback() {
1792 let converter = graph_backend_converter();
1793 let dir = TempDir::new().unwrap();
1794 std::fs::write(dir.path().join("note.txt"), b"plain text").unwrap();
1795 assert_eq!(
1796 converter
1797 .identify(&dir.path().join("note.txt"))
1798 .unwrap()
1799 .method,
1800 IdentificationMethod::Extension
1801 );
1802 std::fs::write(dir.path().join("payload.dat"), b"\x89PNG\r\n\x1a\nxx").unwrap();
1803 let found = converter.identify(&dir.path().join("payload.dat")).unwrap();
1804 assert_eq!(found.format, "png");
1805 assert_eq!(found.method, IdentificationMethod::Magic);
1806 std::fs::write(dir.path().join("random"), [1, 2, 3, 250, 7]).unwrap();
1807 let found = converter.identify(&dir.path().join("random")).unwrap();
1808 assert_eq!(found.format, "bin");
1809 assert_eq!(found.method, IdentificationMethod::Unknown);
1810 }
1811
1812 #[test]
1813 fn identify_rejects_nonregular_and_empty() {
1814 let converter = graph_backend_converter();
1815 let dir = TempDir::new().unwrap();
1816 std::fs::create_dir(dir.path().join("adir")).unwrap();
1817 assert!(matches!(
1818 converter.identify(&dir.path().join("adir")),
1819 Err(Error::Security(_))
1820 ));
1821 std::fs::write(dir.path().join("empty.txt"), b"").unwrap();
1822 assert!(matches!(
1823 converter.identify(&dir.path().join("empty.txt")),
1824 Err(Error::Security(_))
1825 ));
1826 }
1827
1828 #[tokio::test]
1829 async fn unknown_files_require_reinterpretation_opt_in() {
1830 let converter = graph_backend_converter();
1831 let dir = TempDir::new().unwrap();
1832 let path = dir.path().join("mystery");
1833 std::fs::write(&path, [7u8; 40]).unwrap();
1834 let default = converter
1835 .convert(
1836 std::slice::from_ref(&path),
1837 "txt",
1838 &ConversionOptions::default(),
1839 )
1840 .await;
1841 assert!(matches!(default, Err(Error::Plan(_))), "{default:?}");
1842 let policy = Policy {
1843 allow_reinterpret: true,
1844 ..Policy::default()
1845 };
1846 let report = Converter::default()
1847 .with_policy(policy)
1848 .convert(&[path], "txt", &ConversionOptions::default())
1849 .await
1850 .unwrap();
1851 assert_eq!(report.plan.steps.len(), 1);
1852 assert!(
1853 report
1854 .warnings
1855 .iter()
1856 .any(|warning| warning.kind == ConversionKind::Reinterpret)
1857 );
1858 }
1859
1860 #[tokio::test]
1861 async fn same_format_requests_stage_a_copy() {
1862 let converter = graph_backend_converter();
1863 let dir = TempDir::new().unwrap();
1864 let path = dir.path().join("data.txt");
1865 std::fs::write(&path, b"unchanged").unwrap();
1866 let report = converter
1867 .convert(&[path], "txt", &ConversionOptions::default())
1868 .await
1869 .unwrap();
1870 assert!(report.plan.steps.is_empty());
1871 assert_eq!(
1872 std::fs::read_to_string(&report.artifacts[0].path).unwrap(),
1873 "unchanged"
1874 );
1875 }
1876
1877 #[tokio::test]
1878 async fn mixed_format_inputs_are_rejected() {
1879 let converter = graph_backend_converter();
1880 let dir = TempDir::new().unwrap();
1881 std::fs::write(dir.path().join("a.txt"), b"a").unwrap();
1882 std::fs::write(dir.path().join("b.gz"), b"\x1f\x8brest").unwrap();
1883 let error = converter
1884 .convert(
1885 &[dir.path().join("a.txt"), dir.path().join("b.gz")],
1886 "tar",
1887 &ConversionOptions::default(),
1888 )
1889 .await
1890 .err();
1891 assert!(matches!(error, Some(Error::Invalid(_))));
1892 }
1893
1894 #[test]
1895 fn validating_artifacts_rejects_escapes_and_mismatch() {
1896 let dir = TempDir::new().unwrap();
1897 let step_dir = dir.path().join("step");
1898 std::fs::create_dir(&step_dir).unwrap();
1899 let step = crate::Conversion::new(
1900 "a",
1901 "png",
1902 "backend",
1903 "convert",
1904 ConversionKind::Lossless,
1905 1,
1906 );
1907 let limits = Limits::default();
1908
1909 let graph = Graph::new();
1910 let defaults = ConversionOptions::default();
1911 std::fs::write(dir.path().join("escape.png"), b"x").unwrap();
1912 let escape = Artifact::new(dir.path().join("escape.png"), "png");
1913 assert!(matches!(
1914 validate_artifacts(
1915 vec![escape],
1916 &step_dir,
1917 &step,
1918 &limits,
1919 &graph,
1920 &defaults,
1921 &BTreeMap::new()
1922 ),
1923 Err(Error::Security(_))
1924 ));
1925
1926 let directory = Artifact::new(step_dir.clone(), "png");
1927 assert!(matches!(
1928 validate_artifacts(
1929 vec![directory],
1930 &step_dir,
1931 &step,
1932 &limits,
1933 &graph,
1934 &defaults,
1935 &BTreeMap::new(),
1936 ),
1937 Err(Error::Security(_))
1938 ));
1939
1940 let wrong = Artifact::new(step_dir.join("wrong.jpg"), "jpeg".to_owned());
1941 std::fs::write(&wrong.path, b"x").unwrap();
1942 assert!(matches!(
1943 validate_artifacts(
1944 vec![wrong],
1945 &step_dir,
1946 &step,
1947 &limits,
1948 &graph,
1949 &defaults,
1950 &BTreeMap::new()
1951 ),
1952 Err(Error::Conversion(_))
1953 ));
1954
1955 std::fs::write(step_dir.join("real.png"), b"x").unwrap();
1956 let good = Artifact::new(step_dir.join("real.png"), "png");
1957 assert_eq!(
1958 validate_artifacts(
1959 vec![good],
1960 &step_dir,
1961 &step,
1962 &limits,
1963 &graph,
1964 &defaults,
1965 &BTreeMap::new()
1966 )
1967 .unwrap()
1968 .0
1969 .len(),
1970 1
1971 );
1972 }
1973
1974 #[test]
1975 fn stage_input_rejects_nonregular_and_oversize() {
1976 let limits = Limits {
1977 max_input_bytes: 4,
1978 ..Limits::default()
1979 };
1980 let dir = TempDir::new().unwrap();
1981 let path = dir.path().join("in");
1982 std::fs::write(&path, b"payload").unwrap();
1983 assert!(matches!(
1984 stage_input(&path, dir.path(), 0, "bin", &limits),
1985 Err(Error::Limit(_))
1986 ));
1987 std::fs::create_dir(dir.path().join("adir")).unwrap();
1988 assert!(matches!(
1989 stage_input(
1990 &dir.path().join("adir"),
1991 dir.path(),
1992 1,
1993 "bin",
1994 &Limits::default()
1995 ),
1996 Err(Error::Security(_))
1997 ));
1998 }
1999
2000 #[tokio::test]
2001 async fn backend_constraint_selects_or_rejects_routes() {
2002 let converter = graph_backend_converter();
2003 let dir = TempDir::new().unwrap();
2004 std::fs::write(dir.path().join("data.txt"), b"[1, 2, 3]").unwrap();
2005 let options = ConversionOptions {
2006 from: Some("txt".into()),
2007 backend: Some("builtin".into()),
2008 ..ConversionOptions::default()
2009 };
2010 let report = converter
2011 .convert(&[dir.path().join("data.txt")], "csv", &options)
2012 .await
2013 .err();
2014 assert!(report.is_some(),);
2015 }
2016
2017 #[test]
2018 #[cfg(feature = "media")]
2019 fn graph_routes_honor_policy() {
2020 let converter = graph_backend_converter();
2021 let strict = converter
2022 .plan("bin", "png", &Policy::default())
2023 .unwrap_err();
2024 assert!(matches!(
2025 strict,
2026 Error::Plan(convert_rs_core::PlanError::NoRoute { .. })
2027 ));
2028 }
2029}