exisjs 0.7.11 → 0.7.13

package/dist/docs/content/middleware.mdx

@@ -1,522 +1,244 @@
 ---
-nextUrl: "/docs/modules"
-nextTitle: "Modules & Plugins"
+title: "Middleware Pipeline"
+description: "Configure global, folder-scoped, and route-level middlewares, type-safe context injection, file uploads, and Express bridges in ExisJS."
+nextUrl: "/docs/errors"
+nextTitle: "Error Handling"
 ---
 
-# Middleware
+# Middleware Pipeline
 
-ExisJS comes with a collection of built-in middleware out of the box.
+ExisJS provides a unified middleware pipeline supporting three execution levels:
+1. **Global Middlewares (`src/http/server.ts` or `exis.config.ts`)**: Apply to every incoming HTTP request across the server.
+2. **Folder-Scoped Middlewares (`src/http/**/boundary.ts`)**: Apply to all routes within a directory and its subdirectories.
+3. **Route-Scoped Middlewares (`route.ts`)**: Apply to specific individual endpoints.
 
-ExisJS provides first-party implementations for features like CORS, Request Logging, Backpressure, In-Memory Rate Limiting, Idempotency, and Deduplication.
-
-All middleware can be imported directly from the `exisjs/middleware` package.
+All standard middlewares can be imported directly from `exisjs/middleware`. Custom typed middlewares can be declared using `defineMiddleware<TContext>()` from `exisjs/router`.
 
 ---
 
-## Where to Apply Middleware
-
-ExisJS gives you granular control over where your middleware executes:
-
-1. **Globally (`server.ts`)**: Applies to every request hitting your server via `app.use()`.
-2. **Folder-Scoped (`boundary.ts`)**: Applies to routes inside that folder and all subfolders automatically.
-3. **Route-Scoped (`route.ts`)**: Applies only to a specific endpoint.
-
-```typescript filename="src/http/admin/boundary.ts"
-import { defineBoundary } from 'exisjs/router'
-import type { Request, Response, Next } from 'exisjs/router'
-import { requestLogger } from 'exisjs/middleware'
-
-export const config = defineBoundary({})
-
-// Auto-detected chain step for /admin/*
-export const logger = requestLogger({ level: 'debug' })
-```
-
-### Middleware Context Type Inference (`defineMiddleware`)
-
-When custom middlewares attach data to `req` (such as authenticated user details, session data, or tenant tokens), ExisJS supports **End-to-End Middleware Context Type Inference**.
-
-By using `defineMiddleware<TContext>()`, downstream route handlers automatically inherit strongly typed properties on `req` with zero manual type casts (`as any`) or boilerplate.
-
-#### Local Route-Level Inference (Recommended)
-
-```typescript filename="src/http/route.ts"
-import { controller, route, defineMiddleware } from 'exisjs/router'
-
-// 1. Define your custom context shape
-interface AuthContext {
-  user: {
-    id: string
-    role: 'admin' | 'user'
-    email: string
-  }
-}
-
-// 2. Define the middleware with your context
-export const authMiddleware = defineMiddleware<AuthContext>((req, res, next) => {
-  req.user = {
-    id: 'usr_123',
-    role: 'admin',
-    email: 'alex@example.com'
-  }
-  next()
-})
-
-export default controller({
-  profile: route.get('/profile', {
-    middlewares: [authMiddleware],
-    handle({ req, res }) {
-      // ✨ req.user is automatically inferred directly from middlewares: [authMiddleware]!
-      // Full autocomplete and strict type safety:
-      return res.json({
-        userId: req.user.id,
-        role: req.user.role,
-        email: req.user.email
-      })
-    }
-  })
-})
-```
-
-#### Multi-Middleware Context Composition
-
-When passing multiple middlewares, ExisJS automatically merges all injected contexts:
-
-```typescript
-const authMw = defineMiddleware<{ user: { id: string } }>(...)
-const tenantMw = defineMiddleware<{ tenantId: string }>(...)
+## Built-in Middlewares Reference
+
+| Middleware | Signature | Description |
+| :--- | :--- | :--- |
+| `cors` | `cors(options?)` | Cross-Origin Resource Sharing handler for allowed origins, methods, and preflight headers. |
+| `requestLogger` | `requestLogger(options?)` | Request logger powered by Pino, injecting `req.log` with automatic timing and child loggers. |
+| `requestId` | `requestId()` | Attaches a unique `X-Request-Id` to requests and responses with distributed tracing headers. |
+| `compress` | `compress()` | Stream-based HTTP response compression supporting Gzip, Brotli, and Deflate. |
+| `rateLimit` | `rateLimit(options?)` | Off-heap / in-memory rate limiter returning `429 Too Many Requests` with standard headers. |
+| `idempotent` | `idempotent(options?)` | Duplicate mutation caching keyed by `Idempotency-Key` headers. |
+| `dedupe` | `dedupe(options)` | Merges simultaneous identical in-flight `GET` requests into a single operation. |
+| `backpressure` | `backpressure(options?)` | Queues requests during high load and sheds excess traffic with `503 Service Unavailable`. |
+| `serveStatic` | `serveStatic(root, options?)` | Serves static assets from disk with strong ETags and Brotli/Gzip pre-compression. |
+| `timeout` | `timeout(ms \| options)` | Terminates requests exceeding the duration limit with `503 Service Unavailable`. |
+| `fileUpload` | `fileUpload(options?)` | Streaming multipart/form-data parser supporting disk/memory storage and MIME checks. |
+| `fromExpress` | `fromExpress(middleware)` | Connect/Express bridge adapter running third-party middleware (e.g. Multer) directly. |
 
-export default controller({
-  data: route.get('/data', {
-    middlewares: [authMw, tenantMw],
-    handle({ req }) {
-      // req has both `req.user` and `req.tenantId` strictly typed!
-      return { userId: req.user.id, tenant: req.tenantId }
-    }
-  })
-})
-```
-
-#### Module-Scoped Context (`createRouter<TContext>()`)
-
-If an entire file or subsystem shares the same context, use `createRouter<TContext>()`:
+---
 
