dynamic-image-endpoints

Dynamic Image Endpoints

Thesis: Dynamic image endpoints must be (1) pure deterministic renderers — same input always produces identical bytes — and (2) include a renderer version constant in their ETag hash so visual changes invalidate downstream caches on deploy. Without (1), the render is slow, untestable, and depends on external runtimes; without (2), browser/CDN/conditional-GET caches keep serving the old bytes for the full max-age window after every renderer change.

Refrain: Pure function in → deterministic bytes out → version the renderer in the ETag

When this applies

• OG/social-card preview images (/api/v1/profiles/:slug/og-image)
• Badge/credential PNGs (e.g. Labs certifications)
• QR code endpoints with branded chrome
• Invoice/receipt PDF generation
• Any endpoint that returns image bytes computed from request input

Does NOT apply to:

• Static image assets served from frontend/public/images/ (Vite hashes filenames; no dynamic rendering)
• User-uploaded images (no rendering; just storage proxy)
• Avatar/thumbnail resizing (use a dedicated image-proxy library)

Rule 1: Pure renderer functions

The renderer must be a pure Go function: input struct → []byte PNG output, no I/O, no network, no browser, no embedded language runtime.

BAD: Node/browser/screenshot pipeline

// Headless Chrome screenshot: second runtime, non-deterministic pixels.
func RenderOGImage(profile *Profile) ([]byte, error) {
    return chromiumScreenshot("https://localhost/render-og?slug=" + profile.Slug)
}

GOOD: Pure Go renderer

// Pure function: same input → same bytes; testable in 50ms via `go test`.
func RenderPublicProfileOGImage(ctx context.Context, profile *PublicStudentProfile) (*PublicProfileOGImage, error) {
    img := image.NewRGBA(...)
    drawProofCardSurface(img, ...)
    drawText(img, name, ...)
    // ... pure draw calls only
    return &PublicProfileOGImage{PNG: bytes, ETag: computeETag(profile)}, nil
}