webspresso 0.0.105 → 0.0.106

package/plugins/upload/gcs-provider.js

@@ -0,0 +1,148 @@
+/**
+ * Google Cloud Storage (GCS) File Provider for Webspresso
+ * Enables direct file storage, streaming, and signed upload URLs with Google Cloud Storage
+ * Zero-dependency compatible: supports official @google-cloud/storage or standard duck-typed client interfaces
+ * @module plugins/upload/gcs-provider
+ */
+
+'use strict';
+
+const { generateStorageKey } = require('./s3-provider');
+
+/**
+ * Google Cloud Storage Provider
+ * @param {Object} options
+ * @param {Object|string} options.bucket - GCS Bucket name (string) or Bucket instance (e.g. storage.bucket('my-bucket'))
+ * @param {Object} [options.storageClient] - Optional Storage instance from @google-cloud/storage
+ * @param {string} [options.publicBaseUrl] - Custom public domain or CDN URL (e.g. 'https://cdn.example.com')
+ * @param {string} [options.prefix='uploads'] - Subdirectory prefix inside the GCS bucket
+ * @returns {Object} Upload storage provider implementing put, delete, and createSignedUploadUrl
+ */
+function createGcsFileProvider(options = {}) {
+  const { storageClient, publicBaseUrl, prefix = 'uploads' } = options;
+  let bucket = options.bucket;
+
+  if (!bucket) {
+    throw new Error('[createGcsFileProvider] GCS Bucket (name string or Bucket object) is required.');
+  }
+
+  const bucketName = typeof bucket === 'string' ? bucket : (bucket.name || 'bucket');
+  let bucketInstance = typeof bucket === 'object' && bucket !== null ? bucket : null;
+
+  if (typeof bucket === 'string' && storageClient && typeof storageClient.bucket === 'function') {
+    bucketInstance = storageClient.bucket(bucket);
+  }
+
+  const defaultBaseUrl = `https://storage.googleapis.com/${bucketName}`;
+  const normalizedBaseUrl = (publicBaseUrl || defaultBaseUrl).replace(/\/+$/, '');
+
+  return {
+    bucketName,
+    publicBaseUrl: normalizedBaseUrl,
+
+    /**
+     * Store file in Google Cloud Storage
+     * @param {Object} args
+     * @param {Buffer} args.buffer
+     * @param {string} args.originalName
+     * @param {string} args.mimeType
+     * @returns {Promise<{ publicUrl: string, key: string }>}
+     */
+    async put({ buffer, originalName, mimeType }) {
+      const key = generateStorageKey(originalName, mimeType, prefix);
+
+      if (bucketInstance && typeof bucketInstance.file === 'function') {
+        const file = bucketInstance.file(key);
+        await file.save(buffer, {
+          metadata: {
+            contentType: mimeType || 'application/octet-stream',
+            metadata: {
+              originalName: originalName || '',
+              uploadedAt: new Date().toISOString(),
+            },
+          },
+          resumable: false,
+        });
+      } else {
+        throw new Error(
+          '[createGcsFileProvider] A valid GCS bucket instance with .file() is required to perform .put().'
+        );
+      }
+
+      const publicUrl = `${normalizedBaseUrl}/${key}`;
+      return { publicUrl, key };
+    },
+
+    /**
+     * Delete file from Google Cloud Storage
+     * @param {string} key
+     * @returns {Promise<boolean>}
+     */
+    async delete(key) {
+      if (bucketInstance && typeof bucketInstance.file === 'function') {
+        const file = bucketInstance.file(key);
+        try {
+          if (typeof file.delete === 'function') {
+            await file.delete({ ignoreNotFound: true });
+            return true;
+          }
+        } catch (_) {
+          return false;
+        }
+      }
+      return false;
+    },
+
+    /**
+     * Generate a V4 signed URL for direct browser-to-GCS upload
+     * @param {Object} [params]
+     * @param {string} [params.originalName]
+     * @param {string} [params.mimeType]
+     * @param {number} [params.expiresInMs=900000] - 15 minutes default
+     * @param {string} [params.key] - Custom key override
+     * @returns {Promise<{ uploadUrl: string, publicUrl: string, key: string, method: string, headers: Record<string, string> }>}
+     */
+    async createSignedUploadUrl(params = {}) {
+      const {
+        originalName = 'upload',
+        mimeType = 'application/octet-stream',
+        expiresInMs = 15 * 60 * 1000,
+        key: customKey,
+      } = params;
+
+      const key = customKey || generateStorageKey(originalName, mimeType, prefix);
+
+      if (!bucketInstance || typeof bucketInstance.file !== 'function') {
+        throw new Error('[createGcsFileProvider] GCS bucket instance required for generating signed upload URLs.');
+      }
+
+      const file = bucketInstance.file(key);
+      if (typeof file.getSignedUrl !== 'function') {
+        throw new Error('[createGcsFileProvider] file.getSignedUrl() method is not implemented on GCS File instance.');
+      }
+
+      const [signedUrl] = await file.getSignedUrl({
+        version: 'v4',
+        action: 'write',
+        expires: Date.now() + expiresInMs,
+        contentType: mimeType,
+      });
+
+      const publicUrl = `${normalizedBaseUrl}/${key}`;
+
+      return {
+        uploadUrl: signedUrl,
+        publicUrl,
+        key,
+        method: 'PUT',
+        headers: {
+          'Content-Type': mimeType,
+        },
+      };
+    },
+  };
+}
+
+module.exports = {
+  createGcsFileProvider,
+};

