KV Store: Read and Write at the Edge

/// Interface to Fastly's [Compute KV Store].
///
/// For a high-level introduction to this feature, see this [blog post].
///
/// [Compute KV Store]: https://www.fastly.com/documentation/guides/concepts/edge-state/data-stores/#kv-stores (opens in a new window)
/// [blog post]: https://www.fastly.com/blog/introducing-the-compute-edge-kv-store-global-persistent-storage-for-compute-functions (opens in a new window)
interface kv-store {
  use types.{error, open-error};
  use http-body.{body};

  /// A KV Store.
  resource store {
    /// Opens the KV Store with the given name.
    open: static func(name: string) -> result<store, open-error>;

    /// Looks up a value in the KV Store.
    ///
    /// Returns `ok(some(v))` with the value `v` that was found, `ok(none)` if no value was
    /// found, or `err(e)` indicating the error `e` occurred.
    ///
    /// This function waits until the operation completes.
    lookup: func(
      key: string,
    ) -> result<option<entry>, kv-error>;

    /// Look up a value in the KV Store asynchronously.
    ///
    /// This function initiates an async lookup of a value in the KV Store. Use
    /// `await-lookup` to finish the lookup.
    lookup-async: func(
      key: string,
    ) -> result<pending-lookup, error>;

    /// Inserts a value into the KV Store.
    ///
    /// If the KV Store already contains a value for this key, the `mode` field
    /// of the `options` argument specifies how the existing value is handled.
    ///
    /// This function waits until the operation completes.
    insert: func(
      key: string,
      body: body,
      options: insert-options,
    ) -> result<_, kv-error>;

    /// Insert a value into the KV Store asynchronously.
    ///
    /// If the KV Store already contains a value for this key, the `mode` field
    /// of the `options` argument specifies how the existing value is handled.
    ///
    /// This function initiates an async insert of a value in the KV Store. Use
    /// `await-insert` to finish the lookup.
    insert-async: func(
      key: string,
      body: body,
      options: insert-options,
    ) -> result<pending-insert, error>;

    /// Deletes a value in the KV Store.
    ///
    /// Returns `ok(true)` if a value was successfully deleted, `ok(false)` if no value was
    /// found, or `err(e)` indicating the error `e` occurred.
    ///
    /// This function waits until the operation completes.
    delete: func(
      key: string,
    ) -> result<bool, kv-error>;

    /// Delete of a value in the KV Store.
    ///
    /// This function initiates an async delete of a value in the KV Store. Use
    /// `await-delete` to finish the lookup.
    delete-async: func(
      key: string,
    ) -> result<pending-delete, error>;

    /// Lists keys in the KV Store.
    ///
    /// Returns `ok(b)` with the body `b` on success, or `err(e)` indicating the error `e`
    /// occurred.
    ///
    /// This function waits until the operation completes.
    %list: func(
      options: list-options,
    ) -> result<body, kv-error>;

    /// List of keys in the KV Store.
    ///
    /// This function initiates an async list value in the KV Store. Use
    /// `await-list` to finish the lookup.
    list-async: func(
      options: list-options,
    ) -> result<pending-list, error>;
  }

  ...
}

/// A value indicating the status of a KV store operation.
variant kv-error {
  /// KV store cannot or will not process the request due to something that is perceived to be a
  /// client error.
  ///
  /// This will map to the api's 400 codes.
  bad-request,
  /// KV store cannot fulfill the request, as defined by the client's prerequisites, for example
  /// `if-generation-match`.
  ///
  /// This will map to the api's 412 codes.
  precondition-failed,
  /// The size limit for a KV store key was exceeded.
  ///
  /// This will map to the api's 413 codes.
  payload-too-large,
  /// The system encountered an unexpected internal error.
  ///
  /// This will map to all remaining http error codes.
  internal-error,
  /// Too many requests have been made to the KV store.
  ///
  /// This will map to the api's 429 codes.
  too-many-requests,
  /// Generic error value.
  ///
  /// This means that some unexpected error occurred.
  generic-error,
  /// Additional error information may be added in the future via this resource type.
  extra(extra-kv-error),
}

