Implementasi Upload File Multipart di Node.js: Validasi, Streaming, dan Penyimpanan ke Amazon S3

Lhuqita Fazry
Web Development Node.js Express.js Amazon S3 File Upload
Implementasi Upload File Multipart di Node.js: Validasi, Streaming, dan Penyimpanan ke Amazon S3

Menerima file dari client bukan sekadar menambahkan satu route. Format body berubah, ukuran payload tidak bisa diabaikan, dan setiap byte harus dianggap tidak tepercaya. Kita akan mem-parse multipart/form-data, memvalidasi isi file, lalu meneruskan objek ke Amazon S3.

Mengapa Parsing Multipart Menjadi Titik Kritis pada Upload File

Ketika sebuah form berisi file, browser tidak mengirim body sebagai JSON. Browser memakai multipart/form-data, format yang membungkus setiap field dan file sebagai part terpisah. Antar part dipisahkan oleh boundary, string acak pada header Content-Type.

Satu request bisa memuat field teks dan file sekaligus. Setiap browser memakai boundary yang berbeda, jadi nilainya harus dibaca dari header request.

Di titik inilah express.json() dan express.urlencoded() berhenti bekerja. Keduanya membaca body sampai habis lalu mem-parse sesuai format teks, sehingga req.file tetap undefined dan req.body hanya berisi field teks.

Anatomi satu part terdiri dari header dan isi. Header memuat Content-Disposition dengan name serta filename, lalu Content-Type. Setelah satu baris kosong, isi biner mengalir sampai boundary berikutnya, dan parser yang membaca body utuh akan menyertakan CRLF sehingga file tersimpan lebih panjang dari aslinya.

multer tidak mem-parse sendiri. Library ini membungkus busboy, parser streaming yang membaca body per chunk dan memancarkan event field serta file. File besar tidak perlu ditampung utuh sebelum diproses.

Parsing yang salah punya gejala yang mudah dikenali. Field teks hilang karena boundary tidak cocok, file terpotong di tengah, atau proses kehabisan heap karena seluruh body ditampung di memori. Semuanya berakar pada asumsi bahwa body selalu berupa teks.

Menyiapkan Endpoint Express dengan multer dan Memilih Strategi Penyimpanan

multer menyediakan dua strategi penyimpanan. multer.diskStorage menulis stream langsung ke filesystem, sehingga req.file.path tersedia saat handler berjalan. multer.memoryStorage menampung seluruh isi file sebagai Buffer di req.file.buffer tanpa menyentuh disk.

Memory storage masuk akal untuk file kecil, ketika kita perlu memvalidasi seluruh isi, atau ketika file akan diteruskan ke storage eksternal. Disk storage lebih tepat untuk file besar yang hanya perlu disimpan, karena isi file tidak pernah menetap di heap proses.

limits adalah pertahanan pertama sebelum validasi manual. Opsi fileSize, files, dan fields membatasi apa yang boleh masuk. Ketika fileSize terlampaui, multer menghentikan pembacaan dan memanggil error LIMIT_FILE_SIZE, yang kita petakan ke status 413.

Route POST /upload memakai upload.single('file') karena hanya menerima satu file pada field bernama file. Setelah middleware selesai, handler menulis buffer ke folder tmp/ lewat pipeline, lalu mengembalikan metadata. Nama file asli tidak dipakai langsung sebagai path karena nilainya berasal dari client.

javascript
import express from 'express';
import multer from 'multer';
import request from 'supertest';
import fs from 'node:fs';
import path from 'node:path';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

fs.mkdirSync(path.join(process.cwd(), 'tmp'), { recursive: true });

const upload = multer({
  storage: multer.memoryStorage(),
  limits: { fileSize: 2 * 1024 * 1024, files: 1, fields: 4 },
});

const app = express();

app.post('/upload', upload.single('file'), async (req, res) => {
  if (!req.file) {
    return res.status(400).json({ error: 'Field "file" tidak ditemukan' });
  }

  const storedAs = `${Date.now()}-${path.basename(req.file.originalname)}`;
  const target = path.join(process.cwd(), 'tmp', storedAs);

  await pipeline(Readable.from(req.file.buffer), fs.createWriteStream(target));

  return res.status(201).json({
    originalname: req.file.originalname,
    storedAs,
    mimetype: req.file.mimetype,
    size: req.file.size,
  });
});

