@aetherframework/middleware 1.0.2

package/examples/advanced-router-demo.js

@@ -0,0 +1,119 @@
+// examples/advanced-router-demo.js
+import { AetherPipeline, middleware } from '../index.js';
+import http from "http"; 
+
+const app = new AetherPipeline();
+const router = new middleware.router.Router();
+
+// Use global middlewares
+app.use(middleware.cors());
+app.use(middleware.security());
+app.use(middleware.bodyParser());
+app.use(middleware.json());
+app.use(middleware.params()); // Add parameter parsing middleware
+
+// ========== ROUTE WITH VALIDATION ==========
+const userValidation = {
+  name: { 
+    type: "string", 
+    required: true, 
+    minLength: 2, 
+    maxLength: 50 
+  },
+  email: { 
+    type: "string", 
+    required: true, 
+    pattern: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$" 
+  },
+  age: { 
+    type: "number", 
+    min: 18, 
+    max: 100 
+  },
+  tags: { 
+    type: "array" 
+  }
+};
+
+router.post("/api/users", (ctx) => {
+  // Parameters are already validated and parsed
+  const { name, email, age, tags } = ctx.allParams;
+  
+  ctx.json({ 
+    success: true,
+    data: { 
+      name, 
+      email, 
+      age, 
+      tags,
+      id: Date.now()
+    }
+  });
+});
+
+// Add validation rules to route
+router.routes.get("POST:/api/users").validationRules = userValidation;
+
+// ========== COMPLEX ROUTE EXAMPLE ==========
+router.group("/api/v1", (v1) => {
+  v1.use(middleware.jwt()); // JWT auth for all v1 routes
+  
+  v1.group("/admin", (admin) => {
+    admin.get("/dashboard", (ctx) => {
+      const user = ctx.getState("user");
+      ctx.json({ 
+        admin: true, 
+        user,
+        timestamp: new Date().toISOString()
+      });
+    });
+    
+    admin.get("/users", (ctx) => {
+      const { page = 1, limit = 20, sort = "desc" } = ctx.query;
+      ctx.json({ 
+        page: parseInt(page),
+        limit: parseInt(limit),
+        sort,
+        users: []
+      });
+    });
+  });
+  
+  // 修复：将 'public' 改为非保留字名称
+  v1.group("/public", (publicGroup) => {
+    publicGroup.get("/products", (ctx) => {
+      const { category, minPrice, maxPrice } = ctx.query;
+      ctx.json({ 
+        category,
+        minPrice: minPrice ? parseFloat(minPrice) : null,
+        maxPrice: maxPrice ? parseFloat(maxPrice) : null,
+        products: []
+      });
+    });
+  });
+});
+
+// Add router to pipeline
+app.use(router.middleware());
+
+// ========== 404 HANDLER ==========
+app.use(async (ctx) => {
+  if (!ctx.isTerminated()) {
+    ctx.setStatus(404).json({
+      error: "Not Found",
+      message: `Cannot ${ctx.method} ${ctx.url}`,
+      timestamp: new Date().toISOString()
+    });
+  }
+});
+
+// Start server using http.createServer
+const server = http.createServer(async (req, res) => {
+  await app.handle(req, res);
+});
+
+server.listen(3000, () => {
+  console.log("🚀 Advanced AetherJS Server running on http://localhost:3000");
+  console.log("📋 Registered routes:");
+  console.log(router.getRoutes());
+});

package/examples/advanced-server.js

