Server side query retry and caching with request scoped QueryClient (#2596)

* Server side query retry and caching with request scoped QueryClient and native fetch for axios

* Default to force-cache on fetch options. ESLint rule to prevent use of API outside a Query Client

* Status on axios error

* Update comment

* Hydration issues with non-serializable error response. Sanitize axios errors and remove from query client

* Remove catch - prefetch does not throw

* Safe generate metadata utility with error catch

* Remove use of native fetch

* Update tests to expect console calls

* Remove comment

* Update comment

Co-authored-by: Chris Chudzicki <christopher.chudzicki@gmail.com>

* Update to use query client for API calls / no direct API client import

* Metadata fallback not used

* Remove not used debug props. Update test for standardized metadata fallback

---------

Co-authored-by: Chris Chudzicki <christopher.chudzicki@gmail.com>

Author: jonkafton

frontends/.eslintrc.js

@@ -68,6 +68,11 @@ module.exports = {
           message:
             "The LearningResourceDrawer should be lazy loaded with dynamic import.",
         },
+        {
+          group: ["api/clients"],
+          message:
+            "Direct import from 'api/clients' is not allowed. Use React Query hooks from 'api/hooks/*' instead for caching and error handling. In server components, use getServerQueryClient().fetchQuery(), passing the queryOptions.",
+        },
       ],
     }),
     // This rule is disabled in the default a11y config, but unclear why.
@@ -145,6 +150,12 @@ module.exports = {
         message:
           "Do not specify `fontFamily` manually. Prefer spreading `theme.typography.subtitle1` or similar. If using neue-haas-grotesk-text, this is ThemeProvider's default fontFamily.",
       },
+      {
+        selector:
+          "FunctionDeclaration[id.name='generateMetadata'] > BlockStatement > ReturnStatement[argument.type!='CallExpression'], FunctionDeclaration[id.name='generateMetadata'] > BlockStatement > ReturnStatement[argument.callee.name!='safeGenerateMetadata']",
+        message:
+          "generateMetadata functions must return safeGenerateMetadata() to ensure proper error handling and fallback metadata.",
+      },
     ],
   },
   overrides: [

frontends/api/package.json

@@ -5,15 +5,13 @@
   "sideEffects": false,
   "exports": {
     ".": "./src/generated/v1/api.ts",
-    "./clients": "./src/clients.ts",
     "./v0": "./src/generated/v0/api.ts",
     "./v1": "./src/generated/v1/api.ts",
     "./hooks/*": "./src/hooks/*/index.ts",
     "./constants": "./src/common/constants.ts",
     "./ssr/*": "./src/ssr/*.ts",
     "./test-utils/factories": "./src/test-utils/factories/index.ts",
     "./test-utils": "./src/test-utils/index.ts",
-    "./mitxonline": "./src/mitxonline/index.ts",
     "./mitxonline-hooks/*": "./src/mitxonline/hooks/*/index.ts",
     "./mitxonline-test-utils": "./src/mitxonline/test-utils/index.ts"
   },

frontends/api/src/hooks/learningResources/queries.ts

@@ -18,6 +18,7 @@ import type {
   FeaturedApiFeaturedListRequest as FeaturedListParams,
   LearningResourcesApiLearningResourcesItemsListRequest as ItemsListRequest,
   LearningResourcesSearchResponse,
+  LearningResourcesApiLearningResourcesSummaryListRequest as LearningResourcesSummaryListRequest,
 } from "../../generated/v1"
 import { queryOptions } from "@tanstack/react-query"
 import { hasPosition, randomizeGroups } from "./util"
@@ -46,6 +47,11 @@ const learningResourceKeys = {
     ...learningResourceKeys.listsRoot(),
     params,
   ],
+  summaryListRoot: () => [...learningResourceKeys.root, "summaryList"],
+  summaryList: (params: LearningResourcesSummaryListRequest) => [
+    ...learningResourceKeys.summaryListRoot(),
+    params,
+  ],
   // detail
   detailsRoot: () => [...learningResourceKeys.root, "detail"],
   detail: (id: number) => [...learningResourceKeys.detailsRoot(), id],
@@ -150,6 +156,14 @@ const learningResourceQueries = {
           results: res.data.results.map(clearListMemberships),
         })),
     }),
