Struct Repository 

pub struct Repository<ObjectID: FsVerityHashValue> {
    repository: OwnedFd,
    objects: OnceCell<OwnedFd>,
    insecure: bool,
    _data: PhantomData<ObjectID>,
}

A content-addressable repository for composefs objects.

Stores content-addressed objects, splitstreams, and images with fsverity verification. Objects are stored by their fsverity digest, streams by SHA256 content hash, and both support named references for persistence across garbage collection.

Fields

repository: OwnedFd

objects: OnceCell<OwnedFd>

insecure: bool

_data: PhantomData<ObjectID>

Implementations

impl<ObjectID: FsVerityHashValue> Repository<ObjectID>

pub fn objects_dir(&self) -> ErrnoResult<&OwnedFd>

Return the objects directory.

pub fn open_path(dirfd: impl AsFd, path: impl AsRef<Path>) -> Result<Self>

Open a repository at the target directory and path.

pub fn open_user() -> Result<Self>

Open the default user-owned composefs repository.

pub fn open_system() -> Result<Self>

Open the default system-global composefs repository.

fn ensure_dir(&self, dir: impl AsRef<Path>) -> ErrnoResult<()>

pub async fn ensure_object_async( self: &Arc<Self>, data: Vec<u8>, ) -> Result<ObjectID>

Asynchronously ensures an object exists in the repository.

Same as ensure_object but runs the operation on a blocking thread pool to avoid blocking async tasks. Returns the fsverity digest of the object.

pub fn ensure_object(&self, data: &[u8]) -> Result<ObjectID>

Given a blob of data, store it in the repository.

fn open_with_verity( &self, filename: &str, expected_verity: &ObjectID, ) -> Result<OwnedFd>

pub fn set_insecure(&mut self, insecure: bool) -> &mut Self

By default fsverity is required to be enabled on the target filesystem. Setting this disables verification of digests and an instance of Self can be used on a filesystem without fsverity support.

pub fn create_stream( self: &Arc<Self>, sha256: Option<Sha256Digest>, maps: Option<DigestMap<ObjectID>>, ) -> SplitStreamWriter<ObjectID>

Creates a SplitStreamWriter for writing a split stream. You should write the data to the returned object and then pass it to .store_stream() to store the result.

fn format_object_path(id: &ObjectID) -> String

pub fn has_stream(&self, sha256: &Sha256Digest) -> Result<Option<ObjectID>>

Check if the provided splitstream is present in the repository; if so, return its fsverity digest.

pub fn check_stream(&self, sha256: &Sha256Digest) -> Result<Option<ObjectID>>

Similar to Self::has_stream but performs more expensive verification.

pub fn write_stream( &self, writer: SplitStreamWriter<ObjectID>, reference: Option<&str>, ) -> Result<ObjectID>

Write the given splitstream to the repository with the provided name.

pub fn name_stream(&self, sha256: Sha256Digest, name: &str) -> Result<()>

Assign the given name to a stream. The stream must already exist. After this operation it will be possible to refer to the stream by its new name ‘refs/{name}’.

pub fn ensure_stream( self: &Arc<Self>, sha256: &Sha256Digest, callback: impl FnOnce(&mut SplitStreamWriter<ObjectID>) -> Result<()>, reference: Option<&str>, ) -> Result<ObjectID>

Ensures that the stream with a given SHA256 digest exists in the repository.

This tries to find the stream by the sha256 digest of its contents. If the stream is already in the repository, the object ID (fs-verity digest) is read from the symlink. If the stream is not already in the repository, a SplitStreamWriter is created and passed to callback. On return, the object ID of the stream will be calculated and it will be written to disk (if it wasn’t already created by someone else in the meantime).

In both cases, if reference is provided, it is used to provide a fixed name for the object. Any object that doesn’t have a fixed reference to it is subject to garbage collection. It is an error if this reference already exists.

On success, the object ID of the new object is returned. It is expected that this object ID will be used when referring to the stream from other linked streams.

pub fn open_stream( &self, name: &str, verity: Option<&ObjectID>, ) -> Result<SplitStreamReader<File, ObjectID>>

Open a splitstream with the given name.

pub fn open_object(&self, id: &ObjectID) -> Result<OwnedFd>

Given an object identifier (a digest), return a read-only file descriptor for its contents. The fsverity digest is verified (if the repository is not in insecure mode).

pub fn merge_splitstream( &self, name: &str, verity: Option<&ObjectID>, stream: &mut impl Write, ) -> Result<()>

Merges a splitstream into a single continuous stream.

Opens the named splitstream, resolves all object references, and writes the complete merged content to the provided writer. Optionally verifies the splitstream’s fsverity digest matches the expected value.

pub fn write_image(&self, name: Option<&str>, data: &[u8]) -> Result<ObjectID>

Write data into the repository as an image with the given name`.

The fsverity digest is returned.

Integrity

This function is not safe for untrusted users.

pub fn import_image<R: Read>( &self, name: &str, image: &mut R, ) -> Result<ObjectID>

Import the data from the provided read into the repository as an image.

The fsverity digest is returned.

Integrity

This function is not safe for untrusted users.

fn open_image(&self, name: &str) -> Result<(OwnedFd, bool)>

Returns the fd of the image and whether or not verity should be enabled when mounting it.

pub fn mount(&self, name: &str) -> Result<OwnedFd>

Create a detached mount of an image. This file descriptor can then be attached via e.g. move_mount.

pub fn mount_at(&self, name: &str, mountpoint: impl AsRef<Path>) -> Result<()>

Mount the image with the provided digest at the target path.

pub fn symlink( &self, name: impl AsRef<Path>, target: impl AsRef<Path>, ) -> ErrnoResult<()>

Creates a relative symlink within the repository.

Computes the correct relative path from the symlink location to the target, creating any necessary intermediate directories. Atomically replaces any existing symlink at the specified name.

fn read_symlink_hashvalue(dirfd: &OwnedFd, name: &CStr) -> Result<ObjectID>

fn walk_symlinkdir(fd: OwnedFd, objects: &mut HashSet<ObjectID>) -> Result<()>

fn openat(&self, name: &str, flags: OFlags) -> ErrnoResult<OwnedFd>

Open the provided path in the repository.

fn gc_category(&self, category: &str) -> Result<HashSet<ObjectID>>

pub fn objects_for_image(&self, name: &str) -> Result<HashSet<ObjectID>>

Given an image, return the set of all objects referenced by it.

pub fn gc(&self) -> Result<()>

Perform a garbage collection operation.

Locking

An exclusive lock is held for the duration of this operation.

Trait Implementations

impl<ObjectID: Debug + FsVerityHashValue> Debug for Repository<ObjectID>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<ObjectID: FsVerityHashValue> Drop for Repository<ObjectID>

fn drop(&mut self)

Executes the destructor for this type.