Serving Files over HTTP with Blobby

Learn It

About the Application

Blobby is a demonstration file server showing the basic CRUD operations of the wasmcloud:blobstore contract. By connecting it to the HTTP Server capability, the application can receive and serve files over the web using GET, POST, and DELETE requests. Since wasmCloud works on any platform, this file server could be on a local Linux box, a Raspberry Pi, a MacBook, in an AWS/Azure/GCP virtual machine, or anywhere else!

Architecture and Design

This application consists of a single actor bound to the HTTP Server and Blobstore capabilities. It is designed be called via HTTP to upload, get, modify, and delete files.

Contracts

Actor	Contract	Provider Implementation
Blobby	wasmcloud:httpserver	HTTP Server Provider
Blobby	wasmcloud:blobstore	Blobstore-FS Provider

Source Code

The code for this actor can be found in the wasmCloud examples repository.

Run It

Prerequisites

You can run this application on the Cosmonic platform or locally with wasmCloud. The components are the same either way. The only thing you need is a reference to an actor which has been uploaded to a publicly accessible OCI registry. If you're deploying the reference example, you can use wasmcloud.azurecr.io/blobby:0.2.0. If you built your own actor, follow the steps in the Deploying your Application documentation and substitute your own OCI reference in the remaining steps of this guide.

Is this OCI reference public?

You can always check if an OCI reference is publicly accessible by inspecting its claims. You can also see what capabilities the actor declares, so you know exactly what the actor is allowed to do.

cosmo inspect wasmcloud.azurecr.io/blobby:0.2.0

Starting the hosts

For this example, we're going to demonstrate the power of wasmCloud by running two hosts: one managed by Cosmonic, and the other on your local system.

Starting a managed host

Navigate to Cosmonic, and click Launch if you haven't already signed in. Ensure that you have at least one host on your infrastructure view; if you don't already have a host, you can use the Launch Host button:

Starting a local host

Blobby is compatible with many different blobstores. In this example, we'll use the local filesystem as the storage, so we'll start a local wasmCloud host using cosmo. Simply run cosmo up (you'll be prompted to log in if you haven't already). A few seconds later, you'll see a second host join your constellation. Since this host isn't managed by Cosmonic, you'll notice the lack of an icon in the upper-right. Note which host name is associated with your managed host.

Starting the actor

Navigate to the Logic View and use the toolbar on the left to Launch an Actor. Enter your actor reference in the OCI reference field (e.g. wasmcloud.azurecr.io/blobby:0.2.0, if using the reference example) and then select Launch Actor.

You'll see your actor on the canvas in just a few seconds.

Starting the capability providers

Next, we'll launch the HTTP Server (Wormhole) and Blobstore-FS capability providers, one at a time. Use the Launch Provider button on the left toolbar to bring up the modal, then enter the corresponding OCI reference for each provider. Keep the link name as default for each. Start the HTTP Server on the Cosmonic-managed host, and the Blobstore-FS provider on your local host.

Provider	OCI reference	Host
HTTP Client	cosmonic.azurecr.io/httpserver_wormhole:0.5.3	Cosmonic-managed
Blobstore-FS	wasmcloud.azurecr.io/blobstore_fs:0.3.1	Local

To start a provider on a specific host, you can either select the host name explicitly (if you remember which is managed and which is local from the previous steps), or you can click Find Host and filter by labels. For example, we can filter by stargate=true, to find the local host:

When you click the Find Hosts button, the appropriate host should appear in the dropdown. Once you've started both providers, your canvas should look something like this:

Linking the actor to capabilities

Next we'll link the Blobby actor to the two capability providers. Simply drag from each of the bubbles next to the contract names on the actor to the corresponding provider. This will open a modal, where you can define link values (runtime configuration) between the actor and provider. The HTTP Server doesn't need any configuration. However, for the Blobstore-FS provider, we will specify the ROOT of the filesystem to be /tmp. Specify the link values using the table below. Make sure you click the Add button to set the value before you click Create Link.

Contract	Key	Value
wasmcloud:httpserver	N/A (leave empty)	N/A (leave empty)
wasmcloud:blobstore	ROOT	/tmp

Your configured application should look something like this:

Accessing the application

To access our app in the browser, we'll need to create a wormhole, which exposes the application over an HTTP endpoint. Use the Create Wormhole button on the left toolbar and select your Blobby actor. If this is your only actor on the canvas, Cosmonic automatically selects this for you. For now, this wormhole should be created without authentication so you can load it in a browser tab, rather than providing an authorization bearer token.

Once the wormhole is created, you can click the wormhole on the canvas to select it, which will open a side panel. Click Access your Wormhole to open your wormhole in another tab. You'll get an error page that states Failed to process request, since we haven't added any files to the server yet!

Wormhole Traffic

As soon as you've accessed your wormhole, you'll see live, directed traffic lines on your canvas, indicating traffic flowing in your constellation.

Interacting with the Blobstore

Adding our first file

Let's upload a file to the blobstore using blobby. First, let's record our wormhole URL, since we'll be referencing it a few times:

# replace me with your wormhole URL
export WORMHOLE_URL=https://foo-bar-1234.cosmonic.app

Now let's create a simple file:

echo 'Hello there!' > myfile.txt

And then upload it over HTTP:

curl -H 'Content-Type: text/plain' -v $WORMHOLE_URL/myfile.txt --data-binary @myfile.txt

Now we should be able to retrieve the file. We could use curl again, but since this is HTTP, let's have the browser do it! Simply navigate to $WORMHOLE_URL/myfile.txt, and you should see the contents of the file rendered in your browser.

Modifying a file

Updating the contents of a file is as simple as issuing another POST request:

echo 'General Kenobi!' >> myfile.txt
curl -H 'Content-Type: text/plain' -v $WORMHOLE_URL/myfile.txt --data-binary @myfile.txt

Refresh the browser tab containing your file path, and you should see the updated text.

(Optional) Inspecting the filesystem

The wormhole is connected to Blobby, which then passes the bytes to the Blobstore-FS capability provider on your local host. That means we should also be able to view the file locally. The Blobstore-FS provider stores files separated by actor ID, so let's get that information first. Select Blobby on the canvas, which will open a side panel with more information. From there, click the button next to the Key field to copy the actor's ID to your clipboard:

The file structure used by the provider is [ROOT]/[ACTOR_ID]/[LINK_NAME]. Let's record those values:

# replace me with your actor ID
export ROOT=/tmp
export ACTOR_ID=MBY3COMRDLQYTX2AUTNB5D2WYAH5TUKNIMELDSQ5BUFZVV7CBUUIKEDR
export LINK_NAME=default

And now we can inspect the internals of the blobstore:

ls -l $ROOT/$ACTOR_ID/$LINK_NAME

You should see your myfile.txt there. Let's print its contents:

cat $ROOT/$ACTOR_ID/$LINK_NAME/myfile.txt

Hello there!
General Kenobi!

Deleting a file

Likewise, deleting files is just another request:

curl -X DELETE -v $WORMHOLE_URL/myfile.txt

Of course, now if you try to access the file, you'll get an error once again.

Summary

That's it! To recap, you: started an Blobby actor, linked it to the HTTP Server (running on Cosmonic) and Blobstore (running locally) capabilities, and created a wormhole to expose your application to the internet. You then issued HTTP requests to store and retrieve files from the filesystem.