refactor: create simplified key-value store interface to interact with blobs with common tracing pattern

pieh · pieh · commit 2e7a9517f5cf · 2025-03-20T11:11:31.000+01:00
diff --git a/src/build/content/static.ts b/src/build/content/static.ts
@@ -6,8 +6,8 @@ import { trace } from '@opentelemetry/api'
 import { wrapTracer } from '@opentelemetry/api/experimental'
 import glob from 'fast-glob'
 
-import type { HtmlBlob } from '../../run/next.cjs'
 import { encodeBlobKey } from '../../shared/blobkey.js'
+import type { HtmlBlob } from '../../shared/cache-types.cjs'
 import { PluginContext } from '../plugin-context.js'
 import { verifyNetlifyForms } from '../verification.js'
 
diff --git a/src/run/handlers/cache.cts b/src/run/handlers/cache.cts
@@ -5,7 +5,6 @@ import { Buffer } from 'node:buffer'
 import { join } from 'node:path'
 import { join as posixJoin } from 'node:path/posix'
 
-import { Store } from '@netlify/blobs'
 import { purgeCache } from '@netlify/functions'
 import { type Span } from '@opentelemetry/api'
 import type { PrerenderManifest } from 'next/dist/build/index.js'
@@ -21,37 +20,34 @@ import {
   type NetlifyCachedRouteValue,
   type NetlifyCacheHandlerValue,
   type NetlifyIncrementalCacheValue,
+  type TagManifest,
 } from '../../shared/cache-types.cjs'
-import { getRegionalBlobStore } from '../regional-blob-store.cjs'
+import {
+  getMemoizedKeyValueStoreBackedByRegionalBlobStore,
+  MemoizedKeyValueStoreBackedByRegionalBlobStore,
+} from '../regional-blob-store.cjs'
 
 import { getLogger, getRequestContext } from './request-context.cjs'
 import { getTracer } from './tracer.cjs'
 
-type TagManifest = { revalidatedAt: number }
-
-type TagManifestBlobCache = Record<string, Promise<TagManifest>>
+type TagManifestBlobCache = Record<string, Promise<TagManifest | null>>
 
 const purgeCacheUserAgent = `${nextRuntimePkgName}@${nextRuntimePkgVersion}`
 
 export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
   options: CacheHandlerContext
   revalidatedTags: string[]
-  blobStore: Store
+  cacheStore: MemoizedKeyValueStoreBackedByRegionalBlobStore
   tracer = getTracer()
   tagManifestsFetchedFromBlobStoreInCurrentRequest: TagManifestBlobCache
 
   constructor(options: CacheHandlerContext) {
     this.options = options
     this.revalidatedTags = options.revalidatedTags
-    this.blobStore = getRegionalBlobStore({ consistency: 'strong' })
+    this.cacheStore = getMemoizedKeyValueStoreBackedByRegionalBlobStore({ consistency: 'strong' })
     this.tagManifestsFetchedFromBlobStoreInCurrentRequest = {}
   }
 
