External Storage¶

external_storage ¶

External payload storage contracts for large Durable Workflow payloads.

ExternalPayloadIntegrityError ¶

Bases: ValueError

Raised when fetched external payload bytes do not match their reference.

ExternalStorageDriver ¶

Bases: Protocol

Protocol implemented by pluggable external payload storage drivers.

put ¶

put(data, *, sha256, codec)

Persist data and return a stable URI for later fetches.

get ¶

get(uri)

Fetch previously persisted payload bytes.

delete ¶

delete(uri)

Delete previously persisted payload bytes when retention removes a run.

ExternalPayloadStoragePolicy `dataclass` ¶

ExternalPayloadStoragePolicy(enabled, driver=None, threshold_bytes=None, config=dict(), reference=None, prefix='', mode=None, status=None, integrity_required=True)

Normalized external payload storage policy from server or Cloud APIs.

from_dict `classmethod` ¶

from_dict(data)

Parse a server namespace or Cloud organization storage policy.

ExternalPayloadReference `dataclass` ¶

ExternalPayloadReference(uri, sha256, size_bytes, codec, expires_at=None, schema=EXTERNAL_PAYLOAD_REFERENCE_SCHEMA)

Stable wire envelope for a payload stored outside workflow history.

ExternalPayloadCache ¶

ExternalPayloadCache(*, max_entries=128, max_bytes=16 * 1024 * 1024)

Bounded cache for verified external payload bytes during replay.

Cache entries are keyed by the complete reference identity. Bytes are inserted only by :func:fetch_external_payload after size and sha256 verification has succeeded, so cache hits preserve the same integrity contract as a fresh driver fetch.

discard ¶

discard(reference)

Remove verified bytes for reference after external retention cleanup.

LocalFilesystemExternalStorage ¶

LocalFilesystemExternalStorage(root)

Dependency-free external storage driver for development and tests.

S3ExternalStorage ¶

S3ExternalStorage(client, *, bucket, prefix='')

External storage driver backed by a boto3-compatible S3 client.

The SDK does not depend on boto3. Applications that need S3 pass an already-configured client exposing put_object, get_object, and delete_object.

GCSExternalStorage ¶

GCSExternalStorage(client, *, bucket, prefix='')

External storage driver backed by a google-cloud-storage client.

The SDK does not depend on google-cloud-storage. Applications pass a configured client exposing bucket(name).blob(key).

AzureBlobExternalStorage ¶

AzureBlobExternalStorage(container_client, *, container, prefix='')

External storage driver backed by an azure-storage-blob container client.

The SDK does not depend on azure-storage-blob. Applications pass a configured container client exposing upload_blob, download_blob, and delete_blob.

external_storage_driver_from_policy ¶

external_storage_driver_from_policy(policy, *, s3_client=None, gcs_client=None, azure_container_client=None, local_root=None)

Build an SDK storage driver from a server or Cloud policy payload.

Provider SDK clients remain application-owned. Pass the already-configured S3/GCS/Azure client that matches the policy returned by the control plane.

store_external_payload ¶

store_external_payload(driver, data, *, codec, expires_at=None)

Store encoded payload bytes and return their reference envelope.

fetch_external_payload ¶

fetch_external_payload(driver, reference, *, cache=None)

Fetch payload bytes and verify size/hash before replay or decode.

delete_external_payload ¶

delete_external_payload(driver, reference, *, cache=None)

Delete referenced payload bytes and evict any verified replay cache entry.