Merge pull request #21 from DevelApp-ai/copilot/fix-220572152-310773785-588774bd-232a-469f-afa4-329fbca131e0

Expose async module-based plugin loading types for Kubernetes/remote sources (v2.1.0)

Author: larsbuch

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to the RuntimePluggableClassFactory project will be document
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2025-11-03
+
+### Added - Async Module-Based Plugin Loading Support
+
+#### Expanded Async Loading Capabilities
+- **HybridPluginFactory<T>**: Officially exposed factory for working with both traditional and containerized plugins
+- **PluginInfo**: Public type for plugin metadata including execution mode and container information
+- **PluginExecutionMode**: Enum for specifying plugin execution mode (Auto, Traditional, Containerized)
+- **HybridPluginFactoryOptions**: Configuration options for hybrid plugin loading
+- Moved hybrid plugin types from Examples namespace to main public API namespace
+
+#### Module Identification Types (Already Public, Now Documented)
+- **PluginIdentifier**: Identifies plugins by namespace, name, and version
+- **ContainerizedPluginInfo**: Information about deployed containerized plugins
+- **ContainerizedPluginLoader<T>**: Async loader for containerized plugins
+- **ContainerizedPluginProxy<T>**: Proxy for bridging traditional and containerized plugin execution
+- **ContainerizedPluginLoaderOptions**: Configuration for containerized plugin loading
+
+### Changed
+- Moved `HybridPluginFactory` and related types from `.Examples` namespace to `.Containerized` namespace
+- Elevated hybrid plugin loading from example code to officially supported public API
+
+### Use Cases Enabled
+- **Dynamic Module Loading from Kubernetes/Remote Sources**: Full support for async loading of plugins from containerized environments
+- **Hybrid Plugin Architectures**: Seamlessly mix traditional in-process plugins with containerized plugins
+- **Custom Async Plugin Loaders**: All types needed for implementing custom module-based async plugin loading are now publicly exposed
+
 ## [2.0.0] - 2025-07-24
 
 ### Added - TDS Implementation Complete

README.md

@@ -205,12 +205,71 @@ All performance targets are validated by automated tests:
 - **TypedPluginClassFactory**: Type-safe plugin execution
 - **PluginExecutionSandbox**: Isolated execution environment
 - **DefaultPluginSecurityValidator**: Comprehensive security validation
+- **HybridPluginFactory** (v2.1.0+): Hybrid factory for both traditional and containerized plugins
+- **ContainerizedPluginLoader** (v2.1.0+): Async loader for containerized plugins from Kubernetes/remote sources
 
 ### Key Interfaces
 - `IPluginClass`: Basic plugin interface
 - `ITypedPluginClass<TInput, TOutput>`: Type-safe plugin interface
 - `IPluginLoader<T>`: Plugin loading interface
 - `IPluginSecurityValidator`: Security validation interface
+- `IContainerizedPluginOrchestrator` (v2.1.0+): Interface for containerized plugin orchestration
+
+## Async Module-Based Plugin Loading (v2.1.0+)
+
+### Hybrid Plugin Loading
+
+The `HybridPluginFactory` enables seamless mixing of traditional in-process plugins with containerized plugins loaded from Kubernetes or other remote sources:
+
+```csharp
+using DevelApp.RuntimePluggableClassFactory.Containerized;
+using DevelApp.RuntimePluggableClassFactory.Containerized.Interfaces;
+
+// Setup traditional plugin loader
+var traditionalLoader = new FilePluginLoader<IMyPlugin>(pluginDirectory, securityValidator);
+var traditionalFactory = new PluginClassFactory<IMyPlugin>(traditionalLoader);
+
+// Setup containerized plugin orchestrator (e.g., Kubernetes)
+var containerizedOrchestrator = new KubernetesPluginOrchestrator(/* ... */);
+
+// Create hybrid factory
+var hybridFactory = new HybridPluginFactory<IMyPlugin>(
+    traditionalFactory,
+    containerizedOrchestrator,
+    logger,
+    new HybridPluginFactoryOptions 
+    { 
+        PreferContainerized = true,
+        AutoDeployContainerized = false 
+    });
+
+// Load plugins from either source
+var plugin = await hybridFactory.GetPluginAsync(
+    new NamespaceString("MyCompany.Plugins"),
+    new IdentifierString("DataProcessor"),
+    version: new SemanticVersionNumber(1, 0, 0),
+    executionMode: PluginExecutionMode.Auto);
+
+// List all available plugins
+var availablePlugins = await hybridFactory.ListAvailablePluginsAsync();
+foreach (var pluginInfo in availablePlugins)
+{
+    Console.WriteLine($"{pluginInfo.ModuleName}.{pluginInfo.PluginName} ({pluginInfo.ExecutionMode})");
+}
+```
+
+### Module Identification Types
+
+The following types are now exposed in the public API for implementing custom async module-based plugin loading:
+
+- **PluginIdentifier**: Identifies plugins by namespace, name, and version
+- **PluginInfo**: Plugin metadata including execution mode and container information
+- **PluginExecutionMode**: Enum values - Auto, Traditional, Containerized
+- **ContainerizedPluginInfo**: Metadata for deployed containerized plugins
+- **ContainerizedPluginLoader<T>**: Async loader for containerized plugins
+- **ContainerizedPluginLoaderOptions**: Configuration for async loading
+
+These types enable dynamic module loading from Kubernetes/remote sources as an alternative to traditional directory-based scanning.
 
 ## Documentation
 