@@ -0,0 +1,272 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present, AetherFramework Contributors.
+ * Response compression middleware for AetherFramework framework.
+ * Supports gzip, deflate, and brotli compression with zero-copy operations.
+ */
+
+import http from "http";
+import { AetherPipeline } from "../index.js";
+
+// Import optimized middleware
+import security from "../src/middleware/security.js";
+import rateLimit from "../src/middleware/rate-limit.js";
+import cors from "../src/middleware/cors.js";
+import jwt from "../src/middleware/jwt.js";
+import bodyParser from "../src/middleware/body-parser.js";
+import compression from "../src/middleware/compression.js";
+import SessionManager from "../src/middleware/session.js";
+
+// Load configuration
+const config = {
+  jwtSecret: process.env.JWT_SECRET || "dev-secret",
+  port: process.env.PORT || 3001,
+  sessionSecret: process.env.SESSION_SECRET || "aether-session-secret",
+};
+
+// Initialize Aether pipeline
+const pipeline = new AetherPipeline();
+
+// ==========================================================
+// Middleware adapter: Convert standard (ctx, next) middleware to AetherPipeline (ctx, signal) format
+// ==========================================================
+function adaptMiddleware(standardMiddleware) {
+  return async function adaptedMiddleware(ctx, signal) {
+    // Define a standard next function that calls signal.next()
+    const next = async () => {
+      if (signal && typeof signal.next === "function") {
+        return await signal.next();
+      }
+    };
+
+    // Call the original middleware with ctx and the new next function
+    // Note: Some middleware may not return a Promise, so use await to ensure execution completes
+    try {
+      const result = standardMiddleware(ctx, next);
+      if (result && typeof result.then === "function") {
+        await result;
+      }
+    } catch (error) {
+      console.error("Middleware error:", error);
+      // Optionally handle errors here or let the global error handler catch them
+    }
+  };
+}
+
+// ==========================================================
+// Pre-initialize all middleware (never create in request callbacks)
+// ==========================================================
+const securityMiddleware = security({
+  hsts: { enabled: true, maxAge: 31536000 },
+  noSniff: { enabled: true },
+  frameguard: { enabled: true, action: "DENY" },
+});
+
+const corsMiddleware = cors({
+  origin: "*",
+  credentials: true,
+});
+
+const compressionMiddleware = compression({
+  enabled: process.env.COMPRESSION_ENABLED === "true",
+  threshold: parseInt(process.env.COMPRESSION_THRESHOLD) || 1024,
+  gzip: process.env.COMPRESSION_GZIP !== "false",
+  deflate: process.env.COMPRESSION_DEFLATE === "true",
+  brotli: process.env.COMPRESSION_BROTLI === "true",
+  types: "application/json,text/plain",
+});
+
+const sessionManager = new SessionManager({
+  enabled: true,
+  secret: config.sessionSecret,
+  maxAge: parseInt(process.env.SESSION_MAX_AGE) || 86400000,
+  cookieName: "aether_session",
+  store: "memory",
+});
+const sessionMiddleware = sessionManager.middleware();
+
+const rateLimitMiddleware = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  enabled: true,
+});
+
+const bodyParserMiddleware = bodyParser({
+  json: { enabled: true, limit: "1mb" },
+});
+
+const jwtMiddlewareInstance = jwt({
+  secret: config.jwtSecret,
+  algorithms: ["HS256"],
+});
+
+// ==========================================================
+// Mount middleware pipeline (explicitly pass control to next)
+// ==========================================================
+
+// 1. Security Headers
+pipeline.use(securityMiddleware);
+
+// 2. CORS
+pipeline.use(corsMiddleware);
+
+// 3. Response Compression
+pipeline.use(compressionMiddleware);
+
+// 4. Session Management
+pipeline.use(sessionMiddleware);
+
+// 5. Rate Limiting
+pipeline.use(rateLimitMiddleware);
+
+// 6. Body Parsing
+pipeline.use(bodyParserMiddleware);
+
+// 7. Public Routes
+pipeline.use((ctx, next) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+  if (ctx.url === "/public/info") {
+    ctx.setStatus(200);
+    ctx.json({ message: "This is public information" });
+    if (typeof ctx.terminate === "function") ctx.terminate();
+    return; // Endpoint reached, do not call next()
+  }
+  return next(); // Route not matched, must pass control
+});
+
+// 8. Session Example Route
+pipeline.use((ctx, next) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+
+  if (ctx.url === "/session/example") {
+    const visitCount = ctx.session?.get("visitCount") || 0;
+    ctx.session?.set("visitCount", visitCount + 1);
+    ctx.session?.set("lastVisit", new Date().toISOString());
+
+    ctx.setStatus(200);
+    ctx.json({
+      message: "Session example",
+      sessionId: ctx.state?.session?.id,
+      visitCount: visitCount + 1,
+    });
+    if (typeof ctx.terminate === "function") ctx.terminate();
+    return;
+  }
+  return next(); // Pass control
+});
+
+// 9. Login Route
+pipeline.use((ctx, next) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+
+  if (ctx.url === "/api/login" && ctx.method === "POST") {
+    const { username, password } = ctx._request?.body || ctx.body || {};
+
+    if (username === "admin" && password === "password") {
+      ctx.session?.set("user", {
+        id: 1,
+        username,
+        role: "admin",
+        loggedIn: true,
+      });
+      ctx.session?.save();
+
+      ctx.setStatus(200);
+      ctx.json({ message: "Login successful" });
+    } else {
+      ctx.setStatus(401);
+      ctx.json({ error: "Invalid credentials" });
+    }
+    if (typeof ctx.terminate === "function") ctx.terminate();
+    return;
+  }
+  return next(); // Pass control
+});
+
+// 10. Logout Route
+pipeline.use((ctx, next) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+
+  if (ctx.url === "/api/logout" && ctx.method === "POST") {
+    ctx.session?.destroy();
+    ctx.setStatus(200);
+    ctx.json({ message: "Logged out successfully" });
+    if (typeof ctx.terminate === "function") ctx.terminate();
+    return;
+  }
+  return next(); // Pass control
+});
+
+// 11. JWT Protection for /api/* routes
+pipeline.use(async (ctx, next) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+  if (ctx.url.startsWith("/api/")) {
+    // Standard parameter passing: pass Aether's next-level async dispatch pointer
+    await jwtMiddlewareInstance(ctx, next);
+  } else {
+    return next(); // Skip non-/api/ routes directly
+  }
+});
+
+// 12. Profile Route
+pipeline.use((ctx, next) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+  if (ctx.url === "/api/profile" && ctx.method === "GET") {
+    ctx.setStatus(200);
+    ctx.json({
+      user: { id: 1, name: "Mock User" },
+      message: "Access granted",
+    });
+    if (typeof ctx.terminate === "function") ctx.terminate();
+    return;
+  }
+  return next(); // Pass control
+});
+
+// 13. POST Example
+pipeline.use((ctx, next) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+
+  if (ctx.url === "/api/data" && ctx.method === "POST") {
+    const reqBody = ctx._request?.body || ctx.body;
+    ctx.setStatus(200);
+    ctx.json({
+      received: reqBody,
+      message: "Data created successfully",
+    });
+    if (typeof ctx.terminate === "function") ctx.terminate();
+    return;
+  }
+  return next(); // Pass control
+});
+
+// 14. Fallback 404
+pipeline.use((ctx) => {
+  if (ctx.isTerminated() || ctx.res?.writableEnded) return;
+  ctx.setStatus(404);
+  ctx.json({ error: "Route not found" });
+  if (typeof ctx.terminate === "function") ctx.terminate();
+});
+
+// 15. Precompile for optimization
+pipeline.precompile();
+
+// 16. Create HTTP server
+const server = http.createServer(async (req, res) => {
+  try {
+    await pipeline.handle(req, res);
+  } catch (err) {
+    console.error("Pipeline Error:", err);
+    if (!res.headersSent) {
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.end(JSON.stringify({ error: "Internal Server Error" }));
+    }
+  }
+});
+
+// Start server
+server.listen(config.port, () => {
+  console.log(`🔒 Advanced Server running on http://localhost:${config.port}`);
+});

