@samanbayaka/core 0.0.1

package/helper/utility/check-syntax.mjs

@@ -0,0 +1,91 @@
+import * as fs from "fs"
+import * as path from "path"
+import * as acorn from "acorn"
+
+import { ABSOLUTE_PATH } from '#hUti/file-handler.mjs'
+
+const extensions = new Set([".js", ".mjs"])
+
+const getFiles = async(dir) => {
+  const entries = await fs.promises.readdir(dir, {
+    withFileTypes: true
+  })
+
+  const files = []
+
+  for (const entry of entries) {
+    if (entry.name === "node_modules") {
+      continue
+    }
+
+    const fullPath = path.join(dir, entry.name)
+
+    if (entry.isDirectory()) {
+      files.push(...await getFiles(fullPath))
+    } else if (extensions.has(path.extname(entry.name))) {
+      files.push(fullPath)
+    }
+  }
+
+  return files
+}
+
+const checkSyntax = async(file) => {
+  const source = await fs.promises.readFile(file, "utf8")
+
+  try {
+    acorn.parse(source, {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      locations: true
+    })
+
+    return null
+  } catch (err) {
+    return {
+      file,
+      message: err.message,
+      line: err.loc?.line,
+      column: err.loc?.column
+    }
+  }
+}
+
+export const checkProjectSyntax = async(projectDir = ABSOLUTE_PATH) => {
+  const files = await getFiles(path.resolve(projectDir))
+  const errors = []
+
+  for (const file of files) {
+    const error = await checkSyntax(file)
+
+    if (error) {
+      errors.push(error)
+    }
+  }
+
+  return {
+    filesChecked: files.length,
+    errors
+  }
+}
+
+// // Example
+// const result = await checkProjectSyntax()
+
+// if (result.errors.length === 0) {
+//   console.log(
+//     `No syntax errors found (${result.filesChecked} files checked)`
+//   )
+// } else {
+//   console.error(
+//     `Found ${result.errors.length} syntax error(s):`
+//   )
+
+//   for (const error of result.errors) {
+//     console.error(
+//       `${error.file}:${error.line}:${error.column} - ${error.message}`
+//     )
+//   }
+
+//   process.exitCode = 1
+// }

package/helper/utility/config-handler.mjs

