Crate boxferry

Expand description

Reusable high-level APIs for BoxFerry conversions.

This facade exposes the same neutral model and conversion engine used by the boxferry command-line application. Compose, Podman, and Quadlet adapters are available through additive features. Every conversion uses the importer → neutral model → exporter pipeline.

Planning does not execute generated commands or mutate a runtime. Podman acquisition requires an explicit caller-supplied read-only transport, and Podman output is a reviewable deployment plan and command script.

§Example

use boxferry::{
    Application, Identifier, InMemoryAdapter, LossPolicy, PlatformVersion, TargetProfile,
    convert,
};

let application = Application::new(Identifier::new("example")?);
let adapter = InMemoryAdapter::exact("target document".to_owned());
let target = TargetProfile::new("podman", PlatformVersion::new(5, 4, 0), None)?;
let result = convert(
    &adapter,
    &application,
    &adapter,
    &target,
    LossPolicy::ExactOnly,
)?;

assert_eq!(result.output().map(String::as_str), Some("target document"));

Re-exports§

pub use boxferry_compose as compose;
pub use boxferry_engine as engine;
pub use boxferry_model as model;
pub use boxferry_podman as podman;
pub use boxferry_quadlet as quadlet;

Modules§

report: Versioned, presentation-independent conversion reports. Versioned, privacy-safe conversion reports.

Structs§

Annotation: One protected annotation with independently sourced name and value.
Application: One ordered multi-service application graph.
ArtifactDependency: One explicit, directed image-artifact dependency.
BuildContext: One named additional context in a structured source build declaration.
BuildSettingValues: One typed collection belonging to one explicitly present image-artifact key.
ComposeExporter: Loss-aware exporter for deterministic, parse-back-validated Compose YAML.
ComposeImporter: Maps an explicitly processed Compose source into BoxFerry’s neutral model.
ComposeSource: A merged Compose project and the caller-owned context needed to import it safely.
Config: One application-level configuration declaration.
ConversionOutcome: One subject-level conversion decision.
ConversionPlan: Validated target candidate, decisions, and structured diagnostics.
ConversionResult: Policy-authorized conversion output and its complete report.
Diagnostic: Structured conversion diagnostic.
DiagnosticCode: Stable machine-readable diagnostic identifier.
DiagnosticField: Named structured context attached to a diagnostic.
DiagnosticRule: Immutable metadata shared by human, JSON, and support-bundle presentation.
EnvironmentFile: One ordered environment-file declaration.
EnvironmentVariable: One ordered service environment entry.
ExposedPort: A container port exposed for inter-service use without publishing it to a host.
Healthcheck: Format-independent service health-check intent with field-level provenance.
HealthcheckDuration: Raw-preserving duration shared by container health-check implementations.
HealthcheckRetries: Raw-preserving non-negative health-check retry count.
HostAddress: One raw-preserving address or runtime token used by a service host mapping.
HostMapping: One ordered service hostname-to-address mapping.
Identifier: Opaque, non-empty application or resource identifier.
ImageAcquisition: An image-acquisition resource.
ImageArtifactAssignment: One source-preserving assignment used by image artifact settings.
ImageBuild: An image-build resource with independently retained source declaration and artifact settings.
ImageReference: A preserved image reference with optional tag and digest components.
ImportResult: Recoverable result of importing a native source model.
InMemoryAdapter: Deterministic adapter for public API tests and embedding examples.
KernelParameter: One raw-preserving kernel-parameter assignment.
Logging: Provider-specific logging intent.
LoggingOption: One provider-specific logging option with independently sourced name and value.
MetadataLabel: One portable metadata label attached to an application resource.
Mount: One service storage attachment.
NativeFinding: A native parser, model, runtime, or platform finding retained at an adapter boundary.
NativeFindingLabel: One value-free source location attached to a native-format finding.
Network: One application-level network declaration.
NetworkAttachment: One service attachment to an application network.
NetworkDriverOption: One driver-specific network option with independently sourced key and value.
NetworkIpamConfig: One explicitly associated IPAM configuration row.
ParsePlatformVersionError: Error returned when a platform version is not exactly major.minor.patch.
PlatformVersion: Numeric target implementation version.
PodmanExporter: Loss-aware Podman exporter producing only review artifacts.
PodmanImporter: PodmanLens-to-neutral-model semantic importer.
PodmanOutput: Serialized PodmanLens deployment artifact and runnable shell rendering.
PodmanPromotionPolicy: Explicit authorization for promoting effective runtime observations into desired intent.
PodmanSource: One explicit Podman import source after caller-owned acquisition and discovery.
Port: One container port and its optional single-host publication.
ProtectedString: Plain or sensitive text with redacting debug output.
Provenance: Location from which a neutral-model value was derived.
QuadletDocumentInput: One caller-supplied Quadlet unit file held entirely in memory.
QuadletExporter: Native target adapter for validated Podman Quadlet output.
QuadletFile: One generated Quadlet file whose contents passed QuadletLens parse-back validation.
QuadletImporter: Maps an explicitly parsed Quadlet document set into BoxFerry’s neutral model.
QuadletOutput: Deterministically ordered generated files and their validated dependency graph.
QuadletParseDiagnostic: One recoverable QuadletLens diagnostic retained without source contents.
QuadletParseDiagnosticLabel: One labelled byte range on a QuadletParseDiagnostic.
QuadletParseError: Quadlet parse failure with recoverable diagnostics retained.
QuadletParseFailure: A non-recoverable failure that prevented a parse result.
QuadletParseResult: Successful native parse with every recoverable diagnostic retained.
QuadletSource: A named Quadlet document set and caller-owned source identities.
ResolvedPodmanTarget: A BoxFerry target resolved to one exact reviewed Podman engine and API pair.
ResourceGrant: One ordered service grant of a configuration or secret resource.
ResourceLimit: One raw-preserving resource-limit declaration.
RetainedNativeEvidence: One provenance-bearing native evidence event.
Secret: One application-level secret declaration.
Service: One application service with ordered attachments and source provenance.
ServiceDependency: One ordered dependency edge from a service to another application service.
ServiceGroup: One structural group of application services.
ServiceGroupRuntime: Native runtime settings owned by one ServiceGroup.
SourceBuildSecret: A source build-secret declaration whose options remain distinct from target build-secret text.
SourceId: Caller-selected identity for one imported source.
SourceSpan: Half-open byte range in one imported source.
Sourced: A value and every source location that contributed to it.
StopTimeout: Raw-preserving stop grace duration.
TargetProfile: Caller-selected target implementation and supported compatibility range.
VersionRange: Inclusive minimum and optional maximum target versions.
Volume: One application-level volume declaration.

