@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/extensions/components/health-check.md

@@ -1,6 +1,6 @@
 # Health Check
 
-Simple endpoint for monitoring application health -- essential for microservices and containerized deployments.
+A minimal status endpoint for uptime monitoring - the default target for load balancer health checks and Kubernetes liveness probes.
 
 ## Quick Reference
 
@@ -17,200 +17,112 @@ import { HealthCheckComponent, HealthCheckBindingKeys } from '@venizia/ignis';
 import type { IHealthCheckOptions } from '@venizia/ignis';
 ```
 
-## Setup
+## In one example
 
-### 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' },
-});
-```
-
-### Step 2: Register Component
+Register the component with no configuration - `GET /health` and `POST /health/ping` are live immediately.
 
 ```typescript
-import { HealthCheckComponent } from '@venizia/ignis';
+import { HealthCheckComponent, BaseApplication, ValueOrPromise } from '@venizia/ignis';
 
-preConfigure(): ValueOrPromise<void> {
-  // ... optional bindings from Step 1
-  this.component(HealthCheckComponent);
+export class Application extends BaseApplication {
+  preConfigure(): ValueOrPromise<void> {
+    this.component(HealthCheckComponent);
+  }
 }
 ```
 
-### Step 3: Use
+```bash
+curl localhost:3000/health
+# { "status": "ok" }
+```
 
-The health check endpoints are auto-registered -- no injection needed. Once the component is registered, `GET /health` and `POST /health/ping` are available immediately.
+## How it works
 
