Skip to content

updating requirements on default label #1545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 14, 2025
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions content/wasm-functions/using-key-value-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,17 @@ enable_shortcodes = true
---

- [About the Fermyon Wasm Functions Key Value Store](#about-the-fermyon-wasm-functions-key-value-store)
- [Key Value Limitations and Considerations](#key-value-limitations-and-considerations)
- [Creating a New Spin Application](#creating-a-new-spin-application)
- [Grant Key Value Store Permission](#grant-key-value-store-permission)
- [Implementing the Spin Application](#implementing-the-spin-application)
- [Testing the Spin Application](#testing-the-spin-application)
- [Deploying to Fermyon Wasm Functions](#deploying-to-fermyon-wasm-functions)
- [Next Steps](#next-steps)

With Spin Key Value Store support in _Fermyon Wasm Functions_, you can persist non-relational data generated by your [Spin](https://spinframework.dev) application across application restarts and updates. _Fermyon Wasm Functions_ will provision and manage the key value store on your behalf, handling the heavy lifting for you. Spin Key Value Stores are isolated to a single application, and components cannot access the store unless explicitly granted permission. This capabilities-based security model ensures that only authorized components can interact with the data. To learn more about the Spin Key Value Store SDK, please visit the [API guide](https://spinframework.dev/v3/kv-store-api-guide).
With Spin key value store support in _Fermyon Wasm Functions_, you can persist non-relational data generated by your [Spin](https://spinframework.dev) application across application restarts and updates. _Fermyon Wasm Functions_ will provision and manage the key value store on your behalf, handling the heavy lifting for you. Spin key value stores are isolated to a single application, and components cannot access the store unless explicitly granted permission. This capabilities-based security model ensures that only authorized components can interact with the data. To learn more about the Spin key value store SDK, please visit the [API guide](https://spinframework.dev/v3/kv-store-api-guide).

As part of this tutorial, we will build a Spin application which leverages the Key Value Store provided by _Fermyon Wasm Functions_ for persistence. Once we have finished implementing the Spin app, we will run it locally using `spin up` for testing purposes, before we deploy it to _Fermyon Wasm Functions_ using the `spin aka deploy` command.
As part of this tutorial, we will build a Spin application which leverages the key value store provided by _Fermyon Wasm Functions_ for persistence. Once we have finished implementing the Spin app, we will run it locally using `spin up` for testing purposes, before we deploy it to _Fermyon Wasm Functions_ using the `spin aka deploy` command.

## About the Fermyon Wasm Functions Key Value Store

Expand Down Expand Up @@ -45,7 +46,9 @@ $ npm install

## Grant Key Value Store Permission

To enable a component in Spin to use a key value store, you need to [grant it the necessary permissions in the application's manifest](https://spinframework.dev/kv-store-api-guide#granting-key-value-store-permissions-to-components) (`spin.toml`) by adding a key-value store label. This both grants the component access to the key value store and signals _Fermyon Wasm Functions_ (FWF) to provision one for the application. In this tutorial, we’ll use the label "default", but you can choose any label that works best for you.
To enable a component in Spin to use a key-value store, you need to [grant it the necessary permissions in the application's manifest](https://spinframework.dev/kv-store-api-guide#granting-key-value-store-permissions-to-components) (`spin.toml`). To do this, add the label of the store to the component's `key_value_stores` in `spin.toml`.

In _Fermyon Wasm Functions_, the only label allowed is `"default"` which signals to the platform to automatically provision a Key Value store for your Spin application.

```toml
[component.hello-key-value-store]
Expand All @@ -58,8 +61,8 @@ key_value_stores = [ "default" ]

The `http-js` template generates a simple _Hello World_ example in `src/index.js`. As part of this section, we'll replace the existing code and use the HTTP router, provided by the template, to make our Spin application respond to the following HTTP request patterns:

- `GET /get/:key` for retrieving a value from Key Value Store using the key provided as `:key`
- `POST /set/:key` for storing a value provided as request payload using `:key` in Key Value Store
- `GET /get/:key` for retrieving a value from key value store using the key provided as `:key`
- `POST /set/:key` for storing a value provided as request payload using `:key` in key value store

Let's start by bringing necessary capabilities from the `@fermyon/spin-sdk` package into scope and laying out the routes:

Expand All @@ -84,7 +87,7 @@ addEventListener('fetch', async (event) => {
});
```

Incoming `GET` requests at `/get/:key` will be handled by the `handleGetValue` function. As part of the function, we use the Key Value Store APIs provided by the Spin SDK for JavaScript (`import Kv from '@fermyon/spin-sdk'`):
Incoming `GET` requests at `/get/:key` will be handled by the `handleGetValue` function. As part of the function, we use the key value store APIs provided by the Spin SDK for JavaScript (`import Kv from '@fermyon/spin-sdk'`):

```JavaScript
function handleGetValue(key) {
Expand All @@ -97,19 +100,19 @@ function handleGetValue(key) {
return new Response(null, { status: 404 });
}

// load JSON data at key from Key Value Store
// load JSON data at key from key value store
let found = store.getJson(key);

// Return an HTTP 200 with corresponding HTTP header and payload
// if something was found at position key in the Key Value Store
// if something was found at position key in the key value store
return new Response(
JSON.stringify(found),
{ status: 200, headers: { "content-type": "application/json" } }
);
}
```

Incoming `POST` requests at `/set/:key` will be handled by the `handleSetValue` function. After the request payload is validated, we use the Key Value Store APIs for persisting the data.
Incoming `POST` requests at `/set/:key` will be handled by the `handleSetValue` function. After the request payload is validated, we use the key value store APIs for persisting the data.

```JavaScript
function handleSetValue(key, requestBody) {
Expand Down Expand Up @@ -209,7 +212,7 @@ Move back to the first terminal instance and terminate your Spin application by

## Deploying to Fermyon Wasm Functions

_Fermyon Wasm Functions_ takes care of provisioning a Key Value Store for you. That said, all we have to do is deploying our Spin application using the `spin aka deploy` command:
_Fermyon Wasm Functions_ takes care of provisioning a key value store for you. That said, all we have to do is deploying our Spin application using the `spin aka deploy` command:

<!-- @selectiveCpy -->

Expand Down
Loading