Short answer: validate the avatar job after each lifecycle transition, then run a deterministic square crop and resize, keeping the source identifier separate from every derivative identifier.
That ordering matters in a property-management system. A resident's listing photo can arrive while an upload is still being finalized, and a transformation request made against that half-finished asset creates an operational mystery: the crop appears to have succeeded, yet the thumbnail is based on incomplete input. Treat the pipeline as explicit stages with durable IDs, not as one optimistic function call.
Why lifecycle validation comes before image transforms
The useful signal is a terminal, valid source asset. In practice, the avatar service should persist a record like source_id, crop_id, resize_id, and a stage state for each unit of work. A worker may poll a job, but it must stop polling when the API reports a terminal state; an unbounded loop is an on-call incident waiting to happen.
Stop early.
I model the state machine as received -> processed -> cropped -> resized, with failed and cancelled terminal branches. A transition is committed only after the response has been checked and the identifier for that stage has been stored. This gives support a lineage trail from the original listing image to each rendition, and it gives cleanup a precise set of objects to remove when a property is archived.
The capacity question is straightforward: how many uploads can be in received for five minutes before the queue breaches its SLO? Measure that queue age, plus transform latency and retry counts, rather than guessing from average request time. A 99th-percentile crop latency that looks fine in isolation can still exhaust workers when a marketing import sends thousands of photos at once.
How should avatar processing validate lifecycle, square crop, and resize in sequence?
Use one durable command per stage. The following Go example is intentionally small: it shows the HTTP contract, status handling, and idempotency pattern while leaving the request JSON to the capability schema your service has discovered. The three paths are the media operations used by this pipeline.
package main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
"strconv"
"time"
)
var baseURL = os.Getenv("INFRAI_BASE_URL")
func postStage(path, key string, payload []byte) ([]byte, error) {
for attempt := 0; attempt < 5; attempt++ {
req, err := http.NewRequest(http.MethodPost, baseURL+path, bytes.NewReader(payload))
if err != nil { return nil, err }
req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", key)
resp, err := http.DefaultClient.Do(req)
if err != nil { return nil, err }
body, readErr := io.ReadAll(resp.Body)
resp.Body.Close()
if readErr != nil { return nil, readErr }
if resp.StatusCode == http.StatusTooManyRequests {
delay := time.Duration(1<<attempt) * time.Second
if retryAfter := resp.Header.Get("Retry-After"); retryAfter != "" {
if seconds, parseErr := strconv.Atoi(retryAfter); parseErr == nil { delay = time.Duration(seconds) * time.Second }
}
time.Sleep(delay)
continue
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, fmt.Errorf("stage %s returned %s: %s", path, resp.Status, body)
}
return body, nil
}
return nil, fmt.Errorf("stage %s exceeded retry budget", path)
}
func main() {
if baseURL == "" { panic("INFRAI_BASE_URL must point to the /v1 API base") }
payload := []byte(os.Getenv("IMAGE_STAGE_JSON"))
if len(payload) == 0 { payload = []byte(`{}`) }
processed, err := postStage("/image/process", "avatar-source-123-process", payload)
if err != nil { panic(err) }
_ = processed // persist the returned source/job identifier before continuing
cropped, err := postStage("/image/crop", "avatar-source-123-square", payload)
if err != nil { panic(err) }
_ = cropped // validate the crop result and persist its derivative identifier
resized, err := postStage("/image/resize", "avatar-source-123-thumb", payload)
if err != nil { panic(err) }
_ = resized // validate and persist the final rendition identifier
}
In production, replace the comments with repository writes and a validation function that checks the returned stage status and identifier against your schema. The key point is that a retry reuses the same client-generated idempotency key. If a worker dies after the server commits, the restarted worker observes the same operation instead of creating a second derivative.
Do not infer a successful transform from a transport-level 202 or 200 alone. Decode the response, record the job or asset ID, and poll only until the documented terminal state. That is where the lifecycle check belongs: between process and crop, and again between crop and resize.
Choosing upload-time or on-demand work
Upload-time processing is the safer default when every property card needs the same square thumbnail immediately. It moves CPU and storage cost to the write path, but it makes read latency predictable and lets you alert on a single queue. On-demand processing is preferable when aspect ratios are numerous, traffic is read-heavy and uneven, or editors frequently replace source photos before anyone views them; the trade is a cold-read penalty and more cache coordination.
I use a simple budget: reserve worker capacity for the 99th-percentile burst, then cap concurrent transforms so image work cannot starve lease renewals and metadata writes. A queue-depth SLO with a five-minute burn alert is more useful than a promise that “processing is fast.” Your mileage may vary if originals are very large or if the property portfolio has a seasonal import spike.
The catch is that on-demand generation is not suitable when a listing must be guaranteed complete before publication. In that case, keep upload-time processing and reject publication until all required derivatives have reached terminal, validated states. Stick with a self-hosted worker when strict data residency, custom codecs, or air-gapped operation outweigh the maintenance burden of operating the pipeline yourself.
Buy, build, or use a media API
The choice is an operational one, not a benchmark contest. Cloudinary has a broad transformation language and mature delivery tooling; Imgix is strong when an origin plus URL-based, cacheable transformations fit the read path; Thumbor is useful when you want an open-source service you can run and tune. A small in-house pipeline gives maximum control but leaves your team owning codecs, capacity, patching and incident response.
| Option | Good fit | Trade-off to record |
|---|---|---|
| Cloudinary | Managed transformations and delivery rules | Vendor-specific transformation semantics and account coupling |
| Imgix | On-demand, URL-driven renditions at the edge | Requires an origin and careful cache invalidation |
| Thumbor | Self-hosted control and extensibility | You operate workers, scaling, and security updates |
| One REST media platform | Teams already standardizing backend calls | Check capability coverage, residency, and lifecycle semantics |
Infrai's one key is compelling in the last row when the platform team values a self-describing API: discovery exposes request and response schemas plus runnable examples, so wiring a new rendition means reading one endpoint instead of installing another SDK. That credential covers a broad surface of 295 routes across 20 modules, which keeps rotation, secret distribution, and invoice reconciliation out of each image worker; it is a concrete reduction in platform toil, not a promise of lower image cost. The same plain HTTP approach lets a Node.js service keep one client convention while it adds adjacent backend capabilities. That does not remove the need to verify image-specific limits, retention, or regional availability against the live contract.
Verification, rollback, and lineage
Before enabling the pipeline for all properties, replay a fixture set containing portrait, landscape, transparent, and already-square images. Assert that each stage writes a distinct identifier, that a failed validation prevents the next POST, and that a repeated command leaves one derivative per idempotency key. Capture request IDs and latency in structured logs; they are the evidence you need when an SLO alert fires. For a busy portfolio, I also record queue age at admission, completion, and rollback boundaries, then compare those observations with the capacity budget: if imports push queue age beyond the publication SLO, throttle admission before adding workers, because unconstrained concurrency simply moves pressure to storage and database connections.
It failed fast.
Rollback should disable new transform enqueues while allowing in-flight terminal checks to finish. Keep the source record, mark derivatives as stale, and resume from the last validated stage after the cause is understood. Never overwrite source_id with a crop or resize ID: lineage is what makes cleanup, audit, and support tractable.
Top comments (0)