cellar_lowlevel library

Backend assembly kit for cellar.

package:cellar/cellar.dart's Cellar constructor handles the standard platform + encryption case; this entrypoint exposes the underlying backend pieces so you can compose stacks Cellar doesn't cover, wire your own backend, or chunk an arbitrary backing store.

Example — encrypted, chunked-on-native storage rooted at a custom directory, wired into a multi-partition Cellar:

import 'package:cellar/cellar.dart';            // Cellar + facade types
import 'package:cellar/cellar_lowlevel.dart';   // backend pieces

final mainBackend = EncryptedBackend(
  inner: ChunkedBackend(
    backing: FileSystemBackend('/var/data/main'),
  ),
  encryptor: myEncryptor,
);

final cellar = Cellar.withBackends(
  {'main': mainBackend},
  defaultPartition: 'main',
  keyPrefix: 'user/u1',
);
await cellar.open();

To plug in a brand-new backend (DynamoDB, GCS without S3 interop, an in-memory cache, …), implement StorageBackend and pass it to Cellar.withBackends. The Cellar surface is identical regardless of the backing store.

Classes

ChunkedBackend

Generic chunked storage layer.

ChunkedManifest

In-memory representation of a manifest record.

EncryptedBackend

Transparent encryption decorator for StorageBackend.

EncryptionKeyResolver

Resolves encryption keys for file operations.

FileEncryptor

Bring-your-own encryption interface for EncryptedBackend.

FileSystemBackend

Web stub for the native-only filesystem backend — constructor throws.

IndexedDbBackend

Native stub for the web-only IndexedDB backend — constructor throws.

MaterializedFile

A handle to a stored object made available for non-Dart consumers.

ObjectInfo

Metadata about a stored object.

StorageBackend

Platform-agnostic object storage interface.

StorageRoots

The two native directories a default-constructed Cellar places partitions under, resolved once per cellar.

StorageScope

Tenant-scoping wrapper around a StorageBackend.

WriteOptions

Options for write operations.

Mixins

DisposeGuard

Mixin providing the disposed flag, the idempotent marker, and the post-dispose StateError check shared by every StorageBackend.

Functions

initDefaultBackend({required String name, StorageRoots? roots}) → Future<StorageBackend>

Fallback stub — throws on platforms with neither dart:io nor dart:js_interop.

Exceptions / Errors

ChunkVerificationError

Per-chunk MAC verification failed — chunk has been tampered with or the wrong key was used.

CorruptedFileError

File is corrupted — cannot be read or decrypted.

CorruptedMetadataError

Sidecar metadata is corrupted or unreadable.

EncryptionKeyMissingError

Encryption was requested but no key could be resolved.

FileNotFoundError

File/object not found at the given key.

InvalidHeaderError

The encrypted file header is invalid or from an unsupported version.

InvalidKeyError

The storage key contains invalid characters or structure.

StorageError

Typed error hierarchy for storage operations.

WriteError

A write operation failed (disk full, permission denied, etc.).