Expand description
Image renditions — resized variants of a Media row served at
/__media__/<filter_spec>/<media_id>.
Rendition pipeline:
- Tera template emits
<img src="/__media__/fill-300x200/42">via thercms_image_url(media_id, filter_spec)Tera function. - The public route handler looks up the
MediaRenditionkeyed by(media.content_hash, filter_spec). On hit it streams the cached bytes from storage; on miss it loads the original, resizes via theimagecrate, writes the result, and inserts a row. cms_media_renditionrows are GC’d by a futuremanage cms gc-renditions --older-than 30dverb (deferred).
Dedup happens at the (content_hash, filter_spec) level — two
Media rows with identical bytes share renditions automatically.
Structs§
- Encoding
Ops - Encoding hints — applied after the geometric resize. Filter
pipeline spec encodes these as
|format-X|quality-N|bgcolor-XYZchained after the resize op. All optional; defaults match the source format (JPEG → JPEG, anything else → PNG). - Filter
Pipeline - 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 intoEncodingOps. - Media
Rendition - One row per (media, filter_spec) pair. Multiple
Mediarows sharing the samecontent_hashshare renditions implicitly via the(content_hash, filter_spec)key — re-uploading the same image doesn’t regenerate renditions.
Enums§
- Encode
Format - Filter
Error - Filter
Op - Parsed filter spec — what the URL looked like, broken down into a resize operation.
- Rendition
Sig - What a rendition request’s
s=signature says.
Constants§
- DEFAULT_
MAX_ UNSIGNED_ VARIANTS - Default for
max_unsigned_variants.
Functions§
- apply
- Apply
optooriginal(decoded image) and return the resized image. Filters are cheap-and-correct (Lanczos3). ForFill,focal(whenSome) 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-autoor 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_imageon 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
imageper the suppliedEncodingOps, applying background-color flattening when targeting a non-alpha format (JPEG). Returns(bytes, mime, extension). With no format, orformat-auto, the format comes fromauto_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_keybefore 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, elseDEFAULT_MAX_UNSIGNED_VARIANTS. Sizes already generated keep serving; a new one past the cap gets429. 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 thecrate::rendition_route::routerroute. 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. ReturnsNonefor an invalid spec.content_hashis the optionalv=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_imageon the blocking pool. Returns the bytes to store — the re-encoded ones when EXIF was stripped, else the input — and the decoded dimensions.