Serving Files over HTTP with Blobby
- Learn It
- Run 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.
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.
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.
bash
bash
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!
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:
bash
bash
Now let's create a simple file:
bash
bash
And then upload it over HTTP:
bash
bash
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:
bash
bash
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:
bash
bash
And now we can inspect the internals of the blobstore:
bash
bash
You should see your myfile.txt there. Let's print its contents:
bash
bash
Deleting a file
Likewise, deleting files is just another request:
bash
bash
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.