Add stubs for new "busy handle" APIs for the core cache

lib/compute-at-edge-abi/cache.witx

@@ -1,5 +1,7 @@
 ;;; The outcome of a cache lookup (either bare or as part of a cache transaction)
 (typename $cache_handle (handle))
+;;; Handle that can be used to check whether or not a cache lookup is waiting on another client.
+(typename $cache_busy_handle (handle))
 (typename $cache_object_length u64)
 (typename $cache_duration_ns u64)
 (typename $cache_hit_count u64)
@@ -117,6 +119,24 @@
         (result $err (expected $cache_handle (error $fastly_status)))
     )
 
+    ;;; The entrypoint to the request-collapsing cache transaction API, returning instead of waiting on busy.
+    ;;;
+    ;;; This operation always participates in request collapsing and may return stale objects. To bypass
+    ;;; request collapsing, use `lookup` and `insert` instead.
+    (@interface func (export "transaction_lookup_async")
+        (param $cache_key (list u8))
+        (param $options_mask $cache_lookup_options_mask)
+        (param $options (@witx pointer $cache_lookup_options))
+        (result $err (expected $cache_busy_handle (error $fastly_status)))
+    )
+
+    ;;; Continues the lookup transaction from which the given busy handle was returned,
+    ;;; waiting for the leader transaction if request collapsed, and returns a cache handle.
+    (@interface func (export "cache_busy_handle_wait")
+        (param $busy_handle $cache_busy_handle)
+        (result $err (expected $cache_handle (error $fastly_status)))
+    )
+
     ;;; Insert an object into the cache with the given metadata.
     ;;;
     ;;; Can only be used in if the cache handle state includes the `$must_insert_or_update` flag.
@@ -166,6 +186,12 @@
         (param $handle $cache_handle)
         (result $err (expected (error $fastly_status))))
 
+    ;;; Close an interaction with the cache that has not yet finished request collapsing.
+    (@interface func (export "close_busy")
+        (param $handle $cache_busy_handle)
+        (result $err (expected (error $fastly_status)))
+    )
+
     ;;; Close an ongoing interaction with the cache.
     ;;;
     ;;; If the cache handle state includes the `$must_insert_or_update` (and hence no insert or

lib/src/component/cache.rs

@@ -53,6 +53,28 @@ impl cache::Host for Session {
         .into())
     }
 
+    async fn transaction_lookup_async(
+        &mut self,
+        _key: String,
+        _options_mask: cache::LookupOptionsMask,
+        _options: cache::LookupOptions,
+    ) -> Result<cache::BusyHandle, types::Error> {
+        Err(Error::Unsupported {
+            msg: "Cache API primitives not yet supported",
+        }
+        .into())
+    }
+
+    async fn cache_busy_handle_wait(
+        &mut self,
+        _handle: cache::BusyHandle,
+    ) -> Result<cache::Handle, types::Error> {
+        Err(Error::Unsupported {
+            msg: "Cache API primitives not yet supported",
+        }
+        .into())
+    }
+
     async fn transaction_insert(
         &mut self,
         _handle: cache::Handle,
@@ -96,6 +118,13 @@ impl cache::Host for Session {
         .into())
     }
 
+    async fn close_busy(&mut self, _handle: cache::BusyHandle) -> Result<(), types::Error> {
+        Err(Error::Unsupported {
+            msg: "Cache API primitives not yet supported",
+        }
+        .into())
+    }
+
     async fn close(&mut self, _handle: cache::Handle) -> Result<(), types::Error> {
         Err(Error::Unsupported {
             msg: "Cache API primitives not yet supported",

lib/src/wiggle_abi/cache.rs

@@ -32,6 +32,22 @@ impl FastlyCache for Session {
         Err(Error::NotAvailable("Cache API primitives"))
     }
 
+    fn transaction_lookup_async<'a>(
+        &mut self,
+        cache_key: &wiggle::GuestPtr<'a, [u8]>,
+        options_mask: types::CacheLookupOptionsMask,
+        options: &wiggle::GuestPtr<'a, types::CacheLookupOptions>,
+    ) -> Result<types::CacheBusyHandle, Error> {
+        Err(Error::NotAvailable("Cache API primitives"))
+    }
+
+    fn cache_busy_handle_wait(
+        &mut self,
+        handle: types::CacheBusyHandle,
+    ) -> Result<types::CacheHandle, Error> {
+        Err(Error::NotAvailable("Cache API primitives"))
+    }
+
     fn transaction_insert<'a>(
         &mut self,
         handle: types::CacheHandle,
@@ -63,6 +79,10 @@ impl FastlyCache for Session {
         Err(Error::NotAvailable("Cache API primitives"))
     }
 
+    fn close_busy(&mut self, handle: types::CacheBusyHandle) -> Result<(), Error> {
+        Err(Error::NotAvailable("Cache API primitives"))
+    }
+
     fn close(&mut self, handle: types::CacheHandle) -> Result<(), Error> {
         Err(Error::NotAvailable("Cache API primitives"))
     }

lib/wit/deps/fastly/compute.wit

@@ -522,7 +522,7 @@ interface http-resp {
   ) -> result<_, error>;
 
   send-downstream: func(
-    h: response-handle, 
+    h: response-handle,
     b: body-handle,
     streaming: bool,
   ) -> result<_, error>;
@@ -835,6 +835,8 @@ interface cache {
 
   /// The outcome of a cache lookup (either bare or as part of a cache transaction)
   type handle = u32;
+  /// Handle that can be used to check whether or not a cache lookup is waiting on another client.
+  type busy-handle = u32;
   type object-length = u64;
   type duration-ns = u64;
   type cache-hit-count = u64;
@@ -941,6 +943,22 @@ interface cache {
     options: lookup-options,
   ) -> result<handle, error>;
 
+  /// The entrypoint to the request-collapsing cache transaction API, returning instead of waiting on busy.
+  ///
+  /// This operation always participates in request collapsing and may return stale objects. To bypass
+  /// request collapsing, use `lookup` and `insert` instead.
+  transaction-lookup-async: func(
+    key: string,
+    mask: lookup-options-mask,
+    options: lookup-options,
+  ) -> result<busy-handle, error>;
+
+  /// Continues the lookup transaction from which the given busy handle was returned,
+  /// waiting for the leader transaction if request collapsed, and returns a cache handle.
+  cache-busy-handle-wait: func(
+    handle: busy-handle,
+  ) -> result<handle, error>;
+
   /// Insert an object into the cache with the given metadata.
   ///
   /// Can only be used in if the cache handle state includes the `must-insert-or-update` flag.
@@ -985,6 +1003,14 @@ interface cache {
   /// Useful if there is an error before streaming is possible, e.g. if a backend is unreachable.
   transaction-cancel: func(handle: handle) -> result<_, error>;
 
+  /// Close an interaction with the cache that has not yet finished request collapsing.
+  close-busy: func(handle: busy-handle) -> result<_, error>;
+
+  /// Close an ongoing interaction with the cache.
+  ///
+  /// If the cache handle state includes the `$must_insert_or_update` (and hence no insert or
+  /// update has been performed), closing the handle cancels any request collapsing, potentially
+  /// choosing a new waiter to perform the insertion/update.
   close: func(handle: handle) -> result<_, error>;
 
   get-state: func(handle: handle) -> result<lookup-state, error>;