-```typescript filename="src/http/admin/route.ts"
-import { createRouter } from 'exisjs/router'
+## Where to Apply Middleware
 
-interface AdminContext {
-  user: { id: string; role: 'admin' }
-}
+### 1. Global Middleware (`src/http/server.ts`)
 
-const { route, controller } = createRouter<AdminContext>()
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { requestId, requestLogger, compress } from 'exisjs/middleware'
 
-export default controller({
-  settings: route.get('/settings', {
-    middlewares: [authMiddleware],
-    handle({ req }) {
-      return { adminId: req.user.id }
-    }
-  })
+export default exis({
+  async onStart(app) {
+    app.use(requestId())
+    app.use(requestLogger({ level: 'info' }))
+    app.use(compress())
+  },
 })
 ```
 
-#### Boundary-Scoped Context (`defineBoundary<TContext>()`)
+### 2. Folder-Scoped Middleware (`src/http/**/boundary.ts`)
 
-Propagate context types across all routes in a directory tree:
+Middlewares defined in a `boundary.ts` apply to all routes in that folder and child folders:
 
 ```typescript filename="src/http/admin/boundary.ts"
 import { defineBoundary } from 'exisjs/router'
-
-export const config = defineBoundary<AdminContext>({
-  beforeHandle: async ({ req }) => {
-    console.log(`Admin action by: ${req.user.id}`)
-  }
-})
-```
-
-#### Class-Based (OOP) Context Usage
-
-In OOP controllers, you can attach typed middlewares via `@Use()` and type the injected `@Req()` object:
-
-```typescript filename="src/http/admin/route.ts"
-import { Controller, Get, Use, Req } from 'exisjs/decorators'
-import type { Request } from 'exisjs/router'
-import { authMiddleware } from '../../middleware/auth'
-import type { AuthContext } from '../../middleware/auth'
-
-@Controller('/admin')
-@Use(authMiddleware)
-export default class AdminController {
-  @Get('/profile')
-  getProfile(@Req() req: Request & AuthContext) {
-    return {
-      userId: req.user.id,
-      role: req.user.role,
-      email: req.user.email,
-    }
-  }
-}
-```
-
-#### Functional Paradigm
-
-```typescript filename="src/http/route.ts"
-import { controller, route } from 'exisjs/router'
-import { validate } from 'exisjs/middleware'
-import { tex } from 'exisjs/validator'
-
-const mySchema = {
-  body: tex.object({ name: tex.string() })
-}
-
-export default controller({
-  create: route.post('/', {
-    middlewares: [validate(mySchema)],
-    handle({ req }) {
-      return { ok: true, name: req.body.name }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/route.ts"
-import { Controller, Post, Use } from 'exisjs/decorators'
-import { validate } from 'exisjs/middleware'
-import { tex } from 'exisjs/validator'
-
-const mySchema = {
-  body: tex.object({ name: tex.string() })
-}
-
-@Controller()
-export default class MyController {
-  @Use(validate(mySchema))
-  @Post('/')
-  async create() {
-    return { ok: true }
-  }
-}
-```
-
----
-
-## 1. CORS
-
-The `cors` middleware handles Cross-Origin Resource Sharing.
-
-The recommended practice in ExisJS is to configure CORS globally in your **`exis.config.ts`** file or per-folder in `boundary.ts`.
-
-```typescript filename="exis.config.ts"
-import { defineConfig } from 'exisjs/config'
-
-export default async () => defineConfig({
-  cors: {
-    origin: ['https://myapp.com', /localhost:\d+/],
-    methods: ['GET', 'POST', 'OPTIONS'],
-    credentials: true,
-    maxAge: 86400,
-  }
-})
-```
-
----
-
-## 2. Request Logger
-
-ExisJS uses Pino under the hood. The `requestLogger` injects a request-scoped logger instance (`req.log`) and times response cycles automatically.
-
-```typescript filename="src/http/server.ts"
-import { requestLogger } from 'exisjs/middleware'
-
-app.use(requestLogger({
-  level: 'debug',
-  pretty: true
-}))
-```
-
----
-
-## 3. Request ID
-
-Injects a unique `X-Request-Id` into every incoming request and outgoing response header. Supports distributed tracing headers (`traceparent`, `x-b3-traceid`).
-
-```typescript filename="src/http/server.ts"
-import { requestId } from 'exisjs/middleware'
-
-app.use(requestId())
-```
-
----
-
-## 4. Rate Limiting (In-Memory / Native Off-Heap)
-
-ExisJS provides high-performance rate limiting powered by Rust native memory:
-
-#### Functional Paradigm
-
-```typescript filename="src/http/auth/route.ts"
-import { controller, route } from 'exisjs/router'
 import { rateLimit } from 'exisjs/middleware'
+import { authGuard } from '../../common/guards/auth.guard'
 
-const authLimiter = rateLimit({ windowMs: 60000, max: 10 })
-
-export default controller({
-  login: route.post('/login', {
-    middlewares: [authLimiter],
-    handle({ req }) {
-      return { status: 'ok' }
-    }
-  })
+const adminLimiter = rateLimit({
+  windowMs: 60 * 1000,
+  max: 60,
+  message: 'Admin rate limit exceeded',
 })
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/auth/route.ts"
-import { Controller, Post, Use } from 'exisjs/decorators'
-import { rateLimit } from 'exisjs/middleware'
-
-const authLimiter = rateLimit({ windowMs: 60000, max: 10 })
-
-@Controller('/auth')
-export default class AuthController {
-  @Post('/login')
-  @Use(authLimiter)
-  async login() {
-    return { status: 'ok' }
-  }
-}
-```
-
-> [!NOTE]
-> Core rate limiting runs completely off-heap in-memory. For Redis-backed distributed rate limiting across clusters, use `@exisjs/cache`.
-
----
-
-## 5. Idempotency (In-Memory / Native Off-Heap)
-
-Idempotency caches responses based on the `Idempotency-Key` header, preventing duplicate mutations:
-
-#### Functional Paradigm
 
