Add cache: reload as experimental (#4875)

Author: tewaro

src/workerd/api/http-test-ts.ts

@@ -71,6 +71,9 @@ export const cacheMode = {
     if (env.NO_CACHE_ENABLED) {
       enabledCacheModes.add('no-cache');
     }
+    if (env.RELOAD_ENABLED) {
+      enabledCacheModes.add('reload');
+    }
 
     const failureCacheModes = allowedCacheModes.difference(enabledCacheModes);
     for (const cacheMode of failureCacheModes) {

src/workerd/api/http-test-ts.ts-wd-test

@@ -11,6 +11,7 @@ const unitTests :Workerd.Config = (
           ( name = "SERVICE", service = "http-test" ),
           ( name = "CACHE_ENABLED", json = "false" ),
           ( name = "NO_CACHE_ENABLED", json = "false" ),
+          ( name = "RELOAD_ENABLED", json = "false" ),
         ],
         compatibilityDate = "2023-08-01",
         compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_option_disabled"],
@@ -25,6 +26,7 @@ const unitTests :Workerd.Config = (
           ( name = "SERVICE", service = "http-test-cache-option-enabled" ),
           ( name = "CACHE_ENABLED", json = "true" ),
           ( name = "NO_CACHE_ENABLED", json = "false" ),
+          ( name = "RELOAD_ENABLED", json = "false" ),
         ],
         compatibilityDate = "2024-11-11",
         compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers"],
@@ -39,10 +41,27 @@ const unitTests :Workerd.Config = (
           ( name = "SERVICE", service = "http-test-cache-no-cache" ),
           ( name = "CACHE_ENABLED", json = "true" ),
           ( name = "NO_CACHE_ENABLED", json = "true" ),
+          ( name = "RELOAD_ENABLED", json = "false" ),
         ],
         compatibilityDate = "2024-11-11",
         compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_no_cache_enabled"],
       )
     ),
+    ( name = "http-test-cache-reload",
+      worker = (
+        modules = [
+          ( name = "worker-reload", esModule = embed "http-test-ts.js" )
+        ],
+        bindings = [
+          ( name = "SERVICE", service = "http-test-cache-reload" ),
+          ( name = "CACHE_ENABLED", json = "true" ),
+          ( name = "NO_CACHE_ENABLED", json = "true" ),
+          ( name = "RELOAD_ENABLED", json = "true" ),
+        ],
+        compatibilityDate = "2024-11-11",
+        compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers",
+        "cache_no_cache_enabled", "cache_reload_enabled"],
+      )
+    ),
   ],
 );

src/workerd/api/http.c++

@@ -123,6 +123,7 @@ void requireValidHeaderValue(kj::StringPtr value) {
 Request::CacheMode getCacheModeFromName(kj::StringPtr value) {
   if (value == "no-store") return Request::CacheMode::NOSTORE;
   if (value == "no-cache") return Request::CacheMode::NOCACHE;
+  if (value == "reload") return Request::CacheMode::RELOAD;
   JSG_FAIL_REQUIRE(TypeError, kj::str("Unsupported cache mode: ", value));
 }
 
@@ -134,6 +135,8 @@ jsg::Optional<kj::StringPtr> getCacheModeName(Request::CacheMode mode) {
       return "no-cache"_kj;
     case (Request::CacheMode::NOSTORE):
       return "no-store"_kj;
+    case (Request::CacheMode::RELOAD):
+      return "reload"_kj;
   }
   KJ_UNREACHABLE;
 }
@@ -1241,19 +1244,20 @@ kj::Maybe<kj::String> Request::serializeCfBlobJson(jsg::Lock& js) {
   }
   auto obj = KJ_ASSERT_NONNULL(clone.get(js));
 
