Animal Image Downloader
- Learn It
- Run It
About the Application
The animal image downloader is an example application that illustrates how to interact with NATS and connect multiple capabilities to a single actor. The application:
- Accepts requests over NATS
- Downloads a random image of an animal via HTTP
- Saves the image to a blobstore
In this example, we'll be using the local filesystem for our blob store, rather than remote object storage.
Architecture and Design
This application consists of a single actor, the animal image downloader. It is bound to the NATS messaging provider, the HTTP client provider, and the Blobstore-FS provider. Upon receiving a request, the actor downloads a random image of the selected animal to the local filesystem.
Contracts
| Actor | Contract | Provider Implementation |
|---|---|---|
| Animal Image Downloader | wasmcloud:messaging | NATS Messaging Provider |
| Animal Image Downloader | wasmcloud:httpclient | HTTP Client Provider |
| Animal Image Downloader | wasmcloud:blobstore | Blobstore-FS Provider |
Source Code
The code for this actor can be found in the wasmCloud examples repository.
The code for the capability providers can be found in the wasmCloud capability providers repository.
Prerequisites
To interact with this application, you will need the nats CLI, which you can install by following
these instructions.
To run this application, you will need 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/animal-image-downloader:0.1.2. 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.
Hint: 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/animal-image-downloader:0.1.2
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
Now 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
Let's populate the hosts. 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/animal-image-downloader:0.1.2, if using the reference example).
Feel free to select either host to start the actor, 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 NATS Messaging, HTTP Client, 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. You can launch the first two providers on either host, but make sure you select your
local host's name for the Blobstore-FS provider.
| Provider | OCI reference | Host |
|---|---|---|
| HTTP Client | wasmcloud.azurecr.io/httpclient:0.7.0 | Cosmonic-managed |
| NATS Messaging | wasmcloud.azurecr.io/nats_messaging:0.17.0 | Cosmonic-managed |
| Blobstore-FS | wasmcloud.azurecr.io/blobstore_fs:0.3.1 | Local |
Once you're done, your canvas should look something like this (notice the icon on the Blobstore-FS provider is different, indicating it's running on your local host):
Linking the actor to capabilities
Next we'll link your actor to the three 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. Specify these values for the NATS messaging and Blobstore-FS providers using the table below. Make sure you click the Add button to set the value before you click Create Link.
| Contract | Key | Value |
|---|---|---|
wasmcloud:httpclient | N/A (leave empty) | N/A (leave empty) |
wasmcloud:messaging | SUBSCRIPTION | wasmcloud.animal.* |
wasmcloud:blobstore | ROOT | /tmp |
Once all three providers are linked, your application should look like this:
Before accessing the application, let's take a moment and notice what we did. Despite the Blobstore-FS provider running on a different machine than the rest of the application, you don't need to do anything special. wasmCloud applications work seamlessly across hosts, regardless of the physical location, operating system, or architecture of the device.
Accessing the application
Unlike some of our other examples, this application isn't available over HTTP. Instead, we're going
to use the nats CLI tool. First, let's double-check that we can connect to our local NATS server,
which we started with cosmo earlier:
nats rtt -s 127.0.0.1:4223
You should get back a response immediately. Now we'll communicate with our application. The link we
established between the actor and NATS messaging provider set up a subscription on the topic prefix
wasmcloud.animal.*. Let's send a request on a topic that matches (we'll send an empty body):
nats req -s 127.0.0.1:4223 wasmcloud.animal.dog ''
After a moment, you should get a response back:
Enjoy your animal picture 🐶🐱
If we navigate to the directory we configured with the Blobstore-FS provider, we should see a file
at /tmp/[ACTOR_ID]/animalpics/animal.png. Open the image on your computer, and you should see a
picture of a dog! If you prefer cats, give this a try:
If you're using the reference actor, the ID is
MDBIB35BEIFT552CBSJXY3TOQYGIDAWZMMX4TKD5AGMRSJUDYSDCDWDF, and you can copy this path:
/tmp/MDBIB35BEIFT552CBSJXY3TOQYGIDAWZMMX4TKD5AGMRSJUDYSDCDWDF/animalpics/animal.png
nats req -s 127.0.0.1:4223 wasmcloud.animal.cat ''
The contents of /tmp/[ACTOR_ID]/animalpics/animal.png image should now be different. Can't decide
between dogs and cats? We have you covered:
nats req -s 127.0.0.1:4223 wasmcloud.animal.idk ''
Check out /tmp/[ACTOR_ID]/animalpics/animal.png one more time for an Easter egg 😉
Summary
That's it! To recap, you: started an animal image downloader actor, linked it to a NATS messaging provider (for inbound messages), HTTP Client (for outbound connections), and Blobstore-FS (running locally) capabilities, and downloaded images to your local filesystem by publishing requests over NATS.