fastly 0.12.0 - Docs.rs

//! Interface to the [Compute KV Store][blog].
//!
//! [blog]: https://www.fastly.com/blog/introducing-the-compute-edge-kv-store-global-persistent-storage-for-compute-functions

use crate::kv_store;
use crate::Body;
use serde::Deserialize;

pub use self::handle::InsertMode;
pub use self::handle::KVStoreError;
pub use self::handle::ListMode;
pub use self::handle::StoreHandle;

pub use self::handle::PendingDeleteHandle;
pub use self::handle::PendingInsertHandle;
pub use self::handle::PendingListHandle;
pub use self::handle::PendingLookupHandle;

// TODO ACF 2022-10-10: this module is temporarily public for the large kv preview.
#[doc(hidden)]
pub mod handle;

/// A response from a KV Store Lookup operation.
///
/// This type holds the [`Body`][`crate::Body`], metadata, and generation of found key.
pub struct LookupResponse {
    body: Option<Body>,
    metadata: Option<bytes::Bytes>,
    generation: u64,
}

impl LookupResponse {
    /// Return the `Body` from a `LookupResponse`.
    ///
    /// Returns the body contents in a `Body`
    pub fn take_body(&mut self) -> Body {
        self.body.take().unwrap_or_else(Body::new)
    }

    /// Take and return the body from this response if it has one, otherwise return `None`.
    ///
    /// After calling this method, this response will no longer have a body.
    pub fn try_take_body(&mut self) -> Option<Body> {
        self.body.take()
    }

    /// Convert the `LookupResponse` body into a byte vector.
    ///
    /// Returns the body contents in a `Vec<u8>`
    pub fn take_body_bytes(&mut self) -> Vec<u8> {
        if let Some(body) = self.try_take_body() {
            body.into_bytes()
        } else {
            Vec::new()
        }
    }

    /// Read the metadata of the KVStore item.
    ///
    /// Returns the metadata in a `Option<bytes::Bytes>`
    pub fn metadata(&self) -> Option<bytes::Bytes> {
        self.metadata.to_owned()
    }

    /// Read the generation of the KVStore item.
    ///
    /// Returns the generation in a `u32`
    #[deprecated(
        since = "0.11.0",
        note = "`generation` has a bug in this version of the SDK, and will always return 0"
    )]
    pub fn generation(&self) -> u32 {
        0
    }

    /// Read the current generation of the KVStore item.
    ///
    /// Returns the current generation in a `u64`
    pub fn current_generation(&self) -> u64 {
        self.generation
    }
}

#[derive(Deserialize, Debug, Clone)]
struct ListMetadata {
    limit: u32,
    next_cursor: Option<String>,
    prefix: Option<String>,
    consistency: Option<String>,
}

/// A page from a KV Store List operation.
#[derive(Deserialize, Debug, Clone)]
pub struct ListPage {
    data: Vec<String>,
    meta: ListMetadata,
}

impl ListPage {
    /// Returns a slice of the listed keys in the current page.
    pub fn keys(&self) -> &[String] {
        self.data.as_slice()
    }
    /// Consumes the page, and returns a `Vec<String>` of its listed keys.
    pub fn into_keys(self) -> Vec<String> {
        self.data
    }
    /// Returns an `Option<String>` of the List operation's `next_cursor`
    pub fn next_cursor(&self) -> Option<String> {
        self.meta.next_cursor.clone()
    }
    /// Returns an `Option<&str>` of the List operation's `prefix`
    pub fn prefix(&self) -> Option<&str> {
        self.meta.prefix.as_deref()
    }
    /// Returns a `u32` of the List operation's `limit`
    pub fn limit(&self) -> u32 {
        self.meta.limit
    }
    /// Returns the `ListMode` of the List operation
    pub fn mode(&self) -> ListMode {
        match self.meta.consistency.as_deref() {
            // default
            None => ListMode::Strong,
            // api doesn't actually return strong, but returns none, as above
            // however if this should change, we'll catch it
            Some("strong") => ListMode::Strong,
            Some("eventual") => ListMode::Eventual,
            Some(other) => ListMode::Other(other.to_string()),
        }
    }
}

