@riaskov/nevo-messaging 1.0.1 → 1.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Andrei Riaskóv
+Copyright (c) 2026 Andrei Riaskóv <code@riaskov.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,15 +4,20 @@ A powerful microservices messaging framework for NestJS 11+ with Kafka 4+ transp
 
 ## Features
 
-- 🚀 **Type-safe messaging** - Full TypeScript support with auto-completion
-- 🔄 **Dual communication patterns** - Both request-response (query) and fire-and-forget (emit)
-- 🎯 **Signal-based routing** - Declarative method mapping with `@Signal` decorator
-- 📡 **Kafka transport** - Production-ready Apache Kafka integration
-- 🔧 **Auto-configuration** - Automatic topic creation and client setup
-- 🛡️ **Error handling** - Comprehensive error propagation and timeout management
-- 📊 **BigInt support** - Native handling of large integers across services
-- 🪝 **Lifecycle hooks** - Before/after message processing hooks
-- 🔍 **Debug mode** - Built-in logging for development and troubleshooting
+- 🚀 **Type-safe messaging** - Full TypeScript support with auto-completion
+- 🔄 **Dual communication patterns** - Both request-response (query) and fire-and-forget (emit)
+- 📡 **Subscriptions** - Publish/subscribe updates without direct requests
+- 📢 **Broadcast** - System-wide messages for all connected consumers
+- 🎯 **Signal-based routing** - Declarative method mapping with `@Signal` decorator
+- 📡 **Kafka transport** - Production-ready Apache Kafka integration
+- 🧭 **Service discovery** - Heartbeat-based registry topic
+- 🔐 **Access control** - Topic + method + service-level ACLs
+- 🔌 **Multiple transports** - Kafka, NATS, HTTP (SSE), Socket.IO
+- 🔧 **Auto-configuration** - Automatic topic creation and client setup
+- 🛡️ **Error handling** - Comprehensive error propagation and timeout management
+- 📊 **BigInt support** - Native handling of large integers across services
+- 🪝 **Lifecycle hooks** - Before/after message processing hooks
+- 🔍 **Debug mode** - Built-in logging for development and troubleshooting
 
 ## Installation
 
@@ -23,7 +28,7 @@ npm install @riaskov/nevo-messaging
 ### Peer Dependencies
 
 ```bash
-npm install @nestjs/common @nestjs/core @nestjs/microservices @nestjs/config @nestjs/platform-fastify kafkajs rxjs reflect-metadata
+npm install @nestjs/common @nestjs/core @nestjs/microservices @nestjs/config @nestjs/platform-fastify kafkajs nats socket.io socket.io-client rxjs reflect-metadata
 ```
 
 ## Quick Start
@@ -137,12 +142,44 @@ Use for operations that need a response:
 const user = await this.query("user", "user.getById", { id: 123n })
 ```
 
-#### Emit Pattern (Fire-and-Forget)
-Use for events and notifications:
-
-```typescript
-await this.emit("notifications", "user.created", { userId: 123n, email: "user@example.com" })
-```
+#### Emit Pattern (Fire-and-Forget)
+Use for events and notifications:
+
+```typescript
+await this.emit("notifications", "user.created", { userId: 123n, email: "user@example.com" })
+```
+
+#### Subscription Pattern (Publish/Subscribe)
+Use when you want to receive updates without requesting:
+
+```typescript
+const sub = await this.subscribe("user", "user.updated", { ack: true }, async (msg, ctx) => {
+  await ctx.ack()
+})
+
+await sub.unsubscribe()
+```
+
+Publish updates:
+
+```typescript
+await this.publish("user", "user.updated", { userId: 123n })
+```
+
+#### Broadcast Pattern (System-Wide)
+Send to everyone connected to the broker:
+
+```typescript
+await this.broadcast("system.status", { ok: true })
+```
+
+Receive broadcast:
+
+```typescript
+await this.subscribe("__broadcast", "system.status", {}, (msg) => {
+  console.log("System status:", msg)
+})
+```
 
 ## Advanced Usage
 
@@ -258,7 +295,7 @@ export class UserController {
 }
 ```
 
