@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/wiki/references/base/middlewares.md

@@ -1,590 +0,0 @@
----
-title: Middlewares Reference
-description: Technical reference for IGNIS built-in middlewares
-difficulty: intermediate
-lastUpdated: 2026-01-03
----
-
-# Middlewares Reference
-
-IGNIS provides a collection of built-in middlewares for common application needs including error handling, request logging, and favicon serving.
-
-**Files:**
-- `packages/core/src/base/middlewares/*.ts`
-
-## Prerequisites
-
-- [Hono Middleware basics](https://hono.dev/docs/guides/middleware)
-- [IGNIS Application basics](./application.md)
-- Basic understanding of HTTP request/response lifecycle
-
-## Quick Reference
-
-| Middleware | Purpose | Key Options |
-|------------|---------|-------------|
-| `appErrorHandler` | Catches and formats application errors | `logger` |
-| `notFoundHandler` | Handles 404 Not Found responses | `logger` |
-| `RequestSpyMiddleware` | Logs request lifecycle, timing, and parses request body | None |
-| `emojiFavicon` | Serves an emoji as favicon | `icon` |
-
-## Table of Contents
-
-- [Error Handler (`appErrorHandler`)](#error-handler-apporerrorhandler)
-- [Not Found Handler (`notFoundHandler`)](#not-found-handler-notfoundhandler)
-- [Request Spy (`RequestSpyMiddleware`)](#request-spy-requestspymiddleware)
-- [Emoji Favicon](#emoji-favicon)
-- [Creating Custom Middleware](#creating-custom-middleware)
-- [Middleware Order & Priority](#middleware-order--priority)
-- [See Also](#see-also)
-
-## Built-in Middlewares
-
-### Error Handler (`appErrorHandler`)
-
-The error handler middleware catches all unhandled errors in your application and formats them into consistent JSON responses.
-
-**File:** `packages/core/src/base/middlewares/app-error/app-error.middleware.ts`
-
-#### Features
-
-- **Automatic Error Formatting**: Converts all errors to structured JSON responses
-- **ZodError Support**: Validation errors surface a schema-driven `messageCode` and `message` (from `params.code`, else the raw Zod code), with the full per-field list under `details.cause`
-- **Database Error Handling**: Returns 400 for SQLSTATE class `22` (data exception) and `23` (integrity) errors, with a fallback message; other classes (e.g. `42` programming errors) stay 500
-- **Production-Safe**: Hides stack traces, error causes, DB driver internals (`detail`/`table`/`constraint`), and raw system messages in production
-- **Request Tracking**: Includes `requestId` for debugging and tracing
-- **Status Code Detection**: Automatically extracts `statusCode` from errors
-
-#### Usage
-
-```typescript
-import { appErrorHandler } from '@venizia/ignis';
-
-const app = new IgnisApplication({
-  // ...
-});
-
-// Register error handler
-app.onError(appErrorHandler({
-  logger: app.logger
-}));
-```
-
-#### Error Response Format
-
-**Standard Error:**
-```json
-{
-  "message": "Something went wrong",
-  "statusCode": 500,
-  "requestId": "abc123",
-  "details": {
-    "url": "http://localhost:3000/api/users",
-    "path": "/api/users",
-    "stack": "Error: Something went wrong\n  at ...",  // development only
-    "cause": { ... }  // development only
-  }
-}
-```
-
-**Validation Error (ZodError):**
-
-Top-level `message`/`messageCode` come from the first failing issue — its `params.code` if the schema set one (see below), otherwise its raw Zod code. The full per-field list stays under `details.cause`. If `error.rootKey` is configured, the whole body is wrapped under that key.
-
-```json
-{
-  "message": "Invalid email address",
-  "messageCode": "invalid_type",
-  "statusCode": 422,
-  "requestId": "abc123",
-  "details": {
-    "url": "http://localhost:3000/api/users",
-    "path": "/api/users",
-    "stack": "...",  // development only
-    "cause": [
-      {
-        "path": "email",
-        "message": "Invalid email address",
-        "code": "invalid_type",
-        "expected": "string"
-      }
-    ]
-  }
-}
-```
-
-To emit a stable, domain-specific `messageCode`, attach `params.code` to a custom check:
-
-```typescript
-z.string().refine(isEmail, { message: 'Invalid email address', params: { code: 'user.email.invalid' } });
-// → "messageCode": "user.email.invalid"
-```
-
-**Database Constraint Error:**
-
-Database errors in SQLSTATE class `22` (data exception) and `23` (integrity constraint) are detected by **class** and returned as 400 Bad Request. A known code uses its specific message; any other in-class code uses `DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE` (`"Invalid database request"`).
-
-```json
-// non-production — full driver context for debugging
-{
-  "message": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
-  "statusCode": 400,
-  "requestId": "abc123",
-  "details": { "url": "...", "path": "/api/users", "stack": "...", "cause": { } }
-}
-```
-
-:::warning Production sanitizes database internals
-In **production** the message is the base message only — `Detail:`/`Table:`/`Constraint:` are stripped (they echo row values and schema names), and `details.stack`/`details.cause` are omitted. Codes outside class 22/23 (e.g. `42703` undefined column) and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak.
-:::
-
-**Database client error classes** — codes in SQLSTATE class `22` (data exception), `23` (integrity constraint), and `44` (WITH CHECK OPTION) map to HTTP 400. Common codes get a specific message; any other in-class code uses the fallback (`"Invalid database request"`).
-
-| Class | Codes with a specific message |
-|-------|-------------------------------|
-| `23` Integrity | `23505` unique · `23503` foreign key · `23502` not null · `23514` check · `23P01` exclusion · `23000` integrity · `23001` restrict |
-| `22` Data exception | `22001` string too long · `22003` numeric range · `22004` null not allowed · `22007` datetime format · `22008` datetime overflow · `22009` tz displacement · `22011` substring · `22012` division by zero · `22023` invalid parameter · `22025` invalid escape · `22026` length mismatch · `22030` duplicate JSON key · `22032` invalid JSON · `22P01` floating-point · `22P02` invalid text · `22P03` invalid binary · `22P05` untranslatable char |
-| `44` View check | `44000` WITH CHECK OPTION violation |
-
-:::tip Transient conflicts return 409, not 400/500
-Class `40` (`40001` serialization failure, `40P01` deadlock) is **transient/retryable** and returns **409 Conflict** with `messageCode: "database.conflict"` and a safe "please retry" message — the client can safely retry the same request. Programming/infra classes (`42` syntax, `53` resources, `0A`, `25`, `28`) remain 500.
-:::
-
-#### API Reference
-
-##### `appErrorHandler(options)`
-
-**Parameters:**
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `logger` | `ApplicationLogger` | Yes | Logger instance for error logging |
-
-**Returns:** `ErrorHandler` - Hono error handler function
-
-#### Common Patterns
-
-```typescript
-// Custom error with status code
-class NotFoundError extends Error {
-  statusCode = 404;
-
-  constructor(message: string) {
-    super(message);
-    this.name = 'NotFoundError';
-  }
-}
-
-// Throw in controller
-const GetUserConfig = {
-  method: HTTP.Methods.GET,
-  path: '/users/:id',
-  request: {
-    params: z.object({ id: z.string() }),
-  },
-  responses: jsonResponse({
-    schema: z.object({ id: z.string(), name: z.string() }),
-  }),
-} as const;
-
-@get({ configs: GetUserConfig })
-async getUser(c: TRouteContext) {
-  const { id } = c.req.valid<{ id: string }>('param');
-  const user = await this.userRepository.findById(id);
-  if (!user) {
-    throw new NotFoundError(`User ${id} not found`);
-  }
-  return c.json(user, HTTP.ResultCodes.RS_2.Ok);
-}
-```
-
-
-### Not Found Handler (`notFoundHandler`)
-
-Handles requests to routes that don't exist, returning a standardized 404 response.
-
-**File:** `packages/core/src/base/middlewares/not-found.middleware.ts`
-
-#### Usage
-
-```typescript
-import { notFoundHandler } from '@venizia/ignis';
-
-const app = new IgnisApplication({
-  // ...
-});
-
-// Register 404 handler
-app.notFound(notFoundHandler({
-  logger: app.logger
-}));
-```
-
-#### Response Format
-
-```json
-{
-  "message": "URL NOT FOUND",
-  "path": "/api/nonexistent",
-  "url": "http://localhost:3000/api/nonexistent"
-}
-```
-
-**Status Code:** `404 Not Found`
-
-#### API Reference
-
-##### `notFoundHandler(options)`
-
-**Parameters:**
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `logger` | `ApplicationLogger` | No | `console` | Logger instance for logging 404s |
-
-**Returns:** `NotFoundHandler` - Hono not found handler function
-
-
-### Request Spy (`RequestSpyMiddleware`)
-
-Logs detailed information about each request including timing, IP address, method, path, query parameters, and request body. Also handles request body parsing for JSON, form data, and text content types.
-
-**File:** `packages/core/src/base/middlewares/request-spy.middleware.ts`
-
-#### Features
-
-- Request lifecycle logging (incoming/outgoing)
-- Performance timing tracking
-- IP address extraction (supports `x-real-ip` and `x-forwarded-for` headers)
-- Request ID tracking
-- Query and body parameter logging (body only logged in non-production)
-- **Request body parsing**: Automatically parses and caches request bodies:
-  - `application/json` → `req.json()`
-  - `multipart/form-data`, `application/x-www-form-urlencoded` → `req.parseBody()`
-  - Other content types (text, html, xml) → `req.text()`
-
-#### Usage
-
-```typescript
-import { RequestSpyMiddleware } from '@venizia/ignis';
-
-const app = new IgnisApplication({
-  // ...
-});
-
-// Create and register spy middleware
-const requestSpy = new RequestSpyMiddleware();
-app.use(requestSpy.value());
-```
-
-#### Log Output
-
-**Request Start:**
-```
-[spy][abc123] START  | Handling Request | forwardedIp: 192.168.1.1 | path: /api/users | method: GET
-```
-
-**Request Complete:**
-```
-[spy][abc123] DONE   | Handling Request | forwardedIp: 192.168.1.1 | path: /api/users | method: GET | Took: 45.23 (ms)
-```
-
-#### API Reference
-
-##### `RequestSpyMiddleware`
-
-**Class Methods:**
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `value()` | `MiddlewareHandler` | Returns the middleware handler |
-
-**Static Properties:**
-| Property | Type | Value | Description |
-|----------|------|-------|-------------|
-| `REQUEST_ID_KEY` | `string` | `'requestId'` | Context key for request ID |
-
-#### Accessing Request ID
-
-```typescript
-import { RequestSpyMiddleware, get, jsonResponse, TRouteContext, z } from '@venizia/ignis';
-import { HTTP } from '@venizia/ignis-helpers';
-
-const ExampleConfig = {
-  method: HTTP.Methods.GET,
-  path: '/example',
-  responses: jsonResponse({
-    schema: z.object({ requestId: z.string() }),
-  }),
-} as const;
-
-// In a controller
-@get({ configs: ExampleConfig })
-async example(c: TRouteContext) {
-  const requestId = c.get(RequestSpyMiddleware.REQUEST_ID_KEY);
-  console.log('Request ID:', requestId);
-  return c.json({ requestId }, HTTP.ResultCodes.RS_2.Ok);
-}
-```
-
-:::warning Performance Impact
-Request spy logs every request detail. Consider disabling or reducing verbosity in production environments with high traffic.
-:::
-
-
-### Emoji Favicon
-
-Serves an SVG emoji as the application's favicon, providing a lightweight alternative to traditional favicon files.
-
-**File:** `packages/core/src/base/middlewares/emoji-favicon.middleware.ts`
-
-#### Usage
-
-```typescript
-import { emojiFavicon } from '@venizia/ignis';
-
-const app = new IgnisApplication({
-  // ...
-});
-
-// Serve a rocket emoji as favicon
-app.use(emojiFavicon({ icon: '🚀' }));
-```
-
-#### How It Works
-
-1. Intercepts requests to `/favicon.ico`
-2. Returns an inline SVG with the specified emoji
-3. Sets `Content-Type: image/svg+xml`
-4. All other requests pass through unchanged
-
-#### API Reference
-
-##### `emojiFavicon(options)`
-
-**Parameters:**
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `icon` | `string` | Yes | Emoji character to use as favicon |
-
-**Returns:** `MiddlewareHandler` - Hono middleware function
-
-#### Examples
-
-```typescript
-// Different emoji icons
-app.use(emojiFavicon({ icon: '🔥' })); // Fire
-app.use(emojiFavicon({ icon: '⚡' })); // Lightning
-app.use(emojiFavicon({ icon: '🎯' })); // Target
-app.use(emojiFavicon({ icon: '🌟' })); // Star
-```
-
-:::tip Browser Support
-SVG favicons are supported in all modern browsers. Fallback to a traditional `.ico` file if you need to support legacy browsers.
-:::
-
-
-## Creating Custom Middleware
-
-IGNIS uses Hono's middleware system. Create custom middleware using the `createMiddleware` factory:
-
-### Basic Middleware
-
-```typescript
-import { createMiddleware } from 'hono/factory';
-import type { MiddlewareHandler } from 'hono';
-
-export const myMiddleware = (): MiddlewareHandler => {
-  return createMiddleware(async (context, next) => {
-    // Before request handling
-    console.log('Before:', context.req.path);
-
-    await next();
-
-    // After request handling
-    console.log('After:', context.req.path);
-  });
-};
-```
-
-### Middleware with Options
-
-```typescript
-interface MyMiddlewareOptions {
-  enabled: boolean;
-  prefix?: string;
-}
-
-export const myMiddleware = (opts: MyMiddlewareOptions): MiddlewareHandler => {
-  const { enabled, prefix = 'LOG' } = opts;
-
-  return createMiddleware(async (context, next) => {
-    if (enabled) {
-      console.log(`[${prefix}]`, context.req.path);
-    }
-    await next();
-  });
-};
-
-// Usage
-app.use(myMiddleware({ enabled: true, prefix: 'API' }));
-```
-
-### Provider-Based Middleware
-
-For middleware requiring dependency injection:
-
-```typescript
-import { BaseHelper } from '@venizia/ignis-helpers';
-import { IProvider } from '@venizia/ignis-inversion';
-import { injectable } from '@venizia/ignis-inversion';
-import { createMiddleware } from 'hono/factory';
-import type { MiddlewareHandler } from 'hono';
-
-@injectable()
-export class MyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
-  constructor() {
-    super({ scope: MyMiddleware.name });
-  }
-
-  value(): MiddlewareHandler {
-    return createMiddleware(async (context, next) => {
-      this.logger.info('Processing request:', context.req.path);
-      await next();
-    });
-  }
-}
-
-// Usage
-const myMiddleware = app.get(MyMiddleware);
-app.use(myMiddleware.value());
-```
-
-
-## Middleware Order & Priority
-
-Middleware execution order matters. Follow these guidelines:
-
-### Recommended Order
-
-```typescript
-const app = new IgnisApplication({ /* ... */ });
-
-// 1. CORS (if needed)
-app.use(cors());
-
-// 2. Request ID generation
-app.use(requestId());
-
-// 3. Request spy/logging (also handles body parsing)
-const requestSpy = new RequestSpyMiddleware();
-app.use(requestSpy.value());
-
-// 4. Security middleware (helmet, etc.)
-app.use(helmet());
-
-// 5. Rate limiting
-app.use(rateLimit());
-
-// 6. Authentication
-app.use('/api/*', authenticate());
-
-// 7. Favicon (can be early or late)
-app.use(emojiFavicon({ icon: '🚀' }));
-
-// 8. Application routes
-app.mountControllers();
-
-// 9. Error handler (LAST in chain)
-app.onError(appErrorHandler({ logger: app.logger }));
-
-// 10. Not found handler (AFTER error handler)
-app.notFound(notFoundHandler({ logger: app.logger }));
-```
-
-### Key Principles
-
-1. **Request ID First**: Generate request ID before logging
-2. **Request Spy Early**: Log and parse request bodies before business logic
-3. **Security Middleware Before Routes**: Protect routes with security checks
-4. **Error Handler Last**: Catch all errors from previous middleware
-5. **404 Handler After Error Handler**: Ensure unhandled routes return 404
-
-:::warning Order Matters
-Placing error handler before routes will prevent it from catching route errors. Always register error handlers last.
-:::
-
-
-## Common Patterns
-
-### Conditional Middleware
-
-```typescript
-const app = new IgnisApplication({ /* ... */ });
-
-// Enable request spy only in development
-if (process.env.NODE_ENV === 'development') {
-  const requestSpy = new RequestSpyMiddleware();
-  app.use(requestSpy.value());
-}
-```
-
-### Route-Specific Middleware
-
-```typescript
-// Apply middleware to specific routes
-app.use('/api/admin/*', adminAuthMiddleware());
-app.use('/api/public/*', rateLimitMiddleware());
-```
-
-### Middleware Composition
-
-```typescript
-// Combine multiple middleware
-const apiMiddleware = (): MiddlewareHandler => {
-  return createMiddleware(async (context, next) => {
-    // Run multiple middleware in sequence
-    await rateLimit()(context, async () => {
-      await authenticate()(context, next);
-    });
-  });
-};
-```
-
-
-## Performance Considerations
-
-### Request Spy in Production
-
-Request spy logs detailed information for every request. In high-traffic production environments:
-
-```typescript
-// Conditional request spy
-const isDevelopment = process.env.NODE_ENV === 'development';
-
-if (isDevelopment) {
-  const requestSpy = new RequestSpyMiddleware();
-  app.use(requestSpy.value());
-}
-```
-
-### Error Logging Volume
-
-Error handlers log every error. For high error rates, consider:
-- Sampling (log 1 in N errors)
-- Error aggregation services (Sentry, Rollbar)
-- Rate-limited logging
-
-
-## See Also
-
-- **Related References:**
-  - [Application](./application.md) - Application setup and configuration
-  - [Controllers](./controllers.md) - HTTP routing and request handling
-  - [Dependency Injection](./dependency-injection.md) - DI container and providers
-
-- **Guides:**
-  - [Building a CRUD API](/guides/tutorials/building-a-crud-api)
-
-- **Best Practices:**
-  - [Troubleshooting Tips](/best-practices/troubleshooting-tips)
-
-- **External Resources:**
-  - [Hono Middleware Documentation](https://hono.dev/docs/guides/middleware)
-  - [HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)