@venizia/ignis-docs 0.0.7 → 0.0.8-0

package/wiki/references/base/index.md

@@ -7,7 +7,8 @@ Core classes that power every Ignis application - from the Application entry poi
 | Class | Purpose | Extends |
 |-------|---------|---------|
 | `BaseApplication` | Application entry point, DI container | `AbstractApplication` |
-| `BaseController` | HTTP route handlers | - |
+| `BaseRestController` | REST/HTTP route handlers | `AbstractRestController` |
+| `BaseGrpcController` | gRPC route handlers (ConnectRPC) | `AbstractGrpcController` |
 | `BaseService` | Business logic layer | - |
 | `BaseProvider` | Factory pattern for runtime instantiation | `BaseHelper` |
 | `BaseComponent` | Pluggable feature modules | - |
@@ -19,29 +20,31 @@ Core classes that power every Ignis application - from the Application entry poi
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────┐
 │                     BaseApplication                          │
 │  (DI Container + Lifecycle + Server Management)              │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │                                                              │
-│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐     │
-│  │ BaseController│   │ BaseService  │   │BaseComponent │     │
-│  │ (HTTP Layer) │   │(Business Logic)│  │ (Plugins)   │     │
-│  └──────┬───────┘   └──────┬───────┘   └──────────────┘     │
-│         │                  │                                 │
-│         └────────┬─────────┘                                 │
-│                  ▼                                           │
-│         ┌──────────────────┐                                 │
-│         │DefaultCRUDRepository│                              │
-│         │  (Data Access)    │                                │
-│         └────────┬──────────┘                                │
-│                  │                                           │
-│         ┌────────┴────────┐                                  │
-│         ▼                 ▼                                  │
-│  ┌────────────┐   ┌────────────┐                             │
-│  │BaseDataSource│  │ BaseEntity │                            │
-│  │(Connection) │  │  (Schema)  │                             │
-│  └─────────────┘  └────────────┘                             │
+│  ┌──────────────────┐  ┌─────────────┐  ┌──────────────┐    │
+│  │BaseRestController │  │ BaseService  │  │BaseComponent │    │
+│  │  (REST Layer)     │  │(Biz Logic)  │  │ (Plugins)    │    │
+│  ├──────────────────┤  └──────┬───────┘  └──────────────┘    │
+│  │BaseGrpcController │        │                              │
+│  │  (gRPC Layer)     │        │                              │
+│  └────────┬──────────┘        │                              │
+│           └─────────┬─────────┘                              │
+│                     ▼                                        │
+│          ┌──────────────────────┐                            │
+│          │DefaultCRUDRepository │                            │
+│          │  (Data Access)       │                            │
+│          └──────────┬───────────┘                            │
+│                     │                                        │
+│          ┌──────────┴──────────┐                             │
+│          ▼                     ▼                             │
+│   ┌──────────────┐      ┌────────────┐                      │
+│   │BaseDataSource │      │ BaseEntity │                      │
+│   │(Connection)   │      │  (Schema)  │                      │
+│   └───────────────┘      └────────────┘                      │
 │                                                              │
 └──────────────────────────────────────────────────────────────┘
 ```
@@ -52,8 +55,9 @@ Core classes that power every Ignis application - from the Application entry poi
 - [Application](./application.md) - `BaseApplication` class, resource registration, lifecycle hooks
 - [Bootstrapping](./bootstrapping.md) - Startup sequence, `initialize()` flow
 
-### HTTP Layer
-- [Controllers](./controllers.md) - Route handlers, decorators, request/response handling
+### Transport Layer
+- [REST Controllers](./controllers.md) - REST route handlers, decorators, request/response handling
+- [gRPC Controllers](./grpc-controllers.md) - gRPC/ConnectRPC handlers, RPC decorators
 - [Middlewares](./middlewares.md) - Built-in middlewares for error handling, logging, and request processing
 - [Services](./services.md) - Business logic, injectable services
 
@@ -79,7 +83,11 @@ AbstractRepository
 │   └── PersistableRepository
 │       └── DefaultCRUDRepository ──────► Your Repository
 │
-BaseController ──────► Your Controller
+AbstractRestController
+└── BaseRestController ──────► Your REST Controller
+
+AbstractGrpcController
+└── BaseGrpcController ──────► Your gRPC Controller
 BaseService ──────► Your Service
 BaseProvider ──────► Your Provider
 BaseComponent ──────► Your Component

package/wiki/references/base/middleware.md

@@ -0,0 +1,347 @@
+---
+title: Middleware Reference
+description: Technical reference for built-in middlewares in IGNIS
+difficulty: intermediate
+lastUpdated: 2026-03-15
+---
+
+# Middleware Reference
+
+IGNIS provides built-in middleware functions and a provider-based middleware class for handling common HTTP concerns: error handling, request logging, 404 responses, and favicon serving. These are registered automatically by `BaseApplication` during startup.
+
+**Files:**
+- `packages/core/src/base/middlewares/app-error.middleware.ts`
+- `packages/core/src/base/middlewares/not-found.middleware.ts`
+- `packages/core/src/base/middlewares/request-spy.middleware.ts`
+- `packages/core/src/base/middlewares/emoji-favicon.middleware.ts`
+
+## Prerequisites
+
+Before reading this document, you should understand:
+- [Hono middleware](https://hono.dev/docs/guides/middleware) basics
+- [Application lifecycle](./application.md)
+- [Providers](./providers.md) - `RequestSpyMiddleware` implements `IProvider`
+
+## Quick Reference
+
+| Middleware | Type | Purpose |
+|-----------|------|---------|
+| `appErrorHandler` | `ErrorHandler` | Global error handler (Zod, DB constraints, generic) |
+| `notFoundHandler` | `NotFoundHandler` | JSON 404 response for unknown routes |
+| `RequestSpyMiddleware` | `IProvider<MiddlewareHandler>` | Request/response logging with timing |
+| `emojiFavicon` | `MiddlewareHandler` | Serves an emoji as SVG favicon |
+
+## Default Registration Order
+
+`BaseApplication.registerDefaultMiddlewares()` registers middleware in this order during `initialize()`:
+
+```typescript
+protected async registerDefaultMiddlewares() {
+  const server = this.getServer();
+
+  // 1. Global error handler
+  server.onError(appErrorHandler({ logger, rootKey }));
+
+  // 2. Async context storage (if enabled)
+  if (this.configs.asyncContext?.enable) {
+    server.use(contextStorage());
+  }
+
+  // 3. Not-found handler
+  server.notFound(notFoundHandler({ logger }));
+
+  // 4. RequestTrackerComponent (requestId + RequestSpyMiddleware)
+  this.component(RequestTrackerComponent);
+
+  // 5. Emoji favicon
+  server.use(emojiFavicon({ icon: this.configs.favicon ?? '🔥' }));
+}
+```
+
+After `registerDefaultMiddlewares()`, the application calls user-defined `staticConfigure()`, `preConfigure()`, and so on. The user's `setupMiddlewares()` hook runs after `initialize()` but before the server starts.
+
+## appErrorHandler
+
+Global error handler registered via `server.onError()`. Handles ZodError validation errors, PostgreSQL constraint violations, and generic errors.
+
+### Signature
+
+```typescript
+function appErrorHandler(opts: {
+  logger: Logger;
+  rootKey?: string;
+}): ErrorHandler
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `logger` | `Logger` | Logger instance for error logging |
+| `rootKey` | `string \| undefined` | Optional root key to wrap the error response object |
+
+### Error Handling Logic
+
+#### 1. ZodError (Validation Errors)
+
+When `error.name === 'ZodError'`, returns HTTP `422 Unprocessable Entity`:
+
+```json
+{
+  "message": "ValidationError",
+  "statusCode": 422,
+  "requestId": "abc-123",
+  "details": {
+    "url": "http://localhost:3000/users",
+    "path": "/users",
+    "stack": "...(non-production only)",
+    "cause": [
+      {
+        "path": "email",
+        "message": "Invalid email",
+        "code": "invalid_string",
+        "expected": "string",
+        "received": "undefined"
+      }
+    ]
+  }
+}
+```
+
+#### 2. PostgreSQL Constraint Violations
+
+Database errors with recognized SQLSTATE codes return HTTP `400 Bad Request` instead of 500:
+
+| SQLSTATE Code | Error Type |
+|--------------|------------|
+| `23505` | Unique constraint violation |
+| `23503` | Foreign key constraint violation |
+| `23502` | Not null constraint violation |
+| `23514` | Check constraint violation |
+| `23P01` | Exclusion constraint violation |
+| `22P02` | Invalid text representation |
+| `22003` | Numeric value out of range |
+| `22001` | String data too long |
+
+The error response includes detail, table, and constraint information when available from the database error's `cause` property.
+
+#### 3. Generic Errors
+
+All other errors use the `statusCode` property from the error if present, otherwise default to HTTP `500 Internal Server Error`.
+
+### Response Format
+
+```json
+{
+  "message": "Error message",
+  "statusCode": 500,
+  "requestId": "abc-123",
+  "details": {
+    "url": "http://localhost:3000/users",
+    "path": "/users",
+    "stack": "...(non-production only)",
+    "cause": "...(non-production only)"
+  }
+}
+```
+
+When `rootKey` is provided (e.g., `rootKey: 'error'`), the response is wrapped:
+
+```json
+{
+  "error": {
+    "message": "Error message",
+    "statusCode": 500,
+    "requestId": "abc-123",
+    "details": { ... }
+  }
+}
+```
+
+**Production behavior:** `stack` and `cause` fields are omitted when `NODE_ENV` is `'production'`.
+
+
+## notFoundHandler
+
+Returns a JSON 404 response when no route matches. Registered via `server.notFound()`.
+
+### Signature
+
+```typescript
+function notFoundHandler(opts: {
+  logger?: Logger;
+}): NotFoundHandler
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `logger` | `Logger \| undefined` | Logger instance (defaults to `console`) |
+
+### Response Format
+
+```json
+{
+  "message": "URL NOT FOUND",
+  "statusCode": 404,
+  "requestId": "abc-123",
+  "path": "/unknown",
+  "url": "http://localhost:3000/unknown"
+}
+```
+
+The handler logs the 404 at error level with the request ID, path, and full URL.
+
+
+## RequestSpyMiddleware
+
+A provider-based middleware class that logs incoming request details and outgoing response timing. It extends `BaseHelper` and implements `IProvider<MiddlewareHandler>`.
+
+### Class Definition
+
+```typescript
+export class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
+  static readonly REQUEST_ID_KEY = 'requestId';
+
+  constructor() {
+    super({ scope: 'SpyMW' });
+  }
+
+  async parseBody(opts: { req: TContext['req'] }): Promise<unknown>;
+  value(): MiddlewareHandler;
+}
+```
+
+### How It Is Registered
+
+`RequestSpyMiddleware` is not registered directly. Instead, `BaseApplication.registerDefaultMiddlewares()` registers a `RequestTrackerComponent`, which:
+
+1. Adds the `requestId()` middleware from `hono/request-id` to assign a unique ID to every request
+2. Binds `RequestSpyMiddleware` as a singleton provider in the DI container
+3. Resolves the middleware via `IProvider.value()` and registers it with `server.use()`
+
+### Request Logging
+
+In **non-production** mode, logs the full request including query and body:
+
+```
+[requestId][clientIp][=>] METHOD   /path | query: {...} | body: {...}
+```
+
+In **production** mode, body is excluded:
+
+```
+[requestId][clientIp][=>] METHOD   /path | query: {...}
+```
+
+### Response Logging
+
+After the handler completes:
+
+```
+[requestId][clientIp][<=] METHOD   /path | Took: 12.34 (ms)
+```
+
+### Body Parsing
+
+The `parseBody` method parses the request body based on `Content-Type`:
+
+| Content-Type | Parse Method |
+|-------------|-------------|
+| `application/json` | `req.json()` |
+| `multipart/form-data` | `req.parseBody()` |
+| `application/x-www-form-urlencoded` | `req.parseBody()` |
+| Other | `req.text()` |
+
+Returns `null` if no `Content-Type` header or `Content-Length` is `0`/missing. Throws HTTP 400 `'Malformed Body Payload'` on parse failure.
+
+### IP Detection
+
+The middleware resolves the client IP from the connection info or falls back to `x-real-ip` / `x-forwarded-for` headers. If neither is available, it throws HTTP 400 `'Malformed Connection Info'`.
+
+
+## emojiFavicon
+
+A simple middleware that serves an emoji as an SVG favicon on `/favicon.ico`.
+
+### Signature
+
+```typescript
+function emojiFavicon(opts: { icon: string }): MiddlewareHandler
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `icon` | `string` | Emoji character to use as favicon |
+
+### Behavior
+
+- Only intercepts requests to `/favicon.ico`
+- Returns an SVG with `content-type: image/svg+xml`
+- All other requests pass through via `next()`
+
+**Default icon:** The application uses `this.configs.favicon ?? '🔥'` when registering.
+
+
+## Middleware Configuration via IApplicationConfigs
+
+Several middleware behaviors are configured through `IApplicationConfigs`:
+
+```typescript
+interface IApplicationConfigs {
+  favicon?: string;                    // Emoji for emojiFavicon (default: '🔥')
+  error?: { rootKey: string };         // Root key wrapper for appErrorHandler
+  asyncContext?: { enable: boolean };  // Enable Hono contextStorage() middleware
+  // ...
+}
+```
+
+## User-Defined Middlewares
+
+The `setupMiddlewares()` abstract method on `AbstractApplication` is called after `initialize()` and before the server starts. Use this hook to register additional Hono middlewares:
+
+```typescript
+export class MyApplication extends BaseApplication {
+  async setupMiddlewares() {
+    const server = this.getServer();
+
+    // CORS
+    server.use(cors({ origin: '*' }));
+
+    // Body limit
+    server.use(bodyLimit({ maxSize: 1024 * 1024 })); // 1MB
+  }
+}
+```
+
+The `IMiddlewareConfigs` type defines the shape for configurable middleware options:
+
+```typescript
+interface IMiddlewareConfigs {
+  requestId?: IRequestIdOptions;
+  compress?: ICompressOptions;
+  cors?: ICORSOptions;
+  csrf?: ICSRFOptions;
+  bodyLimit?: IBodyLimitOptions;
+  ipRestriction?: IBaseMiddlewareOptions & IIPRestrictionRules;
+  [extra: string | symbol]: any;
+}
+```
+
+Each option interface extends `IBaseMiddlewareOptions`:
+
+```typescript
+interface IBaseMiddlewareOptions {
+  enable: boolean;
+  path?: string;
+  [extra: string | symbol]: any;
+}
+```
+
+
+## See Also
+
+- **Related References:**
+  - [Application](./application.md) - Application lifecycle and initialization
+  - [Providers](./providers.md) - Provider pattern (`RequestSpyMiddleware` implements `IProvider`)
+  - [Components](./components.md) - `RequestTrackerComponent`
+
+- **Guides:**
+  - [Application Guide](/guides/core-concepts/application/)