@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/references/base/grpc-controllers.md

@@ -11,13 +11,13 @@ Technical reference for gRPC controller classes -- the foundation for building g
 IGNIS gRPC controllers follow the same patterns as REST controllers (decorator-based routing, `binding()` method, DI integration) while bridging to ConnectRPC's universal handler system. REST and gRPC controllers coexist in the same application, sharing the same DI container, middleware pipeline, and lifecycle.
 
 **Files:**
-- `packages/core/src/base/controllers/grpc/abstract.ts`
-- `packages/core/src/base/controllers/grpc/base.ts`
-- `packages/core/src/base/controllers/grpc/adapter.ts`
-- `packages/core/src/base/controllers/grpc/common/types.ts`
-- `packages/core/src/base/metadata/routes/rpc.ts`
-- `packages/core/src/components/controller/grpc/grpc.component.ts`
-- `packages/core/src/components/controller/grpc/common/types.ts`
+- `packages/core-server/src/base/controllers/grpc/abstract.ts`
+- `packages/core-server/src/base/controllers/grpc/base.ts`
+- `packages/core-server/src/base/controllers/grpc/adapter.ts`
+- `packages/core-server/src/base/controllers/grpc/common/types.ts`
+- `packages/core-server/src/base/metadata/routes/rpc.ts`
+- `packages/core-server/src/components/controller/grpc/grpc.component.ts`
+- `packages/core-server/src/components/controller/grpc/common/types.ts`
 
 ## Quick Reference
 
