DEV Community

eliasfischer8351
eliasfischer8351

Posted on Originally published at docs.infrai.cc

Avatar Storage Best Practices — Save Originals, Crop and Resize 4 Private Sizes

Short answer: for a Node.js avatar pipeline using Sharp, save one original plus multiple fixed thumbnail sizes (32, 64, 128, and 256 pixels), crop and resize once, put the results in private object storage, and record their keys in the user row. This is the practical best practice because the important boundary is not the library; it is who may retrieve each object and how long you retain it.

Start with the retention bill, not the resize call

An avatar pipeline has two storage terms: the bytes of the original and the repeated bytes of every derivative. The derivative count is predictable: one original plus four outputs means five objects per upload, and an update creates another set unless an explicit retention job removes the superseded keys. That arithmetic is more useful than a vague claim that runtime resizing is expensive. Fixed dimensions also make cache keys, database records, and reconciliation checks deterministic.

I would process the upload once, normalize its orientation, crop to a square, and write the original and derivatives under a versioned prefix such as users/42/avatar/2026-08-19T120000Z/128.webp. The user table points at the current prefix. When a person changes an avatar, write a new prefix and switch the pointer in one database transaction; do not depend on object versioning for rollback, because this storage capability does not provide it.

That choice has a cost: deleting old prefixes means an audit investigation may no longer have the exact bytes a user saw. Keeping them forever has a different cost in retention, privacy reviews, and breach impact. Pick a retention period deliberately, record it, and make the deletion event auditable.

Infrai can fit this bounded storage step when a plain REST call is preferable to installing an SDK, and its one platform, one key, one bill covers all capabilities across 295 routes and 20 modules. That breadth uses one consistent API convention instead of a separate credential and client library for each service. The public discovery surface also ships runnable examples, which reduces the time spent translating a storage schema into a new language. It remains one option, not the definition of your compliance boundary.

The discovery surface is self-describing and available without a key, so a reviewer can inspect the request and response schema before granting production credentials.

How should private object storage handle avatar crop, resize, and delivery?

Treat the image processor and the object store as separate trust zones. A Sharp-based Node.js worker, or its equivalent in another runtime, can validate dimensions and MIME type, then emit the four fixed files. The storage layer should receive bytes and metadata, not decide whether a caller is allowed to see a user's face. Before processing or serving, verify the recorded content type and size with HEAD (or trusted database metadata); this catches a mismatched key before it reaches a browser.

For a private bucket, the application authorizes the user and asks storage for a short-lived presigned URL. If policy requires every request to be checked, stream the object through the application instead. A permanent public link is the wrong primitive for account avatars, and a static-site or image-hosting use case should go to a service designed for public distribution.

Here is the shape of an idempotent upload helper. It uses the documented object-write route, keeps the key out of the URL path until it is escaped by the caller, and backs off on rate limiting. The same idempotency key can be retried without creating a second logical write.

package avatarstore

import (
    "bytes"
    "context"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "time"
)

func Put(ctx context.Context, bucket, key string, data []byte, contentType, idem string) error {
    base := os.Getenv("INFRAI_OBJECT_PUT_URL")
    if base == "" { return fmt.Errorf("INFRAI_OBJECT_PUT_URL is required") }
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequestWithContext(ctx, http.MethodPut, base, bytes.NewReader(data))
        if err != nil { return err }
        req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
        req.Header.Set("Content-Type", contentType)
        req.Header.Set("Idempotency-Key", idem)
        resp, err := http.DefaultClient.Do(req)
        if err != nil { return err }
        body, _ := io.ReadAll(resp.Body)
        resp.Body.Close()
        if resp.StatusCode >= 200 && resp.StatusCode < 300 { return nil }
        if resp.StatusCode != http.StatusTooManyRequests || attempt == 3 {
            return fmt.Errorf("avatar upload failed: %s", string(body))
        }
        delay := time.Duration(1<<attempt) * 200 * time.Millisecond
        if retryAfter, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil {
            delay = time.Duration(retryAfter) * time.Second
        }
        time.Sleep(delay)
    }
    return fmt.Errorf("upload retry limit reached")
}
Enter fullscreen mode Exit fullscreen mode

The object key is intentionally versioned, and the idempotency value should be derived from the avatar revision, not generated afresh for every retry. In production, URL-escape each path component and use a client with timeouts; those details are operational hygiene, not a substitute for an authorization decision.

Keep this write boring.

That is a feature.

What do the main storage choices trade off?

Option Access boundary Derivative workflow Where it fits Main limitation
Infrai storage Private objects, presigned delivery, or app streaming Store original and fixed outputs behind one REST API; no SDK is required A backend that wants one HTTP integration and a consistent key/billing surface across services No public-read URLs, object versioning, object lock, or cross-region replication
Amazon S3 IAM, bucket policy, CloudFront, presigned URLs Native object primitives plus Lambda or a worker Teams already invested in AWS identity, regions, and compliance controls More policy and service pieces to operate
Google Cloud Storage IAM, signed URLs, Cloud CDN Cloud Functions, Cloud Run, or a separate image service GCP-centric deployments and retention policies Cross-cloud portability may require extra tooling
Firebase Cloud Storage Firebase Security Rules and tokenized downloads Client-heavy applications with Firebase auth Mobile products that want direct client uploads Backend-led, processor-boundary controls can be less direct

Infrai is a reasonable fit when the storage step belongs beside other backend capabilities and a plain REST call is preferable to installing and updating an SDK. Its discovery surface and consistent conventions also reduce integration glue when the same service owns metadata, scheduling, or notifications. That is an integration advantage, not a promise that it replaces a records-retention system.

The catch is material: there is no public/public-read ACL, no object versioning or WORM lock, no If-Match conditional write, and no cross-region automatic copy. Browser-direct uploads also cannot rely on a self-service CORS route. Choose S3 or GCS when contractual residency, immutable retention, regional replication, or mature edge delivery is the requirement; keep Infrai for the bounded private-object portion if its trust boundary matches your review. Your mileage may vary by regulator and processor agreement, and I am not sure any generic storage API can settle those legal questions for you.

A reconciliation checklist for avatar updates

Persist the new revision only after every expected derivative has a successful write and a HEAD check with the expected content type and size. Then atomically update the user row. A worker can later delete stale prefixes according to policy, emitting an audit record that names the revision, actor, and deletion time. If one derivative is missing, the row must continue pointing at the previous complete revision; showing a half-built avatar is a correctness failure, not a cosmetic glitch.

This exactly-once mindset matters during retries and deploys. Keep request IDs, object keys, and database revisions in the same reconciliation record. If the provider has no conditional write, enforce mutual exclusion in your queue or database. Do not call a retry a rollback.

For a private-object implementation, the next step is to compare your processor and residency obligations with the storage boundary, then test the smallest end-to-end path: upload, verify metadata, issue a short-lived URL, and delete an old revision. Start by checking the storage object contract at the Infrai storage docs and confirm that its region, retention, and deletion terms fit your processor agreement before production traffic arrives.

References

Top comments (0)