javonet-nodejs-sdk 2.6.13 → 2.6.15

package/lib/plugins/PluginRegistry.js

@@ -0,0 +1,295 @@
+/**
+ * A thread-safe registry for managing plugins.
+ * Provides access to registered plugin instances and their typed variants,
+ * allowing for dynamic plugin resolution at runtime.
+ * 
+ * Note: JavaScript is single-threaded (event loop), so thread-safety considerations
+ * from the .NET implementation are not needed here. However, the freeze pattern
+ * is still used to prevent modifications after the registration phase.
+ */
+export class PluginRegistry {
+  // Private static fields (ES2022 private fields)
+  
+  /** @type {Map<string, object>} Map of runtime context IDs to sending plugin instances */
+  static #sendingPlugins = new Map()
+  
+  /** @type {Map<string, object> | null} Immutable snapshot of sending plugins after freeze */
+  static #sendingSnapshot = null
+  
+  /** @type {SendingPluginCacheEntry | null} Hot cache for last accessed plugin */
+  static #sendingCache = null
+  
+  /** @type {object | null} The receiving plugin instance */
+  static #receivingPlugin = null
+  
+  /** @type {Function | null} The receiving plugin constructor/class */
+  static #receivingPluginType = null
+  
+  /** @type {string[] | null} Array of registered runtime context IDs for fast lookup */
+  static #registeredKeys = null
+  
+  /** @type {boolean} Whether to create new plugin instances on each resolve */
+  static #useTransientPlugins = false
+  
+  /** @type {boolean} Whether the registry has been frozen */
+  static #isFrozen = false
+
+  /**
+   * Checks if a receiving plugin has been registered
+   * @returns {boolean} True if a receiving plugin exists
+   */
+  static get hasReceivingPlugin() {
+    return PluginRegistry.#receivingPlugin !== null
+  }
+
+  /**
+   * Registers a sending plugin implementation for a specific runtime context.
+   * The plugin is stored as a singleton instance and can later be resolved using the runtime context ID.
+   * 
+   * @param {string} runtimeContextId - The UUID of the runtime context
+   * @param {object} plugin - Plugin instance that implements ICommunitySendingPlugin interface
+   * @throws {Error} If registry is already frozen
+   * @throws {TypeError} If plugin doesn't have required execute method
+   * 
+   * @example
+   * const plugin = new JwtPlugin('token123')
+   * PluginRegistry.registerSendingPlugin(runtimeCtx.runtimeContextId, plugin)
+   */
+  static registerSendingPlugin(runtimeContextId, plugin) {
+    if (PluginRegistry.#isFrozen) {
+      throw new Error('Cannot register plugins after registry has been frozen. Call reset() first.')
+    }
+
+    if (!plugin || typeof plugin.execute !== 'function') {
+      throw new TypeError('Plugin must have an execute() method')
+    }
+
+    if (!plugin.pluginId) {
+      throw new TypeError('Plugin must have a pluginId property')
+    }
+
+    if (!runtimeContextId || typeof runtimeContextId !== 'string') {
+      throw new TypeError('runtimeContextId must be a non-empty string')
+    }
+
+    PluginRegistry.#sendingPlugins.set(runtimeContextId, plugin)
+
+    // Update cache with the newly registered plugin
+    PluginRegistry.#sendingCache = {
+      key: runtimeContextId,
+      value: plugin,
+      hasValue: true,
+      type: plugin.constructor
+    }
+  }
+
+  /**
+   * Registers a receiving plugin implementation.
+   * The plugin is stored as a singleton instance and executed on the receiving side.
+   * Only one receiving plugin can be registered per application.
+   * 
+   * @param {object} plugin - Plugin instance that implements ICommunityReceivingPlugin interface
+   * @throws {Error} If a receiving plugin is already registered
+   * @throws {Error} If registry is already frozen
+   * @throws {TypeError} If plugin doesn't have required execute method
+   * 
+   * @example
+   * const plugin = new ValidationPlugin()
+   * PluginRegistry.registerReceivingPlugin(plugin)
+   */
+  static registerReceivingPlugin(plugin) {
+    if (PluginRegistry.#isFrozen) {
+      throw new Error('Cannot register plugins after registry has been frozen. Call reset() first.')
+    }
+
+    if (PluginRegistry.#receivingPlugin !== null) {
+      throw new Error('A receiving plugin is already registered. Only one receiving plugin is allowed.')
+    }
+
+    if (!plugin || typeof plugin.execute !== 'function') {
+      throw new TypeError('Plugin must have an execute(commandPayload, executionTarget) method')
+    }
+
+    if (!plugin.pluginId) {
+      throw new TypeError('Plugin must have a pluginId property')
+    }
+
+    PluginRegistry.#receivingPlugin = plugin
+    PluginRegistry.#receivingPluginType = plugin.constructor
+  }
+
+  /**
+   * Resolves and returns the registered receiving plugin instance.
+   * If transient mode is enabled, creates a new instance.
+   * 
+   * @returns {object} The receiving plugin instance
+   * @throws {Error} If no receiving plugin has been registered
+   * 
+   * @example
+   * const plugin = PluginRegistry.resolveReceivingPlugin()
+   * const result = plugin.execute(payload, target)
+   */
+  static resolveReceivingPlugin() {
+    if (PluginRegistry.#useTransientPlugins && PluginRegistry.#receivingPluginType) {
+      return new PluginRegistry.#receivingPluginType()
+    }
+
+    if (PluginRegistry.#receivingPlugin === null) {
+      throw new Error('No receiving plugin has been registered')
+    }
+
+    return PluginRegistry.#receivingPlugin
+  }
+
+  /**
+   * Attempts to retrieve a sending plugin registered for the specified runtime context.
+   * First checks a single-entry hot cache for the last accessed plugin,
+   * and if not found, falls back to the map of registered plugins.
+   * On a successful map lookup, the cache is updated with the resolved entry
+   * for faster access in subsequent calls.
+   * 
+   * @param {string} runtimeContextId - The identifier of the runtime context
+   * @returns {{success: boolean, plugin: object | null}} Object with success flag and plugin instance
+   * 
+   * @example
+   * const result = PluginRegistry.tryGetSendingPlugin(runtimeContextId)
+   * if (result.success) {
+   *   const payload = result.plugin.execute()
+   * }
+   */
+  static tryGetSendingPlugin(runtimeContextId) {
+    const localCache = PluginRegistry.#sendingCache
+
+    // If using transient plugins, create a new instance
+    if (PluginRegistry.#useTransientPlugins && localCache && localCache.hasValue && localCache.key === runtimeContextId) {
+      return {
+        success: true,
+        plugin: new localCache.type()
+      }
+    }
+
+    // Check hot cache first
+    if (localCache && localCache.hasValue && localCache.key === runtimeContextId) {
+      return {
+        success: true,
+        plugin: localCache.value
+      }
+    }
+
+    // Fall back to snapshot/map
+    const snapshot = PluginRegistry.#sendingSnapshot
+    if (snapshot && snapshot.has(runtimeContextId)) {
+      const plugin = snapshot.get(runtimeContextId)
+      
+      // Update cache for next access
+      PluginRegistry.#sendingCache = {
+        key: runtimeContextId,
+        value: plugin,
+        hasValue: true,
+        type: plugin.constructor
+      }
+
+      return {
+        success: true,
+        plugin: plugin
+      }
+    }
+
+    return {
+      success: false,
+      plugin: null
+    }
+  }
+
+  /**
+   * Checks whether any plugins have been registered for given RuntimeContext ID.
+   * 
+   * @param {string} runtimeContextId - The identifier of the runtime context
+   * @returns {boolean} True if at least one plugin is registered for the runtime context
+   * 
+   * @example
+   * if (PluginRegistry.arePluginsRegisteredForRuntime(runtimeContextId)) {
+   *   // Build and wrap command with plugin payload
+   * }
+   */
+  static arePluginsRegisteredForRuntime(runtimeContextId) {
+    const keys = PluginRegistry.#registeredKeys
+
+    if (!keys || keys.length === 0) {
+      return false
+    }
+
+    // Fast array lookup
+    return keys.includes(runtimeContextId)
+  }
+
+  /**
+   * Finalizes the plugin registration phase by creating a compact snapshot of all registered keys.
+   * This snapshot is stored to allow extremely fast lookups on the hot path.
+   * After calling freeze(), no more plugins can be registered unless reset() is called.
+   * 
+   * @param {boolean} useTransientPlugins - If true, creates new plugin instances on each resolve
+   * 
+   * @example
+   * // Register all plugins
+   * PluginRegistry.registerSendingPlugin(rtmCtx.runtimeContextId, plugin1)
+   * PluginRegistry.registerSendingPlugin(rtmCtx2.runtimeContextId, plugin2)
+   * 
+   * // Freeze the registry
+   * PluginRegistry.freeze()
+   * 
+   * // Or freeze with transient mode
+   * PluginRegistry.freeze(true)
+   */
+  static freeze(useTransientPlugins = false) {
+    PluginRegistry.#useTransientPlugins = useTransientPlugins
+
+    // Create array of registered keys for fast lookup
+    PluginRegistry.#registeredKeys = Array.from(PluginRegistry.#sendingPlugins.keys())
+
+    // Create immutable snapshot
+    PluginRegistry.#sendingSnapshot = new Map(PluginRegistry.#sendingPlugins)
+
+    // Clear the mutable map to prevent accidental modifications
+    PluginRegistry.#sendingPlugins.clear()
+
+    // Mark as frozen
+    PluginRegistry.#isFrozen = true
+  }
+
+  /**
+   * Resets the entire plugin registry to its initial state.
+   * Clears all registered plugins and unfreezes the registry.
+   * Useful for testing or reconfiguration scenarios.
+   * 
+   * @example
+   * PluginRegistry.reset()
+   * // Can now register new plugins
+   */
+  static reset() {
+    PluginRegistry.#sendingPlugins.clear()
+    PluginRegistry.#sendingSnapshot = null
+    PluginRegistry.#sendingCache = null
+    PluginRegistry.#receivingPlugin = null
+    PluginRegistry.#receivingPluginType = null
+    PluginRegistry.#registeredKeys = null
+    PluginRegistry.#useTransientPlugins = false
+    PluginRegistry.#isFrozen = false
+  }
+
+  /**
+   * Checks if the registry has been frozen
+   * @returns {boolean} True if the registry is frozen
+   */
+  static get isFrozen() {
+    return PluginRegistry.#isFrozen
+  }
+}
+
+/**
+ * @typedef {Object} SendingPluginCacheEntry
+ * @property {string} key - The runtime context ID
+ * @property {object} value - The plugin instance
+ * @property {boolean} hasValue - Whether the entry has a value
+ * @property {Function} type - The plugin constructor/class
+ */

