@kido/storage-uploaderCopy Anchor Link

Architecture Paradigm: Pure Web Crypto AWS SigV4 Presigned URL Generation (Zero @aws-sdk Bloat) + Direct Browser-to-R2 Upload (\$0 Egress Bandwidth) + Cloudflare R2 \$0 Free Tier Budget Circuit Breaker + 3-Tier Cold AVIF Storage Lifecycle.

💥 The Real-World BottleneckCopy Anchor Link

Handling file and image uploads through traditional server-side proxy patterns introduces heavy infrastructure costs and memory instability:

1. The Backend Multipart Upload Memory Trap:

   Copy Text

   // The Naive Disaster: Relaying a 20MB multipart file through Node.js
   app.post('/upload', upload.single('file'), async (req, res) => {
     await s3.upload({ Body: req.file.buffer }).promise(); // Double bandwidth and V8 heap bloat!
   });

   Streaming high-resolution photos through the API server buffers binary data in the V8 heap, triggering garbage collection spikes, blocking the Event Loop, and causing HTTP 502 Bad Gateway errors under concurrent traffic.
2. Cloud Bandwidth Egress Bill Shocks: Traditional AWS S3 charges \$0.09 per GB for data egress. A media-heavy or e-commerce platform serving 10TB of images monthly incurs \$900 in unexpected egress bandwidth fees.
3. Heavy @aws-sdk/client-s3 Bundle Bloat: Importing the official AWS SDK adds ~45MB of dependencies to node_modules and slows cold-start initialization on serverless and edge runtimes by hundreds of milliseconds.
4. Surprise Cloud Billing Beyond Free Tiers: Platforms without automated storage budget guards silently cross the Cloudflare R2 10GB free tier or AWS S3 request thresholds, accumulating unmonitored credit card charges.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

@kido/storage-uploader provides lightweight, zero-dependency object storage utilities:

1. Pure Web Crypto AWS SigV4 Presigner (src/adapters/s3-r2.ts)Copy Anchor Link

• generatePresignedPutUrl(options): Generates compliant AWS Signature Version 4 presigned URLs using native globalThis.crypto.subtle.
  • Zero heavy @aws-sdk/client-s3 dependencies (< 5 KB runtime footprint).
  • Compatible with Node.js, Bun, Cloudflare Workers, and Vercel Edge Runtime.
  • Supports custom headers (Content-Type, x-amz-acl, x-amz-meta-*).
• S3R2Adapter: Adapter wrapping Cloudflare R2 and AWS S3 endpoints.

2. Pre-Upload Image & Dimension Validator (src/image-processor.ts)Copy Anchor Link

• validateImage(buffer, options): Inspects magic bytes and image dimensions without external C-bindings or native binary dependencies (sharp / libvips not required).
• Validates MIME types (image/jpeg, image/png, image/webp, image/avif) and enforces standard aspect ratios (1:1 Avatar, 4:3 Product, 16:9 Banner).

3. R2 \$0 Budget Circuit Breaker (src/budget-guard.ts)Copy Anchor Link

• checkCloudflareR2Budget(metrics): Circuit breaker monitoring stored storage gigabytes and Class A/B operation counts. Automatically prevents new uploads when approaching the 10GB / 1,000,000 operation free tier threshold.
• validateGarageS3Credentials(key): Validates GarageHQ self-hosted S3 access keys (GK+24hex).

4. 3-Tier Zero-Cost Storage Lifecycle (src/tiered-lifecycle.ts)Copy Anchor Link

• evaluateStorageLifecycle(item): Moves aged files across the 3-Tier Storage Chain:
  • Hot: Cloudflare R2 (0-30 days, free tier).
  • Warm: Local NVMe SSD.
  • Cold: Local Cold HDD transcoded to AVIF (saving up to 90% disk space).
• buildImgproxyColdTranscodeUrl(key, options): Generates on-demand imgproxy transformation URLs.

💻 Production Implementation & Code SnippetCopy Anchor Link

Hono Direct-to-R2 Presigned Upload EndpointCopy Anchor Link

import { Hono } from 'hono';
import { 
  generatePresignedPutUrl, 
  checkCloudflareR2Budget,
  validateImage 
} from '@kido/storage-uploader';

const app = new Hono();

app.post('/api/uploads/presign', async (c) => {
  const body = await c.req.json();
  const { filename, contentType, fileSize, tenantId } = body;

  // 1. Check R2 $0 Free Tier Budget Circuit Breaker
  const budget = checkCloudflareR2Budget({
    currentStorageBytes: 8.5 * 1024 * 1024 * 1024, // 8.5 GB used
    monthlyClassAOperations: 650000, // 650k / 1M operations
  });

  if (!budget.allowed) {
    return c.json({ error: 'Storage budget threshold reached' }, 403);
  }

  // 2. Generate Object Key
  const sanitized = filename.replace(/[^a-zA-Z0-9.-]/g, '_');
  const objectKey = `tenants/${tenantId}/${Date.now()}-${sanitized}`;

  // 3. Generate Pure Web Crypto SigV4 Presigned PUT URL (< 0.8ms)
  const presigned = await generatePresignedPutUrl({
    bucket: process.env.R2_BUCKET_NAME!,
    key: objectKey,
    endpoint: process.env.R2_ENDPOINT!, // e.g. https://<account_id>.r2.cloudflarestorage.com
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    region: 'auto',
    expiresInSeconds: 900, // 15 minutes
    contentType,
  });

  // Client uploads binary directly to Cloudflare R2 using presigned.url
  return c.json({
    uploadUrl: presigned.url,
    objectKey,
    publicUrl: `https://cdn.kido.vn/${objectKey}`,
  });
});

export default app;

⚡ Benchmark & Verified k6 PerformanceCopy Anchor Link

Benchmarked against traditional server-relay multipart uploads:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

# Install directly via Kido CLI
npx @kido/cli add @kido/storage-uploader