webspresso 0.0.103 → 0.0.105

package/.agents/AGENTS.md

@@ -18,6 +18,7 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](AUTH.md) | `core/auth/` |
 | **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](QUEUE.md) | `jobs/` |
 | **Decoupled Events & Signals** | [`.agents/EVENTS.md`](EVENTS.md) | `core/events/`, `listeners/` |
+| **Fault Tolerance / Circuit Breaker / Retry** | [`.agents/RESILIENCE.md`](RESILIENCE.md) | `core/resilience/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](../index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -56,6 +57,11 @@ This `.agents/` customization root is organized into modular topic guides:
 17. **[SSR Streaming & Chunked Transfer](.agents/STREAMING.md)** — Native HTTP chunked streaming (`res.renderStream()`), deferred data loader slots (`defer: { key: promise }`), and TTFB optimization.
 18. **Polar billing production checklist** — [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md) (env, webhooks, rate limits, external tier hooks, CSP). Plugin reference: [PLUGINS.md § polarPlugin](PLUGINS.md).
 19. **[Decoupled Events & Signals Architecture](.agents/EVENTS.md)** — Zero-dependency enterprise event dispatcher (`core/events`), sync/async/parallel/serial/waterfall dispatch, wildcard listeners (`order.*`), Django-style `Signal` and sender filtering, queue bridging, and listener auto-discovery.
+20. **[HTTP 103 Early Hints](.agents/EARLY_HINTS.md)** — Zero-dependency RFC 8288 / RFC 8297 Early Hints dispatcher (`core/early-hints`), preloading route CSS/JS and fonts before SSR loader execution, `createApp({ earlyHints })`, and `res.earlyHints(links)` / `ctx.earlyHints(links)` helpers.
+21. **[Payload Limits & DoS Protection](.agents/LIMITS.md)** — Zero-dependency request body limits and DoS protection (`core/limits`), `createApp({ limits })`, automatic `PayloadTooLargeError` (HTTP 413) mapping, route overrides (`limits.routes`), streaming bypass, and native HMAC webhook `req.rawBody` capture.
+22. **[Cloud & Kubernetes Health Probes](.agents/HEALTH.md)** — Zero-dependency RFC-compliant liveness (`/healthz`), readiness (`/readyz`), and combined diagnostic (`/health`) probes (`core/health`), event loop lag telemetry, database/queue health monitors, automatic HTTP 503 draining on graceful shutdown, and `createApp({ healthCheck: true })`.
+23. **[LRU & Tagged Cache Engine](.agents/CACHE.md)** — Zero-dependency, memory-bounded in-memory LRU cache (`core/cache`), byte budget constraints (`maxBytes` / `maxMemoryMb`), TTL expiration, stampede protection (`getOrSet`), leak-free tag invalidation (`TaggedLruCache`), ORM query cache provider, and `createApp({ cache })`.
+24. **[Enterprise Resilience & Circuit Breaker](.agents/RESILIENCE.md)** — Zero-dependency fault tolerance engine (`core/resilience`), three-state `CircuitBreaker` (`CLOSED`, `OPEN`, `HALF_OPEN`), rolling window failure rate, per-call execution timeout, fallback handlers, and exponential backoff retry engine (`retry`, `withRetry`) with randomized jitter and transient error detection.
 
 ---
 

package/.agents/ARCHITECTURE.md

@@ -51,6 +51,29 @@
 - **HTTP Response Compression (`core/compression`)**:
   - Zero-dependency streaming zlib compression configured via `createApp({ server: { compression: true } })`.
   - Content negotiation for Brotli (`br`), Gzip (`gzip`), Deflate (`deflate`), threshold filtering (1 KB), and `res.compress(false)` route opt-out.
+- **Configurable Payload Size Limits & DoS Protection (`core/limits`)**:
+  - Zero-dependency request body limits configured via `createApp({ limits: { json: '1mb', urlencoded: '1mb', raw: false, text: false, parameterLimit: 1000 } })` or shorthand string/number (`limits: '5mb'`). Also accepted under `createApp({ server: { limits } })`.
+  - **HTTP 413 & 400 Error Mapping**: Payload limit violations and excessive form parameters automatically produce `PayloadTooLargeError` (HTTP 413) with `{ limit, length, expected }` metadata; malformed JSON bodies produce `BadRequestError` (HTTP 400) with `INVALID_JSON_PAYLOAD`.
+  - **Raw Body Capture for Webhooks**: `captureRawBody: true | string[] | Function` captures incoming request payload `Buffer` on `req.rawBody` for zero-overhead HMAC cryptographic verification (Polar, Stripe, GitHub).
+  - **Route Overrides & Exclusions**: `limits.routes` supports per-route limit adjustments (e.g. `routes: { '/api/upload': { json: '25mb' } }`), while `limits.exclude` completely bypasses body parsing for raw socket/streaming endpoints.
+- **Cloud & Kubernetes Health Probes (`core/health`, `/healthz`, `/readyz`, `/health`)**:
+  - RFC-compliant cloud-native endpoints enabled via `createApp({ healthCheck: true })` or fine-grained `{ path: '/healthz', readyPath: '/readyz', combinedPath: '/health', db: true, queue: true, eventLoopLag: true }`.
+  - **Liveness Probe (`/healthz`)**: Non-blocking probe reporting basic process health, memory usage (`rss`, `heapUsed`, `heapTotal`, `external`), and system uptime.
+  - **Readiness Probe (`/readyz`)**: Deep dependency inspection checking database ping (`knex.raw('SELECT 1')`), worker queue status, custom user checks, and `ShutdownManager` draining state (immediately returning HTTP 503 so upstream load balancers detach the instance).
+  - **Diagnostic Health (`/health`)**: Full operational dashboard with event loop lag percentiles (`perf_hooks.monitorEventLoopDelay`), dependency breakdown, and latency metrics.
+- **In-Memory LRU & Tagged Cache Engine (`core/cache`)**:
+  - Zero-dependency O(1) Least-Recently-Used caching engine configured via `createApp({ cache: { maxEntries, maxMemoryMb, defaultTtl } })` or `cache: false`.
+  - **Memory Budget & Leak Prevention**: Enforces byte boundaries (`maxBytes` / `maxMemoryMb`) via `approximateByteSize` to prevent process OOM errors, combined with passive and active TTL pruning (`pruneExpired()`).
+  - **Bidirectional Tag Invalidation (`TaggedLruCache`)**: Supports model and query tagging (`invalidateTag`, `invalidateTags`). When items are evicted via LRU, all associated tag sets are automatically and symmetrically cleaned up, eliminating dangling Set memory leaks.
+  - **Stampede / Thundering Herd Protection**: `getOrSet(key, asyncFactory, options)` deduplicates concurrent in-flight requests for cold keys so expensive factories execute only once.
+  - **Framework Integration**: Directly powers `core/orm/cache/memory-provider.js` (ORM query caching) and `core/schema-cache.js` (Zod schema cache), and is automatically exposed on `req.cache`, `req.context.cache`, and `app.cache`.
+- **Enterprise Resilience, Circuit Breaker & Retry Engine (`core/resilience`)**:
+  - Zero-dependency fault tolerance and cascading failure prevention system built natively on `events` and `perf_hooks`.
+  - **Three-State Circuit Breaker (`CircuitBreaker`)**: Standard `CLOSED`, `OPEN`, and `HALF_OPEN` states. Trips to `OPEN` when consecutive failures reach `failureThreshold` or failure rate percentage exceeds `failureRateThreshold` in a rolling sample window (`rollingWindow`).
+  - **Fail-Fast & Graceful Fallbacks**: Fast-fails calls with `CircuitBreakerOpenError` (HTTP 503) without executing downstream code when open, or seamlessly executes fallback handlers (`fallback: (err, ...args) => ...`).
+  - **Trial Recovery Probing**: Automatically transitions to `HALF_OPEN` after `resetTimeout` and tests downstream health using trial probes (`successThreshold`).
+  - **Exponential Backoff Retry with Full Jitter (`retry`, `withRetry`)**: Automatically retries transient network errors (`ECONNRESET`, `ETIMEDOUT`, 429 Too Many Requests, and 5xx errors) with randomized full jitter to prevent thundering herd spikes while avoiding retrying 4xx client errors.
+  - **Services Layer Integration**: Declarative `defineService({ circuitBreaker, retry })` seamlessly wraps service execution. Also accessible on `app.breakers`, `app.getBreaker()`, `req.breaker()`, `req.retry()`, `ctx.breaker()`, and `ctx.retry()`.
 - **Custom Error & 404 Pages (`errorPages`)**:
   - Configured via `createApp({ errorPages: { notFound, serverError, timeout } })`.
   - **404 Not Found (`notFound`)**: Template path (`'404.njk'`) or handler `(req, res, ctx) => ...`.

package/.agents/CACHE.md

@@ -0,0 +1,147 @@
+# High-Performance In-Memory LRU & Tagged Cache Engine (`core/cache`)
+
+Webspresso includes a zero-dependency, memory-bounded, leak-free in-memory cache engine featuring O(1) Least-Recently-Used (LRU) eviction, byte budget constraints (`maxBytes` / `maxMemoryMb`), TTL expiration, stampede protection (thundering herd prevention), and O(1) bidirectional tag-based invalidation.
+
+---
+
+## 🎯 Key Capabilities & Design Guarantees
+
+1. **True O(1) LRU Eviction**: Built on V8's native insertion-order Map mechanics with zero extra memory allocation for linked-list node wrappers.
+2. **Dual Capacity Boundaries**:
+   - **`maxEntries`**: Restricts the maximum number of items stored.
+   - **`maxBytes` / `maxMemoryMb`**: Enforces strict memory budgets using `approximateByteSize` to prevent process Out-Of-Memory (OOM) crashes under heavy or large payload loads.
+3. **Symmetrical Tag Cleanup (Zero Leaks)**: When an item is evicted via LRU, expired via TTL, or deleted, all associated tag index sets are automatically pruned. Empty tag sets are deleted immediately, preventing the classic "dangling Set memory leak".
+4. **Stampede / Thundering Herd Protection**: `getOrSet(key, asyncFactory)` coalesces concurrent requests for the same missing key, invoking the expensive calculation or DB query exactly once.
+5. **Universal Integration**:
+   - **ORM Query Cache**: Powers `core/orm/cache/memory-provider.js` with true LRU and memory budgets.
+   - **Zod Schema Cache**: Powers `core/schema-cache.js` with bounded 2,000 schemas capacity.
+   - **Application & Context**: Automatically mounted on `app.cache`, `req.cache`, and `req.context.cache` unless `cache: false` is configured.
+
+---
+
+## 🚀 Quick Usage
+
+### 1. Standalone `LruCache`
+```javascript
+const { createLruCache } = require('webspresso');
+
+const cache = createLruCache({
+  maxEntries: 1000,
+  maxMemoryMb: 50,          // 50 MB byte budget
+  defaultTtl: '15m',        // 15 minutes default TTL
+  clone: false,             // Set true if cached objects must not be mutated
+});
+
+cache.set('user:42', { name: 'Alice', role: 'admin' });
+
+const user = cache.get('user:42'); // Refreshes LRU position
+const peekUser = cache.peek('user:42'); // Reads without refreshing LRU position
+```
+
+### 2. Tagged Invalidation (`TaggedLruCache`)
+```javascript
+const { createTaggedLruCache } = require('webspresso');
+
+const cache = createTaggedLruCache({
+  maxEntries: 5000,
+  maxMemoryMb: 100,
+});
+
+// Tag items by model and primary key
+cache.set('query:users:active', usersList, { tags: ['model:User', 'q:active'] });
+cache.set('user:1:profile', userProfile, { tags: ['model:User', 'pk:1'] });
+
+// Invalidate single primary key
+cache.invalidateTag('pk:1');
+
+// Invalidate all queries related to the User model
+cache.invalidateTags(['model:User']);
+```
+
+### 3. Stampede / Thundering Herd Protection (`getOrSet`)
+```javascript
+// 50 concurrent requests for 'expensive:report' will execute the factory only once:
+const report = await cache.getOrSet('expensive:report', async (key) => {
+  return await generateHeavyReport();
+}, { ttl: '1h' });
+```
+
+---
+
+## ⚙️ Application Configuration (`createApp`)
+
+Configure the process-wide cache directly when bootstrapping Webspresso:
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  pagesDir: './pages',
+  cache: {
+    maxEntries: 5000,
+    maxMemoryMb: 64,        // 64 MB budget
+    defaultTtl: '10m',
+  },
+});
+```
+
+To disable the app cache completely:
+```javascript
+const app = createApp({
+  pagesDir: './pages',
+  cache: false,
+});
+```
+
+---
+
+## 🌐 Context & Route Usage
+
+Inside page loaders, services, or API route handlers:
+
+```javascript
+// In API routes (pages/api/stats.get.js)
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const stats = await req.cache.getOrSet('site:stats', async () => {
+      return await req.db.getRepository('Order').getSummaryStats();
+    }, { ttl: '5m', tags: ['stats', 'model:Order'] });
+
+    return res.json(stats);
+  },
+});
+```
+
+```javascript
+// From any background job or script using app-context
+const { getCache } = require('webspresso');
+
+const cache = getCache();
+if (cache) {
+  cache.invalidateTag('stats');
+}
+```
+
+---
+
+## 📊 Telemetry & Observability Metrics
+
+Access real-time cache performance and memory metrics:
+
+```javascript
+const stats = app.cache.getStats();
+console.log(stats);
+// {
+//   entries: 42,
+//   tags: 5,
+//   currentBytes: 124850,
+//   maxBytes: 67108864,
+//   maxEntries: 5000,
+//   hits: 1540,
+//   misses: 23,
+//   hitRate: 0.985,
+//   sets: 65,
+//   evictions: 0,
+//   expirations: 12
+// }
+```

