ImageKit conformance

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

The reference is ImageKit's published transformation docs. When this guide and ImageKit's docs disagree, treat ImageKit's docs as the contract and file an issue against image_plug.

URL forms

Provider configuration

plug Image.Plug,
  provider: {Image.Plug.Provider.ImageKit,
             mount: "",
             endpoint: "your_imagekit_id",
             strict?: true,
             signing: %{keys: [secret], required?: true}},
  source_resolver: ...

• :mount — path prefix to strip first. Defaults to "" (root).

• :endpoint — additional path segment to strip after :mount. ImageKit URLs commonly include a per-account endpoint id (e.g. /your_imagekit_id/). Defaults to "".

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

• :signing — nil or %{keys: [...], required?: bool}. Wire format matches ImageKit's hosted SHA-1 signed URLs.

Option-key conformance

Every option ImageKit documents in the transformation reference. ✅ = full conformance. ⚠️ = partial / behavioural difference. ❌ = not implemented.

Sizing

Format / output

Effects

Geometry

Overlays

Misc

Behavioural differences

Multi-stage chained transforms collapse to one stage

ImageKit lets you chain transforms with :: tr:w-200,h-100:rt-90:e-blur-300. The v0.1 IR doesn't model multi-pass pipelines — all options compose into one Resize op, one Adjust op, etc.

The provider flattens chained stages by joining them with , and processes them as a single set. For most useful transforms (resize + format + quality + a single effect) this is identical to ImageKit. Recipes that genuinely require ordering lose information: only the last write per op kind survives.

Path-prefix vs query-string

ImageKit accepts both tr:w-200/sample.jpg and sample.jpg?tr=w-200. The provider recognises both — and even accepts a mix (tr:w-200/sample.jpg?tr=q-80 produces the merged set w-200,q-80). The component-side adapter only emits the path-prefix form (the documented default). Mixing is permitted on inbound for compatibility with hand-rolled URLs.

Canonical-string for signing

ImageKit's HMAC payload is the path-and-query of the request, with the ik-s parameter removed but the ik-t parameter retained. The hash is HMAC-SHA1 keyed by the secret, hex-encoded lowercase. We replicate this exactly. URLs signed by ImageKit's hosted service verify against an image_plug deployment with the same secret, and vice-versa.

e-contrast is approximated

ImageKit's e-contrast is a single boolean toggle (auto-contrast on the input). The Image library doesn't expose a content-aware contrast knob, so we approximate as Adjust{contrast: 1.1} — a fixed mild bump. Visible on low-contrast inputs; close-enough on the rest.

Conformance summary

Reporting gaps

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