fix: add image fetch timeouts and Server-Timing instrumentation (#581)

Author: harlan-zw

src/module.ts

@@ -208,6 +208,17 @@ export interface ModuleOptions {
     maxDpr?: number
     /** Render timeout in milliseconds. Returns 408 on timeout. @default 15000 */
     renderTimeout?: number
+    /**
+     * Per-image fetch timeout in milliseconds.
+     *
+     * Applies to remote `<img>` / `background-image` fetches done while resolving templates.
+     * A stalled resource can otherwise consume the entire `renderTimeout` budget, which
+     * shows up as near-total request timeouts on edge platforms (e.g. Cloudflare Workers
+     * when the image URL routes back through the same worker).
+     *
+     * @default 3000
+     */
+    imageFetchTimeout?: number
     /**
      * Maximum allowed length (in characters) for the query string on runtime OG image requests.
      * Requests exceeding this limit receive a 400 response.
@@ -1530,6 +1541,7 @@ export const rootDir = ${JSON.stringify(nuxt.options.rootDir)}`
           maxDimension: config.security?.maxDimension ?? 2048,
           maxDpr: config.security?.maxDpr ?? 2,
           renderTimeout: config.security?.renderTimeout ?? 15_000,
+          imageFetchTimeout: config.security?.imageFetchTimeout ?? 3_000,
           maxQueryParamSize: config.security?.maxQueryParamSize ?? (config.security?.strict ? 2048 : null),
           restrictRuntimeImagesToOrigin: config.security?.restrictRuntimeImagesToOrigin === true || (config.security?.strict && config.security?.restrictRuntimeImagesToOrigin == null)
             ? []

src/runtime/server/og-image/bindings/font-assets/cloudflare.ts

@@ -2,38 +2,22 @@ import type { H3Event } from 'h3'
 import type { FontConfig } from '../../../../types'
 import { useRuntimeConfig } from 'nitropack/runtime'
 import { withBase } from 'ufo'
+import { getCloudflareAssets } from '../../../util/cloudflareAssets'
+import { fetchLocalAsset } from '../../../util/fetchLocalAsset'
+import { getFetchTimeout } from '../../../util/fetchTimeout'
+import { useOgImageRuntimeConfig } from '../../../utils'
 
 export async function resolve(event: H3Event, font: FontConfig) {
   const path = font.src || font.localPath
   const { app } = useRuntimeConfig()
   const fullPath = withBase(path, app.baseURL)
+  const timeout = getFetchTimeout(useOgImageRuntimeConfig())
 
-  // Try ASSETS binding first (Cloudflare Pages / Workers with static assets)
-  // This is the recommended approach and requires either:
-  // - nitro.cloudflare.deployConfig: true (generates wrangler.json with ASSETS binding)
-  // - A wrangler.toml/json with [assets] configured
-  const assets = event.context.cloudflare?.env?.ASSETS || event.context.ASSETS
-  if (assets && typeof assets.fetch === 'function') {
-    const origin = event.context.cloudflare?.request?.url || `https://${event.headers.get('host') || 'localhost'}`
-    const url = new URL(fullPath, origin).href
-    const res = await assets.fetch(url).catch(() => null) as Response | null
-    if (res?.ok) {
-      return Buffer.from(await res.arrayBuffer())
-    }
-  }
-
-  // Fallback: use event.fetch (Nitro localFetch) which routes through the h3 app
-  // and can serve public assets from Nitro's built-in asset handler.
-  if (typeof event.fetch === 'function') {
-    const origin = event.context.cloudflare?.request?.url || `https://${event.headers.get('host') || 'localhost'}`
-    const url = new URL(fullPath, origin).href
-    const res = await event.fetch(url).catch(() => null) as Response | null
-    if (res?.ok) {
-      return Buffer.from(await res.arrayBuffer())
-    }
-  }
+  const ab = await fetchLocalAsset(event, fullPath, { fetchTimeout: timeout })
+  if (ab)
+    return Buffer.from(ab)
 
-  if (!assets && !event.context._ogImageWarnedMissingAssets) {
+  if (!getCloudflareAssets(event) && !event.context._ogImageWarnedMissingAssets) {
     event.context._ogImageWarnedMissingAssets = true
     console.warn(
       `[Nuxt OG Image] No ASSETS binding found on Cloudflare Workers. Font loading will fail. `

src/runtime/server/og-image/bindings/font-assets/dev-prerender.ts

@@ -6,6 +6,8 @@ import { getRequestURL } from 'h3'
 import { useRuntimeConfig } from 'nitropack/runtime'
 import { join } from 'pathe'
 import { withBase } from 'ufo'
+import { getFetchTimeout } from '../../../util/fetchTimeout'
+import { useOgImageRuntimeConfig } from '../../../utils'
 
 let fontUrlMapping: Record<string, string> | undefined
 
@@ -19,6 +21,7 @@ async function loadFontUrlMapping(): Promise<Record<string, string>> {
 
 export async function resolve(event: H3Event, font: FontConfig): Promise<Buffer> {
   const path = font.src || font.localPath
+  const timeout = getFetchTimeout(useOgImageRuntimeConfig())
 
   // Static bundled fonts — read directly from absolute path
   if (font.absolutePath) {
@@ -48,7 +51,7 @@ export async function resolve(event: H3Event, font: FontConfig): Promise<Buffer>
 
       const mapping = await loadFontUrlMapping()
       if (mapping[filename]) {
-        const res = await fetch(mapping[filename]).catch(() => null)
+        const res = await fetch(mapping[filename], { signal: AbortSignal.timeout(timeout) }).catch(() => null)
         if (res?.ok)
           return Buffer.from(await res.arrayBuffer())
       }
@@ -78,7 +81,7 @@ export async function resolve(event: H3Event, font: FontConfig): Promise<Buffer>
     const filename = path.slice('/_fonts/'.length)
     const mapping = await loadFontUrlMapping()
     if (mapping[filename]) {
-      const res = await fetch(mapping[filename]).catch(() => null)
+      const res = await fetch(mapping[filename], { signal: AbortSignal.timeout(timeout) }).catch(() => null)
       if (res?.ok)
         return Buffer.from(await res.arrayBuffer())
     }
@@ -99,7 +102,7 @@ export async function resolve(event: H3Event, font: FontConfig): Promise<Buffer>
     const reqUrl = getRequestURL(event)
     const origin = `${reqUrl.protocol}//${reqUrl.host}`
     const url = new URL(withBase(path, app.baseURL), origin).href
-    const res = await fetch(url).catch(() => null)
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeout) }).catch(() => null)
     if (res?.ok) {
       return Buffer.from(await res.arrayBuffer())
     }
@@ -108,6 +111,7 @@ export async function resolve(event: H3Event, font: FontConfig): Promise<Buffer>
   // @ts-expect-error excessive stack depth from Nuxt typed routes
   const arrayBuffer = await event.$fetch(fullPath, {
     responseType: 'arrayBuffer',
+    timeout,
   }) as ArrayBuffer
   return Buffer.from(arrayBuffer)
 }

src/runtime/server/og-image/bindings/font-assets/node.ts

@@ -3,20 +3,24 @@ import type { FontConfig } from '../../../../types'
 import { getNitroOrigin } from '#site-config/server/composables'
 import { useRuntimeConfig } from 'nitropack/runtime'
 import { withBase } from 'ufo'
+import { getFetchTimeout } from '../../../util/fetchTimeout'
+import { useOgImageRuntimeConfig } from '../../../utils'
 
 export async function resolve(event: H3Event, font: FontConfig) {
   const path = font.src || font.localPath
   const { app } = useRuntimeConfig()
   const fullPath = withBase(path, app.baseURL)
   const origin = getNitroOrigin(event)
-  const res = await fetch(new URL(fullPath, origin).href).catch(() => null)
+  const timeout = getFetchTimeout(useOgImageRuntimeConfig())
+  const res = await fetch(new URL(fullPath, origin).href, { signal: AbortSignal.timeout(timeout) }).catch(() => null)
   if (res?.ok) {
     return Buffer.from(await res.arrayBuffer())
   }
   // Fallback to Nitro's internal handler when origin is unreachable
   // (behind a proxy, serverless, or server not fully started)
   const arrayBuffer = await event.$fetch(fullPath, {
     responseType: 'arrayBuffer',
+    timeout,
   }) as ArrayBuffer
   return Buffer.from(arrayBuffer)
 }

src/runtime/server/og-image/browser/screenshot.ts

@@ -5,6 +5,7 @@ import { getNitroOrigin } from '#site-config/server/composables'
 import { withQuery } from 'ufo'
 import { toValue } from 'vue'
 import { buildOgImageUrl } from '../../../shared'
+import { getFetchTimeout } from '../../util/fetchTimeout'
 import { logger } from '../../util/logger'
 import { useOgImageRuntimeConfig } from '../../utils'
 
@@ -79,8 +80,9 @@ async function takeScreenshot(page: Page, selector: string | undefined, options:
   return await page.screenshot(puppeteerOptions)
 }
 
-export async function createScreenshot({ basePath, e, options, extension }: OgImageRenderEventContext, browser: Browser): Promise<Buffer> {
-  const { colorPreference, defaults, security } = useOgImageRuntimeConfig()
+export async function createScreenshot({ basePath, e, options, extension, timings }: OgImageRenderEventContext, browser: Browser): Promise<Buffer> {
+  const runtimeConfig = useOgImageRuntimeConfig()
+  const { colorPreference, defaults, security } = runtimeConfig
   // For browser renderer, we need to load the HTML template with options encoded in URL
   const path = options.component === 'PageScreenshot' ? basePath : buildOgImageUrl(options, 'html', false, defaults, security?.secret || undefined).url
 
@@ -110,7 +112,8 @@ export async function createScreenshot({ basePath, e, options, extension }: OgIm
     }
     if (import.meta.prerender && !options.html) {
       // we need to do a nitro fetch for the HTML instead of rendering with browser
-      options.html = await e.$fetch(path).catch(() => undefined) as string
+      options.html = await timings.measure('html-fetch', () =>
+        e.$fetch(path, { timeout: getFetchTimeout(runtimeConfig) }).catch(() => undefined)) as string
     }
 
     await setViewport(
@@ -159,7 +162,7 @@ export async function createScreenshot({ basePath, e, options, extension }: OgIm
       }, _options.mask)
     }
 
-    return await takeScreenshot(page, _options.selector, screenshotOptions)
+    return await timings.measure('render-browser', () => takeScreenshot(page, _options.selector, screenshotOptions))
   }
   finally {
     await page.close()

src/runtime/server/og-image/context.ts

@@ -21,6 +21,7 @@ import { decodeOgImageParams, extractEncodedSegment, sanitizeProps, separateProp
 import { autoEjectCommunityTemplate } from '../util/auto-eject'
 import { createNitroRouteRuleMatcher } from '../util/kit'
 import { normaliseOptions } from '../util/options'
+import { createTimings, TIMING_CTX_KEY } from '../util/timings'
 import { useOgImageRuntimeConfig } from '../utils'
 import { getBrowserRenderer, getSatoriRenderer, getTakumiRenderer } from './instances'
 
@@ -257,6 +258,8 @@ export async function resolveContext(e: H3Event): Promise<H3Error | OgImageRende
       statusMessage: `[Nuxt OG Image] Renderer "${rendererType}" is not available. Component "${normalised.component?.pascalName}" requires the ${rendererType} renderer but it's not bundled for this preset.`,
     })
   }
+  const timings = (e.context[TIMING_CTX_KEY] as ReturnType<typeof createTimings>) || createTimings()
+  e.context[TIMING_CTX_KEY] = timings
   const ctx: OgImageRenderEventContext = {
     e,
     key,
@@ -267,6 +270,7 @@ export async function resolveContext(e: H3Event): Promise<H3Error | OgImageRende
     extension,
     basePath,
     options: normalised.options,
+    timings,
     _nitro: useNitroApp(),
   }
   // call the nitro hook