const png = Buffer.from(
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
  'base64'
);

const response = await request(app)
  .post('/upload')
  .attach('file', png, { filename: 'contoh.png', contentType: 'image/png' });

console.log('status      :', response.status);
console.log('originalname:', response.body.originalname);
console.log('mimetype    :', response.body.mimetype);
console.log('size        :', response.body.size, 'byte');
console.log(
  'file di disk:',
  fs.existsSync(path.join(process.cwd(), 'tmp', response.body.storedAs))
);

Output:

text
status      : 201
originalname: contoh.png
mimetype    : image/png
size        : 70 byte
file di disk: true

Alur di atas berjalan dalam empat tahap. multer mem-parse body dan mengisi req.file, handler menyusun nama simpanan yang unik, pipeline menyalin buffer ke disk, lalu response 201 membawa metadata. Test harness memakai supertest dengan payload multipart di memori, sehingga tidak perlu membuka port. Output yang diharapkan menampilkan status 201, contoh.png, image/png, ukuran byte, dan true untuk konfirmasi file ada di tmp/.

Memvalidasi Tipe MIME, Ekstensi, dan Ukuran File Sebelum Disimpan

Validasi berjalan berlapis, dan setiap lapis menutup celah yang tidak ditangani lapis sebelumnya. Lapis pertama adalah limits.fileSize dari multer, yang menghentikan upload sebelum body selesai dibaca. Lapis kedua adalah whitelist MIME, dan lapis ketiga adalah whitelist ekstensi.

Nilai Content-Type pada sebuah part ditulis oleh client, bukan oleh server. Siapa pun bisa mengirim file executable dengan header Content-Type: image/png. Ekstensi juga hanya bagian dari nama, sehingga foto.png bisa berisi apa saja. Kedua nilai itu adalah klaim, bukan bukti.

Bukti sebenarnya ada pada beberapa byte pertama file, yang disebut magic bytes. Paket file-type membaca byte tersebut dan mengembalikan { ext, mime } bila signature dikenali, atau undefined bila tidak. Pada proyek ESM, fungsinya diimpor sebagai fileTypeFromBuffer. Pada proyek CommonJS, paket ini dimuat lewat import() dinamis.

Hasil deteksi harus cocok dengan MIME yang diklaim dan berada di whitelist. Nama file dinormalisasi dengan path.basename, karakter di luar [a-zA-Z0-9._-] diganti, lalu ditambahi prefiks unik agar tidak menimpa file lain.

MERN Stack Development
Web App • Beginner

MERN Stack Development

Launch your journey into full-stack web development with this comprehensive, pro...

Register
javascript
import path from 'node:path';
import { fileTypeFromBuffer } from 'file-type';

const ALLOWED_MIME = new Set(['image/png', 'image/jpeg', 'application/pdf']);
const ALLOWED_EXT = new Set(['.png', '.jpg', '.jpeg', '.pdf']);
const DANGEROUS_EXT = new Set(['.exe', '.sh', '.bat', '.cmd', '.js']);

export const validateFile = async ({ originalname, mimetype, buffer }) => {
  const ext = path.extname(originalname).toLowerCase();

  if (!ext || DANGEROUS_EXT.has(ext) || !ALLOWED_EXT.has(ext)) {
    return { ok: false, reason: `Ekstensi ${ext || '(kosong)'} tidak diizinkan` };
  }

  if (!ALLOWED_MIME.has(mimetype)) {
    return { ok: false, reason: `MIME ${mimetype} tidak ada di whitelist` };
  }

  const detected = await fileTypeFromBuffer(buffer);

  if (!detected) {
    return { ok: false, reason: 'Signature file tidak dikenali' };
  }

  if (detected.mime !== mimetype) {
    return { ok: false, reason: `Isi file berupa ${detected.mime}, bukan ${mimetype}` };
  }

  return { ok: true, detected };
};

