📤 File Upload Strategies

Why Uploads Are Hard

Reading a value from a text field is trivial: the browser sends a short string and you trust it as far as your validation allows. A file is different. It's arbitrary, attacker-controlled binary data of arbitrary size, and it arrives with a name and a type that the client made up. Treat any of that as trustworthy and you open the door to disk-filling denial of service, malware storage, and path-traversal writes that overwrite your own server files.

The good news: the whole pipeline is just four honest steps, and each one has a clear defensive job. Picture the flow before we build it.

Notice where the decision happens: validate before you store. Once a hostile file lands on your disk under a name it chose, the damage may already be done. This lesson lives almost entirely inside that diamond in the middle of the diagram.

How a File Reaches the Server

When a form contains a file, the browser can't use the ordinary URL-encoded body format — binary data doesn't survive that encoding. Instead it switches to multipart/form-data, which splits the request body into labelled parts separated by a boundary string. Think of it as a shipping container: each field is its own boxed parcel with a label, and files ride alongside text fields in the same container.

The HTML side

<!-- The two attributes that make uploads work: -->
<form action="/api/upload" method="POST" enctype="multipart/form-data">
  <input type="file" name="avatar" accept="image/png,image/jpeg">
  <button type="submit">Upload</button>
</form>

The enctype="multipart/form-data" is the non-negotiable part — forget it and the file never leaves the browser. The accept attribute is a convenience that filters the file picker; it is not security, because anyone can bypass the picker entirely.

Uploading from JavaScript with progress

Most real apps upload with fetch or XMLHttpRequest so they can show a progress bar. FormData builds the multipart body for you and sets the boundary automatically — never set the Content-Type header yourself here, or you'll clobber that boundary.

// Client-side: upload a single file and report progress.
function uploadFile(file) {
  const formData = new FormData();
  formData.append('avatar', file);              // field name must match the server

  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/api/upload');

  xhr.upload.addEventListener('progress', (e) => {
    if (e.lengthComputable) {
      const percent = Math.round((e.loaded / e.total) * 100);
      console.log(`Uploaded ${percent}%`);       // wire this to a progress bar
    }
  });

  xhr.onload = () => {
    // Do NOT let the server hang the connection open; always respond.
    console.log(xhr.status === 200 ? 'Success' : 'Failed', xhr.responseText);
  };

  xhr.send(formData);                            // FormData sets Content-Type + boundary
}

Multer: Memory vs Disk

Express doesn't parse multipart bodies on its own. Multer is the standard middleware that does: it reads the parts, exposes text fields on req.body, and hands you file objects on req.file or req.files. The single most important decision you make with Multer is where the bytes go.

Memory storage — the buffer lands in RAM

const express = require('express');
const multer = require('multer');

const app = express();

// The whole file is held in memory as a Buffer on req.file.buffer.
const upload = multer({
  storage: multer.memoryStorage(),
  limits: { fileSize: 5 * 1024 * 1024 } // 5 MB — enforced before RAM fills up
});

app.post('/api/upload', upload.single('avatar'), (req, res) => {
  if (!req.file) return res.status(400).json({ error: 'No file uploaded' });

  // req.file.buffer is ready to pipe to cloud storage or an image processor.
  console.log(req.file.originalname, req.file.size, req.file.mimetype);
  res.json({ ok: true, size: req.file.size });
});

Why it matters: memory storage is perfect when the file is a stepping stone — you validate it, transform it, and push it to S3 without ever wanting it on your own disk. The catch is right there in the name: a 4 GB upload becomes 4 GB of RAM. The fileSize limit is what keeps that honest.

Disk storage — bytes stream to a folder

const path = require('path');
const crypto = require('crypto');

const upload = multer({
  storage: multer.diskStorage({
    destination: (req, file, cb) => cb(null, 'uploads/'),
    filename: (req, file, cb) => {
      // Never trust file.originalname for the stored name (see the Filenames section).
      const ext = path.extname(file.originalname).toLowerCase();
      cb(null, `${crypto.randomUUID()}${ext}`);
    }
  }),
  limits: { fileSize: 25 * 1024 * 1024 } // 25 MB
});