/// A response from a KV Store List operation.
#[derive(Debug)]
pub struct ListResponse<'a> {
    store_handle: &'a kv_store::StoreHandle,
    page: ListPage,
    iterator_did_error: bool,
}

impl<'a> ListResponse<'a> {
    /// Creates an initialized ListResponse, only used to create an iterable
    fn new(
        handle: &'a kv_store::StoreHandle,
        mode: ListMode,
        cursor: Option<String>,
        limit: Option<u32>,
        prefix: Option<String>,
    ) -> Self {
        let m_limit = limit.unwrap_or(1000);

        let m_consistency = match mode {
            ListMode::Strong => None,
            ListMode::Eventual => Some("eventual".to_string()),
            ListMode::Other(_) => None,
        };

        ListResponse {
            store_handle: handle,
            page: ListPage {
                data: vec![],
                meta: ListMetadata {
                    limit: m_limit,
                    next_cursor: cursor,
                    prefix,
                    consistency: m_consistency,
                },
            },
            iterator_did_error: false,
        }
    }
    /// Consumes the `ListResponse` and returns the current `ListPage`
    pub fn into_page(self) -> ListPage {
        self.page
    }
}

impl Iterator for ListResponse<'_> {
    type Item = Result<ListPage, KVStoreError>;

    fn next(&mut self) -> Option<Self::Item> {
        let cursor = self.page.meta.next_cursor.to_owned();
        // close the iterator after the error
        if self.iterator_did_error {
            return None;
        }

        // end of pagination, unless it's a ListResponse::new()
        if self.page.meta.next_cursor.is_none() && !self.page.data.is_empty() {
            return None;
        }

        let mode = match self.page.meta.consistency.as_deref() {
            None => ListMode::Strong, // default
            Some("strong") => ListMode::Strong,
            Some("eventual") => ListMode::Eventual,
            Some(other) => ListMode::Other(other.to_string()),
        };

        let limit = Some(self.page.meta.limit);
        let prefix = self.page.meta.prefix.to_owned();

        let h_res = self.store_handle.list(mode, cursor, limit, prefix);
        if let Err(e) = h_res {
            return Some(Err(e));
        }
        let handle = h_res.unwrap();

        let w_res = self.store_handle.pending_list_wait(handle);
        if let Err(e) = w_res {
            return Some(Err(e));
        }

        let out = w_res.unwrap().into_page();
        let keys = out.keys();
        if keys.is_empty() {
            return None;
        }

        self.page.data = keys.to_vec();
        self.page.meta.next_cursor = out.next_cursor();

        Some(Ok(self.page.clone()))
    }
}

/// A builder for KVStore insertions, supporting advanced configuration like [`InsertMode`], background_fetch, if_generation_match, metadata, ttl, and asynchronous execution.
///
/// ```no_run
/// # use fastly::kv_store::{InsertMode, KVStore, KVStoreError};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// store.build_insert()
///    .mode(InsertMode::Prepend)
///    .background_fetch()
///    .if_generation_match(1337)
///    .metadata("2000B of arbitrary data")
///    .time_to_live(std::time::Duration::from_secs(5))
///    .execute("key1", "value1")?;
/// # Ok(()) }
/// ```
///
/// # Synchronous and Asynchronous support
///
/// InsertBuilder also exposes the ability to issue an asynchronous insert. When finalizing the InsertBuilder,
/// [`execute_async`][`Self::execute_async()`] will send the request, and unblock. There is currently no polling mechanism.
/// To retrieve the result, use the blocking function [`pending_insert_wait`][`KVStore::pending_insert_wait()`].
///
/// # Examples
///
/// ```no_run
/// # use fastly::kv_store::{KVStore, KVStoreError,PendingInsertHandle};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// // synchronous non-builder insert
/// let result: Result<(), KVStoreError> = store.insert("key", "value");
/// // synchronous builder insert
/// let result: Result<(), KVStoreError> = store.build_insert().execute("key", "value");
/// // asynchronous builder insert
/// let insert_handle: Result<PendingInsertHandle, KVStoreError> = store.build_insert().execute_async("key", "value");
/// let result: Result<(), KVStoreError> = store.pending_insert_wait(insert_handle?);
/// # Ok(()) }
/// ```
pub struct InsertBuilder<'a> {
    store: &'a KVStore,
    mode: InsertMode,
    background_fetch: bool,
    if_generation_match: Option<u64>,
    metadata: String,
    time_to_live_sec: Option<std::time::Duration>,
}