const pngBuffer = Buffer.from(
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
  'base64'
);

const exeBuffer = Buffer.concat([Buffer.from('MZ'), Buffer.alloc(512, 0)]);

const cases = [
  {
    label: 'PNG asli',
    file: { originalname: 'foto.png', mimetype: 'image/png', buffer: pngBuffer },
  },
  {
    label: 'Executable menyamar sebagai PNG',
    file: { originalname: 'foto.png', mimetype: 'image/png', buffer: exeBuffer },
  },
];

for (const { label, file } of cases) {
  const result = await validateFile(file);
  console.log(result.ok ? `LULUS  ${label}` : `TOLAK  ${label} -> ${result.reason}`);
}

Output:

text
LULUS  PNG asli
TOLAK  Executable menyamar sebagai PNG -> Isi file berupa application/x-msdownload, bukan image/png

Fungsi validateFile mengembalikan { ok, reason } sehingga pemanggil tidak perlu melempar exception. Kasus pertama berisi PNG asli dan mencetak LULUS. Kasus kedua memakai buffer berawalan MZ, signature executable Windows, yang dinamai foto.png. Pemeriksaan magic bytes menolaknya karena isi file tidak sesuai klaim.

Respons error sebaiknya konsisten sejak awal. Tipe yang tidak didukung mengembalikan 400 beserta alasan yang bisa dibaca client, sedangkan ukuran berlebih mengembalikan 413. Untuk pengujian cepat, satu perintah curl cukup memakai nama field yang sama dengan route di atas.

bash
curl -F "[email protected];type=image/png" http://localhost:3000/upload

Membandingkan Streaming dan Buffering saat Menangani File Berukuran Besar

Buffering berarti seluruh isi file berada di RAM sebelum diproses. Pola ini sederhana karena data tersedia sebagai satu Buffer utuh, sehingga validasi dan transformasi bisa dilakukan kapan saja. Biayanya muncul saat request berjalan bersamaan. Sepuluh upload berukuran 50 MB berarti 500 MB heap hanya untuk menampung body.

Streaming mengalirkan data per chunk. pipeline() dari node:stream/promises menghubungkan sumber Readable ke fs.createWriteStream, lalu menunggu sampai seluruh chunk selesai ditulis. Ketika buffer tulis penuh, write() mengembalikan false dan pipeline menjeda pembacaan. Mekanisme ini disebut backpressure, dan inilah alasan pemakaian memori tetap datar meski file berukuran besar.

Aliran data per chunk dari disk ke program

Gambar: Aliran chunk dari disk ke program lewat input stream — Sumber: Wikimedia Commons

readable.pipe() biasa tidak meneruskan error ke tujuan dan tidak menutup file handle saat sumber gagal. pipeline() menutup semua stream, membersihkan file sementara, dan mengembalikan promise yang bisa di-await.

Trade-off yang jarang disebut adalah batas validasi. Dengan streaming, kita hanya bisa memeriksa chunk awal tanpa menahan seluruh isi. Pola aman: tulis ke file sementara, validasi setelah selesai, lalu pindahkan atau hapus bila gagal.

javascript
import fs from 'node:fs';
import path from 'node:path';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

const workDir = path.join(process.cwd(), 'tmp');
fs.mkdirSync(workDir, { recursive: true });

const payload = Buffer.alloc(5 * 1024 * 1024, 0x61);
console.log('ukuran payload  :', payload.length, 'byte');

const streamTarget = path.join(workDir, 'stream-copy.bin');
const beforeStream = process.memoryUsage().heapUsed;
const startStream = performance.now();
await pipeline(Readable.from(payload), fs.createWriteStream(streamTarget));
const streamMs = performance.now() - startStream;
const streamHeap = process.memoryUsage().heapUsed - beforeStream;

const writeTarget = path.join(workDir, 'write-copy.bin');
const beforeWrite = process.memoryUsage().heapUsed;
const startWrite = performance.now();
await fs.promises.writeFile(writeTarget, payload);
const writeMs = performance.now() - startWrite;
const writeHeap = process.memoryUsage().heapUsed - beforeWrite;