package/.agents/CLI.md

@@ -313,7 +313,7 @@ Generate production-ready, security-hardened, multi-stage `Dockerfile`, `.docker
 npx webspresso add:docker
 
 # Customize Node.js version, database service, or container port
-npx webspresso add:docker --node 22-alpine --db postgres --redis --port 3000
+npx webspresso add:docker --node 22-alpine --db postgres --redis --port 7331
 
 # Overwrite existing files
 npx webspresso add:docker --force

package/.agents/EARLY_HINTS.md

@@ -0,0 +1,120 @@
+# HTTP 103 Early Hints & Critical Asset Preloading
+
+Webspresso features built-in, zero-dependency support for **HTTP 103 Early Hints** (RFC 8288 / RFC 8297).
+Early Hints allow Webspresso to send informational HTTP headers (containing CSS, JavaScript, and font preload instructions) to the client **before** server-side rendering (`load()`, database queries, external API calls) finishes, allowing the browser to download critical page assets in parallel.
+
+---
+
+## 🚀 How It Works
+
+1. The client sends an HTTP request (`GET /products/123`).
+2. Webspresso resolves the matching route and its companion CSS/JS asset candidates via `AssetManager`.
+3. If Early Hints are enabled, Webspresso immediately writes an `HTTP/1.1 103 Early Hints` response with `Link: </css/products.css>; rel=preload; as=style, </js/products.js>; rel=preload; as=script`.
+4. While the browser starts downloading stylesheets and scripts, Webspresso runs the page's async `load()` function and Nunjucks rendering.
+5. Once the HTML is ready, Webspresso returns `HTTP/1.1 200 OK` with the final document.
+6. The browser can immediately render without waiting for secondary asset network round-trips (reducing TTFB, FCP and LCP).
+
+---
+
+## 🛠️ Configuration
+
+### Global Configuration (`createApp`)
+
+Enable automatic route asset preloading globally:
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  earlyHints: true, // Automatically preloads route CSS & JS
+  // Or with custom default links:
+  // earlyHints: {
+  //   auto: true,
+  //   links: ['/css/global.css', '/fonts/inter.woff2'],
+  // }
+});
+```
+
+### Route / Page Configuration (`definePage`)
+
+Configure Early Hints per-page inside your page module:
+
+```javascript
+const { definePage } = require('webspresso');
+
+module.exports = definePage({
+  // Preload route assets automatically
+  earlyHints: true,
+
+  // Or specify exact links:
+  // earlyHints: [
+  //   '/css/special.css',
+  //   { url: '/fonts/inter.woff2', as: 'font', crossOrigin: 'anonymous' }
+  // ],
+
+  load: async (ctx) => {
+    // You can also dispatch hints manually during load:
+    ctx.earlyHints(['/extra-chunk.js']);
+
+    const product = await ctx.db.getRepository('Product').findById(ctx.params.id);
+    return { product };
+  },
+});
+```
+
+### In Route Handlers and API Middleware
+
+`res.earlyHints(links, [callback])` is attached to `res` on every request:
+
+```javascript
+app.get('/dashboard', (req, res) => {
+  // Send 103 Early Hints
+  res.earlyHints([
+    '/css/dashboard.css',
+    '/js/charts.js',
+  ]);
+
+  // Run async queries...
+  setTimeout(() => {
+    res.send('<h1>Dashboard</h1>');
+  }, 200);
+});
+```
+
+---
+
+## 📋 Link Options & Deduction
+
+Webspresso automatically deduces `as` and `crossorigin` attributes based on URL file extensions:
+
+| Extension | Inferred `as` | Browser CORS Requirement |
+| :--- | :--- | :--- |
+| `.css` | `style` | - |
+| `.js`, `.mjs`, `.cjs` | `script` | - |
+| `.woff2`, `.woff`, `.ttf` | `font` | Auto-adds `crossorigin` |
+| `.png`, `.jpg`, `.webp`, `.svg` | `image` | - |
+| `.json` | `fetch` | - |
+
+You can also pass full descriptor objects:
+
+```javascript
+res.earlyHints([
+  {
+    url: '/fonts/inter.woff2',
+    as: 'font',
+    crossOrigin: 'anonymous',
+    fetchPriority: 'high',
+  },
+  {
+    url: 'https://cdn.example.com',
+    rel: 'preconnect',
+  },
+]);
+```
+
+---
+
+## 🛡️ Resilience & Fallbacks
+
+- If the client or proxy does not support HTTP 103, or if running in an environment without `res.writeEarlyHints` (HTTP/1.0, test mocks), `sendEarlyHints` returns `false` safely without throwing.
+- Calling `earlyHints` after response headers have been sent (`res.headersSent === true`) is a safe no-op.

