StorageScope class

Tenant-scoping wrapper around a StorageBackend.

Cellar builds one StorageScope per partition and routes calls through it. The scope's only job: prepend keyPrefix to every key before delegating to the backend, and validate the key.

// Unscoped — keys pass straight through:
final scope = StorageScope(backend);
scope.write('photos/sunset', bytes); // backend key: "photos/sunset"

// Scoped — every key gets the tenant prefix:
final scope = StorageScope(backend, keyPrefix: 'user/u1');
scope.write('photos/sunset', bytes); // backend key: "user/u1/photos/sunset"

// Two scopes, two tenants, one shared backend:
final alice = StorageScope(backend, keyPrefix: 'user/alice');
final bob   = StorageScope(backend, keyPrefix: 'user/bob');

Key structure

The scope does not impose any structure on keys past the prefix. Paths are /-separated strings; apps choose their own conventions.

Encryption

Encryption is per-write via WriteOptions. The scope passes WriteOptions through to the backend unchanged; encryption is applied (or not) by an EncryptedBackend decorator further down the stack.

Constructors

StorageScope(StorageBackend _backend, {String? keyPrefix})
Create a scoped view over backend.

Properties

backend → StorageBackend
The underlying backend (for advanced or raw operations that need to bypass the prefix layer).
no setter
hashCode → int
The hash code for this object.
no setterinherited
keyPrefix → String?
Optional tenant prefix applied to every key. Null = no prefix.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

copy(String sourcePath, String destPath) → Future<void>
Copy within this scope, metadata included.
copyToScope(String sourcePath, StorageScope dest, String destPath) → Future<void>
Copy into another scope — the backends must share a substrate (same underlying store) for the raw copy to land.
delete(String path) → Future<void>
Delete the scoped key. No-op when absent.
deletePrefix(String pathPrefix) → Future<void>
Delete every scoped key under pathPrefix (raw string prefix).
exists(String path) → Future<bool>
Whether the scoped key exists.
fileSize(String path) → Future<int>
File size in bytes (0 if not found).
Metadata without the body; null when the scoped key is absent.
key(String path) → String
Build the prefixed key for a user-supplied path. No-op when keyPrefix is null.
list(String pathPrefix) → Future<List<ObjectInfo>>
List every scoped key under pathPrefix (raw string prefix).
listKeys(String pathPrefix) → Future<List<String>>
Like list but returns just the keys.
materialize(String path, {bool decrypt = true, bool exclusive = false}) → Future<MaterializedFile>
Materialize a stored object as a platform-local handle.
move(String sourcePath, String destPath) → Future<void>
Copy then delete the source. Not atomic across the two steps.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
prefix(String path) → String
Build the prefixed prefix for list/delete operations. Same logic as key — exposed separately for readability at call sites.
read(String path) → Future<Uint8List>
Read the full body at the scoped key. Throws FileNotFoundError when absent.
readRange(String path, {required int start, required int length}) → Future<Uint8List>
Read length bytes starting at start from the scoped key.
readStream(String path) → Stream<List<int>>
Streaming variant of read.
toString() → String
A string representation of this object.
inherited
totalSize(String pathPrefix) → Future<int>
Total size in bytes of all files under a path prefix.
updateMetadata(String path, {String? contentType, Map<String, String> metadata = const {}}) → Future<void>
Replace contentType + metadata at the scoped key, bytes untouched.
write(String path, Uint8List bytes, [WriteOptions options = const WriteOptions()]) → Future<void>
Validate path, apply the prefix, write bytes at the scoped key.
writeStream(String path, Stream<List<int>> byteStream, [WriteOptions options = const WriteOptions()]) → Future<void>
Streaming variant of write — constant memory for any size.

Operators

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