APIs with Express · Chapter 16 of 29

File uploads

By the end of this chapter you can accept files safely: size and type limits, names you choose yourself, bytes that prove their type, a form upload parsed by hand, and files served back without leaking others. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The Tapri API
  • 6 tasks
  • Express
  • In the all labs plan

The first 2 chapters of APIs with Express are free. This one comes with the all labs plan.

Why you need this

Anjali has photographed the whole menu, and partner cafés want to upload their own photos too, some from their apps and some from a plain HTML form on their admin page. Every photo has to reach Tapri's disk.

With what you know, req.body is JSON or a form, and an image is neither. And an upload is a stranger writing bytes to your disk: trust its size and one request fills memory, trust its name and it can land outside the folder, trust its type and a script moves in as chai.jpg.

What you build: 6 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    POST /menu/:id/photo: small JPEGs and PNGs only

    In createApp({ uploadDir, maxBytes }), add POST /menu/:id/photo. The body is the image itself, with Content-Type image/jpeg or image/png, read as raw bytes up to maxBytes (the check uses 1024). A good photo answers 201.

    Any other content type (text/plain, image/gif) answers 415 with { error: 'Send a JPEG or PNG image' }. A body over maxBytes answers 413 with { error: 'Photo is too large' }. An empty body answers 400 with { error: 'No photo sent' }. An id that is not in menuIds, such as filter-coffee, answers 404 with { error: 'No such menu item' }.

  2. Task 2

    Save each photo under a name you generate

    Save each accepted photo in uploadDir, creating the folder if it does not exist, under a new name: crypto.randomUUID() plus .jpg for image/jpeg or .png for image/png (imageTypes). The file holds exactly the bytes that were sent, and every photo gets its own name.

    The 201 answers { id, file, size }: the menu item's id, the generated file name and the number of bytes, for example { id: 'cutting-chai', file: '<uuid>.jpg', size: 300 }.

    Nothing is written outside uploadDir, and a refused upload (a 413, say) leaves no file behind.

  3. Task 3

    Check the bytes really are the claimed image

    Before saving, check that the bytes start like the claimed type: every JPEG starts with ff d8 ff, every PNG with 89 50 4e 47 0d 0a 1a 0a (the signatures object in the starter). Otherwise answer 415 with { error: 'That file is not a real image' } and save nothing.

    So a script sent as image/jpeg, a real PNG sent as image/jpeg, and a 2-byte body sent as image/png are all refused, and the upload folder stays empty.

  4. Task 4

    parseMultipart: split a form body by hand

    Export parseMultipart(body, boundary): body is a Buffer of multipart/form-data, and boundary is the boundary from the Content-Type header, without the two leading dashes. Return the parts in order as { name, filename, contentType, data }.

    name and filename come from the part's Content-Disposition header (filename is undefined for a plain field), contentType from its Content-Type header (undefined when there is none), and data is a Buffer with exactly the bytes between the empty line after the headers and the \r\n before the next boundary line. An empty field has data of length 0.

    Binary data must come through byte for byte, even when it holds \r\n, dashes or a line like --tapri. A body without the boundary gives [].

  5. Task 5

    POST /menu/:id/photo-form: photos from an HTML form

    Add POST /menu/:id/photo-form for multipart/form-data, read as raw bytes up to maxBytes. Take the boundary from the Content-Type header (multipart/form-data; boundary=tapriForm), split the body with parseMultipart, and use the part named photo that has a filename.

    Then it behaves like task 1 to 3 with that part's content type and bytes: 201 with { id, file, size } and the bytes saved under a generated name, 415 { error: 'Send a JPEG or PNG image' } for another type (text/html), 415 { error: 'That file is not a real image' } for bytes that lie. No photo part answers 400 with { error: 'No photo sent' }, and an unknown id 404.

    The client's file name, such as ../evil.jpg, is never used: nothing is written outside uploadDir.

  6. Task 6

    GET /photos/:name: no ../ out of the folder

    Add GET /photos/:name. A name you generated that is on disk answers 200 with the file's exact bytes and Content-Type image/jpeg (or image/png).

    Any other name answers 404 with { error: 'No such photo' }: a generated-looking name that is not on disk, plain secret.txt, and tricks like ..%2Fsecret.txt, %2E%2E%2Fsecret.txt or ..%5Csecret.txt, which Express decodes into ../secret.txt. The check puts secret.txt next to the upload folder, and its contents must never be sent (a 400 or 403 is also accepted for the tricks).

What you will learn

  • Raw bodies with limits: express.raw reads only the types you list, up to a size you choose.
  • Names and types are claims: generate the name, and check the first bytes.
  • multipart/form-data: the body an HTML form sends, and how to split it without breaking binary data.
  • Serving files back: why a name from the URL needs a strict check.

More in The Tapri API

Build "File uploads" yourself

Partner cafés want Tapri’s menu online by Friday: you build its API. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of APIs with Express are free. This one comes with the all labs plan.