@venizia/ignis-docs 0.0.7 → 0.0.8-0

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

@@ -0,0 +1,984 @@
+---
+title: gRPC Controllers Reference
+description: Technical reference for gRPC controller classes, RPC decorators, ConnectRPC adapter, and component integration
+difficulty: intermediate
+---
+
+# Deep Dive: gRPC Controllers
+
+Technical reference for gRPC controller classes -- the foundation for building gRPC services in Ignis, powered by [ConnectRPC](https://connectrpc.com/).
+
+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`
+
+## Quick Reference
+
+| Item | Description |
+|------|-------------|
+| **AbstractGrpcController** | Abstract base class with RPC registration, ConnectRPC adapter mounting, idempotent `configure()` |
+| **BaseGrpcController** | Recommended concrete base class with `bindRoute()` and `defineRoute()` implementations |
+| **GrpcRequestAdapter** | Internal bridge from Ignis handlers to ConnectRPC universal handlers via `AsyncLocalStorage` |
+| **GrpcComponent** | Auto-discovers gRPC controllers and mounts them on the application router |
+| **@controller** | Class decorator with `transport: ControllerTransports.GRPC` and `service` field |
+| **@unary** | Method decorator for unary RPCs |
+| **@serverStream** | Method decorator for server-streaming RPCs (**unsupported -- throws at boot**) |
+| **@clientStream** | Method decorator for client-streaming RPCs (**unsupported -- throws at boot**) |
+| **@bidiStream** | Method decorator for bidirectional-streaming RPCs (**unsupported -- throws at boot**) |
+| **@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.
+
+## Prerequisites
+
+gRPC support requires the following peer dependencies:
+
+```bash
+bun add @connectrpc/connect @bufbuild/protobuf
+```
+
+| Package | Purpose |
+|---------|---------|
+| `@connectrpc/connect` | ConnectRPC router, universal handlers, protocol bridge |
+| `@bufbuild/protobuf` | Protobuf code generation, `create()` for constructing response messages |
+
+For client-side usage (e.g., test clients), you also need a transport package:
+
+```bash
+bun add @connectrpc/connect-web
+```
+
+> [!NOTE]
+> These are **optional** peer dependencies. They are only loaded at runtime when a gRPC controller is configured, via `createRequire` from the application's `node_modules`. If the deps are missing, `GrpcRequestAdapter.build()` throws a clear error at startup via `validateModule()`.
+
+### Protobuf Code Generation
+
+Use `buf` or `protoc-gen-es` to generate TypeScript code from `.proto` files:
+
+```yaml
+# buf.gen.yaml
+version: v2
+plugins:
+  - local: protoc-gen-es
+    out: generated
+    opt: target=ts
+```
+
+```bash
+buf generate proto/greeter.proto
+```
+
+The generated output includes:
+- **Service descriptors** (e.g., `GreeterService`) -- passed to `@controller({ service })`
+- **Message schemas** (e.g., `SayHelloResponseSchema`) -- used with `create()` to build responses
+- **TypeScript types** (e.g., `SayHelloRequest`, `SayHelloResponse`) -- for handler signatures
+
+## `BaseGrpcController`
+
+The recommended base class for gRPC controllers. Extends `AbstractGrpcController` with concrete `bindRoute()` and `defineRoute()` implementations.
+
+### Constructor Options
+
+```typescript
+interface IGrpcControllerOptions {
+  scope: string;
+  path?: string;  // Falls back to @controller decorator path if not provided
+}
+```
+
+The `scope` is used for scoped logging (`this.logger.for('methodName')`). The `path` defines the HTTP mount point for the ConnectRPC handlers; when both the constructor and `@controller` decorator specify a path, the decorator takes precedence.
+
+### Generic Parameters
+
+`BaseGrpcController` accepts five generic parameters:
+
+```typescript
+class BaseGrpcController<
+  RouteEnv extends Env = Env,
+  RouteSchema extends Schema = {},
+  BasePath extends string = '/',
+  ServiceType = unknown,
+  ConfigurableOptions extends object = {},
+>
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `RouteEnv` | `Env` | Hono environment type for typed context access |
+| `RouteSchema` | `{}` | Hono schema type |
+| `BasePath` | `'/'` | Base path string literal type |
+| `ServiceType` | `unknown` | ConnectRPC service descriptor type |
+| `ConfigurableOptions` | `{}` | Extra options passed to `configure()` |
+
+`AbstractGrpcController` differs by defaulting `ServiceType` to `Parameters<ConnectRouter['service']>[0]` (the actual ConnectRPC service descriptor type), providing stricter type checking on the `service` field.
+
+### The `@controller` Decorator
+
+gRPC controllers use the same `@controller` decorator as REST controllers, with two additional fields:
+
+```typescript
+@controller({
+  path: '/grpc',
+  transport: ControllerTransports.GRPC,
+  service: GreeterServiceDef,  // Generated ConnectRPC service descriptor
+})
+export class GreeterController extends BaseGrpcController {
+  // ...
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `path` | `string` | Yes | HTTP base path for this controller's RPC endpoints |
+| `transport` | `ControllerTransports.GRPC` | Yes | Marks this controller for gRPC transport (picked up by `GrpcComponent`) |
+| `service` | `ServiceType` | Yes | ConnectRPC service descriptor from generated protobuf code |
+| `tags` | `string[]` | No | Metadata tags (inherited from base controller metadata) |
+| `description` | `string` | No | Controller description (inherited from base controller metadata) |
+
+> [!NOTE]
+> If `service` is missing or falsy at configure time, the `GrpcComponent` logs a warning and skips the controller entirely -- no routes are mounted.
+
+### Route Definition Patterns
+
+Like REST controllers, gRPC controllers support three route definition patterns:
+
+#### 1. Decorator-Based (Recommended)
+
+```typescript
+@controller({
+  path: '/grpc',
+  transport: ControllerTransports.GRPC,
+  service: GreeterServiceDef,
+})
+export class GreeterController extends BaseGrpcController {
+  override binding() {}
+
+  @unary({ configs: { name: 'sayHello' } })
+  async sayHello(opts: { request: SayHelloRequest }): Promise<SayHelloResponse> {
+    return create(SayHelloResponseSchema, { message: `Hello, ${opts.request.name}!` });
+  }
+}
+```
+
+Decorator-based RPCs are auto-discovered during `configure()` via `registerRpcsFromRegistry()`. The `binding()` method can be left empty if all routes use decorators.
+
+#### 2. `defineRoute()` -- Imperative
+
+```typescript
+override binding() {
+  this.defineRoute({
+    configs: { name: 'sayHello', method: GRPC.Methods.UNARY },
+    handler: async (opts) => {
+      return create(SayHelloResponseSchema, { message: `Hello!` });
+    },
+  });
+}
+```
+
+#### 3. `bindRoute().to()` -- Fluent
+
+```typescript
+override binding() {
+  this.bindRoute({
+    configs: { name: 'sayHello', method: GRPC.Methods.UNARY },
+  }).to({
+    handler: async (opts) => {
+      return create(SayHelloResponseSchema, { message: `Hello!` });
+    },
+  });
+}
+```
+
+### The `binding()` Method
+
+An abstract method you override to register RPCs using `defineRoute()` or `bindRoute()`. Called during `configure()` before decorator-based RPCs are registered. If you only use decorators, provide an empty implementation:
+
+```typescript
+override binding() {}
+```
+
+### The `definitions` Property
+
+A `Record<string, IRpcRegistration>` that stores all registered RPC handlers keyed by their proto method name. Populated by both decorator-based and imperative registration. The `GrpcRequestAdapter` reads this to build ConnectRPC handlers.
+
+```typescript
+interface IRpcRegistration<RouteEnv extends Env = Env> {
+  configs: IRpcMetadata;
+  handler: TRpcHandler<unknown, unknown, RouteEnv>;
+  middlewares: TRpcMiddleware<RouteEnv>[];  // Pre-built auth middleware
+}
+```
+
+If you register a handler with the same `name` as an existing one, it overwrites the previous handler with a warning.
+
+### The `configure()` Lifecycle
+
+The `configure()` method on `AbstractGrpcController` is idempotent (guarded by `isConfigured` flag). It runs the following steps in order:
+
+1. **`binding()`** -- Your override, registers imperative/fluent routes
+2. **`registerRpcsFromRegistry()`** -- Discovers decorator-based RPCs from `MetadataRegistry` and calls `bindRoute()` for each
+3. **`GrpcRequestAdapter.build()`** -- Creates the ConnectRPC adapter and mounts it as Hono middleware on `this.router`
+
+## 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()`.
+
+### `@rpc` -- Generic
+
+The base decorator. Requires the full `IRpcMetadata` config including `method`:
+
+```typescript
+@rpc({ configs: { name: 'sayHello', method: GRPC.Methods.UNARY } })
+async sayHello(opts: { request: SayHelloRequest }): Promise<SayHelloResponse> {
+  // ...
+}
+```
+
+### `@unary`
+
+Shorthand for `@rpc` with `method: 'unary'`. Single request, single response.
+
+```typescript
+@unary({ configs: { name: 'sayHello' } })
+async sayHello(opts: { request: SayHelloRequest }): Promise<SayHelloResponse> {
+  return create(SayHelloResponseSchema, { message: `Hello, ${opts.request.name}!` });
+}
+```
+
+### `@serverStream` (unsupported)
+
+Shorthand for `@rpc` with `method: 'server_streaming'`. **Throws at boot time in the current version** -- streaming is not supported over HTTP/1.1 Connect protocol. Decorator preserved for forward compatibility.
+
+### `@clientStream` (unsupported)
+
+Shorthand for `@rpc` with `method: 'client_streaming'`. **Throws at boot time in the current version.**
+
+### `@bidiStream` (unsupported)
+
+Shorthand for `@rpc` with `method: 'bidi_streaming'`. **Throws at boot time in the current version.**
+
+### Decorator Config
+
+All decorators accept `{ configs: ... }` where configs extends `IRpcMetadata` (with `method` omitted for the shorthand variants):
+
+```typescript
+// @unary, @serverStream, @clientStream, @bidiStream
+{ configs: Omit<IRpcMetadata, 'method'> }
+
+// @rpc (generic)
+{ configs: IRpcMetadata }
+```
+
+## Type Definitions
+
+### `IRpcMetadata`
+
+Metadata stored per RPC method in the `MetadataRegistry`.
+
+```typescript
+interface IRpcMetadata {
+  /** Proto method name -- must match the RPC name in your .proto service definition. */
+  name: string;
+  /** RPC method type. */
+  method: TGrpcMethod;  // 'unary' | 'server_streaming' | 'client_streaming' | 'bidi_streaming'
+  /** Per-RPC authentication config. */
+  authenticate?: { strategies?: TAuthStrategy[]; mode?: TAuthMode };
+  /** Per-RPC authorization spec(s). */
+  authorize?: IAuthorizationSpec | IAuthorizationSpec[];
+}
+```
+
+### `IRpcRegistration`
+
+Unified entry stored in the controller's `definitions` map. Combines metadata, handler function, and pre-built auth middleware.
+
+```typescript
+interface IRpcRegistration<RouteEnv extends Env = Env> {
+  configs: IRpcMetadata;
+  handler: TRpcHandler<unknown, unknown, RouteEnv>;
+  middlewares: TRpcMiddleware<RouteEnv>[];
+}
+```
+
+### `TRpcMiddleware`
+
+Pre-built middleware function for gRPC auth enforcement, created by `AbstractGrpcController.buildRpcMiddlewares()`.
+
+```typescript
+type TRpcMiddleware<RouteEnv extends Env = Env> = (
+  context: TRouteContext<RouteEnv>,
+  next: Next,
+) => ValueOrPromise<void | Response>;
+```
+
+### `TRpcHandler`
+
+The handler signature for gRPC RPC methods. Receives the deserialized protobuf request and the Hono context (via `AsyncLocalStorage`).
+
+```typescript
+type TRpcHandler<
+  RequestType = unknown,
+  ResponseType = unknown,
+  RouteEnv extends Env = Env,
+> = (opts: {
+  request: RequestType;
+  context: TRouteContext<RouteEnv>;
+}) => ValueOrPromise<ResponseType>;
+```
+
+> [!NOTE]
+> When using decorator-based RPCs, the handler method signature is `(opts: { request: RequestType }) => Promise<ResponseType>`. The `context` parameter is injected internally by the adapter and is not passed to the decorator-based handler method directly. The full `TRpcHandler` signature (with `context`) applies when using `defineRoute()` or `bindRoute()`.
+
+### `IGrpcControllerOptions`
+
+Constructor options for gRPC controllers.
+
+```typescript
+interface IGrpcControllerOptions {
+  scope: string;
+  path?: string;
+}
+```
+
+### `IGrpcBindRouteOptions`
+
+Fluent binding returned by `bindRoute()`.
+
+```typescript
+interface IGrpcBindRouteOptions<RouteEnv extends Env = Env> {
+  configs: IRpcMetadata;
+  to: (opts: { handler: TRpcHandler<unknown, unknown, RouteEnv> }) => IGrpcDefineRouteOptions;
+}
+```
+
+### `IGrpcDefineRouteOptions`
+
+Return type from both `defineRoute()` and `bindRoute().to()`.
+
+```typescript
+interface IGrpcDefineRouteOptions {
+  configs: IRpcMetadata;
+}
+```
+
+### `IGrpcController`
+
+The full interface that gRPC controllers implement. Extends `IConfigurable`.
+
+```typescript
+interface IGrpcController<
+  RouteEnv extends Env = Env,
+  RouteSchema extends Schema = {},
+  BasePath extends string = '/',
+  ServiceType = unknown,
+  ConfigurableOptions extends object = {},
+> extends IConfigurable<ConfigurableOptions> {
+  service: ServiceType;
+  router: Hono<RouteEnv, RouteSchema, BasePath>;
+  definitions: Record<string, IRpcRegistration<RouteEnv>>;
+
+  getRouter(): Hono<RouteEnv, RouteSchema, BasePath>;
+  bindRoute(opts: { configs: IRpcMetadata }): IGrpcBindRouteOptions<RouteEnv>;
+  defineRoute(opts: {
+    configs: IRpcMetadata;
+    handler: TRpcHandler<unknown, unknown, RouteEnv>;
+  }): IGrpcDefineRouteOptions;
+}
+```
+
+### `IConnectAdapterResult`
+
+Return type from `GrpcRequestAdapter.build()`.
+
+```typescript
+interface IConnectAdapterResult<
+  RouteEnv extends Env = Env,
+  BasePath extends string = '/',
+  RouteInput extends Input = {},
+> {
+  paths: string[];
+  middleware: MiddlewareHandler<RouteEnv, BasePath, RouteInput>;
+}
+```
+
+## `GrpcRequestAdapter`
+
+Internal bridge between Ignis gRPC controllers and ConnectRPC's universal handler system. You do not interact with this class directly -- it is created automatically during `configure()`.
+
+### 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.
+
+```
+Hono Request
+  -> GrpcRequestAdapter middleware (path matching via basePath + controllerPath)
+    -> AsyncLocalStorage.run(honoContext, ...)
+      -> Pre-built auth middlewares (authenticate -> authorize)
+        -> ConnectRPC universal handler
+          -> Ignis TRpcHandler (reads context from AsyncLocalStorage)
+            -> Response
+```
+
+### Static `build()` Method
+
+The only public API. Validates peer deps via `validateModule()`, creates the adapter, and returns the middleware + registered paths:
+
+```typescript
+static async build(opts: {
+  controller: AbstractGrpcController<...>;
+  interceptors?: unknown[];
+}): Promise<IConnectAdapterResult<RouteEnv, BasePath>>
+```
+
+Called internally by `AbstractGrpcController.configure()`:
+
+```typescript
+const adapter = await GrpcRequestAdapter.build({ controller: this });
+this.router.use('*', adapter.middleware);
+```
+
+The optional `interceptors` array is passed to ConnectRPC's `createConnectRouter()` for request/response interception at the protocol level.
+
+### Internal Flow
+
+1. **`buildConnectHandlers()`** -- Wraps each Ignis `TRpcHandler` into ConnectRPC's `(request, context) => response` signature. The wrapper reads the Hono context from `AsyncLocalStorage`, runs pre-built auth middlewares (built by `AbstractGrpcController.buildRpcMiddlewares()`), then passes `{ request, context }` to the Ignis handler.
+
+2. **`registerService()`** -- Bridges the opaque `ServiceType` from `@controller` metadata to ConnectRPC's `router.service()` call, registering all handlers for the service.
+
+3. **`buildMiddleware()`** -- Creates a Hono middleware that:
+   - Strips the full mount prefix (`basePath + controllerPath`) from the request URL to derive the ConnectRPC handler path (e.g., `/package.Service/Method`)
+   - Looks up the ConnectRPC handler by path from the handler map
+   - Runs the handler inside `AsyncLocalStorage.run()` with the current Hono context
+   - Converts between Fetch API `Request`/`Response` and ConnectRPC's `UniversalServerRequest`/`UniversalServerResponse` formats
+   - Returns proper gRPC error responses on failure (with `grpc-status` and `grpc-message` headers)
+
+### Peer Dependency Loading
+
+The adapter loads ConnectRPC modules at runtime using `createRequire` from the application's `node_modules`:
+
+- `@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`.
+
+### Error Handling
+
+On handler errors, the adapter returns a JSON response with:
+- HTTP status: `200` if gRPC status is `OK`, `500` otherwise
+- `grpc-status` header: Preserved from `ConnectError.code` if available (duck-type check on `error.code` being a number), otherwise `13` (INTERNAL)
+- `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.
+
+## `GrpcComponent`
+
+Auto-discovers and configures gRPC controllers during the application lifecycle.
+
+### Configuration
+
+```typescript
+interface IGrpcComponentConfig {
+  interceptors?: unknown[];
+}
+```
+
+The component registers a default (empty) config binding under the key `'@app/grpc/options'` (`GrpcBindingKeys.GRPC_COMPONENT_OPTIONS`).
+
+### Behavior
+
+1. Finds all bindings tagged with the `controllers` namespace
+2. Filters to controllers whose metadata has `transport: 'grpc'`
+3. Validates each gRPC controller:
+   - If `path` is missing, throws an error
+   - If `service` is missing, logs a warning and skips the controller
+4. Sets `instance.basePath` from the application's `path.base` config (needed for correct path stripping in the adapter)
+5. Calls `configure()` on each controller instance
+6. Mounts the controller's router on the application's root router at the controller's path via `router.route(metadata.path, instance.getRouter())`
+
+### Dynamic Discovery
+
+The component uses a re-fetch loop with `Set` tracking. After configuring each controller, it re-queries the container for new controller bindings (excluding already-configured ones). This handles controllers registered dynamically during component composition (e.g., a component that registers another component that registers a gRPC controller).
+
+### Automatic Registration
+
+`GrpcComponent` is instantiated and configured automatically by `BaseApplication` when `appConfigs.transports` includes `ControllerTransports.GRPC`. You do not need to register it manually. The relevant code in `BaseApplication`:
+
+```typescript
+case ControllerTransports.GRPC: {
+  const grpcComponent = new GrpcComponent(this);
+  await grpcComponent.configure();
+  break;
+}
+```
+
+## `GRPC` Constants
+
+The `GRPC` class from `@venizia/ignis-helpers` provides all gRPC protocol constants:
+
+### Methods
+
+```typescript
+GRPC.Methods.UNARY              // 'unary'
+GRPC.Methods.SERVER_STREAMING   // 'server_streaming'
+GRPC.Methods.CLIENT_STREAMING   // 'client_streaming'
+GRPC.Methods.BIDI_STREAMING     // 'bidi_streaming'
+```
+
+### Result Codes
+
+Standard gRPC status codes (matching `google.rpc.Code`):
+
+```typescript
+GRPC.ResultCodes.OK                 // 0
+GRPC.ResultCodes.CANCELLED          // 1
+GRPC.ResultCodes.UNKNOWN            // 2
+GRPC.ResultCodes.INVALID_ARGUMENT   // 3
+GRPC.ResultCodes.DEADLINE_EXCEEDED  // 4
+GRPC.ResultCodes.NOT_FOUND          // 5
+GRPC.ResultCodes.ALREADY_EXISTS     // 6
+GRPC.ResultCodes.PERMISSION_DENIED  // 7
+GRPC.ResultCodes.RESOURCE_EXHAUSTED // 8
+GRPC.ResultCodes.FAILED_PRECONDITION // 9
+GRPC.ResultCodes.ABORTED           // 10
+GRPC.ResultCodes.OUT_OF_RANGE      // 11
+GRPC.ResultCodes.UNIMPLEMENTED     // 12
+GRPC.ResultCodes.INTERNAL          // 13
+GRPC.ResultCodes.UNAVAILABLE       // 14
+GRPC.ResultCodes.DATA_LOSS         // 15
+GRPC.ResultCodes.UNAUTHENTICATED   // 16
+```
+
+### Headers
+
+Standard gRPC protocol headers:
+
+```typescript
+GRPC.Headers.GRPC_STATUS       // 'grpc-status'
+GRPC.Headers.GRPC_MESSAGE      // 'grpc-message'
+GRPC.Headers.GRPC_TIMEOUT      // 'grpc-timeout'
+GRPC.Headers.GRPC_ENCODING     // 'grpc-encoding'
+// ... and more (see packages/helpers/src/common/constants/grpc.ts)
+```
+
+### Content Types
+
+```typescript
+GRPC.HeaderValues.GRPC           // 'application/grpc'
+GRPC.HeaderValues.GRPC_PROTO     // 'application/grpc+proto'
+GRPC.HeaderValues.GRPC_JSON      // 'application/grpc+json'
+GRPC.HeaderValues.GRPC_WEB       // 'application/grpc-web'
+GRPC.HeaderValues.GRPC_WEB_PROTO // 'application/grpc-web+proto'
+GRPC.HeaderValues.GRPC_WEB_JSON  // 'application/grpc-web+json'
+GRPC.HeaderValues.GRPC_WEB_TEXT  // 'application/grpc-web-text'
+```
+
+## Application Setup
+
+### Enabling gRPC Transport
+
+Add `ControllerTransports.GRPC` to the `transports` array in your application configs:
+
+```typescript
+import {
+  BaseApplication,
+  ControllerTransports,
+  IApplicationConfigs,
+  IApplicationInfo,
+} from '@venizia/ignis';
+import { ValueOrPromise } from '@venizia/ignis-helpers';
+import { GreeterController } from './controllers/greeter';
+import { GreeterService } from './services/greeter.service';
+
+export const appConfigs: IApplicationConfigs = {
+  host: '0.0.0.0',
+  port: 3000,
+  path: { base: '/', isStrict: false },
+  transports: [ControllerTransports.REST, ControllerTransports.GRPC],
+};
+
+export class Application extends BaseApplication {
+  getAppInfo(): ValueOrPromise<IApplicationInfo> {
+    return { name: 'my-app', version: '1.0.0', description: 'gRPC + REST app' };
+  }
+
+  staticConfigure() {}
+
+  preConfigure() {
+    this.service(GreeterService);
+    this.controller(GreeterController);
+  }
+
+  postConfigure() {}
+  setupMiddlewares() {}
+}
+```
+
+> [!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.
+
+### Dual Transport
+
+REST and gRPC controllers coexist in the same application. Each controller declares its own transport via the `@controller` decorator. A single application can serve both:
+
+```typescript
+preConfigure() {
+  // gRPC controller
+  this.controller(GreeterController);
+
+  // REST controller
+  this.controller(StatusController);
+}
+```
+
+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.
+
+## Complete Example
+
+### 1. Proto File
+
+```protobuf
+// proto/greeter.proto
+syntax = "proto3";
+package greeter.v1;
+
+message SayHelloRequest {
+  string name = 1;
+}
+
+message SayHelloResponse {
+  string message = 1;
+}
+
+message ListUsersRequest {}
+
+message ListUsersResponse {
+  repeated string users = 1;
+}
+
+service GreeterService {
+  rpc SayHello (SayHelloRequest) returns (SayHelloResponse);
+  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
+}
+```
+
+### 2. Generate TypeScript Code
+
+```bash
+buf generate proto/greeter.proto
+```
+
+### 3. Definition File (Stable Import Boundary)
+
+```typescript
+// controllers/greeter/definition.ts
+export {
+  GreeterService,
+  ListUsersResponseSchema,
+  SayHelloResponseSchema,
+  type ListUsersRequest,
+  type ListUsersResponse,
+  type SayHelloRequest,
+  type SayHelloResponse,
+} from './generated/greeter_pb';
+```
+
+> [!TIP]
+> Always re-export generated code through a `definition.ts` file. This acts as a stable import boundary -- controller code and external consumers import from here, never from the `generated/` directory directly. When you regenerate protos, only this file needs updating.
+
+### 4. Controller
+
+```typescript
+// controllers/greeter/controller.ts
+import { GreeterService } from '@/services';
+import { create } from '@bufbuild/protobuf';
+import {
+  BaseGrpcController,
+  ControllerTransports,
+  controller,
+  inject,
+  unary,
+} from '@venizia/ignis';
+import {
+  GreeterService as GreeterServiceDef,
+  ListUsersResponseSchema,
+  SayHelloResponseSchema,
+  type ListUsersRequest,
+  type ListUsersResponse,
+  type SayHelloRequest,
+  type SayHelloResponse,
+} from './definition';
+
+@controller({
+  path: '/grpc',
+  transport: ControllerTransports.GRPC,
+  service: GreeterServiceDef,
+})
+export class GreeterController extends BaseGrpcController {
+  constructor(
+    @inject({ key: 'services.GreeterService' })
+    private readonly greeterService: GreeterService,
+  ) {
+    super({ scope: 'GreeterController', path: '/grpc' });
+  }
+
+  override binding() {}
+
+  @unary({ configs: { name: 'sayHello' } })
+  async sayHello(opts: { request: SayHelloRequest }): Promise<SayHelloResponse> {
+    const message = await this.greeterService.sayHello(opts);
+    return create(SayHelloResponseSchema, { message });
+  }
+
+  @unary({ configs: { name: 'listUsers' } })
+  async listUsers(opts: { request: ListUsersRequest }): Promise<ListUsersResponse> {
+    const users = await this.greeterService.listUsers(opts);
+    return create(ListUsersResponseSchema, { users });
+  }
+}
+```
+
+### 5. Minimal Controller (No DI)
+
+A controller with no injected dependencies:
+
+```typescript
+// controllers/echo/controller.ts
+import { create } from '@bufbuild/protobuf';
+import {
+  BaseGrpcController,
+  ControllerTransports,
+  controller,
+  unary,
+} from '@venizia/ignis';
+import {
+  EchoResponseSchema,
+  EchoService as EchoServiceDef,
+  type EchoRequest,
+  type EchoResponse,
+} from './definition';
+
+@controller({
+  path: '/grpc',
+  transport: ControllerTransports.GRPC,
+  service: EchoServiceDef,
+})
+export class EchoController extends BaseGrpcController {
+  constructor() {
+    super({ scope: 'EchoController', path: '/grpc' });
+  }
+
+  override binding() {}
+
+  @unary({ configs: { name: 'echo' } })
+  async echo(opts: { request: EchoRequest }): Promise<EchoResponse> {
+    return create(EchoResponseSchema, {
+      message: `Echo: ${opts.request.message}`,
+    });
+  }
+}
+```
+
+### 6. Application
+
+```typescript
+// application.ts
+import {
+  BaseApplication,
+  ControllerTransports,
+  IApplicationConfigs,
+  IApplicationInfo,
+} from '@venizia/ignis';
+import { ValueOrPromise } from '@venizia/ignis-helpers';
+import { GreeterController } from './controllers/greeter';
+import { EchoController } from './controllers/echo';
+import { GreeterService } from './services/greeter.service';
+
+export const appConfigs: IApplicationConfigs = {
+  host: '0.0.0.0',
+  port: 3000,
+  path: { base: '/', isStrict: false },
+  transports: [ControllerTransports.REST, ControllerTransports.GRPC],
+};
+
+export class Application extends BaseApplication {
+  getAppInfo(): ValueOrPromise<IApplicationInfo> {
+    return { name: 'greeter-app', version: '1.0.0', description: 'gRPC greeter' };
+  }
+
+  staticConfigure() {}
+
+  preConfigure() {
+    this.service(GreeterService);
+    this.controller(GreeterController);
+    this.controller(EchoController);
+  }
+
+  postConfigure() {}
+  setupMiddlewares() {}
+}
+```
+
+### 7. Client (Testing)
+
+```typescript
+// client.ts
+import { create } from '@bufbuild/protobuf';
+import { createClient } from '@connectrpc/connect';
+import { createConnectTransport } from '@connectrpc/connect-web';
+import { GreeterService, SayHelloRequestSchema } from './controllers/greeter/definition';
+
+const transport = createConnectTransport({ baseUrl: 'http://localhost:3000/grpc' });
+const client = createClient(GreeterService, transport);
+
+const response = await client.sayHello(create(SayHelloRequestSchema, { name: 'Ignis' }));
+console.log(response.message);
+```
+
+## Component-Based Registration
+
+gRPC controllers can be registered through components, following the same pattern as REST controllers. This enables modular composition and late registration.
+
+### Basic Component
+
+```typescript
+import {
+  BaseApplication,
+  BaseComponent,
+  CoreBindings,
+  inject,
+} from '@venizia/ignis';
+import { ValueOrPromise } from '@venizia/ignis-helpers';
+import { EchoController } from '../controllers/echo';
+
+export class EchoComponent extends BaseComponent {
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE })
+    private application: BaseApplication,
+  ) {
+    super({ scope: 'EchoComponent' });
+  }
+
+  override binding(): ValueOrPromise<void> {
+    this.application.controller(EchoController);
+  }
+}
+```
+
+### Component Composition
+
+Components can compose other components, building a dependency graph of controllers:
+
+```typescript
+import {
+  BaseApplication,
+  BaseComponent,
+  CoreBindings,
+  inject,
+} from '@venizia/ignis';
+import { TimeController } from '../controllers/time';
+import { EchoComponent } from './echo.component';
+
+export class TimeComponent extends BaseComponent {
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE })
+    private application: BaseApplication,
+  ) {
+    super({ scope: 'TimeComponent' });
+  }
+
+  override async binding(): Promise<void> {
+    // Compose EchoComponent -- registers EchoController
+    this.application.component(EchoComponent);
+
+    // Register this component's own controller
+    this.application.controller(TimeController);
+  }
+}
+```
+
+The `GrpcComponent` handles these dynamically-registered controllers through its re-fetch loop -- after configuring each controller, it re-queries the container for newly added bindings.
+
+### Registration in Application
+
+```typescript
+preConfigure() {
+  // TimeComponent composes EchoComponent internally
+  this.component(TimeComponent);
+}
+```
+
+## Authentication and Authorization
+
+Per-RPC authentication and authorization are configured via the `authenticate` and `authorize` fields in `IRpcMetadata`. Auth middlewares are pre-built during route registration by `AbstractGrpcController.buildRpcMiddlewares()` and executed before the handler inside the `AsyncLocalStorage` context.
+
+### Per-RPC Authentication
+
+```typescript
+@unary({
+  configs: {
+    name: 'sayHello',
+    authenticate: {
+      strategies: ['jwt'],
+      mode: 'required',
+    },
+  },
+})
+async sayHello(opts: { request: SayHelloRequest }): Promise<SayHelloResponse> {
+  // Only accessible with a valid JWT token
+  return create(SayHelloResponseSchema, { message: 'Hello!' });
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `strategies` | `TAuthStrategy[]` | `[]` | Authentication strategies to apply (e.g., `['jwt']`, `['basic']`) |
+| `mode` | `TAuthMode` | `'any'` | `'required'` \| `'optional'` \| `'any'` \| `'all'` (defaults to `AuthenticationModes.ANY`) |
+
+### Per-RPC Authorization
+
+```typescript
+@unary({
+  configs: {
+    name: 'deleteUser',
+    authenticate: { strategies: ['jwt'], mode: 'required' },
+    authorize: { action: 'delete', resource: 'user' },
+  },
+})
+async deleteUser(opts: { request: DeleteUserRequest }): Promise<DeleteUserResponse> {
+  // Requires JWT + delete permission on user resource
+  // ...
+}
+```
+
+Multiple authorization specs can be provided as an array:
+
+```typescript
+authorize: [
+  { action: 'read', resource: 'user' },
+  { action: 'read', resource: 'profile' },
+]
+```
+
+### Middleware Execution Order
+
+Auth middlewares run in the following order inside the ConnectRPC handler wrapper:
+
+1. **Authenticate** middlewares (if `configs.authenticate.strategies` has entries)
+2. **Authorize** middlewares (if `configs.authorize` is present), one per spec
+3. **Handler** execution
+
+## See Also
+
+- [Controllers Reference](./controllers.md) -- REST controller classes and API endpoint patterns
+- [Components Reference](./components.md) -- Component system and built-in components
+- [Dependency Injection](./dependency-injection.md) -- IoC container, `@inject`, binding keys
+- [Services](./services.md) -- Business logic layer