Dynamic OG Images at 5M Portfolio Shares: Benchmarking Satori, resvg-js, Puppeteer, and Cloudinary

// bench/harness.ts
import { performance } from 'node:perf_hooks';

export interface LatencyReport {
  n: number;
  p50: number;
  p95: number;
  p99: number;
  mean: number;
  max: number;
}

/** Nearest-rank percentile. `sortedAsc` MUST be pre-sorted ascending. */
export function percentile(sortedAsc: readonly number[], p: number): number {
  if (sortedAsc.length === 0) throw new RangeError('percentile() requires >= 1 sample');
  if (p < 0 || p > 100) throw new RangeError(`p must be within [0,100], got ${p}`);
  const rank = Math.ceil((p / 100) * sortedAsc.length);
  return sortedAsc[Math.min(Math.max(rank - 1, 0), sortedAsc.length - 1)]!;
}

export async function measure(
  label: string,
  render: () => Promise<unknown>,
  { warmup = 50, iterations = 500 }: { warmup?: number; iterations?: number } = {},
): Promise<LatencyReport> {
  for (let i = 0; i < warmup; i++) await render();

  const samples: number[] = [];
  for (let i = 0; i < iterations; i++) {
    const t0 = performance.now();
    try {
      await render();
    } catch (err) {
      console.warn('sample failed, excluded', (err as Error).message);
      continue;
    }
    samples.push(performance.now() - t0);
  }

  if (samples.length === 0) throw new Error(`${label}: no successful samples`);
  samples.sort((a, b) => a - b);
  const mean = samples.reduce((s, v) => s + v, 0) / samples.length;

  return {
    n: samples.length,
    p50: +percentile(samples, 50).toFixed(1),
    p95: +percentile(samples, 95).toFixed(1),
    p99: +percentile(samples, 99).toFixed(1),
    mean: +mean.toFixed(1),
    max: +samples[samples.length - 1]!.toFixed(1),
  };
}

// src/og/puppeteer.ts — only when you truly need full CSS fidelity
import puppeteer, { type Browser } from 'puppeteer-core';
import chromium from '@sparticuz/chromium';

let browserPromise: Promise<Browser> | null = null;

async function getBrowser(): Promise<Browser> {
  browserPromise ??= puppeteer
    .launch({
      args: [...chromium.args, '--font-render-hinting=none', '--disable-dev-shm-usage'],
      defaultViewport: { width: 1200, height: 630, deviceScaleFactor: 1 },
      executablePath: await chromium.executablePath(),
      headless: 'shell',
    })
    .catch((err: unknown) => {
      browserPromise = null; // never cache a rejected launch
      throw err;
    });
  return browserPromise;
}

export async function renderWithChrome(html: string): Promise<Buffer> {
  const browser = await getBrowser();
  const page = await browser.newPage();
  try {
    await page.setViewport({ width: 1200, height: 630, deviceScaleFactor: 1 });
    await page.setContent(html, { waitUntil: 'networkidle0', timeout: 8_000 });
    await page.evaluate(() => document.fonts.ready);
    const shot = await page.screenshot({ type: 'jpeg', quality: 82, optimizeForSpeed: true });
    return Buffer.from(shot);
  } finally {
    await page.close().catch(() => {});
  }
}

// src/og/cloudinary.ts
import { createHash } from 'node:crypto';

const CLOUD = process.env.CLOUDINARY_CLOUD;
const SECRET = process.env.CLOUDINARY_SECRET;
if (!CLOUD || !SECRET) throw new Error('CLOUDINARY_CLOUD and CLOUDINARY_SECRET are required');