-### Error Handling
+### Error Handling
 
 The framework provides comprehensive error handling:
 
@@ -279,10 +316,69 @@ export class UserService extends KafkaClientBase {
     
     return user
   }
-}
-```
-
-## Configuration
+}
+```
+
+### Method Suggestions (Did You Mean)
+
+If you call a method that doesn't exist, the framework returns a helpful error:
+
+```
+Invalid method name 'user.getByI', did you mean 'user.getById'?
+```
+
+This works for all transports.
+
+### Exponential Backoff (Client-Side)
+
+Clients apply a backoff for **in-flight requests** to avoid sending a duplicate query while the previous one is still being processed.
+
+```typescript
+createNevoKafkaClient(["USER"], {
+  clientIdPrefix: "frontend",
+  backoff: {
+    enabled: true,
+    baseMs: 100,
+    maxMs: 2000,
+    maxAttempts: 0, // 0 = wait until slot is free
+    jitter: true
+  }
+})
+```
+
+This prevents repeated sending of the same request while the service is busy (e.g., stopped on a breakpoint).
+
+### Access Control (ACL)
+
+Restrict who can read messages by topic + method + service:
+
+```typescript
+@KafkaSignalRouter([UserService], {
+  accessControl: {
+    rules: [
+      { topic: "user-events", method: "*", allow: ["frontend", "coordinator"] },
+      { topic: "user-events", method: "user.delete", deny: ["frontend"] }
+    ],
+    logDenied: true
+  }
+})
+export class UserController {}
+```
+
+By default, all services are allowed.
+
+### Service Discovery (Registry Topic)
+
+Each client sends heartbeats to `__nevo.discovery`. You can read the registry:
+
+```typescript
+const services = this.getDiscoveredServices()
+const isUserAvailable = this.isServiceAvailable("user")
+```
+
+Discovery is enabled by default for Kafka/NATS. HTTP and Socket.IO discovery are currently disabled.
+
+## Configuration
 
 ### Environment Variables
 
@@ -296,35 +392,102 @@ NODE_ENV=production
 ### Kafka Client Options
 
 ```typescript
-createNevoKafkaClient(["USER", "INVENTORY", "NOTIFICATIONS"], {
-  clientIdPrefix: "order-service",
-  groupIdPrefix: "order-consumer",
-  sessionTimeout: 30000,
-  allowAutoTopicCreation: true,
-  retryAttempts: 5,
-  brokerRetryTimeout: 2000,
-  timeoutMs: 25000,
-  debug: false
-})
-```
+createNevoKafkaClient(["USER", "INVENTORY", "NOTIFICATIONS"], {
+  clientIdPrefix: "order-service",
+  groupIdPrefix: "order-consumer",
+  sessionTimeout: 30000,
+  allowAutoTopicCreation: true,
+  retryAttempts: 5,
+  brokerRetryTimeout: 2000,
+  timeoutMs: 25000,
+  debug: false,
+  discovery: {
+    enabled: true,
+    heartbeatIntervalMs: 5000,
+    ttlMs: 15000
+  }
+})
+```
 
 ### Microservice Startup Options
 
 ```typescript
