go-duck-cli 1.0.5 → 1.0.7

package/generators/docs.js

@@ -33,6 +33,7 @@ export const generateDocumentation = async (config, entities, outputDir, enums =
         { file: 'gdl', title: 'GDL Reference' },
         { file: 'cli', title: 'CLI & Code Injection' },
         { file: 'rest', title: 'REST & Search API' },
+        { file: 'multitenancy', title: 'Multi-Tenancy' },
         { file: 'grpc', title: 'Kratos gRPC API' },
         { file: 'graphql', title: 'GraphQL Framework' },
         { file: 'realtime', title: 'WebSockets & MQTT' },

package/generators/multitenancy.js

@@ -10,14 +10,76 @@ package middleware
 import (
 	"fmt"
 	"net/http"
+	"sync"
 
 	"github.com/gin-gonic/gin"
+	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
+	"{{app_name}}/config"
+)
+
+// TenantDBManager handles dynamic connection pooling for all tenants
+type TenantDBManager struct {
+	masterDB *gorm.DB
+	configs  *config.Config
+	conns    map[string]*gorm.DB
+	mu       sync.RWMutex
+}
+
+var (
+	manager *TenantDBManager
+	once    sync.Once
 )
 
-func TenantMiddleware(db *gorm.DB) gin.HandlerFunc {
+func GetTenantManager(db *gorm.DB, cfg *config.Config) *TenantDBManager {
+	once.Do(func() {
+		manager = &TenantDBManager{
+			masterDB: db,
+			configs:  cfg,
+			conns:    make(map[string]*gorm.DB),
+		}
+	})
+	return manager
+}
+
+func (m *TenantDBManager) GetDB(dbName string) (*gorm.DB, error) {
+	m.mu.RLock()
+	if db, ok := m.conns[dbName]; ok {
+		m.mu.RUnlock()
+		return db, nil
+	}
+	m.mu.RUnlock()
+
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	// Double check
+	if db, ok := m.conns[dbName]; ok {
+		return db, nil
+	}
+
+	// Dynamic Connection Opening
+	ds := m.configs.GoDuck.Datasource
+	dsn := fmt.Sprintf("host=%s user=%s password=%s dbname=%s port=%d sslmode=disable TimeZone=UTC",
+		ds.Host, ds.Username, ds.Password, dbName, ds.Port)
+
+	newDB, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
+	if err != nil {
+		return nil, err
+	}
+
+	m.conns[dbName] = newDB
+	return newDB, nil
+}
+
+func TenantMiddleware(db *gorm.DB, cfg *config.Config) gin.HandlerFunc {
+	mgr := GetTenantManager(db, cfg)
+
 	return func(c *gin.Context) {
-		// 1. Get roles from JWT (previously set by JWTMiddleware)
+		// 1. Identification (Hint from Header)
+		requestedTenant := c.GetHeader("X-Tenant-ID")
+
+		// 2. Authorization (Extracted from JWT by JWTMiddleware)
 		userRolesInterface, exists := c.Get("UserRoles")
 		if !exists {
 			c.JSON(http.StatusUnauthorized, gin.H{"error": "No roles found in token"})
@@ -32,17 +94,34 @@ func TenantMiddleware(db *gorm.DB) gin.HandlerFunc {
 			return
 		}
 
-		// 2. Lookup DB name for the roles in tenant_roles table
+		// 3. Resolution (Which DB is this role authorized to access?)
 		var dbName string
 		err := db.Raw("SELECT db_name FROM tenant_roles WHERE role_name IN ? LIMIT 1", roles).Scan(&dbName).Error
 		
 		if err != nil || dbName == "" {
-			// Fallback to default DB if no role match (optional behavior)
-			dbName = "go-duck" 
+			c.JSON(http.StatusForbidden, gin.H{"error": "Security: No tenant context mapped to user roles"})
+			c.Abort()
+			return
+		}
+
+		// 4. Security Check (Prevent Cross-Tenant Spoofing)
+		if requestedTenant != "" && requestedTenant != dbName {
+			c.JSON(http.StatusForbidden, gin.H{"error": "Security Breach: Header/Token tenant mismatch"})
+			c.Abort()
+			return
+		}
+
+		// 5. Dynamic Switching (Get or Create the DB Connection)
+		tenantConn, err := mgr.GetDB(dbName)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to resolve tenant database connection"})
+			c.Abort()
+			return
 		}
 
-		// 3. Store tenant info for downstream use
+		// 6. Inject Live Connection into Context
 		c.Set("tenantDB", dbName)
+		c.Set("tenantDBConn", tenantConn)
 		c.Next()
 	}
 }

package/generators/postgrest.js

@@ -35,11 +35,30 @@ func (sc *SearchController) GenericSearch(c *gin.Context) {
 			continue
 		}
 
+		// Security: Basic Sanitization for Key (Allowing letters, numbers, _, -, and JSON arrows)
+		// We split the key if it contains JSON operators to handle them specifically
+		processedKey := key
+		if strings.Contains(key, "->") {
+			parts := strings.SplitN(key, "->", 2)
+			column := parts[0]
+			path := parts[1]
+			operator := "->"
+			if strings.HasPrefix(path, ">") {
+				operator = "->>"
+				path = path[1:]
+			}
+			// Wrap column in quotes and path in single quotes for Postgres JSONB safety
+			processedKey = fmt.Sprintf("\"%s\"%s'%s'", column, operator, path)
+		} else {
+			// Standard column: Wrap in quotes for safety
+			processedKey = fmt.Sprintf("\"%s\"", key)
+		}
+
 		for _, val := range values {
 			parts := strings.SplitN(val, ".", 2)
 			if len(parts) < 2 {
 				// Default to equality
-				query = query.Where(fmt.Sprintf("%s = ?", key), val)
+				query = query.Where(processedKey+" = ?", val)
 				continue
 			}
 
@@ -48,24 +67,27 @@ func (sc *SearchController) GenericSearch(c *gin.Context) {
 
 			switch op {
 			case "eq":
-				query = query.Where(fmt.Sprintf("%s = ?", key), target)
+				query = query.Where(processedKey+" = ?", target)
 			case "neq":
-				query = query.Where(fmt.Sprintf("%s <> ?", key), target)
+				query = query.Where(processedKey+" <> ?", target)
 			case "gt":
-				query = query.Where(fmt.Sprintf("%s > ?", key), target)
+				query = query.Where(processedKey+" > ?", target)
 			case "gte":
-				query = query.Where(fmt.Sprintf("%s >= ?", key), target)
+				query = query.Where(processedKey+" >= ?", target)
 			case "lt":
-				query = query.Where(fmt.Sprintf("%s < ?", key), target)
+				query = query.Where(processedKey+" < ?", target)
 			case "lte":
-				query = query.Where(fmt.Sprintf("%s <= ?", key), target)
+				query = query.Where(processedKey+" <= ?", target)
 			case "like":
-				query = query.Where(fmt.Sprintf("%s LIKE ?", key), "%"+target+"%")
+				query = query.Where(processedKey+" LIKE ?", "%"+target+"%")
 			case "ilike":
-				query = query.Where(fmt.Sprintf("%s ILIKE ?", key), "%"+target+"%")
+				query = query.Where(processedKey+" ILIKE ?", "%"+target+"%")
 			case "in":
 				list := strings.Split(target, ",")
-				query = query.Where(fmt.Sprintf("%s IN ?", key), list)
+				query = query.Where(processedKey+" IN ?", list)
+			default:
+				// Fallback to equality if operator is unrecognized
+				query = query.Where(processedKey+" = ?", val)
 			}
 		}
 	}

package/generators/swagger.js

@@ -18,6 +18,19 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
         ],
         paths: {},
         components: {
+            securitySchemes: {
+                BearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT'
+                },
+                TenantID: {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: 'X-Tenant-ID',
+                    description: 'The unique identifier for the tenant dashboard context'
+                }
+            },
             schemas: {
                 Error: {
                     type: 'object',
@@ -26,9 +39,16 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
                     }
                 }
             }