export function signedOgUrl(slug: string, title: string, accentHex: string): string {
  // Commas and slashes are transformation delimiters — strip them from user text.
  const safeTitle = title.replace(/[,/\\]/g, ' ').slice(0, 70);
  const segments = [
    `c_fill,w_1200,h_630,q_auto:good,f_jpg`,                        // base transform
    `l_text:Inter_64_bold:${encodeURIComponent(safeTitle)},co_rgb:f8fafc,w_1000,c_fit`,
    `fl_layer_apply,g_south_west,x_64,y_180`,
    `l_text:Inter_28:${encodeURIComponent(slug)},co_rgb:${accentHex},g_north_west,x_64,y_64`,
    `fl_layer_apply`,
    `v1/og/base-gradient.png`,
  ];
  const toSign = segments.join('/');
  const signature = createHash('sha1').update(toSign + SECRET).digest('hex');
  return `https://res.cloudinary.com/${CLOUD}/image/upload/s--${signature}--/${toSign}`;
}

// src/og/render.ts
import satori from 'satori';
import { Resvg } from '@resvg/resvg-js';
import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import { performance } from 'node:perf_hooks';

export interface CaseStudyCard {
  slug: string;
  title: string;
  client: string;
  metric: string;      // "p95 71 ms"
  metricLabel: string; // "render latency"
  tags: readonly string[];
  accent: string;      // hex, e.g. #38bdf8
}

interface FontAsset {
  name: string;
  data: ArrayBuffer;
  weight: 400 | 700;
  style: 'normal';
}

let fontCache: Promise<FontAsset[]> | null = null;

function toArrayBuffer(buf: Buffer): ArrayBuffer {
  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;
}

/** Parsed once per container; satori rejects woff2. Always ship .ttf/.woff. */
function loadFonts(): Promise<FontAsset[]> {
  fontCache ??= (async () => {
    const dir = join(process.cwd(), 'fonts');
    const [regular, bold] = await Promise.all([
      readFile(join(dir, 'Inter-Regular.subset.woff')),
      readFile(join(dir, 'Inter-Bold.subset.woff')),
    ]);
    return [
      { name: 'Inter', data: toArrayBuffer(regular), weight: 400, style: 'normal' },
      { name: 'Inter', data: toArrayBuffer(bold), weight: 700, style: 'normal' },
    ];
  })();
  return fontCache;
}

const h = (type: string, props: Record<string, unknown>, ...children: unknown[]) => ({
  type,
  props: { ...props, children: children.length <= 1 ? children[0] : children },
});

function card(c: CaseStudyCard) {
  return h(
    'div',
    {
      style: {
        display: 'flex', flexDirection: 'column', justifyContent: 'space-between',
        width: '1200px', height: '630px', padding: '64px', fontFamily: 'Inter',
        color: '#f8fafc',
        background: `linear-gradient(135deg, #0b0f19 0%, ${c.accent}22 100%)`,
      },
    },
    h('div', { style: { display: 'flex', justifyContent: 'space-between', fontSize: '24px', letterSpacing: '0.08em', textTransform: 'uppercase', color: '#94a3b8' } },
      h('span', {}, c.client), h('span', {}, 'case study')),
    h('div', { style: { display: 'flex', flexDirection: 'column', gap: '16px' } },
      h('div', { style: { fontSize: '72px', fontWeight: 700, lineHeight: 1.05, letterSpacing: '-0.02em' } }, c.title),
      h('div', { style: { display: 'flex', alignItems: 'baseline', gap: '16px' } },
        h('span', { style: { fontSize: '56px', fontWeight: 700, color: c.accent } }, c.metric),
        h('span', { style: { fontSize: '28px', color: '#94a3b8' } }, c.metricLabel))),
    h('div', { style: { display: 'flex', gap: '12px' } },
      ...c.tags.map((t) => h('span', { style: { fontSize: '22px', padding: '8px 16px', borderRadius: '999px', border: '1px solid #334155', color: '#cbd5e1' } }, t))),
  );
}

export interface RenderedCard { png: Buffer; etag: string; renderMs: number }

