Skip to main content

Crate convert_rs

Crate convert_rs 

Source
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.
BackendStatus
An adapter’s reported availability and diagnostic detail.
ContentKind
A type of content carried inside or represented by a file.
ContentProfile
The content streams a specific file or format representation carries.
Conversion
A directed conversion edge supplied by an adapter.
ConversionOptions
Per-conversion identification and route-selection choices.
ConversionReport
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.
InputReport
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.
ProfileReport
Identification plus an optional content profile for one input file.
RouteAttempt
One attempted route during a single Converter::convert call.
StepCost
A note explaining what an executed step costs or discards.
StepRequest
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.
TargetCapability
One target format’s reachability from a source format.
Warning
An informational warning derived from an executed step’s declared kind.

Enums§

CapabilityReason
How reachable a requested target format is from a probed source format.
ConversionCategory
A registered conversion’s role relative to the content’s ordinary purpose.
ConversionKind
An adapter-declared description of a conversion’s semantics.
Error
Failures from registration, identification, planning, and execution.
IdentificationMethod
Evidence source used by Converter::identify.
MediaKind
A format’s media category. Categories do not restrict graph connectivity.
ProfileSource
Where a Converter::profile profile 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§

ConversionFuture
A sendable, boxed adapter future yielding ordered artifacts or an Error.
InspectFuture
Boxed future returned by Adapter::inspect.
Result
Result of a library operation, with Error describing failure.