samanbayaka 0.0.13 → 0.0.14

package/README.md

@@ -30,6 +30,10 @@ This project is a modular, production-ready microservices framework built with M
 ```bash
 pnpm install samanbayaka
 ```
+Once the package is installed, you can import the library using import or require approach:
+```bash
+import sbk from "samanbayaka"
+```
 # Prerequisites
 It is assumed that NATS, Redpanda, and Redis are installed and properly configured. All services should be discoverable through the /etc/hosts file.
 #### Minimum required Node.js version: >= 22.x.x
@@ -37,6 +41,7 @@ It is assumed that NATS, Redpanda, and Redis are installed and properly configur
 node -v
 nvm use 22
 ```
+Additionally, OpenObserve is used to view logs and telemetry.
 
 #### Environment variables
 To configure all required environment variables, create a Bash file:
@@ -45,14 +50,23 @@ sudo nano /etc/logrotate.d/sbk.sh
 ```
 Paste this:
 ```bash
-##Configurations files path
+## Configurations files path
 export SBK_CONFIG_PATH=/usr/local/etc/<your_folder>
 
-##web server port 8760-8769
+## Web server port 8760-8769
 export SBK_PORT=8765
 
-##Log level allowed values are fatal | error | warn | info | debug | trace
-export SBK_LOG_LEVEL=debug
+## Log level allowed values are fatal | error | warn | info | debug | trace
+export SBK_LOG_LEVEL=info
+
+## Maximum allowed TTL for the memoryLRU (L1) cache; the value is capped at 600 seconds.
+export MAX_L1_TTL=120
+
+## Maximum allowed TTL for the redis (L2) cache; the value is capped at 86400 seconds.
+export MAX_L2_TTL=600
+
+## Enabling telemetry middleware – Set the value to true; the default is false.
+export SBK_TELEMETRY_ENABLE=false
 ```
 Set environment variables in the current Bash session.
 ```bash
@@ -98,6 +112,138 @@ Paste this:
   create 0640 node node
 }
 ```
+
+## API Docs
+
+### sbk.Errors
+
+`sbk.Errors` exposes the Moleculer `Errors` object.
+
+### sbk.getConfig
+
+`sbk.getConfig` is a function that returns a configuration object from a specified file name.
+
+The file is loaded from the configuration directory defined by the environment variable.
+
+### sbk.loadDemo
+
+`sbk.loadDemo` is an asynchronous function that creates a demo service to help understand the project.
+
+### sbk.loadGatewayService
+
+`sbk.loadGatewayService` is an asynchronous function that creates a gateway service to expose REST APIs.
+
+### sbk.loadFeatureService
+
+`sbk.loadFeatureService` is an asynchronous function that creates a feature service.
+
+##### Function Signature
+
+```js
+sbk.loadFeatureService(schema)
+```
+
+##### Parameter
+
+*  `schema` - An object that follows the Moleculer service schema structure.
+
+Example:
+
+```js
+{
+    name: "math",
+    actions: {
+        add(ctx) {
+            return Number(ctx.params.a) + Number(ctx.params.b);
+        },
+
+        sub(ctx) {
+            return Number(ctx.params.a) - Number(ctx.params.b);
+        }
+    }
+}
+```
+
+
+### sbk.auxBrokerService
+
+`sbk.auxBrokerService` is a function used to initialize and manage message brokers such as Kafka, MQTT, and RabbitMQ.
+
+##### Function Signature
+
+```js
+sbk.auxBrokerService(
+  type,
+  brokerOpts = {},
+  callback = () => {}
+)
+```
+##### Parameters
+
+* `type` *(string)* - Specifies the broker type to initialize. Supported values:
+
+  * `"kafka"`
+  * `"mqtt"`
+  * `"amqp"`
+
+Example:
+
+```js
+"kafka"
+```
+
+
+* `brokerOpts` *(object)* - Configuration object used to initialize the broker client, producer, and consumer. Example structure:
+
+```js
+{
+  name: <your_service_name>
+  client: {},
+  producer: {},
+  consumer: {
+    groupId: "all",
+    interMessageDelayMs: 10,
+  },
+  logLevel: "INFO",
+  gzip: true,
+  msgPack: true,
+  rest: false,
+}
+```
+
+Configuration Options
+
+| Property | Type | Description |
+|---|---|---|
+| `name` | `string` | Only lowercase letters (a–z), digits (0–9), and hyphens (-) are allowed. |
+| `client` | `object` | Broker client configuration |
+| `producer` | `object` | Producer configuration |
+| `consumer` | `object` | Consumer configuration |
+| `consumer.groupId` | `string` | Consumer group identifier is mandatory for the consumer |
+| `consumer.interMessageDelayMs` | `number` | Optional delay between messages in milliseconds |
+| `logLevel` | `string` | Logging level (`NOTHING`, `ERROR`, `WARN`, `INFO`, `DEBUG`), default `NOTHING` |
+| `gzip` | `boolean` | Enables message compression; only GZIP is supported, default `true` |
+| `msgPack` | `boolean` | Enables MessagePack serialization, default `true` |
+| `rest` | `boolean` | Enables REST end point, default `false` |
+
+
+* `callback` *(function)* - Callback function executed when a message/event is received.
+
+Arguments
+
+| Argument | Description |
+|---|---|
+| `ctx` | Broker context |
+| `payload` | Incoming message payload |
+
+Example:
+
+```js
+(ctx, payload) => {
+  ctx.broker.logger.debug(payload)
+}
+```
+
 # Usage
 #### Create gateway service
 The Gateway is a critical service that exposes all endpoints as REST APIs. At least one Gateway service must be running to make the REST APIs accessible.
