s3db.js 11.3.2 → 12.0.0

package/src/plugins/api/routes/resource-routes.js

@@ -0,0 +1,304 @@
+/**
+ * Resource Routes - Dynamic RESTful routes for s3db.js resources
+ *
+ * Automatically generates REST endpoints for each resource
+ */
+
+import { Hono } from 'hono';
+import { asyncHandler } from '../utils/error-handler.js';
+import * as formatter from '../utils/response-formatter.js';
+
+/**
+ * Create routes for a resource
+ * @param {Object} resource - s3db.js Resource instance
+ * @param {string} version - Resource version (e.g., 'v1', 'v1')
+ * @param {Object} config - Route configuration
+ * @returns {Hono} Hono app with resource routes
+ */
+export function createResourceRoutes(resource, version, config = {}) {
+  const app = new Hono();
+  const {
+    methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
+    customMiddleware = [],
+    enableValidation = true
+  } = config;
+
+  const resourceName = resource.name;
+  const basePath = `/${version}/${resourceName}`;
+
+  // Apply custom middleware
+  customMiddleware.forEach(middleware => {
+    app.use('*', middleware);
+  });
+
+  // LIST - GET /{version}/{resource}
+  if (methods.includes('GET')) {
+    app.get('/', asyncHandler(async (c) => {
+      const query = c.req.query();
+      const limit = parseInt(query.limit) || 100;
+      const offset = parseInt(query.offset) || 0;
+      const partition = query.partition;
+      const partitionValues = query.partitionValues
+        ? JSON.parse(query.partitionValues)
+        : undefined;
+
+      // Extract filters from query string (any key that's not limit, offset, partition, partitionValues, sort)
+      const reservedKeys = ['limit', 'offset', 'partition', 'partitionValues', 'sort'];
+      const filters = {};
+      for (const [key, value] of Object.entries(query)) {
+        if (!reservedKeys.includes(key)) {
+          // Try to parse as JSON for complex values
+          try {
+            filters[key] = JSON.parse(value);
+          } catch {
+            // Keep as string if not valid JSON
+            filters[key] = value;
+          }
+        }
+      }
+
+      let items;
+      let total;
+
+      // Use query if filters are present
+      if (Object.keys(filters).length > 0) {
+        items = await resource.query(filters, { limit: limit + offset });
+        items = items.slice(offset, offset + limit);
+        total = items.length;
+      } else if (partition && partitionValues) {
+        // Query specific partition
+        items = await resource.listPartition({
+          partition,
+          partitionValues,
+          limit: limit + offset
+        });
+        items = items.slice(offset, offset + limit);
+        total = items.length;
+      } else {
+        // Regular list
+        items = await resource.list({ limit: limit + offset });
+        items = items.slice(offset, offset + limit);
+        total = items.length;
+      }
+
+      const response = formatter.list(items, {
+        total,
+        page: Math.floor(offset / limit) + 1,
+        pageSize: limit,
+        pageCount: Math.ceil(total / limit)
+      });
+
+      // Set pagination headers
+      c.header('X-Total-Count', total.toString());
+      c.header('X-Page-Count', Math.ceil(total / limit).toString());
+
+      return c.json(response, response._status);
+    }));
+  }
+
+  // GET ONE - GET /{version}/{resource}/:id
+  if (methods.includes('GET')) {
+    app.get('/:id', asyncHandler(async (c) => {
+      const id = c.req.param('id');
+      const query = c.req.query();
+      const partition = query.partition;
+      const partitionValues = query.partitionValues
+        ? JSON.parse(query.partitionValues)
+        : undefined;
+
+      let item;
+
+      if (partition && partitionValues) {
+        // Get from specific partition
+        item = await resource.getFromPartition({
+          id,
+          partitionName: partition,
+          partitionValues
+        });
+      } else {
+        // Regular get
+        item = await resource.get(id);
+      }
+
+      if (!item) {
+        const response = formatter.notFound(resourceName, id);
+        return c.json(response, response._status);
+      }
+
+      const response = formatter.success(item);
+      return c.json(response, response._status);
+    }));
+  }
+
+  // CREATE - POST /{version}/{resource}
+  if (methods.includes('POST')) {
+    app.post('/', asyncHandler(async (c) => {
+      const data = await c.req.json();
+
+      // Validation middleware will run if enabled
+      const item = await resource.insert(data);
+
+      const location = `${basePath}/${item.id}`;
+      const response = formatter.created(item, location);
+
+      c.header('Location', location);
+      return c.json(response, response._status);
+    }));
+  }
+
+  // UPDATE (full) - PUT /{version}/{resource}/:id
+  if (methods.includes('PUT')) {
+    app.put('/:id', asyncHandler(async (c) => {
+      const id = c.req.param('id');
+      const data = await c.req.json();
+
+      // Check if exists
+      const existing = await resource.get(id);
+      if (!existing) {
+        const response = formatter.notFound(resourceName, id);
+        return c.json(response, response._status);
+      }
+
+      // Full update
+      const updated = await resource.update(id, data);
+
+      const response = formatter.success(updated);
+      return c.json(response, response._status);
+    }));
+  }
+
+  // UPDATE (partial) - PATCH /{version}/{resource}/:id
+  if (methods.includes('PATCH')) {
+    app.patch('/:id', asyncHandler(async (c) => {
+      const id = c.req.param('id');
+      const data = await c.req.json();
+
+      // Check if exists
+      const existing = await resource.get(id);
+      if (!existing) {
+        const response = formatter.notFound(resourceName, id);
+        return c.json(response, response._status);
+      }
+
+      // Partial update (merge with existing)
+      const merged = { ...existing, ...data, id };
+      const updated = await resource.update(id, merged);
+
+      const response = formatter.success(updated);
+      return c.json(response, response._status);
+    }));
+  }
+
+  // DELETE - DELETE /{version}/{resource}/:id
+  if (methods.includes('DELETE')) {
+    app.delete('/:id', asyncHandler(async (c) => {
+      const id = c.req.param('id');
+
+      // Check if exists
+      const existing = await resource.get(id);
+      if (!existing) {
+        const response = formatter.notFound(resourceName, id);
+        return c.json(response, response._status);
+      }
+
+      await resource.delete(id);
+
+      const response = formatter.noContent();
+      return c.json(response, response._status);
+    }));
+  }
+
+  // HEAD - HEAD /{version}/{resource}
+  if (methods.includes('HEAD')) {
+    app.on('HEAD', '/', asyncHandler(async (c) => {
+      // Get statistics
+      const total = await resource.count();
+
+      // Get all items to calculate stats (for small datasets)
+      // For large datasets, this might need optimization
+      const allItems = await resource.list({ limit: 1000 });
+
+      // Calculate statistics
+      const stats = {
+        total,
+        version: resource.config?.currentVersion || resource.version || 'v1'
+      };
+
+      // Add resource-specific stats
+      c.header('X-Total-Count', total.toString());
+      c.header('X-Resource-Version', stats.version);
+
+      // Add schema info
+      c.header('X-Schema-Fields', Object.keys(resource.config?.attributes || {}).length.toString());
+
+      return c.body(null, 200);
+    }));
+
+    app.on('HEAD', '/:id', asyncHandler(async (c) => {
+      const id = c.req.param('id');
+      const item = await resource.get(id);
+
+      if (!item) {
+        return c.body(null, 404);
+      }
+
+      // Add metadata headers
+      if (item.updatedAt) {
+        c.header('Last-Modified', new Date(item.updatedAt).toUTCString());
+      }
+
+      return c.body(null, 200);
+    }));
+  }
+
+  // OPTIONS - OPTIONS /{version}/{resource}
+  if (methods.includes('OPTIONS')) {
+    app.options('/', asyncHandler(async (c) => {
+      c.header('Allow', methods.join(', '));
+
+      // Return metadata about the resource
+      const total = await resource.count();
+      const schema = resource.config?.attributes || {};
+      const version = resource.config?.currentVersion || resource.version || 'v1';
+
+      const metadata = {
+        resource: resourceName,
+        version,
+        totalRecords: total,
+        allowedMethods: methods,
+        schema: Object.entries(schema).map(([name, def]) => ({
+          name,
+          type: typeof def === 'string' ? def.split('|')[0] : def.type,
+          rules: typeof def === 'string' ? def.split('|').slice(1) : []
+        })),
+        endpoints: {
+          list: `/${version}/${resourceName}`,
+          get: `/${version}/${resourceName}/:id`,
+          create: `/${version}/${resourceName}`,
+          update: `/${version}/${resourceName}/:id`,
+          delete: `/${version}/${resourceName}/:id`
+        },
+        queryParameters: {
+          limit: 'number (1-1000, default: 100)',
+          offset: 'number (min: 0, default: 0)',
+          partition: 'string (partition name)',
+          partitionValues: 'JSON string',
+          '[any field]': 'any (filter by field value)'
+        }
+      };
+
+      return c.json(metadata);
+    }));
+
+    app.options('/:id', (c) => {
+      c.header('Allow', methods.filter(m => m !== 'POST').join(', '));
+      return c.body(null, 204);
+    });
+  }
+
+  return app;
+}
+
+export default {
+  createResourceRoutes
+};

