fix: add render concurrency limits and request coalescing

Prevent DoS via concurrent render requests by adding:
- Request coalescing (single-flight): concurrent requests for the same
  cache key share one Promise, avoiding redundant renders
- Concurrency semaphore: caps parallel renders (default 3) to prevent
  memory exhaustion from burst traffic

Both utilities are edge-runtime compatible (in-process, no shared state
across isolates). Configurable via `maxConcurrentRenders` module option.

Author: harlan-zw

src/module.ts

@@ -186,6 +186,14 @@ export interface ModuleOptions {
    * @example ['latin', 'latin-ext', 'devanagari']
    */
   fontSubsets?: string[]
+  /**
+   * Maximum number of concurrent image renders. Prevents memory exhaustion
+   * from burst traffic. Excess requests wait in a FIFO queue.
+   * Works on all runtimes including edge (in-process semaphore).
+   *
+   * @default 3
+   */
+  maxConcurrentRenders?: number
   /**
    * Browser renderer configuration.
    *
@@ -1365,6 +1373,7 @@ export const rootDir = ${JSON.stringify(nuxt.options.rootDir)}`
         isNuxtContentDocumentDriven: !!nuxt.options.content?.documentDriven,
         cacheQueryParams: config.cacheQueryParams ?? false,
         cssFramework: cssFramework || 'none',
+        maxConcurrentRenders: config.maxConcurrentRenders ?? 3,
         // Browser renderer config for cloudflare binding access
         browser: typeof config.browser === 'object'
           ? {

src/runtime/server/util/eventHandlers.ts

@@ -1,4 +1,5 @@
 import type { H3Event } from 'h3'
+import type { Semaphore } from './security'
 import { getSiteConfig } from '#site-config/server/composables/getSiteConfig'
 import { createError, H3Error, setHeader } from 'h3'
 import { logger } from '../../logger'
@@ -8,6 +9,10 @@ import { fetchPathHtmlAndExtractOptions } from '../og-image/devtools'
 import { html } from '../og-image/templates/html'
 import { useOgImageRuntimeConfig } from '../utils'
 import { useOgImageBufferCache } from './cache'
+import { coalesce, createSemaphore } from './security'
+
+// Lazy-init semaphore on first use (needs runtime config for limit)
+let renderSemaphore: Semaphore | undefined
 
 export async function imageEventHandler(e: H3Event) {
   const ctx = await resolveContext(e).catch((err: any) => {
@@ -100,7 +105,23 @@ export async function imageEventHandler(e: H3Event) {
 
   let image: H3Error | BufferSource | Buffer | Uint8Array | false | void = cacheApi.cachedItem
   if (!image) {
-    image = await renderer.createImage(ctx).catch((err: any) => {
+    // Request coalescing: if multiple requests arrive for the same key before the
+    // first render completes, they share one Promise (single-flight pattern).
+    // Concurrency semaphore: limits parallel renders to prevent memory exhaustion.
+    // Both are process-local and edge-compatible (no shared state needed).
+    image = await coalesce(ctx.key, async () => {
+      const runtimeCfg = useOgImageRuntimeConfig()
+      if (!renderSemaphore)
+        renderSemaphore = createSemaphore(runtimeCfg.maxConcurrentRenders || 3)
+
+      await renderSemaphore.acquire()
+      try {
+        return await renderer.createImage(ctx)
+      }
+      finally {
+        renderSemaphore.release()
+      }
+    }).catch((err: any) => {
       logger.error(`renderer.createImage error for ${e.path}:`, err?.stack || err?.message || err)
       throw err
     })

src/runtime/server/util/security.ts

@@ -0,0 +1,67 @@
+/**
+ * Security utilities for OG image generation.
+ *
+ * Request coalescing (single-flight) and concurrency semaphore.
+ * All utilities are edge-runtime compatible (no shared state across isolates).
+ */
+
+// ---------------------------------------------------------------------------
+// Request coalescing (single-flight)
+// ---------------------------------------------------------------------------
+
+const inFlight = new Map<string, Promise<any>>()
+
+/**
+ * Ensures only one render executes per cache key at a time. Concurrent requests
+ * for the same key share the same Promise. Process-local, edge-compatible.
+ */
+export function coalesce<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const existing = inFlight.get(key)
+  if (existing)
+    return existing as Promise<T>
+  const promise = fn().finally(() => inFlight.delete(key))
+  inFlight.set(key, promise)
+  return promise
+}
+
+// ---------------------------------------------------------------------------
+// Concurrency semaphore
+// ---------------------------------------------------------------------------
+
+export type Semaphore = ReturnType<typeof createSemaphore>
+
+/**
+ * Creates a simple in-process semaphore. Edge-compatible (no shared state).
+ * When the limit is reached, new callers wait in a FIFO queue.
+ */
+export function createSemaphore(limit: number) {
+  let active = 0
+  const queue: Array<() => void> = []
+
+  function release() {
+    active--
+    const next = queue.shift()
+    if (next)
+      next()
+  }
+
+  return {
+    async acquire(): Promise<void> {
+      if (active < limit) {
+        active++
+        return
+      }
+      return new Promise<void>((resolve) => {
+        queue.push(() => {
+          active++
+          resolve()
+        })
+      })
+    },
+    release,
+    /** Number of renders currently executing */
+    get active() { return active },
+    /** Number of requests waiting */
+    get waiting() { return queue.length },
+  }
+}

