Skip to main content

Module storage

bext_plugin_api

Module storage 

Source
Expand description

StorageClient capability trait and types for blob / object stores.

A StorageClientPlugin is the runtime side of an object store: get a key, put a key, delete a key, list keys under a prefix, and mint a presigned URL. Backends range from S3 / R2 / MinIO / B2 to local filesystem and in-memory stores for tests. The trait is narrow on purpose — anything that looks like “named blob in a flat keyspace” fits; anything richer (consistency tiers, object versioning beyond a single etag, multipart upload) stays backend-specific.

Design notes:

  • Payloads are Vec<u8>, not Bytes. Matches the rest of the crate, keeps the WASM ABI flat, and lets callers wrap in Bytes themselves when they want the cheap-clone semantics. Bytes-in-the-trait would pull bytes into every WASM guest, which is not worth the ergonomic win for a leaf crate.

  • list is paginated via StorageClientPlugin::list_page, not a BoxStream. Reasons: (1) keeps the trait synchronous, matching every other E1/E2 capability; (2) avoids dragging futures into a leaf crate that otherwise only depends on serde + serde_json; (3) mirrors how every real object store exposes list (S3 / R2 / GCS / Azure all hand out a continuation token). Callers who want a stream-shaped surface can build one on top in two lines.

  • Errors are a flat enum with four variants — NotFound, AccessDenied, QuotaExceeded, Backend(String) — because callers branch on the classification. A route that returns 404 on NotFound, 403 on AccessDenied, and 500 otherwise is a common pattern, and forcing callers to parse a stringly-typed error to implement it is a papercut we can avoid cheaply. Matches the shape of crate::session::SessionError.

  • The trait is sync-only, matching the rest of the plugin API. Native backends that need async I/O (aws-sdk-s3, etc.) drive their own runtime inside each method via tokio::runtime::Handle::block_on or a dedicated Runtime. WASM guests go through the host-function bridge.

Modules§

fuel
Fuel budgets for WASM storage plugin calls.

Structs§

Object
A single object as observed via StorageClientPlugin::list_page.
PutOpts
Options for StorageClientPlugin::put.

Enums§

PresignOp
Operation a presigned URL is minted for.
StorageError
Errors a storage backend can return.

Traits§

StorageClientPlugin
A plugin that owns a blob / object store.