webc 9.1.0

WebContainer implementation for wapm.io
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! 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.
//!
//! ```rust,no_run
//! 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());
//! }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! 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.
//!
//! ```rust,no_run
//! use webc::{
//!     Container,
//!     Version,
//! };
//! # #[cfg(feature = "v1")]
//! use webc::v1::{ParseOptions, WebC};
//! # #[cfg(feature = "v3")]
//! use webc::v3::read::OwnedReader;
//! let bytes: &[u8] = b"...";
//!
//! match webc::detect(bytes) {
//! #   #[cfg(feature = "v1")]
//!     Ok(Version::V1) => {
//!         let options = ParseOptions::default();
//!         let webc = WebC::parse(bytes, &options).unwrap();
//!         if let Some(signature) = webc.signature {
//!             println!("Package signature: {:?}", signature);
//!         }
//!     }
//! #   #[cfg(feature = "v3")]
//!     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
//!
#![doc = document_features::document_features!()]
#![warn(unreachable_pub, elided_lifetimes_in_paths)]
#![deny(missing_docs, missing_debug_implementations)]
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]

pub extern crate bytes;
pub extern crate indexmap;

#[cfg(test)]
#[macro_use]
extern crate pretty_assertions;

#[cfg(test)]
#[macro_use]
#[allow(dead_code, unused_macros)]
mod macros;

mod container;
mod detect;
mod from_path_with_ignore;
pub mod metadata;
mod path_segments;
mod readable_bytes;
mod timestamps;
mod utils;
#[allow(missing_docs)]
#[cfg(feature = "v1")]
pub mod v1;
#[cfg(feature = "v2")]
pub mod v2;
#[cfg(feature = "v3")]
pub mod v3;

#[cfg(all(feature = "v2", feature = "v3"))]
pub mod migration;

mod version;
mod volume;

/// The type for [`MAGIC`].
pub type Magic = [u8; 5];

/// File identification bytes stored at the beginning of the file.
pub const MAGIC: Magic = *b"\0webc";

pub use crate::{
    container::{Container, ContainerError},
    detect::{detect, is_webc, DetectError},
    from_path_with_ignore::DirectoryFromPathError,
    path_segments::{PathSegment, PathSegmentError, PathSegments, ToPathSegments},
    timestamps::Timestamps,
    utils::sanitize_path,
    version::Version,
    volume::{AbstractVolume, Metadata, Volume, VolumeError},
};

pub(crate) use timestamps::since_epoch;

#[doc(hidden)] // HACK: Made accessible for wasmer-cli. Not for public use.
pub use crate::container::{AbstractWebc, AsAny};

/// A compatibility layer for dealing with different versions of the WEBC binary
/// format.
#[deprecated(since = "5.1.0", note = "Import types directly from the crate")]
pub mod compat {
    pub use crate::{
        container::{Container, ContainerError},
        volume::{Metadata, Volume, VolumeError},
    };

    #[deprecated = "Use shared_buffer::OwnedBuffer directly"]
    pub use shared_buffer::OwnedBuffer as SharedBytes;
}