-  int ttl = 2;
+  constexpr int NOCACHE_TTL = -1;
   switch (cacheMode) {
     case CacheMode::NOSTORE:
-      ttl = -1;
-      obj.set(js, "cacheLevel", js.str("bypass"_kjc));
       if (obj.has(js, "cacheTtl")) {
         jsg::JsValue oldTtl = obj.get(js, "cacheTtl");
-        JSG_REQUIRE(oldTtl == js.num(ttl), TypeError,
+        JSG_REQUIRE(oldTtl == js.num(NOCACHE_TTL), TypeError,
             kj::str("CacheTtl: ", oldTtl, ", is not compatible with cache: ",
                 getCacheModeName(cacheMode).orDefault("none"_kj), " header."));
       } else {
-        obj.set(js, "cacheTtl", js.num(ttl));
+        obj.set(js, "cacheTtl", js.num(NOCACHE_TTL));
       }
+      KJ_FALLTHROUGH;
+    case CacheMode::RELOAD:
+      obj.set(js, "cacheLevel", js.str("bypass"_kjc));
       break;
     case CacheMode::NOCACHE:
       obj.set(js, "cacheForceRevalidate", js.boolean(true));
@@ -1274,10 +1278,12 @@ void RequestInitializerDict::validate(jsg::Lock& js) {
     // Validate that the cache type is valid
     auto cacheMode = getCacheModeFromName(c);
 
-    if (!FeatureFlags::get(js).getCacheNoCache()) {
-      JSG_REQUIRE(cacheMode != Request::CacheMode::NOCACHE, TypeError,
-          kj::str("Unsupported cache mode: ", c));
-    }
+    bool invalidNoCache =
+        !FeatureFlags::get(js).getCacheNoCache() && (cacheMode == Request::CacheMode::NOCACHE);
+    bool invalidReload =
+        !FeatureFlags::get(js).getCacheReload() && (cacheMode == Request::CacheMode::RELOAD);
+    JSG_REQUIRE(
+        !invalidNoCache && !invalidReload, TypeError, kj::str("Unsupported cache mode: ", c));
   }
 
   KJ_IF_SOME(e, encodeResponseBody) {
@@ -1901,11 +1907,12 @@ jsg::Promise<jsg::Ref<Response>> fetchImplNoOutputLock(jsg::Lock& js,
   jsRequest->shallowCopyHeadersTo(headers);
 
   // If the jsRequest has a CacheMode, we need to handle that here.
-  // Currently, the only cache mode we support is undefined and no-store (behind an autogate),
-  // but we will soon support no-cache.
+  // Currently, the only cache mode we support is undefined and no-store, no-cache, and reload
   auto headerIds = ioContext.getHeaderIds();
   const auto cacheMode = jsRequest->getCacheMode();
   switch (cacheMode) {
+    case Request::CacheMode::RELOAD:
+      KJ_FALLTHROUGH;
     case Request::CacheMode::NOSTORE:
       KJ_FALLTHROUGH;
     case Request::CacheMode::NOCACHE:

src/workerd/api/http.h

@@ -800,7 +800,16 @@ struct RequestInitializerDict {
   JSG_STRUCT(method, headers, body, redirect, fetcher, cf, cache, integrity, signal, encodeResponseBody);
   JSG_STRUCT_TS_OVERRIDE_DYNAMIC(CompatibilityFlags::Reader flags) {
     if(flags.getCacheOptionEnabled()) {
-      if(flags.getCacheNoCache()) {
+      if(flags.getCacheReload()) {
+        JSG_TS_OVERRIDE(RequestInit<Cf = CfProperties> {
+          headers?: HeadersInit;
+          body?: BodyInit | null;
+          cache?: 'no-store' | 'no-cache' | 'reload';
+          cf?: Cf;
+          encodeResponseBody?: "automatic" | "manual";
+        });
+
+      } else if(flags.getCacheNoCache()) {
         JSG_TS_OVERRIDE(RequestInit<Cf = CfProperties> {
           headers?: HeadersInit;
           body?: BodyInit | null;
@@ -848,6 +857,7 @@ class Request final: public Body {
     NONE,
     NOSTORE,
     NOCACHE,
+    RELOAD,
   };
 
   Request(jsg::Lock& js, kj::HttpMethod method, kj::StringPtr url, Redirect redirect,
@@ -994,7 +1004,14 @@ class Request final: public Body {
       JSG_READONLY_PROTOTYPE_PROPERTY(keepalive, getKeepalive);
       if(flags.getCacheOptionEnabled()) {
         JSG_READONLY_PROTOTYPE_PROPERTY(cache, getCache);
-        if(flags.getCacheNoCache()) {
+        if(flags.getCacheReload()) {
+          JSG_TS_OVERRIDE(<CfHostMetadata = unknown, Cf = CfProperties<CfHostMetadata>> {
+            constructor(input: RequestInfo<CfProperties> | URL, init?: RequestInit<Cf>);
+            clone(): Request<CfHostMetadata, Cf>;
+            cache?: "no-store" | "no-cache" | "reload";
+            get cf(): Cf | undefined;
+          });
+        } else if(flags.getCacheNoCache()) {
           JSG_TS_OVERRIDE(<CfHostMetadata = unknown, Cf = CfProperties<CfHostMetadata>> {
             constructor(input: RequestInfo<CfProperties> | URL, init?: RequestInit<Cf>);
             clone(): Request<CfHostMetadata, Cf>;

src/workerd/io/compatibility-date.capnp

@@ -1187,6 +1187,7 @@ struct CompatibilityFlags @0x8f8c1b68151b6cef {
   enableCtxExports @139 :Bool
     $compatEnableFlag("enable_ctx_exports");
   # Enable the ctx.exports API.
+
   pythonExternalSDK @140 :Bool
     $compatEnableFlag("enable_python_external_sdk")
     $compatDisableFlag("disable_python_external_sdk")
@@ -1201,4 +1202,10 @@ struct CompatibilityFlags @0x8f8c1b68151b6cef {
   # However, optional fields will be explicitly set to undefined rather than
   # being omitted, which is an observable behavior change.
   # TODO(soon): Once proven in production, add a default on date
+
+  cacheReload @142 :Bool
+      $compatEnableFlag("cache_reload_enabled")
+      $compatDisableFlag("cache_reload_disabled")
+      $experimental;
+  # Enables the use of cache: reload in the fetch api.
 }

types/generated-snapshot/experimental/index.d.ts

@@ -2128,7 +2128,7 @@ interface Request<CfHostMetadata = unknown, Cf = CfProperties<CfHostMetadata>>
    *
    * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/cache)
    */
-  cache?: "no-store" | "no-cache";
+  cache?: "no-store" | "no-cache" | "reload";
 }
 interface RequestInit<Cf = CfProperties> {
   /* A string to set request's method. */
@@ -2142,7 +2142,7 @@ interface RequestInit<Cf = CfProperties> {
   fetcher?: Fetcher | null;
   cf?: Cf;
   /* A string indicating how the request will interact with the browser's cache to set request's cache. */
-  cache?: "no-store" | "no-cache";
+  cache?: "no-store" | "no-cache" | "reload";
   /* A cryptographic hash of the resource to be fetched by request. Sets request's integrity. */
   integrity?: string;
   /* An AbortSignal to set request's signal. */

types/generated-snapshot/experimental/index.ts

@@ -2136,7 +2136,7 @@ export interface Request<
    *
    * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/cache)
    */
-  cache?: "no-store" | "no-cache";
+  cache?: "no-store" | "no-cache" | "reload";
 }
 export interface RequestInit<Cf = CfProperties> {
   /* A string to set request's method. */
@@ -2150,7 +2150,7 @@ export interface RequestInit<Cf = CfProperties> {
   fetcher?: Fetcher | null;
   cf?: Cf;
   /* A string indicating how the request will interact with the browser's cache to set request's cache. */
-  cache?: "no-store" | "no-cache";
+  cache?: "no-store" | "no-cache" | "reload";
   /* A cryptographic hash of the resource to be fetched by request. Sets request's integrity. */
   integrity?: string;
   /* An AbortSignal to set request's signal. */