webspresso 0.0.90 → 0.0.93

package/src/services/builtins/media.js

@@ -0,0 +1,196 @@
+/**
+ * Built-in Media & File Upload Services
+ * @module src/services/builtins/media
+ */
+
+const fs = require('fs/promises');
+const path = require('path');
+const { z } = require('zod');
+const { ValidationError, NotFoundError } = require('../../../core/errors');
+const { createLocalFileProvider, canonicalExtFromMime } = require('../../../plugins/upload/local-file-provider');
+
+/**
+ * Convert base64 data (including data URLs) to Buffer
+ * @param {string} base64Str
+ * @returns {{ buffer: Buffer, mimeType?: string }}
+ */
+function parseBase64(base64Str) {
+  const match = base64Str.match(/^data:([^;]+);base64,(.+)$/);
+  if (match) {
+    const mimeType = match[1];
+    const buffer = Buffer.from(match[2], 'base64');
+    return { buffer, mimeType };
+  }
+  return { buffer: Buffer.from(base64Str, 'base64') };
+}
+
+/**
+ * Validate storage key to prevent directory traversal
+ * @param {string} key
+ * @param {string} baseDir
+ * @returns {string} Absolute resolved file path
+ */
+function resolveSafeKeyPath(key, baseDir) {
+  if (!key || typeof key !== 'string' || key.includes('..') || path.isAbsolute(key)) {
+    throw new ValidationError('Invalid file key or path traversal attempt', [
+      { field: 'key', message: 'Path traversal attempt detected' },
+    ]);
+  }
+
+  const resolvedBase = path.resolve(baseDir);
+  const targetPath = path.resolve(resolvedBase, key);
+
+  if (!targetPath.startsWith(resolvedBase + path.sep) && targetPath !== resolvedBase) {
+    throw new ValidationError('Invalid file key or path traversal attempt', [
+      { field: 'key', message: 'Path traversal attempt detected' },
+    ]);
+  }
+
+  return targetPath;
+}
+
+/**
+ * Create built-in media services map
+ * @param {Object} [options]
+ * @param {import('../../../plugins/upload').UploadStorageProvider} [options.provider]
+ * @param {string} [options.destDir]
+ * @param {string} [options.publicBasePath]
+ * @returns {Record<string, Object>}
+ */
+function createMediaServices(options = {}) {
+  const destDir = path.resolve(
+    options.destDir || path.join(process.cwd(), 'public', 'uploads')
+  );
+  const provider = options.provider || createLocalFileProvider({
+    destDir,
+    publicBasePath: options.publicBasePath,
+  });
+
+  return {
+    'media.upload': {
+      schema: z.object({
+        buffer: z.any().optional(),
+        base64: z.string().optional(),
+        filePath: z.string().optional(),
+        originalName: z.string().min(1).default('upload.bin'),
+        mimeType: z.string().optional(),
+        destDir: z.string().optional(),
+        publicBasePath: z.string().optional(),
+      }),
+      async handler(input, ctx) {
+        let { buffer, base64, filePath, originalName, mimeType, destDir: customDest, publicBasePath: customBase } = input;
+        let finalMime = mimeType || 'application/octet-stream';
+
+        if (buffer && !(buffer instanceof Buffer) && !(buffer instanceof Uint8Array)) {
+          if (typeof buffer === 'string') {
+            buffer = Buffer.from(buffer);
+          } else {
+            throw new ValidationError('Invalid buffer provided', [
+              { field: 'buffer', message: 'Expected Buffer or Uint8Array' },
+            ]);
+          }
+        }
+
+        if (!buffer && base64) {
+          const parsed = parseBase64(base64);
+          buffer = parsed.buffer;
+          if (parsed.mimeType && (!mimeType || mimeType === 'application/octet-stream')) {
+            finalMime = parsed.mimeType;
+          }
+        } else if (!buffer && filePath) {
+          try {
+            buffer = await fs.readFile(path.resolve(filePath));
+            if (!originalName || originalName === 'upload.bin') {
+              originalName = path.basename(filePath);
+            }
+          } catch (err) {
+            throw new NotFoundError(`Source file not found: ${filePath}`, { cause: err });
+          }
+        }
+
+        if (!buffer || buffer.length === 0) {
+          throw new ValidationError('No file content provided (buffer, base64, or filePath is required)', [
+            { field: 'buffer', message: 'No file content provided' },
+          ]);
+        }
+
+        const activeProvider = (customDest || customBase)
+          ? createLocalFileProvider({ destDir: customDest || destDir, publicBasePath: customBase })
+          : provider;
+
+        const uploadResult = await activeProvider.put({
+          buffer,
+          originalName,
+          mimeType: finalMime,
+          size: buffer.length,
+          req: ctx.req || null,
+        });
+
+        return {
+          publicUrl: uploadResult.publicUrl,
+          key: uploadResult.key || path.basename(uploadResult.publicUrl),
+          size: buffer.length,
+          mimeType: finalMime,
+          originalName,
+        };
+      },
+    },
+
+    'media.delete': {
+      schema: z.object({
+        key: z.string().min(1, 'Key is required'),
+        destDir: z.string().optional(),
+      }),
+      async handler(input, ctx) {
+        const { key, destDir: customDest } = input;
+        const targetDir = customDest ? path.resolve(customDest) : destDir;
+        const targetPath = resolveSafeKeyPath(key, targetDir);
+
+        try {
+          await fs.unlink(targetPath);
+          return { success: true, key };
+        } catch (err) {
+          if (err.code === 'ENOENT') {
+            return { success: false, key, message: 'File not found' };
+          }
+          throw err;
+        }
+      },
+    },
+
+    'media.info': {
+      schema: z.object({
+        key: z.string().min(1, 'Key is required'),
+        destDir: z.string().optional(),
+      }),
+      async handler(input, ctx) {
+        const { key, destDir: customDest } = input;
+        const targetDir = customDest ? path.resolve(customDest) : destDir;
+        const targetPath = resolveSafeKeyPath(key, targetDir);
+
+        try {
+          const stats = await fs.stat(targetPath);
+          const ext = path.extname(targetPath).toLowerCase();
+          return {
+            exists: true,
+            key,
+            size: stats.size,
+            mtime: stats.mtime,
+            ext,
+          };
+        } catch (err) {
+          if (err.code === 'ENOENT') {
+            return { exists: false, key };
+          }
+          throw err;
+        }
+      },
+    },
+  };
+}
+
+module.exports = {
+  createMediaServices,
+  resolveSafeKeyPath,
+  parseBase64,
+};