@@ -114,7 +260,8 @@ Open index.mjs and paste the following:
 import sbk from "samanbayaka"
 await sbk.loadGatewayService()
 ```
-#### Create feature service
+---
+#### Create feature services
 ```bash
 mkdir <your_service_name>
 cd <your_service_name>
@@ -123,7 +270,7 @@ pnpm install samanbayaka
 touch index.mjs
 ```
 
-A feature service, such as "hello", can be created as follows:
+A feature service, such as `hello`, can be created as follows:
 ```bash
 mkdir hello
 cd hello
@@ -135,7 +282,7 @@ touch index.mjs
 Open index.mjs and paste the following:
 ```bash
 import sbk from "samanbayaka"
-await sbk.loadFeatureService.mainBus({
+await sbk.loadFeatureService({
   name: "hello",
   version: "v1",
 
@@ -152,7 +299,9 @@ await sbk.loadFeatureService.mainBus({
       cache: {
 
         /**
-         * These cache entries will be expired after 30 seconds.
+         * Cache entries expire after 30 seconds.
+         * For L1 caching, TTL should be defined as [L2_TTL, L1_TTL].
+         * Example: ttl: [60, 10] → L2 TTL is 60 seconds and L1 TTL is 10 seconds.
          */      
         ttl: 30
       },
@@ -169,8 +318,87 @@ await sbk.loadFeatureService.mainBus({
   },
 })
 
+```
+---
+#### Create auxaliary broker services
+##### for producer
+```bash
+mkdir <your_service_name>-<type>-<topic>
+cd <your_service_name>-<type>-<topic>
+npm init -y
+pnpm install samanbayaka
+touch index.mjs
+```
+An auxiliary service, such as a `producer` that publishes messages to the `STUDENT` topic, can be created as follows:
+```js
+mkdir producer-kafka-student
+cd producer-kafka-student
+npm init -y
+pnpm install samanbayaka
+touch index.mjs
+```
+
+Open index.mjs and paste the following:
+```bash
+import sbk from "samanbayaka"
+await sbk.auxBrokerService(
+  "kafka",
+  {
+    name: "producer-kafka-student", 
+    rest: true,
+    ...
+  }, 
+  () => {}
+)
+```
+In the service configuration `name` end with "`*`" i.e. `producer-kafka-student*` can capable to publish to the all topics start with `STUDENT` like `STUDENT.SCIENCE`, `STUDENT.ARTS` etc.
+```js
+name: "producer-kafka-student*"
+```
+
+If you do not expose the service as a REST API and run it as a private/internal service, either remove the `rest` property or set it to `false`.
+```js
+rest: false
 ```
 
+##### for consumer
+```bash
+mkdir <your_service_name>-<type>-<topic>-<group>
+cd <your_service_name>-<type>-<topic>-<group>
+npm init -y
+pnpm install samanbayaka
+touch index.mjs
+```
+An auxiliary service, such as a `consumer` that subscribe messages from the `STUDENT` topic having group name `junior`, can be created as follows:
+```js
+mkdir producer-kafka-student-junior
+cd producer-kafka-student-junior
+npm init -y
+pnpm install samanbayaka
+touch index.mjs
+```
+Open index.mjs and paste the following:
+```bash
+import sbk from "samanbayaka"
+await sbk.auxBrokerService(
+  "kafka",
+  {
+    name: "consumer-kafka-student", 
+    consumer: {
+      groupId: "junior",
+      interMessageDelayMs: 10,
+      ...
+    },
+    ...
+  }, 
+  () => {}
+)
+```
+The `interMessageDelayMs` option introduces a delay between two consecutive message/event consumptions, measured in milliseconds. If you do not need any delay between message consumption, simply remove the `interMessageDelayMs` property from the consumer options.
+
+
+---
+
 #### Run the services 
 
  * development/testing
