DEV Community

JedidiahRhodes8293
JedidiahRhodes8293

Posted on

Small Image Uploads: Object Storage Multipart Rules for Avatar and Tenant Files

Short answer: an avatar upload normally deserves one bounded request, not multipart coordination. Keep the multipart path for tenant snapshots where a retry would replay a meaningful fraction of a large file. Make that boundary observable: record bytes, elapsed time, retry bytes, and tenant identity, then move the threshold when the evidence changes.

This sounds like a small API choice. In a marketplace, it is also a fairness rule. A seller changing a 96 KB profile image should not compete with a 400 GB catalog restore for the same worker slots. The upload policy has to protect both paths.

Should small image uploads use multipart object storage?

Path Pick this when What to measure Main guardrail
Single streamed request The object fits a bounded connection and a restart is cheap p95 duration, failed bytes Maximum object size and checksum
Resumable single request The link is variable but the object is still modest reconnect count, total retry bytes Idempotency key and expiry
Multipart transfer A failed connection would repeat substantial work completed-part ratio, assembly time Part receipts and orphan cleanup

For a 120 KB avatar, the first row is usually the clearest operational contract. Validate dimensions and content type before issuing a write. Stream the body so a malicious client cannot turn a small declared file into unbounded memory use. Store a digest and the tenant ID with the object metadata.

The third row is a different job. A selected tenant snapshot may contain millions of records and large media blobs. Splitting it into independently retryable parts lets a worker resume after a process restart. It also creates more state: an upload handle, part numbers, checksums, expiry, and a final assembly step. That state is justified by throughput and recovery time, not by the word “image.”

Measure twice.

What does the boundary look like in production?

I prefer a policy that explains itself in telemetry. A hard-coded “multipart after 5 MB” survives until regions, links, and tenant sizes change; then it becomes folklore. The policy below uses a configured byte floor plus a retry signal from recent transfers.

type TransferMode = "single" | "resumable" | "multipart";

type TransferPolicy = {
  multipartFloorBytes: number;
  resumableFloorBytes: number;
  retryBytesRatioForMultipart: number;
};

export function chooseMode(
  bytes: number,
  observedRetryBytesRatio: number,
  policy: TransferPolicy,
): TransferMode {
  if (bytes >= policy.multipartFloorBytes ||
      observedRetryBytesRatio >= policy.retryBytesRatioForMultipart) {
    return "multipart";
  }
  if (bytes >= policy.resumableFloorBytes) return "resumable";
  return "single";
}
Enter fullscreen mode Exit fullscreen mode

The function is deliberately boring. It does not inspect a vendor-specific URL or infer a tenant from a filename. The caller supplies a measured ratio and an explicit policy version. That makes a decision replayable during an incident review.

For avatars, issue a short-lived signed upload URL only after authorization. The browser sends the bytes directly to object storage, while the application records an intent containing tenant, object key, expected length, and a correlation ID. A completion event is accepted only when the observed length and digest match the intent. Presigned URLs are bearer tokens, so their scope and lifetime belong in the threat model, not in a frontend constant. The S3 presigned URL guidance describes this constraint clearly.

For a backup, the receipt needs more detail. Persist the opaque upload handle, expected bytes, expected digest, and completed part numbers. A worker can then ask for the next missing part instead of starting over.

type SnapshotReceipt = {
  tenantId: string;
  snapshotId: string;
  policyVersion: string;
  expectedBytes: number;
  expectedSha256: string;
  completedParts: number[];
  state: "queued" | "copying" | "verifying" | "ready" | "failed";
};

function nextPart(receipt: SnapshotReceipt, totalParts: number): number | null {
  for (let part = 1; part <= totalParts; part += 1) {
    if (!receipt.completedParts.includes(part)) return part;
  }
  return null;
}
Enter fullscreen mode Exit fullscreen mode

Do not activate a restored snapshot merely because every part arrived. Verify the assembled byte count and digest, validate the snapshot schema, and only then switch the tenant’s read pointer. Keep the old pointer until that transaction succeeds. This is where a throughput optimization becomes a correctness feature.

Which signals tell you the threshold is wrong?

Start with four counters per tenant and per region: uploaded bytes, wall-clock seconds, retry bytes, and active transfer slots. Add a histogram for part upload duration and a counter for abandoned multipart sessions. Emit events for intent created, part accepted, checksum mismatch, assembly completed, and activation completed. The event payload should include a correlation ID and policy version. Never put access tokens or image contents in the log.

The useful comparison is not “multipart is faster.” It is “how much work did a failure force us to repeat?” Suppose a 200 GB snapshot commonly retries 65% of its bytes on a single connection. That ratio is evidence for resumability or multipart in that path. A 120 KB avatar with the same network hiccup still costs little to retry; adding part coordination would enlarge the failure surface without improving user-visible latency.

A canary should exercise both workloads. Kill a worker after part 3 of 8. Throttle a connection during part 7. Replay the same idempotency key. Then inspect whether one receipt continues, whether duplicate parts are harmless, and whether a stale session is removed after its expiry. These tests are more informative than a synthetic “upload succeeded” check because they probe the state transitions that operators must repair.

The most revealing drill is intentionally tedious: start a restore for a tenant with a known 200 GB snapshot, let three parts finish, terminate the worker, and change the policy version before the replacement worker resumes. The replacement should read the old receipt, preserve its completed checksums, and continue without creating a second activation candidate. While that happens, send a burst of avatar uploads from another tenant and watch queue delay, not just aggregate throughput. If the small writes wait behind the restore, the system has optimized a benchmark while degrading the marketplace. Keep the event timeline for the drill; it becomes a runbook example for the next on-call engineer and a regression fixture for deployment tests.

One subtle metric is fairness. Track the maximum concurrent transfer slots consumed by one tenant and the queue delay for interactive media uploads while a restore runs. Large-file throughput that starves avatar writes is a regression, even if the restore’s elapsed time improves. Set per-tenant and global limits, and expose queue delay in the same dashboard as bytes per second.

What are the limits of this rule?

Multipart does not repair a corrupt source. Checksums detect a mismatch; they do not tell you which upstream record was wrong. A completed upload can still fail schema validation. A valid object can still violate a deletion request.

There is a real trade-off here: multipart is the wrong choice for tiny avatars when coordination, expiry handling, and cleanup cost more engineering effort than retrying one request. A resumable protocol can also be a better fit for medium files when your client library already supports it. Choose the smallest mechanism that meets the observed recovery target; the larger mechanism is not automatically the safer one.

Erasure workflows must cover receipts, temporary parts, assembled snapshots, indexes, and derived thumbnails. GDPR Article 17 describes the right to erasure; your object lifecycle and restore catalog need an explicit mapping to that obligation. Keep deletion events auditable without retaining the customer’s bytes.

Thresholds also age. Network paths, worker sizes, and tenant distributions move. Version the policy, keep old receipts readable, and review the retry-byte histogram after each material infrastructure change. The right answer for a beginner avatar endpoint is usually one request. The right answer for a large marketplace backup is the path that can resume, prove what it copied, and yield capacity back to smaller tenants.

References

Top comments (0)