For social profile avatars, process a bounded original at upload, then serve precomputed sizes with a deliberate crop policy and lifecycle checks. That choice keeps profile reads predictable; on-demand transforms remain useful for rare dimensions, but they move latency and failure handling into every request.
Short answer: validate the upload once, keep the original immutable, generate a small set of derivatives, and make replacement/deletion an explicit state transition. Measure p95 transform time, cache hit rate, bytes served, and stale-avatar incidents before changing the split.
The experiment: why eager derivatives won
I first modeled an avatar URL as a pure resize function. It looked tidy: store one object, put width and height in the URL, and transform at the edge. The first profile page was fine. A busy feed was not. A single account could request 32, 64, 96, and 128 pixel variants across clients, and every cache miss paid decode plus encode cost. Worse, a crop change silently altered old URLs, so a moderation review could no longer reproduce what a reviewer had seen.
The revised experiment used a content-addressed original and four named derivatives. Upload work runs once, behind a queue; reads only select a completed derivative. I kept a fallback URL for the original while a job is pending, with a bounded display size so an enormous camera image cannot become a surprise download.
That is an engineering choice, not a law. If your app has user-defined dimensions, live filters, or very low read volume, on-demand processing can be the smaller system. Your mileage may vary; the deciding evidence is traffic shape, not a fashionable architecture.
What should resize, crop, and lifecycle validation guarantee?
Resize and crop are separate contracts. Resize defines the maximum rendered box; crop defines which pixels survive when the source aspect ratio differs. For an avatar, a centered square is a reasonable default, but faces near an edge make a focal point or user-adjusted crop safer. Record the crop rectangle (normalized coordinates work) with the asset version so a later re-encode does not invent a new composition.
Validation needs more than a MIME string. Decode the bytes, enforce a pixel-count and file-size ceiling, normalize orientation, and reject images whose decoded dimensions are zero or implausible. Keep the original bytes quarantined until these checks pass. The browser's accept="image/*" hint is not a security boundary.
Lifecycle is where many “image bugs” are really data-model bugs. Give each upload an immutable assetId and a monotonically increasing version. A profile points to the active version; derivatives point back to that version. On replacement, publish the new version only after required derivatives are ready. On deletion, revoke the profile pointer first, then remove objects asynchronously, retaining an audit record without retaining the image.
A small, testable media contract
The following TypeScript sketch keeps policy independent from any image library. The adapter can call a local decoder, a worker, or a hosted transformer; tests can supply a fake implementation.
type Crop = { x: number; y: number; width: number; height: number };
type ImageProbe = {
mime: string;
width: number;
height: number;
bytes: number;
orientation: number;
};
const LIMITS = { bytes: 8_000_000, pixels: 40_000_000 };
export function validateAvatar(probe: ImageProbe, crop?: Crop): void {
if (!probe.mime.startsWith("image/")) throw new Error("unsupported media");
if (probe.bytes > LIMITS.bytes) throw new Error("file too large");
if (probe.width * probe.height > LIMITS.pixels) throw new Error("too many pixels");
if (probe.width < 32 || probe.height < 32) throw new Error("image too small");
if (crop && (crop.x < 0 || crop.y < 0 || crop.x + crop.width > 1 || crop.y + crop.height > 1)) {
throw new Error("crop outside source");
}
}
export function derivativeKey(assetId: string, version: number, size: number): string {
return `avatars/${assetId}/v${version}/${size}.webp`;
}
Tests should include truncated bytes, a valid file with a misleading extension, EXIF rotation, a crop rectangle touching each boundary, and a replacement that races a read. Property-based tests are useful for crop coordinates because hand-picked examples miss floating-point edges. Keep a fixture with a face close to each corner; that catches a center-crop regression quickly.
When does on-demand processing make sense?
On-demand transforms fit long-tail sizes and products that let users zoom or apply a new effect at read time. Put a strict allow-list around dimensions, cache by source version plus transform parameters, and cap concurrent decodes. Never let arbitrary query parameters become unbounded work. A cache key without the asset version is a stale-content bug waiting for a deployment.
Eager generation fits a known set of UI slots and high read fan-out. The catch is queue complexity: you need retries, idempotent jobs, and a policy for a derivative that never completes. It is not suitable when every consumer invents a new transform; stick with an on-demand path in that case, or narrow the product contract first.
Measuring the decision in production
Log transform duration by source megapixels, derivative size, and codec. Track cache hit rate separately for each requested size; one aggregate number hides a cold mobile variant. Emit an asset-version label with every profile response, then alert when a response references a version whose required derivative is absent.
I would run a seven-day shadow comparison: calculate the would-be on-demand work for uploads while serving eager derivatives, without sending duplicate bytes to users. Compare CPU seconds, queue delay, p95 profile latency, storage growth, and deletion completion time. A lower bill is not the objective; a predictable contract is.
The failure mode I watch most closely is a split-brain profile. Imagine version 18 is active, its 96 pixel derivative is ready, and a replacement uploads version 19 just as a mobile client retries an old request. If the URL is keyed only by user ID, a cache can serve the old pixels with the new metadata, or the reverse. The fix is boring and effective: include the immutable version in the object key and in the response metadata, and make the publish operation conditional on the derivative manifest. A worker may run twice; the second run must write the same bytes or safely discover that the key already exists. A delete request should also be idempotent, because clients retry on network timeouts and queues redeliver jobs. I would test this sequence with a fake clock, two concurrent replacements, and a cache that intentionally returns stale entries. The expected result is not “the newest image always wins” in every in-flight response. The expected result is that each response names a version, and that version can be fetched, audited, and retired according to policy.
Ship it.
Then inspect it.
Metrics are only useful when they map to a decision. A high miss rate for 128 pixel images may justify one more eager derivative; a high decode queue with low traffic points to an upload limit or worker setting. Keep those hypotheses in the dashboard description so the next on-call engineer knows what action the graph is meant to trigger. I'm not sure a single global threshold will survive a product that adds video or animated formats; revisit limits when the media contract changes, and record the reason for each adjustment.
Three words matter: version every object.
Top comments (0)