impl InsertBuilder<'_> {
    /// Change the behavior in the case when the new key matches an existing key.
    pub fn mode(self, mode: InsertMode) -> Self {
        InsertBuilder { mode, ..self }
    }

    /// 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.
    pub fn background_fetch(self) -> Self {
        InsertBuilder {
            background_fetch: true,
            ..self
        }
    }

    /// 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.
    pub fn if_generation_match(self, gen: u64) -> Self {
        InsertBuilder {
            if_generation_match: Some(gen),
            ..self
        }
    }

    /// Sets an arbitrary data field which can contain up to 2000B of data.
    pub fn metadata(self, data: &str) -> Self {
        InsertBuilder {
            metadata: data.to_string(),
            ..self
        }
    }

    /// Sets a time for the key to expire. Deletion will take place up to 24 hours after the ttl reaches 0.
    pub fn time_to_live(self, ttl: std::time::Duration) -> Self {
        InsertBuilder {
            time_to_live_sec: Some(ttl),
            ..self
        }
    }

    /// Initiate and wait on an insert of a value into the KV Store.
    ///
    /// Returns `Ok(())` if the value is inserted, and `KVStoreError` if the insert failed.
    pub fn execute(self, key: &str, value: impl Into<Body>) -> Result<(), KVStoreError> {
        let handle = self.store.handle.insert(
            key,
            value.into().into_handle(),
            self.mode,
            self.background_fetch,
            self.if_generation_match,
            self.metadata.clone(),
            self.time_to_live_sec,
        )?;
        self.store.pending_insert_wait(handle)
    }

    /// Initiate async insert of a value into the KV Store.
    ///
    /// Returns `Ok(Some(PendingInsertHandle))` if insert creation is successful.
    pub fn execute_async(
        &self,
        key: &str,
        value: impl Into<Body>,
    ) -> Result<PendingInsertHandle, KVStoreError> {
        self.store.handle.insert(
            key,
            value.into().into_handle(),
            self.mode,
            self.background_fetch,
            self.if_generation_match,
            self.metadata.clone(),
            self.time_to_live_sec,
        )
    }
}

/// A builder for KVStore lookups, supporting advanced features like asynchronous execution.
///
/// ```no_run
/// # use fastly::kv_store::{KVStore, KVStoreError};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// store.build_lookup()
///    .execute("key1")?;
/// # Ok(()) }
/// ```
///
/// # Synchronous and Asynchronous support
///
/// LookupBuilder exposes the ability to issue an asynchronous lookup. Using
/// [`execute_async`][`Self::execute_async()`] will send the request, and unblock. There is currently no polling mechanism.
/// To retrieve the result, use the blocking function [`pending_lookup_wait`][`KVStore::pending_lookup_wait()`].
///
/// # Examples
///
/// ```no_run
/// # use fastly::kv_store::{KVStore, KVStoreError, LookupResponse, PendingLookupHandle};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// // synchronous non-builder lookup
/// let result: Result<LookupResponse, KVStoreError> = store.lookup("key");
/// // synchronous builder lookup
/// let result: Result<LookupResponse, KVStoreError> = store.build_lookup().execute("key");
/// // asynchronous builder lookup
/// let lookup_handle: Result<PendingLookupHandle, KVStoreError> = store.build_lookup().execute_async("key");
/// let result: Result<LookupResponse, KVStoreError> = store.pending_lookup_wait(lookup_handle?);
/// # Ok(()) }
/// ```
pub struct LookupBuilder<'a> {
    store: &'a KVStore,
}