+  summaryList: (params: LearningResourcesSummaryListRequest) =>
+    queryOptions({
+      queryKey: learningResourceKeys.summaryList(params),
+      queryFn: () =>
+        learningResourcesApi
+          .learningResourcesSummaryList(params)
+          .then((res) => res.data),
+    }),
   featured: (params: FeaturedListParams = {}) =>
     queryOptions({
       queryKey: learningResourceKeys.featured(params),

frontends/api/src/mitxonline/index.ts

@@ -1,71 +1,31 @@
-import { QueryClient, dehydrate } from "@tanstack/react-query"
+import { dehydrate } from "@tanstack/react-query"
+import { getServerQueryClient } from "./serverQueryClient"
 import type { Query } from "@tanstack/react-query"
 
-const MAX_RETRIES = 3
-const NO_RETRY_CODES = [400, 401, 403, 404, 405, 409, 422]
-
-type MaybeHasStatus = {
-  response?: {
-    status?: number
-  }
-}
-
-const getPrefetchQueryClient = () => {
-  return new QueryClient({
-    defaultOptions: {
-      queries: {
-        /**
-         * React Query's default retry logic is only active in the browser.
-         * Here we explicitly configure it to retry MAX_RETRIES times on
-         * the server, with an exclusion list of statuses that we expect not
-         * to succeed on retry.
-         *
-         * Includes status undefined as we want to retry on network errors
-         */
-        retry: (failureCount, error) => {
-          const status = (error as MaybeHasStatus)?.response?.status
-          const isNetworkError = status === undefined || status === 0
-
-          if (isNetworkError || !NO_RETRY_CODES.includes(status)) {
-            return failureCount < MAX_RETRIES
-          }
-          return false
-        },
-
-        /**
-         * By default, React Query gradually applies a backoff delay, though it is
-         * preferable that we do not significantly delay initial page renders (or
-         * indeed pages that are Statically Rendered during the build process) and
-         * instead allow the request to fail quickly so it can be subsequently
-         * fetched on the client.
-         */
-        retryDelay: 1000,
-      },
-    },
-  })
-}
-
-/* Utility to avoid repetition in server components
+/**
+ * Utility to avoid repetition in server components
  * Optionally pass the queryClient returned from a previous prefetch
  * where queries are dependent on previous results
  */
 export const prefetch = async (
   queries: (Query | unknown)[],
 
   /**
-   * The SSR QueryClient is transient - it is created only for prefetch
-   * while API requests are made to server render the page and discarded
-   * as the dehydrated state is produced and sent to the client.
+   * Unless passed, the SSR QueryClient uses React's cache() for reuse for the duration of the request.
    *
-   * Create a new query client if one is not provided.
+   * The QueryClient is garbage collected once the dehydrated state is produced and
+   * sent to the client and the request is complete.
    */
-  queryClient = getPrefetchQueryClient(),
+  queryClient = getServerQueryClient(),
 ) => {
   await Promise.all(
-    queries
-      .filter(Boolean)
-      .map((query) => queryClient.prefetchQuery(query as Query)),
+    queries.filter(Boolean).map((query) => {
+      return queryClient.prefetchQuery(query as Query)
+    }),
   )
 
-  return { dehydratedState: dehydrate(queryClient), queryClient }
+  return {
+    dehydratedState: dehydrate(queryClient),
+    queryClient,
+  }
 }

frontends/api/src/ssr/prefetch.ts

@@ -0,0 +1,76 @@
+import { cache } from "react"
+import { QueryClient } from "@tanstack/react-query"
+import { AxiosError } from "axios"
+
+const MAX_RETRIES = 3
+const NO_RETRY_CODES = [400, 401, 403, 404, 405, 409, 422]
+
+/**
+ * Get or create a server-side QueryClient for consistent retry behavior.
+ * The server QueryClient should be used for all server-side API calls.
+ *
+ * Uses React's cache() to ensure the same QueryClient instance is reused
+ * throughout a single HTTP request, enabling:
+ *
+ * - Server API calls share the same QueryClient:
+ *   - Prefetch runs in page server components
+ *   - generateMetadata()
+ * - No duplicate API calls within the same request
+ * - Automatic cleanup when the request completes
+ * - Isolation between different HTTP requests
+ *
+ * The QueryClientProvider runs (during SSR) in a separate render pass as it's a
+ * client component and so the instance is not reused. On the server this does not
+ * make API calls and only sets up the hydration boundary and registers hooks in
+ * readiness for the dehydrated state to be sent to the client.
+ */
+const getServerQueryClient = cache(() => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        /**
+         * React Query's default retry logic is only active in the browser.
+         * Here we explicitly configure it to retry MAX_RETRIES times on
+         * the server, with an exclusion list of statuses that we expect not
+         * to succeed on retry.
+         *
+         * Includes status undefined as we want to retry on network errors
+         */
+        retry: (failureCount, error) => {
+          const axiosError = error as AxiosError
+          console.info("Retrying failed request", {
+            failureCount,
+            error: {
+              message: axiosError.message,
+              name: axiosError.name,
+              status: axiosError?.status,
+              code: axiosError.code,
+              method: axiosError.request?.method,
+              url: axiosError.request?.url,
+            },
+          })
+          const status = (error as AxiosError)?.response?.status
+          const isNetworkError = status === undefined || status === 0
+
+          if (isNetworkError || !NO_RETRY_CODES.includes(status)) {
+            return failureCount < MAX_RETRIES
+          }
+          return false
+        },
+
+        /**
+         * By default, React Query gradually applies a backoff delay, though it is
+         * preferable that we do not significantly delay initial page renders (or
+         * indeed pages that are Statically Rendered during the build process) and
+         * instead allow the request to fail quickly so it can be subsequently
+         * fetched on the client.
+         */
+        retryDelay: 1000,
+      },
+    },
+  })
+
+  return queryClient
+})
+
+export { getServerQueryClient }

