@smounters/imperium 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to `@smounters/imperium` are documented in this file.
 
+## 1.1.0 - 2026-03-29
+
+### Added
+- **Server Streaming RPC** — `async function*` handlers via ConnectRPC. Delivered as SSE (Server-Sent Events) in browsers without WebSocket.
+- **`@RpcAbortSignal()` decorator** — injects `AbortSignal` from `HandlerContext.signal` for detecting client disconnects in streaming handlers.
+- **WebSocket Gateway** — real-time bidirectional communication via `@fastify/websocket` (optional peer dependency).
+  - `@WsGateway(path)` — marks a class as a WebSocket gateway, registers on the specified path.
+  - `@WsHandler(messageType)` — routes incoming JSON messages by `type` field.
+  - `@WsConnection()`, `@WsMessage()`, `@WsRequest()` — parameter decorators for handler methods.
+  - Lifecycle hooks: `onConnection(socket, req)`, `onDisconnect(socket)`.
+  - Guards execute at connection time (upgrade request).
+- **`./ws` subpath export** — `@smounters/imperium/ws` exposes `registerWsGateways`, `WsGatewayLifecycle`, and related types.
+- `BaseContext` extended with `type: "ws"`, `switchToWs()`, and `WsArgumentsHost` interface.
+
+### Changed
+- `ContextType` is now `"http" | "rpc" | "ws"` (was `"http" | "rpc"`).
+- `RpcParamSource` extended with `"abort_signal"`.
+- RPC router builder no longer throws on `server_streaming` methods; only `client_streaming` and `bidi_streaming` are unsupported.
+- `WsArgumentsHost` methods return `| undefined` for type safety across context switches (no unsafe casts).
+- Peer dependency `@fastify/websocket ^11.0.0` added as optional.
+
+### Updated
+- `@types/node` 24.x → 25.x.
+- `@typescript-eslint/*` 8.56 → 8.57.
+- `eslint` 10.0 → 10.1.
+- `fastify` 5.7 → 5.8.
+
 ## 1.0.3 - 2026-03-20
 
 ### Fixed

package/README.md

@@ -1,13 +1,15 @@
 # @smounters/imperium
 
-`@smounters/imperium` is **inspired by NestJS** and provides a modular DI-first runtime for TypeScript services using Fastify + ConnectRPC.
+`@smounters/imperium` is **inspired by NestJS** and provides a modular DI-first runtime for TypeScript services using Fastify + ConnectRPC + WebSocket.
 
 It is designed for teams that want Nest-like architecture but with explicit control over runtime wiring and exported API surface.
 
 ## Key Features
 
 - Nest-like modules and decorators (`@Module`, `@Injectable`, guards/pipes/interceptors/filters).
-- Unified HTTP + RPC server on one Fastify instance.
+- Unified HTTP + RPC + WebSocket server on one Fastify instance.
+- Server streaming RPC via `async function*` (delivered as SSE in browsers).
+- WebSocket gateway with message routing, lifecycle hooks, and guards at connection time.
 - Request-scoped handler execution.
 - Typed runtime config via `zod` + `ConfigService`.
 - Built-in `LoggerService` (tslog-based).
@@ -25,6 +27,7 @@ Use subpaths only:
 - `@smounters/imperium/services`
 - `@smounters/imperium/pipes`
 - `@smounters/imperium/validation`
+- `@smounters/imperium/ws`
 
 ## Installation
 
@@ -162,9 +165,39 @@ const rules = app.resolveAll<AmlRule>(AML_RULES);
 Use decorators from `@smounters/imperium/decorators`:
 
 - HTTP: `HttpController`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `Body`, `Query`, `Param`, `Header`, `Req`, `Res`
-- RPC: `RpcService`, `RpcMethod`, `RpcData`, `RpcContext`, `RpcHeaders`, `RpcHeader`
+- RPC: `RpcService`, `RpcMethod`, `RpcData`, `RpcContext`, `RpcHeaders`, `RpcHeader`, `RpcAbortSignal`
+- WebSocket: `WsGateway`, `WsHandler`, `WsConnection`, `WsMessage`, `WsRequest`
 
