@venizia/ignis-docs 0.0.5 → 0.0.6-0

package/wiki/references/components/health-check.md

@@ -1,45 +1,64 @@
-# Health Check Component
+# Health Check
 
-Simple endpoint for monitoring application health - essential for microservices and containerized deployments.
+Simple endpoint for monitoring application health -- essential for microservices and containerized deployments.
 
 ## Quick Reference
 
-| Component | Purpose |
-|-----------|---------|
-| **HealthCheckComponent** | Registers health check controller |
-| **HealthCheckController** | Provides health check routes |
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis` |
+| **Class** | `HealthCheckComponent` |
+| **Controller** | `HealthCheckController` |
+| **Runtimes** | Both |
 
-### Default Endpoints
+#### Import Paths
+```typescript
+import { HealthCheckComponent, HealthCheckBindingKeys } from '@venizia/ignis';
+import type { IHealthCheckOptions } from '@venizia/ignis';
+```
 
-| Method | Path | Purpose | Response |
-|--------|------|---------|----------|
-| `GET` | `/health` | Basic health check | `{ "status": "ok" }` |
-| `POST` | `/health/ping` | Echo test | `{ "type": "PONG", "date": "...", "message": "..." }` |
+## Setup
 
-### Configuration
+### Step 1: Bind Configuration (Optional)
+
+Skip this step to use the default `/health` path. To customize the path:
+
+```typescript
+import { HealthCheckBindingKeys, IHealthCheckOptions } from '@venizia/ignis';
+
+// In your Application class's preConfigure method
+this.bind<IHealthCheckOptions>({
+  key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS,
+}).toValue({
+  restOptions: { path: '/health-check' },
+});
+```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `restOptions.path` | `/health` | Base path for health endpoints |
+### Step 2: Register Component
 
-## Architecture Components
+```typescript
+import { HealthCheckComponent } from '@venizia/ignis';
 