package/lib/plugins/index.js

@@ -0,0 +1,29 @@
+/**
+ * Javonet Plugin System
+ * 
+ * This module exports all plugin-related classes and interfaces for easy importing.
+ * 
+ * @example
+ * import { PluginRegistry, ICommunitySendingPlugin } from 'javonet-nodejs-sdk/plugins'
+ * 
+ * @module plugins
+ */
+
+// Plugin Registry
+export { PluginRegistry } from './PluginRegistry.js'
+
+// Plugin Payload Builder
+export { PluginPayloadBuilder } from './PluginPayloadBuilder.js'
+
+// Plugin Interfaces
+export { ICommunityPlugin } from './interfaces/ICommunityPlugin.js'
+export { ICommunitySendingPlugin } from './interfaces/ICommunitySendingPlugin.js'
+export { ICommunityReceivingPlugin } from './interfaces/ICommunityReceivingPlugin.js'
+
+
+// Plugin Implementation Registry
+export { PluginImplementationRegistry } from './PluginImplementationRegistry.js'
+
+// Plugin Settings
+export { BasePluginSettings, PluginLangType } from './settings/BasePluginSettings.js'
+export { JwtGraftocodePluginSettings } from './settings/JwtGraftocodePluginSettings.js'

package/lib/plugins/interfaces/ICommunityPlugin.js