impl LookupBuilder<'_> {
    /// Initiate and wait on an lookup of a value in the KV Store.
    ///
    /// Returns `Ok(LookupResponse)` if the value is retrieved without error, and `KVStoreError` if the lookup failed.
    pub fn execute(&self, key: &str) -> Result<LookupResponse, KVStoreError> {
        self.store
            .handle
            .pending_lookup_wait(self.store.handle.lookup(key.as_bytes())?)
    }

    /// Initiate async lookup of a value in the KV Store.
    ///
    /// Returns `Ok(Some(PendingLookupHandle))` if lookup creation is successful.
    pub fn execute_async(&self, key: &str) -> Result<PendingLookupHandle, KVStoreError> {
        self.store.handle.lookup(key.as_bytes())
    }
}

/// A builder for KVStore deletes, supporting advanced features like asynchronous execution.
///
/// ```no_run
/// # use fastly::kv_store::{KVStore, KVStoreError};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// store.build_delete()
///    .execute("key1")?;
/// # Ok(()) }
/// ```
///
/// # Synchronous and Asynchronous support
///
/// DeleteBuilder exposes the ability to issue an asynchronous delete. Using
/// [`execute_async`][`Self::execute_async()`] will send the request, and unblock. There is currently no polling mechanism.
/// To retrieve the result, use the blocking function [`pending_delete_wait`][`KVStore::pending_delete_wait()`].
///
/// # Examples
///
/// ```no_run
/// # use fastly::kv_store::{KVStore, KVStoreError, PendingDeleteHandle};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// // synchronous non-builder delete
/// let result: Result<(), KVStoreError> = store.delete("key");
/// // synchronous builder delete
/// let result: Result<(), KVStoreError> = store.build_delete().execute("key");
/// // asynchronous builder delete
/// let delete_handle: Result<PendingDeleteHandle, KVStoreError> = store.build_delete().execute_async("key");
/// let result: Result<(), KVStoreError> = store.pending_delete_wait(delete_handle?);
/// # Ok(()) }
/// ```
pub struct DeleteBuilder<'a> {
    store: &'a KVStore,
}

impl DeleteBuilder<'_> {
    /// Initiate and wait on an delete of a value in the KV Store.
    ///
    /// Returns `Ok(()))` if the value is deleted without error, and `KVStoreError` if the delete failed.
    pub fn execute(&self, key: &str) -> Result<(), KVStoreError> {
        self.store
            .pending_delete_wait(self.store.handle.delete(key)?)
    }

    /// Initiate async delete of a value in the KV Store.
    ///
    /// Returns `Ok(PendingDeleteHandle)` if delete creation is successful.
    pub fn execute_async(&self, key: &str) -> Result<PendingDeleteHandle, KVStoreError> {
        self.store.handle.delete(key)
    }
}

/// A builder for KVStore key list operations, supporting advanced configuration like cursor, limit, prefix, and asynchronous execution.
///
/// ```no_run
/// # use fastly::kv_store::{KVStore, KVStoreError};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// store.build_list().execute()?;
/// # Ok(()) }
/// ```
///
/// # Synchronous and Asynchronous support
///
/// ListBuilder also exposes the ability to issue an asynchronous list. When finalizing the ListBuilder,
/// [`execute_async`][`Self::execute_async()`] will send the request, and unblock. There is currently no polling mechanism.
/// To retrieve the result, use the blocking function [`pending_list_wait`][`KVStore::pending_list_wait()`].
///
/// # Examples
///
/// ```no_run
/// # use fastly::kv_store::{KVStore, KVStoreError,PendingListHandle,ListPage};
/// # fn f() -> Result<(), KVStoreError> {
/// # let store = KVStore::open("my-kv-store")?.unwrap();
/// // synchronous non-builder list
/// let result: Result<ListPage, KVStoreError> = store.list();
/// // synchronous builder list
/// let result: Result<ListPage, KVStoreError> = store.build_list().execute();
/// // asynchronous builder list
/// let list_handle: Result<PendingListHandle, KVStoreError> = store.build_list().execute_async();
/// let result: Result<ListPage, KVStoreError> = store.pending_list_wait(list_handle?);
/// # Ok(()) }
/// ```
pub struct ListBuilder<'a> {
    store: &'a KVStore,
    mode: ListMode,
    cursor: Option<String>,
    limit: Option<u32>,
    prefix: Option<String>,
}

