StorageBackend class abstract interface

Platform-agnostic object storage interface.

Every backend in cellar (local filesystem, IndexedDB, plus the Encrypted and Chunked decorators) implements this interface. Cellar orchestrates one or more backends; backends themselves are flat key/value stores that know nothing about partitions or scoping.

All keys are /-separated paths (e.g. "user/u1/photos/sunset"). Each segment must match [a-zA-Z0-9][a-zA-Z0-9._-]*. No path traversal (. or ..), no leading or trailing /, no consecutive //, no null bytes, no characters unsafe on Windows (\ : * ? " < > |). See validateKey for the full rules.

Stream-first: readStream and writeStream are the primary paths; read and write are convenience wrappers that buffer internally for small files.

Cross-backend contract

Every method here MUST be implementable by every backend cellar supports. If a feature can't honor that contract on every backend, it doesn't belong on this interface — push it onto the concrete backend or onto a decorator — never onto this interface.

When non-Dart code needs to consume stored bytes (FFI, OS file pickers, browser APIs taking a URL, native plugins taking a File), use materialize. It returns a platform-local handle — file path on native, Blob URL on web — and works on every backend.

Concurrency

Backends do NOT provide internal locking. Concurrent writes to the same key may corrupt the object. The caller is responsible for serializing writes to the same key (e.g. via a mutex or queue). Reads are safe to perform concurrently with other reads but not with writes.

Method surface (13 methods)

write / writeStream    — store bytes at a key
read / readStream      — retrieve bytes by key
readRange              — partial read (byte range)
head / exists          — metadata / presence without body
delete / deletePrefix  — remove by key or prefix
list                   — enumerate keys under prefix
copy                   — duplicate from one key to another
updateMetadata         — change content-type / metadata in place
materialize            — platform-local handle for non-Dart code

Implementations shipped with cellar:

  • FileSystemBackend — dart:io filesystem (native)
  • IndexedDbBackend — IndexedDB (web)
  • EncryptedBackend — transparent encryption decorator
  • ChunkedBackend — chunk-and-manifest decorator
Implementers

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

copy(String sourceKey, String destKey) → Future<void>
Copy an object, including its metadata.
delete(String key) → Future<void>
Delete a single object.
deletePrefix(String prefix) → Future<void>
Delete every object whose key starts with prefix (batch delete).
dispose() → Future<void>
Release the resources this backend itself constructed (database connections, HTTP clients). Idempotent — safe to call twice. Every method except dispose throws StateError afterwards.
exists(String key) → Future<bool>
Check if a key exists. Convenience for (await head(key)) != null.
Get object metadata without reading the body (HeadObject).
list(String prefix) → Future<List<ObjectInfo>>
List every object whose key starts with prefix, with full metadata.
materialize(String key, {bool decrypt = true, bool exclusive = false}) → Future<MaterializedFile>
Make a stored object available as a platform-local accessible resource.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
read(String key) → Future<Uint8List>
Read entire contents as bytes. Convenience wrapper over readStream.
readRange(String key, {required int start, required int length}) → Future<Uint8List>
Read a byte range.
readStream(String key) → Stream<List<int>>
Read as a byte stream. Primary read path.
toString() → String
A string representation of this object.
inherited
updateMetadata(String key, {String? contentType, Map<String, String> metadata = const {}}) → Future<void>
Update metadata for an existing object without touching its bytes.
write(String key, Uint8List bytes, [WriteOptions options = const WriteOptions()]) → Future<void>
Write bytes. Convenience wrapper over writeStream.
writeStream(String key, Stream<List<int>> byteStream, [WriteOptions options = const WriteOptions()]) → Future<void>
Write a byte stream with optional write options.

Operators

operator ==(Object other) → bool
The equality operator.
inherited