Skip to main content

Module rendition

Module rendition 

Source
Expand description

Image renditions — resized variants of a Media row served at /__media__/<filter_spec>/<media_id>.

Rendition pipeline:

  1. Tera template emits <img src="/__media__/fill-300x200/42"> via the rcms_image_url(media_id, filter_spec) Tera function.
  2. The public route handler looks up the MediaRendition keyed by (media.content_hash, filter_spec). On hit it streams the cached bytes from storage; on miss it loads the original, resizes via the image crate, writes the result, and inserts a row.
  3. cms_media_rendition rows are GC’d by a future manage cms gc-renditions --older-than 30d verb (deferred).

Dedup happens at the (content_hash, filter_spec) level — two Media rows with identical bytes share renditions automatically.

Structs§

EncodingOps
Encoding hints — applied after the geometric resize. Filter pipeline spec encodes these as |format-X|quality-N|bgcolor-XYZ chained after the resize op. All optional; defaults match the source format (JPEG → JPEG, anything else → PNG).
FilterPipeline
One end-to-end filter pipeline: an optional resize + optional encoding hints. Parsed from a pipe-separated spec like fill-300x200|format-webp|quality-75|bgcolor-fff. The first segment must be a resize op (fill/max/width/height); remaining segments classify into EncodingOps.
MediaRendition
One row per (media, filter_spec) pair. Multiple Media rows sharing the same content_hash share renditions implicitly via the (content_hash, filter_spec) key — re-uploading the same image doesn’t regenerate renditions.

Enums§

EncodeFormat
FilterError
FilterOp
Parsed filter spec — what the URL looked like, broken down into a resize operation.
RenditionSig
What a rendition request’s s= signature says.

Constants§

DEFAULT_MAX_UNSIGNED_VARIANTS
Default for max_unsigned_variants.

Functions§

apply
Apply op to original (decoded image) and return the resized image. Filters are cheap-and-correct (Lanczos3). For Fill, focal (when Some) shifts the crop so the focal point stays inside the target rectangle — passes (0.5, 0.5) for “no focal set, use geometric center” semantics.
auto_format
The output format for format-auto or no format at all.
check_rendition_sig
Check a rendition request’s signature. The route calls this before the DB lookup + rendition work so a forged request costs nothing.
crop_image
Decode bytes, crop to (x, y, w, h) in source-pixel coords, and re-encode in the same format. Returns (cropped_bytes, mime). SVG inputs are rejected — vector crop is a different surface.
crop_image_off_runtime
crop_image on the blocking pool: a full decode + encode is hundreds of milliseconds of CPU for a large photo, and inline it parked a Tokio worker for all of it.
encode
Encode image per the supplied EncodingOps, applying background-color flattening when targeting a non-alpha format (JPEG). Returns (bytes, mime, extension). With no format, or format-auto, the format comes from auto_format.
init_signing
Fix the signing key (reading or generating the CMS key file if it is derived). The rendition router calls this at boot; call set_signing_key before it.
max_unsigned_variants
Without a strict key, the most distinct renditions unsigned anonymous requests may cause to exist for one image (#643): RCMS_RENDITION_MAX_UNSIGNED, else DEFAULT_MAX_UNSIGNED_VARIANTS. Sizes already generated keep serving; a new one past the cap gets 429. Signed URLs (every image URL the CMS renders) never count against it, so a visitor can’t use up the slots a page needs. Signed-in editors are not capped.
register_tera_function
Register rcms_image_url(media_id, filter) on the user’s Tera instance. Templates write <img src="{{ rcms_image_url(media_id=42, filter="fill-300x200") }}"> and the URL gets resolved lazily by the crate::rendition_route::router route. The function only validates the filter spec; it does NOT touch the DB, so it stays sync + cheap.
rendition_url_for
Build a concrete rendition URL for spec — parsed + canonicalized, signed when signed URLs are enabled. Returns None for an invalid spec. content_hash is the optional v= cache-buster. Used by the JSON API to emit ready-to-use rendition URLs (clients can’t sign a {filter_spec} template themselves).
set_signing_key
Make rendition signing strict with your own key: every request to the rendition route must then carry a valid s= signature, so media ids can’t be enumerated and no unsigned size is ever generated.
strip_exif_if_image
Re-encode an image’s bytes to strip EXIF metadata. Returns (Some(stripped_bytes), Some((width, height))) on success; for non-image MIMEs or SVGs returns (None, None); for decode errors returns (None, None) so the caller can keep the original bytes.
strip_exif_off_runtime
strip_exif_if_image on the blocking pool. Returns the bytes to store — the re-encoded ones when EXIF was stripped, else the input — and the decoded dimensions.