impl<'a> ListBuilder<'a> {
    /// Rather than read data from the primary data source, which is slower but strongly consistent (`strong`, the default), instead read a local copy if available, which offers higher speed and may be a few seconds out of date (`eventual`).
    pub fn eventual_consistency(self) -> Self {
        ListBuilder {
            mode: ListMode::Eventual,
            ..self
        }
    }
    /// Change the cursor of the request.
    pub fn cursor(self, cursor: &str) -> Self {
        ListBuilder {
            cursor: Some(cursor.to_string()),
            ..self
        }
    }

    /// Set the maximum number of items included the response. The default limit is 100 items.
    pub fn limit(self, limit: u32) -> Self {
        ListBuilder {
            limit: Some(limit),
            ..self
        }
    }

    /// Set the prefix match for items to include in the resultset.
    pub fn prefix(self, prefix: &str) -> Self {
        ListBuilder {
            prefix: Some(prefix.to_string()),
            ..self
        }
    }

    /// Initiate and wait on the first page of a list of values in the KV Store.
    ///
    /// Returns `Ok(ListPage)` if the list is returned, and `KVStoreError` if the list failed.
    pub fn execute(self) -> Result<ListPage, KVStoreError> {
        let handle = self
            .store
            .handle
            .list(self.mode, self.cursor, self.limit, self.prefix)?;
        let res = self.store.pending_list_wait(handle)?;
        Ok(res)
    }

    /// Produce a new ListResponse, which can be used as an iterator for
    /// chunked list operations.
    ///
    /// Returns a new `ListResponse`, primed for iteration.
    pub fn iter(self) -> ListResponse<'a> {
        ListResponse::new(
            &self.store.handle,
            self.mode,
            self.cursor,
            self.limit,
            self.prefix,
        )
    }

    /// Initiate async list of values in the KV Store.
    ///
    /// Returns `Ok(Some(PendingListHandle))` if list creation is successful.
    pub fn execute_async(&self) -> Result<PendingListHandle, KVStoreError> {
        self.store.handle.list(
            self.mode.clone(),
            self.cursor.clone(),
            self.limit,
            self.prefix.clone(),
        )
    }
}

/// A [Compute KV Store][blog].
///
/// Keys in the KV Store must follow the following rules:
///
///   * Keys can contain any sequence of valid Unicode characters, of length 1-1024 bytes when
///     UTF-8 encoded.
///   * Keys cannot contain Carriage Return or Line Feed characters.
///   * Keys cannot start with `.well-known/acme-challenge/`.
///   * Keys cannot be named `.` or `..`.
///
/// [blog]: https://www.fastly.com/blog/introducing-the-compute-edge-kv-store-global-persistent-storage-for-compute-functions
pub struct KVStore {
    handle: StoreHandle,
}

impl KVStore {
    // TODO ACF 2022-10-10: temporary method to support the large kv preview
    #[doc(hidden)]
    pub fn as_handle(&self) -> &StoreHandle {
        &self.handle
    }

    /// Open the KV Store with the given name.
    ///
    /// If there is no store by that name, this returns `Ok(None)`.
    pub fn open(name: &str) -> Result<Option<Self>, KVStoreError> {
        match StoreHandle::open(name)? {
            Some(handle) => Ok(Some(Self { handle })),
            None => Ok(None),
        }
    }

    /// Look up a value in the KV Store.
    ///
    /// Returns `Ok(LookupResponse)` if the value is retrieved without error, and `KVStoreError` if the lookup failed.
    pub fn lookup(&self, key: &str) -> Result<LookupResponse, KVStoreError> {
        self.handle
            .pending_lookup_wait(self.handle.lookup(key.as_bytes())?)
    }