Enums§

ArtifactDependencyNode: A format-neutral node used by explicit image-artifact dependency validation.
BuildAttestation: A source build attestation value.
BuildSourceDeclaration: One source declaration for an image build.
BuildSyntax: The generic syntax family that supplied a build declaration or per-key value collection.
Command: How a service command overrides the image command.
ComposeFindingStage: Compose processing layer that emitted a retained native finding.
ComposeRuntime: Exact backend runtime used by the selected Compose provider.
ConfigMaterial: Material source for an application-managed configuration resource.
ConversionError: Failure before a policy-authorized conversion result can be created.
ConversionKind: Fidelity of one source-to-target decision.
Device: A service device declaration with its authored syntax retained.
DiagnosticValue: Plain or sensitive diagnostic field value.
Entrypoint: How a service overrides the image entrypoint.
EnvironmentFileFormat: Explicit parsing mode requested for an environment file.
EnvironmentFileSyntax: Authored syntax family retained for an environment-file declaration.
EnvironmentValue: Source of an environment variable’s value.
GroupExitPolicy: Pod exit behavior retained without assigning lifecycle semantics to group membership.
HealthcheckCommand: How a container runtime executes one service health check.
HostAddressKind: Conservative kind of one service host-mapping address.
ImageAcquisitionSetting: One image-acquisition setting.
ImageBuildSetting: One image-build setting.
LossPolicy: Caller-selected authorization for non-exact candidate output.
ModelError: Error raised when constructing an invalid neutral model value.
MountSource: Storage backing attached to a service.
NativeFindingLabelKind: Producer-neutral role of one source location attached to a native finding.
PodmanTargetError: Failure to resolve a BoxFerry target to reviewed Podman rendering evidence.
Protocol: Transport protocol attached to a published port.
ProvenanceKind: How a neutral-model value entered a conversion plan.
PullPolicy: Source-independent image pull intent.
QuadletExporterError: Failure while creating a Quadlet exporter.
QuadletGroupingPolicy: Caller-selected relationship between source services and generated Quadlet units.
QuadletParseDiagnosticOrigin: Origin of one native diagnostic retained by QuadletSource::parse.
QuadletParseDiagnosticSeverity: Severity of one native diagnostic retained by QuadletSource::parse.
QuadletParseFailureStage: Stage that produced a non-recoverable parse failure.
ReloadAction: One mutually exclusive reload action.
ResourceGrantSyntax: Authored syntax family retained for a config or secret grant.
ResourceOwnership: Who owns a named application resource lifecycle.
RestartPolicy: Container-level automatic restart intent.
RetainedNativeEvidenceEvent: One authored opaque native occurrence retained in source order.
RetainedNativeEvidenceSubject: Resource-qualified opaque source fact retained for explanation, never execution.
RuleId: Stable identifier for one BoxFerry diagnostic rule.
SecretMaterial: Material source for an application-managed secret resource.
SecurityOption: One format-independent service security option.
SelinuxRelabel: SELinux label sharing requested for a bind mount.
ServiceDependencyCondition: Readiness state a service dependency must reach before its dependent starts.
Severity: Diagnostic severity independent from presentation and process exit codes.
SourceBuildSetting: One field from a structured source build declaration.
StartupNotification: Startup notification behavior requested for one service.
VolumeImageSource: The explicit source of an image-backed volume.

Constants§

COMPOSE_SPECIFICATION_PROFILE_REVISION: Internal revision used with COMPOSE_SPECIFICATION_TARGET.
COMPOSE_SPECIFICATION_TARGET: Provider-neutral target for the rolling Compose Specification.
DOCKER_COMPOSE_TARGET: Target implementation name for Docker Compose output.
PODMAN_COMPOSE_TARGET: Target implementation name for the independent containers/podman-compose provider.
PODMAN_TARGET: Target implementation name accepted by the Podman exporter.
RULES: Complete, code-sorted catalogue for this BoxFerry build.

Traits§

ExportAdapter: Plans one neutral application for a native target model.
ImportAdapter: Maps one native source model into the format-independent application model.

Functions§

acquire_podman_source: Acquires and discovers one explicit read-only Podman source.
convert: Runs the same explicit import-plan-authorize path used by the BoxFerry CLI.
convert_imported: Continues conversion from one completed native-to-neutral import.
find_rule: Finds a rule by exact code or human-readable name.
resolve_podman_target: Selects the newest exact reviewed Podman version in the requested inclusive range.
reviewed_podman_versions: Returns exact Podman engine versions backed by PodmanLens rendering evidence.

Crate boxferry

Crate boxferry Copy item path

§Example

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate boxferry