package/src/plugins/api/server.js

@@ -0,0 +1,350 @@
+/**
+ * API Server - Hono-based HTTP server for s3db.js API Plugin
+ *
+ * Manages HTTP server lifecycle and routing
+ */
+
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { swaggerUI } from '@hono/swagger-ui';
+import { createResourceRoutes } from './routes/resource-routes.js';
+import { errorHandler } from './utils/error-handler.js';
+import * as formatter from './utils/response-formatter.js';
+import { generateOpenAPISpec } from './utils/openapi-generator.js';
+
+export class ApiServer {
+  /**
+   * Create API server
+   * @param {Object} options - Server options
+   * @param {number} options.port - Server port
+   * @param {string} options.host - Server host
+   * @param {Object} options.database - s3db.js database instance
+   * @param {Object} options.resources - Resource configuration
+   * @param {Array} options.middlewares - Global middlewares
+   */
+  constructor(options = {}) {
+    this.options = {
+      port: options.port || 3000,
+      host: options.host || '0.0.0.0',
+      database: options.database,
+      resources: options.resources || {},
+      middlewares: options.middlewares || [],
+      verbose: options.verbose || false,
+      auth: options.auth || {},
+      docsEnabled: options.docsEnabled !== false, // Enable /docs by default
+      docsUI: options.docsUI || 'redoc', // 'swagger' or 'redoc'
+      maxBodySize: options.maxBodySize || 10 * 1024 * 1024, // 10MB default
+      rootHandler: options.rootHandler, // Custom handler for root path, if not provided redirects to /docs
+      apiInfo: {
+        title: options.apiTitle || 's3db.js API',
+        version: options.apiVersion || '1.0.0',
+        description: options.apiDescription || 'Auto-generated REST API for s3db.js resources'
+      }
+    };
+
+    this.app = new Hono();
+    this.server = null;
+    this.isRunning = false;
+    this.openAPISpec = null;
+
+    this._setupRoutes();
+  }
+
+  /**
+   * Setup all routes
+   * @private
+   */
+  _setupRoutes() {
+    // Apply global middlewares
+    this.options.middlewares.forEach(middleware => {
+      this.app.use('*', middleware);
+    });
+
+    // Body size limit middleware (only for POST, PUT, PATCH)
+    this.app.use('*', async (c, next) => {
+      const method = c.req.method;
+
+      if (['POST', 'PUT', 'PATCH'].includes(method)) {
+        const contentLength = c.req.header('content-length');
+
+        if (contentLength) {
+          const size = parseInt(contentLength);
+
+          if (size > this.options.maxBodySize) {
+            const response = formatter.payloadTooLarge(size, this.options.maxBodySize);
+            c.header('Connection', 'close'); // Close connection for large payloads
+            return c.json(response, response._status);
+          }
+        }
+      }
+
+      await next();
+    });
+
+    // Kubernetes Liveness Probe - checks if app is alive
+    // If this fails, k8s will restart the pod
+    this.app.get('/health/live', (c) => {
+      // Simple check: if we can respond, we're alive
+      const response = formatter.success({
+        status: 'alive',
+        timestamp: new Date().toISOString()
+      });
+      return c.json(response);
+    });
+
+    // Kubernetes Readiness Probe - checks if app is ready to receive traffic
+    // If this fails, k8s will remove pod from service endpoints
+    this.app.get('/health/ready', (c) => {
+      // Check if database is connected and resources are loaded
+      const isReady = this.options.database &&
+                      this.options.database.connected &&
+                      Object.keys(this.options.database.resources).length > 0;
+
+      if (!isReady) {
+        const response = formatter.error('Service not ready', {
+          status: 503,
+          code: 'NOT_READY',
+          details: {
+            database: {
+              connected: this.options.database?.connected || false,
+              resources: Object.keys(this.options.database?.resources || {}).length
+            }
+          }
+        });
+        return c.json(response, 503);
+      }
+
+      const response = formatter.success({
+        status: 'ready',
+        database: {
+          connected: true,
+          resources: Object.keys(this.options.database.resources).length
+        },
+        timestamp: new Date().toISOString()
+      });
+      return c.json(response);
+    });
+
+    // Generic Health Check endpoint
+    this.app.get('/health', (c) => {
+      const response = formatter.success({
+        status: 'ok',
+        uptime: process.uptime(),
+        timestamp: new Date().toISOString(),
+        checks: {
+          liveness: '/health/live',
+          readiness: '/health/ready'
+        }
+      });
+      return c.json(response);
+    });
+
+    // Root endpoint - custom handler or redirect to docs
+    this.app.get('/', (c) => {
+      // If user provided a custom root handler, use it
+      if (this.options.rootHandler) {
+        return this.options.rootHandler(c);
+      }
+
+      // Otherwise, redirect to docs
+      return c.redirect('/docs', 302);
+    });
+
+    // OpenAPI spec endpoint
+    if (this.options.docsEnabled) {
+      this.app.get('/openapi.json', (c) => {
+        if (!this.openAPISpec) {
+          this.openAPISpec = this._generateOpenAPISpec();
+        }
+        return c.json(this.openAPISpec);
+      });
+
+      // API Documentation UI endpoint
+      if (this.options.docsUI === 'swagger') {
+        // Swagger UI (legacy, less pretty)
+        this.app.get('/docs', swaggerUI({
+          url: '/openapi.json'
+        }));
+      } else {
+        // Redoc (modern, beautiful design!)
+        this.app.get('/docs', (c) => {
+          return c.html(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${this.options.apiInfo.title} - API Documentation</title>
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+<body>
+  <redoc spec-url="/openapi.json"></redoc>
+  <script src="https://cdn.redoc.ly/redoc/v2.5.1/bundles/redoc.standalone.js"></script>
+</body>
+</html>`);
+        });
+      }
+    }
+
+    // Setup resource routes
+    this._setupResourceRoutes();
+
+    // Global error handler
+    this.app.onError((err, c) => {
+      return errorHandler(err, c);
+    });
+
+    // 404 handler
+    this.app.notFound((c) => {
+      const response = formatter.error('Route not found', {
+        status: 404,
+        code: 'NOT_FOUND',
+        details: {
+          path: c.req.path,
+          method: c.req.method
+        }
+      });
+      return c.json(response, 404);
+    });
+  }
+
+  /**
+   * Setup routes for all resources
+   * @private
+   */
+  _setupResourceRoutes() {
+    const { database, resources: resourceConfigs } = this.options;
+
+    // Get all resources from database
+    const resources = database.resources;
+
+    for (const [name, resource] of Object.entries(resources)) {
+      // Skip plugin resources unless explicitly included
+      if (name.startsWith('plg_') && !resourceConfigs[name]) {
+        continue;
+      }
+
+      // Get resource configuration
+      const config = resourceConfigs[name] || {
+        methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
+        auth: false
+      };
+
+      // Determine version
+      const version = resource.config?.currentVersion || resource.version || 'v1';
+
+      // Create resource routes
+      const resourceApp = createResourceRoutes(resource, version, {
+        methods: config.methods,
+        customMiddleware: config.customMiddleware || [],
+        enableValidation: config.validation !== false
+      });
+
+      // Mount resource routes
+      this.app.route(`/${version}/${name}`, resourceApp);
+
+      if (this.options.verbose) {
+        console.log(`[API Plugin] Mounted routes for resource '${name}' at /${version}/${name}`);
+      }
+    }
+  }
+
+  /**
+   * Start the server
+   * @returns {Promise<void>}
+   */
+  async start() {
+    if (this.isRunning) {
+      console.warn('[API Plugin] Server is already running');
+      return;
+    }
+
+    const { port, host } = this.options;
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.server = serve({
+          fetch: this.app.fetch,
+          port,
+          hostname: host
+        }, (info) => {
+          this.isRunning = true;
+          console.log(`[API Plugin] Server listening on http://${info.address}:${info.port}`);
+          resolve();
+        });
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Stop the server
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    if (!this.isRunning) {
+      console.warn('[API Plugin] Server is not running');
+      return;
+    }
+
+    if (this.server && typeof this.server.close === 'function') {
+      await new Promise((resolve) => {
+        this.server.close(() => {
+          this.isRunning = false;
+          console.log('[API Plugin] Server stopped');
+          resolve();
+        });
+      });
+    } else {
+      // For some Hono adapters, server might not have close method
+      this.isRunning = false;
+      console.log('[API Plugin] Server stopped');
+    }
+  }
+
+  /**
+   * Get server info
+   * @returns {Object} Server information
+   */
+  getInfo() {
+    return {
+      isRunning: this.isRunning,
+      port: this.options.port,
+      host: this.options.host,
+      resources: Object.keys(this.options.database.resources).length
+    };
+  }
+
+  /**
+   * Get Hono app instance
+   * @returns {Hono} Hono app
+   */
+  getApp() {
+    return this.app;
+  }
+
+  /**
+   * Generate OpenAPI specification
+   * @private
+   * @returns {Object} OpenAPI spec
+   */
+  _generateOpenAPISpec() {
+    const { port, host, database, resources, auth, apiInfo } = this.options;
+
+    return generateOpenAPISpec(database, {
+      title: apiInfo.title,
+      version: apiInfo.version,
+      description: apiInfo.description,
+      serverUrl: `http://${host === '0.0.0.0' ? 'localhost' : host}:${port}`,
+      auth,
+      resources
+    });
+  }
+}
+
+export default ApiServer;