-```typescript filename="src/http/checkout/route.ts"
-import { controller, route } from 'exisjs/router'
-import { idempotent } from 'exisjs/middleware'
-
-export default controller({
-  checkout: route.post('/', {
-    middlewares: [idempotent({ ttlMs: 86400000 })],
-    async handle() {
-      return { success: true }
-    }
-  })
+export default defineBoundary({
+  middleware: [adminLimiter, authGuard],
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/checkout/route.ts"
-import { Controller, Post, Idempotent } from 'exisjs/decorators'
-
-@Controller('/checkout')
-export default class CheckoutController {
-  @Idempotent({ ttlMs: 86400000 })
-  @Post('/')
-  async checkout() {
-    return { success: true }
-  }
-}
-```
-
----
-
-## 6. Request Deduplication (`dedupe`)
-
-If multiple clients request the exact same resource concurrently, `dedupe` collapses identical in-flight requests into a single operation:
+### 3. Route-Scoped Middleware (`src/http/**/route.ts`)
 
-#### Functional Paradigm
+#### Functional Route Paradigm
 
-```typescript filename="src/http/stats/route.ts"
+```typescript filename="src/http/reports/route.ts"
 import { controller, route } from 'exisjs/router'
 import { dedupe } from 'exisjs/middleware'
 
 export default controller({
-  getStats: route.get('/', {
-    middlewares: [dedupe({ ttlMs: 5000 })],
-    async handle() {
-      return { activeUsers: 1000 }
-    }
-  })
+  generate: route.get('/', {
+    middleware: [
+      dedupe({
+        keyGenerator: (req) => `${req.user?.id || req.ip}:reports`,
+      }),
+    ],
+    async handle({ res }) {
+      const data = await computeReport()
+      res.json({ data })
+    },
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm
+#### Class-Based (OOP) Controller Paradigm
 
-```typescript filename="src/http/stats/route.ts"
+```typescript filename="src/http/reports/controller.ts"
 import { Controller, Get, Use } from 'exisjs/decorators'
 import { dedupe } from 'exisjs/middleware'
 
-@Controller('/stats')
-export default class StatsController {
+@Controller('/reports')
+export default class ReportsController {
   @Get('/')
-  @Use(dedupe({ ttlMs: 5000 }))
-  async getStats() {
-    return { activeUsers: 1000 }
+  @Use(
+    dedupe({
+      keyGenerator: (req) => `${req.user?.id || req.ip}:reports`,
+    })
+  )
+  async generate() {
+    return { data: await computeReport() }
   }
 }
 ```
 
 ---
 
-## 7. Static File Serving
-
-A static file server that resolves MIME types and streams files:
-
-```typescript
-import { serveStatic } from 'exisjs/middleware'
-import path from 'node:path'
-
-app.use('/public', serveStatic(path.join(process.cwd(), 'public'), {
-  maxAge: 31536000
-}))
-```
+## Type-Safe Middleware Context (`defineMiddleware`)
 
----
-
-## 8. Compression (Gzip / Brotli / Deflate)
+When custom middlewares augment `req` with extra properties (such as user sessions or tenant tokens), use `defineMiddleware<TContext>()` from `exisjs/router`. Downstream route handlers will automatically infer the injected properties on `req`:
 
-Stream-based compression middleware supporting Gzip, Deflate, and Brotli:
+### 1. Declaring a Typed Middleware
 
-```typescript filename="exis.config.ts"
-import type { ExisConfig } from 'exisjs/config'
+```typescript filename="src/common/middleware/auth.ts"
+import { defineMiddleware } from 'exisjs/router'
+import { UnauthorizedException } from 'exisjs/error'
 
-const config: ExisConfig = {
-  compression: true,
+export interface AuthContext {
+  user: {
+    id: string
+    role: 'admin' | 'member'
+    email: string
+  }
 }
 
-export default config
-```
-
----
-
-## 9. Request Timeout (`timeout`)
-
-The `timeout()` middleware terminates runaway requests and returns `503 Service Unavailable` (or a custom status code).
-
-ExisJS defaults to **60 seconds (60000ms)** to provide generous headroom for slow network connections and third-party cloud operations (Cloudinary, AWS S3, OpenAI, Stripe).
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { timeout } from 'exisjs/middleware'
+export const requireAuth = defineMiddleware<AuthContext>(async (req, res, next) => {
+  const token = req.headers['authorization']
+  if (!token) {
+    throw new UnauthorizedException('Authentication token missing')
+  }
 
-export default exis({
-  async onStart(app) {
-    app.use(timeout({
-      ms: 60000,
-      statusCode: 504,
-      message: 'Gateway Timeout connecting to upstream cloud service',
-      // Bypass webhooks or long-lived streaming endpoints
-      exclude: ['/webhooks/*', '/ai/stream'],
-    }))
+  req.user = {
+    id: 'user_456',
+    role: 'admin',
+    email: 'dev@example.com',
   }
+
+  next()
 })
 ```
 
-Handlers can also dynamically adjust timeouts using `req.setTimeout(ms)` and `req.clearTimeout()`.
-
-### Route-Level Timeout Overrides
+### 2. Using Typed Middleware in Functional Routes
 
-Long-running routes (file uploads, PDF exports, AI inferences, data migrations) can declare custom timeouts directly in the route definition, overriding any global application timeout:
-
-```typescript filename="src/http/ai/route.ts"
+```typescript filename="src/http/profile/route.ts"
 import { controller, route } from 'exisjs/router'
+import { requireAuth } from '../../common/middleware/auth'
 
 export default controller({
-  heavyTask: route.post('/heavy-task', {
-    timeoutMs: 120000, // 2 minutes for this endpoint only
-    async handle({ body }) {
-      return await generateLargeReport(body)
-    }
+  me: route.get('/', {
+    middleware: [requireAuth],
+    handle({ req, res }) {
+      // req.user is strongly typed as AuthContext['user'] without manual casts
+      res.json({
+        id: req.user.id,
+        email: req.user.email,
+        role: req.user.role,
+      })
+    },
   }),
-
-  exportStream: route.get('/export', {
-    timeoutMs: 0, // 0 disables timeout completely for infinite SSE / streaming
-    async handle({ res }) {
-      return streamDataToClient(res)
-    }
-  })
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-
-Use the `@Timeout(ms)` decorator on any controller method:
-
-```typescript filename="src/http/ai/controller.ts"
-import { Controller, Post, Timeout } from 'exisjs/decorators'
-
-@Controller('/ai')
-export default class AiController {
-  @Post('/inference')
-  @Timeout(120000)
-  async runInference() {
-    return await computeModel()
-  }
-}
-```
-
 ---
 
-### Declarative Route Uploads
+## Multipart File Uploads (`fileUpload`)
+
+ExisJS includes a streaming multipart parser in `exisjs/middleware` for file uploads:
 
-You can configure file uploads directly within functional route declarations:
+### 1. Functional Route Upload Declaration
 
 ```typescript filename="src/http/media/route.ts"
 import { controller, route } from 'exisjs/router'
+import { fileUpload } from 'exisjs/middleware'
 
 export default controller({
-  upload: route.post('/photo', {
-    upload: {
-      field: 'file',
-      maxSize: '10MB',
-      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
-      destination: 'memory', // 'memory' | 'disk' | 'stream'
+  uploadAvatar: route.post('/avatar', {
+    middleware: [
+      fileUpload.single('avatar', {
+        maxSize: '5MB',
+        allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+        destination: 'memory',
+      }),
+    ],
+    async handle({ req, res }) {
+      const file = req.file
+      if (!file) {
+        return res.status(400).json({ error: 'No file uploaded' })
+      }
+
+      return res.status(201).json({
+        filename: file.filename,
+        mimetype: file.mimetype,
+        size: file.size,
+      })
     },
-    async handle({ file, fields, req }) {
-      // file.buffer, file.mimetype, file.filename are immediately accessible
-      return { success: true, filename: file.filename }
-    }
-  })
+  }),
 })
 ```
 
-### Class-Based (OOP) Upload Decorators
-
-Use `@UseUpload` or `@Upload` to configure file parsing on controller actions:
+### 2. Class-Based (OOP) Upload Decorator
 
 ```typescript filename="src/http/media/controller.ts"
 import { Controller, Post, UseUpload, UploadedFile, Body } from 'exisjs/decorators'
+import type { ExisFile } from 'exisjs/middleware'
 
 @Controller('/media')
 export default class MediaController {
-  @Post('/photo')
+  @Post('/avatar')
   @UseUpload({
-    field: 'file',
-    maxSize: '10MB',
+    field: 'avatar',
+    maxSize: '5MB',
     allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
     destination: 'memory',
   })
-  async uploadPhoto(@UploadedFile() file: any, @Body() fields: any) {
-    return { filename: file.filename, size: file.size }
+  async uploadAvatar(@UploadedFile() file: ExisFile, @Body() body: Record<string, string>) {
+    return {
+      filename: file.filename,
+      size: file.size,
+      title: body.title,
+    }
   }
 }
 ```
 
-### Express / Connect Multer Bridge (`fromExpress`)
+---
+
+## Express and Connect Middleware Bridge (`fromExpress`)
 
-Seamlessly run existing Express/Connect middleware such as **Multer** directly in ExisJS without manual Promise wrapping:
+To run legacy Express or Connect middleware (such as `multer`, `passport`, or custom third-party packages) directly inside ExisJS, wrap them using `fromExpress`:
 
 ```typescript filename="src/http/legacy/route.ts"
 import { controller, route } from 'exisjs/router'
@@ -526,91 +248,43 @@ import multer from 'multer'
 const upload = multer({ storage: multer.memoryStorage() })
 
 export default controller({
-  upload: route.post('/', 
+  upload: route.post(
+    '/',
     fromExpress(upload.single('file')),
-    ({ req }) => {
-      const file = (req.raw as any).file || req.file
-      return { success: true, originalname: file?.originalname }
+    ({ req, res }) => {
+      const file = req.file
+      res.json({ success: true, originalname: file?.filename })
     }
-  )
+  ),
 })
 ```
 
----
-
-## 10. Security Scanner Noise Suppression & Blackhole (`blockSuspiciousProbes`)
-
-In public production deployments, automated vulnerability scanners aggressively probe for `.env`, `/.git/HEAD`, `/.env.backup`, `/.DS_Store`, `wp-config.php`, etc.
+`fromExpress` automatically maps parameters, query strings, headers, and attached properties (like `req.file` or `req.body`) back onto the `ExisRequest` instance.
 
-Each probe generates a `404` error log with structured JSON logging (`{"level":40,"statusCode":404}`), flooding log aggregators and triggering false security alerts.
+---
 
-ExisJS provides `blockSuspiciousProbes` (alias `blockProbes`) to immediately intercept known exploit patterns, terminate the request with an empty response (blackhole), and suppress logger noise.
+## Static File Serving (`serveStatic`)
 
-### Global Usage (`server.ts` / `exis.config.ts`)
+Serve static frontend bundles, assets, or downloads directly from disk:
 
 ```typescript filename="src/http/server.ts"
 import { exis } from 'exisjs'
-import { blockSuspiciousProbes } from 'exisjs/middleware'
+import { serveStatic } from 'exisjs/middleware'
+import path from 'node:path'
 
 export default exis({
   async onStart(app) {
-    // Intercept probes before downstream routes or loggers
-    app.use(blockSuspiciousProbes({
-      statusCode: 404, // or 403
-      silent: true,    // Suppresses level-40 warning logs in requestLogger
-    }))
-  }
-})
-```
-
-Or enable directly in `exis.config.ts`:
-
-```typescript filename="exis.config.ts"
-import { defineConfig } from 'exisjs/config'
-
-export default async () => defineConfig({
-  blockProbes: true, // or { statusCode: 404, silent: true }
-})
-```
-
-### Folder-Scoped Boundary (`boundary.ts`)
-
-```typescript filename="src/http/boundary.ts"
-import { defineBoundary } from 'exisjs/router'
-
-export default defineBoundary({
-  blockProbes: {
-    statusCode: 404,
-    silent: true,
-    exclude: ['/.well-known/security.txt'],
-  }
+    app.use(
+      '/public',
+      serveStatic(path.join(process.cwd(), 'public'), {
+        maxAge: 31536000, // 1 year cache-control
+        etag: true,
+        brotli: true,
+        gzip: true,
+      })
+    )
+  },
 })
 ```
 
-### Class-Based (OOP) Decorator
-
-```typescript filename="src/http/api/route.ts"
-import { Controller, Get, BlockProbes } from 'exisjs/decorators'
-
-@Controller('/api')
-@BlockProbes({ statusCode: 404 })
-export default class ApiController {
-  @Get('/health')
-  health() {
-    return { status: 'healthy' }
-  }
-}
-```
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `statusCode` | `number` | `404` | HTTP status code to return for blocked probes |
-| `blackhole` | `boolean` | `true` | Immediately terminates connection with empty body without calling downstream middleware |
-| `silent` | `boolean` | `true` | Suppresses `requestLogger` warning logs for blocked probe requests |
-| `patterns` | `(string \| RegExp)[]` | `[]` | Additional custom probe patterns to block |
-| `exclude` | `(string \| RegExp)[]` | `[]` | Whitelist patterns to allow through without blocking |
-| `onProbe` | `(req, res, pattern) => void` | `undefined` | Callback hook when a probe is detected (for SIEM or IP reputation metrics) |
-
-
+`serveStatic` automatically handles MIME detection, conditional `If-None-Match` 304 caching, and serves pre-compressed `.br` or `.gz` files if present on disk.