package/plugins/upload/index.js

@@ -122,6 +122,122 @@ function uploadPlugin(options = {}) {
   const mw = ensureArray(middleware).filter(Boolean);
   const parseMultipart = createMulterMiddleware(maxBytes, fieldName, multiple, maxFiles);
 
+  function mountRoutes(ctx) {
+    if (!ctx || typeof ctx.addRoute !== 'function') return;
+
+    if (ctx.app && typeof ctx.app.set === 'function') {
+      ctx.app.set('webspresso.uploadPath', normalizedPath);
+    }
+
+    const handler = (req, res) => {
+      parseMultipart(req, res, async (err) => {
+        if (err) {
+          const { status, message } = multerErrorResponse(err);
+          return res.status(status).json({ error: message, message });
+        }
+
+        const files = multiple ? (req.files || []) : (req.file ? [req.file] : []);
+        if (files.length === 0) {
+          return res.status(400).json({ error: 'No file uploaded', message: 'No file uploaded' });
+        }
+
+        // Validate all files first
+        for (const file of files) {
+          if (!file || !file.buffer) {
+            return res.status(400).json({ error: 'No file uploaded', message: 'No file uploaded' });
+          }
+
+          const mime = file.mimetype || 'application/octet-stream';
+          const originalName = file.originalname || 'upload';
+          const ext = extensionFromName(originalName);
+
+          if (mimeAllowlist && mimeAllowlist.length && !mimeAllowlist.includes(mime)) {
+            return res.status(415).json({ error: 'MIME type not allowed', message: 'MIME type not allowed' });
+          }
+          if (
+            extensionAllowlist &&
+            extensionAllowlist.length &&
+            (!ext || !extensionAllowlist.includes(ext))
+          ) {
+            return res.status(400).json({ error: 'File extension not allowed', message: 'File extension not allowed' });
+          }
+        }
+
+        try {
+          const uploadPromises = files.map(async (file) => {
+            const mime = file.mimetype || 'application/octet-stream';
+            const originalName = file.originalname || 'upload';
+            const result = await provider.put({
+              buffer: file.buffer,
+              originalName,
+              mimeType: mime,
+              size: file.size,
+              req,
+            });
+            return {
+              url: result.publicUrl,
+              publicUrl: result.publicUrl,
+              key: result.key,
+            };
+          });
+
+          const results = await Promise.all(uploadPromises);
+
+          if (multiple) {
+            res.json(results);
+          } else {
+            res.json(results[0]);
+          }
+        } catch (e) {
+          const message = e instanceof Error ? e.message : String(e);
+          res.status(500).json({ error: message, message });
+        }
+      });
+    };
+
+    ctx.addRoute('post', normalizedPath, ...mw, handler);
+
+    // Direct presigned upload endpoint for cloud storage (AWS S3, GCS, R2)
+    if (options.presigned) {
+      const presignPath = options.presignedRoute ? ensureLeadingSlash(options.presignedRoute) : `${normalizedPath}/presign`;
+      const presignMw = ensureArray(options.presignedMiddleware || options.middleware || []);
+
+      ctx.addRoute('post', presignPath, ...presignMw, async (req, res) => {
+        if (!provider || typeof provider.createSignedUploadUrl !== 'function') {
+          return res.status(400).json({
+            error: 'Configured upload provider does not support direct presigned uploads',
+          });
+        }
+
+        const { originalName, mimeType, key, expiresInSeconds, expiresInMs } = req.body || {};
+        if (!originalName) {
+          return res.status(400).json({ error: 'originalName is required in request body' });
+        }
+
+        try {
+          const result = await provider.createSignedUploadUrl({
+            originalName,
+            mimeType: mimeType || 'application/octet-stream',
+            key,
+            expiresInSeconds,
+            expiresInMs,
+          });
+          return res.json(result);
+        } catch (err) {
+          return res.status(500).json({ error: err.message || 'Failed to create presigned upload URL' });
+        }
+      });
+
+      if (process.env.NODE_ENV !== 'production') {
+        console.log(`  Upload plugin: POST ${presignPath} (Presigned URL)`);
+      }
+    }
+
+    if (process.env.NODE_ENV !== 'production') {
+      console.log(`  Upload plugin: POST ${normalizedPath}`);
+    }
+  }
+
   return {
     name: 'upload',
     version: '1.0.0',
@@ -160,83 +276,13 @@ function uploadPlugin(options = {}) {
           }
         }
       }