const toMb = (bytes) => (bytes / 1024 / 1024).toFixed(2);

console.log('pipeline        :', streamMs.toFixed(2), 'ms |', fs.statSync(streamTarget).size, 'byte | heap', toMb(streamHeap), 'MB');
console.log('fs.writeFile    :', writeMs.toFixed(2), 'ms |', fs.statSync(writeTarget).size, 'byte | heap', toMb(writeHeap), 'MB');

Output:

text
ukuran payload  : 5242880 byte
pipeline        : 6.82 ms | 5242880 byte | heap 0.27 MB
fs.writeFile    : 9.49 ms | 5242880 byte | heap 0.04 MB

Kedua pendekatan menulis 5 MB dengan ukuran hasil yang sama. Selisih waktu kecil pada file tunggal karena biaya I/O mendominasi, dan selisih heap juga kecil karena buffer sumber sudah dialokasikan sebelum pengukuran. Perbedaan sebenarnya terlihat pada konkurensi, ketika versi buffering menyimpan satu buffer per request sementara versi streaming hanya menyimpan chunk aktif. Upload besar yang menahan buffer lebih lama juga memperlambat request lain yang berbagi event loop.

Mengunggah File ke Amazon S3 dengan @aws-sdk/client-s3 dan lib-storage

S3Client dibuat sekali dan dipakai ulang di seluruh aplikasi. Region dan kredensial dibaca dari environment variable, bukan ditulis di kode. Pada EC2, ECS, atau Lambda, kredensial sebaiknya tidak diberikan sama sekali karena SDK memakai IAM role lewat default provider chain.

Dua cara mengunggah objek punya karakter berbeda. PutObjectCommand mengirim satu request dan mengharuskan seluruh body tersedia, sehingga ukurannya dibatasi dan tidak ada multipart otomatis. Upload dari @aws-sdk/lib-storage memecah body menjadi part, mengunggahnya secara paralel, dan mengulang part yang gagal.

Dua parameter menentukan perilaku multipart. partSize adalah ukuran tiap part dengan minimum 5 MB, dan queueSize adalah jumlah part yang diunggah bersamaan. partSize terlalu kecil menghasilkan banyak request, sedangkan partSize terlalu besar memperbesar biaya retry.

Body pada Upload menerima Buffer maupun Readable. Buffer dari multer bisa langsung diteruskan tanpa menulis ke disk lokal. Metadata objek diisi eksplisit: ContentType agar browser merender dengan benar, ContentDisposition untuk mengatur perilaku unduh, dan key unik berbasis timestamp untuk mencegah tabrakan nama.

Kegagalan ditangani dengan try/catch di sekitar task.done(). SDK sudah melakukan retry untuk error sementara, tetapi file sementara di disk tetap harus dibersihkan di blok catch. Opsi leavePartsOnError: false memastikan multipart yang gagal dibatalkan agar tidak menyisakan part yatim di bucket.

javascript
import { Readable } from 'node:stream';
import { S3Client } from '@aws-sdk/client-s3';
import { Upload } from '@aws-sdk/lib-storage';

const REGION = process.env.AWS_REGION ?? 'ap-southeast-1';
const BUCKET = process.env.S3_BUCKET ?? 'rumah-coding-uploads';

const s3 = new S3Client({
  region: REGION,
  credentials: process.env.AWS_ACCESS_KEY_ID
    ? {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
      }
    : undefined,
});

export const uploadToS3 = async (buffer, filename, mimetype) => {
  const safeName = filename.replace(/[^a-zA-Z0-9._-]/g, '_');
  const key = `uploads/${Date.now()}-${safeName}`;

  const task = new Upload({
    client: s3,
    params: {
      Bucket: BUCKET,
      Key: key,
      Body: Readable.from(buffer),
      ContentType: mimetype,
      ContentDisposition: `inline; filename="${safeName}"`,
    },
    queueSize: 4,
    partSize: 5 * 1024 * 1024,
    leavePartsOnError: false,
  });

  task.on('httpUploadProgress', (p) => {
    if (p.loaded && p.total) {
      console.log(`progress ${Math.round((p.loaded / p.total) * 100)}%`);
    }
  });

  const result = await task.done();
  return {
    key,
    location: `https://${BUCKET}.s3.${REGION}.amazonaws.com/${key}`,
    etag: result.ETag,
  };
};

