aeat.adapters.outbound.storage._protocol module

StorageProvider Protocol - the v1 storage backend contract.

Concrete backends implement this Protocol behind adapters.outbound.storage.get_storage_provider(). The coordinator depends only on this public surface, the provider records ProviderObjectMetadata and ProviderProbeReport, and the typed adapters.outbound.storage.OutboundStorageError hierarchy; concrete backend classes remain private implementation details.

Bytes are the unit of payload. Encryption + classification + envelope handling happens above the provider layer (in the application sync coordinator) so providers receive opaque encrypted bytes, not plaintext domain data.

class StorageProvider(*args, **kwargs)

Bases: Protocol

Bytes-in / bytes-out per-namespace object store.

The protocol is selected by adapters.outbound.storage.get_storage_provider() from the configured adapters.outbound.storage.ProviderKind, but callers operate only on the protocol plus ProviderObjectMetadata and ProviderProbeReport boundary records.

Implementations must be safe to instantiate from settings without network IO. Backend setup, credential refresh, remote-folder creation, and filesystem root creation happen lazily on probe() or the first read/write operation.

Provider methods translate expected backend failures into the adapters.outbound.storage.OutboundStorageError hierarchy at this boundary. Native backend exceptions should not cross the Protocol surface except for programming errors.

put(namespace, object_key_hmac, payload, *, content_hash, label)

Write or overwrite an object; return its post-write metadata.

Parameters:

• namespace (str) – Destination namespace (substrate namespace name).

• object_key_hmac (str) – Stable HMAC of the object key. Provider surfaces it as part of the filename / Drive name so operator-visible listings carry the HMAC prefix.

• payload (bytes) – Bytes to write. Already encrypted at the application layer; providers do not decrypt or inspect.

• content_hash (str) – Cryptographic hash of payload for integrity round-tripping (adapters.outbound.storage.OutboundStorageIntegrityError raised on read if the stored hash diverges).

• label (str) – Human-readable suffix appended to the filename for operator orientation. Derived from the per-namespace label deriver registered at the application layer.

Return type:

ProviderObjectMetadata

Returns:

The newly-written object’s ProviderObjectMetadata.

get(namespace, object_key_hmac)

Read an object’s payload and metadata.

Parameters:

• namespace (str) – Source namespace to read from.

• object_key_hmac (str) – Stable HMAC identifying the object.

Return type:

tuple[bytes, ProviderObjectMetadata]

Returns:

A 2-tuple containing payload bytes and ProviderObjectMetadata.

delete(namespace, object_key_hmac)

Remove an object. Return True iff it existed before this call.

Parameters:

• namespace (str) – Namespace containing the object.

• object_key_hmac (str) – Stable HMAC identifying the object to remove.

Return type:

bool

Returns:

True if the object existed and was removed; False if it was absent.

iter_namespaces()

Yield every namespace the backend currently holds.

Includes operator-facing underscore-prefixed buckets such as _inbound, _workspace, _probe, _sync-state when they exist on the backend.

Return type:

Iterator[str]

iter_objects(namespace)

Yield every object in namespace. Order is backend-defined.

Parameters:

namespace (str) – Namespace to enumerate.

Return type:

Iterator[ProviderObjectMetadata]

Returns:

An iterator of ProviderObjectMetadata for each object.

probe(*, read_only=False)

Health-check the backend; return a structured report.

When read_only=False, performs provider-specific reachability checks plus a sentinel payload write/delete round-trip in the _probe/ namespace to verify write capability. When read_only=True, skips the sentinel payload round-trip but may still perform provider-specific root or service checks.

Parameters:

read_only (bool) – When True, skips the sentinel payload round-trip.

Return type:

ProviderProbeReport

Returns:

A ProviderProbeReport describing the backend’s state. Never raises on expected backend failures; failure modes surface via the report’s reachable / writable fields and detail string.