/// Selects the behavior for an insert when the new key matches an existing key.
///
...
enum insert-mode {
  /// Updates the existing key's value by overwriting it with the new value.
  ///
  /// This is the default mode.
  overwrite,

  /// Fails, leaving the existing key's value unmodified.
  ///
  /// With this mode, the insert fails with a code of `kv-error.precondition-failed`, and
  /// does not modify the existing value. Inserts with this mode will only “add” new key-value
  /// pairs; they are prevented from modifying any existing ones.
  add,

  /// Updates the existing key's value by appending the new value to it.
  append,

  /// Updates the existing key's value by prepending the new value to it.
  prepend,
}

/// Options for configuring the behavior of the `insert` function.
record insert-options {
  /// If set, allows fetching from the origin to occur in the background, enabling a faster
  /// response with stale content. The cache will be updated with fresh content after the request
  /// is completed.
  background-fetch: bool,

  /// Requests for keys will return a “generation” header specific to the version of a key. The
  /// generation header is a unique, non-serial 64-bit unsigned integer that can be used for
  /// testing against a specific KV store value.
  if-generation-match: option<u64>,

  /// Sets an arbitrary data field which can contain up to 2000B of data.
  metadata: option<string>,

  /// Sets a time for the key to expire. Deletion will take place up to 24 hours after the ttl
  /// reaches 0.
  time-to-live-sec: option<u32>,

  /// Select the behavior in the case when the new key matches an existing key.
  mode: insert-mode,

  /// Additional options may be added in the future via this resource type.
  extra: option<borrow<extra-insert-options>>,
}

/// A response from a KV Store Lookup operation.
///
/// This type holds the `body`, metadata, and generation of found key.
resource entry {
  /// Take and return the body from this `entry`, if it has one; otherwise return `none`.
  ///
  /// After calling this method, this entry will no longer have a body.
  take-body: func() -> option<body>;

  /// Read the metadata of the KV Store item, if present.
  metadata: func(max-len: u64) -> result<option<string>, error>;

  /// Read the current generation of the KV Store item.
  generation: func() -> u64;
}

insert failed: KvError::InternalError

/// An asynchronous KV Store lookup. Use `await-lookup` to resolve.
use async-io.{pollable as pending-lookup};

/// An asynchronous KV Store insert. Use `await-insert` to resolve.
use async-io.{pollable as pending-insert};

/// An asynchronous KV Store delete. Use `await-delete` to resolve.
use async-io.{pollable as pending-delete};

/// An asynchronous KV Store list. Use `await-list` to resolve.
use async-io.{pollable as pending-list};

/// Wait on the async lookup of a value in the KV Store.
///
/// Returns `ok(some(v))` with the value `v` that was found, `ok(none)` if no value was
/// found, or `err(e)` indicating the error `e` occurred.
await-lookup: func(
  handle: pending-lookup,
) -> result<option<entry>, kv-error>;

/// Wait on the async insert of a value in the KV Store.
///
/// Returns `ok` if the `insert` succeeded, or an error code on failure.
await-insert: func(
  handle: pending-insert,
) -> result<_, kv-error>;

/// Wait on the async delete of a value in the KV Store.
///
/// Returns `ok(true)` if a value was successfully deleted, `ok(false)` if no value was
/// found, or `err(e)` indicating the error `e` occurred.
await-delete: func(
  handle: pending-delete,
) -> result<bool, kv-error>;

/// Wait on the async list of keys in the KV Store.
///
/// Returns `ok(b)` with the JSON-encoded body `b` on success, or `err(e)` indicating
/// the error `e` occurred.
await-list: func(
  handle: pending-list,
) -> result<body, kv-error>;

mod bindings;

use bindings::{
    exports::fastly::compute::http_incoming,
    fastly::compute::{http_body, http_req, http_resp, kv_store},
};

fn get_header_value(
    request: &http_incoming::Request,
    name: &str,
) -> Result<Option<String>, http_req::Error> {
    let mut max_len: u64 = 128;
    loop {
        match request.get_header_value(name, max_len) {
            Ok(Some(bytes)) => return Ok(Some(String::from_utf8_lossy(&bytes).into_owned())),
            Ok(None) => return Ok(None),
            Err(http_req::Error::BufferLen(needed)) => max_len = needed,
            Err(e) => return Err(e),
        }
    }
}