package/examples/basic-server.js

@@ -0,0 +1,134 @@
+/**
+ * Simplified Advanced Server - Clean and Performant Edition
+ */
+import http from "http";
+import { AetherPipeline } from "../index.js";
+
+// 1. Create pipeline
+const pipeline = new AetherPipeline();
+
+// 2. Basic middleware: Logging
+const logger = (ctx) => {
+  console.log(`[${new Date().toISOString()}] ${ctx.method} ${ctx.url}`);
+};
+pipeline.use(logger);
+
+// 3. Basic middleware: CORS headers
+pipeline.use((ctx) => {
+  ctx.setHeader("Access-Control-Allow-Origin", "*");
+  ctx.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+  ctx.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+});
+
+// 4. Basic middleware: Security headers
+pipeline.use((ctx) => {
+  ctx.setHeader("X-Content-Type-Options", "nosniff");
+  ctx.setHeader("X-Frame-Options", "DENY");
+  ctx.setHeader("X-XSS-Protection", "1; mode=block");
+});
+
+// 5. Route handling
+pipeline.use((ctx) => {
+  if (ctx.url === "/health") {
+    ctx.setStatus(200);
+    ctx.setHeader("Content-Type", "application/json");
+    ctx.body = JSON.stringify({ 
+      status: "ok", 
+      timestamp: Date.now(),
+      server: "Simplified AetherJS"
+    });
+    ctx._isHandled = true;
+    return true;
+  }
+});
+
+pipeline.use((ctx) => {
+  if (ctx.url === "/public/info") {
+    ctx.setStatus(200);
+    ctx.setHeader("Content-Type", "application/json");
+    ctx.body = JSON.stringify({
+      message: "This is public information",
+      version: "1.0.0",
+      endpoints: ["/health", "/public/info", "/api/data"]
+    });
+    ctx._isHandled = true;
+    return true;
+  }
+});
+
+pipeline.use((ctx) => {
+  if (ctx.url === "/api/data" && ctx.method === "GET") {
+    ctx.setStatus(200);
+    ctx.setHeader("Content-Type", "application/json");
+    ctx.body = JSON.stringify({
+      data: [1, 2, 3, 4, 5],
+      message: "Sample API data",
+      timestamp: Date.now()
+    });
+    ctx._isHandled = true;
+    return true;
+  }
+});
+
+pipeline.use((ctx) => {
+  if (ctx.url === "/api/data" && ctx.method === "POST") {
+    // Simple POST request handling
+    let body = "";
+    ctx.req.on("data", chunk => {
+      body += chunk.toString();
+    });
+    ctx.req.on("end", () => {
+      ctx.setStatus(201);
+      ctx.setHeader("Content-Type", "application/json");
+      ctx.body = JSON.stringify({
+        received: body ? JSON.parse(body) : null,
+        message: "Data received successfully",
+        id: Date.now()
+      });
+    });
+    ctx._isHandled = true;
+    return true;
+  }
+});
+
+// 6. 404 handling
+pipeline.use((ctx) => {
+  if (ctx._isHandled || ctx.statusCode === 200 || ctx.res?.statusCode === 200) {
+    return;
+  }
+  ctx.setStatus(404);
+  ctx.setHeader("Content-Type", "application/json");
+  ctx.body = JSON.stringify({ 
+    error: "Not Found",
+    path: ctx.url,
+    method: ctx.method
+  });
+});
+
+// 7. Precompile for optimization
+pipeline.precompile();
+
+// 8. Create HTTP server
+const server = http.createServer(async (req, res) => {
+  try {
+    await pipeline.handle(req, res);
+  } catch (err) {
+    console.error("Pipeline Error:", err);
+    if (!res.headersSent) {
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ error: "Internal Server Error" }));
+    }
+  }
+});
+
+// 9. Start server
+const PORT = process.env.PORT || 3001;
+server.listen(PORT, () => {
+  console.log(`🚀 Simplified Advanced Server running on http://localhost:${PORT}`);
+  console.log(`📊 Available endpoints:`);
+  console.log(`   GET  /health        - Health check`);
+  console.log(`   GET  /public/info   - Public information`);
+  console.log(`   GET  /api/data      - Get sample data`);
+  console.log(`   POST /api/data      - Submit data`);
+});