Validating Size & Real Type

Two validations separate a toy endpoint from a production one: how big the file is and what it actually is. Both must be enforced on the server. Client-side checks improve the user experience but stop no attacker.

Size: fail fast with a limit

The limits.fileSize option makes Multer abort the moment the stream crosses the threshold — it never buffers the whole oversized file. When it trips, Multer throws a MulterError with code LIMIT_FILE_SIZE, which you translate into a friendly response.

// Centralized Multer error handler — mount it AFTER your upload routes.
app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError) {
    if (err.code === 'LIMIT_FILE_SIZE') {
      return res.status(413).json({ error: 'File too large (max 5 MB)' });
    }
    return res.status(400).json({ error: err.message });
  }
  if (err) return res.status(400).json({ error: err.message });
  next();
});

Type: sniff the magic bytes, don't trust the label

Here is the trap most tutorials fall into. Multer's file.mimetype and the file extension both come from the client. An attacker renames virus.exe to photo.jpg and sets the MIME to image/jpeg — your extension check waves it through. Real file types are identified by magic bytes: a signature in the first few bytes of the file. A JPEG always starts with FF D8 FF; a PNG with 89 50 4E 47.

The file-type package inspects the buffer for you. Pair it with memory storage so the bytes are already in hand.

// npm install file-type
const { fileTypeFromBuffer } = require('file-type');

const ALLOWED = new Set(['image/jpeg', 'image/png', 'image/webp', 'application/pdf']);

app.post('/api/upload', upload.single('doc'), async (req, res) => {
  if (!req.file) return res.status(400).json({ error: 'No file uploaded' });

  // Inspect the actual bytes, not req.file.mimetype (which the client supplied).
  const detected = await fileTypeFromBuffer(req.file.buffer);

  if (!detected || !ALLOWED.has(detected.mime)) {
    return res.status(400).json({
      error: 'Unsupported file type',
      detected: detected ? detected.mime : 'unknown'
    });
  }

  // detected.ext is the trustworthy extension for the stored filename.
  res.json({ ok: true, type: detected.mime, ext: detected.ext });
});

Safe Filenames

The name the browser sends is attacker-controlled text. Two things can go wrong if you reuse it verbatim: collisions (two users upload image.png and one overwrites the other) and path traversal (a crafted name like ../../etc/passwd or ..\\..\\config.js escapes your uploads folder and writes somewhere dangerous).

The fix is to throw the original name away for storage and mint a fresh, random one. crypto.randomUUID() is built into modern Node and gives you a globally-unique, unguessable identifier with no special characters.

const crypto = require('crypto');
const path = require('path');

function safeFileName(detectedExt) {
  // A UUID can never contain "/", "\\", or ".." — traversal is impossible.
  return `${crypto.randomUUID()}.${detectedExt}`;
}

// Keep the human-readable original name ONLY as metadata in your database,
// never as the name on disk:
const record = {
  storedName: safeFileName('jpg'),   // e.g. "6f9619ff-8b86-...-4f8d.jpg"
  originalName: req.file.originalname // display-only, e.g. "My Vacation.jpg"
};

Streaming Large Files

Buffering works beautifully up to a point, and that point is your available memory. A video-upload service that reads each file fully into RAM will fall over under load. The scalable pattern is to stream: process the file in small chunks as they arrive, so memory usage stays flat no matter how large the file is.

With disk storage, Multer has already streamed the file to a path; you then hand that path to a read stream. Think of buffering as filling a bathtub before you can bathe, and streaming as standing under a running shower — you never need to hold all the water at once.

const fs = require('fs');

app.post('/api/upload-large', upload.single('video'), (req, res) => {
  if (!req.file) return res.status(400).json({ error: 'No file uploaded' });

  // req.file.path points at the file Multer streamed to disk.
  const readStream = fs.createReadStream(req.file.path);

  readStream.on('error', (err) => {
    console.error('Stream error:', err);
    res.status(500).json({ error: 'Processing failed' });
  });

  // Pipe to wherever it needs to go — a hash, a transform, or cloud storage.
  const hash = crypto.createHash('sha256');
  readStream.on('data', (chunk) => hash.update(chunk));
  readStream.on('end', () => {
    res.json({ ok: true, checksum: hash.digest('hex') });
  });
});