--   **`HealthCheckComponent`**: Registers `HealthCheckController`
--   **`HealthCheckController`**: Uses decorators (`@api`) to define routes
--   **Self-contained**: No external dependencies required
+preConfigure(): ValueOrPromise<void> {
+  // ... optional bindings from Step 1
+  this.component(HealthCheckComponent);
+}
+```
 
-## Implementation Details
+### Step 3: Use
 
-### Tech Stack
+The health check endpoints are auto-registered -- no injection needed. Once the component is registered, `GET /health` and `POST /health/ping` are available immediately.
 
--   **Hono**
--   **`@hono/zod-openapi`**
+> [!TIP]
+> If you customized the path in Step 1, the endpoints will be at your custom path instead (e.g., `GET /health-check` and `POST /health-check/ping`).
 
-### Configuration
+## Configuration
 
-The health check endpoint path can be configured by binding a custom `IHealthCheckOptions` object to the `HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS` key in the DI container.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `restOptions.path` | `string` | `'/health'` | Base path for health endpoints |
 
-**Default options:**
+The component uses `IHealthCheckOptions` bound to `HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS`. If no custom binding is found, it falls back to:
 
 ```typescript
 const DEFAULT_OPTIONS: IHealthCheckOptions = {
@@ -47,40 +66,161 @@ const DEFAULT_OPTIONS: IHealthCheckOptions = {
 };
 ```
 
-#### Customizing the Health Check Path
+#### IHealthCheckOptions -- Full Reference
+```typescript
+interface IHealthCheckOptions {
+  restOptions: { path: string };
+}
+```
+
+The `path` value is applied via `@controller({ path })` decorator on `HealthCheckController` during the component's `binding()` phase. All controller routes are relative to this base path.
 
-In your `src/application.ts`, you can bind your custom options:
+### Component Lifecycle
+
+1. **`constructor()`** -- Receives `BaseApplication` via `@inject({ key: CoreBindings.APPLICATION_INSTANCE })`. Calls `super()` with `initDefault: { enable: true, container: application }` and provides default bindings for `HEALTH_CHECK_OPTIONS`:
 
 ```typescript
-import { HealthCheckBindingKeys, IHealthCheckOptions, HealthCheckComponent } from '@venizia/ignis';
+constructor(
+  @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
+) {
+  super({
+    scope: HealthCheckComponent.name,
+    initDefault: { enable: true, container: application },
+    bindings: {
+      [HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS]: Binding.bind<IHealthCheckOptions>({
+        key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS,
+      }).toValue(DEFAULT_OPTIONS),
+    },
+  });
+}
+```
+
+The `initDefault: { enable: true, container: application }` option tells `BaseComponent` to automatically register all entries in `this.bindings` into the DI container before `binding()` is called. This happens inside `BaseComponent.configure()` via `initDefaultBindings()`, which iterates over `this.bindings` and calls `container.set()` for any key not already bound. This means users who bind their own `HEALTH_CHECK_OPTIONS` before registering the component will keep their custom value -- the default is only applied if the key is unbound.
 
-// ... in your Application class's preConfigure method
-  preConfigure(): ValueOrPromise<void> {
-    // ...
-    this.bind<IHealthCheckOptions>({
+2. **`binding()`** -- Reads options from the DI container using `application.get()` with `isOptional: true` and falls back to `DEFAULT_OPTIONS` via the `??` operator. Applies `@controller({ path })` decorator dynamically to `HealthCheckController` using `Reflect.decorate`. Registers the controller with the application:
+
+```typescript
+override binding(): ValueOrPromise<void> {
+  const healthOptions =
+    this.application.get<IHealthCheckOptions>({
       key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS,
-    }).toValue({
-      restOptions: { path: '/health-check' },
-    });
-    this.component(HealthCheckComponent);
-    // ...
-  }
+      isOptional: true,
+    }) ?? DEFAULT_OPTIONS;
+
+  Reflect.decorate(
+    [controller({ path: healthOptions.restOptions.path })],
+    HealthCheckController,
+  );
+  this.application.controller(HealthCheckController);
+}
 ```
 
-### Code Samples
+> [!NOTE]
+> The `@controller` decorator is applied dynamically during `binding()`, not statically on the class definition. This allows the path to be configured at runtime via DI bindings.
+
+## Binding Keys
+
+| Key | Constant | Type | Required | Default |
+|-----|----------|------|----------|---------|
+| `@app/health-check/options` | `HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS` | `IHealthCheckOptions` | No | `{ restOptions: { path: '/health' } }` |
 
-#### Controller Implementation
+> [!NOTE]
+> The component provides a default binding for `HEALTH_CHECK_OPTIONS` via `initDefault`. You only need to bind this key if you want to customize the endpoint path. If you do bind it, do so **before** calling `this.component(HealthCheckComponent)` -- the `initDefaultBindings()` check uses `isBound()` and will skip keys that already exist in the container.
 
-The `HealthCheckController` is a simple controller that uses decorators to define its routes. It now includes a `GET /` for a simple status check and a `POST /ping` that echoes a message.
+### Rest Paths
+
+| Constant | Value | Full Path (default) |
+|----------|-------|---------------------|
+| `HealthCheckRestPaths.ROOT` | `/` | `GET /health` |
+| `HealthCheckRestPaths.PING` | `/ping` | `POST /health/ping` |
+
+### Rest Path Constants
 
 ```typescript
