webspresso 0.0.67 → 0.0.69

package/plugins/upload/index.js

@@ -0,0 +1,188 @@
+/**
+ * File upload plugin — multipart parsing, validation, pluggable storage.
+ * @module plugins/upload
+ */
+
+const multer = require('multer');
+const path = require('path');
+const { createLocalFileProvider } = require('./local-file-provider');
+
+/**
+ * @typedef {import('express').Request} ExpressRequest
+ */
+
+/**
+ * @typedef {Object} UploadPutArgs
+ * @property {Buffer} [buffer]
+ * @property {import('stream').Readable} [stream]
+ * @property {string} originalName
+ * @property {string} mimeType
+ * @property {number} size
+ * @property {ExpressRequest} req
+ */
+
+/**
+ * @typedef {Object} UploadPutResult
+ * @property {string} publicUrl
+ * @property {string} [key]
+ */
+
+/**
+ * @typedef {Object} UploadStorageProvider
+ * @property {(args: UploadPutArgs) => Promise<UploadPutResult>} put
+ */
+
+/**
+ * @param {string} [p]
+ * @returns {string}
+ */
+function normalizeRoutePath(p) {
+  const s = (p || '/api/upload').trim();
+  return s.startsWith('/') ? s : `/${s}`;
+}
+
+/**
+ * @param {string} [name]
+ * @returns {string} lowercase extension without dot
+ */
+function extensionFromName(name) {
+  return path.extname(path.basename(name || '')).replace(/^\./, '').toLowerCase();
+}
+
+/**
+ * @param {number} maxBytes
+ * @param {string} fieldName
+ * @returns {import('express').RequestHandler}
+ */
+function createMulterSingleMiddleware(maxBytes, fieldName) {
+  const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: maxBytes, files: 1 },
+  });
+  return upload.single(fieldName);
+}
+
+/**
+ * @param {unknown} err
+ * @returns {{ status: number, message: string }}
+ */
+function multerErrorResponse(err) {
+  if (err instanceof multer.MulterError) {
+    if (err.code === 'LIMIT_FILE_SIZE') {
+      return { status: 413, message: 'File too large' };
+    }
+    if (err.code === 'LIMIT_FILE_COUNT' || err.code === 'LIMIT_UNEXPECTED_FILE') {
+      return { status: 400, message: 'Invalid upload (too many files or unexpected field)' };
+    }
+    return { status: 400, message: err.message || 'Upload error' };
+  }
+  return { status: 400, message: err instanceof Error ? err.message : String(err) };
+}
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.path='/api/upload'] — POST route
+ * @param {UploadStorageProvider} [options.provider] — Storage backend; default: local disk
+ * @param {Object} [options.local] — Shorthand for createLocalFileProvider when provider omitted
+ * @param {string} [options.local.destDir]
+ * @param {string} [options.local.publicBasePath]
+ * @param {number} [options.maxBytes=10485760] — 10 MiB default
+ * @param {string[]|null} [options.mimeAllowlist] — If set, reject other MIME types (415)
+ * @param {string[]|null} [options.extensionAllowlist] — Optional extra guard on original extension
+ * @param {import('express').RequestHandler|import('express').RequestHandler[]} [options.middleware]
+ * @param {string} [options.fieldName='file'] — Multipart field name
+ * @returns {Object} Webspresso plugin
+ */
+function uploadPlugin(options = {}) {
+  const {
+    path: routePath = '/api/upload',
+    provider: userProvider,
+    local,
+    maxBytes = 10 * 1024 * 1024,
+    mimeAllowlist = null,
+    extensionAllowlist = null,
+    middleware = [],
+    fieldName = 'file',
+  } = options;
+
+  const normalizedPath = normalizeRoutePath(routePath);
+
+  const provider =
+    userProvider ||
+    createLocalFileProvider({
+      destDir: local?.destDir,
+      publicBasePath: local?.publicBasePath,
+    });
+
+  const mw = (Array.isArray(middleware) ? middleware : [middleware]).filter(Boolean);
+  const parseMultipart = createMulterSingleMiddleware(maxBytes, fieldName);
+
+  return {
+    name: 'upload',
+    version: '1.0.0',
+    description: 'Multipart file uploads with pluggable storage',
+
+    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 file = req.file;
+          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 result = await provider.put({
+              buffer: file.buffer,
+              originalName,
+              mimeType: mime,
+              size: file.size,
+              req,
+            });
+            res.json({
+              url: result.publicUrl,
+              publicUrl: result.publicUrl,
+              key: result.key,
+            });
+          } 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}`);
+      }
+    },
+  };
+}
+
+module.exports = {
+  uploadPlugin,
+  createLocalFileProvider,
+};

package/plugins/upload/local-file-provider.js

@@ -0,0 +1,122 @@
+/**
+ * Default upload storage: write files to local disk and expose a public URL path.
+ * @module plugins/upload/local-file-provider
+ */
+
+const fs = require('fs/promises');
+const path = require('path');
+const { randomBytes } = require('crypto');
+
+/**
+ * Common MIME → canonical extension (lowercase, with leading dot).
+ * Used so stored filenames match the MIME the server accepted (see uploadPlugin mimeAllowlist).
+ * Does not verify file content; spoofed MIME is a separate concern (allowlist + optional magic-byte later).
+ */
+const MIME_TO_EXT = {
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/gif': '.gif',
+  'image/webp': '.webp',
+  'image/svg+xml': '.svg',
+  'image/avif': '.avif',
+  'application/pdf': '.pdf',
+  'text/plain': '.txt',
+  'text/csv': '.csv',
+  'text/html': '.html',
+  'application/json': '.json',
+  'application/zip': '.zip',
+  'application/gzip': '.gz',
+  'video/mp4': '.mp4',
+  'video/webm': '.webm',
+  'audio/mpeg': '.mp3',
+  'audio/webm': '.weba',
+};
+
+/**
+ * Normalize public URL prefix (no trailing slash).
+ * @param {string} [publicBasePath]
+ * @returns {string}
+ */
+function normalizePublicBase(publicBasePath) {
+  let p = (publicBasePath == null || publicBasePath === '' ? '/uploads' : String(publicBasePath)).trim();
+  p = p.replace(/\/+$/, '');
+  if (!p.startsWith('/')) {
+    p = `/${p}`;
+  }
+  return p || '/uploads';
+}
+
+/**
+ * @param {string} [mimeType]
+ * @returns {string|null} extension with leading dot, or null if unknown
+ */
+function canonicalExtFromMime(mimeType) {
+  if (!mimeType || typeof mimeType !== 'string') return null;
+  const base = mimeType.split(';')[0].trim().toLowerCase();
+  return MIME_TO_EXT[base] || null;
+}
+
+/**
+ * Prefer a safe extension from the filename; align with MIME when we have a mapping.
+ * @param {string} [mimeType]
+ * @param {string} extFromName - already normalized (lowercase, with dot or '')
+ * @returns {string} extension with leading dot or empty string
+ */
+function resolveStoredExtension(mimeType, extFromName) {
+  const fromMime = canonicalExtFromMime(mimeType);
+  if (fromMime) {
+    if (!extFromName || extFromName !== fromMime) {
+      return fromMime;
+    }
+    return extFromName;
+  }
+  return extFromName || '';
+}
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.destDir] — Absolute or cwd-relative directory for stored files
+ * @param {string} [options.publicBasePath='/uploads'] — URL prefix (first segment of public URL)
+ * @returns {import('./index').UploadStorageProvider}
+ */
+function createLocalFileProvider(options = {}) {
+  const destDir = path.resolve(
+    options.destDir || path.join(process.cwd(), 'public', 'uploads')
+  );
+  const publicBase = normalizePublicBase(options.publicBasePath);
+
+  return {
+    async put({ buffer, originalName, mimeType, size, req }) {
+      void size;
+      void req;
+      await fs.mkdir(destDir, { recursive: true });
+
+      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 storedName = `${Date.now()}-${randomBytes(8).toString('hex')}${ext}`;
+      const target = path.join(destDir, storedName);
+      const resolvedDest = path.resolve(destDir);
+      if (!target.startsWith(resolvedDest + path.sep) && target !== resolvedDest) {
+        throw new Error('Invalid storage path');
+      }
+
+      await fs.writeFile(target, buffer);
+
+      const publicUrl = `${publicBase}/${storedName}`.replace(/\/{2,}/g, '/');
+      return { publicUrl, key: storedName };
+    },
+  };
+}
+
+module.exports = {
+  createLocalFileProvider,
+  normalizePublicBase,
+  canonicalExtFromMime,
+  resolveStoredExtension,
+};

package/src/file-router.js

@@ -16,6 +16,12 @@ const i18nCache = new Map();
 // Cache for route configs in production
 const configCache = new Map();
 
+// Dev-only: avoid require() on every SSR request when the .js file is unchanged (mtime)
+const routeConfigDevCache = new Map();
+
+// Cache for API filename -> { method, baseName } (basename keys; stable per process)
+const methodFromFilenameCache = new Map();
+
 /**
  * Convert a file path to an Express route pattern
  * @param {string} filePath - Relative path from pages/
@@ -51,26 +57,87 @@ function filePathToRoute(filePath, ext) {
   return route;
 }
 
+/**
+ * Metadata for ordering route registration: more specific Express paths must be
+ * registered before less specific ones (static before dynamic; more literal
+ * segments before fewer; deeper paths before shallower among same class).
+ * @param {string} routePath
+ * @returns {{ tier: number, literalSegCount: number, paramSegCount: number, depth: number, routePath: string }}
+ */
+function routeRegistrationMeta(routePath) {
+  const hasCatchAll = routePath.includes('*');
+  const hasDynamic = routePath.includes(':');
+  let tier;
+  if (hasCatchAll) tier = 2;
+  else if (hasDynamic) tier = 1;
+  else tier = 0;
+
+  const segments = routePath.split('/').filter(Boolean);
+  let literalSegCount = 0;
+  let paramSegCount = 0;
+  for (const seg of segments) {
+    if (seg === '*' || (seg.length > 0 && seg.includes('*'))) continue;
+    if (seg.includes(':')) paramSegCount += 1;
+    else literalSegCount += 1;
+  }
+
+  return {
+    tier,
+    literalSegCount,
+    paramSegCount,
+    depth: segments.length,
+    routePath,
+  };
+}
+
+/**
+ * Compare two routes for registration order (negative if a before b).
+ * @param {{ routePath: string }} a
+ * @param {{ routePath: string }} b
+ */
+function compareRouteRegistrationOrder(a, b) {
+  const ma = routeRegistrationMeta(a.routePath);
+  const mb = routeRegistrationMeta(b.routePath);
+  if (ma.tier !== mb.tier) return ma.tier - mb.tier;
+  if (ma.literalSegCount !== mb.literalSegCount) {
+    return mb.literalSegCount - ma.literalSegCount;
+  }
+  if (ma.depth !== mb.depth) return mb.depth - ma.depth;
+  if (ma.paramSegCount !== mb.paramSegCount) return ma.paramSegCount - mb.paramSegCount;
+  return ma.routePath.localeCompare(mb.routePath);
+}
+
 /**
  * Extract HTTP method from API filename
  * @param {string} filename - Filename like health.get.js
  * @returns {{ method: string, baseName: string }}
  */
 function extractMethodFromFilename(filename) {
+  const hit = methodFromFilenameCache.get(filename);
+  if (hit !== undefined) {
+    return hit;
+  }
+
   const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
   const parts = filename.replace('.js', '').split('.');
-  
+  let result;
+
   if (parts.length > 1) {
     const lastPart = parts[parts.length - 1].toLowerCase();
     if (methods.includes(lastPart)) {
-      return {
+      result = {
         method: lastPart,
-        baseName: parts.slice(0, -1).join('.')
+        baseName: parts.slice(0, -1).join('.'),
       };
     }
   }
-  
-  return { method: 'get', baseName: parts.join('.') };
+
+  if (!result) {
+    result = { method: 'get', baseName: parts.join('.') };
+  }
+
+  methodFromFilenameCache.set(filename, result);
+  return result;
 }
 
 /**
@@ -201,25 +268,31 @@ function createTranslator(translations) {
  */
 function loadRouteConfig(configPath, isDev) {
   if (!fs.existsSync(configPath)) {
+    routeConfigDevCache.delete(configPath);
     return null;
   }
-  
+
   try {
-    // Clear cache in development mode
-    if (isDev && require.cache[require.resolve(configPath)]) {
-      delete require.cache[require.resolve(configPath)];
+    if (isDev) {
+      const stats = fs.statSync(configPath);
+      const devCached = routeConfigDevCache.get(configPath);
+      if (devCached && devCached.mtime >= stats.mtimeMs) {
+        return devCached.config;
+      }
+      if (require.cache[require.resolve(configPath)]) {
+        delete require.cache[require.resolve(configPath)];
+      }
+      const config = require(configPath);
+      routeConfigDevCache.set(configPath, { mtime: stats.mtimeMs, config });
+      return config;
     }
-    
-    if (!isDev && configCache.has(configPath)) {
+
+    if (configCache.has(configPath)) {
       return configCache.get(configPath);
     }
-    
+
     const config = require(configPath);
-    
-    if (!isDev) {
-      configCache.set(configPath, config);
-    }
-    
+    configCache.set(configPath, config);
     return config;
   } catch (err) {
     console.error(`Error loading route config ${configPath}:`, err.message);
@@ -431,22 +504,8 @@ function mountPages(app, options) {
     }
   }
   
-  // Sort routes: specific routes first, then dynamic, then catch-all
-  const sortRoutes = (routes) => {
-    return routes.sort((a, b) => {
-      const aHasCatchAll = a.routePath.includes('*');
-      const bHasCatchAll = b.routePath.includes('*');
-      const aHasDynamic = a.routePath.includes(':');
-      const bHasDynamic = b.routePath.includes(':');
-      
-      if (aHasCatchAll && !bHasCatchAll) return 1;
-      if (!aHasCatchAll && bHasCatchAll) return -1;
-      if (aHasDynamic && !bHasDynamic) return 1;
-      if (!aHasDynamic && bHasDynamic) return -1;
-      
-      return a.routePath.localeCompare(b.routePath);
-    });
-  };
+  // Sort routes: static before dynamic before catch-all; then more literal segments, then deeper paths
+  const sortRoutes = (routes) => routes.sort(compareRouteRegistrationOrder);
   
   // Register API routes
   for (const route of sortRoutes(apiRoutes)) {
@@ -686,6 +745,8 @@ module.exports = {
   loadI18n,
   createTranslator,
   detectLocale,
-  resolveMiddlewares
+  resolveMiddlewares,
+  routeRegistrationMeta,
+  compareRouteRegistrationOrder,
 };