frontends/api/src/ssr/serverQueryClient.ts

@@ -22,6 +22,7 @@
     "@sentry/nextjs": "^10.0.0",
     "@tanstack/react-query": "^5.66",
     "api": "workspace:*",
+    "async_hooks": "^1.0.0",
     "classnames": "^2.5.1",
     "formik": "^2.4.6",
     "iso-639-1": "^3.1.4",

frontends/main/package.json

@@ -1,29 +1,30 @@
 import React from "react"
 import { HydrationBoundary } from "@tanstack/react-query"
-import { standardizeMetadata } from "@/common/metadata"
+import { safeGenerateMetadata, standardizeMetadata } from "@/common/metadata"
 import { prefetch } from "api/ssr/prefetch"
 import CoursePage from "@/app-pages/ProductPages/CoursePage"
-import { pagesApi } from "api/mitxonline"
-import * as Sentry from "@sentry/nextjs"
 import { notFound } from "next/navigation"
 import { pagesQueries } from "api/mitxonline-hooks/pages"
 import { coursesQueries } from "api/mitxonline-hooks/courses"
 import { DEFAULT_RESOURCE_IMG } from "ol-utilities"
+import { getServerQueryClient } from "api/ssr/serverQueryClient"
 
 export const generateMetadata = async (
   props: PageProps<"/courses/[readable_id]">,
 ) => {
   const params = await props.params
 
-  try {
-    const resp = await pagesApi.pagesfieldstypecmsCoursepageRetrieve({
-      readable_id: decodeURIComponent(params.readable_id),
-    })
+  return safeGenerateMetadata(async () => {
+    const queryClient = getServerQueryClient()
+
+    const data = await queryClient.fetchQuery(
+      pagesQueries.coursePages(decodeURIComponent(params.readable_id)),
+    )
 
-    if (resp.data.items.length === 0) {
+    if (data.items.length === 0) {
       notFound()
     }
-    const [course] = resp.data.items
+    const [course] = data.items
     const image = course.feature_image
       ? course.course_details.page.feature_image_src
       : DEFAULT_RESOURCE_IMG
@@ -32,14 +33,7 @@ export const generateMetadata = async (
       image,
       robots: "noindex, nofollow",
     })
-  } catch (error) {
-    Sentry.captureException(error)
-    console.error(
-      "Error fetching course page metadata for",
-      params.readable_id,
-      error,
-    )
-  }
+  })
 }
 
 const Page: React.FC<PageProps<"/courses/[readable_id]">> = async (props) => {

frontends/main/src/app/(products)/courses/[readable_id]/page.tsx

@@ -1,29 +1,30 @@
 import React from "react"
 import { HydrationBoundary } from "@tanstack/react-query"
-import { standardizeMetadata } from "@/common/metadata"
+import { safeGenerateMetadata, standardizeMetadata } from "@/common/metadata"
 import { prefetch } from "api/ssr/prefetch"
 import ProgramPage from "@/app-pages/ProductPages/ProgramPage"
-import { pagesApi } from "api/mitxonline"
-import * as Sentry from "@sentry/nextjs"
 import { notFound } from "next/navigation"
 import { pagesQueries } from "api/mitxonline-hooks/pages"
 import { programsQueries } from "api/mitxonline-hooks/programs"
 import { DEFAULT_RESOURCE_IMG } from "ol-utilities"
+import { getServerQueryClient } from "api/ssr/serverQueryClient"
 
 export const generateMetadata = async (
   props: PageProps<"/programs/[readable_id]">,
 ) => {
   const params = await props.params
 
-  try {
-    const resp = await pagesApi.pagesfieldstypecmsProgrampageRetrieve({
-      readable_id: decodeURIComponent(params.readable_id),
-    })
+  return safeGenerateMetadata(async () => {
+    const queryClient = getServerQueryClient()
+
+    const data = await queryClient.fetchQuery(
+      pagesQueries.programPages(decodeURIComponent(params.readable_id)),
+    )
 
-    if (resp.data.items.length === 0) {
+    if (data.items.length === 0) {
       notFound()
     }
-    const [program] = resp.data.items
+    const [program] = data.items
 
     // Note: feature_image.src is relative to mitxonline root.
     const image = program.feature_image
@@ -34,17 +35,10 @@ export const generateMetadata = async (
       image,
       robots: "noindex, nofollow",
     })
-  } catch (error) {
-    Sentry.captureException(error)
-    console.error(
-      "Error fetching course page metadata for",
-      params.readable_id,
-      error,
-    )
-  }
+  })
 }
 
-const Page: React.FC<PageProps<"/courses/[readable_id]">> = async (props) => {
+const Page: React.FC<PageProps<"/programs/[readable_id]">> = async (props) => {
   const params = await props.params
   const readableId = decodeURIComponent(params.readable_id)
   /**