-Imperium auto-detects registered HTTP/RPC handlers and serves both protocols from one server.
+Imperium auto-detects registered HTTP/RPC/WebSocket handlers and serves all protocols from one server.
+
+## WebSocket
+
+```ts
+import { WsGateway, WsHandler, WsConnection, WsMessage, Module } from "@smounters/imperium/decorators";
+import type { WsGatewayLifecycle } from "@smounters/imperium/ws";
+import type { WebSocket } from "@fastify/websocket";
+
+@WsGateway("/ws")
+class ChatGateway implements WsGatewayLifecycle {
+  private clients = new Set<WebSocket>();
+
+  onConnection(socket: WebSocket) { this.clients.add(socket); }
+  onDisconnect(socket: WebSocket) { this.clients.delete(socket); }
+
+  @WsHandler("message")
+  onMessage(@WsConnection() ws: WebSocket, @WsMessage() data: { text: string }) {
+    const msg = JSON.stringify({ type: "message", data });
+    for (const client of this.clients) {
+      if (client.readyState === 1) client.send(msg);
+    }
+  }
+}
+
+@Module({ providers: [ChatGateway] })
+class AppModule {}
+```
+
+Requires optional peer dependency: `pnpm add @fastify/websocket`
 
 ## Services
 

package/dist/core/container.d.ts