export async function renderCard(c: CaseStudyCard): Promise<RenderedCard> {
  const t0 = performance.now();
  const fonts = await loadFonts();
  let svg: string;
  try {
    svg = await satori(card(c) as never, { width: 1200, height: 630, fonts, embedFont: true });
  } catch (err) {
    throw new Error(`satori failed for slug=${c.slug}`, { cause: err });
  }
  const png = new Resvg(svg, {
    fitTo: { mode: 'width', value: 1200 },
    background: '#0b0f19',
  }).render().asPng();

  const hash = createHash('sha256').update(png).digest('base64url').slice(0, 27);
  const etag = `"${hash}"`;
  return { png, etag, renderMs: performance.now() - t0 };
}

// src/og/handler.ts
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
import { renderCard } from './render';
import { loadCardFromCms } from './cms'; // your typed CMS/DB loader

const s3 = new S3Client({ region: process.env.AWS_REGION });
const TTL = 60 * 60 * 24 * 365;

function required(name: string): string {
  const v = process.env[name];
  if (!v) throw new Error(`missing env var ${name}`);
  return v;
}
const BUCKET = required('OG_BUCKET');

async function getObject(key: string) {
  const res = await s3.send(new GetObjectCommand({ Bucket: BUCKET, Key: key }));
  if (!res.Body) return null;
  return { body: Buffer.from(await res.Body.transformToByteArray()), etag: res.ETag ?? '' };
}

function respond(png: Buffer, etag: string, event: APIGatewayProxyEventV2, xCache: string): APIGatewayProxyResultV2 {
  if (event.headers?.['if-none-match'] === etag) return { statusCode: 304, headers: { etag } };
  return {
    statusCode: 200,
    headers: {
      'content-type': 'image/png',
      'cache-control': `public, max-age=${TTL}, immutable`,
      etag,
      'x-og-cache': xCache,
    },
    body: png.toString('base64'),
    isBase64Encoded: true,
  };
}

export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
  const slug = event.pathParameters?.slug;
  if (!slug || !/^[a-z0-9-]{1,80}$/.test(slug)) {
    return { statusCode: 400, headers: { 'content-type': 'text/plain' }, body: 'invalid slug' };
  }
  const key = `og/${slug}.png`;

  const hit = await getObject(key).catch((e) => { console.warn('s3 get failed', e); return null; });
  if (hit) return respond(hit.body, hit.etag, event, 'HIT');

  try {
    const card = await loadCardFromCms(slug);
    const { png, etag, renderMs } = await renderCard(card);
    console.log(JSON.stringify({ msg: 'og.render', slug, ms: +renderMs.toFixed(1) }));
    await s3.send(new PutObjectCommand({
      Bucket: BUCKET, Key: key, Body: png,
      ContentType: 'image/png',
      CacheControl: `public, max-age=${TTL}, immutable`,
    })).catch((e) => console.warn('s3 put failed (non-fatal)', e));
    return respond(png, etag, event, 'MISS');
  } catch (err) {
    console.error('og.render.failed', { slug, err });
    const fallback = await getObject('og/_fallback.png').catch(() => null);
    if (fallback) return respond(fallback.body, fallback.etag, event, 'STALE');
    return { statusCode: 500, headers: { 'content-type': 'text/plain' }, body: 'render failed' };
  }
};

function negotiate(accept: string): { contentType: string; format: 'png' | 'webp' | 'avif' } {
  if (/\bimage\/avif\b/.test(accept)) return { contentType: 'image/avif', format: 'avif' };
  if (/\bimage\/webp\b/.test(accept)) return { contentType: 'image/webp', format: 'webp' };
  return { contentType: 'image/png', format: 'png' }; // crawlers send */* → PNG
}

<meta property="og:image" content="https://cdn.example.com/og/atlas-p95-71ms.png?v=3f9a1c" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:alt" content="Case study: Atlas — p95 71 ms render latency" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://cdn.example.com/og/atlas-p95-71ms.png?v=3f9a1c" />