@@ -0,0 +1,25 @@
+/**
+ * Represents a plugin that can be registered, configured, and executed within the system.
+ * This is the base interface that all plugins must implement.
+ * 
+ * @interface ICommunityPlugin
+ */
+export class ICommunityPlugin {
+  /**
+   * Unique identifier for the plugin.
+   * This should be a string that uniquely identifies the plugin across the system.
+   * @type {string}
+   */
+  pluginId
+
+  /**
+   * Creates an instance of ICommunityPlugin
+   * This is a base class and should not be instantiated directly.
+   */
+  constructor() {
+    if (new.target === ICommunityPlugin) {
+      throw new TypeError('Cannot construct ICommunityPlugin instances directly')
+    }
+  }
+}
+

package/lib/plugins/interfaces/ICommunityReceivingPlugin.js

@@ -0,0 +1,57 @@
+import { ICommunityPlugin } from './ICommunityPlugin.js'
+
+/**
+ * Represents a receiving plugin that executes after commands are received from the target runtime.
+ * Receiving plugins can validate responses, decrypt data, or perform audit logging.
+ * 
+ * @interface ICommunityReceivingPlugin
+ * @extends {ICommunityPlugin}
+ */
+export class ICommunityReceivingPlugin extends ICommunityPlugin {
+  /**
+   * Creates an instance of ICommunityReceivingPlugin
+   * This is a base class and should not be instantiated directly.
+   */
+  constructor() {
+    super()
+    if (new.target === ICommunityReceivingPlugin) {
+      throw new TypeError('Cannot construct ICommunityReceivingPlugin instances directly')
+    }
+  }
+
+  /**
+   * Executes the plugin using the provided payload as input.
+   * This method is called after receiving commands from the target runtime.
+   * 
+   * @abstract
+   * @param {object} commandPayload - The input payload used during execution.
+   * @param {ExecutionTarget} executionTarget - Defines the execution target, including the target type name
+   *                                            and the method name that will be invoked just before execution.
+   * @returns {IExecutionContext} An execution context representing the execution result.
+   * @throws {Error} If not implemented by derived class
+   * 
+   * @example
+   * class ValidationPlugin extends ICommunityReceivingPlugin {
+   *   execute(commandPayload, executionTarget) {
+   *     console.log('Validating:', executionTarget)
+   *     return { isValid: true, result: commandPayload }
+   *   }
+   * }
+   */
+  execute(commandPayload, executionTarget) {
+    throw new Error('Method execute(commandPayload, executionTarget) must be implemented by derived class')
+  }
+}
+
+/**
+ * @typedef {Object} ExecutionTarget
+ * @property {string} typeName - The name of the target type
+ * @property {string} methodName - The name of the method being invoked
+ */
+
+/**
+ * @typedef {Object} IExecutionContext
+ * @property {boolean} isValid - Indicates if the execution was valid
+ * @property {*} result - The result of the execution
+ */
+

