s3db.js 12.0.1 → 12.1.0

package/mcp/entrypoint.js

@@ -2,7 +2,7 @@
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { S3db, CachePlugin, CostsPlugin } from '../dist/s3db.es.js';
 import { FilesystemCache } from '../src/plugins/cache/filesystem-cache.class.js';
@@ -10,6 +10,7 @@ import { config } from 'dotenv';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { readFileSync } from 'fs';
+import express from 'express';
 
 // Load environment variables
 config();
@@ -1109,70 +1110,103 @@ class S3dbMCPServer {
   }
 
   setupTransport() {
-    const transport = process.argv.includes('--transport=sse') || process.env.MCP_TRANSPORT === 'sse'
-      ? new SSEServerTransport('/sse', process.env.MCP_SERVER_HOST || '0.0.0.0', parseInt(process.env.MCP_SERVER_PORT || '17500'))
-      : new StdioServerTransport();
-
-    this.server.connect(transport);
-    
-    // SSE specific setup
-    if (transport instanceof SSEServerTransport) {
-      const host = process.env.MCP_SERVER_HOST || '0.0.0.0';
-      const port = process.env.MCP_SERVER_PORT || '17500';
-      
-      console.log(`S3DB MCP Server running on http://${host}:${port}/sse`);
-      
-      // Add health check endpoint for SSE transport
-      this.setupHealthCheck(host, port);
+    const useHttp = process.argv.includes('--transport=http') || process.env.MCP_TRANSPORT === 'http';
+
+    if (useHttp) {
+      // Setup Express server for Streamable HTTP transport
+      this.setupHttpTransport();
+    } else {
+      // Use stdio transport (default)
+      const transport = new StdioServerTransport();
+      this.server.connect(transport);
     }
   }
 
-  setupHealthCheck(host, port) {
-    import('http').then(({ createServer }) => {
-      const healthServer = createServer((req, res) => {
-        if (req.url === '/health') {
-          const healthStatus = {
-            status: 'healthy',
-            timestamp: new Date().toISOString(),
-            uptime: process.uptime(),
-            version: SERVER_VERSION,
-            database: {
-              connected: database ? database.isConnected() : false,
-              bucket: database?.bucket || null,
-              keyPrefix: database?.keyPrefix || null,
-              resourceCount: database ? Object.keys(database.resources || {}).length : 0
-            },
-            memory: process.memoryUsage(),
-            environment: {
-              nodeVersion: process.version,
-              platform: process.platform,
-              transport: 'sse'
-            }
-          };
+  setupHttpTransport() {
+    const host = process.env.MCP_SERVER_HOST || '0.0.0.0';
+    const port = parseInt(process.env.MCP_SERVER_PORT || '17500');
+
+    const app = express();
+    app.use(express.json());
+
+    // Enable CORS for browser-based clients
+    app.use((req, res, next) => {
+      res.header('Access-Control-Allow-Origin', '*');
+      res.header('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+      res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+      res.header('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+
+      if (req.method === 'OPTIONS') {
+        return res.sendStatus(200);
+      }
+      next();
+    });
+
+    // Streamable HTTP endpoint (stateless mode - recommended)
+    app.post('/mcp', async (req, res) => {
+      try {
+        // Create a new transport for each request to prevent request ID collisions
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+          enableJsonResponse: true
+        });
+
+        res.on('close', () => {
+          transport.close();
+        });
 
-          res.writeHead(200, {
-            'Content-Type': 'application/json',
-            'Access-Control-Allow-Origin': '*',
-            'Access-Control-Allow-Methods': 'GET',
-            'Access-Control-Allow-Headers': 'Content-Type'
+        await this.server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+      } catch (error) {
+        console.error('Error handling MCP request:', error);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: '2.0',
+            error: {
+              code: -32603,
+              message: 'Internal server error'
+            },
+            id: null
           });
-          res.end(JSON.stringify(healthStatus, null, 2));
-        } else {
-          res.writeHead(404, { 'Content-Type': 'text/plain' });
-          res.end('Not Found');
         }
-      });
+      }
+    });
 
-      // Listen on a different port for health checks to avoid conflicts
-      const healthPort = parseInt(port) + 1;
-      healthServer.listen(healthPort, host, () => {
-        console.log(`Health check endpoint: http://${host}:${healthPort}/health`);
-      });
-    }).catch(err => {
-      console.warn('Could not setup health check endpoint:', err.message);
+    // Health check endpoint
+    app.get('/health', (req, res) => {
+      const healthStatus = {
+        status: 'healthy',
+        timestamp: new Date().toISOString(),
+        uptime: process.uptime(),
+        version: SERVER_VERSION,
+        database: {
+          connected: database ? database.isConnected() : false,
+          bucket: database?.bucket || null,
+          keyPrefix: database?.keyPrefix || null,
+          resourceCount: database ? Object.keys(database.resources || {}).length : 0
+        },
+        memory: process.memoryUsage(),
+        environment: {
+          nodeVersion: process.version,
+          platform: process.platform,
+          transport: 'streamable-http'
+        }
+      };
+
+      res.json(healthStatus);
+    });
+
+    // Start Express server
+    app.listen(port, host, () => {
+      console.log(`S3DB MCP Server running on http://${host}:${port}/mcp`);
+      console.log(`Health check endpoint: http://${host}:${port}/health`);
+    }).on('error', error => {
+      console.error('Server error:', error);
+      process.exit(1);
     });
   }
 
+
   // 📖 DOCUMENTATION TOOLS HANDLERS
 
   async handleS3dbQueryDocs(args) {
@@ -2718,8 +2752,8 @@ async function main() {
 
   console.log(`S3DB MCP Server v${SERVER_VERSION} started`);
   console.log(`Transport: ${args.transport}`);
-  if (args.transport === 'sse') {
-    console.log(`URL: http://${args.host}:${args.port}/sse`);
+  if (args.transport === 'http') {
+    console.log(`URL: http://${args.host}:${args.port}/mcp`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "12.0.1",
+  "version": "12.1.0",
   "description": "Use AWS S3, the world's most reliable document storage, as a database with this ORM.",
   "main": "dist/s3db.cjs.js",
   "module": "dist/s3db.es.js",
@@ -70,6 +70,7 @@
     "@smithy/node-http-handler": "^4.4.2",
     "@supercharge/promise-pool": "^3.2.0",
     "dotenv": "^17.2.3",
+    "express": "^5.1.0",
     "fastest-validator": "^1.19.1",
     "flat": "^6.0.1",
     "glob": "^11.0.3",

package/src/plugins/plugin.class.js

@@ -176,6 +176,11 @@ export class Plugin extends EventEmitter {
    * - Pode modificar argumentos/resultados.
    */
   addMiddleware(resource, methodName, middleware) {
+    // Safety check: verify method exists
+    if (typeof resource[methodName] !== 'function') {
+      throw new Error(`Cannot add middleware to "${methodName}": method does not exist on resource "${resource.name || 'unknown'}"`);
+    }
+
     if (!resource._pluginMiddlewares) {
       resource._pluginMiddlewares = {};
     }

package/src/plugins/relation.plugin.js

@@ -140,7 +140,10 @@ import {
  *   cache: true,
  *   batchSize: 100,
  *   preventN1: true,
- *   verbose: false
+ *   verbose: false,
+ *   fallbackLimit: null,  // null = no limit (recommended), number = max records in fallback queries
+ *   cascadeBatchSize: 10,  // Parallel operations in cascade delete/update (default: 10)
+ *   cascadeTransactions: false  // Enable rollback on cascade failures (default: false)
  * })
  *
  * === 💡 Usage Examples ===
@@ -283,6 +286,21 @@ class RelationPlugin extends Plugin {
     this.preventN1 = config.preventN1 !== undefined ? config.preventN1 : true;
     this.verbose = config.verbose || false;
 
+    // Fallback limit for non-partitioned queries
+    // null = no limit (load all records, slower but correct)
+    // number = max records to load (faster but may truncate)
+    // WARNING: Setting a limit may cause silent data loss if you have more related records!
+    this.fallbackLimit = config.fallbackLimit !== undefined ? config.fallbackLimit : null;
+
+    // Cascade batch size for parallel delete/update operations
+    // Higher = faster but more memory/connections (default: 10)
+    this.cascadeBatchSize = config.cascadeBatchSize || 10;
+
+    // Enable transaction/rollback support for cascade operations (default: false)
+    // When enabled, tracks all cascade operations and rolls back on failure
+    // Note: Best-effort rollback (S3 doesn't support true transactions)
+    this.cascadeTransactions = config.cascadeTransactions !== undefined ? config.cascadeTransactions : false;
+
     // Track loaded relations per request to prevent N+1
     this._loaderCache = new Map();
 
@@ -296,7 +314,8 @@ class RelationPlugin extends Plugin {
       batchLoads: 0,
       cascadeOperations: 0,
       partitionCacheHits: 0,
-      deduplicatedQueries: 0
+      deduplicatedQueries: 0,
+      fallbackLimitWarnings: 0
     };
   }
 
@@ -647,13 +666,7 @@ class RelationPlugin extends Plugin {
       );
     } else {
       // Fallback: Load all and filter (less efficient but works)
-      if (this.verbose) {
-        console.log(
-          `[RelationPlugin] No partition found for ${relatedResource.name}.${config.foreignKey}, using full scan`
-        );
-      }
-      const allRelated = await relatedResource.list({ limit: 10000 });
-      relatedRecords = allRelated.filter(r => localKeys.includes(r[config.foreignKey]));
+      relatedRecords = await this._fallbackLoad(relatedResource, config.foreignKey, localKeys);
     }
 
     // Create lookup map
@@ -707,13 +720,7 @@ class RelationPlugin extends Plugin {
       );
     } else {
       // Fallback: Load all and filter (less efficient but works)
-      if (this.verbose) {
-        console.log(
-          `[RelationPlugin] No partition found for ${relatedResource.name}.${config.foreignKey}, using full scan`
-        );
-      }
-      const allRelated = await relatedResource.list({ limit: 10000 });
-      relatedRecords = allRelated.filter(r => localKeys.includes(r[config.foreignKey]));
+      relatedRecords = await this._fallbackLoad(relatedResource, config.foreignKey, localKeys);
     }
 
     // Create lookup map (one-to-many)
@@ -775,13 +782,7 @@ class RelationPlugin extends Plugin {
         );
       } else {
         // Fallback: Load all and filter (less efficient but works)
-        if (this.verbose) {
-          console.log(
-            `[RelationPlugin] No partition found for ${relatedResource.name}.${config.localKey}, using full scan`
-          );
-        }
-        const allRelated = await relatedResource.list({ limit: 10000 });
-        return allRelated.filter(r => foreignKeys.includes(r[config.localKey]));
+        return await this._fallbackLoad(relatedResource, config.localKey, foreignKeys);
       }
     });
 
@@ -856,13 +857,7 @@ class RelationPlugin extends Plugin {
       );
     } else {
       // Fallback: Load all and filter (less efficient but works)
-      if (this.verbose) {
-        console.log(
-          `[RelationPlugin] No partition found for ${junctionResource.name}.${config.foreignKey}, using full scan`
-        );
-      }
-      const allJunction = await junctionResource.list({ limit: 10000 });
-      junctionRecords = allJunction.filter(j => localKeys.includes(j[config.foreignKey]));
+      junctionRecords = await this._fallbackLoad(junctionResource, config.foreignKey, localKeys);
     }
 
     if (junctionRecords.length === 0) {
@@ -888,13 +883,7 @@ class RelationPlugin extends Plugin {
       );
     } else {
       // Fallback: Load all and filter (less efficient but works)
-      if (this.verbose) {
-        console.log(
-          `[RelationPlugin] No partition found for ${relatedResource.name}.${config.localKey}, using full scan`
-        );
-      }
-      const allRelated = await relatedResource.list({ limit: 10000 });
-      relatedRecords = allRelated.filter(r => otherKeys.includes(r[config.localKey]));
+      relatedRecords = await this._fallbackLoad(relatedResource, config.localKey, otherKeys);
     }
 
     // Create maps
@@ -929,6 +918,60 @@ class RelationPlugin extends Plugin {
     return records;
   }
 
+  /**
+   * Batch process operations with controlled parallelism
+   * @private
+   */
+  async _batchProcess(items, operation, batchSize = null) {
+    if (items.length === 0) return [];
+
+    const actualBatchSize = batchSize || this.cascadeBatchSize;
+    const results = [];
+
+    // Process in chunks to control parallelism
+    for (let i = 0; i < items.length; i += actualBatchSize) {
+      const chunk = items.slice(i, i + actualBatchSize);
+      const chunkPromises = chunk.map(item => operation(item));
+      const chunkResults = await Promise.all(chunkPromises);
+      results.push(...chunkResults);
+    }
+
+    return results;
+  }
+
+  /**
+   * Load records using fallback (full scan) when no partition is available
+   * Issues warnings when limit is reached to prevent silent data loss
+   * @private
+   */
+  async _fallbackLoad(resource, fieldName, filterValues) {
+    const options = this.fallbackLimit !== null ? { limit: this.fallbackLimit } : {};
+
+    if (this.verbose) {
+      console.log(
+        `[RelationPlugin] No partition found for ${resource.name}.${fieldName}, using full scan` +
+        (this.fallbackLimit ? ` (limited to ${this.fallbackLimit} records)` : ' (no limit)')
+      );
+    }
+
+    const allRecords = await resource.list(options);
+    const filteredRecords = allRecords.filter(r => filterValues.includes(r[fieldName]));
+
+    // WARNING: If we hit the limit, we may have missed some records!
+    if (this.fallbackLimit && allRecords.length >= this.fallbackLimit) {
+      this.stats.fallbackLimitWarnings++;
+      console.warn(
+        `[RelationPlugin] WARNING: Fallback query for ${resource.name}.${fieldName} hit the limit of ${this.fallbackLimit} records. ` +
+        `Some related records may be missing! Consider:\n` +
+        `  1. Adding a partition on field "${fieldName}" for better performance\n` +
+        `  2. Increasing fallbackLimit in plugin config (or set to null for no limit)\n` +
+        `  Partition example: partitions: { by${fieldName.charAt(0).toUpperCase() + fieldName.slice(1)}: { fields: { ${fieldName}: 'string' } } }`
+      );
+    }
+
+    return filteredRecords;
+  }
+
   /**
    * Find partition by field name (for efficient relation loading)
    * Uses cache to avoid repeated lookups
@@ -1028,6 +1071,7 @@ class RelationPlugin extends Plugin {
   /**
    * Cascade delete operation
    * Uses partitions when available for efficient cascade
+   * Supports transaction/rollback when enabled
    * @private
    */
   async _cascadeDelete(record, resource, relationName, config) {
@@ -1041,6 +1085,10 @@ class RelationPlugin extends Plugin {
       });
     }
 
+    // Track deleted records for rollback (if transactions enabled)
+    const deletedRecords = [];
+    const junctionResource = config.type === 'belongsToMany' ? this.database.resource(config.through) : null;
+
     try {
       if (config.type === 'hasMany') {
         // Delete all related records - use partition if available
@@ -1065,13 +1113,20 @@ class RelationPlugin extends Plugin {
           });
         }
 
-        for (const related of relatedRecords) {
-          await relatedResource.delete(related.id);
+        // Track records for rollback if transactions enabled
+        if (this.cascadeTransactions) {
+          deletedRecords.push(...relatedRecords.map(r => ({ type: 'delete', resource: relatedResource, record: r })));
         }
 
+        // Batch delete for better performance (10-100x faster than sequential)
+        await this._batchProcess(relatedRecords, async (related) => {
+          return await relatedResource.delete(related.id);
+        });
+
         if (this.verbose) {
           console.log(
-            `[RelationPlugin] Cascade deleted ${relatedRecords.length} ${config.resource} for ${resource.name}:${record.id}`
+            `[RelationPlugin] Cascade deleted ${relatedRecords.length} ${config.resource} for ${resource.name}:${record.id} ` +
+            `(batched in ${Math.ceil(relatedRecords.length / this.cascadeBatchSize)} chunks)`
           );
         }
       } else if (config.type === 'hasOne') {
@@ -1093,6 +1148,10 @@ class RelationPlugin extends Plugin {
         }
 
         if (relatedRecords.length > 0) {
+          // Track for rollback if transactions enabled
+          if (this.cascadeTransactions) {
+            deletedRecords.push({ type: 'delete', resource: relatedResource, record: relatedRecords[0] });
+          }
           await relatedResource.delete(relatedRecords[0].id);
         }
       } else if (config.type === 'belongsToMany') {
@@ -1120,18 +1179,51 @@ class RelationPlugin extends Plugin {
             });
           }
 
-          for (const junction of junctionRecords) {
-            await junctionResource.delete(junction.id);
+          // Track for rollback if transactions enabled
+          if (this.cascadeTransactions) {
+            deletedRecords.push(...junctionRecords.map(j => ({ type: 'delete', resource: junctionResource, record: j })));
           }
 
+          // Batch delete for better performance (10-100x faster than sequential)
+          await this._batchProcess(junctionRecords, async (junction) => {
+            return await junctionResource.delete(junction.id);
+          });
+
           if (this.verbose) {
             console.log(
-              `[RelationPlugin] Cascade deleted ${junctionRecords.length} junction records from ${config.through}`
+              `[RelationPlugin] Cascade deleted ${junctionRecords.length} junction records from ${config.through} ` +
+              `(batched in ${Math.ceil(junctionRecords.length / this.cascadeBatchSize)} chunks)`
             );
           }
         }
       }
     } catch (error) {
+      // Attempt rollback if transactions enabled
+      if (this.cascadeTransactions && deletedRecords.length > 0) {
+        console.error(
+          `[RelationPlugin] Cascade delete failed, attempting rollback of ${deletedRecords.length} records...`
+        );
+
+        const rollbackErrors = [];
+        // Rollback in reverse order (LIFO)
+        for (const { resource: res, record: rec } of deletedRecords.reverse()) {
+          try {
+            await res.insert(rec);
+          } catch (rollbackError) {
+            rollbackErrors.push({ record: rec.id, error: rollbackError.message });
+          }
+        }
+
+        if (rollbackErrors.length > 0) {
+          console.error(
+            `[RelationPlugin] Rollback partially failed for ${rollbackErrors.length} records:`,
+            rollbackErrors
+          );
+        } else if (this.verbose) {
+          console.log(`[RelationPlugin] Rollback successful, restored ${deletedRecords.length} records`);
+        }
+      }
+
       throw new CascadeError('delete', resource.name, record.id, error, {
         relation: relationName,
         relatedResource: config.resource
@@ -1142,6 +1234,7 @@ class RelationPlugin extends Plugin {
   /**
    * Cascade update operation (update foreign keys when local key changes)
    * Uses partitions when available for efficient cascade
+   * Supports transaction/rollback when enabled
    * @private
    */
   async _cascadeUpdate(record, changes, resource, relationName, config) {
@@ -1152,6 +1245,9 @@ class RelationPlugin extends Plugin {
       return;
     }
 
+    // Track updated records for rollback (if transactions enabled)
+    const updatedRecords = [];
+
     try {
       const oldLocalKeyValue = record[config.localKey];
       const newLocalKeyValue = changes[config.localKey];
@@ -1182,18 +1278,58 @@ class RelationPlugin extends Plugin {
         });
       }
 
-      for (const related of relatedRecords) {
-        await relatedResource.update(related.id, {
+      // Track old values for rollback if transactions enabled
+      if (this.cascadeTransactions) {
+        updatedRecords.push(...relatedRecords.map(r => ({
+          type: 'update',
+          resource: relatedResource,
+          id: r.id,
+          oldValue: r[config.foreignKey],
+          newValue: newLocalKeyValue,
+          field: config.foreignKey
+        })));
+      }
+
+      // Batch update for better performance (10-100x faster than sequential)
+      await this._batchProcess(relatedRecords, async (related) => {
+        return await relatedResource.update(related.id, {
           [config.foreignKey]: newLocalKeyValue
         }, { skipCascade: true }); // Prevent infinite cascade loop
-      }
+      });
 
       if (this.verbose) {
         console.log(
-          `[RelationPlugin] Cascade updated ${relatedRecords.length} ${config.resource} records`
+          `[RelationPlugin] Cascade updated ${relatedRecords.length} ${config.resource} records ` +
+          `(batched in ${Math.ceil(relatedRecords.length / this.cascadeBatchSize)} chunks)`
         );
       }
     } catch (error) {
+      // Attempt rollback if transactions enabled
+      if (this.cascadeTransactions && updatedRecords.length > 0) {
+        console.error(
+          `[RelationPlugin] Cascade update failed, attempting rollback of ${updatedRecords.length} records...`
+        );
+
+        const rollbackErrors = [];
+        // Rollback in reverse order (LIFO)
+        for (const { resource: res, id, field, oldValue } of updatedRecords.reverse()) {
+          try {
+            await res.update(id, { [field]: oldValue }, { skipCascade: true });
+          } catch (rollbackError) {
+            rollbackErrors.push({ id, error: rollbackError.message });
+          }
+        }
+
+        if (rollbackErrors.length > 0) {
+          console.error(
+            `[RelationPlugin] Rollback partially failed for ${rollbackErrors.length} records:`,
+            rollbackErrors
+          );
+        } else if (this.verbose) {
+          console.log(`[RelationPlugin] Rollback successful, restored ${updatedRecords.length} records`);
+        }
+      }
+
       throw new CascadeError('update', resource.name, record.id, error, {
         relation: relationName,
         relatedResource: config.resource