    /// Create a buildable lookup request for the KV Store.
    ///
    /// When the desired configuration has been set, execute the lookup and wait for the response.
    pub fn build_lookup(&self) -> LookupBuilder<'_> {
        LookupBuilder { store: self }
    }

    /// Look up a value in the KV Store.
    ///
    /// Returns `Ok(LookupResponse)` if the value is found, and `Err(KVStoreError)` if the lookup failed.
    pub fn pending_lookup_wait(
        &self,
        pending_request_handle: PendingLookupHandle,
    ) -> Result<LookupResponse, KVStoreError> {
        self.handle.pending_lookup_wait(pending_request_handle)
    }

    /// Insert a value into the KV Store.
    ///
    /// If the store already contained a value for this key, it will be overwritten.
    ///
    /// The value may be provided as any type that can be converted to [`Body`], such as `&[u8]`,
    /// `Vec<u8>`, `&str`, or `String`.
    ///
    /// # Value sizes
    ///
    /// The size of the value must be known when calling this method. In practice, that means that
    /// if a [`Body`] value contains an external request or response, it must be encoded with
    /// `Content-Length` rather than `Transfer-Encoding: chunked`.
    pub fn insert(&self, key: &str, value: impl Into<Body>) -> Result<(), KVStoreError> {
        self.pending_insert_wait(self.handle.insert(
            key,
            value.into().into_handle(),
            InsertMode::Overwrite,
            false,
            None,
            "",
            None,
        )?)
    }

    /// Create a buildable insert request for the KV Store.
    ///
    /// When the desired configuration has been set, execute the insert and wait for the response.
    pub fn build_insert(&self) -> InsertBuilder<'_> {
        InsertBuilder {
            store: self,
            mode: InsertMode::Overwrite,
            background_fetch: false,
            if_generation_match: None,
            metadata: String::new(),
            time_to_live_sec: None,
        }
    }

    /// Insert a value in the KV Store.
    ///
    /// Returns `Ok(())` if the value is found, and `KVStoreError` if the key was not found.
    pub fn pending_insert_wait(
        &self,
        pending_insert_handle: PendingInsertHandle,
    ) -> Result<(), KVStoreError> {
        self.handle.pending_insert_wait(pending_insert_handle)?;
        Ok(())
    }

    /// Delete a value in the KV Store.
    ///
    /// Returns `Ok(())` if delete is successful.
    pub fn delete(&self, key: &str) -> Result<(), KVStoreError> {
        self.pending_delete_wait(self.handle.delete(key)?)
    }

    /// Create a buildable delete request for the KV Store.
    ///
    /// When the desired configuration has been set, execute the delete and wait for the response.
    pub fn build_delete(&self) -> DeleteBuilder<'_> {
        DeleteBuilder { store: self }
    }

    /// Delete a value in the KV Store.
    ///
    /// Returns `Ok(())` if the key is deleted, and `KVStoreError` if the key was not found.
    pub fn pending_delete_wait(
        &self,
        pending_delete_handle: PendingDeleteHandle,
    ) -> Result<(), KVStoreError> {
        self.handle.pending_delete_wait(pending_delete_handle)?;
        Ok(())
    }

    /// List keys in the KV Store.
    ///
    /// Returns an `Ok(ListPage)` on success, and `Err(KVStoreError)` if there was a failure. The
    /// limit of items per page defaults to 100 items, but can be configured through [`ListBuilder`].
    pub fn list(&self) -> Result<ListPage, KVStoreError> {
        let lh = self.handle.list(ListMode::Strong, None, None, None);

        self.pending_list_wait(lh?)
    }

    /// Create a buildable list request for the KV Store.
    ///
    /// When the desired configuration has been set, execute the list and wait for the response.
    pub fn build_list(&self) -> ListBuilder<'_> {
        ListBuilder {
            store: self,
            mode: ListMode::Strong,
            cursor: None,
            limit: None,
            prefix: None,
        }
    }

    /// Wait on a pending list operation.
    ///
    /// Returns `Ok(ListPage)` on success, and `Err(KVStoreError)` if there was a failure.
    pub fn pending_list_wait(
        &self,
        pending_request_handle: PendingListHandle,
    ) -> Result<ListPage, KVStoreError> {
        let res = self.handle.pending_list_wait(pending_request_handle);
        Ok(res?.into_page())
    }
}