‏Pushduck: آپلود فایل به S3 با چند خط کد

Pushduck یه کتابخونه‌ی open-source برای آپلود فایل به سرویس‌های S3-compatible (مثل AWS S3، Cloudflare R2، DigitalOcean Spaces و MinIO) هست که ادعا می‌کنه با ۳ فایل و حدود ۵۰ خط کد می‌شه آپلود production-ready راه انداخت. نقطه‌ی اصلی تمایزش اینه که به‌جای AWS SDK سنگین (که می‌تونه بیشتر از ۵۰۰KB به باندل اضافه کنه)، از aws4fetch استفاده می‌کنه؛ یه امضاکننده‌ی درخواست AWS که کوچیکه، بدون dependency هست و روی Edge Runtime‌ها هم کار می‌کنه.

معماری Pushduck secure-by-default طراحی شده. جریان کار اینه: کلاینت از سرور یه URL می‌خواد، سرور اون URL رو validate و امضا می‌کنه، بعد فایل مستقیماً از مرورگر کاربر به S3 آپلود می‌شه — بدون اینکه از سرور عبور کنه. این یعنی credentials AWS هیچ‌وقت به کلاینت نمی‌رسه و پهنای باند سرور هم مصرف نمی‌شه.

راه‌اندازی Pushduck در Next.js سه مرحله داره: ساخت API route در سمت سرور، ساخت upload client در سمت کلاینت، و استفاده از hook توی کامپوننت. کد زیر نشون می‌ده چطور توی یه کامپوننت React فایل‌ها رو آپلود کنی و پیشرفت هر فایل رو نشون بدی:

const { uploadFiles, files, isUploading } = upload.imageUpload();

return (
  <input
    type="file"
    multiple
    accept="image/*"
    onChange={(e) => uploadFiles(Array.from(e.target.files || []))}
    disabled={isUploading}
  />
);

علاوه بر آپلود، یه Storage Operations API هم داره که مدیریت کامل فایل‌ها رو ممکن می‌کنه: لیست گرفتن با فیلتر (بر اساس پسوند، حجم، تاریخ)، گرفتن metadata، حذف تکی یا دسته‌ای، تولید لینک دانلود موقت (presigned URL)، و pagination برای dataset‌های بزرگ.

امکانات پیشرفته‌تری مثل rate limiting، تعریف path سفارشی برای فایل‌ها، middleware برای احراز هویت، و hook‌هایی مثل onUploadComplete (برای ذخیره در دیتابیس یا ارسال notification) هم وجود داره. کتابخونه کاملاً TypeScript هست و type inference هوشمندی داره.

نکات کلیدی:

• آپلود مستقیم از مرورگر به S3 — سرور فقط URL امضاشده صادر می‌کنه
• به‌جای AWS SDK حجیم از aws4fetch (~5KB) استفاده می‌کنه
• با Next.js، Express، Fastify و Edge Runtime‌ها سازگاره
• پشتیبانی از AWS S3، Cloudflare R2، DigitalOcean Spaces و MinIO
• Storage API کامل برای لیست، حذف، metadata و لینک دانلود موقت
• TypeScript کامل با type inference هوشمند