@venizia/ignis-docs 0.0.7 → 0.0.8-1

package/wiki/{references → extensions}/components/authorization/usage.md

@@ -10,12 +10,12 @@ Use the `authorize` field in route configs to declare authorization requirements
 
 ```typescript
 import {
-  BaseController,
+  BaseRestController,
   Authentication,
   AuthorizationActions,
 } from '@venizia/ignis';
 
-class ArticleController extends BaseController {
+class ArticleController extends BaseRestController {
   binding() {
     // Read requires 'read' action on 'Article' resource
     this.defineRoute({
@@ -102,7 +102,7 @@ Use the `authorize` field alongside `authenticate` in decorator configs:
 import { controller, get, post, AuthorizationActions, AuthorizationRoles } from '@venizia/ignis';
 
 @controller({ path: '/articles' })
-class ArticleController extends BaseController {
+class ArticleController extends BaseRestController {
   @get({
     configs: {
       path: '/',
@@ -134,6 +134,34 @@ class ArticleController extends BaseController {
 }
 ```
 
+### gRPC Route Authorization
+
+Authorization works the same way in gRPC controllers. Use the `authorize` field in RPC metadata:
+
+```typescript
+import { AuthorizationActions, Authentication } from '@venizia/ignis';
+
+class GreeterController extends BaseGrpcController {
+  binding() {
+    this.defineRoute({
+      configs: {
+        method: sayHello,
+        authenticate: { strategies: [Authentication.STRATEGY_JWT] },
+        authorize: {
+          action: AuthorizationActions.EXECUTE,
+          resource: 'Greeter',
+        },
+      },
+      handler: async (context) => {
+        // Handler runs only if authorized
+      },
+    });
+  }
+}
+```
+
+The `AbstractGrpcController.buildRpcMiddlewares()` method injects authorization middleware in the same order as REST controllers: authenticate first, then authorize.
+
 ## Using the `authorize()` Standalone Function
 
 The `authorize()` function is a convenience wrapper around `AuthorizationProvider`. It returns a Hono `MiddlewareHandler`:
@@ -383,7 +411,7 @@ ControllerFactory.defineCrudController({
 
 ### Priority Resolution (Factory Routes)
 
-The `defineControllerRouteConfigs` function resolves authorization with this priority:
+The `resolveRouteAuthorize` function in `defineControllerRouteConfigs` resolves authorization with this priority:
 
 ```mermaid
 flowchart TD
@@ -403,6 +431,16 @@ flowchart TD
 3. **Per-route `authorize` spec** -- overrides controller-level
 4. **Controller-level `authorize`** -- default for all routes
 
+### Per-Route Auth Type
+
+The per-route authorize config is typed as a discriminated union:
+
+```typescript
+type TRouteAuthorizeConfig = { skip: true } | IAuthorizationSpec | IAuthorizationSpec[];
+```
+
+This means each route can either skip authorization entirely, provide a single spec, or provide an array of specs that all must pass.
+
 ## Dynamic Skip Authorization
 
 Use `Authorization.SKIP_AUTHORIZATION` to dynamically bypass authorization in middleware (step 1 in the pipeline):

package/wiki/{references → extensions}/components/health-check.md

@@ -213,10 +213,11 @@ The controller uses `this.definitions = RouteConfigs` to store route configurati
 #### Controller Source
 ```typescript
 import {
-  BaseController, IControllerOptions, TRouteContext,
-  api, jsonContent, jsonResponse, z,
+  BaseRestController, IControllerOptions, TRouteContext,
 } from '@venizia/ignis';
-import { HTTP } from '@venizia/ignis-helpers';
+import { api, jsonContent, jsonResponse } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+import { HTTP, ValueOrPromise } from '@venizia/ignis-helpers';
 
 const RouteConfigs = {
   ROOT: {
@@ -258,7 +259,7 @@ const RouteConfigs = {
   },
 } as const;
 
-export class HealthCheckController extends BaseController {
+export class HealthCheckController extends BaseRestController {
   constructor(opts: IControllerOptions) {
     super({ ...opts, scope: HealthCheckController.name });
     this.definitions = RouteConfigs;

package/wiki/{references → extensions}/components/index.md

@@ -15,6 +15,7 @@ Reusable, pluggable modules that group together related features. A component ca
 | [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 |
+| [gRPC](/references/base/grpc-controllers) | gRPC transport | ConnectRPC integration, unary RPC, decorator-based |
 
 ## Creating a Component
 
@@ -81,6 +82,7 @@ Using components is a great way to organize your application's features into mod
   - [WebSocket](./websocket/) - Bun native WebSocket
   - [Static Asset](./static-asset/) - Static file serving
   - [Swagger](./swagger) - API documentation
+  - [gRPC](/references/base/grpc-controllers) - gRPC transport (ConnectRPC)
 
 - **References:**
   - [BaseComponent API](/references/base/components) - Component base class

package/wiki/{references → extensions}/components/mail/index.md

@@ -211,7 +211,7 @@ The `TMailOptions` configuration determines which email transport provider is us
 
 ```typescript
 // Simple SMTP Authentication (e.g., Gmail with app password)
-this.bind<TMailOptions>({ key: MailBindingKeys.MAIL_OPTIONS }).toValue({
+this.bind<TMailOptions>({ key: MailKeys.MAIL_OPTIONS }).toValue({
   provider: 'nodemailer',
   from: 'noreply@example.com',
   fromName: 'My App',

package/wiki/{references → extensions}/components/request-tracker.md

@@ -248,7 +248,7 @@ If running without a proxy, ensure the runtime provides connection info (Bun doe
   - [All Components](./index) - Built-in components list
 
 - **Helpers:**
-  - [Logger Helper](/references/helpers/logger/) - Logging utilities
+  - [Logger Helper](/extensions/helpers/logger/) - Logging utilities
 
 - **Best Practices:**
   - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Debugging with request IDs

package/wiki/{references → extensions}/components/socket-io/api.md

@@ -630,7 +630,7 @@ Reads all binding keys from the DI container and validates required ones:
 |---------|-----------|------------------|
 | `SERVER_OPTIONS` | Optional, merged with defaults via `Object.assign()` | -- |
 | `REDIS_CONNECTION` | Must be `instanceof DefaultRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisHelper for single redis connection or RedisClusterHelper for redis cluster mode!"` |
-| `AUTHENTICATE_HANDLER` | Must be a function (non-null) | `"Invalid authenticateFn to setup io socket server!"` |
+| `AUTHENTICATE_HANDLER` | Must be a function (non-null) | `"[DANGER][SocketIOComponent] Invalid authenticateFn to setup io socket server!"` |
 | `VALIDATE_ROOM_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
 | `CLIENT_CONNECTED_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
 
@@ -673,7 +673,7 @@ Returns a fetch handler function that routes requests:
 Registers a post-start hook that:
 
 1. Gets the HTTP server instance via `getServerInstance()`
-2. Validates the server instance exists (throws `"HTTP server not available for Node.js runtime!"` if not)
+2. Validates the server instance exists (throws `"[SocketIOComponent] HTTP server not available for Node.js runtime!"` if not)
 3. Calls `createNodeSocketIOHelper()` which creates `SocketIOServerHelper` with `runtime: RuntimeModules.NODE` and the HTTP server, then awaits `configure()`
 4. Binds the helper to `SOCKET_IO_INSTANCE`
 

package/wiki/{references → extensions}/components/socket-io/errors.md

@@ -59,6 +59,8 @@
 **Fix**: Use `RedisHelper` (single instance) or `RedisClusterHelper` (cluster mode):
 
 ```typescript
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+
 // Correct -- single instance
 this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
   .toValue(new RedisHelper({ name: 'socket-io', host, port, password }));

package/wiki/{references → extensions}/components/socket-io/index.md

@@ -8,31 +8,33 @@
 |------|-------|
 | **Package** | `@venizia/ignis` (core) |
 | **Class** | `SocketIOComponent` |
-| **Server Helper** | [`SocketIOServerHelper`](/references/helpers/socket-io/) |
-| **Client Helper** | [`SocketIOClientHelper`](/references/helpers/socket-io/) |
+| **Server Helper** | [`SocketIOServerHelper`](/extensions/helpers/socket-io/) |
+| **Client Helper** | [`SocketIOClientHelper`](/extensions/helpers/socket-io/) |
 | **Runtimes** | Node.js (`@hono/node-server`) and Bun (native) |
 | **Scaling** | `@socket.io/redis-adapter` + `@socket.io/redis-emitter` |
 
 #### Import Paths
+
+> [!IMPORTANT]
+> `SocketIOComponent` and `SocketIOBindingKeys` are **not** exported from the `@venizia/ignis` barrel. You must import from the `@venizia/ignis/socket-io` subpath.
+
 ```typescript
+// From core -- subpath import (NOT from '@venizia/ignis')
 import {
   SocketIOComponent,
   SocketIOBindingKeys,
-} from '@venizia/ignis';
+} from '@venizia/ignis/socket-io';
 
+// From helpers -- subpath import
 import {
   SocketIOServerHelper,
-  RedisHelper,
-} from '@venizia/ignis-helpers';
-
-import {
   SocketIOClientHelper,
   SocketIOConstants,
   SocketIOClientStates,
 } from '@venizia/ignis-helpers/socket-io';
 
+// Types from helpers subpath
 import type {
-  IServerOptions,
   TSocketIOAuthenticateFn,
   TSocketIOValidateRoomFn,
   TSocketIOClientConnectedFn,
@@ -40,7 +42,7 @@ import type {
   IOptions,
   TSocketIOEventHandler,
   TSocketIOClientState,
-} from '@venizia/ignis';
+} from '@venizia/ignis-helpers/socket-io';
 ```
 
 ### Use Cases
@@ -69,18 +71,17 @@ bun add @socket.io/bun-engine
 In your application's `preConfigure()` method, bind the required services and register the component:
 
 ```typescript
+import { BaseApplication } from '@venizia/ignis';
 import {
-  BaseApplication,
   SocketIOComponent,
   SocketIOBindingKeys,
-  ValueOrPromise,
-} from '@venizia/ignis';
-import { RedisHelper } from '@venizia/ignis-helpers';
+} from '@venizia/ignis/socket-io';
+import { RedisHelper, ValueOrPromise } from '@venizia/ignis-helpers';
 import type {
   TSocketIOAuthenticateFn,
   TSocketIOValidateRoomFn,
   TSocketIOClientConnectedFn,
-} from '@venizia/ignis';
+} from '@venizia/ignis-helpers/socket-io';
 
 export class Application extends BaseApplication {
   private redisHelper: RedisHelper;
@@ -225,10 +226,10 @@ const DEFAULT_SERVER_OPTIONS: Partial<IServerOptions> = {
 Bind custom server options before registering the component:
 
 ```typescript
-import { SocketIOBindingKeys, IServerOptions } from '@venizia/ignis';
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+import type { ServerOptions } from 'socket.io';
 
-const customOptions: Partial<IServerOptions> = {
-  identifier: 'my-app-socket',
+const customOptions: Partial<ServerOptions> = {
   path: '/socket.io',
   cors: {
     origin: ['https://myapp.com', 'https://admin.myapp.com'],
@@ -240,20 +241,23 @@ const customOptions: Partial<IServerOptions> = {
   maxHttpBufferSize: 1e6, // 1MB
 };
 
-this.bind<Partial<IServerOptions>>({
+this.bind<Partial<ServerOptions>>({
   key: SocketIOBindingKeys.SERVER_OPTIONS,
 }).toValue(customOptions);
 
 this.component(SocketIOComponent);
 ```
 
+> [!NOTE]
+> The `identifier` field is part of the component's `IServerOptions` interface (which extends `ServerOptions`), not Socket.IO's native options. To set the identifier, include it in the bound options object.
+
 ## Binding Keys
 
 All binding keys are available in `SocketIOBindingKeys`:
 
 | Binding Key | Constant | Type | Required | Default |
 |------------|----------|------|----------|---------|
-| `@app/socket-io/server-options` | `SERVER_OPTIONS` | `Partial<IServerOptions>` | No | See defaults above |
+| `@app/socket-io/server-options` | `SERVER_OPTIONS` | `Partial<ServerOptions>` | No | See defaults above |
 | `@app/socket-io/redis-connection` | `REDIS_CONNECTION` | `RedisHelper` / `RedisClusterHelper` / `DefaultRedisHelper` | **Yes** | `null` |
 | `@app/socket-io/authenticate-handler` | `AUTHENTICATE_HANDLER` | `TSocketIOAuthenticateFn` | **Yes** | `null` |
 | `@app/socket-io/validate-room-handler` | `VALIDATE_ROOM_HANDLER` | `TSocketIOValidateRoomFn` | No | `null` |
@@ -404,7 +408,7 @@ interface IHandshake {
 - **Components:**
   - [Components Index](../index) -- All built-in components
 - **Helpers:**
-  - [Socket.IO Helper](/references/helpers/socket-io/) -- Full `SocketIOServerHelper` + `SocketIOClientHelper` API reference
+  - [Socket.IO Helper](/extensions/helpers/socket-io/) -- Full `SocketIOServerHelper` + `SocketIOClientHelper` API reference
 - **External Resources:**
   - [Socket.IO Documentation](https://socket.io/docs/) -- Official docs
   - [Socket.IO Redis Adapter](https://socket.io/docs/v4/redis-adapter/) -- Horizontal scaling guide

package/wiki/{references → extensions}/components/socket-io/usage.md

@@ -12,11 +12,11 @@ Inject `SocketIOServerHelper` to interact with Socket.IO:
 import {
   BaseService,
   inject,
-  SocketIOBindingKeys,
   CoreBindings,
   BaseApplication,
 } from '@venizia/ignis';
-import { SocketIOServerHelper } from '@venizia/ignis-helpers';
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+import { SocketIOServerHelper } from '@venizia/ignis-helpers/socket-io';
 
 export class NotificationService extends BaseService {
   // Lazy getter pattern -- helper is bound AFTER server starts

package/wiki/{references → extensions}/components/static-asset/api.md

@@ -6,10 +6,11 @@
 
 The `AssetControllerFactory.defineAssetController()` method dynamically creates controller classes at runtime. For each storage backend in the options:
 
-1. A new class extending `BaseController` is created with `@controller({ path: basePath })`
+1. A new class extending `BaseRestController` is created with `@controller({ path: basePath })`
 2. The class name is set dynamically via `Object.defineProperty(_controller, 'name', { value: name })`
 3. Routes are bound in the controller's `binding()` method using `this.bindRoute().to()`
-4. The controller is registered via `this.application.controller()`
+4. Route configs are spread-merged with per-route overrides from `controller.routes` (e.g., `{ ...StaticAssetDefinitions.UPLOAD, ...routes?.upload }`)
+5. The controller is registered via `this.application.controller()`
 
 ```
 StaticAssetComponent.binding()
@@ -17,7 +18,7 @@ StaticAssetComponent.binding()
 AssetControllerFactory.defineAssetController({ controller, storage, helper, ... })
     | creates
 @controller({ path: basePath })
-class _controller extends BaseController { ... }
+class _controller extends BaseRestController { ... }
     | registered via
 this.application.controller(_controller)
 ```
@@ -28,11 +29,7 @@ The factory method accepts the following options:
 
 ```typescript
 interface IAssetControllerOptions {
-  controller: {
-    name: string;
-    basePath: string;
-    isStrict?: boolean;   // Default: true
-  };
+  controller: TStaticAssetsComponentOptions[string]['controller'];
   storage: TStaticAssetStorageType;
   helper: IStorageHelper;
   useMetaLink?: boolean;
@@ -49,8 +46,9 @@ A constants class following the Ignis pattern with `static readonly` fields, a `
 class StaticAssetStorageTypes {
   static readonly DISK = 'disk';
   static readonly MINIO = 'minio';
+  static readonly BUN_S3 = 'bun-s3';
 
-  static readonly SCHEME_SET = new Set([this.DISK, this.MINIO]);
+  static readonly SCHEME_SET = new Set([this.DISK, this.MINIO, this.BUN_S3]);
 
   static isValid(orgType: string): boolean {
     return this.SCHEME_SET.has(orgType);
@@ -58,7 +56,7 @@ class StaticAssetStorageTypes {
 }
 
 type TStaticAssetStorageType = TConstValue<typeof StaticAssetStorageTypes>;
-// Resolves to: 'disk' | 'minio'
+// Resolves to: 'disk' | 'minio' | 'bun-s3'
 ```
 
 ## MultipartBodySchema
@@ -133,7 +131,7 @@ interface IStorageHelper {
   upload(opts: {
     bucket: string;
     files: IUploadFile[];
-    normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
+    normalizeNameFn?: (opts: { originalName: string }) => string;
     normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
   }): Promise<IUploadResult[]>;
 
@@ -157,7 +155,6 @@ interface IUploadFile {
   buffer: Buffer;
   size: number;
   encoding?: string;
-  folderPath?: string;
   [key: string | symbol]: any;
 }
 
@@ -207,6 +204,7 @@ BaseStorageHelper (abstract class)
     |
     +-- DiskHelper (local filesystem)
     +-- MinioHelper (S3-compatible)
+    +-- BunS3Helper (Bun-native S3)
 ```
 
 ## MetaLink SQL Schema
@@ -225,21 +223,22 @@ BaseStorageHelper (abstract class)
 | `size` | INTEGER | No | -- | File size in bytes |
 | `etag` | TEXT | Yes | -- | Entity tag for versioning |
 | `metadata` | JSONB | Yes | -- | Additional file metadata |
-| `storage_type` | TEXT | No | -- | Storage type (`'disk'` or `'minio'`) |
+| `storage_type` | TEXT | No | -- | Storage type (`'disk'`, `'minio'`, or `'bun-s3'`) |
 | `is_synced` | BOOLEAN | No | `false` | Whether MetaLink is synchronized with storage |
+| `variant` | TEXT | Yes | -- | Upload variant tag (e.g., `'thumbnail'`, `'original'`) |
 | `principal_type` | TEXT | Yes | -- | Type of the associated principal (e.g., `'user'`, `'service'`) |
 | `principal_id` | TEXT | Yes | -- | ID of the associated principal (always stored as string) |
 
 **Indexes:** `bucket_name`, `object_name`, `storage_type`, `is_synced`.
 
 > [!NOTE]
-> The `isSynced` field is automatically set to `true` when files are uploaded or synced via the meta-links endpoint. When a file is deleted, the MetaLink record is removed entirely. The `principalType` and `principalId` fields are only populated during upload when the corresponding query parameters are provided.
+> The `isSynced` field is automatically set to `true` when files are uploaded or synced via the meta-links endpoint. When a file is deleted, the MetaLink record is removed entirely. The `principalType`, `principalId`, and `variant` fields are only populated during upload when the corresponding query parameters are provided.
 
 ### MetaLink Tracking
 
 When `useMetaLink: true`, the component:
 
-- **On upload:** Creates a MetaLink database record for each uploaded file after fetching file stats from storage. Stores `principalType` and `principalId` from query parameters (if provided). The `principalId` is always coerced to a string via `String()`. If MetaLink creation fails, the upload still succeeds and the response includes `metaLink: null` with a `metaLinkError` message.
+- **On upload:** Creates a MetaLink database record for each uploaded file after fetching file stats from storage. If a `createMetaLink` callback is provided on `TMetaLinkConfig`, it is used instead of the default creation logic. Stores `principalType`, `principalId`, and `variant` from query parameters (if provided). The `principalId` is always coerced to a string via `String()`. If MetaLink creation fails, the upload still succeeds and the response includes `metaLink: null` with a `metaLinkError` message.
 - **On delete:** Initiates MetaLink record deletion as fire-and-forget (the `.then()/.catch()` promise chain is not awaited). The HTTP response with `{ "success": true }` returns before the database deletion completes. Deletion errors are logged but do not fail the request.
 - **On sync (PUT meta-links):** Checks if a MetaLink exists for the object (matched by `bucketName` + `objectName`). Updates it if found, creates a new one if not. Always sets `isSynced: true`. Returns `{ success: true, metaLink: ... }`.
 

package/wiki/{references → extensions}/components/static-asset/errors.md

@@ -41,10 +41,12 @@ Every endpoint that accepts `bucketName` validates it and returns HTTP 400 `"Inv
 **Fix:** Ensure each storage configuration has all required fields:
 
 ```typescript
+import { StaticAssetStorageTypes } from '@venizia/ignis/static-asset';
+
 {
   [uniqueKey]: {
     controller: { name, basePath, isStrict },
-    storage: 'disk' | 'minio',
+    storage: StaticAssetStorageTypes.DISK | StaticAssetStorageTypes.MINIO | StaticAssetStorageTypes.BUN_S3,
     helper: IStorageHelper,
     extra: {}
   }