-> [!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`).
+- **Auto-registered controller.** `HealthCheckComponent.binding()` applies `@controller({ path })` to `HealthCheckController` via `Reflect.decorate` at runtime, then calls `this.application.controller(HealthCheckController)`. The path comes from DI, not a hardcoded class decorator.
+- **Options are optional, field by field.** `IHealthCheckOptions.restOptions.path` is optional; a partially-filled binding (e.g., `{ restOptions: {} }`) still resolves. The component reads `healthOptions?.restOptions?.path ?? '/health'`, falling back per field rather than discarding the whole binding.
+- **The default binding wins the race if you're late.** The constructor pre-binds `HEALTH_CHECK_OPTIONS` via `initDefault`, filling only an unbound key. A custom binding must exist BEFORE `this.component(HealthCheckComponent)` runs - otherwise the default has already claimed the slot.
+- **Three route styles, one controller.** `HealthCheckController` demonstrates all three IGNIS route patterns - use it as a reference when picking a style for your own controllers:
 
-## Configuration
+  | Style | API | Route |
+  |-------|-----|-------|
+  | Fluent | `bindRoute().to()` | `GET /` |
+  | Decorator | `@api()` | `POST /ping` |
+  | Imperative | `defineRoute()` (commented out in source) | - |
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `restOptions.path` | `string` | `'/health'` | Base path for health endpoints |
+## Common tasks
 
-The component uses `IHealthCheckOptions` bound to `HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS`. If no custom binding is found, it falls back to:
+### Customize the health check path
+Bind `IHealthCheckOptions` BEFORE registering the component - order matters (see above).
 
 ```typescript
-const DEFAULT_OPTIONS: IHealthCheckOptions = {
-  restOptions: { path: '/health' },
-};
-```
+import { HealthCheckBindingKeys, IHealthCheckOptions } from '@venizia/ignis';
 
-#### IHealthCheckOptions -- Full Reference
-```typescript
-interface IHealthCheckOptions {
-  restOptions: { path: string };
-}
+this.bind<IHealthCheckOptions>({
+  key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS,
+}).toValue({ restOptions: { path: '/health-check' } });
+
+this.component(HealthCheckComponent); // AFTER the bind
 ```
 
-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.
+### Call the ping endpoint
+`POST /health/ping` echoes `message` back with a server timestamp - useful for round-trip latency checks and body-parsing smoke tests.
 
-### Component Lifecycle
+```bash
+curl -X POST localhost:3000/health/ping \
+  -H 'content-type: application/json' \
+  -d '{"message":"hello"}'
+# { "type": "PONG", "date": "2026-02-11T12:00:00.000Z", "message": "hello" }
+```
 
-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`:
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| `type` | `string` | No | Defaults to `"PING"` |
+| `message` | `string` | Yes | Min 1, max 255 characters |
+
+### Fix "health check endpoint returns 404"
+Register the component in `preConfigure()`, before any controller registration completes.
 
 ```typescript
-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),
-    },
-  });
+preConfigure(): ValueOrPromise<void> {
+  this.component(HealthCheckComponent);
+  // ... other registrations
 }
 ```
 
-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.
+## Reference
 
-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:
+### Configuration
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `restOptions.path` | `string` (optional) | `'/health'` | Base path for health endpoints |
 
 ```typescript
-override binding(): ValueOrPromise<void> {
-  const healthOptions =
-    this.application.get<IHealthCheckOptions>({
-      key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS,
-      isOptional: true,
-    }) ?? DEFAULT_OPTIONS;
-
-  Reflect.decorate(
-    [controller({ path: healthOptions.restOptions.path })],
-    HealthCheckController,
-  );
-  this.application.controller(HealthCheckController);
+interface IHealthCheckOptions {
+  /** Partially-filled bindings are accepted; every missing field falls back to its default. */
+  restOptions?: { path?: string };
 }
 ```
 
-> [!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
-
+### Binding keys
 | Key | Constant | Type | Required | Default |
 |-----|----------|------|----------|---------|
 | `@app/health-check/options` | `HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS` | `IHealthCheckOptions` | No | `{ restOptions: { path: '/health' } }` |
 
-> [!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.
-
-### Rest Paths
-
-| Constant | Value | Full Path (default) |
+### REST paths
+| Constant | Value | Full path (default) |
 |----------|-------|---------------------|
 | `HealthCheckRestPaths.ROOT` | `/` | `GET /health` |
 | `HealthCheckRestPaths.PING` | `/ping` | `POST /health/ping` |
 
-### Rest Path Constants
-
-```typescript
-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
+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:
-
-| 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
+### Controller source
 ```typescript
 import {
   BaseRestController, IControllerOptions, TRouteContext,
@@ -286,101 +198,15 @@ export class HealthCheckController extends BaseRestController {
 }
 ```
 
-#### Route Configuration Schemas
-
-**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
-  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;
-```
-
 ## 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
-}
-```
-
-### "Custom path is not applied"
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `GET /health` returns 404 | `HealthCheckComponent` not registered, or registered after controllers were already mounted | Call `this.component(HealthCheckComponent)` in `preConfigure()` |
+| Custom path not applied | Custom `IHealthCheckOptions` bound AFTER `this.component()` ran - the default binding already claimed the DI key | Bind options BEFORE calling `this.component(HealthCheckComponent)` |
+| `POST /health/ping` returns a validation error | `message` is missing, or exceeds 255 characters | Send a `message` string between 1 and 255 characters |
 
-**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
+## See also
 
 - **Guides:**
   - [Components Overview](/guides/core-concepts/components) - Component system basics
@@ -391,3 +217,11 @@ preConfigure(): ValueOrPromise<void> {
 
 - **Best Practices:**
   - [Deployment Strategies](/best-practices/deployment-strategies) - Production monitoring
+
+**Files:**
+
+- [`packages/core-server/src/components/health-check/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/health-check/component.ts) - `HealthCheckComponent`
+- [`packages/core-server/src/components/health-check/controller.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/health-check/controller.ts) - `HealthCheckController`
+- [`packages/core-server/src/components/health-check/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/health-check/common/types.ts) - `IHealthCheckOptions`
+- [`packages/core-server/src/components/health-check/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/health-check/common/keys.ts) - `HealthCheckBindingKeys`
+- [`packages/core-server/src/components/health-check/common/rest-paths.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/health-check/common/rest-paths.ts) - `HealthCheckRestPaths`

package/content/extensions/components/index.md

@@ -1,92 +1,26 @@
 # Components
 
-Reusable, pluggable modules that group together related features. A component can encapsulate various resources such as providers, services, controllers, repositories, or even an entire mini-application, providing a clean way to modularize and share complex logic across IGNIS applications.
-
-## Built-in Components
-
-| Component | Purpose | Key Features |
-|-----------|---------|--------------|
-| [Authentication](./authentication/) | JWT/Basic auth | Token generation, protected routes, multi-strategy |
-| [Authorization](./authorization/) <Badge type="warning" text="Experimental" /> | Enforcer-based authz | RBAC, ABAC, voters, Casbin integration, role shortcuts |
-| [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, Bun S3 & local filesystem support |
-| [Swagger](./api-reference) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
-| [gRPC](/references/base/grpc-controllers) | gRPC transport | ConnectRPC integration, unary RPC, decorator-based |
-
-## Creating a Component
-
-To create a new component, you need to create a class that extends `BaseComponent`.
-
-```typescript
-import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise } from '@venizia/ignis';
-
-export class MyCustomComponent extends BaseComponent {
-  constructor(
-    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
-  ) {
-    super({ scope: MyCustomComponent.name });
-  }
-
-  override binding(): ValueOrPromise<void> {
-    // This is where you bind your component's resources.
-    this.application.service(MyCustomService);
-    this.application.controller(MyCustomController);
-  }
-}
-```
-
-## Component Lifecycle
-
-| Phase | When | Purpose |
-|-------|------|---------|
-| **`constructor()`** | Component instantiation | Receive dependencies, define default bindings |
-| **`binding()`** | Application startup | Register controllers, services, repositories with DI container |
-
-## Registering a Component
-
-To use a component, you need to register it with the application instance, usually in the `preConfigure` method of your `Application` class.
-
-```typescript
-// in src/application.ts
-import { MyCustomComponent } from './components/my-custom.component';
-
-// ... inside your Application class
-
-  preConfigure(): ValueOrPromise<void> {
-    // ...
-    this.component(MyCustomComponent);
-  }
-```
-
-When the application starts, it will automatically call the `binding()` method of the registered component, setting up all the resources it provides.
-
-Using components is a great way to organize your application's features into modular, reusable pieces of code, keeping your main application class clean and focused on high-level configuration.
-
-## See Also
-
-- **Component Guides:**
-  - [Components Overview](/guides/core-concepts/components) - What components are
-  - [Creating Components](/guides/core-concepts/components-guide) - Build your own components
-
-- **Built-in Components:**
-  - [Authentication](./authentication/) - JWT/Basic authentication
-  - [Authorization](./authorization/) - Enforcer-based authorization
-  - [Health Check](./health-check) - Health check endpoints
-  - [Mail](./mail/) - Email functionality
-  - [Request Tracker](./request-tracker) - Request tracking
-  - [Socket.IO](./socket-io/) - Socket.IO WebSocket support
-  - [WebSocket](./websocket/) - Bun native WebSocket
-  - [Static Asset](./static-asset/) - File upload/download management
-  - [Swagger](./api-reference) - API documentation
-  - [gRPC](/references/base/grpc-controllers) - gRPC transport (ConnectRPC)
-
-- **References:**
-  - [BaseComponent API](/references/base/components) - Component base class
-  - [Application](/references/base/application) - Registering components
-
-- **Best Practices:**
-  - [Architectural Patterns](/best-practices/architectural-patterns) - Component design patterns
+Self-contained feature modules you register with `this.component(SomeComponent)`.
+
+## Built-in components
+
+| Component | What it does | When you reach for it |
+|---|---|---|
+| [Authentication](./authentication/) | JWT and Basic auth - token generation, protected routes, multi-strategy | A route needs to know who the caller is |
+| [Authorization](./authorization/) <Badge type="warning" text="Experimental" /> | Enforcer-based RBAC/ABAC, voters, Casbin integration | A route needs a permission check beyond authentication |
+| [Health Check](./health-check) | `/health` endpoint, ping/pong | A load balancer or Kubernetes needs a liveness probe |
+| [Mail](./mail/) | Email sending - multiple transports, templating, queue-based | The app sends transactional or templated email |
+| [Request Tracker](./request-tracker) | Request ID, timing, structured request logging | Always on - registered automatically, nothing to configure |
+| [Socket.IO](./socket-io/) | Real-time over Socket.IO - Redis adapter, event-based | Clients need rooms or Socket.IO-specific features |
+| [WebSocket](./websocket/) | Native Bun WebSocket, Redis pub/sub, heartbeat | Clients need a raw WebSocket without Socket.IO |
+| [Static Asset](./static-asset/) | Upload/download files - MinIO, Bun S3, local disk | The app stores or serves user-uploaded files |
+| [API Reference](./api-reference) | OpenAPI generation, Scalar UI by default, Swagger UI optional | You want a browsable UI for your REST routes |
+| [gRPC](/references/base/grpc-controllers) | ConnectRPC transport, unary RPC, decorator-based | The app serves gRPC alongside or instead of REST |
+
+## See also
+
+- [Components Overview](/guides/core-concepts/components) - What components are
+- [Creating Components](/guides/core-concepts/components-guide) - Build your own
+- [BaseComponent API](/references/base/components) - Component base class
+- [Application](/references/base/application) - Registering components
+- [Architectural Patterns](/best-practices/architectural-patterns) - Component design patterns