@@ -207,9 +435,6 @@ Run the service, demo
 node demo.mjs
 ```
 
-
-
-
 <p align="center" style="margin-top: 100px;">
   <img src="https://moleculer.services/images/banner.png" alt="Moleculer Logo" width="600">
 </p>

package/commit-hash.mjs

@@ -1 +1 @@
-export const COMMIT_HASH = '289c98a';
+export const COMMIT_HASH = '782e7c8';

package/config/catcher.mjs

@@ -0,0 +1,27 @@
+/*catcher.mjs*/
+export default {
+  /**
+   * Maximum items
+   */
+  max: 200,
+
+  /**
+   * Time-to-Live in seconds
+   */
+  ttl: [600, 120],
+
+  redis: {           
+    /**
+     * Turns Redis client monitoring on.
+     */
+    monitor: false,
+
+    /**
+     * Redis settings like hostname, port, password
+     */
+    host: "redis",
+    port: 6379,
+    // password: "1234",
+    // db: 0,
+  }
+}

package/config/kafkajs.mjs

@@ -1,54 +1,66 @@
-/*kafkajs.mjs*/
-// export default Object.freeze({
-//   prefix: "SBK",
-//   client: {
-//     clientId: "moleculer-kafkajs",
-//     brokers: ["redpanda:9092"],
-//     connectionTimeout: 3000,
-//     requestTimeout: 25000,
-//     enforceRequestTimeout: false,
-//     retry: {
-//       maxRetryTime: 30000,
-//       initialRetryTime: 300,
-//       factor: 0.2,
-//       multiplier: 2,
-//       retries: 5
-//     },
-//     producer: {
-//       idempotent: true,
-//       maxInFlightRequests: 1,
-//     },
-//     logLevel: "INFO",
-//   }
-// })
-
-
-export default Object.freeze({
-  type: "Kafka",
-  options: {
-    // host: "localhost:9092", // Your Kafka broker address
-    client: {
-      clientId: "moleculer-cluster",
-      brokers: ["redpanda:9092"],
-      connectionTimeout: 3000,
-      requestTimeout: 25000,
-      enforceRequestTimeout: false,
-      retry: {
-        maxRetryTime: 30000,
-        initialRetryTime: 300,
-        factor: 0.2,
-        multiplier: 2,
-        retries: 5
-      }      
+export default {
+  client: {
+    clientId: "node-client123",
+    brokers:  ["pnsntst.wbsedcl.in:9092"],
+    connectionTimeout: 20000,
+    requestTimeout: 20000,
+    enforceRequestTimeout: true,
+    retry: {
+      maxRetryTime: 60000,
+      initialRetryTime: 300,
+      factor: 0.2,
+      multiplier: 2,
+      retries: 5
     },
-    producer: {
-      idempotent: true,
-      maxInFlightRequests: 1,
+    ssl: {
+     rejectUnauthorized: true,
     },
-    consumer: {
-      groupId: "moleculer-group"
+    sasl: {
+      mechanism: "scram-sha-256",
+      username:  "bob",
+      password:  "SUhcznwt0xopsTfDXKIPzgw66dzJpZ",
+    }, 
+  },
+  producer: {
+    retry: {
+      initialRetryTime: 300,
+      // retries: Number.MAX_SAFE_INTEGER
+      retries: 8,
+      maxRetryTime: 30000,
+      factor: 0.2,
+      multiplier: 2
     },
-    logLevel: "INFO",
-  }
-  // Ensure protocol v5 is active (default in 0.15.0-beta1)
-})
+    metadataMaxAge: 300000,
+    allowAutoTopicCreation: false,
+    transactionTimeout: 30000,
+    idempotent: true,
+    maxInFlightRequests: 1,
+  },
+  consumer: {
+    groupId: "default",
+    // partitionAssigners: <Array>,
+    sessionTimeout: 30000,
+    rebalanceTimeout: 60000,
+    heartbeatInterval: 5000,
+    metadataMaxAge: 300000,
+    allowAutoTopicCreation: false,
+    maxBytesPerPartition: 1048576,      // 1 MB
+    minBytes: 1,
+    maxBytes: 10485760,                 // 10 MB
+    maxWaitTimeInMs: 5000,
+    retry: {
+      initialRetryTime: 300,
+      retries: 8,
+      maxRetryTime: 30000,
+      factor: 0.2,
+      multiplier: 2
+    },
+    maxInFlightRequests: 1,
+    // rackId: <String>,
+    // interMessageDelayMs: 10,
+  },
+  logLevel: "INFO",
+  gzip: true,
+  msgPack: true,
+  rest: false,
+}

package/config/nats.mjs

@@ -1,26 +1,189 @@
-/*nats.mjs*/
-export default Object.freeze({
-  type: "NATS",
-  options: {
-    /**
-     * High availability
-     */
-    servers: [
-      "nats://nats:4222",
-    ],
-
-    /**
-     * Reconnect settings
-     */
-    reconnect: true,
-    maxReconnectAttempts: -1,
-    reconnectTimeWait: 2000,
-
-    /**
-     * Performance
-     */
-    maxInFlight: 1000,
-    timeout: 5000,
+/*broker.mjs*/
 
+export default {
+  /**
+   * Namespace of nodes to segment your nodes on the same network
+   */
+  namespace: "sbk",
+
+  /**
+   * Timeouts
+   */
+  requestTimeout: 10 * 1000,
+
+  /**
+   * Retry policy
+   */
+  retryPolicy: {
+    enabled: true,
+    retries: 3,
+    delay: 200,
+    maxDelay: 3000,
+    factor: 2,
+    check: err => err && !!err.retryable
+  },
+
+  /**
+   * Controls whether ctx.params is cloned or passed by reference
+   */
+  contextParamsCloning: false,
+
+  /**
+   * Limits nested service call depth
+   */
+  maxCallLevel: 100,
+
+  /**
+   * How often (seconds) a node sends heartbeat signals
+   */
+  heartbeatInterval: 5,
+  heartbeatTimeout: 20,
+
+  /**
+   * When your service shuts down
+   */
+  tracking: {
+    enabled: true,
+    shutdownTimeout: 10 * 1000,
+  },
+
+  /**
+   * Controls whether Moleculer’s built-in load balancer is used
+   */
+  disableBalancer: false,
+
+  /**
+   * Load balancing
+   */
+  registry: {
+    strategy: "RoundRobin",
+    preferLocal: true
+  },
+
+  /**
+   * Circuit breaker in Moleculer—a critical pattern to prevent 
+   * cascading failures in distributed systems
+   */
+  circuitBreaker: {
+    enabled: true,
+    threshold: 0.5,
+    minRequestCount: 50,
+    windowTime: 60,
+    halfOpenTime: 10 * 1000
+  },
+
+  /**
+   * Bulkhead (prevent overload)
+   */
+  bulkhead: {
+    enabled: true,
+    concurrency: 50,
+    maxQueueSize: 200
+  },
+
+  /**
+   * Metrics (optional but recommended)
+   */
+  metrics: {
+    enabled: false,
+    // reporter: [
+    //   {
+    //     type: "Prometheus",
+    //     options: {
+    //       port: 3030
+    //     }
+    //   }
+    // ]
+  },
+
+  tracing: {
+      enabled: false,
+      // exporter: [
+      //     "Console"
+      // ]
+  },
+
+  /**
+   * Transit options control the internal messaging layer of Moleculer
+   */
+  transit: {
+    maxQueueSize: 50 * 1000,
+    disableReconnect: false,
+    disableVersionCheck: false,
+    packetLogFilter: ["HEARTBEAT"]
+  },
+
+  uidGenerator: null,
+
+  errorHandler: null,
+  
+  // cacher: "MemoryLRU",
+
+  /**
+   * Serializer
+   */
+  serializer: "MsgPack",
+
+  validator: true,
+  errorRegenerator: null,
+
+
+  internalServices: true,
+  internalMiddlewares: true,
+
+  hotReload: false,
+
+  // middlewares: ["MyMiddleware"],
+
+  replOptions: {
+    delimiter: "mol # ",
+    customCommands: [
+      {
+        command: "hello <name>",      
+        action(broker, args) {
+            // ...
+        }
+      }
+    ]        
+  },
+
+  metadata: {
+      // region: "eu-west1"
+  },
+
+  logger: "CustomPino",
+  logLevel: "error",
+
+  /**
+   * transporter configuration
+   */
+  transporter: {
+    type: "NATS",
+    options: {
+      /**
+       * High availability
+       */
+      servers: [
+        "nats://nats:nats123@nats:4222",
+      ],
+
+      user: "nats",
+      pass: "nats123",
+
+      /**
+       * Reconnect settings
+       */
+      reconnect: true,
+      maxReconnectAttempts: -1,
+      reconnectTimeWait: 2000,
+      waitOnFirstConnect: true,
+
+      /**
+       * Performance
+       */
+      maxInFlight: 1000,
+      timeout: 5000,
+
+    }
   }
-})
+}

package/config/telemetry.mjs

@@ -0,0 +1,5 @@
+export default {
+  host: 'openobserve',
+  port: 5080,
+  token: "Basic cm9vdEBleGFtcGxlLmNvbTpQYll3S29vNDA0b3ZHWExJ" 
+}

package/helper/file/esm-loading.mjs

@@ -113,7 +113,8 @@ const pkgService = readPkg(SERVICES_DIR)
 export const serviceDtls = {
   name: pkgService.name,
   version: pkgService.version,
-  id: [pkgService.name, os.hostname(),process.pid].join("-")
+  id: [pkgService.name, os.hostname(), process.pid].join("-"),
+  osPid: [os.hostname(), process.pid].join("-")
 }