-        }
+        },
+        security: [
+            { BearerAuth: [], TenantID: [] }
+        ]
     };
 
+    const commonHeaders = [
+        { name: 'X-Tenant-ID', in: 'header', required: true, schema: { type: 'string', default: 'default' }, description: 'Multi-tenancy context identifier' }
+    ];
+
     // 1. Add Entity Paths
     for (const entity of entities) {
         const name = entity.name.toLowerCase();
@@ -53,6 +73,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             post: {
                 tags: [capitalized],
                 summary: `Create a new ${capitalized}`,
+                parameters: [...commonHeaders],
                 requestBody: {
                     required: true,
                     content: { 'application/json': { schema: { $ref: `#/components/schemas/${capitalized}` } } }
@@ -65,9 +86,10 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
                 tags: [capitalized],
                 summary: `Get all ${capitalized}s`,
                 parameters: [
-                    { name: 'page', in: 'query', schema: { type: 'integer' } },
-                    { name: 'size', in: 'query', schema: { type: 'integer' } },
-                    { name: 'eager', in: 'query', schema: { type: 'boolean' } }
+                    ...commonHeaders,
+                    { name: 'page', in: 'query', schema: { type: 'integer' }, description: 'Zero-based page index' },
+                    { name: 'size', in: 'query', schema: { type: 'integer' }, description: 'Records per page' },
+                    { name: 'eager', in: 'query', schema: { type: 'boolean' }, description: 'If true, performs SQL Join to fetch relations' }
                 ],
                 responses: {
                     200: { description: 'OK', content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } } }
@@ -80,7 +102,11 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             get: {
                 tags: [capitalized],
                 summary: `Get ${capitalized} by ID`,
-                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
+                parameters: [
+                    ...commonHeaders,
+                    { name: 'id', in: 'path', required: true, schema: { type: 'integer' } },
+                    { name: 'eager', in: 'query', schema: { type: 'boolean' } }
+                ],
                 responses: {
                     200: { description: 'OK', content: { 'application/json': { schema: { $ref: `#/components/schemas/${capitalized}` } } } }
                 }
@@ -88,7 +114,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             put: {
                 tags: [capitalized],
                 summary: `Update ${capitalized}`,
-                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
+                parameters: [...commonHeaders, { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
                 responses: {
                     200: { description: 'Updated', content: { 'application/json': { schema: { $ref: `#/components/schemas/${capitalized}` } } } }
                 }
@@ -96,32 +122,105 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             delete: {
                 tags: [capitalized],
                 summary: `Delete ${capitalized}`,
-                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
+                parameters: [...commonHeaders, { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
                 responses: {
                     204: { description: 'No Content' }
                 }
             }
         };
+
+        // BULK Operations /entities/bulk
+        swagger.paths[`/${name}s/bulk`] = {
+            post: {
+                tags: [capitalized],
+                summary: `Bulk Create ${capitalized}s`,
+                parameters: [...commonHeaders],
+                requestBody: {
+                    required: true,
+                    content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } }
+                },
+                responses: {
+                    201: { description: 'Created', content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } } }
+                }
+            },
+            put: {
+                tags: [capitalized],
+                summary: `Bulk Update ${capitalized}s`,
+                parameters: [...commonHeaders],
+                requestBody: {
+                    required: true,
+                    content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } }
+                },
+                responses: {
+                    200: { description: 'Updated', content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } } }
+                }
+            },
+            patch: {
+                tags: [capitalized],
+                summary: `Bulk Patch ${capitalized}s`,
+                parameters: [...commonHeaders],
+                requestBody: {
+                    required: true,
+                    content: { 
+                        'application/json': { 
+                            schema: { 
+                                type: 'array', 
+                                items: { 
+                                    type: 'object',
+                                    properties: {
+                                        id: { type: 'integer' },
+                                        changes: { type: 'object' }
+                                    }
+                                } 
+                            } 
+                        } 
+                    }
+                },
+                responses: {
+                    200: { description: 'Patched' }
+                }
+            }
+        };
     }
 
     // 2. Add System Paths
     swagger.paths['/rpc/{table}'] = {
         get: {
-            tags: ['Search'],
-            summary: 'Generic PostgREST-like Search',
+            tags: ['Search Engine'],
+            summary: 'Generic PostgREST RPC Engine',
+            description: `Powerful dynamic querying system. 
+            
+            ### Dynamic Filtering
+            Append any column name as a query parameter using operator notation:
+            - \`?age=gt.20\` (Greater Than)
+            - \`?name=ilike.John\` (Case-insensitive search)
+            - \`?id=in.1,2,3\` (Set containment)
+            
+            ### JSONB Path Querying
+            For JSON fields, use arrow notation:
+            - \`?metadata->>role=eq.ADMIN\` (Nested text extraction)
+            - \`?details->count=gt.5\` (Nested numeric extraction)`,
             parameters: [
-                { name: 'table', in: 'path', required: true, schema: { type: 'string' } },
-                { name: 'order', in: 'query', schema: { type: 'string' } },
-                { name: 'limit', in: 'query', schema: { type: 'integer' } }
+                ...commonHeaders,
+                { name: 'table', in: 'path', required: true, schema: { type: 'string' }, description: 'The database table to query' },
+                { name: 'order', in: 'query', schema: { type: 'string' }, description: 'Sorting (e.g., id.desc)' },
+                { name: 'limit', in: 'query', schema: { type: 'integer' }, description: 'Row limit' },
+                { name: 'offset', in: 'query', schema: { type: 'integer' }, description: 'Query offset' }
             ],
-            responses: { 200: { description: 'OK' } }
+            responses: { 
+                200: { 
+                    description: 'OK', 
+                    content: { 'application/json': { schema: { type: 'array', items: { type: 'object' } } } } 
+                } 
+            }
         }
     };
 
     swagger.paths['/audit'] = {
         get: {
-            tags: ['Audit'],
-            summary: 'View Audit Logs',
+            tags: ['Observability'],
+            summary: 'Fetch Audit Trail',
+            parameters: [...commonHeaders],
             responses: { 200: { description: 'OK' } }
         }
     };
