Expand description
File conversion through a policy-controlled graph of independent adapters.
Use Converter::new for compiled-in pure-Rust adapters. With the external
feature, Converter::discover().await also probes installed native tools.
Discovery does not enable external routes; set Policy::allow_external
explicitly. Register additional implementations through Converter::register.
§Convert a file
Conversion requires a Tokio runtime. This example uses only the byte/text API and no native tools. A same-format request stages a byte-for-byte copy without decoding, validating the claimed format, or choosing a codec.
use convert_rs::{ConversionOptions, Converter};
let inputs = tempfile::tempdir()?;
let source = inputs.path().join("note.txt");
std::fs::write(&source, "Conversion example\n")?;
let converter = Converter::new();
let report = converter.convert(&[source], "txt", &ConversionOptions::default()).await?;
assert!(report.plan.steps.is_empty());
assert!(report.warnings.is_empty());
assert_eq!(std::fs::read_to_string(&report.artifacts[0].path)?, "Conversion example\n");
// Persist output outside the report-owned workspace before dropping it.
let saved = inputs.path().join("saved.txt");
std::fs::copy(&report.artifacts[0].path, &saved)?;
let temporary = report.artifacts[0].path.clone();
drop(report);
assert!(!temporary.exists());
assert!(saved.exists());§Features and fidelity
Default features are data (JSON, TOML, CSV), media (image and audio
operations), archives (archive and compression operations), and external
(native-tool discovery). Without default features, the built-in byte and text
operations remain. Registered formats and available routes depend on features
and adapters; listing a format does not promise an encoder for every input.
Plans use adapter-declared costs and semantic classifications. The default
policy permits lossy conversions. There is no lossless-only policy flag:
inspect Plan::steps and, if appropriate, execute a reviewed forced plan.
ConversionReport::warnings describes non-lossless steps of the successful
route, not measured quality loss or every possible metadata change. An empty
warning list is not proof of complete fidelity. No public option selects
codecs, bitrates, or encoder quality settings.
§Execution boundaries
Inputs are staged separately for each attempted route. Final paths belong to
the returned ConversionReport and are removed when it is dropped. Cloning
an Artifact does not keep its file alive. Returned output paths, declared
formats, counts, and byte totals are checked, but file contents are not
independently decoded by the engine to verify their declared format.
Limits provides staging checks and adapter-specific budgets, not a hard
memory, CPU, disk, or wall-clock sandbox. Custom adapters are trusted code.
Native tools require operating-system isolation when processing hostile data;
this library does not provide that isolation.
Structs§
- Artifact
- A path and declared format for a staged input or adapter output.
- Backend
Status - An adapter’s reported availability and diagnostic detail.
- Content
Kind - A type of content carried inside or represented by a file.
- Content
Profile - The content streams a specific file or format representation carries.
- Conversion
- A directed conversion edge supplied by an adapter.
- Conversion
Options - Per-conversion identification and route-selection choices.
- Conversion
Report - A resolved conversion: the accepted route, its warnings, and the artifacts.
- Converter
- Adapter registry, routing configuration, and file conversion entry point.
- Format
- A registered format and its lookup metadata.
- Graph
- An in-memory registry of formats and directed conversion edges.
- Identification
- A resolved input format with the evidence used to determine it.
- Input
Report - Identification plus per-format deep-decode results for one input file.
- Limits
- Resource budgets used during staging, output checks, and adapter execution.
- Plan
- An ordered sequence of conversion steps and its declared total cost.
- Policy
- Gates and search budgets used by
Graph::routes. - Profile
Report - Identification plus an optional content profile for one input file.
- Route
Attempt - One attempted route during a single
Converter::convertcall. - Step
Cost - A note explaining what an executed step costs or discards.
- Step
Request - One adapter invocation. Adapters must write only inside
output_dir, must not change inputs, and must return at least one regular file on success. - Stream
- One observed or declared stream inside a container.
- Target
Capability - One target format’s reachability from a source format.
- Warning
- An informational warning derived from an executed step’s declared kind.
Enums§
- Capability
Reason - How reachable a requested target format is from a probed source format.
- Conversion
Category - A registered conversion’s role relative to the content’s ordinary purpose.
- Conversion
Kind - An adapter-declared description of a conversion’s semantics.
- Error
- Failures from registration, identification, planning, and execution.
- Identification
Method - Evidence source used by
Converter::identify. - Media
Kind - A format’s media category. Categories do not restrict graph connectivity.
- Profile
Source - Where a
Converter::profileprofile came from.
Traits§
- Adapter
- Output port for conversion backends. Implement this to add formats without changing the planner or orchestrator. Backend names identify registrations; registering the same name replaces its previous implementation.
Type Aliases§
- Conversion
Future - A sendable, boxed adapter future yielding ordered artifacts or an
Error. - Inspect
Future - Boxed future returned by
Adapter::inspect. - Result
- Result of a library operation, with
Errordescribing failure.