-createKafkaMicroservice({
-  microserviceName: "user",
-  module: AppModule,
-  port: 8086,
-  host: "0.0.0.0",
-  debug: true,
-  onInit: async (app) => {
-    // Custom initialization logic
-    await app.get(DatabaseService).runMigrations()
-  }
-})
-```
-
-## BigInt Support
+createKafkaMicroservice({
+  microserviceName: "user",
+  module: AppModule,
+  port: 8086,
+  host: "0.0.0.0",
+  debug: true,
+  onInit: async (app) => {
+    // Custom initialization logic
+    await app.get(DatabaseService).runMigrations()
+  }
+})
+```
+
+## Transports
+
+### Kafka (default)
+Use `createKafkaMicroservice` + `KafkaSignalRouter` as before.
+
+### NATS
+Client factory:
+
+```typescript
+createNevoNatsClient(["USER", "COORDINATOR"], {
+  clientIdPrefix: "user",
+  servers: ["nats://127.0.0.1:4222"]
+})
+```
+
+Controller decorator:
+
+```typescript
+@NatsSignalRouter([UserService])
+export class UserController {}
+```
+
+### HTTP (SSE)
+HTTP uses plain POST for `query/emit` and SSE for `subscribe`.
+
+```typescript
+@HttpSignalRouter([UserService])
+export class UserController {}
+```
+
+Include transport controller to enable SSE + publish endpoints:
+
+```typescript
+controllers: [UserController, HttpTransportController]
+```
+
+Client:
+
+```typescript
+createNevoHttpClient(
+  { coordinator: "http://127.0.0.1:8091" },
+  { clientIdPrefix: "user" }
+)
+```
+
+### Socket.IO
+Socket.IO server is started inside the router decorator:
+
+```typescript
+@SocketSignalRouter([UserService], { serviceName: "user", port: 8093 })
+export class UserController {}
+```
+
+Client:
+
+```typescript
+createNevoSocketClient(
+  { coordinator: "http://127.0.0.1:8094" },
+  { clientIdPrefix: "user" }
+)
+```
+
+## BigInt Support
 
 The framework automatically handles BigInt serialization across service boundaries:
 
@@ -723,19 +886,27 @@ Class decorator for signal routing setup.
 
 Base class for services that need to communicate with other microservices.
 
-**Methods:**
-- `query<T>(serviceName, method, params): Promise<T>` - Request-response communication
-- `emit(serviceName, method, params): Promise<void>` - Fire-and-forget communication
-- `getAvailableServices(): string[]` - List registered services
+**Methods:**
+- `query<T>(serviceName, method, params): Promise<T>` - Request-response communication
+- `emit(serviceName, method, params): Promise<void>` - Fire-and-forget communication
+- `publish(serviceName, method, params): Promise<void>` - Publish to subscriptions
+- `subscribe(serviceName, method, options, handler): Promise<Subscription>` - Subscribe to updates
+- `broadcast(method, params): Promise<void>` - System-wide broadcast
+- `getAvailableServices(): string[]` - List registered services
+- `getDiscoveredServices(): DiscoveryEntry[]` - Service registry snapshot
+- `isServiceAvailable(serviceName): boolean` - Availability check
 
 #### `NevoKafkaClient`
 
 Universal Kafka client for multi-service communication.
 
-**Methods:**
-- `query<T>(serviceName, method, params): Promise<T>` - Send query to service
-- `emit(serviceName, method, params): Promise<void>` - Emit event to service
-- `getAvailableServices(): string[]` - Get list of available services
+**Methods:**
+- `query<T>(serviceName, method, params): Promise<T>` - Send query to service
+- `emit(serviceName, method, params): Promise<void>` - Emit event to service
+- `publish(serviceName, method, params): Promise<void>` - Publish to subscriptions
+- `subscribe(serviceName, method, options, handler): Promise<Subscription>` - Subscribe to updates
+- `broadcast(method, params): Promise<void>` - System-wide broadcast
+- `getAvailableServices(): string[]` - Get list of available services
 
 ### Functions
 
@@ -747,7 +918,21 @@ Factory function for creating Kafka client providers.
 
 Bootstrap function for starting NestJS microservices with Kafka transport.
 
-## Troubleshooting
+## Examples
+
+### Kafka
+- `examples/user` - standard Kafka microservice
+
+### NATS
+- `examples/nats-user` - NATS request/response + publish/subscribe + broadcast
+
+### HTTP (SSE)
+- `examples/http-user` - HTTP query/emit + SSE subscribe + broadcast + discovery
+
+### Socket.IO
+- `examples/socket-user` - Socket.IO transport with subscribe/broadcast
+
+## Troubleshooting
 
 ### Common Issues
 