package/lib/plugins/interfaces/ICommunitySendingPlugin.js

@@ -0,0 +1,42 @@
+import { ICommunityPlugin } from './ICommunityPlugin.js'
+
+/**
+ * Represents a sending plugin that executes before commands are sent to the target runtime.
+ * Sending plugins can add authentication tokens, modify payloads, or inject custom data.
+ * 
+ * @interface ICommunitySendingPlugin
+ * @extends {ICommunityPlugin}
+ */
+export class ICommunitySendingPlugin extends ICommunityPlugin {
+  /**
+   * Creates an instance of ICommunitySendingPlugin
+   * This is a base class and should not be instantiated directly.
+   */
+  constructor() {
+    super()
+    if (new.target === ICommunitySendingPlugin) {
+      throw new TypeError('Cannot construct ICommunitySendingPlugin instances directly')
+    }
+  }
+
+  /**
+   * Executes the plugin and returns the result.
+   * This method is called before sending commands to the target runtime.
+   * The returned object will be serialized and included in the command payload.
+   * 
+   * @abstract
+   * @returns {object} The result of plugin execution as an object.
+   * @throws {Error} If not implemented by derived class
+   * 
+   * @example
+   * class JwtPlugin extends ICommunitySendingPlugin {
+   *   execute() {
+   *     return { token: 'abc123', timestamp: Date.now() }
+   *   }
+   * }
+   */
+  execute() {
+    throw new Error('Method execute() must be implemented by derived class')
+  }
+}
+

