Crate webc

Expand description

A library for reading and writing WEBC files.

The Container provides an abstraction over the various WEBC versions this crate can handle. As such, it tries to cater to the lowest common denominator and favors portability over performance or power.

use webc::{Container, Version};
let bytes: &[u8] = b"\0webc...";

let container = Container::from_bytes_and_version(bytes.into(), Version::V3)?;

println!("{:?}", container.manifest());

println!("Atoms:");
for (name, atom) in container.atoms() {
    let length = atom.len();
    println!("{name}: {length} bytes");
}

for (name, volume) in container.volumes() {
    let root_items = volume.read_dir("/").expect("The root directory always exists");
    println!("{name}: {} items", root_items.len());
}

In general, errors that occur during lazy operations won’t be accessible to the user.

§Version-Specific Fallbacks

If more flexibility is required, consider using crate::detect() and instantiating a compatible parser directly.

use webc::{
    Container,
    Version,
};
use webc::v1::{ParseOptions, WebC};
use webc::v3::read::OwnedReader;
let bytes: &[u8] = b"...";

match webc::detect(bytes) {
    Ok(Version::V1) => {
        let options = ParseOptions::default();
        let webc = WebC::parse(bytes, &options).unwrap();
        if let Some(signature) = webc.signature {
            println!("Package signature: {:?}", signature);
        }
    }
    Ok(Version::V3) => {
        let webc = OwnedReader::parse(bytes).unwrap();
        let index = webc.index();
        let signature = &index.signature;
        if !signature.is_none() {
            println!("Package signature: {signature:?}");
        }
    }
    Ok(other) => todo!("Unsupported version, {other}"),
    Err(e) => todo!("An error occurred: {e}"),
}

§Feature Flags

v1 (enabled by default) — Load WEBC files in the v1 format
v2 (enabled by default) — Load WEBC files in the v2 format
v3 (enabled by default) — Load WEBC files in the v3 format
crypto — Sign and verify binaries in v1 webc format
mmap — No longer used

Re-exports§

pub extern crate bytes;
pub extern crate indexmap;

Modules§

compatDeprecated: A compatibility layer for dealing with different versions of the WEBC binary format.
metadata: Package metadata.
migrationv2 and v3: Contains code for migrating v2 <–> v3
v1v1: Parsing code for v1 of the WEBC format.
v2v2: Parsing code for v2 of the WEBC format.
v3v3: Parsing code for v3 of the WEBC format.

Structs§

Container: A version-agnostic read-only WEBC container.
PathSegment: a cheaply cloneable path segment (i.e. the path, to, and file.txt in path/to/file.txt).
PathSegments: A series of PathSegments specifying the absolute path to something.
Timestamps: Represents file or directory timestamps.
Version: A WEBC file’s version number.
Volume: A WEBC volume.

Enums§

ContainerError: Various errors that may occur during Container operations.
DetectError: An error returned by detect().
DirectoryFromPathError: Error returned from from_path_with_ignore.
Metadata: Metadata describing the properties of a file or directory.
PathSegmentError: An error that may occur while parsing a PathSegment or PathSegments.
VolumeError: Errors that may occur when doing Volume operations.

Constants§

MAGIC: File identification bytes stored at the beginning of the file.

Traits§

AbstractVolume: Abstraction over different volume implementations
ToPathSegments: Convert something into PathSegments.

Functions§

detect: Check whether something looks like a valid WEBC file and extract its version number.
is_webc: Check if the provided item looks like a WEBC file.
sanitize_path: Turn any path that gets passed in into something WASI can use.

Type Aliases§

Magic: The type for MAGIC.

Crate webcCopy item path