Blobstore

The blobstore capability allows your application component to store, retrieve, and manage data from various blobstores. This enables flexible, persistent data storage for large amounts of data. This capability is included as one of the open source wasmCloud interfaces and has the capability contract ID wasmcloud:blobstore.

Using this Capability

This capability can be used in your project by adding a dependency on the wasmcloud-interface-blobstore crate, and by adding wasmcloud:blobstore to the capabilities section in your application's wasmcloud.toml file.

Cargo.toml

toml
wasmcloud-interface-blobstore = "0.5.1"

toml
wasmcloud-interface-blobstore = "0.5.1"

wasmcloud.toml

toml
[actor]
capabilities = ["wasmcloud:blobstore"]

toml
[actor]
capabilities = ["wasmcloud:blobstore"]

Basic Operations

Operation	Input	Output
remove_objects	A RemoveObjectsRequest type that allows for deleting 1 or more objects from a container	An empty list if no errors occurred or a list of ItemResults that contain any errors that may have occurred
put_object	A PutObjectRequest containing the first chunk of data and other optional metadata about the object	PutObjectResponse containing the stream ID
get_object	GetObjectRequest	A GetObjectResponse type with the first chunk of data and indicators of whether or not more chunks should be fetched
put_chunk	PutChunkRequest	N/A

Example Usage

Upload object

rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_blobstore::{
    Blobstore, BlobstoreSender, Chunk, PutObjectRequest, PutObjectResponse,
};
async fn upload_bytes(ctx: &Context, image_bytes: &[u8]) -> RpcResult<PutObjectResponse> {
    BlobstoreSender::new()
        .put_object(
            ctx,
            &PutObjectRequest {
                chunk: Chunk {
                    container_id: "mycontainer".to_string(),
                    object_id: "myobjectname".to_string(),
                    bytes: image_bytes.to_vec(),
                    offset: 0,
                    is_last: true,
                },
                content_type: Some("image/png".to_string()),
                ..Default::default()
            },
        )
        .await
}

rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_blobstore::{
    Blobstore, BlobstoreSender, Chunk, PutObjectRequest, PutObjectResponse,
};
async fn upload_bytes(ctx: &Context, image_bytes: &[u8]) -> RpcResult<PutObjectResponse> {
    BlobstoreSender::new()
        .put_object(
            ctx,
            &PutObjectRequest {
                chunk: Chunk {
                    container_id: "mycontainer".to_string(),
                    object_id: "myobjectname".to_string(),
                    bytes: image_bytes.to_vec(),
                    offset: 0,
                    is_last: true,
                },
                content_type: Some("image/png".to_string()),
                ..Default::default()
            },
        )
        .await
}

Get object

rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_blobstore::{
    Blobstore, BlobstoreSender, GetObjectRequest, GetObjectResponse,
};
async fn get_bytes(ctx: &Context) -> RpcResult<GetObjectResponse> {
    let o = BlobstoreSender::new().get_object(ctx, &GetObjectRequest {
        object_id: "myobjectname".to_string(),
        container_id: "mycontainer".to_string(),
        range_start: Some(0),
        range_end: None,
    }).await
}

rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_blobstore::{
    Blobstore, BlobstoreSender, GetObjectRequest, GetObjectResponse,
};
async fn get_bytes(ctx: &Context) -> RpcResult<GetObjectResponse> {
    let o = BlobstoreSender::new().get_object(ctx, &GetObjectRequest {
        object_id: "myobjectname".to_string(),
        container_id: "mycontainer".to_string(),
        range_start: Some(0),
        range_end: None,
    }).await
}

Delete object

rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_blobstore::{
    Blobstore, BlobstoreSender, RemoveObjectsRequest,
};
async fn delete_object(ctx: &Context, object_id: &str) -> RpcResult<()> {
    let errors = BlobstoreSender::new()
        .remove_objects(
            ctx,
            &RemoveObjectsRequest {
                container_id: "mycontainer".to_string(),
                objects: vec![object_id.to_owned()],
            },
        )
        .await?;
    // Handle the errors here
    Ok(())
}

rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_blobstore::{
    Blobstore, BlobstoreSender, RemoveObjectsRequest,
};
async fn delete_object(ctx: &Context, object_id: &str) -> RpcResult<()> {
    let errors = BlobstoreSender::new()
        .remove_objects(
            ctx,
            &RemoveObjectsRequest {
                container_id: "mycontainer".to_string(),
                objects: vec![object_id.to_owned()],
            },
        )
        .await?;
    // Handle the errors here
    Ok(())
}

Advanced operations

Operation	Input	Output
container_exists	A String representing a container ID to check for	bool
create_container	A String representing a container ID	ContainerMetadata
get_container_info	A String representing a container ID	ContainerMetadata
list_containers	N/A	A list of ContainerMetadata
remove_containers	A list of Strings representing container IDs	A list of ItemResults that contain any errors that may have occurred
object_exists	ContainerObject	bool
get_object_info	ContainerObject	ObjectMetadata
list_objects	ListObjectsRequest	A ListObjectResponse type that contains the list of objects and an optional continuation token for paginated results

Choosing an Implementation

After you've written your component to use the blobstore capability, you will choose an implementation, or capability provider, at runtime to connect to a real blobstore. Depending on what your application requirements are, you could choose to use an S3 capable store or a filesystem.

Available Implementations

Below you can find the different implementations of blobstores that you can use out-of-the-box. If the options don't meet your needs, you can always implement the wasmcloud:blobstore interface with your own implementation. Please feel free to reach out to us on Discord so we can collaborate with you on a solution.

📄️ Local Filesystem

Connect to a local filesystem via a blobstore

📄️ Blob Store (S3)

Consume S3-compliant services from an actor