package/lib/plugins/settings/BasePluginSettings.js

@@ -0,0 +1,79 @@
+/**
+ * Represents the base configuration model shared by all plugins.
+ * This class contains common metadata such as plugin ID, path, and language type.
+ * 
+ * @abstract
+ * @class BasePluginSettings
+ */
+export class BasePluginSettings {
+  /**
+   * Creates an instance of BasePluginSettings.
+   * This is a base class and should not be instantiated directly.
+   */
+  constructor() {
+    if (new.target === BasePluginSettings) {
+      throw new TypeError('Cannot construct BasePluginSettings instances directly')
+    }
+
+    /**
+     * A unique identifier assigned by the developer using a predefined plugin.
+     * Used to reference or distinguish plugin instances during registration or execution.
+     * @type {string}
+     */
+    this.pluginId = ''
+
+    /**
+     * The file system path to the plugin code.
+     * This may point to a DLL (for .NET) or other file (for external languages).
+     * Should remain empty if the plugin is executed directly from a referenced package.
+     * @type {string}
+     */
+    this.pluginPath = ''
+
+    /**
+     * Defines the language or technology in which the plugin is implemented.
+     * Used to determine how the plugin should be loaded or invoked.
+     * @type {PluginLangType}
+     */
+    this.pluginLangType = null
+  }
+}
+
+/**
+ * Specifies the programming language or runtime environment used to implement a plugin.
+ * @enum {number}
+ */
+export const PluginLangType = {
+  /** .NET Framework (legacy) implementation */
+  Clr: 0,
+
+  /** Go implementation */
+  Go: 1,
+
+  /** Java class or JAR-based plugin */
+  Jvm: 2,
+
+  /** .NET Core / .NET 5+ implementation */
+  Netcore: 3,
+
+  /** Perl script or module */
+  Perl: 4,
+
+  /** Python script or module */
+  Python: 5,
+
+  /** Ruby script or library */
+  Ruby: 6,
+
+  /** Node.js JavaScript module */
+  Nodejs: 7,
+
+  /** C++ script or class-based plugin */
+  Cpp: 8,
+
+  /** PHP script or class-based plugin */
+  Php: 9,
+
+  /** Python 2.7 script or class-based plugin */
+  Python27: 10
+}

package/lib/plugins/settings/JwtGraftocodePluginSettings.js

@@ -0,0 +1,43 @@
+import { BasePluginSettings } from './BasePluginSettings.js'
+
+/**
+ * Represents configuration settings specific to JWT plugins,
+ * including user identity and authorization logic class information.
+ * Inherits shared properties from BasePluginSettings.
+ * 
+ * @class JwtGraftocodePluginSettings
+ * @extends {BasePluginSettings}
+ */
+export class JwtGraftocodePluginSettings extends BasePluginSettings {
+  /**
+   * Creates an instance of JwtGraftocodePluginSettings.
+   */
+  constructor() {
+    super()
+
+    /**
+     * Username for JWT token generation.
+     * @type {string}
+     */
+    this.username = ''
+
+    /**
+     * Secret key used for JWT token signing and validation.
+     * @type {string}
+     */
+    this.secretKey = ''
+
+    /**
+     * Whether to use attributes for authorization checks.
+     * @type {boolean}
+     */
+    this.useAttributes = false
+
+    /**
+     * JWT authorization class implementation.
+     * In Node.js, this is typically a class constructor/function rather than a Type.
+     * @type {Function | null}
+     */
+    this.jwtAuthorizeClass = null
+  }
+}