RuntimePluggableClassFactory.Containerized/Examples/HybridPluginFactory.cs renamed to RuntimePluggableClassFactory.Containerized/HybridPluginFactory.cs

@@ -6,13 +6,15 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Threading;
 using System.Threading.Tasks;
 
-namespace DevelApp.RuntimePluggableClassFactory.Containerized.Examples
+namespace DevelApp.RuntimePluggableClassFactory.Containerized
 {
     /// <summary>
-    /// Example factory that can use both traditional (in-process) and containerized plugins
-    /// This demonstrates how the CRPCF can coexist with the existing RuntimePluggableClassFactory
+    /// Factory that can use both traditional (in-process) and containerized plugins.
+    /// Enables async module-based plugin loading from Kubernetes/remote sources and local directories.
+    /// This allows the CRPCF to coexist with the existing RuntimePluggableClassFactory.
     /// </summary>
     /// <typeparam name="T">Plugin interface type</typeparam>
     public class HybridPluginFactory<T> where T : IPluginClass
@@ -46,12 +48,14 @@ public HybridPluginFactory(
         /// <param name="pluginName">Plugin name</param>
         /// <param name="version">Plugin version (optional)</param>
         /// <param name="executionMode">Preferred execution mode</param>
+        /// <param name="cancellationToken">Cancellation token</param>
         /// <returns>Plugin instance or null if not found</returns>
         public async Task<T?> GetPluginAsync(
             NamespaceString moduleName,
             IdentifierString pluginName,
             SemanticVersionNumber? version = null,
-            PluginExecutionMode executionMode = PluginExecutionMode.Auto)
+            PluginExecutionMode executionMode = PluginExecutionMode.Auto,
+            CancellationToken cancellationToken = default)
         {
             _logger.LogDebug("Getting plugin {ModuleName}.{PluginName} with execution mode {ExecutionMode}",
                 moduleName, pluginName, executionMode);
@@ -64,14 +68,14 @@ public HybridPluginFactory(
                         return await GetTraditionalPluginAsync(moduleName, pluginName, version);
 
                     case PluginExecutionMode.Containerized:
-                        return await GetContainerizedPluginAsync(moduleName, pluginName, version);
+                        return await GetContainerizedPluginAsync(moduleName, pluginName, version, cancellationToken);
 
                     case PluginExecutionMode.Auto:
                     default:
                         // Try preferred mode first, then fallback
                         if (_options.PreferContainerized)
                         {
-                            var containerized = await GetContainerizedPluginAsync(moduleName, pluginName, version);
+                            var containerized = await GetContainerizedPluginAsync(moduleName, pluginName, version, cancellationToken);
                             if (containerized != null) return containerized;
 
                             return await GetTraditionalPluginAsync(moduleName, pluginName, version);
@@ -81,7 +85,7 @@ public HybridPluginFactory(
                             var traditional = await GetTraditionalPluginAsync(moduleName, pluginName, version);
                             if (traditional != null) return traditional;
 
-                            return await GetContainerizedPluginAsync(moduleName, pluginName, version);
+                            return await GetContainerizedPluginAsync(moduleName, pluginName, version, cancellationToken);
                         }
                 }
             }
@@ -95,8 +99,10 @@ public HybridPluginFactory(
         /// <summary>
         /// Lists all available plugins from both traditional and containerized sources
         /// </summary>
+        /// <param name="cancellationToken">Cancellation token</param>
         /// <returns>Available plugins with their execution modes</returns>
-        public async Task<IEnumerable<PluginInfo>> ListAvailablePluginsAsync()
+        public async Task<IEnumerable<PluginInfo>> ListAvailablePluginsAsync(
+            CancellationToken cancellationToken = default)
         {
             var plugins = new List<PluginInfo>();
 
@@ -120,7 +126,7 @@ public async Task<IEnumerable<PluginInfo>> ListAvailablePluginsAsync()
                 // Get containerized plugins
                 if (_containerizedOrchestrator != null)
                 {
-                    var containerizedPlugins = await _containerizedOrchestrator.ListPluginsAsync();
+                    var containerizedPlugins = await _containerizedOrchestrator.ListPluginsAsync(null, cancellationToken);
                     plugins.AddRange(containerizedPlugins.Select(p => new PluginInfo
                     {
                         ModuleName = p.PluginId.Namespace,
@@ -150,8 +156,11 @@ public async Task<IEnumerable<PluginInfo>> ListAvailablePluginsAsync()
         /// Deploys a NuGet package as a containerized plugin
         /// </summary>
         /// <param name="request">Deployment request</param>
+        /// <param name="cancellationToken">Cancellation token</param>
         /// <returns>Deployment result</returns>
-        public async Task<PluginDeploymentResult> DeployContainerizedPluginAsync(PluginDeploymentRequest request)
+        public async Task<PluginDeploymentResult> DeployContainerizedPluginAsync(
+            PluginDeploymentRequest request,
+            CancellationToken cancellationToken = default)
         {
             if (_containerizedOrchestrator == null)
             {
@@ -162,7 +171,7 @@ public async Task<PluginDeploymentResult> DeployContainerizedPluginAsync(PluginD
 
             try
             {
-                return await _containerizedOrchestrator.DeployPluginAsync(request);
+                return await _containerizedOrchestrator.DeployPluginAsync(request, cancellationToken);
             }
             catch (Exception ex)
             {
@@ -236,7 +245,11 @@ public void AllowTraditionalPlugin(NamespaceString moduleName, IdentifierString
             }
         }
 
-        private async Task<T?> GetContainerizedPluginAsync(NamespaceString moduleName, IdentifierString pluginName, SemanticVersionNumber? version)
+        private async Task<T?> GetContainerizedPluginAsync(
+            NamespaceString moduleName, 
+            IdentifierString pluginName, 
+            SemanticVersionNumber? version,
+            CancellationToken cancellationToken = default)
         {
             if (_containerizedOrchestrator == null)
             {
@@ -250,10 +263,10 @@ public void AllowTraditionalPlugin(NamespaceString moduleName, IdentifierString
                 {
                     Namespace = moduleName,
                     Name = pluginName,
-                    Version = version ?? new SemanticVersionNumber(0, 0, 0) // Will match latest if version not specified
+                    Version = version ?? new SemanticVersionNumber(0, 0, 0) // Use 0.0.0 as placeholder when version not specified
                 };
 
-                var pluginInfo = await _containerizedOrchestrator.GetPluginInfoAsync(pluginId);
+                var pluginInfo = await _containerizedOrchestrator.GetPluginInfoAsync(pluginId, cancellationToken);
                 if (pluginInfo != null)
                 {
                     var proxy = ContainerizedPluginProxyFactory.Create<T>(_containerizedOrchestrator, pluginInfo);

RuntimePluggableClassFactory.Containerized/Implementations/ContainerizedPluginProxy.cs

@@ -59,7 +59,7 @@ public ContainerizedPluginProxy(
         /// <param name="context">Execution context</param>
         /// <param name="input">Input data</param>
         /// <returns>Execution result</returns>
-        public PluginExecutionResult<object> ExecuteTyped(IPluginExecutionContext context, object input)
+        public Interface.PluginExecutionResult<object> ExecuteTyped(IPluginExecutionContext context, object input)
         {
             try
             {
@@ -68,7 +68,7 @@ public PluginExecutionResult<object> ExecuteTyped(IPluginExecutionContext contex
             catch (Exception ex)
             {
                 _logger?.LogError(ex, "Error executing containerized plugin {PluginId}", _pluginId);
-                return PluginExecutionResult<object>.CreateFailure($"Plugin execution failed: {ex.Message}", ex);
+                return Interface.PluginExecutionResult<object>.CreateFailure($"Plugin execution failed: {ex.Message}", ex);
             }
         }
 
@@ -78,7 +78,7 @@ public PluginExecutionResult<object> ExecuteTyped(IPluginExecutionContext contex
         /// <param name="context">Execution context</param>
         /// <param name="input">Input data</param>
         /// <returns>Execution result</returns>
-        public async Task<PluginExecutionResult<object>> ExecuteAsync(IPluginExecutionContext context, object input)
+        public async Task<Interface.PluginExecutionResult<object>> ExecuteAsync(IPluginExecutionContext context, object input)
         {
             try
             {
@@ -130,22 +130,22 @@ public async Task<PluginExecutionResult<object>> ExecuteAsync(IPluginExecutionCo
                         }
                     }
 
-                    return PluginExecutionResult<object>.CreateSuccess(output!);
+                    return Interface.PluginExecutionResult<object>.CreateSuccess(output!);
                 }
                 else
                 {
                     _logger?.LogWarning("Containerized plugin {PluginId} execution failed: {Error}", 
                         _pluginId, result.ErrorMessage);
 
-                    return PluginExecutionResult<object>.CreateFailure(
+                    return Interface.PluginExecutionResult<object>.CreateFailure(
                         result.ErrorMessage ?? "Unknown error", 
-                        result.Exception);
+                        result.Exception ?? null!);
                 }
             }
             catch (Exception ex)
             {
                 _logger?.LogError(ex, "Error executing containerized plugin {PluginId}", _pluginId);
-                return PluginExecutionResult<object>.CreateFailure($"Plugin execution failed: {ex.Message}", ex);
+                return Interface.PluginExecutionResult<object>.CreateFailure($"Plugin execution failed: {ex.Message}", ex);
             }
         }
     }

RuntimePluggableClassFactory.Containerized/Security/NuGetSignatureValidator.cs

@@ -50,7 +50,7 @@ public async Task<PackageValidationResult> ValidatePackageAsync(
                 using var package = new PackageArchiveReader(packageStream);
 
                 // Extract package information
-                var packageInfo = await ExtractPackageInfoInternalAsync(package);
+                var packageInfo = await ExtractPackageInfoInternalAsync(package, packageStream);
 
                 // Check if signature is required
                 if (options.RequireSignature)
@@ -116,20 +116,25 @@ public async Task<SignedPackageInfo> ExtractPackageInfoAsync(Stream packageStrea
         {
             packageStream.Seek(0, SeekOrigin.Begin);
             using var package = new PackageArchiveReader(packageStream);
-            return await ExtractPackageInfoInternalAsync(package);
+            return await ExtractPackageInfoInternalAsync(package, packageStream);
         }
 
-        private async Task<SignedPackageInfo> ExtractPackageInfoInternalAsync(PackageArchiveReader package)
+        private async Task<SignedPackageInfo> ExtractPackageInfoInternalAsync(PackageArchiveReader package, Stream packageStream)
         {
             var identity = package.GetIdentity();
 
             // Calculate package hash using actual package content
             byte[] hash;
             long packageSize;
-            using (var stream = package.GetStream())
-            {
-                (hash, packageSize) = await ComputeHashAndSizeAsync(stream);
-            }
+            
+            // Save current position
+            var originalPosition = packageStream.Position;
+            
+            // Compute hash from the package stream
+            (hash, packageSize) = await ComputeHashAndSizeAsync(packageStream);
+            
+            // Restore stream position
+            packageStream.Seek(originalPosition, SeekOrigin.Begin);
 
             return new SignedPackageInfo
             {
@@ -160,7 +165,7 @@ private async Task<SignedPackageInfo> ExtractPackageInfoInternalAsync(PackageArc
                         totalBytes += bytesRead;
                     }
                 }
-                return (sha256.Hash, totalBytes);
+                return (sha256.Hash ?? Array.Empty<byte>(), totalBytes);
             }
         }
         private async Task<SignatureValidationInternalResult> ValidateSignatureAsync(PackageArchiveReader package)