Cloudflare Images conformance

This guide documents image_plug's conformance to the Cloudflare Images URL grammar — what we implement, where we differ, and what we deliberately don't ship.

The reference is Cloudflare's published URL spec. When this guide and Cloudflare's documentation disagree, treat Cloudflare's docs as the contract and file an issue against image_plug.

URL forms

Provider configuration

Both URL forms come from the same provider. Configure via:

plug Image.Plug,
  provider: {Image.Plug.Provider.Cloudflare,
             mount: "/img",
             hosted_account_hash: "abc123",
             strict?: true,
             variants_enabled?: true},
  source_resolver: ...

• :hosted_account_hash — when set, the hosted form is recognised. When nil (default), only /cdn-cgi/image/... is.

• :variants_enabled? — false disables variant lookup; hosted-form requests with a variant tail return :variant_not_found.

• :strict? — true (default) rejects unknown option keys with :unknown_option; false logs and ignores them.

Option-key conformance

Every key Cloudflare documents in the URL options reference. ✅ = full conformance. ⚠️ = partial / behavioural difference. ❌ = not implemented.

Resize / sizing

Output / format

Effects

Geometry

Drawing / overlays

| draw | ⚠️ | Cloudflare's docs only define draw for the Workers binding (a JSON array). We invent a URL grammar of the form draw=url(<absolute-url>);width=N;height=N;fit=...;gravity=...;opacity=0.5;repeat=true|x|y;top=N;right=N;bottom=N;left=N;background=#hex;rotate=90. Multiple draw= entries become multiple layers in declaration order. The inner url(...) and ; separators must be percent-encoded so the path-split survives. The interpreter prefers SVG composition for .svg sources (scale-clean); bitmap sources are decoded and composited with the configured opacity and position. |

Misc

Behavioural differences

These are intentional choices where image_plug does something Cloudflare does not (or vice versa).

Format negotiation for format=auto

Cloudflare picks AVIF → WebP → original-format based on the Accept header and the source's content-type. We do the same, gated by Image.Plug.Capabilities.avif_write?/0 — if libvips lacks AVIF write support at boot, the AVIF tier is skipped and format=avif (whether requested explicitly or via auto) is served as WebP, with x-image-plug-format-fallback: avif->webp on the response. Cloudflare's edge always has AVIF; ours depends on the build. Document this loudly to users.

Output format negotiation: image/* and */* in Accept

Per the HTTP spec, image/* matches every image/<subtype>. We honour that — if image/* is present and Image.Plug.Capabilities.avif_write?/0 is true, format=auto returns AVIF. Cloudflare's behaviour with image/* alone is not documented; this is an interpretation, not a contract.

Option-cardinality

Cloudflare's docs are silent on what happens when an option key appears twice (width=200,width=400). We treat duplicates as last-wins through the parser, then the normaliser enforces "at most one" cardinality per op kind and raises :invalid_option if multiple op-emitting keys collide after parsing (e.g. two width= entries that produce two Resize ops would fail normalisation). In practice the parser already de-duplicates inside one Resize op so this only matters for the few keys that emit a fresh op each time. Behaviour is consistent and predictable; it may differ from Cloudflare's edge.

ETag derivation

Cloudflare's URLs are content-addressed by their CDN; ours derive a strong ETag from meta.etag_seed (provided by the source resolver) plus the normalised pipeline's fingerprint plus the chosen output format. Two URLs that differ only in option order produce the same ETag. If you mirror Cloudflare's URLs through image_plug and want a single consistent cache key across both deployments, you'll need to either canonicalise URLs upstream or accept different ETags.

<picture> markup is the client's responsibility

Cloudflare's documented URL grammar is consumed by client markup the developer writes by hand or via a JS helper. We do the same: image_plug serves bytes, and the image_components sister package emits <.image> and <.picture> markup using the same URL grammar.

Conformance summary

| Drawing/overlays (draw=) | Partial | URL grammar invented (Cloudflare doesn't define one); SVG-preferred composition; opacity/position implemented; repeat=true|x|y not yet executed. | | Metadata (metadata=copyright) | Partial | Treats :copyright as :none for now. | | Animation (anim=false) | Stub | Parsed; encoder doesn't yet collapse animated inputs. | | Subject segmentation (segment=foreground) | Stub | Parsed; interpreter is a no-op. | | URL-level onerror=redirect | Partial | Parsed; plug-level :on_error config wins until the request-level override lands. | | Signed URLs | Full | Same parameter names (sig, exp), algorithm (HMAC-SHA256), and canonical string as Cloudflare's hosted Images. URL format interchangeable; HMAC value differs because secrets do. |

Reporting gaps

Open an issue at the project's GitHub. Include the request URL, the expected behaviour per Cloudflare's docs (with a link), and the actual response.