package/.agents/HEALTH.md

@@ -0,0 +1,118 @@
+# Cloud & Kubernetes Health & Readiness Probes (`core/health`)
+
+Webspresso includes a zero-dependency, Docker & Kubernetes-native health inspection system. It provides standard liveness (`/healthz`), readiness (`/readyz`), and combined diagnostics endpoints with automatic database pings, background worker queue checks, event loop delay metrics, and instant graceful shutdown draining integration.
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Kubernetes Liveness Probe (`/healthz`)**:
+   - Confirms process vitality and responsiveness.
+   - Gathers memory footprint (`rss`, `heapUsed`, `heapTotal` formatted and raw bytes), process uptime, PID, platform, and event loop lag statistics (`meanMs`, `maxMs`, `p99Ms`).
+   - If event loop delay exceeds threshold (`eventLoopThresholdMs`), flags status as `degraded`.
+
+2. **Kubernetes Readiness Probe (`/readyz`)**:
+   - Confirms the container is fully prepared to handle live client traffic.
+   - **Database Connectivity**: Pings active Knex instance (`SELECT 1`) with timeout protection.
+   - **Queue Readiness**: Probes worker queue instance status.
+   - **Custom Probes**: Executes user-registered async checks concurrently (`checks: { redis, stripe }`).
+   - Returns `HTTP 200` (`{ ready: true, status: 'ready' }`) when all components are healthy.
+   - Returns `HTTP 503` (`{ ready: false, status: 'unhealthy', checks: ... }`) if any component fails.
+
+3. **Graceful Draining Integration (`ShutdownManager`)**:
+   - As soon as the server enters shutdown draining (`app.close()` or `SIGTERM`/`SIGINT`), `/readyz` immediately returns `HTTP 503` (`{ ready: false, status: 'draining' }`).
+   - Cloud load balancers (AWS ALB, K8s Ingress, Google Cloud, Cloudflare) immediately stop routing new traffic to this instance, while existing active requests drain cleanly without dropping a single connection.
+
+---
+
+## 🚀 Configuration Examples
+
+### 1. Simple Enablement
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  pagesDir: 'pages',
+  // Enables /healthz (liveness), /readyz (readiness), and /health (combined)
+  healthCheck: true,
+});
+```
+
+Shorthand custom path:
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  healthCheck: '/api/status', // Mounts combined status on /api/status
+});
+```
+
+### 2. Full Production Configuration
+
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  db: myDatabaseInstance,
+  queue: myQueueInstance,
+  healthCheck: {
+    enabled: true,
+    path: '/healthz',               // Liveness probe URL
+    readyPath: '/readyz',           // Readiness probe URL
+    combinedPath: '/health',        // Diagnostic summary URL
+    db: true,                       // Automatically probe database (SELECT 1)
+    queue: true,                    // Automatically probe worker queue
+    eventLoopLag: true,             // Monitor event loop delay
+    eventLoopThresholdMs: 300,      // Lag threshold in ms
+    timeoutMs: 2500,                // Probe timeout before marking down
+    checks: {                       // Custom dependency probes
+      redis: async () => redisClient.ping(),
+      stripe: async () => checkStripeHealth(),
+    },
+    headers: {
+      'Cache-Control': 'no-store, no-cache, must-revalidate',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  },
+});
+```
+
+---
+
+## ☸️ Kubernetes Pod Spec Example
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  timeoutSeconds: 3
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /readyz
+    port: 3000
+  initialDelaySeconds: 2
+  periodSeconds: 5
+  timeoutSeconds: 2
+  failureThreshold: 2
+```
+
+---
+
+## 🔍 Programmatic Inspection
+
+Access health state directly in code or CLI scripts:
+
+```javascript
+// Get complete diagnostic payload
+const status = await app.getHealthStatus();
+console.log('Liveness:', status.liveness);
+console.log('Readiness:', status.readiness);
+
+// Or via healthManager
+const liveness = await app.healthManager.getLiveness();
+const readiness = await app.healthManager.getReadiness();
+```