@@ -139,7 +238,10 @@ const mapToSwaggerType = (type) => {
         'Long': 'integer',
         'BigDecimal': 'number',
         'LocalDate': 'string',
-        'Instant': 'string'
+        'Instant': 'string',
+        'JSON': 'object',
+        'JSONB': 'object',
+        'Text': 'string'
     };
     return types[type] || 'string';
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-duck-cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "go function generator",
   "main": "index.js",
   "type": "module",

package/templates/docs/pages/multitenancy.hbs

@@ -0,0 +1,83 @@
+<div class="mb-10 text-center lg:text-left border-b border-slate-200 pb-8">
+    <div class="inline-flex items-center px-3 py-1 rounded-full bg-blue-100 text-blue-700 text-xs font-semibold tracking-wide uppercase mb-4">
+        Enterprise Architecture
+    </div>
+    <h1 class="text-4xl lg:text-5xl font-extrabold text-slate-900 tracking-tight leading-tight mb-4">Dynamic Multi-Tenancy</h1>
+    <p class="text-lg lg:text-xl text-slate-600 max-w-2xl leading-relaxed">Secure, high-performance database-per-tenant isolation with real-time connection hot-swapping.</p>
+</div>
+
+<section class="mb-12">
+    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
+        <span class="w-8 h-8 rounded-lg bg-blue-100 text-blue-600 flex items-center justify-center mr-3 text-sm">
+            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10"></path></svg>
+        </span>
+        The Dual-DB Architecture
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">GO-DUCK separates management logic from customer data. Your application maintains a persistent connection to a <strong>Master Database</strong> while dynamically "Relocating" per-request traffic to isolated <strong>Tenant Databases</strong>.</p>
+
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-8 mb-8">
+        <div class="p-6 rounded-2xl border border-slate-200 bg-white shadow-sm">
+            <div class="w-12 h-12 bg-indigo-100 rounded-xl flex items-center justify-center mb-4">
+                <svg class="w-6 h-6 text-indigo-600" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"></path></svg>
+            </div>
+            <h3 class="text-xl font-bold text-slate-900 mb-2">Master Registry</h3>
+            <p class="text-slate-600 text-sm leading-relaxed">The <code>tenant_roles</code> table in the Master DB acts as the "Grand Concierge," mapping authenticated user roles to physical database names at runtime.</p>
+        </div>
+        <div class="p-6 rounded-2xl border border-slate-200 bg-white shadow-sm">
+            <div class="w-12 h-12 bg-emerald-100 rounded-xl flex items-center justify-center mb-4">
+                <svg class="w-6 h-6 text-emerald-600" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
+            </div>
+            <h3 class="text-xl font-bold text-slate-900 mb-2">Hot-Swapping Pools</h3>
+            <p class="text-slate-600 text-sm leading-relaxed">The <code>TenantDBManager</code> uses lazy loading to open and cache connection pools for tenants only when they are active, ensuring minimal resource overhead.</p>
+        </div>
+    </div>
+</section>
+
+<section class="mb-12">
+    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
+        <span class="w-8 h-8 rounded-lg bg-rose-100 text-rose-600 flex items-center justify-center mr-3 text-sm">
+            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 00-2 2zm10-10V7a4 4 0 00-8 0v4h8z"></path></svg>
+        </span>
+        Security & Anti-Spoofing
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">Header-based tenancy (<code>X-Tenant-ID</code>) is convenient but dangerous. GO-DUCK solves this by cryptographically validating the tenant context against the JWT.</p>
+    
+    <div class="bg-slate-900 rounded-2xl p-6 shadow-xl mb-6">
+        <h4 class="text-emerald-400 font-mono text-sm mb-4">// Internal Verification Loop</h4>
+        <pre class="text-slate-300 font-mono text-sm leading-relaxed">
+1. Extract Roles from signed Keycloak JWT
+2. Lookup authorized DB in Master mapping table
+3. Compare against X-Tenant-ID header
+4. If Mismatch: Return 403 Forbidden (Security Breach)
+5. If Match: Activate Dynamic Connection Pool
+        </pre>
+    </div>
+</section>
+
+<section class="mb-12">
+    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
+        <span class="w-8 h-8 rounded-lg bg-amber-100 text-amber-600 flex items-center justify-center mr-3 text-sm">
+            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6V4m0 2a2 2 0 100 4m0-4a2 2 0 110 4m-6 8a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4m6 6v10m6-2a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4"></path></svg>
+        </span>
+        Tenant Provisioning API
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">Adding a new customer is a single atomic operation. Use the management API to provision a side-by-side database instantly.</p>
+
+    <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg mb-4">
+        <div class="bg-[#2d2d2d] px-4 py-2 border-b border-[#404040] flex items-center">
+            <span class="px-2 py-0.5 rounded bg-emerald-500/20 text-emerald-400 text-[10px] font-bold mr-3">POST</span>
+            <span class="text-xs text-slate-300 font-mono">/management/db/create</span>
+        </div>
+        <div class="p-5 text-sm font-mono text-slate-300">
+            {
+                "role": "ROLE_ACME_CORP",
+                "db_name": "acme_isolated_db"
+            }
+        </div>
+    </div>
+    <ul class="space-y-3 text-slate-600 text-sm">
+        <li class="flex items-center"><svg class="w-4 h-4 text-emerald-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path></svg> Executing physical <code>CREATE DATABASE</code></li>
+        <li class="flex items-center"><svg class="w-4 h-4 text-emerald-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path></svg> Mapping role to DB in <code>tenant_roles</code> Master table</li>
+        <li class="flex items-center"><svg class="w-4 h-4 text-emerald-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path></svg> Triggering automated Liquibase migrations on new DB</li>
+    </ul>
+</section>

