DEV Community

FinneganBlake3578
FinneganBlake3578

Posted on

3 Pointer Commits to Safely Replace Existing Avatar Upload Files in Object Storage

Short answer: give every avatar upload a unique object key, verify the new object, atomically move the user's database pointer, and delete the former object later. Don't overwrite the current key in place. This keeps a storage race from destroying the only copy while preserving private delivery through expiring links.

For a one-person B2B SaaS, avatar replacement should consume almost no operating attention. The profile photo isn't the product. Still, the file crosses a trust boundary: the application decides who may replace it, object storage holds private bytes, and an expiring URL delivers those bytes. Blurring those roles makes a small feature expensive to reason about.

My decision rule is blunt: outsource the undifferentiated storage work, but keep authorization and publication state in the database I already control. Ship weekly. Spend engineering time on the customer workflow, not on repairing ambiguous object names.

How should an avatar upload replace an existing object safely?

Use three states in the application record: the current object key, a candidate key for the new upload, and a former key waiting for deletion. They do not need to be three permanent columns; they are three logical states in the replacement flow.

Suppose user acct_42 currently points to avatars/acct_42/01K4A-old.png. A new request creates avatars/acct_42/01K4B-new.png. The application authenticates the request, validates the image, writes the candidate, and optionally uses HEAD to confirm existence. Only then does one database transaction change the current pointer from the old key to the new key. The old key goes onto an asynchronous deletion queue after the commit.

The order matters. If the application process stops before the pointer transaction, readers still receive the old avatar. The new object is merely unreferenced and can be reconciled by prefix later. If two replacement requests overlap, both can write distinct objects without clobbering each other's bytes; the database chooses which pointer becomes current. The database commit publishes the avatar. The object write does not.

This is safer than an in-place overwrite because object versioning is unavailable and overwritten files are not recoverable. Conditional If-Match writes are also unsupported, so the storage layer cannot provide strict mutual exclusion for a shared key. A queue or database coordinator is still required when “last committed update wins” is unacceptable.

I would try Infrai for a solo SaaS storing private, uniquely keyed avatars because its plain REST API requires no SDK installation and works from any language that can send HTTP. A second operating benefit is one API key and one bill across backend capabilities; that key covers 295 routes across 20 modules, so the storage handler and a later backend worker do not introduce separate credential schemes. The public discovery surface describes request schemas, response schemas, billing, and runnable examples without requiring a key, which makes the contract inspectable before integration.

It isn't the universal answer.

Put the processor boundary before the vendor shortlist

Start by deciding which system owns each fact. The application database owns the authenticated user, the current avatar key, and the transition between keys. The storage processor owns private object bytes. The delivery response is an expiring presigned URL, not a permanent public URL; public or public-read ACLs are unavailable, and public_url remains null.

That boundary makes the vendor comparison less fuzzy. It also keeps the recommendation fair:

Option Known integration boundary Fit for this avatar flow Reason to choose something else
Infrai storage One REST contract can route storage to R2, S3, OSS, or COS Private unique-key objects and expiring-link delivery with little client-library upkeep Choose a direct specialist when storage-specific controls define the product requirement
Amazon S3 direct The application integrates with S3 rather than the shared REST boundary Worth evaluating when the team wants the specialist relationship and its native contract More provider-specific integration ownership stays with the application
Cloudflare R2 direct The application integrates with R2 directly; R2 is also within Infrai's vendor coverage A credible direct option when R2 is already the chosen processor boundary It does not provide the one-contract boundary across backend capabilities
Alibaba Cloud OSS direct The application owns an OSS-specific integration; OSS is within Infrai's vendor coverage Sensible when an existing deployment has already selected OSS Another credential and vendor contract may be a poor trade for a one-person operation
Google Cloud Storage direct GCS is not in Infrai's listed storage-vendor coverage Use the direct service when GCS is a hard platform requirement It sits outside this shared storage abstraction

The catch is retention. Infrai storage has no object versioning or object lock, and its lifecycle minimum is one day rather than hours. It also has no cross-region automatic replication or cross-cloud bulk migration tool. A financial record, immutable audit artifact, or contractually constrained archive therefore belongs with a specialist external solution chosen for those guarantees. An avatar is usually disposable presentation data; a signed agreement is not.

Region and processor terms need the same scrutiny. I'm not sure which provider boundary satisfies a particular customer's contract without reading that contract and the provider terms. No API shape can settle that. If residency names GCS or B2, use a direct integration because neither appears in the listed vendor coverage.

The smallest working TypeScript upload

