aetherframework-middleware 1.0.0

package/.env.example

@@ -0,0 +1,88 @@
+# ============================================
+# AetherJS Framework Configuration
+# ============================================
+
+# Server Configuration
+PORT=3001
+
+# Security Configuration
+JWT_SECRET=your-super-secret-jwt-key-change-in-production
+SESSION_SECRET=your-super-secret-session-key-change-in-production
+
+# CORS Configuration
+CORS_ENABLED=true
+CORS_ORIGIN=*
+CORS_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
+CORS_ALLOWED_HEADERS=Content-Type,Authorization
+CORS_CREDENTIALS=true
+CORS_MAX_AGE=86400
+CORS_PREFLIGHT_CONTINUE=false
+CORS_OPTIONS_STATUS=204
+
+# Compression Configuration
+COMPRESSION_ENABLED=true
+COMPRESSION_THRESHOLD=1024
+COMPRESSION_LEVEL=6
+COMPRESSION_MEM_LEVEL=8
+COMPRESSION_STRATEGY=0
+COMPRESSION_CHUNK_SIZE=16384
+COMPRESSION_WINDOW_BITS=15
+COMPRESSION_GZIP=true
+COMPRESSION_DEFLATE=false
+COMPRESSION_BROTLI=false
+COMPRESSION_TYPES=application/json,text/plain,text/html,text/css,application/javascript
+
+# Session Configuration
+SESSION_ENABLED=true
+SESSION_MAX_AGE=86400000
+SESSION_COOKIE_NAME=aether_sid
+
+# Rate Limiting Configuration
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
+RATE_LIMIT_MAX_REQUESTS=100
+RATE_LIMIT_MESSAGE="Too many requests, please try again later."
+RATE_LIMIT_STATUS_CODE=429
+RATE_LIMIT_SKIP_SUCCESSFUL=false
+RATE_LIMIT_SKIP_FAILED=false
+
+# Security Headers Configuration
+SECURITY_HSTS_ENABLED=true
+SECURITY_HSTS_MAX_AGE=31536000
+SECURITY_NO_SNIFF=true
+SECURITY_XSS_FILTER=true
+SECURITY_FRAMEGUARD_ACTION=DENY
+SECURITY_HIDE_POWERED_BY=true
+SECURITY_REFERRER_POLICY=strict-origin-when-cross-origin
+
+# JWT Configuration
+JWT_ENABLED=true
+JWT_ALGORITHMS=HS256
+JWT_AUDIENCE=
+JWT_ISSUER=
+JWT_EXPIRES_IN=7d
+JWT_IGNORE_EXPIRATION=false
+JWT_CREDENTIALS_REQUIRED=true
+JWT_TOKEN_HEADER=authorization
+JWT_TOKEN_QUERY=token
+JWT_TOKEN_COOKIE=token
+
+# Body Parser Configuration
+BODY_ENABLE_JSON=true
+BODY_LIMIT_JSON=1mb
+JSON_STRICT=true
+JSON_REVIVER=
+
+BODY_ENABLE_URLENCODED=true
+BODY_LIMIT_URLENCODED=1mb
+
+BODY_ENABLE_TEXT=true
+BODY_LIMIT_TEXT=1mb
+
+BODY_ENABLE_RAW=true
+BODY_LIMIT_RAW=10mb
+
+# Development/Production Mode
+NODE_ENV=development
+DEBUG=false
+LOG_LEVEL=info

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aetherjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,578 @@
+
+AetherFramework Middleware
+
+
+📦 Installation
+
+Install AetherFramework Middleware via npm:
+
+```bash
+npm install aetherframework-middleware
+```
+
+🚀 Quick Start
+
+Basic Server Example
+
+```javascript
+import http from "http";
+import { AetherPipeline } from "aetherframework-middleware";
+
+// Create pipeline
+const pipeline = new AetherPipeline();
+
+// Add middleware
+pipeline.use((ctx) => {
+  ctx.setHeader("Content-Type", "application/json");
+});
+
+// Add routes
+pipeline.use((ctx) => {
+  if (ctx.url === "/health") {
+    ctx.setStatus(200);
+    ctx.body = JSON.stringify({ status: "ok" });
+    ctx._isHandled = true;
+    return true;
+  }
+});
+
+// 404 handler
+pipeline.use((ctx) => {
+  if (!ctx._isHandled) {
+    ctx.setStatus(404);
+    ctx.body = JSON.stringify({ error: "Not Found" });
+  }
+});
+
+// Precompile for performance
+pipeline.precompile();
+
+// Create server
+const server = http.createServer(async (req, res) => {
+  await pipeline.handle(req, res);
+});
+
+server.listen(3001, () => {
+  console.log("🚀 Server running on http://localhost:3001");
+});
+```
+
+📖 Documentation
+
+Core Concepts
+
+AetherPipeline
+The central routing and middleware system that handles request processing with intelligent caching and optimization.
+
+```javascript
+import { AetherPipeline } from "aetherframework-middleware";
+
+const pipeline = new AetherPipeline();
+
+// Add middleware
+pipeline.use(securityMiddleware);
+pipeline.use(corsMiddleware);
+pipeline.use(compressionMiddleware);
+
+// Add routes
+pipeline.use((ctx) => {
+  if (ctx.url === "/api/users") {
+    ctx.json({ users: [] });
+    return true;
+  }
+});
+
+// Compile for performance
+pipeline.precompile();
+```
+
+AetherContext
+The request context object with optimized header management and zero-allocation patterns.
+
+```javascript
+// Setting headers
+ctx.setHeader("Content-Type", "application/json");
+
+// Setting status
+ctx.setStatus(200);
+
+// JSON response
+ctx.json({ message: "Success" });
+
+// Raw response
+ctx.raw("Hello World");
+
+// Get request data
+const ip = ctx.ip;
+const query = ctx.query;
+const body = ctx.body;
+```
+
+Middleware System
+
+AetherJS includes a comprehensive set of built-in middleware:
+
+Security Middleware
+```javascript
+import { middleware } from "aetherframework-middleware";
+
+const securityMiddleware = middleware.security({
+  hsts: { enabled: true, maxAge: 31536000 },
+  noSniff: { enabled: true },
+  frameguard: { enabled: true, action: "DENY" },
+  hidePoweredBy: true,
+  referrerPolicy: { 
+    enabled: true, 
+    value: "strict-origin-when-cross-origin" 
+  },
+  permissionsPolicy: {
+    enabled: true,
+    directives: { camera: "()", microphone: "()", geolocation: "()" }
+  }
+});
+```
+
+CORS Middleware
+```javascript
+import { middleware } from "aetherframework-middleware";
+
+const corsMiddleware = middleware.cors({
+  origin: "*",
+  credentials: true,
+  methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+  allowedHeaders: ["Content-Type", "Authorization"],
+  maxAge: 86400
+});
+```
+
+Compression Middleware
+```javascript
+import { middleware } from "aetherframework-middleware";
+
+const compressionMiddleware = middleware.compression({
+  enabled: true,
+  threshold: 1024,
+  gzip: true,
+  deflate: false,
+  brotli: false,
+  types: "application/json,text/plain,text/html"
+});
+```
+
+Rate Limiting Middleware
+```javascript
+import { middleware } from "aetherframework-middleware";
+
+const rateLimitMiddleware = middleware.rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // Limit each IP to 100 requests per window
+  message: "Too many requests, please try again later.",
+  statusCode: 429
+});
+```
+
+JWT Middleware
+```javascript
+import { middleware } from "aetherframework-middleware";
+
+const jwtMiddleware = middleware.jwt({
+  secret: process.env.JWT_SECRET,
+  algorithms: ["HS256"],
+  credentialsRequired: true,
+  tokenHeader: "authorization"
+});
+```
+
+Session Middleware
+```javascript
+import { middleware } from "aetherframework-middleware";
+
+const sessionManager = new middleware.session({
+  enabled: true,
+  secret: process.env.SESSION_SECRET,
+  maxAge: 86400000, // 24 hours
+  cookieName: "aether_session",
+  store: "memory" // or custom store
+});
+const sessionMiddleware = sessionManager.middleware();
+```
+
+Body Parser Middleware
+```javascript
+import { middleware } from "aetherframework-middleware";
+
+const bodyParserMiddleware = middleware.bodyParser({
+  json: { enabled: true, limit: "1mb" },
+  urlencoded: { enabled: true, limit: "1mb" },
+  text: { enabled: true, limit: "1mb" },
+  raw: { enabled: true, limit: "10mb" }
+});
+```
+
+🔧 Advanced Server Example
+
+```javascript
+import http from "http";
+import { AetherPipeline, middleware } from "aetherframework-middleware";
+
+// Initialize pipeline
+const pipeline = new AetherPipeline();
+
+// Middleware configuration
+const securityMiddleware = middleware.security({
+  hsts: { enabled: true, maxAge: 31536000 },
+  noSniff: { enabled: true },
+  frameguard: { enabled: true, action: "DENY" }
+});
+
+const corsMiddleware = middleware.cors({
+  origin: "*",
+  credentials: true
+});
+
+const compressionMiddleware = middleware.compression({
+  enabled: process.env.COMPRESSION_ENABLED === "true",
+  threshold: parseInt(process.env.COMPRESSION_THRESHOLD) || 1024
+});
+
+const sessionManager = new middleware.session({
+  enabled: true,
+  secret: process.env.SESSION_SECRET,
+  maxAge: parseInt(process.env.SESSION_MAX_AGE) || 86400000
+});
+
+const rateLimitMiddleware = middleware.rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  enabled: true
+});
+
+const bodyParserMiddleware = middleware.bodyParser({
+  json: { enabled: true, limit: "1mb" }
+});
+
+const jwtMiddleware = middleware.jwt({
+  secret: process.env.JWT_SECRET,
+  algorithms: ["HS256"]
+});
+
+// Mount middleware
+pipeline.use(securityMiddleware);
+pipeline.use(corsMiddleware);
+pipeline.use(compressionMiddleware);
+pipeline.use(sessionManager.middleware());
+pipeline.use(rateLimitMiddleware);
+pipeline.use(bodyParserMiddleware);
+
+// Public routes
+pipeline.use((ctx, next) => {
+  if (ctx.url === "/public/info") {
+    ctx.setStatus(200);
+    ctx.json({ message: "Public information" });
+    return;
+  }
+  return next();
+});
+
+// Protected routes
+pipeline.use(async (ctx, next) => {
+  if (ctx.url.startsWith("/api/")) {
+    await jwtMiddleware(ctx, next);
+  } else {
+    return next();
+  }
+});
+
+pipeline.use((ctx) => {
+  if (ctx.url === "/api/profile" && ctx.method === "GET") {
+    ctx.setStatus(200);
+    ctx.json({ user: { id: 1, name: "John Doe" } });
+  }
+});
+
+// 404 handler
+pipeline.use((ctx) => {
+  ctx.setStatus(404);
+  ctx.json({ error: "Route not found" });
+});
+
+// Precompile for performance
+pipeline.precompile();
+
+// Create 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" }));
+    }
+  }
+});
+
+// Start server
+const PORT = process.env.PORT || 3001;
+server.listen(PORT, () => {
+  console.log(`🚀 AetherJS Server running on http://localhost:${PORT}`);
+});
+```
+
+⚡ Performance Optimization
+
+Object Pooling
+AetherJS uses object pooling to reuse context objects, reducing garbage collection pressure:
+
+```javascript
+// Object pool with 4096 pre-allocated contexts
+const CONTEXT_POOL = [];
+const CONTEXT_POOL_SIZE = 4096;
+
+// Context reuse
+_getContext(request, response) {
+  if (CONTEXT_POOL.length > 0) {
+    const context = CONTEXT_POOL.pop();
+    context._reset(request, response);
+    return context;
+  }
+  return new AetherContext(request, response);
+}
+```
+
+Header Buffer Optimization
+Pre-allocated global buffer for header operations:
+
+```javascript
+// Pre-allocated header buffer
+const GLOBAL_HEADER_BUFFER = new Array(64);
+
+// Fast header setting
+_finalize() {
+  let cursor = 2;
+  for (let i = 0; i < this._headersCount; i++) {
+    const key = this._headersKeys[i];
+    const val = this._headersObj[key];
+    if (val !== undefined) {
+      GLOBAL_HEADER_BUFFER[cursor++] = key;
+      GLOBAL_HEADER_BUFFER[cursor++] = val;
+    }
+  }
+}
+```
+
+Middleware Compilation
+AetherCompiler optimizes middleware chains at runtime:
+
+```javascript
+// Compile middleware chain for optimal execution
+compile() {
+  // Check if all middleware are synchronous
+  const isAllSync = middlewares.every((mw) => {
+    const str = mw.toString();
+    return !str.includes("async ") && 
+           !str.includes(".then") && 
+           !str.includes("await ");
+  });
+
+  // Fast path for synchronous chains
+  if (isAllSync) {
+    return function executePureSyncChain(context) {
+      for (let i = 0; i < len; i++) {
+        middlewares[i](context, null);
+        if (context.isTerminated()) return;
+      }
+      context._finalize();
+    };
+  }
+
+  // Async chain with optimized state machine
+  return function executeAsyncChain(context) {
+    // Async execution with minimal overhead
+  };
+}
+```
+
+🔧 Configuration
+
+Environment Variables
+Copy .env.example to .env and customize:
+
+```bash
+Server
+PORT=3001
+
+Security
+JWT_SECRET=your-secure-jwt-secret
+SESSION_SECRET=your-secure-session-secret
+
+CORS
+CORS_ENABLED=true
+CORS_ORIGIN=*
+CORS_CREDENTIALS=true
+
+Compression
+COMPRESSION_ENABLED=true
+COMPRESSION_THRESHOLD=1024
+COMPRESSION_GZIP=true
+
+Rate Limiting
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_MAX_REQUESTS=100
+RATE_LIMIT_WINDOW_MS=900000
+```
+
+Custom Configuration
+All middleware supports both environment variables and programmatic configuration:
+
+```javascript
+// Programmatic configuration
+const securityMiddleware = middleware.security({
+  hsts: { 
+    enabled: true, 
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: false
+  },
+  noSniff: { enabled: true },
+  frameguard: { enabled: true, action: "DENY" },
+  hidePoweredBy: true,
+  referrerPolicy: { 
+    enabled: true, 
+    value: "strict-origin-when-cross-origin" 
+  }
+});
+```
+
+📊 Benchmarking
+
+Running Benchmarks
+```bash
+Install autocannon
+npm install -g autocannon
+
+Run benchmark
+autocannon -c 100 -d 30 -p 10 http://localhost:3001/public/info
+```
+
+Expected Results
+- Throughput: 25,000+ requests per second
+- Latency: 3-7ms average, <50ms P99
+- Memory: <50MB under load
+- CPU: Efficient single-core utilization
+
+🛡️ Security Features
+
+Built-in Security Headers
+- Strict-Transport-Security: Enforces HTTPS
+- X-Content-Type-Options: Prevents MIME type sniffing
+- X-Frame-Options: Clickjacking protection
+- X-XSS-Protection: Cross-site scripting protection
+- Referrer-Policy: Controls referrer information
+- Permissions-Policy: Feature permission controls
+
+JWT Security
+- Synchronous verification for maximum performance
+- Multiple token extraction methods (header, query, cookie)
+- Configurable algorithms and validation options
+- Token refresh capabilities
+
+Rate Limiting
+- Memory-efficient LRU storage
+- Incremental cleanup to avoid blocking
+- Configurable windows and limits
+- Skip options for successful/failed requests
+
+🔌 Extending AetherJS
+
+Custom Middleware
+```javascript
+function customMiddleware(options = {}) {
+  return async function middleware(context, next) {
+    // Pre-processing
+    const startTime = Date.now();
+    
+    // Call next middleware
+    if (typeof next === "function") {
+      await next();
+    }
+    
+    // Post-processing
+    const duration = Date.now() - startTime;
+    context.setHeader("X-Response-Time", `${duration}ms`);
+  };
+}
+
+// Usage
+pipeline.use(customMiddleware());
+```
+
+Custom Stores
+```javascript
+class RedisStore {
+  constructor(redisClient) {
+    this.client = redisClient;
+  }
+  
+  async get(key) {
+    return await this.client.get(key);
+  }
+  
+  async set(key, value, ttl) {
+    await this.client.setex(key, Math.floor(ttl / 1000), value);
+  }
+  
+  async delete(key) {
+    await this.client.del(key);
+  }
+}
+
+// Usage with session manager
+const sessionManager = new middleware.session({
+  store: new RedisStore(redisClient),
+  // ... other options
+});
+```
+
+🏆 Our Advantages
+
+1. Unmatched Performance
+- 25,000+ QPS on a single core
+- Zero-allocation design minimizes GC pressure
+- Object pooling for context reuse
+- Pre-compiled middleware chains
+
+2. Memory Efficiency
+- Fixed-size object pools prevent memory fragmentation
+- LRU caching for intelligent resource management
+- Incremental cleanup avoids blocking operations
+
+3. Developer Experience
+- Familiar middleware pattern (Express/Koa-like)
+- Comprehensive built-in middleware
+- Environment-based configuration
+- Type-safe (with TypeScript definitions)
+
+4. Production Ready
+- Comprehensive security headers and protections
+- Built-in rate limiting with efficient storage
+- JWT authentication with synchronous verification
+- Session management with multiple store options
+
+5. Extensible Architecture
+- Easy custom middleware creation
+- Pluggable storage backends
+- Comprehensive error handling
+- Detailed metrics and monitoring
+
+6. Modern Features
+- Async/await support throughout
+- HTTP/2 ready architecture
+- Compression with multiple algorithms
+- CORS with fine-grained control
+
+📄 License
+
+MIT License - see LICENSE file for details.
+