javonet-nodejs-sdk 2.6.12 → 2.6.14

package/lib/core/interpreter/Interpreter.js

@@ -7,11 +7,14 @@ import { CommandSerializer } from '../protocol/CommandSerializer.js'
 import { TransmitterWebsocketBrowser } from '../transmitter/TransmitterWebsocketBrowser.js'
 import { TransmitterWebsocket } from '../transmitter/TransmitterWebsocket.js'
 import { Handler } from '../handler/Handler.js'
-
+import { PluginRegistry } from '../../plugins/PluginRegistry.js'
+import { PluginPayloadBuilder } from '../../plugins/PluginPayloadBuilder.js'
+import { Command } from '../../utils/Command.js'
+import { CommandType } from '../../utils/CommandType.js'
+ 
 /**
  * @typedef {import('../../utils/connectionData/IConnectionData.js').IConnectionData} IConnectionData
  * @typedef {typeof import('../../types.d.ts').RuntimeName} RuntimeNameType
- * @typedef {import('../../utils/Command.js').Command} Command
  */
 
 /** @type {typeof import('../receiver/Receiver.js').Receiver} */
@@ -26,13 +29,24 @@ const requireDynamic = getRequire(import.meta.url)
 export class Interpreter {
 
     /**
-     *
+     * @param {string} runtimeContextId    
      * @param {Command} command
      * @param {IConnectionData} connectionData
      * @returns {Promise<Command>}
      */
-    static async execute(command, connectionData) {
+    static async execute(runtimeContextId, command, connectionData) {
         try {
+            if (PluginRegistry.arePluginsRegisteredForRuntime(runtimeContextId)) {
+                const serializedPlugins = PluginPayloadBuilder.buildPluginsPayload(runtimeContextId)
+                
+                // Wrap the command with PluginWrapper
+                command = new Command(
+                    command.runtimeName, 
+                    CommandType.PluginWrapper, 
+                    [serializedPlugins, command]
+                )
+            }
+
             let messageByteArray = CommandSerializer.serialize(command, connectionData)
 
             if (!(messageByteArray instanceof Uint8Array)) {

package/lib/core/protocol/CommandDeserializer.js

@@ -60,6 +60,8 @@ export class CommandDeserializer {
                 return this.readUInt()
             case 'JAVONET_NULL':
                 return this.readNull()
+            case 'JAVONET_UNDEFINED':
+                return this.readUndefined()
             default:
                 throw 'Unknown type - not supported in JavaScript'
         }
@@ -186,4 +188,11 @@ export class CommandDeserializer {
         this.position += size
         return TypeDeserializer.deserializeNull()
     }
+
+    readUndefined() {
+        const size = 1
+        this.position += 2
+        this.position += size
+        return TypeDeserializer.deserializeUndefined()
+    }
 }

package/lib/core/protocol/TypeDeserializer.js

@@ -114,4 +114,9 @@ export class TypeDeserializer {
     static deserializeNull(encodedNull = null) {
         return null
     }
+
+    // eslint-disable-next-line no-unused-vars
+    static deserializeUndefined(encodedUndefined = null) {
+        return undefined
+    }
 }

package/lib/core/protocol/TypeSerializer.js

@@ -15,6 +15,9 @@ class TypeSerializer {
         if (payload_item === null) {
             return TypeSerializer.serializeNull()
         }
+        if (payload_item === undefined) {
+            return TypeSerializer.serializeUndefined()
+        }
         if (payload_item instanceof Command) {
             return TypeSerializer.serializeCommand(payload_item)
         } else if (typeof payload_item === 'number') {
@@ -36,14 +39,6 @@ class TypeSerializer {
                     payload_item
                 throw new CustomError(message, 'JAVONET_PROMISE')
             }
-            if (payload_item === undefined) {
-                throw Error(
-                    'Unsupported payload item type: ' +
-                        typeof payload_item +
-                        ' for payload item: ' +
-                        payload_item
-                )
-            }
             throw Error(
                 'Unsupported payload item type: ' +
                     (payload_item?.constructor?.name || typeof payload_item) +
@@ -185,6 +180,14 @@ class TypeSerializer {
         return buffer
     }
 
+    static serializeUndefined() {
+        const buffer = Buffer.alloc(3)
+        buffer.writeUInt8(Type.JAVONET_UNDEFINED, 0)
+        buffer.writeUInt8(1, 1)
+        buffer.writeUInt8(0, 2)
+        return buffer
+    }
+
     /**
      * @param {number} int_value
      */

package/lib/core/referenceCache/ReferencesCache.js

@@ -41,12 +41,16 @@ class ReferencesCache {
     }
 
     /**
-     * @param {string} id
-     * @returns {number}
+     * @param {string} reference_guid
+     * @returns {boolean}
      */
-    deleteReference(id) {
-        delete _cache[id]
-        return 0
+    deleteReference(reference_guid) {
+        if (reference_guid == null || typeof reference_guid !== 'string') {
+            return false
+        }
+
+        delete _cache[reference_guid]
+        return true
     }
 }
 

package/lib/core/webSocketClient/WebSocketClient.js

@@ -165,7 +165,9 @@ class WebSocketClient {
         if (messageQueue[this.url]) {
             // Reject any pending messages
             messageQueue[this.url].forEach(({ reject }) => {
-                reject(new Error('WebSocket disconnected'))
+                reject(new Error(
+                    `WebSocket to ${this.url} was disconnected. The connection was closed before the operation completed.`
+                ))
             })
             delete messageQueue[this.url]
         }
@@ -185,7 +187,10 @@ class WebSocketClient {
                 WebSocket = requireDynamic('ws')
             } catch (error) {
                 if (/** @type {{ code?: string }} */ (error).code === 'MODULE_NOT_FOUND') {
-                    throw new Error('ws module not found. Please install it using npm install ws')
+                    throw new Error(
+                        'WebSocket connection failed: the "ws" package is not installed. ' +
+                        'Install it with: npm install ws'
+                    )
                 }
                 throw error
             }
@@ -193,7 +198,10 @@ class WebSocketClient {
 
         return new Promise((resolve, reject) => {
             if (!WebSocket) {
-                return reject(new Error('ws client is null'))
+                return reject(new Error(
+                    'WebSocket connection failed: ws client is not available. ' +
+                    'In Node.js ensure the "ws" package is installed (npm install ws).'
+                ))
             }
 
             let client = clients[this.url]
@@ -202,10 +210,27 @@ class WebSocketClient {
                 clients[this.url] = client
             }
 
+            const wrapReject = (/** @type {Error | unknown} */ err) => {
+                const msg = err instanceof Error ? err.message : String(err)
+                const wrapped = new Error(
+                    `WebSocket connection to ${this.url} failed: ${msg}. ` +
+                    'Check that the server is running, the URL is correct (ws:// or wss://), ' +
+                    'and that no firewall or proxy is blocking the connection.'
+                )
+                if (err instanceof Error && 'cause' in Error.prototype) {
+                    /** @type {{ cause?: unknown }} */ (wrapped).cause = err
+                }
+                reject(wrapped)
+            }
+
             client.on(WebSocketStateEvent.OPEN, () => resolve(client))
-            client.on(WebSocketStateEvent.ERROR, (/** @type {unknown} */ error) => reject(error))
+            client.on(WebSocketStateEvent.ERROR, (/** @type {unknown} */ error) => wrapReject(error))
             client.on(WebSocketStateEvent.CLOSE, () => {
-                reject(new Error('Connection closed before receiving message'))
+                reject(new Error(
+                    `WebSocket connection to ${this.url} was closed before it could be established. ` +
+                    'The server may have refused the connection, closed immediately, or a network error occurred. ' +
+                    'Check that the server is running and the URL is correct.'
+                ))
             })
         })
     }

package/lib/core/webSocketClient/WebSocketClientBrowser.js

@@ -136,7 +136,9 @@ class WebSocketClientBrowser {
 
         if (messageQueue[this.url]) {
             messageQueue[this.url].forEach(({ reject }) => {
-                reject(new Error('WebSocket disconnected'))
+                reject(new Error(
+                    `WebSocket to ${this.url} was disconnected. The connection was closed before the operation completed.`
+                ))
             })
             delete messageQueue[this.url]
         }
@@ -152,7 +154,10 @@ class WebSocketClientBrowser {
     _connect() {
         return new Promise((resolve, reject) => {
             if (!WsClient) {
-                return reject(new Error('missing WebSocket client'))
+                return reject(new Error(
+                    `WebSocket connection to ${this.url} failed: WebSocket API is not available in this environment. ` +
+                    'Ensure the code runs in a browser or environment that supports WebSocket.'
+                ))
             }
 
             let client = clients[this.url]
@@ -162,10 +167,27 @@ class WebSocketClientBrowser {
                 clients[this.url] = client
             }
 
+            const wrapReject = (/** @type {Event | Error | unknown} */ err) => {
+                const msg = err instanceof Error ? err.message : (err instanceof Event && err.type ? `Event: ${err.type}` : String(err))
+                const wrapped = new Error(
+                    `WebSocket connection to ${this.url} failed: ${msg}. ` +
+                    'Check that the server is running, the URL is correct (ws:// or wss://), ' +
+                    'and that no firewall, CORS, or proxy is blocking the connection.'
+                )
+                if (err instanceof Error && 'cause' in Error.prototype) {
+                    /** @type {{ cause?: unknown }} */ (wrapped).cause = err
+                }
+                reject(wrapped)
+            }
+
             client.addEventListener(WebSocketState.OPEN, () => resolve(client))
-            client.addEventListener(WebSocketState.ERROR, reject)
+            client.addEventListener(WebSocketState.ERROR, (e) => wrapReject(e))
             client.addEventListener(WebSocketState.CLOSE, () => {
-                reject(new Error('Connection closed before receiving message'))
+                reject(new Error(
+                    `WebSocket connection to ${this.url} was closed before it could be established. ` +
+                    'The server may have refused the connection or a network error occurred. ' +
+                    'Check that the server is running and the URL is correct.'
+                ))
             })
         })
     }
@@ -185,7 +207,9 @@ class WebSocketClientBrowser {
 
             const handleMessage = (/** @type {any} */ message) => {
                 if (!message?.data) {
-                    return reject(new Error('Invalid message received'))
+                    return reject(new Error(
+                        `WebSocket to ${this.url}: invalid message received (no data). The server response may be malformed.`
+                    ))
                 }
 
                 const byteArray = new Uint8Array(message?.data)

package/lib/plugins/PluginImplementationRegistry.js

@@ -0,0 +1,231 @@
+/**
+ * A registry for managing plugins and their implementations.
+ * Provides access to registered plugin instances and their typed variants,
+ * allowing for dynamic plugin resolution at runtime.
+ * 
+ * This class acts as a lightweight alternative to a dependency injection container,
+ * supporting both singleton and transient lifecycles for plugins.
+ * Plugins can be resolved by type, and optionally created with constructor arguments.
+ */
+export class PluginImplementationRegistry {
+  /** @type {Map<string, Function>} Map of interface names to implementation constructors for transient plugins */
+  static #transientImplementations = new Map()
+  
+  /** @type {Map<Function, object>} Map of implementation types to singleton instances */
+  static #singletonImplementations = new Map()
+  
+  /** @type {Map<Function, object>} Map of settings types to configuration objects */
+  static #pluginConfigurations = new Map()
+
+  /**
+   * Registers a transient plugin implementation. A new instance will be created each time the plugin is resolved.
+   * 
+   * @param {Function} InterfaceClass - The interface or base class of the plugin (must be a class/constructor)
+   * @param {Function} ImplementationClass - The concrete class that implements InterfaceClass
+   * @throws {TypeError} If InterfaceClass is not a function/constructor
+   * @throws {TypeError} If ImplementationClass is not a function/constructor
+   * 
+   * @example
+   * PluginImplementationRegistry.registerPluginTransientImplementation(IJwtAuthorize, JwtAuthorizeImpl)
+   */
+  static registerPluginTransientImplementation(InterfaceClass, ImplementationClass) {
+    if (typeof InterfaceClass !== 'function') {
+      throw new TypeError(`${InterfaceClass?.name || 'InterfaceClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    if (typeof ImplementationClass !== 'function') {
+      throw new TypeError(`${ImplementationClass?.name || 'ImplementationClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    // Use the interface class name as the key
+    const interfaceName = InterfaceClass.name || InterfaceClass.toString()
+    PluginImplementationRegistry.#transientImplementations.set(interfaceName, ImplementationClass)
+  }
+
+  /**
+   * Resolves a new instance of a transiently registered plugin.
+   * 
+   * @param {Function} InterfaceClass - The type of the plugin interface to resolve
+   * @param {...any} constructorArgs - Optional arguments to pass to the constructor
+   * @returns {object} A newly created instance of the registered implementation
+   * @throws {Error} If the plugin type has not been registered as transient
+   * @throws {TypeError} If InterfaceClass is not a function/constructor
+   * 
+   * @example
+   * const jwtAuthorize = PluginImplementationRegistry.resolvePluginTransientImplementation(IJwtAuthorize)
+   */
+  static resolvePluginTransientImplementation(InterfaceClass, ...constructorArgs) {
+    if (typeof InterfaceClass !== 'function') {
+      throw new TypeError(`${InterfaceClass?.name || 'InterfaceClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    const interfaceName = InterfaceClass.name || InterfaceClass.toString()
+    const ImplementationClass = PluginImplementationRegistry.#transientImplementations.get(interfaceName)
+
+    if (!ImplementationClass) {
+      throw new Error(`No transient implementation registered for ${interfaceName}.`)
+    }
+
+    try {
+      // Create new instance with constructor arguments if provided
+      const instance = constructorArgs.length > 0
+        ? new ImplementationClass(...constructorArgs)
+        : new ImplementationClass()
+
+      if (!instance) {
+        throw new Error(`Could not instantiate ${ImplementationClass.name || 'implementation'}.`)
+      }
+
+      return instance
+    } catch (error) {
+      throw new Error(`Failed to create instance of ${ImplementationClass.name || 'implementation'}: ${error.message}`)
+    }
+  }
+
+  /**
+   * Registers a plugin configuration/settings object.
+   * 
+   * @param {Function} SettingsClass - The settings class type
+   * @param {object} settings - The settings instance to register
+   * @throws {TypeError} If SettingsClass is not a function/constructor
+   * @throws {TypeError} If settings is not an object
+   * 
+   * @example
+   * const settings = new JwtGraftocodePluginSettings()
+   * settings.username = 'user'
+   * settings.secretKey = 'key'
+   * PluginImplementationRegistry.registerPluginConfiguration(JwtGraftocodePluginSettings, settings)
+   */
+  static registerPluginConfiguration(SettingsClass, settings) {
+    if (typeof SettingsClass !== 'function') {
+      throw new TypeError(`${SettingsClass?.name || 'SettingsClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    if (!settings || typeof settings !== 'object') {
+      throw new TypeError('settings must be an object')
+    }
+
+    PluginImplementationRegistry.#pluginConfigurations.set(SettingsClass, settings)
+  }
+
+  /**
+   * Retrieves the configuration object of the specified type for a given plugin.
+   * 
+   * @param {Function} SettingsClass - The expected configuration type
+   * @returns {object | null} The configuration object, or null if not found
+   * @throws {TypeError} If SettingsClass is not a function/constructor
+   * 
+   * @example
+   * const config = PluginImplementationRegistry.getPluginConfiguration(JwtGraftocodePluginSettings)
+   * if (config) {
+   *   console.log(config.username)
+   * }
+   */
+  static getPluginConfiguration(SettingsClass) {
+    if (typeof SettingsClass !== 'function') {
+      throw new TypeError(`${SettingsClass?.name || 'SettingsClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    const config = PluginImplementationRegistry.#pluginConfigurations.get(SettingsClass)
+    return config || null
+  }
+
+  /**
+   * Checks whether a configuration has been registered for the specified plugin type.
+   * 
+   * @param {Function} SettingsClass - The settings class type to check
+   * @returns {boolean} True if a configuration entry exists, false otherwise
+   * @throws {TypeError} If SettingsClass is not a function/constructor
+   * 
+   * @example
+   * if (PluginImplementationRegistry.isPluginConfigurationAvailable(JwtGraftocodePluginSettings)) {
+   *   // Configuration exists
+   * }
+   */
+  static isPluginConfigurationAvailable(SettingsClass) {
+    if (typeof SettingsClass !== 'function') {
+      throw new TypeError(`${SettingsClass?.name || 'SettingsClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    return PluginImplementationRegistry.#pluginConfigurations.has(SettingsClass)
+  }
+
+  /**
+   * Registers a new plugin implementation of the specified type and stores it as a singleton instance.
+   * 
+   * @param {Function} InterfaceClass - The interface or base class that the plugin implementation inherits or implements
+   * @param {Function} ImplementationClass - The concrete plugin type to register
+   * @param {...any} constructorArgs - Optional arguments to pass to the constructor
+   * @throws {TypeError} If InterfaceClass is not a function/constructor
+   * @throws {TypeError} If ImplementationClass is not a function/constructor
+   * 
+   * @example
+   * PluginImplementationRegistry.registerPluginSingletonImplementation(IJwtAuthorize, JwtAuthorizeImpl)
+   * // Or with constructor arguments:
+   * PluginImplementationRegistry.registerPluginSingletonImplementation(IJwtAuthorize, JwtAuthorizeImpl, 'arg1', 'arg2')
+   */
+  static registerPluginSingletonImplementation(InterfaceClass, ImplementationClass, ...constructorArgs) {
+    if (typeof InterfaceClass !== 'function') {
+      throw new TypeError(`${InterfaceClass?.name || 'InterfaceClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    if (typeof ImplementationClass !== 'function') {
+      throw new TypeError(`${ImplementationClass?.name || 'ImplementationClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    try {
+      // Create instance with constructor arguments if provided
+      const instance = constructorArgs.length > 0
+        ? new ImplementationClass(...constructorArgs)
+        : new ImplementationClass()
+
+      if (!instance) {
+        throw new Error(`Could not create instance of ${ImplementationClass.name || 'implementation'}.`)
+      }
+
+      PluginImplementationRegistry.#singletonImplementations.set(ImplementationClass, instance)
+    } catch (error) {
+      throw new Error(`Failed to register singleton implementation: ${error.message}`)
+    }
+  }
+
+  /**
+   * Resolves a registered plugin implementation by its type.
+   * 
+   * @param {Function} ImplementationClass - The type of the plugin implementation to resolve
+   * @returns {object} The registered plugin instance
+   * @throws {Error} If no plugin instance of the specified type is found in the registry
+   * @throws {TypeError} If ImplementationClass is not a function/constructor
+   * 
+   * @example
+   * const plugin = PluginImplementationRegistry.resolvePluginSingletonImplementation(JwtAuthorizeImpl)
+   */
+  static resolvePluginSingletonImplementation(ImplementationClass) {
+    if (typeof ImplementationClass !== 'function') {
+      throw new TypeError(`${ImplementationClass?.name || 'ImplementationClass'} is not a function. Only classes/constructors are allowed.`)
+    }
+
+    const instance = PluginImplementationRegistry.#singletonImplementations.get(ImplementationClass)
+
+    if (!instance) {
+      throw new Error(`No singleton implementation registered for ${ImplementationClass.name || 'implementation'}.`)
+    }
+
+    return instance
+  }
+
+  /**
+   * Resets the entire plugin implementation registry to its initial state.
+   * Clears all registered plugins and configurations.
+   * Useful for testing or reconfiguration scenarios.
+   * 
+   * @example
+   * PluginImplementationRegistry.reset()
+   * // Can now register new plugins
+   */
+  static reset() {
+    PluginImplementationRegistry.#transientImplementations.clear()
+    PluginImplementationRegistry.#singletonImplementations.clear()
+    PluginImplementationRegistry.#pluginConfigurations.clear()
+  }
+}

package/lib/plugins/PluginPayloadBuilder.js

@@ -0,0 +1,60 @@
+import { PluginRegistry } from "./PluginRegistry.js"
+
+/**
+ * Builds serialized payloads from registered plugins.
+ * This class is responsible for retrieving plugins from the registry,
+ * executing them, and serializing their output for transmission.
+ */
+export class PluginPayloadBuilder {
+  /**
+   * Builds the plugin payload for a specific runtime context.
+   * Retrieves the sending plugin registered for the given runtime context ID,
+   * executes it, and returns the serialized result.
+   * 
+   * @param {string} runtimeContextId - The UUID of the runtime context
+   * @returns {string} JSON-serialized plugin payload
+   * @throws {Error} If no plugin is found for the runtime context
+   * @throws {Error} If plugin execution fails
+   * 
+   * @example
+   * const payload = PluginPayloadBuilder.buildPluginsPayload(runtimeContextId)
+   * // Returns: '{"token":"abc123","timestamp":1234567890}'
+   */
+  static buildPluginsPayload(runtimeContextId) {
+    const result = PluginRegistry.tryGetSendingPlugin(runtimeContextId)
+
+    if (result.success && result.plugin) {
+      try {
+        // Execute the plugin to get the payload data
+        const payload = result.plugin.execute()
+        
+        if (!result?.plugin?.pluginId) {
+          throw new Error('Plugin execution failed pluginId is not defined')
+        }
+        const objectPayload = { [result?.plugin?.pluginId]: payload }
+        return PluginPayloadBuilder.serializeObject(objectPayload)
+      } catch (error) {
+        throw new Error(`Plugin execution failed for runtime context ${runtimeContextId}: ${error.message}`)
+      }
+    }
+
+    throw new Error(`Plugin for runtime context ${runtimeContextId} not found.`)
+  }
+
+  /**
+   * Serializes an object to JSON string.
+   * 
+   * @param {object} payload - The payload object to serialize
+   * @returns {string} JSON-serialized string
+   * @throws {Error} If serialization fails
+   * 
+   * @private
+   */
+  static serializeObject(payload) {
+    try {
+      return JSON.stringify(payload)
+    } catch (error) {
+      throw new Error(`Failed to serialize plugin payload: ${error.message}`)
+    }
+  }
+}