File upload architecture: getting your server out of the path
The simplest form of file upload looks like this: the user submits a form, the file arrives at your server, you move it to storage.
That works, and on small projects it lasts a long time. But there is an architectural problem in it: every byte passes through your server.
If ten users upload a 20 MB video at the same time, your application is busy receiving 200 MB, holding it in memory or on disk, and forwarding it. During all of that it is not answering other requests.
This article is about taking your server out of that path.
Signed URLs: the core idea
The solution is simple: the server does not receive the file, it only grants permission.
The flow has three steps:
- The client asks the server: "I want to upload a file like this".
- The server checks and returns a temporary signed address.
- The client sends the file directly to storage.
On the server side it looks like this:
app.post('/uploads/sign', async (c) => {
const user = await requireUser(c)
const { contentType, size } = await c.req.json()
if (!ALLOWED.has(contentType)) return c.json({ error: 'type' }, 400)
if (size > MAX_SIZE) return c.json({ error: 'size' }, 400)
const key = `uploads/${user.id}/${crypto.randomUUID()}`
const url = await storage.getSignedUploadUrl(key, {
contentType,
expiresIn: 300,
})
return c.json({ url, key })
})The server handles a few kilobytes of JSON, and the file never touches it. However much the load grows, the server's situation does not change.
Two important details
Keep the signature short-lived. Five minutes is plenty. A long-lived signed URL is effectively an open door: whoever gets hold of it can upload.
The server generates the key. Do not use a client-supplied filename as the key. That creates two risks: path games (things like ../) and overwriting somebody else's file. Use a random identifier and store the original name in a separate database field.
Validation: do not trust the client
In the code above I check file type and size. But those are values the client reported.
The real check has to happen after the upload.
For size, you can enforce a limit on the storage side — many services let you bake a maximum size into the signature. That is the most reliable path, because it applies during the upload itself.
For type, trust neither the extension nor what the client said. Both are trivially faked. The correct approach is reading the first few bytes and determining the real format:
const head = await storage.readRange(key, 0, 16)
const realType = detectType(head) // by magic bytes
if (!ALLOWED.has(realType)) {
await storage.delete(key)
throw new Error('file type mismatch')
}This matters especially because a file named .jpg can be something else entirely, and if you later use it — serve it back to users, say — that becomes a security problem.
An extra layer: serve uploaded files from a separate domain. Then even a malicious file does not execute in your main site's context.
The orphaned-file problem
This is the most commonly forgotten consequence of direct uploads.
The client got a signature, uploaded the file — and closed the browser. The file is in storage, but nothing in your database references it. It will never be used and never deleted.
A few months later, storage is full of gigabytes nobody needs.
The fix is a two-stage state:
create table files (
id uuid primary key,
key text not null unique,
owner_id uuid not null,
status text not null default 'pending', -- pending | confirmed
created_at timestamptz not null default now()
);When the signature is issued, a pending row is created. When the client finishes uploading it tells the server, and the row becomes confirmed.
Then a simple cleanup worker:
select key from files
where status = 'pending' and created_at < now() - interval '24 hours';You delete those rows from both storage and the database. Once a day is enough.
Build this stage from the beginning. Adding it later is hard, because you have to walk the entire database to work out which files are needed and which are orphans.
Images: where to resize
Images raise an extra question: when do you produce the different sizes?
There are three options.
Immediately after upload — a background job prepares every size you need. Upside: no waiting later. Downside: you prepare and store sizes that will never be requested.
On first request — the requested size is generated on demand and cached. This is usually the best balance.
On every request — never do this. It burns CPU for nothing.
In practice I take the second option and solve it at the CDN layer: an image service produces the requested size and caches the result. The application then contains no image-processing code at all.
If you must do it yourself, two rules: cap the dimensions (an oversized image will exhaust memory) and strip metadata — photos can carry location coordinates, and you would be publishing them without the user's knowledge.
The download side
Plenty is written about uploads, and downloads get forgotten. But they should not go through your server either.
If the files are public, serve them straight from a CDN.
If they are protected, the same signed-URL pattern works in reverse: the server checks permission and returns a short-lived read address.
app.get('/files/:id', async (c) => {
const file = await getFile(c.req.param('id'))
await requireAccess(c, file)
const url = await storage.getSignedDownloadUrl(file.key, { expiresIn: 60 })
return c.redirect(url)
})The server only checks access; the bytes never pass through it.
Putting it together
A well-built file flow works like this:
- The server issues a signature rather than receiving the file.
- The server generates the key; client-supplied names are not used.
- The signature is short-lived, with the size limit baked in.
- The real file type is verified by its bytes.
- Files are created
pendingand then confirmed. - A cleanup worker removes orphans.
- Downloads also go through a signed address.
Most of that list can be added later, but two items need to be there from the start: server-generated keys and the `pending`/`confirmed` state. The rest can be layered on; those two would require migrating existing data if you add them afterwards.