@@ -35,7 +35,7 @@ IGNIS gRPC controllers follow the same patterns as REST controllers (decorator-b
 | **@rpc** | Generic method decorator (requires explicit `method` in configs) |
 
 > [!WARNING]
-> **Current version supports unary RPCs only.** The `@serverStream`, `@clientStream`, and `@bidiStream` decorators still exist and set metadata correctly, but `BaseGrpcController.registerRoute()` will throw a clear error at boot time if a non-unary RPC is registered. This is because the Connect protocol over HTTP/1.1 cannot support streaming. The decorators are preserved for forward compatibility.
+> **Current version supports unary RPCs only.** The `@serverStream`, `@clientStream`, and `@bidiStream` decorators still exist and set metadata correctly. But `BaseGrpcController.registerRoute()` throws a clear error at boot time if a non-unary RPC is registered - the Connect protocol over HTTP/1.1 cannot support streaming. The decorators are preserved for forward compatibility.
 
 ## Prerequisites
 
@@ -57,7 +57,7 @@ bun add @connectrpc/connect-web
 ```
 
 > [!NOTE]
-> `@connectrpc/connect` is an **optional** peer dependency of `@venizia/ignis` - it is only loaded at runtime when a gRPC controller is configured, via `createRequire` from the application's `node_modules`. If it is missing, `GrpcRequestAdapter.build()` throws a clear error at startup via `validateModule()`. `@bufbuild/protobuf` is required by your generated protobuf code (e.g. `create()`), not by the framework itself.
+> `@connectrpc/connect` is an **optional** peer dependency of `@venizia/ignis`. It is only loaded at runtime when a gRPC controller is configured, via `createRequire` from the application's `node_modules`. If it is missing, `GrpcRequestAdapter.build()` throws a clear error at startup via `ModuleUtility.assertInstalled()`. A compiled binary has no `node_modules` to resolve against and must pass the peer through `IGrpcComponentConfig.module` - see [Peer Dependency Loading](#peer-dependency-loading). `@bufbuild/protobuf` is required by your generated protobuf code (e.g. `create()`), not by the framework itself.
 
 ### Protobuf Code Generation
 
@@ -229,7 +229,7 @@ The `configure()` method on `AbstractGrpcController` is idempotent (guarded by `
 
 ## RPC Decorators
 
-All RPC decorators live in `packages/core/src/base/metadata/routes/rpc.ts`. They register metadata in the `MetadataRegistry`, which is read during `configure()`.
+All RPC decorators live in `packages/core-server/src/base/metadata/routes/rpc.ts`. They register metadata in the `MetadataRegistry`, which is read during `configure()`.
 
 ### `@rpc` -- Generic
 
@@ -415,7 +415,7 @@ Internal bridge between IGNIS gRPC controllers and ConnectRPC's universal handle
 
 ### Architecture
 
-The adapter solves a key challenge: ConnectRPC handlers have their own `(request, context) => response` signature, but IGNIS controllers need access to the Hono `Context` for middleware, auth, and request-scoped state. The adapter uses `AsyncLocalStorage` to provide request-scoped context isolation, ensuring concurrent requests never share state.
+The adapter solves a key challenge: ConnectRPC handlers have their own `(request, context) => response` signature. IGNIS controllers, though, need access to the Hono `Context` for middleware, auth, and request-scoped state. The adapter uses `AsyncLocalStorage` to provide request-scoped context isolation, ensuring concurrent requests never share state.
 
 ```
 Hono Request
@@ -429,7 +429,7 @@ Hono Request
 
 ### Static `build()` Method
 
-The only public API. Validates peer deps via `validateModule()`, creates the adapter, and returns the middleware + registered paths:
+The only public API. Validates peer deps via `ModuleUtility.assertInstalled()`, creates the adapter, and returns the middleware + registered paths:
 
 ```typescript
 static async build(opts: {
@@ -462,12 +462,27 @@ The optional `interceptors` array is passed to ConnectRPC's `createConnectRouter
 
 ### Peer Dependency Loading
 
-The adapter loads ConnectRPC modules at runtime using `createRequire` from the application's `node_modules`:
+The adapter needs two entry points:
 
 - `@connectrpc/connect` -- for `createConnectRouter`
 - `@connectrpc/connect/protocol` -- for `universalServerRequestFromFetch` and `universalServerResponseToFetch`
 
-This approach supports single-file builds where the peer deps may not be resolvable via standard `import`.
+By default it loads both at runtime using `createRequire` from the application's `node_modules`. That keeps the specifier invisible to `Bun.build`, so a consumer who never uses gRPC is not forced to install the peer.
+
+**A compiled application must pass `module`.** A `bun build --compile` binary ships without `node_modules`, so `createRequire` has nothing to resolve against. Hand the peer over through the component options instead - the static import is what embeds it in the binary:
+
+```typescript
+import * as connect from '@connectrpc/connect';
+import * as protocol from '@connectrpc/connect/protocol';
+
+this.bind({ key: GrpcBindingKeys.GRPC_COMPONENT_OPTIONS }).toValue({
+  module: { connect, protocol },
+});
+```
+
+`GrpcComponent` assigns the module to each controller before `configure()`, and the adapter skips both `assertInstalled` and `createRequire` when it is present.
+
+`ModuleUtility.register` does not work here. The adapter resolves the specifier itself, so the registry never reaches it.
 
 ### Error Handling
 
@@ -477,7 +492,7 @@ On handler errors, the adapter returns a JSON response with:
 - `grpc-message` header: URL-encoded error message
 - Body: JSON `{ message, code }`
 
-The adapter uses a duck-type check on `error.code` to preserve gRPC status codes from ConnectRPC errors without importing `ConnectError` directly, avoiding tight coupling to the peer dependency.
+The adapter uses a duck-type check on `error.code` to preserve gRPC status codes from ConnectRPC errors, without importing `ConnectError` directly. That avoids tight coupling to the peer dependency.
 
 ## `GrpcComponent`
 
@@ -488,9 +503,30 @@ Auto-discovers and configures gRPC controllers during the application lifecycle.
 ```typescript
 interface IGrpcComponentConfig {
   interceptors?: unknown[];
+  module?: IConnectRpcModule;
 }
 ```
 
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `interceptors` | `unknown[]` | none | ConnectRPC interceptors, passed to `createConnectRouter` for every gRPC controller. An empty list passes nothing |
+| `module` | `IConnectRpcModule` | none | The ConnectRPC peer, as `{ connect, protocol }`. Required for a compiled binary - see [Peer Dependency Loading](#peer-dependency-loading) |
+
+Both options are component-wide. `GrpcComponent` assigns them to every gRPC controller it discovers, before calling `configure()`:
+
+```typescript
+import type { Interceptor } from '@connectrpc/connect';
+
+const logging: Interceptor = next => async request => {
+  const response = await next(request);
+  return response;
+};
+
+this.bind({ key: GrpcBindingKeys.GRPC_COMPONENT_OPTIONS }).toValue({
+  interceptors: [logging],
+});
+```
+
 The component registers a default (empty) config binding under the key `'@app/grpc/options'` (`GrpcBindingKeys.GRPC_COMPONENT_OPTIONS`).
 
 ### Behavior
@@ -623,7 +659,7 @@ export class Application extends BaseApplication {
 ```
 
 > [!WARNING]
-> If `transports` does not include `ControllerTransports.GRPC`, gRPC controllers are still registered in the DI container but the `GrpcComponent` is never mounted -- their `configure()` is never called and no routes are served.
+> If `transports` does not include `ControllerTransports.GRPC`, gRPC controllers are still registered in the DI container. But the `GrpcComponent` is never mounted -- their `configure()` is never called and no routes are served.
 
 ### Dual Transport
 
@@ -639,7 +675,7 @@ preConfigure() {
 }
 ```
 
-REST controllers are handled by the `RestComponent` (active when transports includes `ControllerTransports.REST`, which is the default); gRPC controllers are handled by the `GrpcComponent` (active when transport is enabled). They share the same DI container and lifecycle.
+REST controllers are handled by the `RestComponent`, active when `transports` includes `ControllerTransports.REST` (the default). gRPC controllers are handled by the `GrpcComponent`, active when that transport is enabled. They share the same DI container and lifecycle.
 
 ## Complete Example
 

package/content/references/base/index.md

@@ -9,7 +9,7 @@ Core classes that power every IGNIS application - from the Application entry poi
 
 | Class | Purpose | Extends |
 |-------|---------|---------|
-| `BaseApplication` | Application entry point, DI container | `AbstractApplication` |
+| `BaseApplication` | Application entry point, DI container | `ServerApplication` -> `RestApplication` -> `AbstractApplication` |
 | `BaseRestController` | REST/HTTP route handlers | `AbstractRestController` |
 | `BaseGrpcController` | gRPC route handlers (ConnectRPC) | `AbstractGrpcController` |
 | `BaseService` | Business logic layer | - |
@@ -79,8 +79,10 @@ Core classes that power every IGNIS application - from the Application entry poi
 ## Class Hierarchy
 
 ```
-AbstractApplication
-└── BaseApplication ──────► Your Application
+AbstractApplication (browser-pure, @venizia/ignis-kernel)
+└── RestApplication (browser-pure, owns the router)
+    └── ServerApplication (opens the socket)
+        └── BaseApplication ──────► Your Application
 
 AbstractRepository (engine-neutral, src/base)
 ├── PostgresBaseRepository (connectors/postgres)

package/content/references/base/middlewares.md

@@ -10,10 +10,10 @@ lastUpdated: 2026-06-14
 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 - you do not import or wire them manually.
 
 **Files:**
-- `packages/core/src/base/middlewares/app-error/app-error.middleware.ts`
-- `packages/core/src/base/middlewares/not-found/not-found.middleware.ts`
-- `packages/core/src/base/middlewares/request-spy/request-spy.middleware.ts`
-- `packages/core/src/base/middlewares/emoji-favicon/emoji-favicon.middleware.ts`
+- `packages/core-server/src/base/middlewares/app-error/app-error.middleware.ts`
+- `packages/core-server/src/base/middlewares/not-found/not-found.middleware.ts`
+- `packages/core-server/src/base/middlewares/request-spy/request-spy.middleware.ts`
+- `packages/core-server/src/base/middlewares/emoji-favicon/emoji-favicon.middleware.ts`
 
 ## Prerequisites
 
@@ -26,7 +26,7 @@ Before reading this document, you should understand:
 
 | Middleware | Type | Purpose |
 |-----------|------|---------|
-| `appErrorHandler` | `ErrorHandler` | Global error handler (Zod, DB constraints, generic) |
+| `AppErrorMiddleware` | `IProvider<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 |
@@ -40,7 +40,7 @@ protected async registerDefaultMiddlewares() {
   const server = this.getServer();
 
   // 1. Global error handler
-  server.onError(appErrorHandler({ logger, rootKey }));
+  server.onError(new AppErrorMiddleware({ logger, rootKey }).value());
 
   // 2. Async context storage (if enabled)
   if (this.configs.asyncContext?.enable) {
@@ -60,24 +60,24 @@ protected async registerDefaultMiddlewares() {
 
 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
+## AppErrorMiddleware
 
-Global error handler registered via `server.onError()`. Handles ZodError validation errors, PostgreSQL constraint violations, and generic errors.
+Global error handler registered via `server.onError()`. Handles ZodError validation errors, PostgreSQL constraint violations, and generic errors. Like `RequestSpyMiddleware`, it is an `IProvider` - build it, then call `value()` for the handler.
 
-**Not exported from `@venizia/ignis`** - registered automatically by `BaseApplication`.
+Registered automatically by `BaseApplication`.
 
 ### Signature
 
 ```typescript
-function appErrorHandler(opts: {
-  logger: Logger;
-  rootKey?: string;
-}): ErrorHandler
+class AppErrorMiddleware extends BaseHelper implements IProvider<ErrorHandler> {
+  constructor(opts?: { logger?: ILogger; rootKey?: string });
+  value(): ErrorHandler;
+}
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `logger` | `Logger` | Logger instance for error logging |
+| `logger` | `ILogger \| undefined` | Overrides the middleware's own scoped logger - `BaseApplication` passes its own so error lines stay in its scope |
 | `rootKey` | `string \| undefined` | Optional root key to wrap the error response object |
 
 ### Error Handling Logic
@@ -86,13 +86,17 @@ function appErrorHandler(opts: {
 
 When `error.name === 'ZodError'`, returns HTTP `422 Unprocessable Entity`.
 
-Top-level `message`/`messageCode` come from the first failing issue - its `params.code` if the schema set one, otherwise its raw Zod code. The full per-field list stays under `details.cause`.
+`message` and `normalized.code` come from the first failing issue. `message` is that issue's message; `normalized.code` is its `params.code` if the schema set one, otherwise its raw Zod code. The full per-field list stays under `details.cause`. `normalized.args` is always `{}` - a Zod issue carries no interpolation values.
 
 ```json
 {
   "message": "Invalid email address",
-  "messageCode": "user.email.invalid",
   "statusCode": 422,
+  "normalized": {
+    "text": "Invalid email address",
+    "code": "user.email.invalid",
+    "args": {}
+  },
   "requestId": "abc-123",
   "details": {
     "url": "http://localhost:3000/users",
@@ -111,22 +115,22 @@ Top-level `message`/`messageCode` come from the first failing issue - its `param
 }
 ```
 
-To emit a stable, domain-specific `messageCode`, attach `params.code` to a custom check:
+To emit a stable, domain-specific `normalized.code`, attach `params.code` to a custom check:
 
 ```typescript
 z.string().refine(isEmail, {
   message: 'Invalid email address',
   params: { code: 'user.email.invalid' }
 });
-// produces "messageCode": "user.email.invalid"
+// produces "normalized": { "code": "user.email.invalid", ... }
 ```
 
 > [!NOTE]
-> When `error.message` cannot be parsed as the expected Zod issue array (a malformed or unrecognized `ZodError`), no issue-derived `messageCode` exists - the response still carries one, resolved to `MessageCode.DEFAULT` (`"core.system_error"`) via `MessageCode.resolve(undefined)`. No error response from this middleware is ever missing `messageCode`.
+> When `error.message` cannot be parsed as the expected Zod issue array (a malformed or unrecognized `ZodError`), no issue-derived code exists. `normalized.code` still resolves to `MessageCode.DEFAULT` (`"core.system_error"`) via `MessageCode.resolve(undefined)`. No error response from this middleware is ever missing `normalized.code`.
 
 #### 2. PostgreSQL Constraint Violations
 
-Database errors in SQLSTATE class `22` (data exception), `23` (integrity constraint), and `44` (WITH CHECK OPTION violation) are detected by class and returned as HTTP `400 Bad Request`. A known code uses its specific message; any other in-class code uses `"Invalid database request"` as a fallback.
+Database errors in SQLSTATE class `22` (data exception), `23` (integrity constraint), and `44` (WITH CHECK OPTION violation) are detected by class. They return HTTP `400 Bad Request`. A known code uses its specific message; any other in-class code uses `"Invalid database request"` as a fallback.
 
 | Class | Codes with a specific message |
 |-------|-------------------------------|
@@ -135,7 +139,7 @@ Database errors in SQLSTATE class `22` (data exception), `23` (integrity constra
 | `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.
+Class `40` (`40001` serialization failure, `40P01` deadlock) is transient/retryable. It returns **409 Conflict** with `normalized.code: "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.
 :::
 
 :::warning Production sanitizes database internals
@@ -151,8 +155,12 @@ All other errors use the `statusCode` property from the error if present, otherw
 ```json
 {
   "message": "Error message",
-  "messageCode": "core.system_error",
   "statusCode": 500,
+  "normalized": {
+    "text": "Error message",
+    "code": "core.system_error",
+    "args": {}
+  },
   "requestId": "abc-123",
   "details": {
     "url": "http://localhost:3000/users",
@@ -163,14 +171,20 @@ All other errors use the `statusCode` property from the error if present, otherw
 }
 ```
 
+An intentional `getError(...)` throw also carries `extra` when the throw site attached context of its own; every other branch never does. There is no top-level `messageCode` - the code always lives at `normalized.code`.
+
 When `rootKey` is provided (e.g., `rootKey: 'error'`), the response is wrapped:
 
 ```json
 {
   "error": {
     "message": "Error message",
-    "messageCode": "core.system_error",
     "statusCode": 500,
+    "normalized": {
+      "text": "Error message",
+      "code": "core.system_error",
+      "args": {}
+    },
     "requestId": "abc-123",
     "details": { ... }
   }
@@ -215,13 +229,13 @@ Returns a JSON 404 response when no route matches. Registered via `server.notFou
 
 ```typescript
 function notFoundHandler(opts: {
-  logger?: Logger;
+  logger?: ILogger;
 }): NotFoundHandler
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `logger` | `Logger \| undefined` | Logger instance (defaults to `console`) |
+| `logger` | `ILogger \| undefined` | Logger instance (defaults to `console`) |
 
 ### Response Format
 
@@ -235,7 +249,8 @@ function notFoundHandler(opts: {
 }
 ```
 
-The handler logs the 404 at error level with the request ID, path, and full URL.
+The handler logs the 404 at warn level with the request ID, path, and full URL. An unrouted path is a
+client mistake, not a server fault - alerting tuned to error level should not fire on it.
 
 
 ## RequestSpyMiddleware
@@ -363,7 +378,7 @@ Several middleware behaviors are configured through `IApplicationConfigs`:
 ```typescript
 interface IApplicationConfigs {
   favicon?: string;                    // Emoji for emojiFavicon (default: '🔥')
-  error?: { rootKey: string };         // Root key wrapper for appErrorHandler
+  error?: { rootKey: string };         // Root key wrapper for AppErrorMiddleware
   asyncContext?: { enable: boolean };  // Enable Hono contextStorage() middleware
   // ...
 }
@@ -482,7 +497,7 @@ export class MyMiddleware extends BaseHelper implements IProvider<MiddlewareHand
 }
 ```
 
-Register it with `.toProvider()` (the same pattern `RequestTrackerComponent` uses for `RequestSpyMiddleware`), then use the resolved handler inside `setupMiddlewares()` - `get()` returns the produced `MiddlewareHandler` because the container calls `value()` for provider bindings:
+Register it with `.toProvider()` (the same pattern `RequestTrackerComponent` uses for `RequestSpyMiddleware`). Then use the resolved handler inside `setupMiddlewares()`: `get()` returns the produced `MiddlewareHandler`, because the container calls `value()` for provider bindings.
 
 ```typescript
 export class MyApplication extends BaseApplication {