package/examples/benchmark.js

@@ -0,0 +1,85 @@
+/**
+ * Simple Benchmark Script
+ * Compares raw HTTP vs Aether Pipeline overhead.
+ */
+import http from 'http';
+import { AetherPipeline, AetherContext } from '../index.js'; 
+import json from "../src/middleware/json.js";
+
+const ITERATIONS = 10000;
+
+// 1. Raw HTTP Server
+const rawServer = http.createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ status: 'ok' }));
+});
+
+// 2. Aether Server
+const pipeline = new AetherPipeline();
+pipeline.use(json());
+pipeline.use(async (ctx, signal) => {
+    ctx.body = { status: 'ok' };
+    await signal.next();
+});
+
+const aetherServer = http.createServer(async (req, res) => {
+
+    try {
+        if (!req || !res) {
+            console.error('ERROR: req or res is undefined');
+            res.writeHead(500);
+            res.end('Internal Server Error');
+            return;
+        }
+        
+        await pipeline.handle(req, res);
+    } catch (error) {
+        console.error('Pipeline execution error:', error);
+        if (!res.headersSent) {
+            res.writeHead(500);
+            res.end('Internal Server Error');
+        }
+    }
+});
+
+async function runBenchmark(server, name) {
+    return new Promise((resolve) => {
+        server.listen(0, () => {
+            const port = server.address().port;
+            const start = Date.now();
+            let completed = 0;
+
+            function makeRequest() {
+                http.get(`http://localhost:${port}/`, (res) => {
+                    res.resume();
+                    res.on('end', () => {
+                        completed++;
+                        if (completed < ITERATIONS) {
+                            makeRequest();
+                        } else {
+                            const duration = Date.now() - start;
+                            const rps = (ITERATIONS / duration) * 1000;
+                            console.log(`${name}: ${duration}ms for ${ITERATIONS} requests (${rps.toFixed(0)} req/sec)`);
+                            server.close(() => resolve());
+                        }
+                    });
+                }).on('error', (e) => {
+                    console.error(e);
+                    server.close(() => resolve());
+                });
+            }
+            
+            makeRequest();
+        });
+    });
+}
+
+async function main() {
+  
+    
+    await runBenchmark(rawServer, 'Raw HTTP');
+    await runBenchmark(aetherServer, 'Aether Pipeline');
+ 
+}
+
+main().catch(console.error);