Architecture

System overview

WASM engine

The image processing engine is written in Zig, compiled to WebAssembly with Relaxed SIMD enabled.

Binary size: 172 KB raw / ~87 KB gzip (Zig WASM, includes libwebp + miniz). The full Worker bundle including libavif lands at ~838 KB gzip.

Module	Language	Purpose
jpeg.zig	Pure Zig	Baseline JPEG decoder (Huffman, IDCT, YCbCr→RGB)
decode.zig	Pure Zig	PNG decoder (all color types, zlib inflate)
encode.zig	Zig + C	JPEG encoder (DCT) + PNG encoder (miniz) + WebP encoder (libwebp)
webp_encode.zig	Zig→C	Binding to libwebp for WebP encoding
resize.zig	Pure Zig	Lanczos3 with SIMD FMA + premultiplied alpha
deflate.zig	Zig→C	Binding to miniz for zlib compression
memory.zig	Pure Zig	WASM heap allocator
libc_glue.zig	Pure Zig	malloc/free/memcpy/math functions for C libraries

Why Zig + C?

Three C libraries are statically linked into the single Worker:

• miniz (public domain), deflate compression for PNG encoding. Smaller and more predictable than Zig stdlib’s flate path on freestanding WASM.
• libwebp (BSD), WebP encoding. Patched cpu.c to add __wasm__ detection (upstream only checks for EMSCRIPTEN). Software math functions in libc_glue.zig replace Zig builtins that recurse on freestanding WASM.
• libavif + libaom: AVIF encoder, always bundled. Custom-built (see tools/build-avif/) with size-first emcc flags and 8-bit-only AV1, weighing ~1.5 MB versus jsquash’s stock ~3.4 MB build. Lazily instantiated on the first AVIF request, so Workers that never serve AVIF never pay its startup cost; set DISABLED_FORMATS="avif" in the Cloudflare dashboard for a runtime kill switch.

SIMD acceleration

The build targets wasm32-freestanding with these features:

• simd128: 128-bit SIMD vectors
• relaxed_simd: fused multiply-add (FMA) for Lanczos kernel
• bulk_memory: fast memory operations
• sign_ext: sign extension instructions

The Lanczos3 resize uses @mulAdd(Vec4, a, b, c) which compiles to f32x4.relaxed_madd: processing 4 RGBA channels per instruction.

Premultiplied alpha

edgesharp premultiplies alpha before resizing and unpremultiplies after, matching Sharp/libvips behavior. Without this, transparent edges get color fringing because the Lanczos kernel blends RGB values from fully transparent pixels.

Durable Object pool

16 deterministically named DOs (img-slot-0 through img-slot-15) hold warm WASM instances. The slot is chosen by hashing the image URL.

V8’s compilation tiers:

1. Liftoff (first request), fast compile, slower execution
2. TurboFan (subsequent requests), optimized SIMD code, full speed

Because the DOs persist between requests, TurboFan has time to optimize the WASM. Cold starts (~2-3s for WASM compilation) only happen when a DO is evicted.

Caching strategy

URLs encode all transform parameters (url, w, q, format), so each unique combination is a distinct cache key. Responses are immutable: the URL uniquely identifies the output.

Cache hierarchy:

1. Cache API: per-datacenter, free, evicted under memory pressure
2. R2: persistent, survives cache eviction. $0.015/GB-month storage, free egress, so cached output ships back to viewers at no bandwidth cost
3. WASM: recomputes on double-miss (extremely rare)

The Vary: Accept header ensures the CDN caches different format responses separately (JPEG vs PNG vs AVIF).