feat(web-fragments): add fragment fetch failing handling

Author: dario-piotrowicz

e2e/pierced-react/functions/_middleware.ts

@@ -1,6 +1,13 @@
 import { FragmentGateway, getPagesMiddleware } from 'web-fragments/gateway';
 
-const gateway = new FragmentGateway({
+const getGatewayMiddleware: ((devMode: boolean) => PagesFunction) & {
+  _gatewayMiddleware?: PagesFunction;
+} = (devMode) => {
+  if (getGatewayMiddleware._gatewayMiddleware) {
+    return getGatewayMiddleware._gatewayMiddleware;
+  }
+
+  const gateway = new FragmentGateway({
     prePiercingStyles: `<style id="fragment-piercing-styles" type="text/css">
       fragment-host[data-piercing="true"] {
         position: absolute;
@@ -13,16 +20,29 @@ const gateway = new FragmentGateway({
         }
       }
     </style>`
-});
+  });
 
-gateway.registerFragment({
+  gateway.registerFragment({
     fragmentId: "remix",
     prePiercingClassNames: ['remix'],
     routePatterns: ["/", "/_fragment/remix/:_*"],
     // Note: make sure to run the pierced-react-remix-fragment (with remix-serve)
     upstream: "http://localhost:3000",
-});
+    onFragmentFailedFetch: () => {
+      return new Response(
+        "<p id='remix-fragment-not-found'><style>#remix-fragment-not-found { color: red; font-size: 2rem; }</style>Remix fragment not found</p>",
+        { headers: [["content-type", "text/html"]] }
+      );
+    },
+  });
 
-const gatewayMiddleware = getPagesMiddleware(gateway);
+  getGatewayMiddleware._gatewayMiddleware = getPagesMiddleware(gateway, devMode);
+  return getGatewayMiddleware._gatewayMiddleware;
+};
 
-export const onRequest = gatewayMiddleware;
+export const onRequest: PagesFunction<{ DEV_MODE?: boolean }> = async (
+  context
+) => {
+  const gatewayMiddleware = getGatewayMiddleware(!!context.env.DEV_MODE);
+  return gatewayMiddleware(context);
+};

e2e/pierced-react/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "pnpm run --stream --parallel '/^dev:.*/'",
-    "dev:pages": "wrangler pages dev",
+    "dev:pages": "wrangler pages dev --binding DEV_MODE=true",
     "dev:vite": "vite build -w",
     "build": "tsc -b && vite build",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",

e2e/pierced-react/tsconfig.pages-functions.json

@@ -2,7 +2,9 @@
   "compilerOptions": {
     "composite": true,
     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "lib": ["ESNext"],
     "skipLibCheck": true,
+    "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
     "allowSyntheticDefaultImports": true,

packages/web-fragments/src/gateway/fragment-gateway.ts

@@ -27,15 +27,29 @@ export interface FragmentConfig {
    * This will be fetched on any request paths matching the specified `routePatterns`
    */
   upstream: string;
+  /**
+   * Handler/Fallback to apply when the fetch for a fragment ssr code fails.
+   * It allows the gateway to serve the provided fallback response instead of an error response straight
+   * from the server.
+   *
+   * @param req the request sent to the fragment
+   * @param failedRes the failed response (with a 4xx or 5xx status) or the thrown error
+   * @returns the response to use for the document's ssr
+   */
+  onFragmentFailedFetch?: (req: RequestInfo, failedResOrError: Response|unknown) => Response|Promise<Response>;
+}
+
+type FragmentGatewayConfig = {
+  prePiercingStyles?: string;
 }
 
 export class FragmentGateway {
   private fragmentConfigs: Map<string, FragmentConfig> = new Map();
   private routeMap: Map<MatchFunction, FragmentConfig> = new Map();
   #prePiercingStyles: string;
 
-  constructor(options?: { prePiercingStyles?: string }) {
-    this.#prePiercingStyles = options?.prePiercingStyles ?? '';
+  constructor(config?: FragmentGatewayConfig) {
+    this.#prePiercingStyles = config?.prePiercingStyles ?? '';
   }
 
   get prePiercingStyles() {

packages/web-fragments/src/gateway/pagesMiddleware.ts

@@ -7,6 +7,7 @@ const fragmentHostInitialization = ({ content, classNames }: {content: string; c
 
 export function getPagesMiddleware(
   gateway: FragmentGateway,
+  devMode: boolean,
 ): PagesFunction<unknown> {
   return async ({ request, next }) => {
     /**
@@ -19,10 +20,10 @@ export function getPagesMiddleware(
      * reload) in the reframed context has the correct url.
      */
     if (request.headers.get('sec-fetch-dest') === 'iframe') {
-        const matchedFragment = gateway.matchRequestToFragment(request);
-        if (matchedFragment) {
-            return new Response('<!doctype html><title>');
-        }
+      const matchedFragment = gateway.matchRequestToFragment(request);
+      if (matchedFragment) {
+        return new Response('<!doctype html><title>');
+      }
     }
 
     // If this is a document request, we should bail and
@@ -52,8 +53,8 @@ export function getPagesMiddleware(
         const requestUrl = new URL(request.url);
 
         const upstreamUrl = new URL(
-            `${requestUrl.pathname}${requestUrl.search}`,
-            matchedFragment.upstream,
+          `${requestUrl.pathname}${requestUrl.search}`,
+          matchedFragment.upstream,
         );
 
         // TODO: this logic should not be here but in the reframed package (and imported and used here)
@@ -63,12 +64,39 @@ export function getPagesMiddleware(
           element(element) {
             const scriptType = element.getAttribute('type');
             if(scriptType) {
-                element.setAttribute('data-script-type', scriptType);
+              element.setAttribute('data-script-type', scriptType);
             }
             element.setAttribute('type', 'inert');
           }
         });
-        const fragmentRes = scriptRewriter.transform(await fetch(upstreamUrl, { ...request }));
+
+        const fragmentReq: RequestInfo = { ...request, url: upstreamUrl };
+        let fragmentRes: Response;
+        let fragmentFailedResOrError: Response | unknown | null = null;
+        try {
+          fragmentRes = scriptRewriter.transform(await fetch(fragmentReq));
+          if (fragmentRes.status >= 400 && fragmentRes.status <= 500) {
+            fragmentFailedResOrError = fragmentRes;
+          }
+        } catch (e) {
+          fragmentFailedResOrError = e;
+        }
+
+        if (fragmentFailedResOrError) {
+          if (matchedFragment.onFragmentFailedFetch) {
+            fragmentRes = await matchedFragment.onFragmentFailedFetch(
+              fragmentReq,
+              fragmentFailedResOrError
+            );
+          } else {
+            fragmentRes = new Response(
+              devMode
+                ? `<p>Fetching fragment upstream failed: ${matchedFragment.upstream}</p>`
+                : "<p>There was a problem fulfilling your request.</p>",
+              { headers: [["content-type", "text/html"]] }
+            );
+          }
+        }
 
         const rewriter = new HTMLRewriter()
           .on('head', {