@riaskov/nevo-messaging 1.0.1 → 1.1.2

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

@@ -1,13 +1,18 @@
 # Nevo Messaging
 
-A powerful microservices messaging framework for NestJS 11+ with Kafka 4+ transport, designed for building scalable distributed systems with type-safe inter-service communication.
+A powerful microservices messaging framework for NestJS 11+ with multi-transport support (NATS, Kafka, Socket.IO, HTTP/SSE), designed for building scalable distributed systems with type-safe inter-service communication.
 
 ## Features
 
 - 🚀 **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** - NATS, Kafka, Socket.IO, HTTP (SSE)
 - 🔧 **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
@@ -23,23 +28,23 @@ 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
 
-### 1. Basic Service Setup
+### 1. Basic Service Setup (NATS)
 
 Create a simple microservice that responds to messages:
 
 ```typescript
 // user.service.ts
 import { Injectable, Inject } from "@nestjs/common"
-import { KafkaClientBase, NevoKafkaClient } from "@riaskov/nevo-messaging"
+import { NatsClientBase, NevoNatsClient } from "@riaskov/nevo-messaging"
 
 @Injectable()
-export class UserService extends KafkaClientBase {
-  constructor(@Inject("NEVO_KAFKA_CLIENT") nevoClient: NevoKafkaClient) {
+export class UserService extends NatsClientBase {
+  constructor(@Inject("NEVO_NATS_CLIENT") nevoClient: NevoNatsClient) {
     super(nevoClient)
   }
 
@@ -61,11 +66,11 @@ Map service methods to external signals using the `@Signal` decorator:
 ```typescript
 // user.controller.ts
 import { Controller, Inject } from "@nestjs/common"
-import { KafkaSignalRouter, Signal } from "@riaskov/nevo-messaging"
+import { NatsSignalRouter, Signal } from "@riaskov/nevo-messaging"
 import { UserService } from "./user.service"
 
 @Controller()
-@KafkaSignalRouter([UserService])
+@NatsSignalRouter([UserService])
 export class UserController {
   constructor(@Inject(UserService) private readonly userService: UserService) {}
 
@@ -79,13 +84,13 @@ export class UserController {
 
 ### 3. Module Configuration
 
-Configure the module with Kafka client:
+Configure the module with the NATS client:
 
 ```typescript
 // user.module.ts
 import { Module } from "@nestjs/common"
 import { ConfigModule } from "@nestjs/config"
-import { createNevoKafkaClient } from "@riaskov/nevo-messaging"
+import { createNevoNatsClient } from "@riaskov/nevo-messaging"
 import { UserController } from "./user.controller"
 import { UserService } from "./user.service"
 
@@ -94,8 +99,9 @@ import { UserService } from "./user.service"
   controllers: [UserController],
   providers: [
     UserService,
-    createNevoKafkaClient(["COORDINATOR"], {
-      clientIdPrefix: "user"
+    createNevoNatsClient(["COORDINATOR"], {
+      clientIdPrefix: "user",
+      servers: ["nats://127.0.0.1:4222"]
     })
   ]
 })
@@ -104,20 +110,20 @@ export class UserModule {}
 
 ### 4. Application Bootstrap
 
-Start your microservice:
+Start your service:
 
 ```typescript
 // main.ts
-import { createKafkaMicroservice } from "@riaskov/nevo-messaging"
+import { NestFactory } from "@nestjs/core"
 import { AppModule } from "./app.module"
 
-createKafkaMicroservice({
-  microserviceName: "user",
-  module: AppModule,
-  port: 8086
-}).then()
-```
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  await app.listen(8086)
+}
 
+bootstrap()
+```
 ## Core Concepts
 
 ### Signal Routing
@@ -144,6 +150,38 @@ Use for events and notifications:
 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
 
 ### Parameter Transformation
@@ -282,6 +320,65 @@ export class UserService extends KafkaClientBase {
 }
 ```
 
+### 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 available when enabled (HTTP requires `discoveryUrl`).
+
 ## Configuration
 
 ### Environment Variables
@@ -304,7 +401,12 @@ createNevoKafkaClient(["USER", "INVENTORY", "NOTIFICATIONS"], {
   retryAttempts: 5,
   brokerRetryTimeout: 2000,
   timeoutMs: 25000,
-  debug: false
+  debug: false,
+  discovery: {
+    enabled: true,
+    heartbeatIntervalMs: 5000,
+    ttlMs: 15000
+  }
 })
 ```
 
@@ -324,6 +426,74 @@ createKafkaMicroservice({
 })
 ```
 
+## Transports
+
+| Transport | Patterns | Discovery | Infra | Notes |
+| --- | --- | --- | --- | --- |
+| NATS | query/emit/publish/subscribe/broadcast | on by default | NATS server | Lowest latency, simple ops |
+| Kafka | query/emit/publish/subscribe/broadcast | on by default | Kafka broker | Durable log, topic setup |
+| Socket.IO | query/emit/publish/subscribe/broadcast | optional | Socket.IO server | WebSocket-friendly apps |
+| HTTP (SSE) | query/emit + SSE subscribe/broadcast | optional | HTTP server | Simple HTTP/SSE integration |
+
+### NATS (priority)
+Client factory:
+
+```typescript
+createNevoNatsClient(["USER", "COORDINATOR"], {
+  clientIdPrefix: "user",
+  servers: ["nats://127.0.0.1:4222"]
+})
+```
+
+Controller decorator:
+
+```typescript
+@NatsSignalRouter([UserService])
+export class UserController {}
+```
+
+### Kafka
+Use `createKafkaMicroservice` + `KafkaSignalRouter` as before.
+
+### 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" }
+)
+```
+
+### 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" }
+)
+```
 ## BigInt Support
 
 The framework automatically handles BigInt serialization across service boundaries:
@@ -697,56 +867,21 @@ createNevoKafkaClient(["HIGH_VOLUME_SERVICE"], {
 
 ## API Reference
 
-### Decorators
-
-#### `@Signal(signalName, methodName?, paramTransformer?, resultTransformer?)`
-
-Maps external signals to service methods.
-
-**Parameters:**
-- `signalName` (string): External signal identifier
-- `methodName` (string, optional): Service method name (defaults to signalName)
-- `paramTransformer` (function, optional): Transform incoming parameters
-- `resultTransformer` (function, optional): Transform outgoing results
-
-#### `@KafkaSignalRouter(serviceTypes, options?)`
-
-Class decorator for signal routing setup.
-
-**Parameters:**
-- `serviceTypes` (Type<any> | Type<any>[]): Service classes to route to
-- `options` (object, optional): Configuration options
-
-### Classes
-
-#### `KafkaClientBase`
-
-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
-
-#### `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
-
-### Functions
+See `API.md`.
 
-#### `createNevoKafkaClient(serviceNames, options)`
+## Examples
 
-Factory function for creating Kafka client providers.
+### NATS
+- `examples/nats-user` - NATS request/response + publish/subscribe + broadcast
 
-#### `createKafkaMicroservice(options)`
+### Kafka
+- `examples/user` - standard Kafka microservice
 
-Bootstrap function for starting NestJS microservices with Kafka transport.
+### Socket.IO
+- `examples/socket-user` - Socket.IO transport with subscribe/broadcast
 
+### HTTP (SSE)
+- `examples/http-user` - HTTP query/emit + SSE subscribe + broadcast + discovery
 ## Troubleshooting
 
 ### Common Issues
@@ -828,4 +963,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>;
 }