@@ -0,0 +1,161 @@
+import { Etcd3 } from "etcd3"
+import YAML from 'yaml'
+
+import * as errHdl from '#hUti/error-handler.mjs'
+
+/**
+ * Handle uncaught errors
+ */
+process.on("uncaughtException", async (err) => {
+})
+process.on("unhandledRejection", async (err) => {
+})
+
+
+/**
+ * User credentials for accessing and reading configurations from 
+ * the configuration server.
+ * @type {string}
+ * @return {array} [user, password, port]
+ */
+export const etcdCred = errHdl.validateConfigCred(process.env.SBK_CONFIG_CRED)
+
+/**
+ * Configuration Reader Client Options
+ * @type {object}
+ */
+export const client = new Etcd3({
+  hosts: `http://etcd:${etcdCred[2]}`,
+  auth: {
+    username: etcdCred[0],
+    password: etcdCred[1]
+  }
+})
+
+/**
+ * Getting configurations against a Etcd key
+ * @param  {string}
+ * @return {object | string}
+ */
+export const getConfigs = async (path, isYaml = false) => {
+  try {
+    const yamlText = (await client.get(path))?.toString()
+    if ( path.split('/').includes('yaml') ) {
+      return isYaml ? yamlText : Object.freeze( YAML.parse( yamlText ) )
+    }
+    else {
+      return yamlText
+    }
+    
+  } catch (err) {
+    throw new Error(`Unable to read configuration: ${err.message}`)
+  }
+}
+
+/**
+ * Getting all keys having prefix path
+ * @param  {string}  path  
+ * @param  {Boolean} fullPath
+ * @return {array}
+ */
+export const getConfigKeys = async (path, fullPath = false) => {
+  try {
+    const entries = await client.getAll()
+      .prefix(path)
+      .strings()
+
+    const keys = Object.keys(entries)
+
+    return fullPath ? keys : keys.map( e => e.split('/').pop() )
+  }
+  catch (err) {
+    throw new Error(`Unable to read configuration keys: ${err.message}`)
+  }
+}
+
+/**
+ * Create Etcd key with value
+ * @param  {string} path
+ * @param  {string} data
+ */
+export const putConfig = async(path, data) => {
+  await client.put(path)
+  .value(data)
+}
+
+/**
+ * Delete Etcd key
+ * @param  {string} path
+ * @return {string}
+ */
+export const delConfig = async(path) => {
+  const deletedData = await client
+    .delete()
+    .key(path)
+    .getPrevious()
+
+  return deletedData.map(item => ({
+    ...item,
+    key: Buffer.from(item.key).toString("utf8"),
+    value: Buffer.from(item.value).toString("utf8"),
+  }))
+  
+}
+
+
+export const getConfigAll = async (path, fullPath = false) => {
+  try {
+    const entries = await client.getAll()
+      .prefix(path)
+      .strings()
+
+    return fullPath 
+      ? entries
+      : Object.fromEntries(
+          Object.entries(entries).map(([key, value]) => [
+            key.replace(path, ""),
+            value
+          ])
+        )
+  }
+  catch (err) {
+    throw new Error(`Unable to read configuration keys: ${err.message}`)
+  }
+}
+
+
+export const watchConfigs = async (path, callback) => {
+  try {
+    const watcher = await client
+      .watch()
+      .prefix(path)
+      .create()
+
+    watcher.on("put", event => {
+      const evVal = path.split('/').includes('yaml')
+        ? Object.freeze( YAML.parse(event.value.toString()) )
+        : event.value?.toString()
+      callback(
+        "put",
+        event.key?.toString(),
+        evVal
+      )
+    })
+
+    watcher.on("delete", event => {
+      callback(
+        "delete",
+        event.key.toString(),
+        null
+      )
+    })
+    return watcher
+  }
+  catch (err) {
+    throw new Error(`Unable to watck configuration: ${err.message}`)
+  } 
+
+}
+
+
+

package/helper/utility/error-handler.mjs