package/templates/docs/pages/rest.hbs

@@ -124,6 +124,84 @@
             </div>
         </div>
     </div>
+
+    <!-- JSON Querying Section -->
+    <div class="bg-white border border-slate-200 rounded-2xl p-8 shadow-sm">
+        <h4 class="text-xl font-bold text-slate-900 mb-4 flex items-center">
+            <svg class="w-6 h-6 mr-3 text-indigo-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4"></path></svg>
+            Deep JSON/JSONB Querying
+        </h4>
+        <p class="text-slate-600 text-sm mb-6 leading-relaxed">
+            The GO-DUCK generator natively supports PostgreSQL JSONB operators. You can drill down into nested fields directly from the URL using arrow notation.
+        </p>
+        
+        <div class="space-y-4">
+            <div class="bg-slate-50 p-5 rounded-xl border border-slate-100">
+                <div class="flex items-center justify-between mb-2">
+                    <span class="text-xs font-bold text-indigo-600 uppercase tracking-widest">Text Extraction (->>)</span>
+                    <span class="px-2 py-0.5 rounded bg-indigo-100 text-indigo-700 text-[10px] font-bold">Standard Use</span>
+                </div>
+                <code class="text-xs text-slate-800">GET /api/rpc/users?metadata->>role=eq.ADMIN</code>
+                <p class="text-[11px] text-slate-500 mt-2">Extracts the value as text. Perfect for equality checks on nested strings.</p>
+            </div>
+
+            <div class="bg-slate-50 p-5 rounded-xl border border-slate-100">
+                <div class="flex items-center justify-between mb-2">
+                    <span class="text-xs font-bold text-purple-600 uppercase tracking-widest">Object Extraction (->)</span>
+                </div>
+                <code class="text-xs text-slate-800">GET /api/rpc/orders?details->itemsCount=gt.5</code>
+                <p class="text-[11px] text-slate-500 mt-2">Treats the extracted value as a JSON object/numeric, allowing for range checks on nested numbers.</p>
+            </div>
+        </div>
+
+        <div class="mt-6 p-4 bg-amber-50 rounded-xl border border-amber-100">
+            <p class="text-[11px] text-amber-800 leading-relaxed">
+                <strong>Pro Tip:</strong> For high-performance JSON querying, ensure you have a <code>GIN</code> index on the JSONB column in your database.
+            </p>
+        </div>
+    </div>
+</section>
+
+<section class="mb-12">
+    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
+        <span class="w-8 h-8 rounded-lg bg-orange-100 text-orange-600 flex items-center justify-center mr-3 text-sm">
+            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
+        </span>
+        Bulk Mission Control (High Velocity)
+    </h2>
+    <p class="text-slate-600 text-sm mb-6 leading-relaxed">
+        For batch processing and migrations, avoid the overhead of multiple HTTP calls. Use the specialized <code class="bg-orange-50 px-1 rounded text-orange-700">/bulk</code> endpoints to process hundreds of records in a single transaction.
+    </p>
+
+    <div class="space-y-6">
+        <!-- Bulk Create -->
+        <div class="bg-white border border-slate-200 rounded-2xl overflow-hidden">
+            <div class="bg-slate-50 px-6 py-3 border-b border-slate-200 flex items-center justify-between">
+                <span class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Bulk Create Transaction</span>
+                <span class="px-2 py-0.5 rounded bg-emerald-100 text-emerald-700 text-[10px] font-bold">POST /api/:entities/bulk</span>
+            </div>
+            <div class="p-6">
+                <pre class="bg-slate-900 rounded-xl p-4 text-xs text-slate-300 font-mono">[
+  { "title": "Bulk Article A", "status": "DRAFT" },
+  { "title": "Bulk Article B", "status": "PUBLISHED" }
+]</pre>
+            </div>
+        </div>
+
+        <!-- Bulk Patch -->
+        <div class="bg-white border border-slate-200 rounded-2xl overflow-hidden">
+            <div class="bg-slate-50 px-6 py-3 border-b border-slate-200 flex items-center justify-between">
+                <span class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Multi-Entity Patch</span>
+                <span class="px-2 py-0.5 rounded bg-blue-100 text-blue-700 text-[10px] font-bold">PATCH /api/:entities/bulk</span>
+            </div>
+            <div class="p-6">
+                <pre class="bg-slate-900 rounded-xl p-4 text-xs text-slate-300 font-mono">[
+  { "id": 1, "changes": { "status": "ARCHIVED" } },
+  { "id": 2, "changes": { "title": "Updated Title via Bulk" } }
+]</pre>
+            </div>
+        </div>
+    </div>
 </section>
 
 <section class="mb-12">