@@ -828,4 +1013,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - Examples: Check the `examples/` directory for complete working examples
 
 ## Aux
-There are many anys in core code - the simple temporary solution for changeable Nest.js microservices API.
+There are many anys in core code - the simple temporary solution for changeable Nest.js microservices API.

package/dist/common/access-control.d.ts

@@ -0,0 +1,15 @@
+import { AccessControlConfig, MessageMeta } from "./types";
+import { ErrorCode } from "./error-code";
+export declare function extractCallerService(meta?: MessageMeta): string | undefined;
+export declare function isAccessAllowed(config: AccessControlConfig | undefined, topic: string, method: string, callerService: string | undefined): boolean;
+export declare function logAccessDenied(config: AccessControlConfig | undefined, details: Record<string, unknown>): void;
+export declare function createAccessDeniedError(method: string, serviceName: string, callerService?: string): {
+    code: ErrorCode;
+    message: string;
+    details: {
+        method: string;
+        serviceName: string;
+        callerService: string | undefined;
+    };
+    service: string;
+};

package/dist/common/access-control.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCallerService = extractCallerService;
+exports.isAccessAllowed = isAccessAllowed;
+exports.logAccessDenied = logAccessDenied;
+exports.createAccessDeniedError = createAccessDeniedError;
+const error_code_1 = require("./error-code");
+function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+        return null;
+    }
+    try {
+        const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const padded = payload.padEnd(payload.length + ((4 - (payload.length % 4)) % 4), "=");
+        const json = Buffer.from(padded, "base64").toString("utf8");
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+function extractCallerService(meta) {
+    if (meta?.service) {
+        return meta.service;
+    }
+    const token = meta?.auth?.token;
+    if (!token) {
+        return undefined;
+    }
+    const payload = decodeJwtPayload(token);
+    if (!payload) {
+        return undefined;
+    }
+    const serviceName = (payload["serviceName"] || payload["service"] || payload["svc"] || payload["sub"]);
+    return serviceName;
+}
+function matchPattern(pattern, value) {
+    if (!pattern || pattern === "*") {
+        return true;
+    }
+    return pattern === value;
+}
+function listHasValue(list, value) {
+    if (!list || list.length === 0) {
+        return false;
+    }
+    if (list.includes("*")) {
+        return true;
+    }
+    if (!value) {
+        return false;
+    }
+    return list.includes(value);
+}
+function isAccessAllowed(config, topic, method, callerService) {
+    if (!config) {
+        return true;
+    }
+    const allowAllByDefault = config.allowAllByDefault !== false;
+    const rules = config.rules || [];
+    let matched = false;
+    for (const rule of rules) {
+        if (!matchPattern(rule.topic, topic) || !matchPattern(rule.method, method)) {
+            continue;
+        }
+        matched = true;
+        if (listHasValue(rule.deny, callerService)) {
+            return false;
+        }
+        if (rule.allow && rule.allow.length > 0) {
+            return listHasValue(rule.allow, callerService);
+        }
+    }
+    return matched ? allowAllByDefault : allowAllByDefault;
+}
+function logAccessDenied(config, details) {
+    if (config?.logDenied === false) {
+        return;
+    }
+    console.warn("[NevoMessaging][ACL] Access denied:", details);
+}
+function createAccessDeniedError(method, serviceName, callerService) {
+    return {
+        code: error_code_1.ErrorCode.UNAUTHORIZED,
+        message: "Access denied",
+        details: {
+            method,
+            serviceName,
+            callerService
+        },
+        service: serviceName
+    };
+}

package/dist/common/base.client.d.ts

@@ -1,12 +1,17 @@
-import { MessagePayload, MicroserviceConfig, TransportClientOptions } from "./types";
+import { MessagePayload, MicroserviceConfig, TransportClientOptions, MessageType, Subscription, SubscriptionOptions, SubscriptionContext } from "./types";
 export declare abstract class BaseMessagingClient {
     protected readonly options: TransportClientOptions;
     protected readonly microservices: Map<string, string>;
+    protected readonly serviceName?: string;
+    protected readonly authToken?: string;
     protected constructor(options?: TransportClientOptions);
     protected registerMicroservices(configs: MicroserviceConfig[]): void;
     protected query<T = any>(serviceName: string, method: string, params: any): Promise<T>;
     protected emit(serviceName: string, method: string, params: any): Promise<void>;
-    protected createMessagePayload(method: string, params: any): MessagePayload;
+    protected createMessagePayload(method: string, params: any, type?: MessageType): MessagePayload;
     protected abstract _queryMicroservice<T>(clientName: string, method: string, params: any): Promise<T>;
     protected abstract _emitToMicroservice(clientName: string, method: string, params: any): Promise<void>;
+    protected abstract _publishToMicroservice(clientName: string, method: string, params: any): Promise<void>;
+    protected abstract _broadcast(method: string, params: any): Promise<void>;
+    protected abstract _subscribeToMicroservice<T>(clientName: string, method: string, options: SubscriptionOptions | undefined, handler: (data: T, context: SubscriptionContext) => Promise<void> | void): Promise<Subscription>;
 }

package/dist/common/base.client.js

@@ -12,6 +12,8 @@ class BaseMessagingClient {
             debug: false,
             ...options
         };
+        this.serviceName = this.options.serviceName || this.options.clientId;
+        this.authToken = this.options.authToken;
     }
     registerMicroservices(configs) {
         for (const config of configs) {
@@ -38,9 +40,21 @@ class BaseMessagingClient {
         }
         return this._emitToMicroservice(clientName, method, params);
     }
-    createMessagePayload(method, params) {
+    createMessagePayload(method, params, type = "emit") {
         const uuid = (0, node_crypto_1.randomUUID)();
-        const request = { uuid, method, params };
+        const request = {
+            uuid,
+            method,
+            params,
+            meta: {
+                type,
+                service: this.serviceName,
+                ts: Date.now(),
+                auth: {
+                    token: this.authToken
+                }
+            }
+        };
         return {
             key: uuid,
             value: JSON.stringify(request)

package/dist/common/base.controller.d.ts

@@ -1,4 +1,4 @@
-import { AfterHook, BeforeHook, ServiceMethodHandler, ServiceMethodMapping, SystemAfterHook, SystemBeforeHook, MessageResponse } from "./types";
+import { AfterHook, BeforeHook, ServiceMethodHandler, ServiceMethodMapping, SystemAfterHook, SystemBeforeHook, MessageResponse, AccessControlConfig, MessageMeta } from "./types";
 export declare abstract class BaseMessageController {
     protected readonly methodRegistry: ServiceMethodMapping;
     serviceInstances: any[];
@@ -8,14 +8,18 @@ export declare abstract class BaseMessageController {
     protected readonly systemBeforeHook: SystemBeforeHook;
     protected readonly systemAfterHook: SystemAfterHook;
     protected readonly debug: boolean;
+    protected readonly accessControl?: AccessControlConfig;
     protected constructor(serviceName: string, serviceInstances: any[], methodHandlers: ServiceMethodMapping, options?: {
         onBefore?: BeforeHook;
         onAfter?: AfterHook;
         debug?: boolean;
+        accessControl?: AccessControlConfig;
     });
     protected registerMethodHandlers(handlers: ServiceMethodMapping): void;
     protected findServiceInstance(methodName: string): any;
     protected executeHandler(handler: ServiceMethodHandler, params: unknown): Promise<unknown>;
+    private suggestClosestMethod;
+    private levenshteinDistance;
     protected formatResult(result: unknown): Promise<unknown>;
     protected createErrorResponse(uuid: string, method: string, error: any): MessageResponse;
     processMessage(data: any): Promise<MessageResponse>;
@@ -23,6 +27,7 @@ export declare abstract class BaseMessageController {
         method: string;
         uuid: string;
         params: any;
+        meta?: MessageMeta;
     };
     abstract handleMessage(data: any): Promise<MessageResponse>;
 }

package/dist/common/base.controller.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseMessageController = void 0;
 const _1 = require("./");
+const access_control_1 = require("./access-control");
 class BaseMessageController {
     constructor(serviceName, serviceInstances, methodHandlers, options) {
         this.methodRegistry = {};
@@ -11,6 +12,7 @@ class BaseMessageController {
         this.beforeHook = options?.onBefore;
         this.afterHook = options?.onAfter;
         this.debug = options?.debug || false;
+        this.accessControl = options?.accessControl;
         this.systemBeforeHook = (context) => {
             if (this.debug) {
                 console.log(`[${this.constructor.name}] Received:`, {
@@ -67,6 +69,50 @@ class BaseMessageController {
             throw error;
         }
     }
+    suggestClosestMethod(method) {
+        const candidates = Object.keys(this.methodRegistry || {});
+        if (!candidates.length) {
+            return null;
+        }
+        const normalized = method.toLowerCase();
+        let best = null;
+        for (const candidate of candidates) {
+            const score = this.levenshteinDistance(normalized, candidate.toLowerCase());
+            if (!best || score < best.score) {
+                best = { name: candidate, score };
+            }
+        }
+        if (!best) {
+            return null;
+        }
+        const threshold = Math.max(2, Math.floor(method.length * 0.4));
+        return best.score <= threshold ? best.name : null;
+    }
+    levenshteinDistance(a, b) {
+        if (a === b) {
+            return 0;
+        }
+        if (!a.length) {
+            return b.length;
+        }
+        if (!b.length) {
+            return a.length;
+        }
+        const matrix = Array.from({ length: a.length + 1 }, () => []);
+        for (let i = 0; i <= a.length; i++) {
+            matrix[i][0] = i;
+        }
+        for (let j = 0; j <= b.length; j++) {
+            matrix[0][j] = j;
+        }
+        for (let i = 1; i <= a.length; i++) {
+            for (let j = 1; j <= b.length; j++) {
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+            }
+        }
+        return matrix[a.length][b.length];
+    }
     async formatResult(result) {
         if (result instanceof Promise) {
             result = await result;
@@ -100,12 +146,13 @@ class BaseMessageController {
         };
     }
     async processMessage(data) {
-        const { method, uuid, params } = this.extractMessageData(data);
+        const { method, uuid, params, meta } = this.extractMessageData(data);
         const baseContext = {
             method,
             serviceName: this.serviceName,
             uuid,
-            rawData: data
+            rawData: data,
+            meta
         };
         const requestContext = {
             ...baseContext,
@@ -120,10 +167,26 @@ class BaseMessageController {
                     processedParams = hookResult;
                 }
             }
+            const callerService = (0, access_control_1.extractCallerService)(meta);
+            const topic = this.serviceName;
+            if (!(0, access_control_1.isAccessAllowed)(this.accessControl, topic, method, callerService)) {
+                (0, access_control_1.logAccessDenied)(this.accessControl, { topic, method, serviceName: this.serviceName, callerService });
+                return {
+                    uuid,
+                    method,
+                    params: {
+                        result: "error",
+                        error: (0, access_control_1.createAccessDeniedError)(method, this.serviceName, callerService)
+                    },
+                    meta
+                };
+            }
             const handler = this.methodRegistry[method];
             if (!handler) {
+                const suggestion = this.suggestClosestMethod(method);
+                const message = suggestion ? `Invalid method name '${method}', did you mean '${suggestion}'?` : `Method handler not found: ${method}`;
                 throw new _1.MessagingError(_1.ErrorCode.UNKNOWN, {
-                    message: `Method handler not found: ${method}`
+                    message
                 });
             }
             const result = await this.executeHandler(handler, processedParams);
@@ -131,7 +194,8 @@ class BaseMessageController {
             let response = {
                 uuid,
                 method,
-                params: { result: formattedResult }
+                params: { result: formattedResult },
+                meta
             };
             const responseContext = {
                 ...baseContext,