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.
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. - 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). Whenencoding.formatisNone, falls back tosource_mime(JPEG passthrough, anything else → PNG) to preserve the v0.2 behavior. - 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 - Enable signed rendition URLs. Once a key is set, every
rcms_image_url/rcms_image_srcset/rcms_pictureURL carries an HMACs=over(canonical_spec, media_id), and the rendition route (crate::rendition_route) rejects requests whose signature is missing or forged — closing the media-id-enumeration + arbitrary- spec CPU-DoS surface. - 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.- verify_
rendition_ sig - Verify a rendition request’s
s=signature. Returnstruewhen signing is disabled (open contract) ORsigmatches(spec, id). The route calls this before the DB lookup + rendition work so a forged request costs nothing.