reading a body to a String, the same loop as the body article (11 lines)
fn read_body_to_string(body: &http_body::Body) -> Result<String, http_body::Error> {
    let mut buf = Vec::new();
    loop {
        let chunk = http_body::read(body, 8192)?;
        if chunk.is_empty() {
            break;
        }
        buf.extend_from_slice(&chunk);
    }
    Ok(String::from_utf8_lossy(&buf).into_owned())
}

struct KvStoreExample;

impl http_incoming::Guest for KvStoreExample {
    fn handle(request: http_incoming::Request, request_body: http_body::Body) -> Result<(), ()> {
        let key = get_header_value(&request, "x-key")
            .map_err(|_| ())?
            .unwrap_or_else(|| "demo-note".to_string());

        let incoming_value = read_body_to_string(&request_body).map_err(|_| ())?;
        let value = if incoming_value.is_empty() {
            "Hello from the KV Store!".to_string()
        } else {
            incoming_value
        };

        let store = kv_store::Store::open("notes").map_err(|_| ())?;
        let mut log = String::new();

        let insert_body = http_body::new().map_err(|_| ())?;
        http_body::write(&insert_body, value.as_bytes()).map_err(|_| ())?;
        let insert_options = kv_store::InsertOptions {
            background_fetch: false,
            if_generation_match: None,
            metadata: Some("written by the kv-store example".to_string()),
            time_to_live_sec: None,
            mode: kv_store::InsertMode::Overwrite,
            extra: None,
        };
        let pending_insert = store
            .insert_async(&key, insert_body, &insert_options)
            .map_err(|_| ())?;
        kv_store::await_insert(pending_insert).map_err(|_| ())?;
        log.push_str(&format!("inserted \"{key}\" = \"{value}\"\n"));

        let pending_lookup = store.lookup_async(&key).map_err(|_| ())?;
        let entry = kv_store::await_lookup(pending_lookup)
            .map_err(|_| ())?
            .ok_or(())?;
        let generation = entry.generation();
        let metadata = entry.metadata(256).map_err(|_| ())?;
        let entry_body = entry.take_body().ok_or(())?;
        let read_back = read_body_to_string(&entry_body).map_err(|_| ())?;
        log.push_str(&format!(
            "looked up \"{key}\": value = \"{read_back}\", generation = {generation}, metadata = {metadata:?}\n"
        ));

        let pending_delete = store.delete_async(&key).map_err(|_| ())?;
        let deleted = kv_store::await_delete(pending_delete).map_err(|_| ())?;
        log.push_str(&format!("deleted \"{key}\": {deleted}\n"));

        let pending_lookup_2 = store.lookup_async(&key).map_err(|_| ())?;
        let after_delete = kv_store::await_lookup(pending_lookup_2).map_err(|_| ())?;
        log.push_str(&format!(
            "looked up \"{key}\" again: {}\n",
            match after_delete {
                Some(_) => "still there",
                None => "gone",
            }
        ));

        let response = http_resp::Response::new().map_err(|_| ())?;
        response
            .insert_header("content-type", b"text/plain")
            .map_err(|_| ())?;

        let out_body = http_body::new().map_err(|_| ())?;
        http_body::write(&out_body, log.as_bytes()).map_err(|_| ())?;
        http_resp::send_downstream(response, out_body).map_err(|_| ())?;

        Ok(())
    }
}

bindings::export!(KvStoreExample with_types_in bindings);

[local_server.kv_stores]
  notes = []

fastly compute serve

curl http://127.0.0.1:7676/ (opens in a new window)

inserted "demo-note" = "Hello from the KV Store!"
looked up "demo-note": value = "Hello from the KV Store!", generation = 1785949892671600000, metadata = Some("written by the kv-store example")
deleted "demo-note": true
looked up "demo-note" again: gone

curl -H "x-key: my-note" -d "a value I wrote myself" http://127.0.0.1:7676/ (opens in a new window)

inserted "my-note" = "a value I wrote myself"
looked up "my-note": value = "a value I wrote myself", generation = 1785949892677652000, metadata = Some("written by the kv-store example")
deleted "my-note": true
looked up "my-note" again: gone