File Uploads with Limits

A form with a file arrives as multipart/form-data, which multer reads in Express, saving the file under a name the server makes and refusing a file that's too big (413) or of the wrong type (400) before it fills the disk.

Freelancer · Node.js · Web Development · Updated

By

After this lesson you can

  • Accept one file upload in Express with multer's upload.single, reading req.file and the form's text fields in req.body
  • Limit an upload's size and type with multer's limits and fileFilter, answering 413 or 400 with a clear message
  • Save an upload under a name the server makes, never the file name the client sent

Key takeaways

  • A form with a file is sent as multipart/form-data, in parts, so express.json() can't read it. multer can.
  • upload.single("photo") saves one file from the field photo, puts its details in req.file and the form's text fields in req.body.
  • The file name a client sends is never trusted. The server makes the name, such as a randomUUID() and an extension picked from the allowed types.
  • limits.fileSize refuses a file that's too big with 413, read "content too large", and fileFilter refuses a type you don't allow with 400.
  • Online, uploads belong in storage made for files, such as Amazon S3 or Azure Blob Storage, because a host can wipe its own disk at the next deploy.

Profile pictures, receipts, résumés, homework hand-ins: sooner or later an app takes files. Uploads are also one of the easiest ways to fill a server's disk or overwrite its files, so this lesson covers both halves: accepting files, and refusing the wrong ones.

Snapshot Saturday is moving its entries online: each entrant sends a photo with their name and the photo's title. With express.json() in place, the route's req.body comes out undefined. A photo isn't JSON, and it doesn't arrive as JSON.

What a file upload looks like

Think of a parcel with a cover letter: several things in one box, each with its own label. A form with a file travels the same way, as multipart/form-data: the body is split into parts, each with its own headers. Here's the request as a REST Client .http file sends it:

POST http://localhost:3100/entries
Content-Type: multipart/form-data; boundary=SnapshotSaturday

--SnapshotSaturday
Content-Disposition: form-data; name="name"

Grace
--SnapshotSaturday
Content-Disposition: form-data; name="title"

Harbor at dawn
--SnapshotSaturday
Content-Disposition: form-data; name="photo"; filename="sunset.jpg"
Content-Type: image/jpeg

< ./sunset.jpg
--SnapshotSaturday--

The boundary is the line between parts, and the last one ends with two extra dashes. Each part says its field's name; the file's part also says its filename and its type, and < ./sunset.jpg tells REST Client to send that file's bytes. A browser builds the same thing from a <form enctype="multipart/form-data">.

Accepting one photo with multer

multer is the Express middleware that reads these forms. Install it with npm install multer@2.5.0 --save-exact, then:

import express from "express";
import multer from "multer";

const app = express();
const upload = multer({ dest: "uploads/" });

app.post("/entries", upload.single("photo"), (req, res) => {
  console.log(req.body.name, req.body.title);
  console.log(req.file);
  res.status(201).json({ message: "Thanks for your entry!" });
});

app.listen(3100, () => console.log("Listening on http://localhost:3100"));

upload.single("photo") accepts one file from the field named photo and saves it in uploads/. Send the request above, and the terminal shows:

Listening on http://localhost:3100
Grace Harbor at dawn
{
  fieldname: 'photo',
  originalname: 'sunset.jpg',
  encoding: '7bit',
  mimetype: 'image/jpeg',
  path: 'uploads\\1365da442c21b7f521abe70537466907',
  destination: 'uploads/',
  filename: '1365da442c21b7f521abe70537466907',
  size: 929
}

The text fields are in req.body, and the file's details are in req.file: its size in bytes, its type (mimetype), the name it was saved under and the name it had on the entrant's computer. (On macOS, path reads uploads/….)

Never trust the file name

originalname is whatever the client says, so it's tempting to save the file under it, and it's a mistake. When Ava and Omar both send IMG_0001.jpg, the name a phone gives its first photo, the second upload replaces the first: on a test run the folder held one IMG_0001.jpg, Omar's 266 bytes, and Ava's 929-byte photo was gone. A name such as ../../server.js is worse: .. means "the folder above", so the name climbs out of the uploads folder. That's path traversal. multer drops the folders from a name by itself, but other tools, and multer's own preservePath option, don't.

The rule: the server makes the name. randomUUID() from node:crypto gives a new random id every time, and the extension comes from a list of the types you allow, never from the client:

const extensions = { "image/jpeg": ".jpg", "image/png": ".png" };

const storage = multer.diskStorage({
  destination: "uploads/",
  filename: (req, file, cb) => {
    cb(null, randomUUID() + extensions[file.mimetype]);
  },
});

multer's functions answer through a callback, cb: call it with null (no error) and the value. destination can be a function in the same style when the folder depends on the request.

Limits on size and type: 413 and 400

Without limits, one entrant could send a 20 GB file and fill the disk. limits.fileSize stops reading a file past its size, and fileFilter decides about each file before it's saved:

const upload = multer({
  storage,
  limits: { fileSize: 5 * 1024 * 1024 },
  fileFilter: (req, file, cb) => {
    if (extensions[file.mimetype]) {
      cb(null, true);
    } else {
      const err = new Error("Only JPEG and PNG photos can enter.");
      err.status = 400;
      cb(err);
    }
  },
});

Both send their errors to Express, so an error-handling middleware turns them into answers, each in the course's one error shape, sent with sendProblem from Error Handling and Consistent Error Responses:

app.use((err, req, res, next) => {
  if (err.code === "LIMIT_FILE_SIZE") {
    sendProblem(res, 413, "A photo can be at most 5 MB.");
  } else if (err.status === 400) {
    sendProblem(res, 400, err.message);
  } else {
    console.error(err);
    sendProblem(res, 500, "Something went wrong on our side.");
  }
});

The route itself answers 400 when req.file is missing. Sending a text file, then a 6 MB file:

HTTP/1.1 400 Bad Request
{"status":400,"title":"Bad Request","detail":"Only JPEG and PNG photos can enter."}

HTTP/1.1 413 Payload Too Large
{"status":413,"title":"Payload Too Large","detail":"A photo can be at most 5 MB."}

413 reads "content too large: I won't take something this big". The HTTP standard now calls it Content Too Large; Node still uses its older name, in the status line and in STATUS_CODES, so that's the title too. multer removes the half-written file, so a refused upload leaves nothing behind. The mimetype is the client's word too, so a careful server also checks a file's first bytes: every JPEG starts with the bytes FF D8 FF, and every PNG with 89 50 4E 47.

Where uploads go when it's online

A folder on your computer is right for learning. Many hosts, Module 6's included, wipe the server's own disk when it restarts or deploys, and two copies of a server don't share one disk. So real apps send each file to storage made for files, such as Amazon S3, Azure Blob Storage or Cloudflare R2, and keep only its name in the database.

Check yourself

2 questions to try on the lesson page.

So what

Every upload route needs the same three guards: a size limit, a list of allowed types, and a name the server makes. With those, a file from a stranger is a photo in a folder instead of a full disk or an overwritten one.

Key terms

Related