package/src/services/builtins/system.js

@@ -0,0 +1,221 @@
+/**
+ * Built-in System, Maintenance & Health Check Services
+ * @module src/services/builtins/system
+ */
+
+const os = require('os');
+const { z } = require('zod');
+const { cleanExpiredTokens, createKnexAuthTokensAdapter } = require('../../../core/auth/tokens');
+
+/**
+ * Format memory usage bytes into human-readable MB
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatMb(bytes) {
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+/**
+ * Create built-in system services map
+ * @param {Object} [options]
+ * @param {Object} [options.db] - Database or knex instance
+ * @param {import('../registry').ServiceRegistry} [options.serviceRegistry] - ServiceRegistry instance
+ * @param {Object} [options.pluginManager] - PluginManager instance
+ * @returns {Record<string, Object>}
+ */
+function createSystemServices(options = {}) {
+  const { db, serviceRegistry, pluginManager } = options;
+
+  return {
+    'system.health': {
+      schema: z.object({
+        detailed: z.boolean().default(false),
+      }),
+      async handler(input, ctx) {
+        const activeDb = ctx.db || db;
+        const memory = process.memoryUsage();
+        const uptime = process.uptime();
+        const timestamp = new Date();
+
+        let dbStatus = 'disconnected';
+        let dbLatencyMs = null;
+
+        if (activeDb) {
+          const knex = activeDb.knex || activeDb;
+          const startPing = Date.now();
+          try {
+            await knex.raw('SELECT 1');
+            dbStatus = 'connected';
+            dbLatencyMs = Date.now() - startPing;
+          } catch (err) {
+            dbStatus = 'error';
+          }
+        }
+
+        const isHealthy = dbStatus !== 'error';
+
+        const result = {
+          status: isHealthy ? 'ok' : 'degraded',
+          uptime,
+          uptimeHuman: `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m ${Math.floor(uptime % 60)}s`,
+          timestamp,
+          database: {
+            status: dbStatus,
+            latencyMs: dbLatencyMs,
+          },
+          memory: {
+            rss: formatMb(memory.rss),
+            heapUsed: formatMb(memory.heapUsed),
+            heapTotal: formatMb(memory.heapTotal),
+            external: formatMb(memory.external),
+          },
+        };
+
+        if (activeDb?.cache && typeof activeDb.cache.stats === 'function') {
+          result.cache = activeDb.cache.stats();
+        }
+
+        return result;
+      },
+    },
+
+    'system.cleanup': {
+      schema: z.object({
+        olderThanDays: z.number().int().positive().default(90),
+        purgeAuthTokens: z.boolean().default(true),
+        purgeAuditLogs: z.boolean().default(true),
+      }),
+      auth: 'admin',
+      async handler(input, ctx) {
+        const { olderThanDays, purgeAuthTokens, purgeAuditLogs } = input;
+        const activeDb = ctx.db || db;
+        if (!activeDb) {
+          throw new Error('Database instance is required for system.cleanup');
+        }
+
+        const knex = activeDb.knex || activeDb;
+        const purged = {};
+
+        // 1. Purge expired auth tokens
+        if (purgeAuthTokens) {
+          try {
+            const hasAuthTokensTable = await knex.schema.hasTable('auth_tokens');
+            if (hasAuthTokensTable) {
+              const now = new Date();
+              const count = await knex('auth_tokens').where('expires_at', '<', now).delete();
+              purged.authTokens = count;
+            } else {
+              purged.authTokens = 0;
+            }
+          } catch (err) {
+            purged.authTokens = 0;
+          }
+        }
+
+        // 2. Purge old audit logs if table exists
+        if (purgeAuditLogs) {
+          try {
+            const hasAuditTable = await knex.schema.hasTable('audit_logs');
+            if (hasAuditTable) {
+              const cutoff = new Date(Date.now() - olderThanDays * 24 * 60 * 60 * 1000);
+              const deleted = await knex('audit_logs').where('created_at', '<', cutoff).delete();
+              purged.auditLogs = deleted;
+            } else {
+              purged.auditLogs = 0;
+            }
+          } catch (err) {
+            purged.auditLogs = 0;
+          }
+        }
+
+        return {
+          success: true,
+          purged,
+          timestamp: new Date(),
+        };
+      },
+    },
+
+    'system.cache-flush': {
+      schema: z.object({
+        scope: z.enum(['all', 'orm', 'services']).default('all'),
+        model: z.string().optional(),
+      }),
+      auth: 'admin',
+      async handler(input, ctx) {
+        const { scope, model } = input;
+        const activeDb = ctx.db || db;
+        const registry = ctx.serviceRegistry || serviceRegistry;
+
+        let ormCachePurged = false;
+        let serviceCacheCleared = false;
+
+        // 1. Flush ORM Cache
+        if (scope === 'all' || scope === 'orm') {
+          if (activeDb?.cache && typeof activeDb.cache.purge === 'function') {
+            activeDb.cache.purge(model);
+            ormCachePurged = true;
+          } else if (activeDb?.cache && typeof activeDb.cache.clear === 'function') {
+            activeDb.cache.clear();
+            ormCachePurged = true;
+          }
+        }
+
+        // 2. Clear Service Memoization Caches
+        if (scope === 'all' || scope === 'services') {
+          if (registry && typeof registry.clearCache === 'function') {
+            registry.clearCache();
+            serviceCacheCleared = true;
+          }
+        }
+
+        return {
+          success: true,
+          scope,
+          model: model || null,
+          ormCachePurged,
+          serviceCacheCleared,
+          timestamp: new Date(),
+        };
+      },
+    },
+
+    'system.info': {
+      schema: z.object({}),
+      auth: 'admin',
+      async handler(input, ctx) {
+        const activeDb = ctx.db || db;
+        const registry = ctx.serviceRegistry || serviceRegistry;
+        const pm = ctx.pluginManager || pluginManager;
+
+        const models = activeDb && typeof activeDb.getAllModelInstances === 'function'
+          ? activeDb.getAllModelInstances().map(m => m.name)
+          : [];
+
+        const services = registry && typeof registry.list === 'function'
+          ? registry.list()
+          : [];
+
+        const plugins = pm && pm.plugins
+          ? Array.from(pm.plugins.keys())
+          : [];
+
+        return {
+          nodeVersion: process.version,
+          platform: os.platform(),
+          arch: os.arch(),
+          pid: process.pid,
+          uptime: process.uptime(),
+          models,
+          services,
+          plugins,
+        };
+      },
+    },
+  };
+}
+
+module.exports = {
+  createSystemServices,
+};