POST /api/upload-large  →  200 OK
{ "ok": true, "checksum": "e3b0c44298fc1c149afbf4c8996fb924..." }
Peak memory: ~a few MB, regardless of a 2 GB input

Why it matters: streaming is what lets a modest server accept files far larger than its RAM. When you move to cloud storage in the next lesson, you'll see the same principle taken one step further — the browser streams straight to the bucket and your server barely touches the bytes at all.

Practice & Quiz

const express = require('express');
const multer = require('multer');
const crypto = require('crypto');
const fs = require('fs/promises');
// TODO: import fileTypeFromBuffer, set up multer memoryStorage with a 2 MB limit,
//       validate the buffer, and write it under a UUID filename.

const express = require('express');
const multer = require('multer');
const crypto = require('crypto');
const fs = require('fs/promises');
const { fileTypeFromBuffer } = require('file-type');

const app = express();
const ALLOWED = new Set(['image/jpeg', 'image/png']);

const upload = multer({
  storage: multer.memoryStorage(),
  limits: { fileSize: 2 * 1024 * 1024 } // 2 MB
});

app.post('/api/upload', upload.single('image'), async (req, res) => {
  if (!req.file) return res.status(400).json({ error: 'No file uploaded' });

  const detected = await fileTypeFromBuffer(req.file.buffer);
  if (!detected || !ALLOWED.has(detected.mime)) {
    return res.status(400).json({ error: 'Only JPEG or PNG allowed' });
  }

  const storedName = `${crypto.randomUUID()}.${detected.ext}`;
  await fs.writeFile(`uploads/${storedName}`, req.file.buffer);

  res.json({ ok: true, storedName, type: detected.mime });
});

app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError && err.code === 'LIMIT_FILE_SIZE') {
    return res.status(413).json({ error: 'File too large (max 2 MB)' });
  }
  res.status(400).json({ error: err.message });
});

app.listen(3000, () => console.log('Listening on 3000'));

function allowOnly(mimeTypes) {
  const allowed = new Set(mimeTypes);
  return (req, file, cb) => {
    if (allowed.has(file.mimetype)) return cb(null, true);
    // Reject cleanly; the error flows to your Multer error handler.
    cb(new Error(`Type ${file.mimetype} is not allowed`), false);
  };
}

const imageUpload = multer({
  storage: multer.memoryStorage(),
  fileFilter: allowOnly(['image/jpeg', 'image/png', 'image/webp']),
  limits: { fileSize: 5 * 1024 * 1024 }
});
// Remember: this is the cheap first pass. Still verify magic bytes after.

Best Practices & Pitfalls

✅ Do

• Set a limits.fileSize on every Multer instance — no exceptions
• Verify the real content type from magic bytes with file-type
• Store files under a random crypto.randomUUID() name, keeping the original only as metadata
• Keep the uploads folder outside your statically-served web root
• Stream files that could be large instead of buffering them whole

❌ Don't

• Trust file.originalname, file.mimetype, or the extension for security decisions
• Concatenate user-supplied names into a filesystem path
• Set the Content-Type header yourself when sending FormData from the browser
• Serve uploaded HTML or SVG from the same origin as your app without sanitizing (stored XSS)
• Forget to send a response on every branch — a hung request ties up a connection

app.post('/api/upload', upload.single('f'), (req, res) => {
  if (!req.file) return; // ❌ no response — the browser hangs until timeout
  res.json({ ok: true });
});

Summary

📚 Additional Resources

• Multer — official documentation
• MDN — FormData
• MDN — MIME types
• file-type — magic-byte detection on npm

🚀 What's Next?

You can now accept a file safely and store it on your own server — but that server has finite disk and doesn't scale. Next we hand storage off to a dedicated service: Cloud Storage Integration, where you'll upload to Amazon S3 with the AWS SDK v3 and let the browser send files straight to the bucket with presigned URLs.