composefs/
lib.rs

1//! # composefs: The reliability of disk images, the flexibility of files
2//!
3//! composefs combines several Linux kernel features to provide read-only
4//! mountable filesystem trees that stack on top of a conventional "lower"
5//! filesystem.
6//!
7//! ## Interfaces
8//!
9//! composefs offers two programmatic interfaces:
10//!
11//! - **Rust API** — this crate and its siblings (`composefs-oci`,
12//!   `composefs-boot`, etc.), usable as regular Cargo dependencies.
13//! - **Varlink API** — a [varlink](https://varlink.org) RPC interface
14//!   exposed by `cfsctl varlink` over a Unix socket, accessible from
15//!   any language.  See the [`varlink`] module for examples.
16//!
17//! Neither interface is declared stable yet.  Both may change across
18//! releases while the project is under active development.
19//!
20//! ## Key technologies
21//!
22//! - **[overlayfs]** — the kernel mount interface that exposes the composed tree
23//! - **[EROFS]** — an in-kernel read-only filesystem for the metadata tree
24//!   (directories, symlinks, permissions, xattrs) with no file data
25//! - **[fs-verity]** (optional) — per-file integrity verification on the
26//!   backing store, validated by overlayfs at access time
27//!
28//! [overlayfs]: https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt
29//! [EROFS]: https://erofs.docs.kernel.org
30//! [fs-verity]: https://www.kernel.org/doc/html/next/filesystems/fsverity.html
31//!
32//! ## Design
33//!
34//! composefs produces an EROFS image containing *only* metadata.  Non-empty
35//! data files live in a content-addressed backing store, with
36//! `trusted.overlay.redirect` xattrs telling overlayfs where to find them.
37//! Identical files across images are stored once on disk and shared in the
38//! Linux page cache.
39//!
40//! See the [`repository_format`] module for the on-disk layout.
41
42#![forbid(unsafe_code)]
43// This is a library: emit diagnostics via the `log` crate (or return them),
44// never by writing to the process's stdout/stderr. Genuinely-intentional
45// exceptions carry a local `#[allow]` with justification. Test code is exempt.
46#![cfg_attr(not(test), deny(clippy::print_stdout, clippy::print_stderr))]
47
48pub mod digest;
49pub mod dumpfile;
50pub mod dumpfile_parse;
51pub mod erofs;
52pub mod filesystem_ops;
53pub mod fs;
54pub mod fsverity;
55pub mod mount;
56pub mod mountcompat;
57pub mod progress;
58pub mod repository;
59pub use repository::ImageNotFound;
60pub mod splitstream;
61pub mod tree;
62pub mod util;
63
64#[cfg(doc)]
65pub mod erofs_format;
66pub mod generic_tree;
67#[cfg(doc)]
68pub mod repository_format;
69#[cfg(doc)]
70pub mod splitstream_format;
71#[cfg(any(test, feature = "test"))]
72pub mod test;
73pub mod varlink;
74
75/// Files with this many bytes or fewer are stored inline in the erofs image
76/// (and in splitstreams).  Files above this threshold are written to object
77/// storage and referenced via overlay metacopy xattrs.
78///
79/// Changing this value is effectively a format break: it affects which files
80/// get fs-verity checksums (external) vs. which are stored directly (inline),
81/// so images produced with different thresholds are not interchangeable.
82/// A future composefs format version may change this size
83/// (see <https://github.com/composefs/composefs-rs/issues/107>).
84///
85/// For the *parsing* safety bound enforced when reading untrusted input, see
86/// [`MAX_INLINE_CONTENT`].
87pub const INLINE_CONTENT_MAX_V0: usize = 64;
88
89/// Maximum inline content size accepted when parsing untrusted input (dumpfiles,
90/// EROFS images in composefs-restricted mode).
91///
92/// Only enforced for v2 images; the C code does not check this limit.
93///
94/// This is intentionally higher than [`INLINE_CONTENT_MAX_V0`] to allow for future
95/// increases to the inline threshold (see
96/// <https://github.com/composefs/composefs-rs/issues/107>).
97pub const MAX_INLINE_CONTENT: usize = 512;
98
99/// Maximum symlink target length in bytes.
100///
101/// Only enforced for v2 images; the C code does not check this limit.
102///
103/// XFS limits symlink targets to 1024 bytes (`XFS_SYMLINK_MAXLEN`). Since
104/// generic Linux containers are commonly backed by XFS, we enforce that
105/// limit rather than the Linux VFS `PATH_MAX` of 4096.
106pub const SYMLINK_MAX: usize = 1024;
107
108/// Internal constants shared across workspace crates.
109///
110/// Not part of the public API — may change without notice.
111#[doc(hidden)]
112pub mod shared_internals {
113    /// Default I/O buffer capacity for BufWriter/BufReader in streaming paths.
114    ///
115    /// The stdlib default of 8 KiB is suboptimal for large file I/O.
116    /// 64 KiB provides significantly better throughput.
117    /// See <https://github.com/bootc-dev/ocidir-rs/pull/63>.
118    pub const IO_BUF_CAPACITY: usize = 64 * 1024;
119}
composefs/lib.rs

composefs/
lib.rs
