0:00 Introduction

0:00 Hello. And welcome back to the complete guide to Spin. Today, we're taking a look at a new feature of Spin, which is key value storage. This is an awesome new feature that opens up the ability to save and retrieve state with a very simple API and our WebAssembly context. One of the classic examples out there online for WebAssembly is writing your own URL shortener. Why? Well, because WebAssembly has very fast startup times, typically in microseconds. So for URL shortener, this makes a lot of sense. As requests come in, we can actually send that redirect response faster than traditional

0:18 Applying Key-Value Stores to a URL Shortener

0:38 serverless workflows. But what if we want to offer dynamic charted URLs? And by dynamic I mean not hard coded and the code itself like most of the examples online show including the one in the Fermian documentation. Well we can use the spin key value store using HTTP verbs such as put to store your short URLs. Use the get verb, find and redirect where possible and even support delete for when we want to remove URLs that no longer should be shortened. This allows us to provide an HTTP API to add, remove and fetch our URLs which is pretty neat. Well, let's take a

1:17 look using Fermion one point o, which launched just last week. Let's have some fun. Okay. What do we have? Well, we're in another directory called spin dash k v. In this directory, we have a brand new spin project. Well, almost brand new. I've written some code, which uses a rust SDK. We can tell that because we have a cargo dot toml. We also have a spin.toml, which we've seen a few of before. However, this one has one unique change. If we scroll down to here, you'll see that under the component configuration block, we have key value stores. And we have

1:24 Project Setup and Spin Configuration (`spin.toml`)

1:52 a list of the value default. At the time of recording this video and for spin one point o, the only value we can use in this list is the default key value store. However, in the future, more options may become available. Stay tuned. So we have this default value for now and we have our spend project. Now you may be wondering, where do all the key values live when we run spend locally on our machine? And that is a great question. Thank you for asking. Inside the dot spin directory, you will find a dot DB file.

2:11 Code Walkthrough: Implementing the Key-Value API

2:27 This is a SQLite database, which is used by Spin to store all of your configuration or at least whatever you decide to store in the key value store. So let's pop open lib dot r s. And here, you'll see that we pull in the key value create, which has a store and an error type. These are not that important right now and we will come back to them shortly. If we scroll down the line 13, you'll see that we ask the store to give us the default key value store. This does have the potential to fail and

3:01 if you want to capture the error and match on it yourself, well, feel free. For today's example, we're just going to use the question mark and let it work it out itself. And because our handler expects a result, it's okay for it just to throw and propagate the error to the runtime. Next, we grab the short URL from the request URI, where the short URI is just the path that being slash hello slash a b c slash hello a b c, whatever. Next, we do a match on the method. Now we're going to rely on HTTP verbs

3:36 for this very simple API. That being when we get a GET request on a path, we're going to look up that path and the key value store for a redirect URL. If it doesn't exist, we'll return a http not found slash four zero four. And if it is, we're gonna return a temporary redirect, a three zero seven with the URL. We also accept two more HTTP verbs as part of this API. If we get a put request, then we'll actually attempt to store the body, the redirect URL, and the key value store. I'm not doing

4:12 a lot of validation or verification of that value, but we do check that it doesn't exist in the key value store first. If there's already a value, we'd not allow it to be replaced. It must be explicitly deleted first and then recreated. So where the value already exists or where the key already exists in the store, we return an HTTP conflict, a four zero nine. Lastly, HTTP delete and because delete doesn't really do anything different if the key exists or doesn't, we're just gonna return an HTTP okay. Again, if you want to handle a this

4:46 key doesn't exist when you delete, feel free to match instead of propagating that error up the stack. Lastly or very lastly, finally lastly, if we get an issue to be verb that isn't supported by our API, we return method not allowed. Once we've handled that, we have access to a issue to be status that we wish to return to the requester. And if we have a temporary redirect, we will provide the location header. Otherwise, we pass the status back with a body of none. Nice and simple API. Let's see it in action. So let's run

5:16 Demonstration Setup

5:19 a spin build and a spin up. Now we can open another terminal where we can run some HTTP requests against our API. As you can see, our application runs on local host port 3,000. Now I'm not going to execute arbitrary curl commands because honestly, it's twenty twenty three. Instead, we're gonna use HARL and I have a test dot HARL file. If you're not familiar with HARL, go to hARL dot dev and you'll find a very cool text based description HTTP testing framework. It also has really cool support for building assertions against the response too and whether that be string matches, regex, status

5:32 Introducing Hurl and the Test Scenario

5:58 codes, JSON, whatever. Where we see that we're sending a delete request or at least we're using the delete verb to local host 3,000 on the hello world path. The hello world path is going to be our short URL, which could potentially return a longer URL with a redirect. The delete as we've seen in the code always returns a 200, so we just assert by saying we expect an HTTP 200. We then run a GET request against the same path where we expect a four zero four because we just deleted any redirect that may already exist.

6:32 Next, we use a put verb to store a URL. Here, I'm using rockwoodishere.com. Not a real URL, but will suffice for today. We expect an HTTP two zero one and if we try the same request again, we have the same value or a different value, it doesn't matter because the path already exists within the key value store. We get a conflict and a four zero nine. So what we expect when we run a GET on Hello World is for us to get an HTTP temporary redirect, a three zero seven, where we could build an assertion that we

7:05 have a location header that equals the value restored with the PIP. Now we can run Hurl test and point it to our test Hurl file. And we can see that five requests were executed and we have some debug output here that shows we got a delete, a GET, a put, a put and a GET. And we can see that all of our assertions passed. If you want more information, you can add a dash b for verbosity, which will actually show you all of the response and we can see our location header is here. So this extension

7:41 Conclusion and Summary

7:41 of the URL shortener available on the fermion blog as an example of how to do it with their SDK can now be enriched. It can now enable dynamic API driven URLs that's stored in a key value store. So go check it out. It's very cool, simple interface that you can use in just one or two lines of code. Enjoy.