@@ -11,8 +11,10 @@ export declare class AppContainer {
     private readonly loadingModules;
     private readonly rpcControllerSet;
     private readonly httpControllerSet;
+    private readonly wsGatewaySet;
     private readonly rpcControllerModules;
     private readonly httpControllerModules;
+    private readonly wsGatewayModules;
     private readonly lifecycleTargets;
     private readonly requestScopeOwners;
     private readonly requestScopeLinkedScopes;
@@ -20,6 +22,7 @@ export declare class AppContainer {
     private rootModuleRef;
     private controllers;
     private httpControllers;
+    private wsGateways;
     private lifecycleInstances;
     private initialized;
     private closed;
@@ -65,6 +68,7 @@ export declare class AppContainer {
     createRequestScope(controller?: Constructor): DependencyContainer;
     getControllers(): Constructor[];
     getHttpControllers(): Constructor[];
+    getWsGateways(): Constructor[];
     setGlobalGuards(guards: GuardLike[]): void;
     getGlobalGuards(): GuardLike[];
     setGlobalInterceptors(inters: InterceptorLike[]): void;

package/dist/core/container.js

@@ -2,6 +2,7 @@ import "reflect-metadata";
 import { container, Lifecycle } from "tsyringe";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { MODULE_KEY } from "../decorators/di.decorators";
+import { WS_GATEWAY_KEY } from "../decorators/ws.decorators";
 import { ConfigService, LoggerService } from "../services";
 import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from "./app-tokens";
 import { CONFIG_TOKEN } from "./config";
@@ -121,8 +122,10 @@ export class AppContainer {
         this.loadingModules = new Set();
         this.rpcControllerSet = new Set();
         this.httpControllerSet = new Set();
+        this.wsGatewaySet = new Set();
         this.rpcControllerModules = new Map();
         this.httpControllerModules = new Map();
+        this.wsGatewayModules = new Map();
         this.lifecycleTargets = [];
         this.requestScopeOwners = new WeakMap();
         this.requestScopeLinkedScopes = new WeakMap();
@@ -130,6 +133,7 @@ export class AppContainer {
         this.rootModuleRef = null;
         this.controllers = [];
         this.httpControllers = [];
+        this.wsGateways = [];
         this.lifecycleInstances = null;
         this.initialized = false;
         this.closed = false;
@@ -324,7 +328,7 @@ export class AppContainer {
         }
     }
     resolveControllerModule(controller) {
-        return this.httpControllerModules.get(controller) ?? this.rpcControllerModules.get(controller);
+        return this.httpControllerModules.get(controller) ?? this.rpcControllerModules.get(controller) ?? this.wsGatewayModules.get(controller);
     }
     getOrCreateLinkedScopes(originScope) {
         const existing = this.requestScopeLinkedScopes.get(originScope);
@@ -433,6 +437,17 @@ export class AppContainer {
                 this.httpControllerModules.set(ctrl, moduleRef);
                 this.httpControllers.push(ctrl);
             }
+            // Detect WS gateways among providers
+            for (const provider of meta.providers) {
+                const providerClass = typeof provider === "function" ? provider : undefined;
+                if (providerClass && Reflect.hasMetadata(WS_GATEWAY_KEY, providerClass)) {
+                    if (!this.wsGatewaySet.has(providerClass)) {
+                        this.wsGatewaySet.add(providerClass);
+                        this.wsGatewayModules.set(providerClass, moduleRef);
+                        this.wsGateways.push(providerClass);
+                    }
+                }
+            }
             moduleRef.exportedTokens = this.resolveModuleExports(moduleRef);
             if (moduleRef.meta.global) {
                 this.registerGlobalExports(moduleRef);
@@ -660,6 +675,9 @@ export class AppContainer {
     getHttpControllers() {
         return [...this.httpControllers];
     }
+    getWsGateways() {
+        return [...this.wsGateways];
+    }
     setGlobalGuards(guards) {
         this.globalGuards = [...guards];
     }

package/dist/core/server.js

@@ -6,6 +6,7 @@ import { HTTP_ROUTES_KEY } from "../decorators/http.decorators";
 import { RPC_METHODS_KEY, RPC_SERVICE_KEY } from "../decorators/rpc.decorators";
 import { registerHttpRoutes } from "../http";
 import { buildConnectRoutes } from "../rpc";
+import { registerWsGateways } from "../ws";
 import { AppContainer } from "./container";
 function normalizePrefix(prefix) {
     if (!prefix) {
@@ -151,8 +152,9 @@ export async function startServer(diOrOptions, options) {
     const healthConfig = resolveHealth(health);
     const http = hasRegisteredHttpHandlers(di);
     const rpc = hasRegisteredRpcHandlers(di);
-    if (!http && !rpc && !healthConfig.enabled) {
-        throw new Error("No handlers found for HTTP or RPC. Register controllers in @Module().");
+    const ws = di.getWsGateways().length > 0;
+    if (!http && !rpc && !ws && !healthConfig.enabled) {
+        throw new Error("No handlers found for HTTP, RPC, or WebSocket. Register controllers in @Module().");
     }
     let server;
     try {
@@ -254,6 +256,9 @@ export async function startServer(diOrOptions, options) {
                 routes: buildConnectRoutes(di),
             });
         }
+        if (ws) {
+            await registerWsGateways(server, di);
+        }
         await server.listen({ port: listenPort, host });
         return server;
     }

package/dist/core/types.d.ts

@@ -11,7 +11,7 @@ export interface HttpParamMeta {
     source: HttpParamSource;
     key?: string;
 }
-export type RpcParamSource = "data" | "context" | "headers" | "header";
+export type RpcParamSource = "data" | "context" | "headers" | "header" | "abort_signal";
 export interface RpcParamMeta {
     index: number;
     source: RpcParamSource;

package/dist/decorators/index.d.ts

@@ -5,4 +5,5 @@ export { Body, Delete, Get, Header, HttpController, Param, Patch, Post, Put, Que
 export { UseInterceptors } from "./interceptors.decorators";
 export { SetMetadata } from "./metadata.decorators";
 export { UsePipes } from "./pipes.decorators";
-export { RpcContext, RpcData, RpcHeader, RpcHeaders, RpcMethod, RpcService } from "./rpc.decorators";
+export { RpcAbortSignal, RpcContext, RpcData, RpcHeader, RpcHeaders, RpcMethod, RpcService } from "./rpc.decorators";
+export { WsConnection, WsGateway, WsHandler, WsMessage, WsRequest } from "./ws.decorators";

package/dist/decorators/index.js

@@ -5,4 +5,5 @@ export { Body, Delete, Get, Header, HttpController, Param, Patch, Post, Put, Que
 export { UseInterceptors } from "./interceptors.decorators";
 export { SetMetadata } from "./metadata.decorators";
 export { UsePipes } from "./pipes.decorators";
-export { RpcContext, RpcData, RpcHeader, RpcHeaders, RpcMethod, RpcService } from "./rpc.decorators";
+export { RpcAbortSignal, RpcContext, RpcData, RpcHeader, RpcHeaders, RpcMethod, RpcService } from "./rpc.decorators";
+export { WsConnection, WsGateway, WsHandler, WsMessage, WsRequest } from "./ws.decorators";

package/dist/decorators/rpc.decorators.d.ts

@@ -9,3 +9,4 @@ export declare const RpcData: (key?: string) => ParameterDecorator;
 export declare const RpcContext: () => ParameterDecorator;
 export declare const RpcHeaders: () => ParameterDecorator;
 export declare const RpcHeader: (key: string) => ParameterDecorator;
+export declare const RpcAbortSignal: () => ParameterDecorator;

package/dist/decorators/rpc.decorators.js

@@ -48,3 +48,4 @@ export const RpcData = (key) => rpcParamDecorator("data", key);
 export const RpcContext = () => rpcParamDecorator("context");
 export const RpcHeaders = () => rpcParamDecorator("headers");
 export const RpcHeader = (key) => rpcParamDecorator("header", key);
+export const RpcAbortSignal = () => rpcParamDecorator("abort_signal");

package/dist/decorators/ws.decorators.d.ts

@@ -0,0 +1,9 @@
+import "reflect-metadata";
+export declare const WS_GATEWAY_KEY: unique symbol;
+export declare const WS_HANDLERS_KEY: unique symbol;
+export declare const WS_PARAMS_KEY: unique symbol;
+export declare function WsGateway(path?: string): ClassDecorator;
+export declare function WsHandler(messageType: string): MethodDecorator;
+export declare const WsConnection: () => ParameterDecorator;
+export declare const WsMessage: () => ParameterDecorator;
+export declare const WsRequest: () => ParameterDecorator;

package/dist/decorators/ws.decorators.js

@@ -0,0 +1,43 @@
+import "reflect-metadata";
+import { Injectable } from "./di.decorators";
+export const WS_GATEWAY_KEY = Symbol("ws:gateway");
+export const WS_HANDLERS_KEY = Symbol("ws:handlers");
+export const WS_PARAMS_KEY = Symbol("ws:params");
+export function WsGateway(path = "/ws") {
+    return (target) => {
+        Injectable()(target);
+        const meta = { path };
+        Reflect.defineMetadata(WS_GATEWAY_KEY, meta, target);
+    };
+}
+export function WsHandler(messageType) {
+    return (target, propertyKey) => {
+        const handlers = Reflect.getMetadata(WS_HANDLERS_KEY, target.constructor) ?? [];
+        handlers.push({ messageType, handlerName: propertyKey });
+        Reflect.defineMetadata(WS_HANDLERS_KEY, handlers, target.constructor);
+    };
+}
+function getMetaTarget(target, propertyKey) {
+    if (propertyKey === undefined) {
+        return target;
+    }
+    const value = target[propertyKey];
+    if (typeof value !== "object" && typeof value !== "function") {
+        throw new Error("Decorator target is not an object");
+    }
+    return value;
+}
+function setParamMeta(target, propertyKey, meta) {
+    const metaTarget = getMetaTarget(target, propertyKey);
+    const existing = Reflect.getMetadata(WS_PARAMS_KEY, metaTarget);
+    const next = existing ? [...existing, meta] : [meta];
+    Reflect.defineMetadata(WS_PARAMS_KEY, next, metaTarget);
+}
+function wsParamDecorator(source) {
+    return (target, propertyKey, index) => {
+        setParamMeta(target, propertyKey ?? undefined, { index, source });
+    };
+}
+export const WsConnection = () => wsParamDecorator("connection");
+export const WsMessage = () => wsParamDecorator("message");
+export const WsRequest = () => wsParamDecorator("request");

package/dist/http/adapter.js

@@ -135,6 +135,11 @@ export function createHttpHandler(app, controller, methodName) {
                     getData: () => undefined,
                     getContext: () => undefined,
                 }),
+                switchToWs: () => ({
+                    getSocket: () => undefined,
+                    getRequest: () => undefined,
+                    getMessage: () => undefined,
+                }),
             };
             try {
                 const instance = requestScope.resolve(controller);
@@ -159,7 +164,7 @@ export function createHttpHandler(app, controller, methodName) {
                     transformedArgs[index] = value;
                 }
                 const interceptors = collectInterceptorsForHttp(controller, methodName, app.getGlobalInterceptors()).map((interceptorLike) => resolveEnhancer(requestScope, interceptorLike));
-                const controllerHandler = (instance[methodName].bind(instance));
+                const controllerHandler = instance[methodName].bind(instance);
                 let idx = -1;
                 const next = async () => {
                     idx++;

package/dist/rpc/adapter.js

@@ -50,6 +50,9 @@ function buildRpcArgs(payload, context, handler) {
             case "header":
                 args[meta.index] = meta.key ? context.requestHeader.get(meta.key) : undefined;
                 break;
+            case "abort_signal":
+                args[meta.index] = context.signal;
+                break;
         }
     }
     return args;
@@ -124,6 +127,11 @@ export function createRpcHandler(app, controller, methodName) {
                     getData: () => req,
                     getContext: () => context,
                 }),
+                switchToWs: () => ({
+                    getSocket: () => undefined,
+                    getRequest: () => undefined,
+                    getMessage: () => undefined,
+                }),
             };
             try {
                 const instance = scope.resolve(controller);

package/dist/rpc/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./adapter";
+export * from "./streaming-adapter";
 export * from "./router-builder";
 export * from "./utils";

package/dist/rpc/index.js

@@ -1,3 +1,4 @@
 export * from "./adapter";
+export * from "./streaming-adapter";
 export * from "./router-builder";
 export * from "./utils";

package/dist/rpc/router-builder.js

@@ -1,15 +1,7 @@
 import "reflect-metadata";
 import { RPC_METHODS_KEY, RPC_SERVICE_KEY } from "../decorators/rpc.decorators";
 import { createRpcHandler } from "./adapter";
-function assertUnaryRpcMethod(controller, handlerName, method) {
-    if (method.methodKind === "unary") {
-        return;
-    }
-    const serviceName = method.parent.name;
-    const rpcName = method.name;
-    throw new Error(`Streaming RPC methods are not supported: ${serviceName}.${rpcName} (${method.methodKind}) ` +
-        `at ${controller.name}.${handlerName}. Only unary methods are supported.`);
-}
+import { createStreamingRpcHandler } from "./streaming-adapter";
 export function buildConnectRoutes(di) {
     return (router) => {
         for (const ctrl of di.getControllers()) {
@@ -20,8 +12,18 @@ export function buildConnectRoutes(di) {
             }
             const methods = Reflect.getMetadata(RPC_METHODS_KEY, controller) ?? [];
             for (const { method, handlerName } of methods) {
-                assertUnaryRpcMethod(controller, handlerName, method);
-                router.rpc(method, createRpcHandler(di, controller, handlerName));
+                if (method.methodKind === "unary") {
+                    router.rpc(method, createRpcHandler(di, controller, handlerName));
+                }
+                else if (method.methodKind === "server_streaming") {
+                    router.rpc(method, createStreamingRpcHandler(di, controller, handlerName));
+                }
+                else {
+                    const serviceName = method.parent.name;
+                    const rpcName = method.name;
+                    throw new Error(`Client streaming and bidi streaming are not supported: ${serviceName}.${rpcName} (${method.methodKind}) ` +
+                        `at ${controller.name}.${handlerName}. Use unary or server_streaming.`);
+                }
             }
         }
     };

package/dist/rpc/streaming-adapter.d.ts

@@ -0,0 +1,5 @@
+import type { HandlerContext } from "@connectrpc/connect";
+import "reflect-metadata";
+import type { AppContainer } from "../core/container";
+import type { Constructor } from "../types";
+export declare function createStreamingRpcHandler<TController extends Record<string, unknown>>(app: AppContainer, controller: Constructor<TController>, methodName: keyof TController & string): (req: unknown, context: HandlerContext) => AsyncIterable<unknown>;

package/dist/rpc/streaming-adapter.js

@@ -0,0 +1,186 @@
+import "reflect-metadata";
+import { ForbiddenException, toConnectError } from "../core/errors";
+import { CATCH_EXCEPTIONS_KEY } from "../decorators/filters.decorators";
+import { RPC_PARAMS_KEY } from "../decorators/rpc.decorators";
+import { LoggerService } from "../services";
+import { collectFiltersForRpc, collectGuardsForRpc, collectPipesForRpc } from "./utils";
+function logRpcError(app, scope, details, error) {
+    try {
+        scope.resolve(LoggerService).error(details, error);
+        return;
+    }
+    catch {
+        // fallback below
+    }
+    try {
+        app.getLogger().error(details, error);
+        return;
+    }
+    catch {
+        // final fallback
+    }
+    console.error("[imperium] rpc_streaming_error", details, error);
+}
+function getPayloadValue(payload, key) {
+    if (!key) {
+        return payload;
+    }
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    return payload[key];
+}
+function buildRpcArgs(payload, context, handler) {
+    const metas = Reflect.getMetadata(RPC_PARAMS_KEY, handler) ?? [];
+    if (!metas.length) {
+        return [payload];
+    }
+    const args = [];
+    for (const meta of metas) {
+        switch (meta.source) {
+            case "data":
+                args[meta.index] = getPayloadValue(payload, meta.key);
+                break;
+            case "context":
+                args[meta.index] = context;
+                break;
+            case "headers":
+                args[meta.index] = context.requestHeader;
+                break;
+            case "header":
+                args[meta.index] = meta.key ? context.requestHeader.get(meta.key) : undefined;
+                break;
+            case "abort_signal":
+                args[meta.index] = context.signal;
+                break;
+        }
+    }
+    return args;
+}
+function resolveEnhancer(scope, enhancer) {
+    if (typeof enhancer === "function") {
+        return scope.resolve(enhancer);
+    }
+    return enhancer;
+}
+function canHandleException(error, filter) {
+    const exceptions = Reflect.getMetadata(CATCH_EXCEPTIONS_KEY, filter.constructor);
+    if (!exceptions || exceptions.length === 0) {
+        return true;
+    }
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return exceptions.some((ExceptionType) => error instanceof ExceptionType);
+}
+async function runRpcFilters(error, filters, ctx) {
+    let currentError = error;
+    for (const filter of filters) {
+        if (!canHandleException(currentError, filter)) {
+            continue;
+        }
+        try {
+            const result = await filter.catch(currentError, ctx);
+            if (result !== undefined) {
+                return {
+                    handled: true,
+                    error: currentError,
+                    result,
+                };
+            }
+        }
+        catch (nextError) {
+            currentError = nextError;
+        }
+    }
+    return {
+        handled: false,
+        error: currentError,
+    };
+}
+export function createStreamingRpcHandler(app, controller, methodName) {
+    return async function* (req, context) {
+        const scope = app.createRequestScope(controller);
+        const handler = controller.prototype[methodName];
+        const ctx = {
+            type: "rpc",
+            method: methodName,
+            headers: context.requestHeader,
+            rpc: {
+                data: req,
+                context,
+            },
+            controller,
+            handler,
+            getType: () => "rpc",
+            getClass: () => controller,
+            getHandler: () => handler,
+            switchToHttp: () => ({
+                getRequest: () => undefined,
+                getResponse: () => undefined,
+            }),
+            switchToRpc: () => ({
+                getData: () => req,
+                getContext: () => context,
+            }),
+            switchToWs: () => ({
+                getSocket: () => undefined,
+                getRequest: () => undefined,
+                getMessage: () => undefined,
+            }),
+        };
+        try {
+            await app.runInRequestScope(scope, async () => {
+                // Resolve instance inside request scope
+            });
+            // We need to run guards/pipes inside the scope, then yield outside of runInRequestScope
+            // because async generators cannot be fully consumed inside a single runInRequestScope call.
+            // Instead, we set up the scope context and run guards/pipes, then yield from the generator.
+            const instance = scope.resolve(controller);
+            const guards = collectGuardsForRpc(controller, methodName, app.getGlobalGuards()).map((guardLike) => resolveEnhancer(scope, guardLike));
+            for (const guard of guards) {
+                const ok = await guard.canActivate(ctx);
+                if (!ok) {
+                    throw new ForbiddenException();
+                }
+            }
+            let payload = req;
+            const pipes = collectPipesForRpc(controller, methodName, app.getGlobalPipes()).map((pipeLike) => resolveEnhancer(scope, pipeLike));
+            for (const pipe of pipes) {
+                payload = await pipe.transform(payload, ctx);
+            }
+            const args = buildRpcArgs(payload, context, handler);
+            const generator = instance[methodName].apply(instance, args);
+            yield* generator;
+        }
+        catch (error) {
+            logRpcError(app, scope, {
+                type: "rpc_streaming_error",
+                controller: controller.name,
+                handler: methodName,
+                procedure: context.method.name,
+            }, error);
+            const filters = collectFiltersForRpc(controller, methodName, app.getGlobalFilters()).map((filterLike) => resolveEnhancer(scope, filterLike));
+            const filtered = await runRpcFilters(error, filters, ctx);
+            if (filtered.handled) {
+                return;
+            }
+            throw toConnectError(filtered.error, {
+                exposeInternalErrors: app.shouldExposeInternalErrors(),
+            });
+        }
+        finally {
+            try {
+                await app.disposeRequestScope(scope);
+            }
+            catch (disposeError) {
+                logRpcError(app, scope, {
+                    type: "rpc_streaming_scope_dispose_error",
+                    controller: controller.name,
+                    handler: methodName,
+                    procedure: context.method.name,
+                }, disposeError);
+            }
+        }
+    };
+}

package/dist/types.d.ts

@@ -3,7 +3,7 @@ import type { ISettingsParam } from "tslog";
 import type { DependencyContainer, RegistrationOptions, InjectionToken as TsyringeInjectionToken } from "tsyringe";
 import type { ZodType } from "zod";
 export type Constructor<T = unknown> = new (...args: any[]) => T;
-export type ContextType = "http" | "rpc";
+export type ContextType = "http" | "rpc" | "ws";
 export type LoggerOptions = ISettingsParam<Record<string, unknown>>;
 export type InjectionToken<T = unknown> = TsyringeInjectionToken<T>;
 export type MetadataKey = string | symbol;
@@ -69,6 +69,11 @@ export interface RpcArgumentsHost {
     getData<T = unknown>(): T | undefined;
     getContext<T = unknown>(): T | undefined;
 }
+export interface WsArgumentsHost {
+    getSocket<T = unknown>(): T | undefined;
+    getRequest(): FastifyRequest | undefined;
+    getMessage<T = unknown>(): T | undefined;
+}
 export interface BaseContext {
     type: ContextType;
     method: string;
@@ -82,6 +87,11 @@ export interface BaseContext {
         data: unknown;
         context: unknown;
     };
+    ws?: {
+        socket: unknown;
+        request: FastifyRequest;
+        message?: unknown;
+    };
     controller: Constructor;
     handler: Function;
     getType(): ContextType;
@@ -89,6 +99,7 @@ export interface BaseContext {
     getHandler(): Function;
     switchToHttp(): HttpArgumentsHost;
     switchToRpc(): RpcArgumentsHost;
+    switchToWs(): WsArgumentsHost;
 }
 export interface Guard {
     canActivate(ctx: BaseContext): Promise<boolean> | boolean;

package/dist/ws/adapter.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyRequest } from "fastify";
+import type { WebSocket } from "@fastify/websocket";
+import "reflect-metadata";
+import type { AppContainer } from "../core/container";
+import type { Constructor } from "../types";
+export declare function handleWsConnection(app: AppContainer, gateway: Constructor, socket: WebSocket, request: FastifyRequest): void;

package/dist/ws/adapter.js

@@ -0,0 +1,167 @@
+import "reflect-metadata";
+import { GUARDS_KEY } from "../decorators/guards.decorators";
+import { WS_HANDLERS_KEY, WS_PARAMS_KEY } from "../decorators/ws.decorators";
+import { Reflector } from "../core/reflector";
+import { LoggerService } from "../services";
+const reflector = new Reflector();
+function collectGuardsForWs(gateway, app) {
+    const classGuards = (reflector.get(GUARDS_KEY, gateway) ?? []);
+    return [...app.getGlobalGuards(), ...classGuards];
+}
+function resolveEnhancer(scope, enhancer) {
+    if (typeof enhancer === "function") {
+        return scope.resolve(enhancer);
+    }
+    return enhancer;
+}
+function buildWsArgs(socket, request, message, handler) {
+    const metas = Reflect.getMetadata(WS_PARAMS_KEY, handler) ?? [];
+    if (!metas.length) {
+        return [socket, message, request];
+    }
+    const args = [];
+    for (const meta of metas) {
+        switch (meta.source) {
+            case "connection":
+                args[meta.index] = socket;
+                break;
+            case "message":
+                args[meta.index] = message;
+                break;
+            case "request":
+                args[meta.index] = request;
+                break;
+        }
+    }
+    return args;
+}
+function buildWsContext(gateway, methodName, handler, socket, request, message) {
+    return {
+        type: "ws",
+        method: methodName,
+        controller: gateway,
+        handler,
+        ws: {
+            socket,
+            request,
+            message,
+        },
+        getType: () => "ws",
+        getClass: () => gateway,
+        getHandler: () => handler,
+        switchToHttp: () => ({
+            getRequest: () => undefined,
+            getResponse: () => undefined,
+        }),
+        switchToRpc: () => ({
+            getData: () => undefined,
+            getContext: () => undefined,
+        }),
+        switchToWs: () => ({
+            getSocket: () => socket,
+            getRequest: () => request,
+            getMessage: () => message,
+        }),
+    };
+}
+function logWsError(app, scope, details, error) {
+    try {
+        scope.resolve(LoggerService).error(details, error);
+        return;
+    }
+    catch {
+        // fallback
+    }
+    try {
+        app.getLogger().error(details, error);
+        return;
+    }
+    catch {
+        // final fallback
+    }
+    console.error("[imperium] ws_error", details, error);
+}
+export function handleWsConnection(app, gateway, socket, request) {
+    const scope = app.createRequestScope(gateway);
+    const handlers = Reflect.getMetadata(WS_HANDLERS_KEY, gateway) ?? [];
+    const runAsync = async () => {
+        const instance = scope.resolve(gateway);
+        // Run guards at connection time
+        const guardLikes = collectGuardsForWs(gateway, app);
+        const guards = guardLikes.map((g) => resolveEnhancer(scope, g));
+        const ctx = buildWsContext(gateway, "onConnection", gateway, socket, request);
+        for (const guard of guards) {
+            const ok = await guard.canActivate(ctx);
+            if (!ok) {
+                socket.close(4403, "Forbidden");
+                await app.disposeRequestScope(scope);
+                return;
+            }
+        }
+        // Call onConnection lifecycle
+        if (typeof instance.onConnection === "function") {
+            await instance.onConnection(socket, request);
+        }
+        // Route messages to handlers
+        socket.on("message", (raw) => {
+            (async () => {
+                try {
+                    const msg = JSON.parse(raw.toString());
+                    const handler = handlers.find((h) => h.messageType === msg.type);
+                    if (!handler) {
+                        return;
+                    }
+                    const handlerFn = instance[handler.handlerName];
+                    const args = buildWsArgs(socket, request, msg.data, handlerFn);
+                    await handlerFn.apply(instance, args);
+                }
+                catch (error) {
+                    logWsError(app, scope, {
+                        type: "ws_message_error",
+                        gateway: gateway.name,
+                    }, error);
+                }
+            })();
+        });
+        // Cleanup on disconnect
+        socket.on("close", () => {
+            (async () => {
+                try {
+                    if (typeof instance.onDisconnect === "function") {
+                        await instance.onDisconnect(socket);
+                    }
+                }
+                catch (error) {
+                    logWsError(app, scope, {
+                        type: "ws_disconnect_error",
+                        gateway: gateway.name,
+                    }, error);
+                }
+                finally {
+                    try {
+                        await app.disposeRequestScope(scope);
+                    }
+                    catch (error) {
+                        logWsError(app, scope, {
+                            type: "ws_scope_dispose_error",
+                            gateway: gateway.name,
+                        }, error);
+                    }
+                }
+            })();
+        });
+    };
+    runAsync().catch((error) => {
+        logWsError(app, scope, {
+            type: "ws_connection_error",
+            gateway: gateway.name,
+        }, error);
+        try {
+            socket.close(4500, "Internal Server Error");
+        }
+        catch {
+            // socket may already be closed
+        }
+        app.disposeRequestScope(scope).catch(() => { });
+    });
+}

package/dist/ws/index.d.ts

@@ -0,0 +1,3 @@
+export { handleWsConnection } from "./adapter";
+export { registerWsGateways } from "./router-builder";
+export type { WsGatewayLifecycle, WsGatewayMeta, WsHandlerMeta, WsParamMeta, WsParamSource } from "./types";

package/dist/ws/index.js

@@ -0,0 +1,2 @@
+export { handleWsConnection } from "./adapter";
+export { registerWsGateways } from "./router-builder";

package/dist/ws/router-builder.d.ts

@@ -0,0 +1,4 @@
+import type { FastifyInstance } from "fastify";
+import "reflect-metadata";
+import type { AppContainer } from "../core/container";
+export declare function registerWsGateways(server: FastifyInstance, app: AppContainer): Promise<void>;

package/dist/ws/router-builder.js

@@ -0,0 +1,25 @@
+import "reflect-metadata";
+import { WS_GATEWAY_KEY } from "../decorators/ws.decorators";
+import { handleWsConnection } from "./adapter";
+export async function registerWsGateways(server, app) {
+    const gateways = app.getWsGateways();
+    if (gateways.length === 0) {
+        return;
+    }
+    // Dynamic import — @fastify/websocket is an optional peer dep
+    let fastifyWebsocket;
+    try {
+        fastifyWebsocket = await import("@fastify/websocket");
+    }
+    catch {
+        throw new Error("WebSocket gateways are registered but @fastify/websocket is not installed. " +
+            "Install it: pnpm add @fastify/websocket");
+    }
+    await server.register(fastifyWebsocket.default);
+    for (const gateway of gateways) {
+        const meta = Reflect.getMetadata(WS_GATEWAY_KEY, gateway);
+        server.get(meta.path, { websocket: true }, (socket, req) => {
+            handleWsConnection(app, gateway, socket, req);
+        });
+    }
+}

package/dist/ws/types.d.ts

@@ -0,0 +1,18 @@
+import type { FastifyRequest } from "fastify";
+import type { WebSocket } from "@fastify/websocket";
+export interface WsHandlerMeta {
+    messageType: string;
+    handlerName: string;
+}
+export interface WsGatewayMeta {
+    path: string;
+}
+export type WsParamSource = "connection" | "message" | "request";
+export interface WsParamMeta {
+    index: number;
+    source: WsParamSource;
+}
+export interface WsGatewayLifecycle {
+    onConnection?(socket: WebSocket, req: FastifyRequest): void | Promise<void>;
+    onDisconnect?(socket: WebSocket): void | Promise<void>;
+}

package/dist/ws/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smounters/imperium",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "NestJS-like modular DI container with unified HTTP + Connect RPC server for TypeScript",
   "keywords": [
     "di",
@@ -31,6 +31,10 @@
     "./validation": {
       "types": "./dist/validation/index.d.ts",
       "import": "./dist/validation/index.js"
+    },
+    "./ws": {
+      "types": "./dist/ws/index.d.ts",
+      "import": "./dist/ws/index.js"
     }
   },
   "files": [
@@ -71,23 +75,30 @@
     "@connectrpc/connect": "^2.1.1",
     "@connectrpc/connect-fastify": "^2.1.1",
     "@fastify/cors": "^11.2.0",
+    "@fastify/websocket": "^11.0.0",
     "fastify": "^5.7.4",
-    "tsyringe": "^4.10.0",
     "reflect-metadata": "^0.2.2",
     "tslog": "^4.10.2",
+    "tsyringe": "^4.10.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },
+  "peerDependenciesMeta": {
+    "@fastify/websocket": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@types/node": "^24.5.2",
-    "@typescript-eslint/eslint-plugin": "^8.56.0",
-    "@typescript-eslint/parser": "^8.56.0",
     "@connectrpc/connect": "^2.1.1",
     "@connectrpc/connect-fastify": "^2.1.1",
     "@fastify/cors": "^11.2.0",
-    "eslint": "^10.0.0",
+    "@fastify/websocket": "^11.2.0",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
-    "fastify": "^5.7.4",
+    "fastify": "^5.8.4",
     "prettier": "^3.8.1",
     "reflect-metadata": "^0.2.2",
     "tslog": "^4.10.2",
@@ -95,6 +106,5 @@
     "typescript": "^5.9.3",
     "vitepress": "^1.6.4",
     "zod": "^4.3.6"
-  },
-  "dependencies": {}
+  }
 }