package/src/services/discovery.js

@@ -0,0 +1,141 @@
+/**
+ * Webspresso Services Discovery
+ * Recursively scans directory and maps file paths to service names with cross-platform normalization & camelCase aliases
+ * @module src/services/discovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { trimUrlPathSlashes } = require('../../core/url-path-normalize');
+
+const VALID_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
+
+/**
+ * Convert kebab-case or snake_case segment to camelCase
+ * @param {string} str
+ * @returns {string}
+ */
+function toCamelCase(str) {
+  return str.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+}
+
+/**
+ * Check if a file should be included as a service
+ * @param {string} filename - Base name of the file
+ * @returns {boolean}
+ */
+function isValidServiceFile(filename) {
+  if (filename.startsWith('.') || filename.startsWith('_')) {
+    return false;
+  }
+  if (filename.endsWith('.test.js') || filename.endsWith('.spec.js') || filename.endsWith('.d.ts')) {
+    return false;
+  }
+  const ext = path.extname(filename);
+  return VALID_EXTENSIONS.has(ext);
+}
+
+/**
+ * Convert relative file path to dot-separated service name with cross-platform normalization & aliases
+ * @example
+ * filePathToServiceName('user/get.js') -> { name: 'user.get', aliases: [] }
+ * filePathToServiceName('order-items/get-by-id.js') -> { name: 'order-items.get-by-id', aliases: ['orderItems.getById'] }
+ * filePathToServiceName('user/index.js') -> { name: 'user', aliases: ['user.index'] }
+ *
+ * @param {string} relativePath - Path relative to services root
+ * @returns {{ name: string, aliases: string[] }}
+ */
+function filePathToServiceName(relativePath) {
+  if (!relativePath || typeof relativePath !== 'string') {
+    return { name: '', aliases: [] };
+  }
+
+  // Cross-platform slash normalization (Windows \ to Unix /)
+  const normalized = trimUrlPathSlashes(relativePath.replace(/\\/g, '/'));
+  const ext = path.extname(normalized);
+  const withoutExt = ext ? normalized.slice(0, -ext.length) : normalized;
+  const segments = withoutExt.split('/').filter(Boolean);
+
+  if (segments.length === 0) {
+    return { name: '', aliases: [] };
+  }
+
+  const aliases = new Set();
+  const isIndex = segments[segments.length - 1] === 'index';
+
+  let primarySegments;
+  if (isIndex) {
+    primarySegments = segments.slice(0, -1);
+    if (primarySegments.length === 0) {
+      primarySegments = ['index'];
+    } else {
+      aliases.add(segments.join('.')); // e.g. user.index alias
+    }
+  } else {
+    primarySegments = segments;
+  }
+
+  const primaryName = primarySegments.join('.');
+
+  // Generate camelCase alias if segments contain kebab-case or snake_case
+  const camelSegments = primarySegments.map(toCamelCase);
+  const camelName = camelSegments.join('.');
+  if (camelName !== primaryName) {
+    aliases.add(camelName);
+  }
+
+  return {
+    name: primaryName,
+    aliases: Array.from(aliases),
+  };
+}
+
+/**
+ * Recursively discover all service files in a directory
+ * @param {string} servicesDir - Absolute or relative path to services directory
+ * @returns {Array<{ name: string, aliases: string[], filePath: string, relativePath: string }>}
+ */
+function discoverServices(servicesDir) {
+  if (!servicesDir || !fs.existsSync(servicesDir)) {
+    return [];
+  }
+
+  const results = [];
+
+  function scan(currentDir, relativePrefix = '') {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name.startsWith('_') || entry.name === 'node_modules') {
+        continue;
+      }
+
+      const fullPath = path.join(currentDir, entry.name);
+      const relPath = relativePrefix ? path.join(relativePrefix, entry.name) : entry.name;
+
+      if (entry.isDirectory()) {
+        scan(fullPath, relPath);
+      } else if (entry.isFile() && isValidServiceFile(entry.name)) {
+        const { name, aliases } = filePathToServiceName(relPath);
+        if (name) {
+          results.push({
+            name,
+            aliases,
+            filePath: fullPath,
+            relativePath: relPath.replace(/\\/g, '/'),
+          });
+        }
+      }
+    }
+  }
+
+  scan(path.resolve(servicesDir));
+  return results;
+}
+
+module.exports = {
+  isValidServiceFile,
+  toCamelCase,
+  filePathToServiceName,
+  discoverServices,
+};