package/templates/docs/pages/security.hbs

@@ -9,7 +9,27 @@
         <p class="text-indigo-900"><strong>Golden Rule:</strong> In <code>application-dev.yml</code>, ensure your Keycloak Realm, ClientID, and Secret are accurately synced with the local running Docker Keycloak image.</p>
     </div>
 
-    <h3 class="font-semibold mb-2 mt-6">2. Burst Protection (Rate Limiting)</h3>
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">2. Tenant Context Integrity</h2>
+    <p class="mb-4">
+        GO-DUCK implements <strong>Enterprise-Grade Data Isolation</strong>. While the <code>X-Tenant-ID</code> header is required for request context, the system is immune to "Tenant Spoofing" attacks.
+    </p>
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-6 mb-6">
+        <div class="bg-slate-50 p-5 rounded-xl border border-slate-200">
+            <h4 class="font-bold text-slate-900 mb-2">Internal Cross-Verification</h4>
+            <p class="text-xs text-slate-600 leading-relaxed">
+                The <code>TenantMiddleware</code> extracts authorized roles from the signed JWT and performs a server-side lookup of the valid DB context. It then <strong>cross-checks</strong> this against the <code>X-Tenant-ID</code> header.
+            </p>
+        </div>
+        <div class="bg-rose-50 p-5 rounded-xl border border-rose-200">
+            <h4 class="font-bold text-rose-900 mb-2">Spoof Protection</h4>
+            <p class="text-xs text-rose-700 leading-relaxed">
+                If a user attempts to access <code>Tenant-B</code> by modifying headers while their JWT is only valid for <code>Tenant-A</code>, the request is immediately aborted with a <code>403 Forbidden - Security Breach</code> error. 
+                <a href="multitenancy.html" class="text-rose-600 font-bold hover:underline mt-2 inline-block">Learn more about isolation &rarr;</a>
+            </p>
+        </div>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6">3. Burst Protection (Rate Limiting)</h3>
     <p class="mb-4">Using the standard <code>x/time/rate</code> package, a Token Bucket rate limiter is attached to the Gin Engine globally to mitigate DDOS vectors and abusive scripting.</p>
     <pre><code class="language-yaml"># Inside your application-prod.yml
 go-duck:

package/templates/go/controller.go.hbs

@@ -21,20 +21,20 @@ Config *config.Config
 }
 
 // Create{{capitalize name}}
-func (ctrl *{{capitalize name}}Controller) Create(c *gin.Context) {
-tenant, _ := c.Get("tenantDB")
-tenantStr := fmt.Sprintf("%v", tenant)
-ctx := c.Request.Context()
-
-var entity models.{{capitalize name}}
-if err := c.ShouldBindJSON(&entity); err != nil {
-c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
-return
-}
-if err := ctrl.DB.WithContext(ctx).Create(&entity).Error; err != nil {
-c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-return
-}
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
+
+	var entity models.{{capitalize name}}
+	if err := c.ShouldBindJSON(&entity); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := db.WithContext(ctx).Create(&entity).Error; err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
 
 // Dynamic Cache Invalidation (Tenant Aware)
 cache.ClearPattern(tenantStr + ":{{capitalize name}}*")
@@ -50,9 +50,13 @@ c.JSON(http.StatusCreated, entity)
 
 // GetAll{{capitalize name}}s (with filtering, pagination, and lazy/eager loading)
 func (ctrl *{{capitalize name}}Controller) GetAll(c *gin.Context) {
-var entities []models.{{capitalize name}}
-ctx := c.Request.Context()
-query := ctrl.DB.WithContext(ctx)
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
+	var entities []models.{{capitalize name}}
+	ctx := c.Request.Context()
+	query := db.WithContext(ctx)
 
 // 1. Pagination
 page, _ := strconv.Atoi(c.DefaultQuery("page", "0"))
@@ -104,8 +108,12 @@ c.JSON(http.StatusOK, entity)
 return
 }
 
-// 2. Fallback to DB (With Context for Tracing)
-query := ctrl.DB.WithContext(ctx)
+	// 2. Fallback to DB (With Context for Tracing)
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
+	query := db.WithContext(ctx)
 if c.Query("eager") == "true" {
 {{#each relationships}}
 query = query.Preload("{{capitalize from.field}}")
@@ -128,14 +136,13 @@ c.JSON(http.StatusOK, entity)
 }
 
 // Update (PUT) - Full Update
-func (ctrl *{{capitalize name}}Controller) Update(c *gin.Context) {
-id := c.Param("id")
-tenant, _ := c.Get("tenantDB")
-tenantStr := fmt.Sprintf("%v", tenant)
-ctx := c.Request.Context()
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
 
-var entity models.{{capitalize name}}
-if err := ctrl.DB.WithContext(ctx).First(&entity, id).Error; err != nil {
+	var entity models.{{capitalize name}}
+	if err := db.WithContext(ctx).First(&entity, id).Error; err != nil {
 c.JSON(http.StatusNotFound, gin.H{"error": "Resource not found"})
 return
 }
@@ -148,7 +155,7 @@ c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 return
 }
 
-if err := ctrl.DB.WithContext(ctx).Save(&entity).Error; err != nil {
+	if err := db.WithContext(ctx).Save(&entity).Error; err != nil {
 c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 return
 }
@@ -166,14 +173,13 @@ c.JSON(http.StatusOK, entity)
 }
 
 // Patch (PATCH) - Partial Update
-func (ctrl *{{capitalize name}}Controller) Patch(c *gin.Context) {
-id := c.Param("id")
-tenant, _ := c.Get("tenantDB")
-tenantStr := fmt.Sprintf("%v", tenant)
-ctx := c.Request.Context()
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
 
-var entity models.{{capitalize name}}
-if err := ctrl.DB.WithContext(ctx).First(&entity, id).Error; err != nil {
+	var entity models.{{capitalize name}}
+	if err := db.WithContext(ctx).First(&entity, id).Error; err != nil {
 c.JSON(http.StatusNotFound, gin.H{"error": "Resource not found"})
 return
 }
@@ -185,13 +191,13 @@ c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 return
 }
 
-if err := ctrl.DB.WithContext(ctx).Model(&entity).Updates(updates).Error; err != nil {
+if err := db.WithContext(ctx).Model(&entity).Updates(updates).Error; err != nil {
 c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 return
 }
 
 // Fetch updated
-ctrl.DB.WithContext(ctx).First(&entity, id)
+db.WithContext(ctx).First(&entity, id)
 
 // Cache Invalidation (Tenant Aware)
 cache.Delete(fmt.Sprintf("%s:{{capitalize name}}:%s", tenantStr, id))
@@ -205,20 +211,117 @@ return nil, nil
 c.JSON(http.StatusOK, gin.H{"message": "Updated successfully", "data": entity})
 }
 
+// BulkCreate handles creating multiple entities in one transaction
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
+
+	var entities []models.{{capitalize name}}
+	if err := c.ShouldBindJSON(&entities); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := db.WithContext(ctx).Create(&entities).Error; err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Dynamic Cache Invalidation (Tenant Aware)
+	cache.ClearPattern(tenantStr + ":{{capitalize name}}*")
+
+	// MQTT Event (Resilient)
+	resilience.Execute(func() (interface{}, error) {
+		messaging.PublishEvent(ctrl.Config.GoDuck.Messaging.MQTT.TopicPrefix, "BULK_CREATE", "{{capitalize name}}", entities, nil)
+		return nil, nil
+	})
+
+	c.JSON(http.StatusCreated, entities)
+}
+
+// BulkUpdate handles updating multiple entities in one transaction
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
+
+	var entities []models.{{capitalize name}}
+	if err := c.ShouldBindJSON(&entities); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		for _, e := range entities {
+			if err := tx.Save(&e).Error; err != nil {
+				return err
+			}
+			cache.Delete(fmt.Sprintf("%s:{{capitalize name}}:%d", tenantStr, e.ID))
+		}
+		return nil
+	})
+
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// MQTT Event (Resilient)
+	resilience.Execute(func() (interface{}, error) {
+		messaging.PublishEvent(ctrl.Config.GoDuck.Messaging.MQTT.TopicPrefix, "BULK_UPDATE", "{{capitalize name}}", entities, nil)
+		return nil, nil
+	})
+
+	c.JSON(http.StatusOK, entities)
+}
+
+// BulkPatch handles partial updates for multiple entities
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
+
+	var updates []struct {
+		ID      uint                   `json:"id"`
+		Changes map[string]interface{} `json:"changes"`
+	}
+	if err := c.ShouldBindJSON(&updates); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		for _, u := range updates {
+			if err := tx.Model(&models.{{capitalize name}}{}).Where("id = ?", u.ID).Updates(u.Changes).Error; err != nil {
+				return err
+			}
+			cache.Delete(fmt.Sprintf("%s:{{capitalize name}}:%d", tenantStr, u.ID))
+		}
+		return nil
+	})
+
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "Bulk patch completed successfully"})
+}
+
 // Delete