src/runtime/types.ts

@@ -59,6 +59,9 @@ export interface OgImageRuntimeConfig {
   /** Path to community templates (dev only) */
   communityTemplatesDir?: string
 
+  /** Maximum concurrent image renders (edge-compatible in-process semaphore) */
+  maxConcurrentRenders: number
+
   /** Browser renderer config for cloudflare binding access */
   browser?: {
     provider?: BrowserProvider

test/unit/security.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest'
+import { coalesce, createSemaphore } from '../../src/runtime/server/util/security'
+
+describe('coalesce', () => {
+  it('deduplicates concurrent calls with the same key', async () => {
+    let callCount = 0
+    const fn = () => {
+      callCount++
+      return new Promise<string>(resolve => setTimeout(resolve, 10, 'result'))
+    }
+    const [a, b, c] = await Promise.all([
+      coalesce('key1', fn),
+      coalesce('key1', fn),
+      coalesce('key1', fn),
+    ])
+    expect(callCount).toBe(1)
+    expect(a).toBe('result')
+    expect(b).toBe('result')
+    expect(c).toBe('result')
+  })
+
+  it('allows different keys to run independently', async () => {
+    let callCount = 0
+    const fn = () => {
+      callCount++
+      return Promise.resolve('ok')
+    }
+    await Promise.all([coalesce('a', fn), coalesce('b', fn)])
+    expect(callCount).toBe(2)
+  })
+
+  it('cleans up after completion so subsequent calls re-execute', async () => {
+    let callCount = 0
+    const fn = () => {
+      callCount++
+      return Promise.resolve(callCount)
+    }
+    const first = await coalesce('x', fn)
+    const second = await coalesce('x', fn)
+    expect(first).toBe(1)
+    expect(second).toBe(2)
+  })
+})
+
+describe('createSemaphore', () => {
+  it('limits concurrent execution', async () => {
+    const sem = createSemaphore(2)
+    let running = 0
+    let maxRunning = 0
+
+    const task = async () => {
+      await sem.acquire()
+      running++
+      maxRunning = Math.max(maxRunning, running)
+      await new Promise(r => setTimeout(r, 20))
+      running--
+      sem.release()
+    }
+
+    await Promise.all([task(), task(), task(), task(), task()])
+    expect(maxRunning).toBe(2)
+  })
+
+  it('reports active and waiting counts', async () => {
+    const sem = createSemaphore(1)
+    await sem.acquire()
+    expect(sem.active).toBe(1)
+
+    const waiting = sem.acquire()
+    expect(sem.waiting).toBe(1)
+
+    sem.release()
+    await waiting
+    expect(sem.active).toBe(1)
+    expect(sem.waiting).toBe(0)
+    sem.release()
+  })
+})