mbkbucket 3.3.1 → 3.3.2

package/lib/src/utils/errors.js

@@ -1,76 +1,45 @@
 /**
- * Centralized error classification for API routes.
+ * Centralized error classification for API and View routes.
  * Maps error messages to HTTP status codes and machine-readable error codes.
  */
 
-/**
- * Classify an API-level error into { status, code, message }.
- * @param {Error} error
- * @param {string} fallbackMessage
- * @returns {{ status: number, code: string, message: string }}
- */
-export function classifyApiError(error, fallbackMessage = 'Request failed') {
+const API_ERROR_RULES = [
+  { match: 'bucketconnection environment variable is not set', status: 503, code: 'BUCKET_CONFIG_ERROR' },
+  { match: ['no bucket selected', 'not found in bucketconnection'], status: 400, code: 'INVALID_BUCKET' },
+  { match: 'already exists', status: 409, code: 'CONFLICT' },
+  { match: 'not found', status: 404, code: 'NOT_FOUND' },
+  { match: 'access denied', status: 403, code: 'ACCESS_DENIED' },
+  { match: ['required', 'invalid', 'must be'], status: 400, code: 'VALIDATION_ERROR' },
+];
+
+const VIEW_ERROR_RULES = [
+  { match: ['no bucket selected', 'not found in bucketconnection'], status: 400, code: 'INVALID_BUCKET' },
+  { match: 'access denied', status: 403, code: 'ACCESS_DENIED' },
+  { match: 'not found', status: 404, code: 'NOT_FOUND' },
+  { match: ['invalid', 'required'], status: 400, code: 'VALIDATION_ERROR' },
+];
+
+function matchError(rules, error, fallbackMessage) {
   const message = String(error?.message || fallbackMessage);
   const lower = message.toLowerCase();
+  const found = rules.find(r => Array.isArray(r.match) ? r.match.some(m => lower.includes(m)) : lower.includes(r.match));
+  return { status: found?.status ?? 500, code: found?.code ?? 'INTERNAL_ERROR', message };
+}
 
-  if (lower.includes('bucketconnection environment variable is not set')) {
-    return { status: 503, code: 'BUCKET_CONFIG_ERROR', message };
-  }
-  if (lower.includes('no bucket selected') || lower.includes('not found in bucketconnection')) {
-    return { status: 400, code: 'INVALID_BUCKET', message };
-  }
-  if (lower.includes('already exists')) {
-    return { status: 409, code: 'CONFLICT', message };
-  }
-  if (lower.includes('not found')) {
-    return { status: 404, code: 'NOT_FOUND', message };
-  }
-  if (lower.includes('access denied')) {
-    return { status: 403, code: 'ACCESS_DENIED', message };
-  }
-  if (lower.includes('required') || lower.includes('invalid') || lower.includes('must be')) {
-    return { status: 400, code: 'VALIDATION_ERROR', message };
-  }
-  return { status: 500, code: 'INTERNAL_ERROR', message };
+export function classifyApiError(error, fallbackMessage = 'Request failed') {
+  return matchError(API_ERROR_RULES, error, fallbackMessage);
 }
 
-/**
- * Classify a view-level error into { status, code, message }.
- * @param {Error} error
- * @param {string} fallbackMessage
- * @returns {{ status: number, code: string, message: string }}
- */
 export function classifyViewError(error, fallbackMessage = 'Request failed') {
-  const message = String(error?.message || fallbackMessage);
-  const lower = message.toLowerCase();
-
-  if (lower.includes('no bucket selected') || lower.includes('not found in bucketconnection')) {
-    return { status: 400, code: 'INVALID_BUCKET', message };
-  }
-  if (lower.includes('access denied')) {
-    return { status: 403, code: 'ACCESS_DENIED', message };
-  }
-  if (lower.includes('not found')) {
-    return { status: 404, code: 'NOT_FOUND', message };
-  }
-  if (lower.includes('invalid') || lower.includes('required')) {
-    return { status: 400, code: 'VALIDATION_ERROR', message };
-  }
-  return { status: 500, code: 'INTERNAL_ERROR', message };
+  return matchError(VIEW_ERROR_RULES, error, fallbackMessage);
 }
 
-/**
- * Send a classified API error as JSON.
- */
 export function sendApiError(res, error, fallbackMessage = 'Request failed') {
-  const mapped = classifyApiError(error, fallbackMessage);
-  return res.status(mapped.status).json({ success: false, code: mapped.code, error: mapped.message });
+  const { status, code, message } = classifyApiError(error, fallbackMessage);
+  return res.status(status).json({ success: false, code, error: message });
 }
 
-/**
- * Send a classified view error as JSON.
- */
 export function sendViewError(res, error, fallbackMessage = 'Request failed') {
-  const mapped = classifyViewError(error, fallbackMessage);
-  return res.status(mapped.status).json({ code: mapped.code, message: mapped.message });
+  const { status, code, message } = classifyViewError(error, fallbackMessage);
+  return res.status(status).json({ code, message });
 }

package/lib/src/utils/helpers.js

@@ -1,30 +1,98 @@
 /**
- * Shared helper utilities used across controllers and routes.
+ * Shared helper utilities used across controllers, services, and CLI.
  */
 
-/**
- * HTML-escape a string value to prevent XSS.
- */
+const HTML_ESCAPE_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
 export function escapeHtml(value = '') {
-  return String(value)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
+  return String(value ?? '').replace(/[&<>"']/g, c => HTML_ESCAPE_MAP[c]);
 }
 
-/**
- * Extract the base filename from a path (everything after the last '/').
- */
 export function getBaseName(path = '') {
-  const value = String(path || '');
+  const value = String(path ?? '');
   const lastSlashIndex = value.lastIndexOf('/');
-  return lastSlashIndex === -1 ? value : value.substring(lastSlashIndex + 1);
+  return lastSlashIndex === -1 ? value : value.slice(lastSlashIndex + 1);
+}
+
+export function getFileExt(fileName = '') {
+  const name = getBaseName(fileName);
+  const dotIndex = name.lastIndexOf('.');
+  return dotIndex === -1 ? '' : name.slice(dotIndex + 1).toLowerCase();
+}
+
+export function trimSlashes(str = '') {
+  return String(str ?? '').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+export function trimLeadingSlashes(str = '') {
+  return String(str ?? '').replace(/^\/+/, '');
+}
+
+export function getFolderPath(key = '') {
+  const s = String(key ?? '');
+  const lastSlash = s.lastIndexOf('/');
+  return lastSlash === -1 ? '' : s.slice(0, lastSlash + 1);
+}
+
+export function normalizeKeyParam(rawKey) {
+  return Array.isArray(rawKey) ? rawKey.join('/') : String(rawKey || '');
+}
+
+export function buildKey(prefix, fileName) {
+  const cleanPrefix = trimSlashes(prefix);
+  const cleanName = trimLeadingSlashes(fileName);
+  return cleanPrefix ? `${cleanPrefix}/${cleanName}` : cleanName;
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function formatBytes(bytes) {
+  if (!bytes || bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, i)).toFixed(i > 0 ? 1 : 0)} ${units[i]}`;
+}
+
+export function formatDate(iso) {
+  try {
+    return new Date(iso).toLocaleString();
+  } catch {
+    return iso || '—';
+  }
+}
+
+export async function streamToBuffer(stream) {
+  if (Buffer.isBuffer(stream)) return stream;
+  const chunks = [];
+  if (stream?.[Symbol.asyncIterator] || stream?.transformToWeb) {
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  if (stream?.getReader) {
+    const reader = stream.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(Buffer.isBuffer(value) ? value : Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+  }
+  return Buffer.concat(chunks);
+}
+
+export function destroyStream(stream) {
+  if (stream && typeof stream.destroy === 'function') {
+    stream.removeAllListeners?.();
+    stream.destroy();
+  }
 }
 
 // ---------------------------------------------------------------------------
-// MIME type & file extension constants (used by view controller)
+// MIME type & file extension constants
 // ---------------------------------------------------------------------------
 
 export const VIEWABLE_TYPES = new Set([
@@ -37,91 +105,79 @@ export const VIEWABLE_TYPES = new Set([
   'toml', 'ini', 'conf', 'pdf'
 ]);
 
-export const VIEWABLE_TYPES_SORTED = Array.from(VIEWABLE_TYPES).sort();
-
+export const VIEWABLE_TYPES_SORTED = [...VIEWABLE_TYPES].sort();
 export const STATIC_ASSET_TYPES = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'bmp', 'ico', 'css', 'js']);
 export const VIDEO_TYPES = new Set(['mp4', 'webm', 'ogg', 'avi', 'mov']);
 export const AUDIO_TYPES = new Set(['mp3', 'wav', 'flac', 'aac', 'm4a']);
 
 export const MIME_TYPES = {
   // Images
-  'jpg': 'image/jpeg', 'jpeg': 'image/jpeg', 'png': 'image/png',
-  'gif': 'image/gif', 'webp': 'image/webp', 'svg': 'image/svg+xml',
-  'bmp': 'image/bmp', 'ico': 'image/x-icon',
+  jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png',
+  gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml',
+  bmp: 'image/bmp', ico: 'image/x-icon',
   // Videos
-  'mp4': 'video/mp4', 'webm': 'video/webm', 'ogg': 'video/ogg',
-  'avi': 'video/x-msvideo', 'mov': 'video/quicktime',
+  mp4: 'video/mp4', webm: 'video/webm', ogg: 'video/ogg',
+  avi: 'video/x-msvideo', mov: 'video/quicktime',
   // Audio
-  'mp3': 'audio/mpeg', 'wav': 'audio/wav', 'flac': 'audio/flac',
-  'aac': 'audio/aac', 'm4a': 'audio/mp4',
+  mp3: 'audio/mpeg', wav: 'audio/wav', flac: 'audio/flac',
+  aac: 'audio/aac', m4a: 'audio/mp4',
   // Text / Code
-  'txt': 'text/plain; charset=utf-8', 'md': 'text/markdown; charset=utf-8',
-  'json': 'application/json; charset=utf-8', 'xml': 'application/xml; charset=utf-8',
-  'csv': 'text/csv; charset=utf-8', 'log': 'text/plain; charset=utf-8',
-  'js': 'text/javascript; charset=utf-8', 'ts': 'text/typescript; charset=utf-8',
-  'html': 'text/html; charset=utf-8', 'htm': 'text/html; charset=utf-8',
-  'css': 'text/css; charset=utf-8', 'php': 'text/x-php; charset=utf-8',
-  'py': 'text/x-python; charset=utf-8', 'java': 'text/x-java-source; charset=utf-8',
-  'cpp': 'text/x-c++src; charset=utf-8', 'c': 'text/x-csrc; charset=utf-8',
-  'h': 'text/x-chdr; charset=utf-8', 'cs': 'text/x-csharp; charset=utf-8',
-  'rb': 'text/x-ruby; charset=utf-8', 'go': 'text/x-go; charset=utf-8',
-  'rs': 'text/x-rust; charset=utf-8', 'sql': 'text/x-sql; charset=utf-8',
-  'sh': 'text/x-shellscript; charset=utf-8', 'bat': 'text/x-msdos-batch; charset=utf-8',
-  'ps1': 'text/x-powershell; charset=utf-8', 'yaml': 'text/x-yaml; charset=utf-8',
-  'yml': 'text/x-yaml; charset=utf-8', 'toml': 'text/x-toml; charset=utf-8',
-  'ini': 'text/x-ini; charset=utf-8', 'conf': 'text/x-conf; charset=utf-8',
-  // Documents
-  'pdf': 'application/pdf'
+  txt: 'text/plain; charset=utf-8', md: 'text/markdown; charset=utf-8',
+  json: 'application/json; charset=utf-8', xml: 'application/xml; charset=utf-8',
+  csv: 'text/csv; charset=utf-8', log: 'text/plain; charset=utf-8',
+  js: 'text/javascript; charset=utf-8', ts: 'text/typescript; charset=utf-8',
+  html: 'text/html; charset=utf-8', htm: 'text/html; charset=utf-8',
+  css: 'text/css; charset=utf-8', php: 'text/x-php; charset=utf-8',
+  py: 'text/x-python; charset=utf-8', java: 'text/x-java-source; charset=utf-8',
+  cpp: 'text/x-c++src; charset=utf-8', c: 'text/x-csrc; charset=utf-8',
+  h: 'text/x-chdr; charset=utf-8', cs: 'text/x-csharp; charset=utf-8',
+  rb: 'text/x-ruby; charset=utf-8', go: 'text/x-go; charset=utf-8',
+  rs: 'text/x-rust; charset=utf-8', sql: 'text/x-sql; charset=utf-8',
+  sh: 'text/x-shellscript; charset=utf-8', bat: 'text/x-msdos-batch; charset=utf-8',
+  ps1: 'text/x-powershell; charset=utf-8', yaml: 'text/x-yaml; charset=utf-8',
+  yml: 'text/x-yaml; charset=utf-8', toml: 'text/x-toml; charset=utf-8',
+  ini: 'text/x-ini; charset=utf-8', conf: 'text/x-conf; charset=utf-8',
+  // Archives & Documents
+  zip: 'application/zip', gz: 'application/gzip', tar: 'application/x-tar',
+  pdf: 'application/pdf'
 };
 
-/**
- * Check if a content type is sensitive (text-based) and should not be cached.
- */
+export function getMimeType(fileName, fallback = 'application/octet-stream') {
+  return MIME_TYPES[getFileExt(fileName)] || fallback;
+}
+
 export function isSensitiveTextType(contentType = '') {
-  const type = String(contentType || '').toLowerCase();
-  return type.startsWith('text/')
-    || type.includes('json')
-    || type.includes('xml')
-    || type.includes('javascript')
-    || type.includes('typescript');
+  const type = String(contentType ?? '').toLowerCase();
+  return type.startsWith('text/') || /json|xml|javascript|typescript/.test(type);
 }
 
-/**
- * Build a Cache-Control header value based on content type and flags.
- */
 export function buildCacheControl(contentType, { isStaticAsset = false, supportsRanges = false, publicCache = false } = {}) {
   if (publicCache) {
     if (isStaticAsset) return 'public, max-age=3600, immutable';
     if (supportsRanges) return 'public, max-age=86400, must-revalidate';
     return 'public, max-age=300, must-revalidate';
   }
-
   if (isSensitiveTextType(contentType)) return 'private, no-store';
-  if (supportsRanges) return 'private, max-age=1800, must-revalidate';
-  return 'private, max-age=300, must-revalidate';
+  return supportsRanges ? 'private, max-age=1800, must-revalidate' : 'private, max-age=300, must-revalidate';
 }
 
 // ---------------------------------------------------------------------------
-// Range header parsing (used by view controller for media streaming)
+// Range header parsing
 // ---------------------------------------------------------------------------
 
 const DEFAULT_CHUNK_SIZE = 8 * 1024 * 1024; // 8 MB
 
-/**
- * Parse an HTTP Range header (`bytes=start-end`) and compute validated byte offsets.
- * Returns `null` if the range is invalid or unsatisfiable (caller should send 416).
- */
 export function parseRangeHeader(rangeHeader, totalSize) {
   if (!totalSize || totalSize <= 0) return null;
 
-  const match = /^bytes=(\d*)-(\d*)$/.exec(String(rangeHeader || '').trim());
+  const match = /^bytes=(\d*)-(\d*)$/.exec(String(rangeHeader ?? '').trim());
   if (!match) return null;
 
   const [, startStr, endStr] = match;
-  let start, end;
+  let start;
+  let end;
 
   if (startStr === '') {
-    // suffix range: bytes=-N (last N bytes)
     const suffix = parseInt(endStr, 10);
     if (isNaN(suffix) || suffix <= 0) return null;
     start = Math.max(0, totalSize - suffix);
@@ -138,12 +194,11 @@ export function parseRangeHeader(rangeHeader, totalSize) {
   }
 
   if (start >= totalSize || start > end || end >= totalSize) return null;
-
   return { start, end, total: totalSize, size: end - start + 1 };
 }
 
 // ---------------------------------------------------------------------------
-// Player page HTML template (used by view controller)
+// Player page HTML template
 // ---------------------------------------------------------------------------
 
 export function renderPlayerPage(safeFileName, encodedKey, bucketQuery) {
@@ -186,12 +241,11 @@ export const commonHandlebarsHelpers = {
   gte: (a, b) => a >= b,
   lt: (a, b) => a < b,
   lte: (a, b) => a <= b,
-  includes: (arr, val) => (Array.isArray(arr) ? arr.includes(val) : false),
+  includes: (arr, val) => Array.isArray(arr) && arr.includes(val),
   json: (obj) => JSON.stringify(obj, null, 2),
   jsonStringify: (obj) => JSON.stringify(obj),
   getInitials: (username) => {
     if (!username) return '?';
-    const parts = username.split(/[._]/);
-    return parts.map(p => p.charAt(0)).join('').toUpperCase().substring(0, 2);
+    return username.split(/[._]/).map(p => p.charAt(0)).join('').toUpperCase().slice(0, 2);
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkbucket",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Flexible S3/R2 bucket management — library, Express router, and CLI for mbktech.org applications. Provides upload, download, listing, multipart utilities, signed URLs, and a command-line interface with built-in configuration validation and health checks",
   "author": "Muhammad Bin Khalid",
   "homepage": "https://github.com/MIbnEKhalid/mbkbucket#readme",
@@ -15,6 +15,10 @@
     "dev": "cross-env NODE_ENV=dev nodemon index.js",
     "test": "node --test"
   },
+  "imports": {
+    "#helpers": "./lib/src/utils/helpers.js",
+    "#logger": "./lib/src/utils/logger.js"
+  },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.968.0",
     "@aws-sdk/s3-request-presigner": "^3.1000.0",
@@ -46,6 +50,7 @@
   },
   "files": [
     "lib",
+    "views",
     ".env.example",
     ".mbkbucket.config.example.json",
     "cli.js",