Large report files should not make an authenticated marketplace request wait for object storage. The practical trade-off is a little more state in the upload workflow in exchange for bounded request time and a hard tenant boundary. Treat the upload as a resumable job, verify every part, and publish a report only after a complete-object event has passed authorization checks.

How should large generated image uploads avoid timeout failures?

Choice Pick this when Main control Typical failure signal
Single PUT Objects are small and reliably below your request limit Strict size and content checks Client or proxy timeout
Browser direct upload Customers have variable network quality Short-lived, scoped credentials Expired signature
Multipart upload Generated PNG/WebP files can exceed a request budget Part checksums and an expiry policy Missing or mismatched part
Queue-backed ingestion Reports need virus scanning, resizing, or policy review Idempotent job state Stuck processing job

For a marketplace serving generated reports, multipart plus a queue is the usual fit. A direct upload keeps bytes away from the API, while the queue gives operators a place to retry validation. The storage API can be any S3-compatible or HTTP object store; the important contract is the protocol, not the brand.

HTTP 200 from a part request proves only that one part arrived. It does not prove that the final object exists, is owned by the right tenant, or contains an allowed image. I use four signals: an upload session in the database, a checksum for each part, a successful complete call, and a post-completion HEAD or event that records the final size and media type.

Keep the session key tenant-scoped and opaque. Never accept a client-supplied object key as proof of ownership. A report row should move from uploading to ready only in one transaction after the completion verification succeeds.

A complete upload path in TypeScript

HTTP 200 from a part request proves only that one part arrived. It does not prove that the final object exists, is owned by the right tenant, or contains an allowed image. I use four signals: an upload session in the database, a checksum for each part, a successful complete call, and a post-completion HEAD or event that records the final size and media type.

Keep the session key tenant-scoped and opaque. Never accept a client-supplied object key as proof of ownership. A report row should move from uploading to ready only in one transaction after the completion verification succeeds.

The following interface keeps provider details behind three operations. Part numbers are one-based, and the client sends the returned checksums back unchanged.

It failed.

An 8 MiB part is a useful starting point for generated PNG and WebP reports: large enough to avoid thousands of requests, small enough to retry without replaying the whole file. Tune it against your client timeout and memory budget.

type Part = { number: number; etag: string; checksum: string }; interface ObjectStore { createMultipart(key: string, contentType: string): Promise<{ uploadId: string }>; presignPart(key: string, uploadId: string, partNumber: number): Promise<string>; completeMultipart(key: string, uploadId: string, parts: Part[]): Promise<void>; } async function uploadReport( store: ObjectStore, tenantId: string, reportId: string, bytes: Uint8Array, contentType: "image/png" | "image/webp" ) { const key = `tenants/${tenantId}/reports/${reportId}`; const { uploadId } = await store.createMultipart(key, contentType); const chunkSize = 8 * 1024 * 1024; const parts: Part[] = []; for (let offset = 0, number = 1; offset < bytes.length; offset += chunkSize, number++) { const url = await store.presignPart(key, uploadId, number); const chunk = bytes.slice(offset, offset + chunkSize); const response = await fetch(url, { method: "PUT", body: chunk }); if (!response.ok) throw new Error(`part ${number} failed: ${response.status}`); parts.push({ number, etag: response.headers.get("etag") ?? "", checksum: response.headers.get("x-checksum") ?? "" }); } await store.completeMultipart(key, uploadId, parts); return { key, tenantId, reportId }; } 

The production version persists uploadId, the next part number, and an idempotency token before sending bytes. A retry reads that state and uploads only missing parts. On completion, compare the stored tenant ID with the authenticated principal, check the expected byte count, and run image parsing in a worker. Reject files whose detected type disagrees with the declared type; OWASP also recommends allowlists, size limits, randomized names, and malware scanning for uploads.

Troubleshooting and operating the workflow

Start with a timeline keyed by tenantId, reportId, and uploadId. Four counters are enough to make the first diagnosis quick: part_attempts, part_failures, complete_latency_ms, and orphaned_uploads. Add a histogram for part size and a gauge for queued validation jobs. Never log signed URLs or image contents.

When a large PNG times out, inspect the last acknowledged part. A client retry must reuse the same upload ID; creating a new session for every retry leaves abandoned parts behind. If completion returns an ordering error, sort the parts numerically and preserve the exact ETag values. If the object is present but the report is invisible, check the authorization transaction and the worker handoff, not the upload bytes.

Set an explicit abort deadline and a periodic sweeper for sessions that never complete. The deadline is an operational limit, not a user-facing promise. Alert on growth in orphaned uploads and on a rise in completion failures by tenant, since a single noisy customer should not hide a cross-tenant problem.

Multipart does not fix a slow client, a saturated link, or an undersized worker pool. It also adds lifecycle state that must be deleted or retried. Choose single PUT for genuinely small objects, direct upload when API bandwidth is the bottleneck, and queue-backed ingestion when inspection is mandatory. That's the trade-off. In every case, authorization belongs in the report state machine, and observability should make an incomplete upload distinguishable from an unauthorized one.

Sources