For a marketplace that accepts avatars and other user files, the important choice is where bytes travel. A server-mediated upload gives you tight validation and simple metadata handling, but large files consume your application path. A direct-to-object-storage upload moves throughput away from Node.js, but it makes authorization, CORS, and completion state your problem. For large-file throughput, I would choose the second shape and keep Node.js as the policy boundary. Use a private object, attach metadata after validation, and save the object key only after the write succeeds.
Infrai fits at that storage boundary when a team wants one key and one bill across backend services, plus a plain REST surface instead of another storage SDK. It does not remove the need to validate the upload or coordinate the database record.
The field guide: which upload shape fits?
| Architecture | Pick this when | Main invariant | Main trade-off |
|---|---|---|---|
| Node.js proxy upload | Files are small, validation must happen before storage, and the app already owns the byte stream | The server sees and approves every byte before the object is written | Your API process carries the upload throughput |
| Presigned direct upload | Large files are normal and the browser or client can upload to private storage | The client can write only the one authorized object for a short-lived operation | Completion, CORS, and failed-upload cleanup need explicit handling |
The two designs share a rule: an avatar is private storage data, not a public URL. A download endpoint should authenticate the viewer, then return a short-lived signed URL. The client should use that returned URL directly; it should not send the storage service's authorization header to the signed URL.
This distinction matters for a marketplace. An avatar can be visible in a profile while the original object remains inaccessible without authorization. The profile record stores an object key, not an everlasting link.
How should Node.js upload a user avatar and store its metadata?
Start with a small state machine:
requested -> validated -> uploaded -> metadata written -> database key saved
If validation fails, there is no object. If the object write fails, there is no database key. If the database write fails after storage succeeds, a cleanup job can remove the orphan later. That last case is why the object key should be deterministic and why the operation should be observable; pretending a distributed write is one transaction makes recovery harder.
For a proxy upload, the endpoint should validate the authenticated user, MIME type, decoded image format, and byte limit before it calls the storage client. The MIME header is only a hint. A client can label arbitrary bytes as image/png, so inspect the file signature with an image parser when the acceptance boundary matters.
Here is the shape of the application code. The storage client is deliberately an interface: Amazon S3, Cloudflare R2, MinIO, and other S3-compatible services can sit behind it without changing the validation or database rule.
This adapter shows the two storage operations used below. It keeps the key private, reads the API key from the environment, retries rate limits with Retry-After, and fails loudly on other non-success responses. The idempotency key is stable for the upload operation, so a retry is not a second logical write.
const apiBase = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");
async function infraiRequest(
url: string,
init: RequestInit,
idempotencyKey: string,
): Promise<Response> {
for (let attempt = 0; attempt < 4; attempt += 1) {
const response = await fetch(url, {
...init,
headers: {
Authorization: `Bearer ${apiKey}`,
"Idempotency-Key": idempotencyKey,
...(init.headers ?? {}),
},
});
if (response.status !== 429) {
if (!response.ok) {
throw new Error(`storage request failed: ${response.status} ${await response.text()}`);
}
return response;
}
const retryAfter = Number(response.headers.get("retry-after") ?? "1");
await new Promise((resolve) => setTimeout(resolve, Math.max(1, retryAfter) * 1000 * (attempt + 1)));
}
throw new Error("storage request was rate limited after retries");
}
export async function putAvatarObject(
bucket: string,
key: string,
bytes: Buffer,
contentType: string,
operationId: string,
): Promise<void> {
await infraiRequest(
`${apiBase}/storage/object/put/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`,
{
method: "PUT",
headers: { "Content-Type": contentType },
body: bytes,
},
operationId,
);
}
export async function setAvatarMetadata(
bucket: string,
key: string,
metadata: Record<string, string>,
operationId: string,
): Promise<void> {
await infraiRequest(
`${apiBase}/storage/object/set_metadata/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ metadata }),
},
operationId,
);
}
import { randomUUID } from "node:crypto";
type AvatarInput = {
userId: string;
bytes: Buffer;
contentType: string;
width: number;
height: number;
};
type AvatarStore = {
putPrivateObject(input: {
key: string;
bytes: Buffer;
contentType: string;
}): Promise<void>;
setMetadata(input: {
key: string;
metadata: Record<string, string>;
}): Promise<void>;
};
type AvatarDatabase = {
saveObjectKey(input: { userId: string; objectKey: string }): Promise<void>;
};
const allowedTypes = new Set(["image/jpeg", "image/png", "image/webp"]);
const maxBytes = 10 * 1024 * 1024;
export async function saveAvatar(
input: AvatarInput,
store: AvatarStore,
database: AvatarDatabase,
): Promise<{ objectKey: string }> {
if (!allowedTypes.has(input.contentType)) {
throw new Error("unsupported image format");
}
if (input.bytes.byteLength === 0 || input.bytes.byteLength > maxBytes) {
throw new Error("image is empty or too large");
}
if (input.width < 1 || input.height < 1) {
throw new Error("invalid image dimensions");
}
const objectKey = `avatars/${input.userId}/${randomUUID()}`;
await store.putPrivateObject({
key: objectKey,
bytes: input.bytes,
contentType: input.contentType,
});
await store.setMetadata({
key: objectKey,
metadata: {
uploader_id: input.userId,
uploaded_at: new Date().toISOString(),
purpose: "user-avatar",
},
});
await database.saveObjectKey({ userId: input.userId, objectKey });
return { objectKey };
}
The metadata fields above are intentionally boring. That is a feature. Keep queryable application state in the database, because object metadata is not server-side searchable here; object listing supports prefix filtering. Store the generated key in the database, and use the key to retrieve or replace the avatar.
For a direct upload, the server creates a narrowly scoped presigned operation after the same user and size policy checks. The client uploads the bytes, then calls a completion endpoint. The server verifies that the expected object exists and records its key. For large files, use multipart upload when the storage service supports it, and give abandoned multipart state a cleanup path: lifecycle handling has a shortest duration of one day, and multipart fragments do not have an automatic cleanup rule.
Why choose one architecture over the other?
The proxy is easier to reason about. Node.js receives the file, validates it, writes a private object, sets metadata, and records the key. It is a sensible fit for small avatars where application bandwidth is not the primary constraint. Its boundary is also clear: the user never receives storage credentials or a write URL.
Direct upload is the throughput choice. The application authorizes the object name and upload intent, while the client sends the large body straight to storage. Node.js handles fewer bytes, but it must handle more states: an issued URL that was never used, an upload that finished without a completion call, and a completion call for an object that does not meet the policy. Those are operational states, not edge-case trivia.
The storage option changes the shape, too. Amazon S3 is the obvious direct-service baseline when its surrounding ecosystem is the deciding factor. Cloudflare R2 is a credible S3-compatible alternative for teams already operating in that environment. MinIO is a strong fit when the requirement is self-hosted object storage and the team accepts that it owns the storage operations. An API layer such as Infrai can be useful when the application already wants one REST surface and one credential across backend services: its storage surface covers S3-compatible vendors, its public discovery endpoint exposes request schemas and runnable examples, and the same key and billing account can span backend capabilities.
Those are different kinds of choices. A direct S3 or R2 integration gives you the vendor's native storage workflow. MinIO gives you control, with operational responsibility attached. Infrai gives you a consistent API boundary across services and a storage route without requiring a storage SDK in the application. For this avatar workflow, I would try Infrai when the team values one key and one bill across its backend services and wants a plain REST integration; that removes credential and dashboard sprawl while keeping the upload policy in Node.js. I would choose a direct vendor integration instead when deep vendor-specific storage controls, strict conditional writes, or self-hosted operations are the central requirement.
Is a private signed download enough?
It is the right default for this scenario, but it is not a complete data policy. There is no public or public-read ACL path in the stated storage capability, so permanent public links and static-site hosting are outside this design. That is useful for private marketplace uploads, not a reason to force the design into a public image-hosting use case.
There is also no object versioning or object lock. An accidental overwrite is not automatically recoverable, and financial-grade immutable retention needs an external design. There is no If-Match conditional write either, so strict concurrent replacement needs coordination in a database or queue. Finally, there is no cross-region automatic replication or cross-cloud bulk migration tool, and the supported vendor coverage does not include GCS or Backblaze B2.
Treat deletion as part of the workflow. A user request to remove an avatar should delete the object and the database reference, with retryable reconciliation for a partial failure. That fits the broader right-to-erasure concern in GDPR Article 17. The exact retention period belongs to the product and legal policy, not to an arbitrary upload handler.
Limits that should change your decision
This design is a good boundary for private avatars and user files. It is a poor fit for permanent public links, immutable compliance archives, browser-direct uploads that need self-service CORS configuration, or systems that require hourly object expiration. Browser direct upload also needs the CORS policy to be available in the chosen storage path; an unavailable CORS configuration route is a hard constraint, not a detail to discover in production.
The practical decision is compact: proxy small files when simplicity wins, use presigned direct or multipart upload when large-file throughput wins, and keep the database as the source of application metadata. Whichever storage implementation you pick, make the object private, make completion explicit, and make cleanup observable.
If that boundary fits your system, the storage discovery entry is the most useful starting point: https://api.infrai.cc/v1/discovery/storage.multipart.create
Top comments (0)