package/.agents/LIMITS.md

@@ -0,0 +1,109 @@
+# Configurable Payload Size Limits & DoS Protection (`core/limits`)
+
+Webspresso provides a zero-dependency, configurable request body size limiter and Denial of Service (DoS) protection layer. It safeguards Node.js memory against payload exhaustion attacks while supporting per-route overrides, streaming bypass, and native raw body capture for HMAC webhook verification.
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Multi-Parser Configuration**:
+   - `json`: Size limit for `application/json` (default: `'1mb'`).
+   - `urlencoded`: Size limit for `application/x-www-form-urlencoded` (default: `'1mb'`).
+   - `parameterLimit`: Maximum number of URL-encoded form parameters (default: `1000`).
+   - `raw`: Size limit for `application/octet-stream` (default: `false` / disabled).
+   - `text`: Size limit for `text/plain` (default: `false` / disabled).
+2. **Standard Exception Mapping**:
+   - Limit exceeded -> Throws `PayloadTooLargeError` (HTTP 413) with `{ limit, length, expected }` details and `code: 'PAYLOAD_TOO_LARGE'`.
+   - Parameter exhaustion -> Throws `PayloadTooLargeError` (HTTP 413) with `code: 'PARAMETERS_TOO_MANY'`.
+   - Malformed JSON -> Throws `BadRequestError` (HTTP 400) with `code: 'INVALID_JSON_PAYLOAD'`.
+3. **Webhook & HMAC Signature Verification**:
+   - `captureRawBody: true` stores incoming unparsed `Buffer` on `req.rawBody` for zero-overhead cryptographic signatures (Polar, Stripe, LemonSqueezy, GitHub).
+4. **Route Overrides & Streaming Bypass**:
+   - `limits.routes`: Generous limits for specific paths (e.g. `/api/upload` -> 25MB) without loosening server-wide protection.
+   - `limits.exclude`: Completely skips global body parsers for streaming and custom multipart endpoints.
+
+---
+
+## 🚀 Configuration Examples
+
+### 1. Global Configuration
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  pagesDir: 'pages',
+  limits: {
+    json: '2mb',           // 2 Megabytes for JSON
+    urlencoded: '1mb',     // 1 Megabyte for Forms
+    parameterLimit: 2000,  // Up to 2000 parameters
+    raw: '10mb',           // Enable raw buffer parsing for binary data
+    captureRawBody: true,  // Automatically populate req.rawBody
+  },
+});
+```
+
+Shorthand (applies to both JSON and URL-encoded):
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  limits: '5mb', // Both json and urlencoded set to 5 MB
+});
+```
+
+### 2. Route Overrides & Exclusions
+
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  limits: {
+    json: '500kb', // Tight global limit for standard APIs
+    routes: {
+      '/api/import/json': { json: '25mb' }, // Relaxed limit for batch import
+      '/api/webhooks/*': { raw: '5mb', captureRawBody: true },
+    },
+    exclude: [
+      '/api/stream/upload', // Skip global body parser entirely for socket streaming
+    ],
+  },
+});
+```
+
+### 3. Webhook Signature Verification with `req.rawBody`
+
+```javascript
+// pages/api/webhooks/polar.post.js
+const crypto = require('crypto');
+const { defineApi, UnauthorizedError } = require('webspresso');
+
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const signature = req.headers['webhook-signature'];
+    const expected = crypto
+      .createHmac('sha256', process.env.POLAR_WEBHOOK_SECRET)
+      .update(req.rawBody) // Native Buffer captured via captureRawBody
+      .digest('hex');
+
+    if (signature !== expected) {
+      throw new UnauthorizedError('Invalid signature');
+    }
+
+    return res.json({ received: true });
+  },
+});
+```
+
+---
+
+## 🛡️ Standalone Middleware Usage
+
+For manual route mounting or custom Express routers:
+
+```javascript
+const { createLimitsMiddleware } = require('webspresso');
+
+// Mount on custom router or endpoint
+app.post('/custom-endpoint', createLimitsMiddleware({ json: '50mb' }), (req, res) => {
+  res.json({ size: req.body.length });
+});
+```