feat(isr): added background revalidation and non-blocking render

maxisam · eneajaho · commit f41d38fc4339 · 2024-09-01T11:29:34.000+02:00
diff --git a/apps/ssr-isr/server.ts b/apps/ssr-isr/server.ts
@@ -31,8 +31,9 @@ export function app(): express.Express {
     browserDistFolder,
     bootstrap,
     commonEngine,
+    backgroundRevalidation: true, // will revalidate in background and serve the cache page first
+    nonBlockingRender: true, // will serve page first and store in cache in background
     modifyGeneratedHtml: defaultModifyGeneratedHtml,
-
     // cache: fsCacheHandler,
   });
 
diff --git a/libs/isr/models/src/isr-handler-config.ts b/libs/isr/models/src/isr-handler-config.ts
@@ -113,6 +113,17 @@ export interface ISRHandlerConfig {
    * which only add commented text to the html to indicate when it was generated.
    */
   modifyGeneratedHtml?: ModifyHtmlCallbackFn;
+
+  /**
+   * If set to true, the server will not wait for storing the rendered page to the cache storage first and will return the rendered HTML as soon as possible.
+   * This can avoid client-side waiting times if the remote cache storage is down.
+   */
+  nonBlockingRender?: boolean;
+
+  /**
+   * If set to true, the server will provide the cached HTML as soon as possible and will revalidate the cache in the background.
+   */
+  backgroundRevalidation?: boolean;
 }
 
 export interface ServeFromCacheConfig {
diff --git a/libs/isr/server/src/cache-generation.ts b/libs/isr/server/src/cache-generation.ts
@@ -104,10 +104,17 @@ export class CacheGeneration {
         return { html: finalHtml };
       }
       // add the regenerated page to cache
-      await this.cache.add(cacheKey, finalHtml, {
-        revalidate,
-        buildId: this.isrConfig.buildId,
-      });
+      if (this.isrConfig.nonBlockingRender) {
+        this.cache.add(cacheKey, finalHtml, {
+          revalidate,
+          buildId: this.isrConfig.buildId,
+        });
+      } else {
+        await this.cache.add(cacheKey, finalHtml, {
+          revalidate,
+          buildId: this.isrConfig.buildId,
+        });
+      }
       if (mode === 'regenerate') {
         // remove from urlsOnHold because we are done
         this.urlsOnHold = this.urlsOnHold.filter((x) => x !== cacheKey);
diff --git a/libs/isr/server/src/cache-handlers/filesystem-cache-handler.ts b/libs/isr/server/src/cache-handlers/filesystem-cache-handler.ts
@@ -76,14 +76,20 @@ export class FileSystemCacheHandler extends CacheHandler {
 
       if (cachedRoute) {
         // on html field we have saved path to file
-        this.readFromFile(cachedRoute.htmlFilePath).then((html) => {
-          const cacheData: CacheData = {
-            html,
-            options: cachedRoute.options,
-            createdAt: cachedRoute.createdAt,
-          };
-          resolve(cacheData);
-        });
+        this.readFromFile(cachedRoute.htmlFilePath)
+          .then((html) => {
+            const cacheData: CacheData = {
+              html,
+              options: cachedRoute.options,
+              createdAt: cachedRoute.createdAt,
+            };
+            resolve(cacheData);
+          })
+          .catch((err) => {
+            reject(
+              `Error: 💥 Cannot read cache file for route ${route}: ${cachedRoute.htmlFilePath}, ${err}`,
+            );
+          });
       } else {
         reject('Error: 💥 Url is not cached.');
       }
diff --git a/libs/isr/server/src/isr-handler.ts b/libs/isr/server/src/isr-handler.ts
@@ -188,34 +188,46 @@ export class ISRHandler {
         return;
       }
 
-      // Apply the callback if given
-      let finalHtml = html;
-      if (config?.modifyCachedHtml) {
-        const timeStart = performance.now();
-        finalHtml = config.modifyCachedHtml(req, html);
-        const totalTime = (performance.now() - timeStart).toFixed(2);
-        finalHtml += `<!--\nℹ️ ISR: This cachedHtml has been modified with modifyCachedHtml()\n❗️
-        This resulted into more ${totalTime}ms of processing time.\n-->`;
-      }
-
       // Cache exists. Send it.
       this.logger.log(`Page was retrieved from cache: `, cacheKey);
+      let finalHtml = html;
 
       // if the cache is expired, we will regenerate it
       if (cacheConfig.revalidate && cacheConfig.revalidate > 0) {
         const lastCacheDateDiff = (Date.now() - createdAt) / 1000; // in seconds
 
         if (lastCacheDateDiff > cacheConfig.revalidate) {
           // regenerate the page without awaiting, so the user gets the cached page immediately
-          this.cacheGeneration.generateWithCacheKey(
-            req,
-            res,
-            cacheKey,
-            config?.providers,
-            'regenerate',
-          );
+          if (this.isrConfig.backgroundRevalidation) {
+            this.cacheGeneration.generateWithCacheKey(
+              req,
+              res,
+              cacheKey,
+              config?.providers,
+              'regenerate',
+            );
+          } else {
+            const result = await this.cacheGeneration.generateWithCacheKey(
+              req,
+              res,
+              cacheKey,
+              config?.providers,
+              'regenerate',
+            );
+            if (result?.html) {
+              finalHtml = result.html;
+            }
+          }
         }
       }
+      // Apply the callback if given
+      if (config?.modifyCachedHtml) {
+        const timeStart = performance.now();
+        finalHtml = config.modifyCachedHtml(req, finalHtml);
+        const totalTime = (performance.now() - timeStart).toFixed(2);
+        finalHtml += `<!--\nℹ️ ISR: This cachedHtml has been modified with modifyCachedHtml()\n❗️
+              This resulted into more ${totalTime}ms of processing time.\n-->`;
+      }
       return res.send(finalHtml);
     } catch (error) {
       // Cache does not exist. Serve user using SSR