@@ -0,0 +1,456 @@
+import dns from 'node:dns'
+import {STATUS_CODES} from 'node:http'
+import { Errors } from "moleculer"
+import { COMMIT_HASH } from "../../commit-hash.mjs"
+import { checkProjectSyntax } from '#hUti/check-syntax.mjs'
+
+
+const NODE_VER_REQ = 22
+const envRegx = /^(development|production|testing)$/
+const sysClassification = { development: 'dev', testing: 'tst', production: 'prd' }
+const commitHsRegx = /^[a-f0-9]{7}$/i
+const configCredRegex = /^[a-zA-Z0-9]{3,16} [a-zA-Z0-9!@#$^_-]{3,16} [0-9]{4,5}$/
+const serviceNmRegx = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+const portRegx = /^876[0-9]$/
+const logLvlRegx = /^(fatal|error|warn|info|debug|trace)$/i
+const telemetryRegx = /^(true|false)$/i
+
+
+/**
+ * Retain the lines from the error stack that contain "file:///" 
+ * @param  {string} error 
+ * @return {string}       
+ */
+export const extractFileLines = (stack) => {
+  if (!String(stack).includes("file:///")) {
+    return stack
+  }
+
+  const str = String(stack)
+    .split(/\r?\n/)
+
+  return [
+    str[0], 
+    ...str.filter(line => line.includes("file:///"))
+  ].join("\n")
+}
+
+/**
+ * Validate Node version
+ * @return {number}
+ *
+ * @throws error
+ */
+export const checkMinNoveVer = () => {
+  const NODE_VER_CUR = parseInt(process.versions.node.split('.')[0])
+  if(NODE_VER_CUR < NODE_VER_REQ){
+    throw new Error(`Node.js >=${NODE_VER_REQ}.x.x is required but current is ${NODE_VER_CUR}.x.x.`)
+  }
+  return NODE_VER_REQ
+}
+
+
+/**
+ * Validate APP_ENV entry
+ * @return {string}
+ *
+ * @throws error
+ */
+export const isValidAppEnv = (env) => {
+  if (!envRegx.test(env)) {
+    throw new Error(`APP_ENV is '${env}', it must be 'development', 'production', or 'testing'`)
+  }
+  return sysClassification[env]
+}
+
+
+/**
+ * Validate git commit hash
+ * @return {string}
+ *
+ * @throws error
+ */
+export const isValidCommitHash = (hs) => {
+  if(!commitHsRegx.test(hs)){
+    throw new Error(`Git commit hash is '${hs}', it must be 7-character hex string.`)
+  }
+  return hs
+}
+
+
+/**
+ * Validate namespace
+ * @retutn {string}
+ */
+export const validateNamespace = (env) => {
+  return `${isValidAppEnv(env)}-sbk-${isValidCommitHash(COMMIT_HASH)}`.toUpperCase()
+}
+
+
+/**
+ * Validate the string for establis Etcd3 client connection
+ * @return {string}
+ *
+ * @throws error
+ */
+export const validateConfigCred = (env) => {
+  if(!configCredRegex.test(env)){
+    throw new Error(`Environment variable SBK_CONFIG_CRED is "${env}". It must be a valid Etcd user credential in the format "user password port".`)
+  }
+  return env.split(" ")
+}
+
+
+/**
+ * Validate that the MAX_L1_TTL is defined and does not exceed 120 seconds
+ * @return {number} between 0 to 120
+ *
+ * @throws error
+ */
+export const validateL1TTL = (ttl = 120) => {
+  const num = Number(ttl)
+  if (!Number.isInteger(num) || num < 0 || num > 120) {
+    throw new Error(`Configuration variable 'MAX_L1_TTL' is ${ttl}, it must be between 0 and 120`)
+  }
+
+  return num
+}
+
+
+/**
+ * Validate that the MAX_L2_TTL is defined and does not exceed 600 seconds
+ * @return {number} between 0 to 600
+ *
+ * @throws error
+ */
+export const validateL2TTL = (ttl = 600) => {
+  const num = Number(ttl)
+  if (!Number.isInteger(num) || num < 0 || num > 600) {
+    throw new Error(`Configuration variable 'MAX_L2_TTL' is ${ttl}, it must be between 0 and 600`)
+  }
+
+  return num
+}
+
+
+/**
+ * Validate configuration variable SBK_PORT for Apigateway port number
+ * @return {number} between 8760 to 8769
+ *
+ * @throws error
+ */
+export const validatePort = (port) => {
+  if ( port !== undefined && !(portRegx.test(port)) ) {
+    throw new Error(`Configuration variable 'PORT' is ${port}, it must be between 8760 and 8769`)
+  }
+  return Number(port || 8765)
+}
+
+
+/**
+ * Validate environment variable SBK_LOG_LEVEL
+ * @return {string}
+ *
+ * @throws error
+ */
+export const validateLogLevel = (env) => {
+  if ( !(logLvlRegx.test(env)) ) {
+    throw new Error(`LOG_LEVEL is ${env}, it must be fatal | error | warn | info | debug | trace `)
+  }
+  return env
+}
+
+
+/**
+ * Validate hosts entry
+ * @param  {string}  dnsTxt     
+ * @param  {Boolean} isOptional
+ * @return {boolean}
+ *
+ * @throws error
+ * @throws warn
+ */
+export const validateHostEntry = (dnsTxt, isOptional = false) => {
+  return new Promise((resolve, reject) => {
+    dns.lookup(dnsTxt, (err, address) => {
+      if (err || !address) {
+        if (isOptional){
+          console.warn("\x1b[33m%s\x1b[0m", `SBKWRN ❖ Missing hosts entry for "${dnsTxt}".`)
+          return resolve(false)
+        }
+        return reject(new Error(`Missing hosts entry for "${dnsTxt}".`))
+      }
+      resolve(true)
+    })
+  })
+}
+
+
+/**
+ * Validates a service name against a predefined regex pattern.
+ *
+ * @param {string} name - The service name to validate.
+ * @returns {boolean} Returns true if the service name is valid.
+ * 
+ * @throws error
+ */
+export const validateServiceName = (schema, dirName) => {
+  const pkgName = dirName.replace(/^\$/, '')
+  if(!serviceNmRegx.test(pkgName)) {
+    throw new Error(`Invalid service name "${schema.name}".\n  Only lowercase letters (a–z), digits (0–9), and hyphens (-) are allowed.`)
+  }
+  if(schema.name.replace(/^\$/, '') != pkgName){
+    throw new Error(`Service name and package name must be the same, but found "${schema.name.replace(/^\$/, '')}" and "${pkgName}"`)
+  }
+
+  /**
+   * convert package name like  "kafka-produce" 
+   * to  moleculer supported service name "kafka.produce"
+   */
+  schema.name = schema.name.replace(/-/g, ".")
+  return true
+}
+
+
+/**
+ * Telemetry enable or disable inputs
+ * @param  {string} 
+ * @return {boolean}
+ */
+export const validateTelemetry = (env) => {
+  if ( !(telemetryRegx.test(env)) ) {
+    throw new Error(`TELEMETRY is ${env}, it must be true | false `)
+  }
+  return env.toLowerCase() === "true" ? true : false
+}
+
+/**
+ * Validate config revision 
+ * @param  {string}
+ * @return {object}
+ */
+export const validateConfRevision = (env) => {
+  env = env || '{"pub":0,"edg":0,"mem":{"system":0,"gateway":0}}'
+  return JSON.parse(env)
+}
+
+
+/**
+ * Graceful shutdown handler
+ */
+export const gracefulShutdown = async (broker, signal, err=null) => {
+  // broker.logger.info({tag:"SBK", message: `${signal} detected, Stopping the broker...`})
+  try {
+    await broker.stop()
+    if(err) {
+      const { message, stack } = err
+      // broker.logger.error({tag: "SBK", message: `Broker stopped after detecting the ${signal} signal.`}, {err})
+      broker.logger.error({tag: "SBK", message, stack: extractFileLines(stack)})
+      process.exit(1)
+    }
+    else{
+      broker.logger.info({tag: "SBK", message: "Broker stopped gracefully."})
+      process.exit(0)
+    }
+  } catch (brokerStoppingErr) {
+    if(broker) {
+      broker.logger.error({tag: "SBK"}, {brokerStoppingErr}, "Unable to stop the broker.")
+    }
+    else {
+      const { message, stack } = err
+      if (err instanceof SyntaxError) {
+        const result = await checkProjectSyntax()
+        if(result.errors.length > 0){
+          for (const error of result.errors) {
+            const {file, line, column} = error
+            console.error(
+              "\x1b[31m%s\x1b[0m",
+              ` ❖❖ SBKERR ❖❖ \nSyntaxError: ${err.message}\n    at ${file.replace(/^.*node_modules\//, "../")}:${line}:${column}`
+            )
+          }
+        }
+      }
+      else {
+        console.error("\x1b[31m%s\x1b[0m", ` ❖❖ SBKERR ❖❖ \n ${extractFileLines(stack)}`)
+      }
+      
+    }
+    
+    process.exit(1)
+  }
+}
+
+/**
+ * Captures errors thrown during request processing, logs relevant details
+ * (message, stack trace, request context), and formats a standardized
+ * error response before sending it to the client.
+ * 
+ * @type {Object}
+ */
+export const ErrorFormatterMW = {
+  localAction: (next) => {
+    return async(ctx) => {
+      try {
+        return await next(ctx)
+      } 
+      catch (err) {
+        if(!err?.data?.requestID) {          
+          const requestID = ctx?.requestID
+          const status = err?.code || 500
+          const type = err?.type || 'INTERNAL_ERROR'
+          const instance = ctx?.action?.name 
+            ? `${ctx?.action?.name}` 
+            : `event.${ctx?.event?.name}`
+          const title = err?.message || ''
+          const errors = Array.isArray(err?.data)
+            ? err.data.map(({ nodeID, action, ...rest }) => rest)
+            : err?.data || []
+
+          const stack = err?.stack || ""
+          const timestamp = new Date().toISOString()
+
+          if(err.code){
+            ctx.broker.logger.error({tag: "SBK", requestID, type, instance, errors, stack: ""})
+          }
+          else{
+            ctx.broker.logger.error({tag: "SBK", requestID, type, instance, errors, stack: extractFileLines(stack)})
+          }
+
+
+          throw new Errors.MoleculerError(
+            title, 
+            status, 
+            type, 
+            {
+              type,
+              title,              
+              status,
+              timestamp,
+              requestID,
+              errors,
+            }
+          )
+        }
+        else{
+          throw err // IMPORTANT: rethrow
+        }
+      }
+    }
+  }
+}
+
+
+export const httpErrorSchema  = {
+  type: "object",
+  properties: {
+    type: {
+      type: "string",
+      description: "Application-specific error type",
+      examples: [
+        "NOT_FOUND",
+        "UNAUTHORIZED",
+        "VALIDATION_ERROR",
+        "INTERNAL_ERROR",
+      ]
+    },
+    title: {
+      type: "string",
+      description: "Short, human-readable summary of the problem",
+      example: "test error"
+    },
+    status: {
+      type: "integer",
+      description: "HTTP status code",
+      examples: [400, 401, 422, 500]
+    },
+    detail: {
+      type: "string",
+      description: "Human-readable explanation of the problem",
+      example: "test error"
+    },
+    timestamp: {
+      type: "string",
+      description: "Timestamp when the error occurred",
+      example: "2026-04-25T18:55:45.035Z"
+    },
+    requestID: {
+      type: "string",
+      description: "Unique request identifier for tracing",
+      example: "110e025a-7362-4694-87da-63aada9cae53"
+    },
+    instance: {
+      type: "string",
+      description: "Request method and URI that caused the error",
+      example: "GET /api/test"
+    },
+    errors: {
+      type: "array",
+      default: [],
+      items: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            example: "params.id"
+          },
+          message: {
+            type: "string",
+            example: "id should be integer"
+          },
+        },
+        required: ["path", "message"],
+        additionalProperties: false
+      },
+    },
+  },
+  required: [
+    "type",
+    "title",
+    "status",
+    "detail",
+    "timestamp",
+    "requestID",
+    "instance",
+    "errors"
+  ],
+  additionalProperties: false
+}
+
+/**
+ * Normalizes error objects into a consistent HTTP response structure.
+ * Ensures all errors include a standard set of fields such as status code,
+ * message, and optional metadata for client consumption.
+ */
+export const httpErrorFormatter = (req, res, err)=> { 
+  const defaultDetails = {
+    400: "The request is malformed.",
+    401: "Authentication is required.",
+    403: "You do not have permission to perform this action.",
+    404: "The requested resource was not found.",
+    405: "The requested HTTP method is not allowed.",
+    409: "The request conflicts with the current state of the resource.",
+    415: "The request content type is not supported.",
+    422: "One or more parameters are invalid.",
+    429: "Too many requests have been made.",
+    500: "An unexpected server error occurred.",
+    502: "An invalid response was received from an upstream service.",
+    503: "The service is temporarily unavailable.",
+    504: "The request timed out."
+  }
+  const code = err?.data?.status || err?.code || 500
+
+  const errorBody = JSON.stringify({
+    type: err?.data?.type || err?.type || "about:blank",
+    title: err?.data?.title || err?.message,
+    status: code,
+    detail: err?.data?.detail || defaultDetails[code] || STATUS_CODES[code] || "Unknown error",
+    timestamp: err?.data?.timestamp || new Date().toISOString(),
+    requestID: err?.data?.requestID || req.$ctx?.requestID,
+    instance: err?.data?.instance || `${req.method} ${req.$ctx?.params?.req?.originalUrl}`,
+    errors: err?.data?.errors || []
+  })
+  res.setHeader("Content-Type", "application/json")
+  res.writeHead(code)
+  res.end(errorBody)
+
+}