feat: implement SimpleCache.getOrSet method

SimpleCache.getOrSet is a simplified interface to Fastly's request collapsing functionality for lookups and inserts into the service's cache.

Author: Jake Champion

integration-tests/js-compute/fixtures/cache-simple/bin/index.js

@@ -44,6 +44,10 @@ class SimpleCache : public BuiltinImpl<SimpleCache> {
   static bool delete_(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool get(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool set(JSContext *cx, unsigned argc, JS::Value *vp);
+  static bool getOrSet(JSContext *cx, unsigned argc, JS::Value *vp);
+
+  static bool getOrSetThenHandler(JSContext *cx, JS::HandleObject owner, JS::HandleValue extra,
+                                  JS::CallArgs args);
 
   static bool constructor(JSContext *cx, unsigned argc, JS::Value *vp);
 

runtime/js-compute-runtime/builtins/cache-simple.cpp

@@ -217,6 +217,22 @@ typedef struct {
   } val;
 } fastly_world_result_cache_handle_error_t;
 
+typedef struct {
+  bool is_err;
+  union {
+    fastly_world_tuple2_body_handle_cache_handle_t ok;
+    fastly_error_t err;
+  } val;
+} fastly_world_result_tuple2_body_handle_cache_handle_error_t;
+
+typedef struct {
+  bool is_err;
+  union {
+    fastly_cache_lookup_state_t ok;
+    fastly_error_t err;
+  } val;
+} fastly_world_result_cache_lookup_state_error_t;
+
 typedef struct {
   bool is_err;
   union {
@@ -451,6 +467,18 @@ void __wasm_import_fastly_cache_lookup(int32_t, int32_t, int32_t, int32_t, int32
 __attribute__((import_module("fastly"), import_name("cache-insert")))
 void __wasm_import_fastly_cache_insert(int32_t, int32_t, int64_t, int32_t, int32_t, int32_t, int64_t, int64_t, int32_t, int32_t, int64_t, int32_t, int32_t, int32_t, int32_t);
 
+__attribute__((import_module("fastly"), import_name("transaction-lookup")))
+void __wasm_import_fastly_transaction_lookup(int32_t, int32_t, int32_t, int32_t, int32_t);
+
+__attribute__((import_module("fastly"), import_name("transaction-insert-and-stream-back")))
+void __wasm_import_fastly_transaction_insert_and_stream_back(int32_t, int64_t, int32_t, int32_t, int32_t, int64_t, int64_t, int32_t, int32_t, int64_t, int32_t, int32_t, int32_t, int32_t);
+
+__attribute__((import_module("fastly"), import_name("transaction-cancel")))
+void __wasm_import_fastly_transaction_cancel(int32_t, int32_t);
+
+__attribute__((import_module("fastly"), import_name("cache-get-state")))
+void __wasm_import_fastly_cache_get_state(int32_t, int32_t);
+
 __attribute__((import_module("fastly"), import_name("cache-get-body")))
 void __wasm_import_fastly_cache_get_body(int32_t, int64_t, int64_t, int32_t);
 
@@ -2774,6 +2802,125 @@ bool fastly_cache_insert(fastly_world_string_t *cache_key, fastly_cache_write_op
   }
 }
 
+bool fastly_transaction_lookup(fastly_world_string_t *cache_key, fastly_cache_lookup_options_t *options, fastly_cache_handle_t *ret, fastly_error_t *err) {
+  __attribute__((aligned(4)))
+  uint8_t ret_area[8];
+  int32_t option;
+  int32_t option1;
+  if (((*options).request_headers).is_some) {
+    const fastly_request_handle_t *payload0 = &((*options).request_headers).val;
+    option = 1;
+    option1 = (int32_t) (*payload0);
+  } else {
+    option = 0;
+    option1 = 0;
+  }
+  int32_t ptr = (int32_t) &ret_area;
+  __wasm_import_fastly_transaction_lookup((int32_t) (*cache_key).ptr, (int32_t) (*cache_key).len, option, option1, ptr);
+  fastly_world_result_cache_handle_error_t result;
+  switch ((int32_t) (*((uint8_t*) (ptr + 0)))) {
+    case 0: {
+      result.is_err = false;
+      result.val.ok = (uint32_t) (*((int32_t*) (ptr + 4)));
+      break;
+    }
+    case 1: {
+      result.is_err = true;
+      result.val.err = (int32_t) (*((uint8_t*) (ptr + 4)));
+      break;
+    }
+  }
+  if (!result.is_err) {
+    *ret = result.val.ok;
+    return 1;
+  } else {
+    *err = result.val.err;
+    return 0;
+  }
+}
+
+bool fastly_transaction_insert_and_stream_back(fastly_cache_handle_t handle, fastly_cache_write_options_t *options, fastly_world_tuple2_body_handle_cache_handle_t *ret, fastly_error_t *err) {
+  __attribute__((aligned(4)))
+  uint8_t ret_area[12];
+  int32_t ptr = (int32_t) &ret_area;
+  __wasm_import_fastly_transaction_insert_and_stream_back((int32_t) (handle), (int64_t) ((*options).max_age_ns), (int32_t) ((*options).request_headers), (int32_t) ((*options).vary_rule).ptr, (int32_t) ((*options).vary_rule).len, (int64_t) ((*options).initial_age_ns), (int64_t) ((*options).stale_while_revalidate_ns), (int32_t) ((*options).surrogate_keys).ptr, (int32_t) ((*options).surrogate_keys).len, (int64_t) ((*options).length), (int32_t) ((*options).user_metadata).ptr, (int32_t) ((*options).user_metadata).len, (*options).sensitive_data, ptr);
+  fastly_world_result_tuple2_body_handle_cache_handle_error_t result;
+  switch ((int32_t) (*((uint8_t*) (ptr + 0)))) {
+    case 0: {
+      result.is_err = false;
+      result.val.ok = (fastly_world_tuple2_body_handle_cache_handle_t) {
+        (uint32_t) (*((int32_t*) (ptr + 4))),
+        (uint32_t) (*((int32_t*) (ptr + 8))),
+      };
+      break;
+    }
+    case 1: {
+      result.is_err = true;
+      result.val.err = (int32_t) (*((uint8_t*) (ptr + 4)));
+      break;
+    }
+  }
+  if (!result.is_err) {
+    *ret = result.val.ok;
+    return 1;
+  } else {
+    *err = result.val.err;
+    return 0;
+  }
+}
+
+bool fastly_transaction_cancel(fastly_cache_handle_t handle, fastly_error_t *err) {
+  __attribute__((aligned(1)))
+  uint8_t ret_area[2];
+  int32_t ptr = (int32_t) &ret_area;
+  __wasm_import_fastly_transaction_cancel((int32_t) (handle), ptr);
+  fastly_world_result_void_error_t result;
+  switch ((int32_t) (*((uint8_t*) (ptr + 0)))) {
+    case 0: {
+      result.is_err = false;
+      break;
+    }
+    case 1: {
+      result.is_err = true;
+      result.val.err = (int32_t) (*((uint8_t*) (ptr + 1)));
+      break;
+    }
+  }
+  if (!result.is_err) {
+    return 1;
+  } else {
+    *err = result.val.err;
+    return 0;
+  }
+}
+
+bool fastly_cache_get_state(fastly_cache_handle_t handle, fastly_cache_lookup_state_t *ret, fastly_error_t *err) {
+  __attribute__((aligned(1)))
+  uint8_t ret_area[2];
+  int32_t ptr = (int32_t) &ret_area;
+  __wasm_import_fastly_cache_get_state((int32_t) (handle), ptr);
+  fastly_world_result_cache_lookup_state_error_t result;
+  switch ((int32_t) (*((uint8_t*) (ptr + 0)))) {
+    case 0: {
+      result.is_err = false;
+      result.val.ok = (int32_t) (*((uint8_t*) (ptr + 1)));
+      break;
+    }
+    case 1: {
+      result.is_err = true;
+      result.val.err = (int32_t) (*((uint8_t*) (ptr + 1)));
+      break;
+    }
+  }
+  if (!result.is_err) {
+    *ret = result.val.ok;
+    return 1;
+  } else {
+    *err = result.val.err;
+    return 0;
+  }
+}
+
 bool fastly_cache_get_body(fastly_cache_handle_t handle, fastly_cache_get_body_options_t *options, fastly_body_handle_t *ret, fastly_error_t *err) {
   __attribute__((aligned(4)))
   uint8_t ret_area[8];

runtime/js-compute-runtime/builtins/cache-simple.h

@@ -160,6 +160,14 @@ typedef uint8_t fastly_content_encodings_t;
 
 typedef uint64_t fastly_cache_object_length_t;
 
+// The status of this lookup (and potential transaction)
+typedef uint8_t fastly_cache_lookup_state_t;
+
+#define FASTLY_CACHE_LOOKUP_STATE_FOUND (1 << 0)
+#define FASTLY_CACHE_LOOKUP_STATE_USABLE (1 << 1)
+#define FASTLY_CACHE_LOOKUP_STATE_STALE (1 << 2)
+#define FASTLY_CACHE_LOOKUP_STATE_MUST_INSERT_OR_UPDATE (1 << 3)
+
 typedef struct {
   bool is_some;
   fastly_request_handle_t val;
@@ -282,6 +290,11 @@ typedef struct {
   size_t len;
 } fastly_world_list_async_handle_t;
 
+typedef struct {
+  fastly_body_handle_t f0;
+  fastly_cache_handle_t f1;
+} fastly_world_tuple2_body_handle_cache_handle_t;
+
 typedef uint32_t compute_at_edge_request_handle_t;
 
 typedef uint32_t compute_at_edge_body_handle_t;
@@ -443,6 +456,16 @@ bool fastly_cache_lookup(fastly_world_string_t *cache_key, fastly_cache_lookup_o
                          fastly_cache_handle_t *ret, fastly_error_t *err);
 bool fastly_cache_insert(fastly_world_string_t *cache_key, fastly_cache_write_options_t *options,
                          fastly_body_handle_t *ret, fastly_error_t *err);
+bool fastly_transaction_lookup(fastly_world_string_t *cache_key,
+                               fastly_cache_lookup_options_t *options, fastly_cache_handle_t *ret,
+                               fastly_error_t *err);
+bool fastly_transaction_insert_and_stream_back(fastly_cache_handle_t handle,
+                                               fastly_cache_write_options_t *options,
+                                               fastly_world_tuple2_body_handle_cache_handle_t *ret,
+                                               fastly_error_t *err);
+bool fastly_transaction_cancel(fastly_cache_handle_t handle, fastly_error_t *err);
+bool fastly_cache_get_state(fastly_cache_handle_t handle, fastly_cache_lookup_state_t *ret,
+                            fastly_error_t *err);
 bool fastly_cache_get_body(fastly_cache_handle_t handle, fastly_cache_get_body_options_t *options,
                            fastly_body_handle_t *ret, fastly_error_t *err);
 

runtime/js-compute-runtime/fastly-world/fastly_world.c

@@ -796,4 +796,71 @@ bool fastly_cache_get_body(fastly_cache_handle_t handle, fastly_cache_get_body_o
     return true;
   }
   return ok;
-}
+}
+bool fastly_transaction_lookup(fastly_world_string_t *cache_key,
+                               fastly_cache_lookup_options_t *options, fastly_cache_handle_t *ret,
+                               fastly_error_t *err) {
+  // Currently this host-call has been implemented to support the `SimpleCache.getOrSet` method,
+  // which does not use any fields from `fastly_cache_lookup_options_t`.
+  uint32_t options_mask = 0;
+  return convert_result(
+      fastly::cache_transaction_lookup(cache_key->ptr, cache_key->len, options_mask, options, ret),
+      err);
+}
+bool fastly_transaction_insert_and_stream_back(fastly_cache_handle_t handle,
+                                               fastly_cache_write_options_t *options,
+                                               fastly_world_tuple2_body_handle_cache_handle_t *ret,
+                                               fastly_error_t *err) {
+  uint16_t options_mask = 0;
+  fastly::CacheWriteOptions opts;
+  std::memset(&opts, 0, sizeof(opts));
+  opts.max_age_ns = options->max_age_ns;
+
+  MOZ_ASSERT(options->request_headers == INVALID_HANDLE || options->request_headers == 0);
+
+  if (options->vary_rule.ptr != nullptr) {
+    options_mask |= FASTLY_CACHE_WRITE_OPTIONS_MASK_VARY_RULE;
+    opts.vary_rule_len = options->vary_rule.len;
+    opts.vary_rule_ptr = reinterpret_cast<uint8_t *>(options->vary_rule.ptr);
+  }
+  if (options->initial_age_ns != 0) {
+    options_mask |= FASTLY_CACHE_WRITE_OPTIONS_MASK_INITIAL_AGE_NS;
+    opts.initial_age_ns = options->initial_age_ns;
+  }
+  if (options->stale_while_revalidate_ns != 0) {
+    options_mask |= FASTLY_CACHE_WRITE_OPTIONS_MASK_STALE_WHILE_REVALIDATE_NS;
+    opts.stale_while_revalidate_ns = options->stale_while_revalidate_ns;
+  }
+  if (options->surrogate_keys.ptr != nullptr) {
+    options_mask |= FASTLY_CACHE_WRITE_OPTIONS_MASK_SURROGATE_KEYS;
+    opts.surrogate_keys_len = options->surrogate_keys.len;
+    opts.surrogate_keys_ptr = reinterpret_cast<uint8_t *>(options->surrogate_keys.ptr);
+  }
+  if (options->length != 0) {
+    options_mask |= FASTLY_CACHE_WRITE_OPTIONS_MASK_LENGTH;
+    opts.length = options->length;
+  }
+  if (options->user_metadata.ptr != nullptr) {
+    options_mask |= FASTLY_CACHE_WRITE_OPTIONS_MASK_USER_METADATA;
+    opts.user_metadata_len = options->user_metadata.len;
+    opts.user_metadata_ptr = options->user_metadata.ptr;
+  }
+  if (options->sensitive_data) {
+    options_mask |= FASTLY_CACHE_WRITE_OPTIONS_MASK_SENSITIVE_DATA;
+  }
+  return convert_result(fastly::cache_transaction_insert_and_stream_back(handle, options_mask,
+                                                                         &opts, &ret->f0, &ret->f1),
+                        err);
+}
+
+/// Cancel an obligation to provide an object to the cache.
+///
+/// Useful if there is an error before streaming is possible, e.g. if a backend is unreachable.
+bool fastly_transaction_cancel(fastly_cache_handle_t handle, fastly_error_t *err) {
+  return convert_result(fastly::cache_transaction_cancel(handle), err);
+}
+
+bool fastly_cache_get_state(fastly_cache_handle_t handle, fastly_cache_lookup_state_t *ret,
+                            fastly_error_t *err) {
+  return convert_result(fastly::cache_get_state(handle, ret), err);
+}

runtime/js-compute-runtime/fastly-world/fastly_world.h

@@ -540,6 +540,17 @@ default world fastly-world {
       end: u64,
     }
 
+    /// The status of this lookup (and potential transaction)
+    flags cache-lookup-state {
+      /// a cached object was found
+      found,
+      /// the cached object is valid to use (implies found)
+      usable,
+      /// the cached object is stale (but may or may not be valid to use)
+      stale,
+      /// this client is requested to insert or revalidate an object
+      must-insert-or-update,
+    }
 
     /// Performs a non-request-collapsing cache lookup.
     ///
@@ -552,6 +563,30 @@ default world fastly-world {
     /// the cache.
     cache-insert: func(cache-key: string, options: cache-write-options) -> result<body-handle, error>
 
+    /// The entrypoint to the request-collapsing cache transaction API.
+    ///
+    /// This operation always participates in request collapsing and may return stale objects. To bypass
+    /// request collapsing, use `lookup` and `insert` instead.
+    transaction-lookup: func(cache-key: string, options: cache-lookup-options) -> result<cache-handle, error>
+
+    /// Insert an object into the cache with the given metadata, and return a readable stream of the
+    /// bytes as they are stored.
+    ///
+    /// This helps avoid the "slow reader" problem on a teed stream, for example when a program wishes
+    /// to store a backend request in the cache while simultaneously streaming to a client in an HTTP
+    /// response.
+    ///
+    /// The returned body handle is to a streaming body that is used for writing the object _into_
+    /// the cache. The returned cache handle provides a separate transaction for reading out the
+    /// newly cached object to send elsewhere.
+    transaction-insert-and-stream-back: func(handle: cache-handle, options: cache-write-options) -> result<tuple<body-handle, cache-handle>, error>
+
+    /// Cancel an obligation to provide an object to the cache.
+    ///
+    /// Useful if there is an error before streaming is possible, e.g. if a backend is unreachable.
+    transaction-cancel: func(handle: cache-handle) -> result<_, error>
+
+    cache-get-state: func(handle: cache-handle) -> result<cache-lookup-state, error>
 
     /// Gets a range of the found object body, returning the `$none` error if there
     /// was no found object.

runtime/js-compute-runtime/fastly-world/fastly_world_adapter.cpp

@@ -391,6 +391,22 @@ WASM_IMPORT("fastly_cache", "insert")
 int cache_insert(char *cache_key, size_t cache_key_len, uint32_t options_mask,
                  CacheWriteOptions *options, fastly_body_handle_t *ret);
 
+WASM_IMPORT("fastly_cache", "transaction_lookup")
+int cache_transaction_lookup(char *cache_key, size_t cache_key_len, uint32_t options_mask,
+                             fastly_cache_lookup_options_t *options, fastly_cache_handle_t *ret);
+
+WASM_IMPORT("fastly_cache", "transaction_insert_and_stream_back")
+int cache_transaction_insert_and_stream_back(fastly_cache_handle_t handle, uint32_t options_mask,
+                                             CacheWriteOptions *options,
+                                             fastly_body_handle_t *ret_body,
+                                             fastly_cache_handle_t *ret_cache);
+
+WASM_IMPORT("fastly_cache", "transaction_cancel")
+int cache_transaction_cancel(fastly_cache_handle_t handle);
+
+WASM_IMPORT("fastly_cache", "get_state")
+int cache_get_state(fastly_cache_handle_t handle, fastly_cache_lookup_state_t *ret);
+
 WASM_IMPORT("fastly_cache", "get_body")
 int cache_get_body(fastly_cache_handle_t handle, uint32_t options_mask,
                    fastly_cache_get_body_options_t *options, fastly_body_handle_t *ret);

runtime/js-compute-runtime/fastly-world/fastly_world_component_type.o

@@ -3,6 +3,8 @@ declare module "fastly:cache" {
     static get(key: string): SimpleCacheEntry | null;
     static set(key: string, value: BodyInit, ttl: number): undefined;
     static set(key: string, value: ReadableStream, ttl: number, length: number): undefined;
+    static getOrSet(key: string, set: () => Promise<{value: BodyInit,  ttl: number}>): Promise<SimpleCacheEntry>;
+    static getOrSet(key: string, set: () => Promise<{value: ReadableStream, ttl: number, length: number}>): Promise<SimpleCacheEntry>;
     static delete(key: string): undefined;
   }