Crate liteboxfs 

LiteboxFS is a modern POSIX filesystem in a SQLite database.

use std::io::{Read, Write, Seek, SeekFrom};

use liteboxfs::{Connection, CreateOptions, FileKind, Owner};

fn main() -> liteboxfs::Result<()> {
    let mut conn = Connection::open_in_memory(&CreateOptions::new())?;

    let buf = conn.exec(|fs| {
        let mut file = fs.create("example.txt", FileKind::Regular, Owner::current())?;

        file.write_all(b"Hello, world!")?;
        file.seek(SeekFrom::Start(0))?;

        let mut buf = Vec::new();
        file.read_to_end(&mut buf)?;

        liteboxfs::Result::Ok(buf)
    })?;

    assert_eq!(buf, b"Hello, world!");

    Ok(())
}

Getting Started

A litebox is a SQLite database containing a filesystem.

Filesystem is the main type you will use to interact with LiteboxFS. To access the filesystem, you will first need to open a Connection and start a transaction.

Roots

Unlike a traditional POSIX filesystem, LiteboxFS supports multiple root directories, each identified by a universally unique RootId. This allows for multiple independent logical filesystems to coexist within the same database and deduplicate data between them. This feature can also be used to create copy-on-write snapshots of a filesystem.

In addition to their UUID, roots can optionally have a name, which is a UTF-8 string that is unique within the litebox.

When you create a litebox, it will automatically create a default root with name DEFAULT_ROOT_NAME. The default root always exists; it cannot be deleted.

Metadata

A litebox can have user-defined metadata associated with it in the form of key-value pairs. This metadata is stored persistently in the database and is not touched by LiteboxFS, so applications or downstream libraries can use it for any purpose.

Each root can also have its own user-defined metadata.

Compression and Deduplication

LiteboxFS has two optional features to improve storage efficiency at the cost of performance: transparent compression and content-defined chunking.

Files in a litebox are deduplicated at the block level, including between roots. When enabled, content-defined chunking can improve deduplication ratios between files that are similar but not identical.

These features are configurable per-litebox, not per-root. Both these features are feature-gated and disabled by default.

Transactions and Concurrency

LiteboxFS is transactional, with the same fundamental guarantees and caveats as SQLite.

This API makes transaction explicit, which means you can use them to maintain invariants in your application, just like you would with a database.

Internally, LiteboxFS uses savepoints to ensure that individual filesystem operations like copying a file, deleting a file, writing data to a file, etc. are atomic and consistent, with the transaction providing the isolation and durability.

Like SQLite, the concurrency model of LiteboxFS depends on the journal mode.

• In the default mode, readers block writers and writers block readers.
• In WAL mode, reading and writing can happen concurrently.

In both cases, you can only have a single write transaction active at a time, which means that holding a long-running write transaction will block other connections from writing (and possibly reading) to the litebox.

Like SQLite, once a write happens, the transaction is implicitly upgraded to a write transaction and stays that way until it is committed or rolled back. LiteboxFS generally tries to avoid writing to the database unless you tell it to; opening and reading a file should not require a write transaction, for example.

Encryption

LiteboxFS supports optional encryption via SQLCipher. If SQLCipher support is enabled (via Cargo features), you can specify either a password or an encryption key when creating or opening a litebox. The password/key can be changed later.

FUSE Support

On Linux, a litebox can be mounted in the host filesystem via FUSE. This allows for accessing the contents of a litebox root as if it were any other directory on the host system.

Mounting a litebox acquires an exclusive lock on the database for the duration of the mount.

You can mount a litebox root using Connection::mount or via the CLI.

Features

Feature	Default	Description
fs	Yes	Enable features that require interacting with the host filesystem.
compression	No	Enable support for transparent compression of file contents using Zstandard (zstd).
chunking	No	Enable support for content-defined chunking of file contents using FastCDC.
fuse	No	Enable support for mounting a litebox as a FUSE filesystem.
bundled-sqlite	No	Use a bundled version of SQLite instead of linking to it.
sqlcipher	No	Link to SQLCipher instead of SQLite. This searches for and links against a system-installed crypto library.
bundled-sqlcipher	No	Use a bundled version of SQLCipher instead of linking to it. This searches for and links against a system-installed crypto library.
bundled-sqlcipher-vendored-openssl	No	Use a bundled version of SQLCipher with a vendored version of OpenSSL.

Re-exports

pub use db::*;

pub use error::*;

pub use file::*;

pub use fs::*;

pub use metadata::*;

pub use root::*;

pub use user::*;

pub use walk::*;

Modules

db

Types for database connections, transactions, and the filesystem.

error

Error types.

file

Types for working with files and file contents.

fs

Types for interacting with the host filesystem.

metadata

Types for representing file metadata.

root

Types for working with filesystem roots.

user

Types for user-defined metadata associated with filesystems and roots.

walk

Types for walking the filesystem.

Structs

Connection

A connection to a litebox.

File

A handle for accessing a file in the filesystem.

Filesystem

A LiteboxFS filesystem.

Enums

Error

The error type for liteboxfs.

Type Aliases

Result

The result type for operations with a litebox.