-func (ctrl *{{capitalize name}}Controller) Delete(c *gin.Context) {
-id := c.Param("id")
-tenant, _ := c.Get("tenantDB")
-tenantStr := fmt.Sprintf("%v", tenant)
-ctx := c.Request.Context()
+	db := ctrl.DB
+	if tdb, exists := c.Get("tenantDBConn"); exists {
+		db = tdb.(*gorm.DB)
+	}
 
-var entity models.{{capitalize name}}
-if err := ctrl.DB.WithContext(ctx).First(&entity, id).Error; err != nil {
+	var entity models.{{capitalize name}}
+	if err := db.WithContext(ctx).First(&entity, id).Error; err != nil {
 c.JSON(http.StatusNotFound, gin.H{"error": "Resource not found"})
 return
 }
 
-if err := ctrl.DB.WithContext(ctx).Delete(&entity).Error; err != nil {
+	if err := db.WithContext(ctx).Delete(&entity).Error; err != nil {
 c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 return
 }

package/templates/go/main.go.hbs

@@ -143,7 +143,7 @@ mgmt.POST("/db/create", management.CreateDatabaseAndMigrate(masterDB))
 // 9. Secured Application APIs
 api := r.Group("/api")
 api.Use(middleware.JWTMiddleware())
-api.Use(middleware.TenantMiddleware(masterDB))
+api.Use(middleware.TenantMiddleware(masterDB, appConfig))
 api.Use(middleware.AuditMiddleware(masterDB))
 api.Use(middleware.MeteringMiddleware(masterDB))
 {
@@ -163,10 +163,13 @@ api.GET("/rpc/:table", searchCtrl.GenericSearch)
 // {{name}} Routes
 {{toLowerCase name}}Ctrl := controllers.{{capitalize name}}Controller{DB: masterDB, Config: appConfig}
 api.POST("/{{toLowerCase name}}s", {{toLowerCase name}}Ctrl.Create)
+api.POST("/{{toLowerCase name}}s/bulk", {{toLowerCase name}}Ctrl.BulkCreate)
 api.GET("/{{toLowerCase name}}s", {{toLowerCase name}}Ctrl.GetAll)
 api.GET("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.GetByID)
 api.PUT("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.Update)
+api.PUT("/{{toLowerCase name}}s/bulk", {{toLowerCase name}}Ctrl.BulkUpdate)
 api.PATCH("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.Patch)
+api.PATCH("/{{toLowerCase name}}s/bulk", {{toLowerCase name}}Ctrl.BulkPatch)
 api.DELETE("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.Delete)
 {{/each}}
 // go-duck-needle-add-route