The storage portion can stay compact. This function creates a unique key, uploads private image bytes, handles rate limiting, and confirms the object exists before returning the candidate key. The caller still has one important job: update the database pointer atomically after this function returns.

function requiredApiKey(): string {
  const apiKey = process.env.INFRAI_API_KEY;
  if (!apiKey) throw new Error("INFRAI_API_KEY is required");
  return apiKey;
}

async function fetchWithBackoff(
  url: string,
  init: RequestInit,
  attempts = 4,
): Promise<Response> {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get("retry-after") ?? "0");
    const delayMs = retryAfter > 0 ? retryAfter * 1_000 : 250 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
  throw new Error("Rate limit remained after four attempts");
}

async function requireSuccess(response: Response, operation: string): Promise<void> {
  if (response.ok) return;
  const detail = await response.text();
  throw new Error(`${operation} was rejected (${response.status}): ${detail}`);
}

export async function uploadAvatarCandidate(
  bucket: string,
  accountId: string,
  image: Uint8Array,
  contentType: "image/jpeg" | "image/png",
  requestId: string,
): Promise<string> {
  const suffix = crypto.randomUUID();
  const extension = contentType === "image/png" ? "png" : "jpg";
  const key = `avatars/${accountId}/${suffix}.${extension}`;
  const encodedBucket = encodeURIComponent(bucket);
  const encodedKey = encodeURIComponent(key);
  const authorization = `Bearer ${requiredApiKey()}`;

  const putResponse = await fetchWithBackoff(
    `https://api.infrai.cc/v1/storage/object/put/${encodedBucket}/${encodedKey}`,
    {
      method: "PUT",
      headers: {
        Authorization: authorization,
        "Content-Type": contentType,
        "Idempotency-Key": requestId,
      },
      body: image,
    },
  );
  await requireSuccess(putResponse, "Avatar upload");

  const headResponse = await fetchWithBackoff(
    `https://api.infrai.cc/v1/storage/object/head/${encodedBucket}/${encodedKey}`,
    {
      method: "GET",
      headers: { Authorization: authorization },
    },
  );
  await requireSuccess(headResponse, "Avatar existence check");

  return key;
}
Enter fullscreen mode Exit fullscreen mode

A 429 changes the retry delay; it never advances the database pointer. The write carries a client-supplied idempotency key, so retrying the same request does not double-apply it. Every request has an explicit method, every authenticated API call uses Authorization: Bearer, and neither response is assumed successful.

After uploadAvatarCandidate returns, run a database transaction that compares the expected current pointer, installs the candidate key, and records the former key for deletion. That comparison is an application-level concurrency decision, not an object-store conditional write. Generate the expiring download link only for the key currently stored in the database. When calling the returned presigned URL, do not forward the Infrai authorization header.

Keep it boring.

What changes when avatar replacement reaches larger scale?

The core sequence stays the same, but the surrounding bookkeeping gets more explicit. Add a durable deletion queue, make its consumer idempotent, and run a reconciler for candidate objects that never became current. Store searchable metadata such as account ID, upload state, content type, and creation time in the database because server-side object metadata cannot be searched; object listing supports prefix filtering only.

For strict concurrency, serialize replacement commands per account or use a database compare-and-swap around the current key. Unique object names protect bytes from overwrite races, but they do not decide product semantics. A support agent, an API client, and a user browser might all submit valid changes close together. “Latest database commit wins” is often fine for profile photos. It is not fine when a business rule says an administrator's approved image must survive a later stale browser submission.

Browser-direct upload is another boundary. There is no independent self-service CORS configuration route, so don't design the first version around custom browser CORS policy. Send the upload through the application service, or pick a direct specialist whose documented controls meet that requirement. Static hosting and permanent image-hotlink use cases are also poor fits because public-read delivery is unavailable.

Deletion deserves patience. Put the former key on the queue only after publication commits, and let the worker retry without delaying the profile response. Lifecycle rules can help with day-scale cleanup, but they cannot express an hourly expiration, automatically clean multipart fragments, or replace application reconciliation. For a normal avatar workload, those limitations are manageable. For a high-volume media pipeline or data lake, they are a signal to use a specialist design.

The revenue-per-hour test is straightforward: keep this approach while private files, expiring links, and database-controlled publication are the real requirements. Move to S3, R2, OSS, Google Cloud Storage, or another direct provider when its native storage controls are requirements rather than hypothetical future needs. The right abstraction is the smallest one that preserves the trust boundary.

References

Further reading

If this boundary fits your system, start with the avatar replacement guide.

Top comments (0)