-  private async encodeBlobKey(key: string) {
-    const { encodeBlobKey } = await import('../../shared/blobkey.js')
-    return await encodeBlobKey(key)
-  }
-
   private getTTL(blob: NetlifyCacheHandlerValue) {
     if (
       blob.value?.kind === 'FETCH' ||
@@ -245,19 +241,13 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
       const [key, ctx = {}] = args
       getLogger().debug(`[NetlifyCacheHandler.get]: ${key}`)
 
-      const blobKey = await this.encodeBlobKey(key)
-      span.setAttributes({ key, blobKey })
+      span.setAttributes({ key })
 
-      const blob = (await this.tracer.withActiveSpan('blobStore.get', async (blobGetSpan) => {
-        blobGetSpan.setAttributes({ key, blobKey })
-        return await this.blobStore.get(blobKey, {
-          type: 'json',
-        })
-      })) as NetlifyCacheHandlerValue | null
+      const blob = await this.cacheStore.get<NetlifyCacheHandlerValue>(key, 'blobStore.get')
 
       // if blob is null then we don't have a cache entry
       if (!blob) {
-        span.addEvent('Cache miss', { key, blobKey })
+        span.addEvent('Cache miss', { key })
         return null
       }
 
@@ -268,7 +258,6 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
         // but opt to discard STALE data, so that Next.js generate fresh response
         span.addEvent('Discarding stale entry due to SWR background revalidation request', {
           key,
-          blobKey,
           ttl,
         })
         getLogger()
@@ -285,7 +274,7 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
       const staleByTags = await this.checkCacheEntryStaleByTags(blob, ctx.tags, ctx.softTags)
 
       if (staleByTags) {
-        span.addEvent('Stale', { staleByTags, key, blobKey, ttl })
+        span.addEvent('Stale', { staleByTags, key, ttl })
         return null
       }
 
@@ -403,9 +392,8 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
   async set(...args: Parameters<CacheHandlerForMultipleVersions['set']>) {
     return this.tracer.withActiveSpan('set cache key', async (span) => {
       const [key, data, context] = args
-      const blobKey = await this.encodeBlobKey(key)
       const lastModified = Date.now()
-      span.setAttributes({ key, lastModified, blobKey })
+      span.setAttributes({ key, lastModified })
 
       getLogger().debug(`[NetlifyCacheHandler.set]: ${key}`)
 
@@ -415,10 +403,7 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
       // and we didn't yet capture cache tags, we try to get cache tags from freshly produced cache value
       this.captureCacheTags(value, key)
 
-      await this.blobStore.setJSON(blobKey, {
-        lastModified,
-        value,
-      })
+      await this.cacheStore.set(key, { lastModified, value }, 'blobStore.set')
 
       if (data?.kind === 'PAGE' || data?.kind === 'PAGES') {
         const requestContext = getRequestContext()
@@ -476,7 +461,7 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
     await Promise.all(
       tags.map(async (tag) => {
         try {
-          await this.blobStore.setJSON(await this.encodeBlobKey(tag), data)
+          await this.cacheStore.set(tag, data, 'tagManifest.set')
         } catch (error) {
           getLogger().withError(error).log(`Failed to update tag manifest for ${tag}`)
         }
@@ -544,23 +529,21 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
       const tagManifestPromises: Promise<boolean>[] = []
 
       for (const tag of cacheTags) {
-        let tagManifestPromise: Promise<TagManifest> =
+        let tagManifestPromise: Promise<TagManifest | null> =
           this.tagManifestsFetchedFromBlobStoreInCurrentRequest[tag]
 
         if (!tagManifestPromise) {
-          tagManifestPromise = this.encodeBlobKey(tag).then((blobKey) => {
-            return this.tracer.withActiveSpan(`get tag manifest`, async (span) => {
-              span.setAttributes({ tag, blobKey })
-              return this.blobStore.get(blobKey, { type: 'json' })
-            })
-          })
+          tagManifestPromise = this.cacheStore.get<TagManifest>(tag, 'tagManifest.get')
 
           this.tagManifestsFetchedFromBlobStoreInCurrentRequest[tag] = tagManifestPromise
         }
 
         tagManifestPromises.push(
           tagManifestPromise.then((tagManifest) => {
-            const isStale = tagManifest?.revalidatedAt >= (cacheEntry.lastModified || Date.now())
+            if (!tagManifest) {
+              return false
+            }
+            const isStale = tagManifest.revalidatedAt >= (cacheEntry.lastModified || Date.now())
             if (isStale) {
               resolve(true)
               return true
diff --git a/src/run/handlers/server.ts b/src/run/handlers/server.ts
@@ -127,7 +127,6 @@ export default async (
         headers: response.headers,
         request,
         span,
-        tracer,
         requestContext,
       })
     }
diff --git a/src/run/headers.ts b/src/run/headers.ts
@@ -1,12 +1,10 @@
 import type { Span } from '@opentelemetry/api'
 import type { NextConfigComplete } from 'next/dist/server/config-shared.js'
 
-import { encodeBlobKey } from '../shared/blobkey.js'
-import type { NetlifyCachedRouteValue } from '../shared/cache-types.cjs'
+import type { NetlifyCachedRouteValue, NetlifyCacheHandlerValue } from '../shared/cache-types.cjs'
 
 import { getLogger, RequestContext } from './handlers/request-context.cjs'
-import type { RuntimeTracer } from './handlers/tracer.cjs'
-import { getRegionalBlobStore } from './regional-blob-store.cjs'
+import { getMemoizedKeyValueStoreBackedByRegionalBlobStore } from './regional-blob-store.cjs'
 
 const ALL_VARIATIONS = Symbol.for('ALL_VARIATIONS')
 interface NetlifyVaryValues {
@@ -129,13 +127,11 @@ export const adjustDateHeader = async ({
   headers,
   request,
   span,
-  tracer,
   requestContext,
 }: {
   headers: Headers
   request: Request
   span: Span
-  tracer: RuntimeTracer
   requestContext: RequestContext
 }) => {
   const key = new URL(request.url).pathname
@@ -157,23 +153,12 @@ export const adjustDateHeader = async ({
       warning: true,
     })
 
-    const blobStore = getRegionalBlobStore({ consistency: 'strong' })
-    const blobKey = await encodeBlobKey(key)
-
-    // TODO: use metadata for this
-    lastModified = await tracer.withActiveSpan(
+    const cacheStore = getMemoizedKeyValueStoreBackedByRegionalBlobStore({ consistency: 'strong' })
+    const cacheEntry = await cacheStore.get<NetlifyCacheHandlerValue>(
+      key,
       'get cache to calculate date header',
-      async (getBlobForDateSpan) => {
-        getBlobForDateSpan.setAttributes({
-          key,
-          blobKey,
-        })
-        const blob = (await blobStore.get(blobKey, { type: 'json' })) ?? {}
-
-        getBlobForDateSpan.addEvent(blob ? 'Cache hit' : 'Cache miss')
-        return blob.lastModified
-      },
     )
+    lastModified = cacheEntry?.lastModified
   }
 
   if (!lastModified) {
diff --git a/src/run/next.cts b/src/run/next.cts
@@ -4,9 +4,11 @@ import { relative, resolve } from 'path'
 // @ts-expect-error no types installed
 import { patchFs } from 'fs-monkey'
 
+import { HtmlBlob } from '../shared/cache-types.cjs'
+
 import { getRequestContext } from './handlers/request-context.cjs'
 import { getTracer } from './handlers/tracer.cjs'
-import { getRegionalBlobStore } from './regional-blob-store.cjs'
+import { getMemoizedKeyValueStoreBackedByRegionalBlobStore } from './regional-blob-store.cjs'
 
 // https://github.com/vercel/next.js/pull/68193/files#diff-37243d614f1f5d3f7ea50bbf2af263f6b1a9a4f70e84427977781e07b02f57f1R49
 // This import resulted in importing unbundled React which depending if NODE_ENV is `production` or not would use
@@ -76,18 +78,11 @@ ResponseCache.prototype.get = function get(...getArgs: unknown[]) {
 
 type FS = typeof import('fs')
 
-export type HtmlBlob = {
-  html: string
-  isFallback: boolean
-}
-
 export async function getMockedRequestHandler(...args: Parameters<typeof getRequestHandlers>) {
   const tracer = getTracer()
   return tracer.withActiveSpan('mocked request handler', async () => {
     const ofs = { ...fs }
 
-    const { encodeBlobKey } = await import('../shared/blobkey.js')
-
     async function readFileFallbackBlobStore(...fsargs: Parameters<FS['promises']['readFile']>) {
       const [path, options] = fsargs
       try {
@@ -97,11 +92,9 @@ export async function getMockedRequestHandler(...args: Parameters<typeof getRequ
       } catch (error) {
         // only try to get .html files from the blob store
         if (typeof path === 'string' && path.endsWith('.html')) {
-          const store = getRegionalBlobStore()
+          const cacheStore = getMemoizedKeyValueStoreBackedByRegionalBlobStore()
           const relPath = relative(resolve('.next/server/pages'), path)
-          const file = (await store.get(await encodeBlobKey(relPath), {
-            type: 'json',
-          })) as HtmlBlob | null
+          const file = await cacheStore.get<HtmlBlob>(relPath, 'staticHtml.get')
           if (file !== null) {
             if (!file.isFallback) {
               const requestContext = getRequestContext()
diff --git a/src/run/regional-blob-store.cts b/src/run/regional-blob-store.cts
@@ -1,5 +1,9 @@
 import { getDeployStore, GetWithMetadataOptions, Store } from '@netlify/blobs'
 
+import type { BlobType } from '../shared/cache-types.cjs'
+
+import { getTracer } from './handlers/tracer.cjs'
+
 const FETCH_BEFORE_NEXT_PATCHED_IT = Symbol.for('nf-not-patched-fetch')
 const extendedGlobalThis = globalThis as typeof globalThis & {
   [FETCH_BEFORE_NEXT_PATCHED_IT]?: typeof globalThis.fetch
@@ -53,10 +57,52 @@ const fetchBeforeNextPatchedItFallback = forceOptOutOfUsingDataCache(
 const getFetchBeforeNextPatchedIt = () =>
   extendedGlobalThis[FETCH_BEFORE_NEXT_PATCHED_IT] ?? fetchBeforeNextPatchedItFallback
 
-export const getRegionalBlobStore = (args: GetWithMetadataOptions = {}): Store => {
+const getRegionalBlobStore = (args: GetWithMetadataOptions = {}): Store => {
   return getDeployStore({
     ...args,
     fetch: getFetchBeforeNextPatchedIt(),
     region: process.env.USE_REGIONAL_BLOBS?.toUpperCase() === 'TRUE' ? undefined : 'us-east-2',
   })
 }
+
+const encodeBlobKey = async (key: string) => {
+  const { encodeBlobKey: encodeBlobKeyImpl } = await import('../shared/blobkey.js')
+  return await encodeBlobKeyImpl(key)
+}
+
+export const getMemoizedKeyValueStoreBackedByRegionalBlobStore = (
+  args: GetWithMetadataOptions = {},
+) => {
+  const store = getRegionalBlobStore(args)
+  const tracer = getTracer()
+
+  return {
+    async get<T extends BlobType>(key: string, otelSpanTitle: string): Promise<T | null> {
+      const blobKey = await encodeBlobKey(key)
+
+      return tracer.withActiveSpan(otelSpanTitle, async (span) => {
+        span.setAttributes({ key, blobKey })
+        const blob = (await store.get(blobKey, { type: 'json' })) as T | null
+        span.addEvent(blob ? 'Hit' : 'Miss')
+        return blob
+      })
+    },
+    async set(key: string, value: BlobType, otelSpanTitle: string) {
+      const blobKey = await encodeBlobKey(key)
+
+      return tracer.withActiveSpan(otelSpanTitle, async (span) => {
+        span.setAttributes({ key, blobKey })
+        return await store.setJSON(blobKey, value)
+      })
+    },
+  }
+}
+
+/**
+ * Wrapper around Blobs Store that memoizes the cache entries within context of a request
+ * to avoid duplicate requests to the same key and also allowing to read its own writes from
+ * memory.
+ */
+export type MemoizedKeyValueStoreBackedByRegionalBlobStore = ReturnType<
+  typeof getMemoizedKeyValueStoreBackedByRegionalBlobStore
+>
diff --git a/src/shared/cache-types.cts b/src/shared/cache-types.cts
@@ -154,3 +154,12 @@ export type CacheHandlerForMultipleVersions = BaseCacheHandlerForMultipleVersion
     context: CacheHandlerSetContextForMultipleVersions,
   ) => ReturnType<BaseCacheHandlerForMultipleVersions['set']>
 }
+
+export type TagManifest = { revalidatedAt: number }
+
+export type HtmlBlob = {
+  html: string
+  isFallback: boolean
+}
+
+export type BlobType = NetlifyCacheHandlerValue | TagManifest | HtmlBlob

Original file line number	Diff line number	Diff line change
`@@ -127,7 +127,6 @@ export default async (`
`127`	`127`	`headers: response.headers,`
`128`	`128`	`request,`
`129`	`129`	`span,`
`130`		`- tracer,`
`131`	`130`	`requestContext,`
`132`	`131`	`})`
`133`	`132`	`}`