EncryptedBackend class

Transparent encryption decorator for StorageBackend.

Wraps any backend. Per-write encryption decisions come from WriteOptions:

  • encrypt: true → encrypt (fails if no key resolves)
  • encrypt: false → plaintext passthrough
  • encrypt: null → fall back to encryptByDefault

The decorator never inspects the key string to decide encryption — the caller is in charge.

Read behavior

Reads auto-detect encrypted bytes by checking the magic header. No WriteOptions needed at read time; the file format is self-describing.

Streaming

Write and read paths are truly streaming. Memory is O(chunkSize), not O(fileSize). Safe for arbitrarily large files.

Implemented types
Mixed-in types

Constructors

EncryptedBackend({required StorageBackend inner, required FileEncryptor encryptor, EncryptionKeyResolver? keyResolver, StorageBackend? decryptCache, bool encryptByDefault = true})
Wrap inner with transparent encryption via encryptor, resolving per-object keys through keyResolver (or explicit per-write keys).

Properties

disposeLabel → String
Short class name used in the post-dispose error, e.g. 'FileSystemBackend'.
no setteroverride
encryptByDefault → bool
Default encryption policy when WriteOptions.encrypt is null.
final
hashCode → int
The hash code for this object.
no setterinherited
isDisposed → bool
True once markDisposed has run.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

checkNotDisposed() → void
Throws StateError when this object has been disposed. Call as the first statement of every public method.
inherited
copy(String sourceKey, String destKey) → Future<void>
Copy an object, including its metadata.
override
delete(String key) → Future<void>
Delete a single object.
override
deletePrefix(String prefix) → Future<void>
Delete every object whose key starts with prefix (batch delete).
override
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.
override
exists(String key) → Future<bool>
Check if a key exists. Convenience for (await head(key)) != null.
override
Get object metadata without reading the body (HeadObject).
override
list(String prefix) → Future<List<ObjectInfo>>
Lists with PLAINTEXT sizes where the sidecar carries them.
override
markDisposed() → void
Record disposal. Idempotent.
inherited
materialize(String key, {bool decrypt = true, bool exclusive = false}) → Future<MaterializedFile>
Make a stored object available as a platform-local accessible resource.
override
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.
override
readRange(String key, {required int start, required int length}) → Future<Uint8List>
Read a byte range.
override
readStream(String key) → Stream<List<int>>
Read as a byte stream. Primary read path.
override
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.
override
write(String key, Uint8List bytes, [WriteOptions options = const WriteOptions()]) → Future<void>
Write bytes. Convenience wrapper over writeStream.
override
writeStream(String key, Stream<List<int>> byteStream, [WriteOptions options = const WriteOptions()]) → Future<void>
Write a byte stream with optional write options.
override

Operators

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

Constants

decryptTempMarker → const String
Reserved marker for one-shot plaintext temps written by materialize. Keys containing this marker are hidden from list and swept on the first materialize after a crash — do not use it in your own key names (same reservation idea as ChunkedBackend's __manifest suffix).