// Tanpa kredensial AWS, blok eksekusi ini dilewati (skipped).
if (!process.env.AWS_ACCESS_KEY_ID) {
  console.log('SKIP: AWS_ACCESS_KEY_ID tidak tersedia, upload ke S3 tidak dijalankan.');
} else {
  try {
    const output = await uploadToS3(Buffer.from('contoh isi file'), 'contoh.txt', 'text/plain');
    console.log('Location:', output.location);
    console.log('ETag    :', output.etag);
  } catch (error) {
    console.error('Upload gagal:', error.message);
  }
}

Output:

text
SKIP: AWS_ACCESS_KEY_ID tidak tersedia, upload ke S3 tidak dijalankan.

Blok di atas dijaga oleh pengecekan process.env.AWS_ACCESS_KEY_ID. Tanpa kredensial, skrip hanya mencetak pesan bahwa langkah ini dilewati, sehingga tidak ada request jaringan yang gagal. Ketika kredensial tersedia, output berisi Location dan ETag dari S3.

Menjaga Operasional Upload Tetap Aman dan Terukur di Produksi

presigned URL memindahkan beban upload dari server ke client. Server membuat URL bertanda tangan berdurasi pendek, lalu client mengirim PUT langsung ke S3. Server tidak lagi menyentuh isi file, tetapi batas ukuran dan Content-Type harus dikunci di dalam policy saat URL dibuat.

Pemeriksaan malware tetap diperlukan sebelum file dipublikasikan. Objek yang sudah masuk bucket dipindai oleh fungsi terpisah, dan hasilnya menentukan apakah file dipindahkan ke prefix publik atau dihapus. Kuota total per user mencegah satu akun memenuhi bucket.

File yatim muncul ketika upload berhasil tetapi record database gagal dibuat, atau sebaliknya. Cron job periodik mencocokkan daftar objek dengan tabel upload, sementara lifecycle policy menghapus objek di prefix sementara setelah beberapa hari.

Rate limiting per IP dan per user membatasi laju request sebelum menyentuh storage, sementara logging mencatat metadata saja: key, ukuran, MIME, ID user, dan durasi. Isi file maupun presigned URL tidak pernah masuk log karena keduanya bisa disalahgunakan.

Checklist produksi cukup pendek. Batas ukuran per request dan per user, whitelist tipe sampai magic bytes, nama file unik, enkripsi bucket, dan monitoring error rate. Melewatkan satu poin cukup untuk membuka celah yang tidak terlihat dari UI.

Alur upload yang siap produksi dibangun dari potongan kecil seperti yang kita bahas di atas, bukan dari satu library ajaib. Rumah Coding menyediakan kursus backend web development yang membahas Node.js, Express, dan integrasi cloud storage secara bertahap, mulai dari routing sampai deployment.

Course Terkait

EduStream - Mini Learning Management System (LMS)
Premium Course Web App

MERN Stack Development

Launch your journey into full-stack web development with this comprehensive, project-driven course. Designed for beginners, this course demystifies the MERN stack (MongoDB, Express.js, React.js, Node.js) by guiding you step-by-step in building a real-world application from scratch. By the end of this course, you will have the practical skills and a complete portfolio project to confidently step into the modern web development industry.

Capstone Project

EduStream - Mini Learning Management System (LMS)

  • Secure Authentication & Authorization: Robust user registration and login using JWT, with strict role-based access control (Admin/Instructor vs. Student).
  • Course Management (Admin Dashboard): Full CRUD (Create, Read, Update, Delete) capabilities for administrators to manage course details, including titles, descriptions, pricing, and thumbnail image uploads.
  • Public Course Catalog: An interactive and responsive storefront where users can browse available courses.
7 Weeks Beginner
View Course Details

Related Articles