-// packages/core/src/components/health-check/controller.ts
-import { BaseController, IControllerOptions, TRouteContext, api, jsonContent, jsonResponse, HTTP, z } from '@venizia/ignis';
+class HealthCheckRestPaths {
+  static readonly ROOT = '/';    // GET /health (or custom base path)
+  static readonly PING = '/ping'; // POST /health/ping (or custom base path + /ping)
+}
+```
+
+The controller defines two internal route paths via `HealthCheckRestPaths`. These paths are relative to the base path configured in `IHealthCheckOptions.restOptions.path`.
+
+## API Endpoints
+
+| Method | Path | Description | Response |
+|--------|------|-------------|----------|
+| `GET` | `/health` | Basic health check | `{ "status": "ok" }` |
+| `POST` | `/health/ping` | Echo test | `{ "type": "PONG", "date": "...", "message": "..." }` |
+
+### GET /health
+
+Returns a simple health status object. Used by load balancers, Kubernetes liveness probes, and monitoring tools to verify the application is running.
+
+### POST /health/ping
+
+Echoes a message back with a server timestamp. Useful for:
+- Verifying end-to-end connectivity
+- Measuring round-trip latency
+- Testing request body parsing
+
+#### Request & Response Specifications
+
+**GET /health**
+
+Response `200`:
+```json
+{
+  "status": "ok"
+}
+```
+
+**POST /health/ping**
+
+Request body:
+```json
+{
+  "type": "PING",
+  "message": "Any string here"
+}
+```
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| `type` | `string` | No | Defaults to `"PING"` |
+| `message` | `string` | Yes | Min 1, max 255 characters |
+
+Response `200`:
+```json
+{
+  "type": "PONG",
+  "date": "2026-02-11T12:00:00.000Z",
+  "message": "Any string here"
+}
+```
+
+### Route Definition Patterns
+
+The `HealthCheckController` demonstrates all three route definition patterns supported by Ignis:
 
-const ROUTE_CONFIGS = {
-  '/': {
+| Pattern | Method | Used For |
+|---------|--------|----------|
+| **Fluent API** (`bindRoute().to()`) | Root health check (`GET /`) | Inline handlers, method chaining |
+| **Imperative API** (`defineRoute()`) | (commented out in source) | Direct handler assignment in `binding()` |
+| **Decorator API** (`@api()`) | Ping endpoint (`POST /ping`) | Class method handlers with OpenAPI metadata |
+
+The controller uses `this.definitions = RouteConfigs` to store route configurations for introspection. This is optional but enables tools to discover available routes without invoking `binding()`.
+
+#### Controller Source
+```typescript
+import {
+  BaseController, IControllerOptions, TRouteContext,
+  api, jsonContent, jsonResponse, HTTP, z,
+} from '@venizia/ignis';
+
+const RouteConfigs = {
+  ROOT: {
     method: HTTP.Methods.GET,
-    path: '/',
+    path: HealthCheckRestPaths.ROOT,
     responses: jsonResponse({
       schema: z.object({ status: z.string() }).openapi({
         description: 'HealthCheck Schema',
@@ -89,9 +229,9 @@ const ROUTE_CONFIGS = {
       description: 'Health check status',
     }),
   },
-  '/ping': {
+  PING: {
     method: HTTP.Methods.POST,
-    path: '/ping',
+    path: HealthCheckRestPaths.PING,
     request: {
       body: jsonContent({
         description: 'PING | Request body',
@@ -117,26 +257,26 @@ const ROUTE_CONFIGS = {
   },
 } as const;
 
-@controller({ path: '/health' }) // Base path is configured by options
 export class HealthCheckController extends BaseController {
   constructor(opts: IControllerOptions) {
     super({ ...opts, scope: HealthCheckController.name });
-    // Note: This is optional declare internal controller route definitions
-    this.definitions = ROUTE_CONFIGS;
+    this.definitions = RouteConfigs;
   }
 
-  @api({ configs: ROUTE_CONFIGS['/'] })
-  checkHealth(c: TRouteContext) {
-    return c.json({ status: 'ok' }, HTTP.ResultCodes.RS_2.Ok);
+  override binding(): ValueOrPromise<void> {
+    // Fluent API for the root health check
+    this.bindRoute({ configs: RouteConfigs.ROOT }).to({
+      handler: context => {
+        return context.json({ status: 'ok' }, HTTP.ResultCodes.RS_2.Ok);
+      },
+    });
   }
 
-  @api({ configs: ROUTE_CONFIGS['/ping'] })
-  pingPong(c: TRouteContext) {
-    // context.req.valid('json') can be typed explicitly or inferred as unknown
-    const { message } = c.req.valid<{ message: string }>('json');
-
-    // Return type is automatically validated against the response schema
-    return c.json(
+  // Decorator API for the ping endpoint
+  @api({ configs: RouteConfigs.PING })
+  pingPong(context: TRouteContext) {
+    const { message } = context.req.valid<{ type?: string; message: string }>('json');
+    return context.json(
       { type: 'PONG', date: new Date().toISOString(), message },
       HTTP.ResultCodes.RS_2.Ok,
     );
@@ -144,59 +284,108 @@ export class HealthCheckController extends BaseController {
 }
 ```
 
-#### Registering the Health Check Component
+#### Route Configuration Schemas
 
-In your `src/application.ts`, simply register the `HealthCheckComponent`.
+**Root endpoint (`GET /`):**
+```typescript
+const RouteConfigs = {
+  ROOT: {
+    method: HTTP.Methods.GET,
+    path: HealthCheckRestPaths.ROOT,
+    responses: jsonResponse({
+      schema: z.object({ status: z.string() }).openapi({
+        description: 'HealthCheck Schema',
+        examples: [{ status: 'ok' }],
+      }),
+      description: 'Health check status',
+    }),
+  },
+```
 
+**Ping endpoint (`POST /ping`):**
 ```typescript
-// src/application.ts
-import { HealthCheckComponent } from '@venizia/ignis';
+  PING: {
+    method: HTTP.Methods.POST,
+    path: HealthCheckRestPaths.PING,
+    request: {
+      body: jsonContent({
+        description: 'PING | Request body',
+        schema: z.object({
+          type: z.string().optional().default('PING'),
+          message: z.string().min(1).max(255),
+        }),
+      }),
+    },
+    responses: jsonResponse({
+      schema: z.object({
+        type: z.string().optional().default('PONG'),
+        date: z.iso.datetime(),
+        message: z.string(),
+      }).openapi({
+        description: 'HealthCheck PingPong Schema',
+        examples: [{ date: new Date().toISOString(), message: 'ok' }],
+      }),
+      description: 'HealthCheck PingPong Message',
+    }),
+  },
+} as const;
+```
 
-// ... in your Application class's preConfigure method
-  preConfigure(): ValueOrPromise<void> {
-    // ...
-    this.component(HealthCheckComponent);
-    // ...
-  }
+## Troubleshooting
+
+### "Health check endpoint returns 404"
+
+**Cause:** The `HealthCheckComponent` was not registered in your application, or it was registered after controllers were already mounted.
+
+**Fix:** Register the component in `preConfigure()` before any controller registration:
+
+```typescript
+preConfigure(): ValueOrPromise<void> {
+  this.component(HealthCheckComponent);
+  // ... other registrations
+}
 ```
 
-## API or Interface Specifications
-
--   **Endpoint:** `GET /health` (or the custom path you configured)
--   **Method:** `GET`
--   **Success Response (200 OK):**
-    ```json
-    {
-      "status": "ok"
-    }
-    ```
--   **Endpoint:** `POST /health/ping`
--   **Method:** `POST`
--   **Request Body:**
-    ```json
-    {
-      "message": "Any string here"
-    }
-    ```
--   **Success Response (200 OK):**
-    ```json
-    {
-      "type": "PONG",
-      "date": "YYYY-MM-DDTHH:mm:ss.sssZ",
-      "message": "Any string here"
-    }
-    ```
-
-This component provides a simple and effective way to monitor the health of your `Ignis` application.
+### "Custom path is not applied"
+
+**Cause:** The custom `IHealthCheckOptions` binding was registered after the component. The component reads options during its `binding()` phase -- if no binding exists at that point, it uses the default `/health` path. However, because `HealthCheckComponent` uses `initDefault: { enable: true }`, it also registers a default binding before `binding()` runs. If you bind your custom options after calling `this.component()`, the default has already been set and your override will not take effect during the current lifecycle.
+
+**Fix:** Bind your custom options before calling `this.component(HealthCheckComponent)`:
+
+```typescript
+preConfigure(): ValueOrPromise<void> {
+  // Bind options FIRST
+  this.bind<IHealthCheckOptions>({
+    key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS,
+  }).toValue({
+    restOptions: { path: '/custom-health' },
+  });
+
+  // THEN register component
+  this.component(HealthCheckComponent);
+}
+```
+
+### "POST /health/ping returns validation error"
+
+**Cause:** The request body is missing the required `message` field, or the `message` value exceeds the 255-character limit.
+
+**Fix:** Ensure the request body includes a `message` string between 1 and 255 characters:
+
+```json
+{
+  "message": "hello"
+}
+```
 
 ## See Also
 
-- **Related Concepts:**
+- **Guides:**
   - [Components Overview](/guides/core-concepts/components) - Component system basics
   - [Application](/guides/core-concepts/application/) - Registering components
 
-- **Other Components:**
-  - [Components Index](./index) - All built-in components
+- **Components:**
+  - [All Components](./index) - Built-in components list
 
 - **Best Practices:**
   - [Deployment Strategies](/best-practices/deployment-strategies) - Production monitoring

package/wiki/references/components/index.md

@@ -6,13 +6,14 @@ Reusable, pluggable modules that group together related features. A component ca
 
 | Component | Purpose | Key Features |
 |-----------|---------|--------------|
-| [Authentication](./authentication.md) | JWT-based auth | Token generation, protected routes, user payload |
-| [Health Check](./health-check.md) | Monitoring endpoint | `/health` endpoint, ping/pong functionality |
-| [Mail](./mail.md) | Email sending system | Multiple transports, templating, queue-based processing |
-| [Request Tracker](./request-tracker.md) | Request logging | Request ID generation, timing, structured logging |
-| [Socket.IO](./socket-io.md) | Real-time communication | WebSocket support, Redis adapter, event-based |
-| [Static Asset](./static-asset.md) | File management | Upload/download files, MinIO & local filesystem support |
-| [Swagger](./swagger.md) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
+| [Authentication](./authentication/) | JWT/Basic auth | Token generation, protected routes, multi-strategy |
+| [Health Check](./health-check) | Monitoring endpoint | `/health` endpoint, ping/pong functionality |
+| [Mail](./mail/) | Email sending system | Multiple transports, templating, queue-based processing |
+| [Request Tracker](./request-tracker) | Request logging | Request ID generation, timing, structured logging |
+| [Socket.IO](./socket-io/) | Real-time communication | WebSocket support, Redis adapter, event-based |
+| [WebSocket](./websocket/) | Real-time communication | Bun native WebSocket, Redis Pub/Sub, heartbeat |
+| [Static Asset](./static-asset/) | File management | Upload/download files, MinIO & local filesystem support |
+| [Swagger](./swagger) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
 
 ## Creating a Component
 
@@ -70,13 +71,14 @@ Using components is a great way to organize your application's features into mod
   - [Creating Components](/guides/core-concepts/components-guide) - Build your own components
 
 - **Built-in Components:**
-  - [Authentication](./authentication) - JWT authentication
+  - [Authentication](./authentication/) - JWT/Basic authentication
   - [Health Check](./health-check) - Health check endpoints
-  - [Swagger](./swagger) - API documentation
-  - [Socket.IO](./socket-io) - WebSocket support
-  - [Mail](./mail) - Email functionality
+  - [Mail](./mail/) - Email functionality
   - [Request Tracker](./request-tracker) - Request tracking
-  - [Static Asset](./static-asset) - Static file serving
+  - [Socket.IO](./socket-io/) - Socket.IO WebSocket support
+  - [WebSocket](./websocket/) - Bun native WebSocket
+  - [Static Asset](./static-asset/) - Static file serving
+  - [Swagger](./swagger) - API documentation
 
 - **References:**
   - [BaseComponent API](/references/base/components) - Component base class