+      if (typeof ctx.addRoute === 'function' && !ctx.core) {
+        mountRoutes(ctx);
+      }
     },
 
     onRoutesReady(ctx) {
-      const { app } = ctx;
-      app.set('webspresso.uploadPath', normalizedPath);
-
-      const handler = (req, res) => {
-        parseMultipart(req, res, async (err) => {
-          if (err) {
-            const { status, message } = multerErrorResponse(err);
-            return res.status(status).json({ error: message, message });
-          }
-
-          const files = multiple ? (req.files || []) : (req.file ? [req.file] : []);
-          if (files.length === 0) {
-            return res.status(400).json({ error: 'No file uploaded', message: 'No file uploaded' });
-          }
-
-          // Validate all files first
-          for (const file of files) {
-            if (!file || !file.buffer) {
-              return res.status(400).json({ error: 'No file uploaded', message: 'No file uploaded' });
-            }
-
-            const mime = file.mimetype || 'application/octet-stream';
-            const originalName = file.originalname || 'upload';
-            const ext = extensionFromName(originalName);
-
-            if (mimeAllowlist && mimeAllowlist.length && !mimeAllowlist.includes(mime)) {
-              return res.status(415).json({ error: 'MIME type not allowed', message: 'MIME type not allowed' });
-            }
-            if (
-              extensionAllowlist &&
-              extensionAllowlist.length &&
-              (!ext || !extensionAllowlist.includes(ext))
-            ) {
-              return res.status(400).json({ error: 'File extension not allowed', message: 'File extension not allowed' });
-            }
-          }
-
-          try {
-            const uploadPromises = files.map(async (file) => {
-              const mime = file.mimetype || 'application/octet-stream';
-              const originalName = file.originalname || 'upload';
-              const result = await provider.put({
-                buffer: file.buffer,
-                originalName,
-                mimeType: mime,
-                size: file.size,
-                req,
-              });
-              return {
-                url: result.publicUrl,
-                publicUrl: result.publicUrl,
-                key: result.key,
-              };
-            });
-
-            const results = await Promise.all(uploadPromises);
-
-            if (multiple) {
-              res.json(results);
-            } else {
-              res.json(results[0]);
-            }
-          } catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            res.status(500).json({ error: message, message });
-          }
-        });
-      };
-
-      ctx.addRoute('post', normalizedPath, ...mw, handler);
-
-      if (process.env.NODE_ENV !== 'production') {
-        console.log(`  Upload plugin: POST ${normalizedPath}`);
-      }
+      mountRoutes(ctx);
     },
   };
 }
@@ -245,10 +291,22 @@ const {
   scanOrphanedUploads,
   pruneOrphanedUploads,
 } = require('./orphan-pruner');
+const {
+  createR2FileProvider,
+  createS3FileProvider,
+  generateStorageKey,
+} = require('./s3-provider');
+const {
+  createGcsFileProvider,
+} = require('./gcs-provider');
 
 module.exports = {
   uploadPlugin,
   createLocalFileProvider,
+  createR2FileProvider,
+  createS3FileProvider,
+  createGcsFileProvider,
+  generateStorageKey,
   scanOrphanedUploads,
   pruneOrphanedUploads,
 };

package/plugins/upload/s3-provider.js

