[DEV-3615] Fix Metadata Cache to Support Locale (#2025)

* Refactor metadata caching to support locale and improve cache management

* Refactor metadata caching to use generic types and improve locale support

* Add changeset

* Fix metadata cache to support locale matching in fetchMetadataWithCache

* Fix metadata cache logic to correctly handle locale filtering

* Refactor generateMetadata and getGuidePage to improve locale handling

* Remove import

Author: Sebastiano-Bertolin

.changeset/big-bottles-learn.md

@@ -0,0 +1,5 @@
+---
+"nextjs-website": patch
+---
+
+Refactor metadata caching to use generic types and improve locale support

apps/nextjs-website/src/app/[locale]/[productSlug]/guides/[...productGuidePage]/page.tsx

@@ -51,11 +51,11 @@ export type ProductGuidePageProps = {
 export async function generateMetadata(props: {
   params: Promise<Params>;
 }): Promise<Metadata> {
-  const params = await props.params;
+  const { locale, productGuidePage, productSlug } = await props.params;
   const guidePageProps = await getGuidePage(
-    params?.productGuidePage ?? [''],
-    params?.locale,
-    params?.productSlug
+    productGuidePage ?? [''],
+    locale,
+    productSlug
   );
 
   if (guidePageProps?.seo) {

apps/nextjs-website/src/helpers/s3Metadata.helpers.ts

@@ -205,47 +205,72 @@ const S3_SOAP_API_METADATA_JSON_PATH =
   process.env.S3_SOAP_API_METADATA_JSON_PATH ||
   'soap-api/soap-api-metadata.json';
 
-let guidesMetadataCache: readonly JsonMetadata[] | null = null;
-let solutionsMetadataCache: readonly JsonMetadata[] | null = null;
-let releaseNotesMetadataCache: readonly JsonMetadata[] | null = null;
-let soapApiMetadataCache: readonly SoapApiJsonMetadata[] | null = null;
-
-// Add timestamp-based cache invalidation
-// eslint-disable-next-line functional/no-let
-let guidesMetadataCacheTime = 0;
-
-// eslint-disable-next-line functional/no-let
-let solutionsMetadataCacheTime = 0;
+type MetadataCacheItem<T> = {
+  readonly category: string;
+  readonly locale: string;
+  readonly data: readonly T[] | null;
+  readonly refreshTime: number;
+};
 
-// eslint-disable-next-line functional/no-let
-let releaseNotesMetadataCacheTime = 0;
+let metadataCache: readonly MetadataCacheItem<Record<string, unknown>>[] = [];
 
 const METADATA_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 
-export const getGuidesMetadata = async (locale: string, dirName?: string) => {
+async function fetchMetadataWithCache<T extends { readonly dirName: string }>(
+  locale: string,
+  metadataCategory: string,
+  fetchFunction: () => Promise<readonly T[] | null>,
+  dirName?: string
+): Promise<MetadataCacheItem<T>> {
   const now = Date.now();
-
-  if (
-    guidesMetadataCache &&
-    now - guidesMetadataCacheTime < METADATA_CACHE_TTL &&
-    (!dirName || guidesMetadataCache.some((m) => m.dirName === dirName))
-  ) {
-    return guidesMetadataCache;
+  const cacheResult = metadataCache.find((item) => {
+    const categoryMatch = item.category === metadataCategory;
+    const localeMatch = item.locale === locale;
+    const timeMatch = item.data && now - item.refreshTime < METADATA_CACHE_TTL;
+    const dirNameMatch =
+      !dirName ||
+      (Array.isArray(item.data) &&
+        item.data.length > 0 &&
+        'dirName' in item.data[0] &&
+        item.data.some((m: Record<string, unknown>) => m.dirName === dirName));
+    return categoryMatch && localeMatch && timeMatch && dirNameMatch;
+  }) as MetadataCacheItem<T> | undefined;
+
+  if (cacheResult) {
+    return cacheResult;
   }
 
-  guidesMetadataCache = await fetchMetadataFromCDN<JsonMetadata>(
+  const fetchMetadataResult = await fetchFunction();
+
+  const newCacheItem: MetadataCacheItem<T> = {
+    category: metadataCategory,
+    locale,
+    data: fetchMetadataResult,
+    refreshTime: now,
+  };
+
+  metadataCache = [
+    ...metadataCache.filter(
+      (item) => !(item.category === metadataCategory && item.locale === locale)
+    ),
+    newCacheItem,
+  ];
+
+  return newCacheItem;
+}
+
+export const getGuidesMetadata = async (locale: string, dirName?: string) => {
+  const fetchFromCdnPath = dirName
+    ? path.join(locale, S3_PATH_TO_GITBOOK_DOCS, dirName, S3_METADATA_JSON_PATH)
+    : `${locale}/${S3_GUIDES_METADATA_JSON_PATH}`;
+  const cacheResult = await fetchMetadataWithCache<JsonMetadata>(
+    locale,
+    'guides',
+    () => fetchMetadataFromCDN<JsonMetadata>(fetchFromCdnPath),
     dirName
-      ? path.join(
-          locale,
-          S3_PATH_TO_GITBOOK_DOCS,
-          dirName,
-          S3_METADATA_JSON_PATH
-        )
-      : `${locale}/${S3_GUIDES_METADATA_JSON_PATH}`
   );
-  guidesMetadataCacheTime = now;
 
-  return guidesMetadataCache || [];
+  return cacheResult.data || [];
 };
 
 const removeTrailingSlash = (value: string) => value.replace(/\/+$/, '');
@@ -324,29 +349,18 @@ export const getSolutionsMetadata = async (
   locale: string,
   dirName?: string
 ) => {
-  const now = Date.now();
-
-  if (
-    solutionsMetadataCache &&
-    now - solutionsMetadataCacheTime < METADATA_CACHE_TTL &&
-    (!dirName || solutionsMetadataCache.some((m) => m.dirName === dirName))
-  ) {
-    return solutionsMetadataCache;
-  }
-
-  solutionsMetadataCache = await fetchMetadataFromCDN<JsonMetadata>(
+  const fetchFromCdnPath = dirName
+    ? path.join(locale, S3_PATH_TO_GITBOOK_DOCS, dirName, S3_METADATA_JSON_PATH)
+    : `${locale}/${S3_SOLUTIONS_METADATA_JSON_PATH}`;
+
+  const cacheResult = await fetchMetadataWithCache<JsonMetadata>(
+    locale,
+    'solutions',
+    () => fetchMetadataFromCDN<JsonMetadata>(fetchFromCdnPath),
     dirName
-      ? path.join(
-          locale,
-          S3_PATH_TO_GITBOOK_DOCS,
-          dirName,
-          S3_METADATA_JSON_PATH
-        )
-      : `${locale}/${S3_SOLUTIONS_METADATA_JSON_PATH}`
   );
-  solutionsMetadataCacheTime = now;
 
-  return solutionsMetadataCache || [];
+  return cacheResult.data || [];
 };
 
 export const getReleaseNotesMetadataByDirNames = async (
@@ -368,36 +382,29 @@ export const getReleaseNotesMetadata = async (
   locale: string,
   dirName?: string
 ) => {
-  const now = Date.now();
-
-  if (
-    releaseNotesMetadataCache &&
-    now - releaseNotesMetadataCacheTime < METADATA_CACHE_TTL &&
-    (!dirName || releaseNotesMetadataCache.some((m) => m.dirName === dirName))
-  ) {
-    return releaseNotesMetadataCache;
-  }
-
-  releaseNotesMetadataCache = await fetchMetadataFromCDN<JsonMetadata>(
+  const fetchFromCdnPath = dirName
+    ? path.join(locale, S3_PATH_TO_GITBOOK_DOCS, dirName, S3_METADATA_JSON_PATH)
+    : `${locale}/${S3_RELEASE_NOTES_METADATA_JSON_PATH}`;
+
+  const cacheResult = await fetchMetadataWithCache<JsonMetadata>(
+    locale,
+    'releaseNotes',
+    () => fetchMetadataFromCDN<JsonMetadata>(fetchFromCdnPath),
     dirName
-      ? path.join(
-          locale,
-          S3_PATH_TO_GITBOOK_DOCS,
-          dirName,
-          S3_METADATA_JSON_PATH
-        )
-      : `${locale}/${S3_RELEASE_NOTES_METADATA_JSON_PATH}`
   );
-  releaseNotesMetadataCacheTime = now;
 
-  return releaseNotesMetadataCache || [];
+  return cacheResult.data || [];
 };
 
 export const getSoapApiMetadata = async (locale: string) => {
-  if (!soapApiMetadataCache) {
-    soapApiMetadataCache = await fetchMetadataFromCDN<SoapApiJsonMetadata>(
-      `${locale}/${S3_SOAP_API_METADATA_JSON_PATH}`
-    );
-  }
-  return soapApiMetadataCache || [];
+  const cacheResult = await fetchMetadataWithCache<SoapApiJsonMetadata>(
+    locale,
+    'soapApi',
+    () =>
+      fetchMetadataFromCDN<SoapApiJsonMetadata>(
+        `${locale}/${S3_SOAP_API_METADATA_JSON_PATH}`
+      )
+  );
+
+  return cacheResult.data || [];
 };

apps/nextjs-website/src/lib/api.ts

@@ -66,7 +66,6 @@ export async function getGuidePage(
       locale,
       productSlug
     ),
-    getGuidesMetadata(locale),
   ]);
 
   // Path construction
@@ -82,6 +81,7 @@ export async function getGuidePage(
   });
 
   const guidesMetadata = await getGuidesMetadata(
+    locale,
     guideToFind ? guideToFind.dirName : ''
   );
   return manageUndefined(