Merge pull request #65 from tgiachi/feature/plugin-loader

feat(plugin): add SquidStd.Plugin loader package

Author: tgiachi

SquidStd.slnx

@@ -23,6 +23,7 @@
         <Project Path="src/SquidStd.Persistence/SquidStd.Persistence.csproj"/>
         <Project Path="src/SquidStd.Persistence.MessagePack/SquidStd.Persistence.MessagePack.csproj"/>
         <Project Path="src/SquidStd.Plugin.Abstractions/SquidStd.Plugin.Abstractions.csproj"/>
+        <Project Path="src/SquidStd.Plugin/SquidStd.Plugin.csproj"/>
         <Project Path="src/SquidStd.Scripting.Lua/SquidStd.Scripting.Lua.csproj"/>
         <Project Path="src/SquidStd.Services.Core/SquidStd.Services.Core.csproj"/>
         <Project Path="src/SquidStd.Storage.Abstractions/SquidStd.Storage.Abstractions.csproj"/>

docs/articles/plugin.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Plugin/README.md)]

docs/articles/toc.yml

@@ -46,6 +46,8 @@
   href: network.md
 - name: SquidStd.Plugin.Abstractions
   href: plugin-abstractions.md
+- name: SquidStd.Plugin
+  href: plugin.md
 - name: SquidStd.Database.Abstractions
   href: database-abstractions.md
 - name: SquidStd.Database

docs/tutorials/plugins.md

@@ -52,3 +52,4 @@ one plugin by hand so the contract is fully runnable without external assemblies
 ## See also
 
 - [SquidStd.Plugin.Abstractions reference](../articles/plugin-abstractions.md)
+- [SquidStd.Plugin reference](../articles/plugin.md) - the loader that discovers and configures plugins in dependency order

samples/SquidStd.Samples.Plugins/Program.cs

@@ -1,6 +1,9 @@
 using DryIoc;
+using SquidStd.Core.Data.Bootstrap;
 using SquidStd.Plugin.Abstractions.Data;
 using SquidStd.Plugin.Abstractions.Interfaces.Plugins;
+using SquidStd.Plugin.Extensions;
+using SquidStd.Services.Core.Services.Bootstrap;
 
 namespace SquidStd.Samples.Plugins;
 
@@ -41,16 +44,16 @@ private static void Main()
     {
     #region step-2
 
-        var container = new Container();
-        var context = new PluginContext();
-        context.Data["startedAt"] = DateTimeOffset.UtcNow;
-
-        ISquidStdPlugin plugin = new WeatherPlugin();
+        var bootstrap = SquidStdBootstrap.Create(
+            new SquidStdOptions { ConfigName = "plugins-sample", RootDirectory = Directory.GetCurrentDirectory() }
+        );
 
+        var plugin = new WeatherPlugin();
         Console.WriteLine($"Loading {plugin.Metadata.Name} v{plugin.Metadata.Version} by {plugin.Metadata.Author}");
-        plugin.Configure(container, context);
 
-        var greeter = container.Resolve<IGreeter>();
+        bootstrap.UsePlugins(plugins => plugins.Add(plugin));
+
+        var greeter = bootstrap.Resolve<IGreeter>();
         Console.WriteLine(greeter.Greet("squid"));
 
     #endregion

samples/SquidStd.Samples.Plugins/SquidStd.Samples.Plugins.csproj

@@ -10,6 +10,8 @@
 
     <ItemGroup>
         <ProjectReference Include="..\..\src\SquidStd.Plugin.Abstractions\SquidStd.Plugin.Abstractions.csproj"/>
+        <ProjectReference Include="..\..\src\SquidStd.Plugin\SquidStd.Plugin.csproj"/>
+        <ProjectReference Include="..\..\src\SquidStd.Services.Core\SquidStd.Services.Core.csproj"/>
     </ItemGroup>
 
 </Project>

src/SquidStd.Core/Interfaces/Bootstrap/ISquidStdBootstrap.cs

@@ -1,6 +1,7 @@
 using DryIoc;
 using SquidStd.Core.Data.Bootstrap;
 using SquidStd.Core.Interfaces.Config;
+using SquidStd.Core.Types.Bootstrap;
 
 namespace SquidStd.Core.Interfaces.Bootstrap;
 
@@ -19,6 +20,12 @@ public interface ISquidStdBootstrap : IAsyncDisposable
     /// </summary>
     IContainer Container { get; }
 
+    /// <summary>
+    /// Gets the current lifecycle state of the bootstrap. Reads are lock-free and intended for
+    /// pre-start guards, not for synchronizing concurrent lifecycle transitions.
+    /// </summary>
+    BootstrapStateType State { get; }
+
     /// <summary>
     /// Applies custom service registrations before the bootstrap lifecycle starts.
     /// </summary>

…ervices.Core/Types/BootstrapStateType.cs …re/Types/Bootstrap/BootstrapStateType.cssrc/SquidStd.Services.Core/Types/BootstrapStateType.cs renamed to src/SquidStd.Core/Types/Bootstrap/BootstrapStateType.cs src/SquidStd.Services.Core/Types/BootstrapStateType.cs renamed to src/SquidStd.Core/Types/Bootstrap/BootstrapStateType.cs

@@ -1,9 +1,9 @@
-namespace SquidStd.Services.Core.Types;
+namespace SquidStd.Core.Types.Bootstrap;
 
 /// <summary>
 /// Lifecycle state of the SquidStd bootstrapper.
 /// </summary>
-internal enum BootstrapStateType
+public enum BootstrapStateType
 {
     /// <summary>Created but not started.</summary>
     Created,

src/SquidStd.Plugin.Abstractions/Data/PluginContextKeys.cs

@@ -0,0 +1,18 @@
+namespace SquidStd.Plugin.Abstractions.Data;
+
+/// <summary>
+/// Well-known keys the SquidStd plugin loader populates in <see cref="PluginContext.Data" />.
+/// </summary>
+public static class PluginContextKeys
+{
+    /// <summary>
+    /// Application root directory (string): the bootstrap RootDirectory option.
+    /// </summary>
+    public const string RootDirectory = "squidstd:rootDirectory";
+
+    /// <summary>
+    /// Application name (string): the bootstrap AppName option when set, otherwise the entry
+    /// assembly name, otherwise the bootstrap ConfigName.
+    /// </summary>
+    public const string AppName = "squidstd:appName";
+}

src/SquidStd.Plugin.Abstractions/Data/PluginMetadata.cs

@@ -1,11 +1,11 @@
 namespace SquidStd.Plugin.Abstractions.Data;
 
 /// <summary>
-/// Describes a Moongate plugin. This is the source of truth for plugin identity.
+/// Describes a SquidStd plugin. This is the source of truth for plugin identity.
 /// </summary>
 public sealed class PluginMetadata
 {
-    /// <summary>Stable lowercase dotted plugin identifier, for example <c>moongate.weather</c>.</summary>
+    /// <summary>Stable lowercase dotted plugin identifier, for example <c>myapp.weather</c>.</summary>
     public required string Id { get; init; }
 
     /// <summary>Human-readable plugin name.</summary>