@@ -0,0 +1,257 @@
+/**
+ * S3 & Cloudflare R2 Upload Storage Providers for Webspresso
+ * Enables direct file storage in Cloudflare R2 (Worker bindings or S3 API) and AWS S3/MinIO
+ * @module plugins/upload/s3-provider
+ */
+
+'use strict';
+
+const path = require('path');
+const { randomBytes } = require('crypto');
+const { resolveStoredExtension } = require('./local-file-provider');
+
+/**
+ * Generate a secure, unique object storage key
+ * @param {string} originalName
+ * @param {string} mimeType
+ * @param {string} [prefix='']
+ * @returns {string}
+ */
+function generateStorageKey(originalName, mimeType, prefix = '') {
+  const base = path.basename(originalName || 'upload');
+  let ext = path.extname(base).toLowerCase();
+  if (!/^\.[a-z0-9]{1,12}$/.test(ext)) {
+    ext = '';
+  }
+  ext = resolveStoredExtension(mimeType, ext);
+
+  const cleanPrefix = prefix ? prefix.replace(/^\/+|\/+$/g, '') + '/' : '';
+  const uniqueName = `${Date.now()}-${randomBytes(8).toString('hex')}${ext}`;
+  return `${cleanPrefix}${uniqueName}`;
+}
+
+/**
+ * Cloudflare R2 Native Worker Storage Provider
+ * Zero-dependency: interacts directly with Cloudflare Workers R2Bucket binding (env.BUCKET)
+ * @param {Object} options
+ * @param {Object} options.bucket - Cloudflare R2 Bucket binding (e.g. env.BUCKET)
+ * @param {string} options.publicBaseUrl - Public CDN or R2 custom domain URL (e.g. 'https://cdn.example.com')
+ * @param {string} [options.prefix='uploads'] - Directory prefix inside bucket
+ * @returns {import('./index').UploadStorageProvider}
+ */
+function createR2FileProvider(options = {}) {
+  const { bucket, publicBaseUrl, prefix = 'uploads' } = options;
+
+  if (!bucket) {
+    throw new Error('[createR2FileProvider] R2 Bucket binding (env.BUCKET) is required.');
+  }
+
+  const normalizedBaseUrl = (publicBaseUrl || '').replace(/\/+$/, '');
+
+  return {
+    /**
+     * Store file in Cloudflare R2
+     */
+    async put({ buffer, originalName, mimeType, size, req }) {
+      void size;
+      void req;
+
+      const key = generateStorageKey(originalName, mimeType, prefix);
+
+      if (typeof bucket.put !== 'function') {
+        throw new Error('[createR2FileProvider] Provided bucket binding does not implement .put() method.');
+      }
+
+      await bucket.put(key, buffer, {
+        httpMetadata: {
+          contentType: mimeType || 'application/octet-stream',
+        },
+        customMetadata: {
+          originalName: originalName || '',
+          uploadedAt: new Date().toISOString(),
+        },
+      });
+
+      const publicUrl = normalizedBaseUrl ? `${normalizedBaseUrl}/${key}` : `/${key}`;
+      return { publicUrl, key };
+    },
+
+    /**
+     * Delete file from Cloudflare R2
+     * @param {string} key
+     */
+    async delete(key) {
+      if (typeof bucket.delete === 'function') {
+        await bucket.delete(key);
+        return true;
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * Generic S3 Storage Provider (AWS S3, MinIO, or S3-compatible R2)
+ * @param {Object} options
+ * @param {Object} options.s3Client - S3 Client instance (e.g. @aws-sdk/client-s3 S3Client)
+ * @param {string} options.bucket - Bucket name
+ * @param {string} [options.publicBaseUrl] - Public CDN / bucket base URL
+ * @param {string} [options.prefix='uploads'] - Key prefix
+ * @returns {import('./index').UploadStorageProvider}
+ */
+function createS3FileProvider(options = {}) {
+  const { s3Client, bucket, publicBaseUrl, prefix = 'uploads' } = options;
+
+  if (!s3Client || typeof s3Client.send !== 'function') {
+    throw new Error('[createS3FileProvider] An S3 client instance with a .send() method is required.');
+  }
+  if (!bucket) {
+    throw new Error('[createS3FileProvider] Bucket name is required.');
+  }
+
+  const normalizedBaseUrl = (publicBaseUrl || '').replace(/\/+$/, '');
+
+  return {
+    async put({ buffer, originalName, mimeType, size, req }) {
+      void size;
+      void req;
+
+      const key = generateStorageKey(originalName, mimeType, prefix);
+
+      // Dynamically load PutObjectCommand or construct Command payload
+      let command;
+      try {
+        const { PutObjectCommand } = require('@aws-sdk/client-s3');
+        command = new PutObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          Body: buffer,
+          ContentType: mimeType || 'application/octet-stream',
+        });
+      } catch (_) {
+        // Fallback for custom or duck-typed S3 client wrappers
+        command = {
+          constructor: { name: 'PutObjectCommand' },
+          input: {
+            Bucket: bucket,
+            Key: key,
+            Body: buffer,
+            ContentType: mimeType || 'application/octet-stream',
+          },
+        };
+      }
+
+      await s3Client.send(command);
+
+      const publicUrl = normalizedBaseUrl ? `${normalizedBaseUrl}/${key}` : `/${key}`;
+      return { publicUrl, key };
+    },
+
+    async delete(key) {
+      try {
+        let command;
+        try {
+          const { DeleteObjectCommand } = require('@aws-sdk/client-s3');
+          command = new DeleteObjectCommand({
+            Bucket: bucket,
+            Key: key,
+          });
+        } catch (_) {
+          command = {
+            constructor: { name: 'DeleteObjectCommand' },
+            input: {
+              Bucket: bucket,
+              Key: key,
+            },
+          };
+        }
+        await s3Client.send(command);
+        return true;
+      } catch (_) {
+        return false;
+      }
+    },
+
+    /**
+     * Generate a signed PUT URL for direct browser-to-S3 client upload
+     * @param {Object} [params]
+     * @param {string} [params.originalName]
+     * @param {string} [params.mimeType]
+     * @param {number} [params.expiresInSeconds=900] - 15 minutes default
+     * @param {string} [params.key] - Custom key override
+     * @returns {Promise<{ uploadUrl: string, publicUrl: string, key: string, method: string, headers: Record<string, string> }>}
+     */
+    async createSignedUploadUrl(params = {}) {
+      const {
+        originalName = 'upload',
+        mimeType = 'application/octet-stream',
+        expiresInSeconds = 900,
+        key: customKey,
+      } = params;
+
+      const key = customKey || generateStorageKey(originalName, mimeType, prefix);
+      const publicUrl = normalizedBaseUrl ? `${normalizedBaseUrl}/${key}` : `https://${bucket}.s3.amazonaws.com/${key}`;
+
+      // 1. Duck-typed client with direct getSignedUrl method (e.g. AWS SDK v2, MinIO, or mock)
+      if (typeof s3Client.getSignedUrl === 'function') {
+        const uploadUrl = await s3Client.getSignedUrl('putObject', {
+          Bucket: bucket,
+          Key: key,
+          ContentType: mimeType,
+          Expires: expiresInSeconds,
+        });
+        return {
+          uploadUrl,
+          publicUrl,
+          key,
+          method: 'PUT',
+          headers: { 'Content-Type': mimeType },
+        };
+      }
+
+      // 2. Custom signer function option
+      if (typeof options.createSignedUrl === 'function') {
+        const uploadUrl = await options.createSignedUrl({ bucket, key, mimeType, expiresInSeconds });
+        return {
+          uploadUrl,
+          publicUrl,
+          key,
+          method: 'PUT',
+          headers: { 'Content-Type': mimeType },
+        };
+      }
+
+      // 3. AWS SDK v3 with @aws-sdk/s3-request-presigner
+      try {
+        const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+        const { PutObjectCommand } = require('@aws-sdk/client-s3');
+        const uploadUrl = await getSignedUrl(
+          s3Client,
+          new PutObjectCommand({
+            Bucket: bucket,
+            Key: key,
+            ContentType: mimeType,
+          }),
+          { expiresIn: expiresInSeconds }
+        );
+        return {
+          uploadUrl,
+          publicUrl,
+          key,
+          method: 'PUT',
+          headers: { 'Content-Type': mimeType },
+        };
+      } catch (err) {
+        throw new Error(
+          `[createS3FileProvider] Direct signed upload requires @aws-sdk/s3-request-presigner or a mock client with getSignedUrl: ${err.message}`
+        );
+      }
+    },
+  };
+}
+
+module.exports = {
+  createR2FileProvider,
+  createS3FileProvider,
+  generateStorageKey,
+};