Struct identity_common::StagedFile

pub struct StagedFile<'a> { /* private fields */ }

StagedFile is a wrapper around a |&DirectoryProxy| and a |FileProxy| for a staged file within that directory. The primary purpose of StagedFile is to implement the atomic write workflow summarized as open -> write -> sync -> close -> rename. This workflow is simplified to simply write -> commit. One caveat to the use of StagedFile is that in the event of power loss or a crash, there may be orphaned temporary files in the directory. This means that clients should clean up their directories of temporary files prior to operating in that directory. As such, it is important to choose a |filename_prefix| that is guaranteed not to collide with |target_filename|s given when calling StagedFile::commit. It would have been preferable to use the tempfile crate here, but it lacks the ability to open things without making use of paths and namespaces, and as such, StagedFile should only be used in cases where we must supply our own |DirectoryProxy|.

Implementations

impl<'a> StagedFile<'a>

pub async fn new( dir_proxy: &'a DirectoryProxy, tempfile_prefix: &str ) -> Result<StagedFile<'a>, StagedFileError>

Creates a new instance of StagedFile bound to the lifetime of |dir_proxy| that respects |filename_prefix|. |filename_prefix| must have a length > 0.

pub async fn write(&mut self, data: &[u8]) -> Result<(), StagedFileError>

Writes data to the backing staged file proxy. This file is not guaranteed to be persisted until commit is called, at which point it will be renamed to |target_filename|.

pub async fn commit(self, target_filename: &str) -> Result<(), StagedFileError>

Commits the data in the staged file to |target_filename| via the traditional sync -> close -> rename atomic write workflow. Calling commit does not guarantee that |target_filename| will be available, but it does guarantee atomicity of the file if it does exist.

pub async fn cleanup_stale_files( dir_proxy: &DirectoryProxy, tempfile_prefix: &str ) -> Result<(), Vec<StagedFileError>>

Helper function to unlink files in a directory given a function that takes a filename and returns whether or not to unlink it.