429 lines
15 KiB
Markdown
Executable File
429 lines
15 KiB
Markdown
Executable File
# 10 · Plug‑in SDK Guide — **Stella Ops**
|
||
*(v 1.5 — 11 Jul 2025 · template install, no reload, IoC)*
|
||
|
||
---
|
||
|
||
## 0 Audience & Scope
|
||
Guidance for developers who extend Stella Ops with schedule jobs, scanner adapters, TLS providers, notification channels, etc. Everything here is OSS; commercial variants simply ship additional signed plug‑ins.
|
||
|
||
---
|
||
|
||
## 1 Prerequisites
|
||
|
||
| Tool | Min Version |
|
||
| ----------------------- | ----------------------------------------------------------------- |
|
||
| .NET SDK | {{ dotnet }} |
|
||
| **StellaOps templates** | install once via `bash dotnet new install StellaOps.Templates::*` |
|
||
| **Cosign** | 2.3 + — used to sign DLLs |
|
||
| xUnit | 2.6 |
|
||
| Docker CLI | only if your plug‑in shells out to containers |
|
||
|
||
---
|
||
|
||
## 2 Repository & Build Output
|
||
|
||
Every plug‑in is hosted in **`git.stella‑ops.org`**.
|
||
At publish time it must copy its signed artefacts to:
|
||
|
||
~~~text
|
||
src/backend/Stella.Ops.Plugin.Binaries/<MyPlugin>/
|
||
├── MyPlugin.dll
|
||
└── MyPlugin.dll.sig
|
||
~~~
|
||
|
||
The back‑end scans this folder on start‑up, verifies the **Cosign** signature, confirms the `[StellaPluginVersion]` gate, then loads the DLL inside an **isolated AssemblyLoadContext** to avoid dependency clashes
|
||
|
||
---
|
||
|
||
## 3 Project Scaffold
|
||
|
||
Generate with the installed template:
|
||
|
||
~~~bash
|
||
dotnet new stellaops-plugin-schedule \
|
||
-n MyPlugin.Schedule \
|
||
--output src
|
||
~~~
|
||
|
||
Result:
|
||
|
||
~~~text
|
||
src/
|
||
├─ MyPlugin.Schedule/
|
||
│ ├─ MyJob.cs
|
||
│ └─ MyPlugin.Schedule.csproj
|
||
└─ tests/
|
||
└─ MyPlugin.Schedule.Tests/
|
||
~~~
|
||
|
||
---
|
||
|
||
## 4 MSBuild Wiring
|
||
|
||
Add this to **`MyPlugin.Schedule.csproj`** so the signed DLL + `.sig` land in the canonical plug‑in folder:
|
||
|
||
~~~xml
|
||
<PropertyGroup>
|
||
<StellaPluginOut>$(SolutionDir)src/backend/Stella.Ops.Plugin.Binaries/$(MSBuildProjectName)</StellaPluginOut>
|
||
</PropertyGroup>
|
||
|
||
<ItemGroup>
|
||
|
||
<ProjectReference Include="..\..\StellaOps.Common\StellaOps.Common.csproj"
|
||
PrivateAssets="all" />
|
||
</ItemGroup>
|
||
|
||
<Target Name="CopyStellaPlugin" AfterTargets="Publish">
|
||
<MakeDir Directories="$(StellaPluginOut)" />
|
||
<Copy SourceFiles="$(PublishDir)$(AssemblyName).dll;$(PublishDir)$(AssemblyName).dll.sig"
|
||
DestinationFolder="$(StellaPluginOut)" />
|
||
</Target>
|
||
~~~
|
||
|
||
---
|
||
|
||
## 5 Dependency‑Injection Entry‑point
|
||
|
||
Back‑end auto‑discovers restart‑time bindings through two mechanisms:
|
||
|
||
1. **Service binding metadata** for simple contracts.
|
||
2. **`IDependencyInjectionRoutine`** implementations when you need full control.
|
||
|
||
### 5.1 Service binding metadata
|
||
|
||
Annotate implementations with `[ServiceBinding]` to declare their lifetime and service contract.
|
||
The loader honours scoped lifetimes and will register the service before executing any custom DI routines.
|
||
|
||
~~~csharp
|
||
using Microsoft.Extensions.DependencyInjection;
|
||
using StellaOps.DependencyInjection;
|
||
|
||
[ServiceBinding(typeof(IJob), ServiceLifetime.Scoped, RegisterAsSelf = true)]
|
||
public sealed class MyJob : IJob
|
||
{
|
||
// IJob dependencies can now use scoped services (Mongo sessions, etc.)
|
||
}
|
||
~~~
|
||
|
||
Use `RegisterAsSelf = true` when you also want to resolve the concrete type.
|
||
Set `ReplaceExisting = true` to override default descriptors if the host already provides one.
|
||
|
||
### 5.2 Dependency injection routines
|
||
|
||
For advanced scenarios continue to expose a routine:
|
||
|
||
~~~csharp
|
||
namespace StellaOps.DependencyInjection;
|
||
|
||
public sealed class IoCConfigurator : IDependencyInjectionRoutine
|
||
{
|
||
public IServiceCollection Register(IServiceCollection services, IConfiguration cfg)
|
||
{
|
||
services.AddSingleton<IJob, MyJob>(); // schedule job
|
||
services.Configure<MyPluginOptions>(cfg.GetSection("Plugins:MyPlugin"));
|
||
return services;
|
||
}
|
||
}
|
||
~~~
|
||
|
||
---
|
||
|
||
## 6 Schedule Plug‑ins
|
||
|
||
### 6.1 Minimal Job
|
||
|
||
~~~csharp
|
||
using StellaOps.Scheduling; // contract
|
||
|
||
[StellaPluginVersion("2.0.0")]
|
||
public sealed class MyJob : IJob
|
||
{
|
||
public async Task ExecuteAsync(CancellationToken ct)
|
||
{
|
||
Console.WriteLine("Hello from plug‑in!");
|
||
await Task.Delay(500, ct);
|
||
}
|
||
}
|
||
~~~
|
||
|
||
### 6.2 Cron Registration
|
||
|
||
```csharp
|
||
services.AddCronJob<MyJob>("0 15 * * *"); // everyday
|
||
```
|
||
|
||
15:00
|
||
Cron syntax follows Hangfire rules
|
||
|
||
## 7 Scanner Adapters
|
||
|
||
Implement IScannerRunner.
|
||
Register inside Configure:
|
||
```csharp
|
||
services.AddScanner<MyAltScanner>("alt"); // backend
|
||
```
|
||
|
||
selects by --engine alt
|
||
If the engine needs a side‑car container, include a Dockerfile in your repo and document resource expectations.
|
||
## 8 Packaging & Signing
|
||
|
||
```bash
|
||
dotnet publish -c Release -p:PublishSingleFile=true -o out
|
||
cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll # sign binary only
|
||
sha256sum out/MyPlugin.Schedule.dll > out/.sha256 # optional checksum
|
||
zip MyPlugin.zip out/* README.md
|
||
```
|
||
|
||
Unsigned DLLs are refused when StellaOps:Security:DisableUnsigned=false.
|
||
|
||
## 9 Deployment
|
||
|
||
```bash
|
||
docker cp MyPlugin.zip <backend>:/opt/plugins/ && docker restart <backend>
|
||
```
|
||
|
||
Check /health – "plugins":["MyPlugin.Schedule@2.0.0"].
|
||
(Hot‑reload was removed to keep the core process simple and memory‑safe.)
|
||
|
||
## 10 Configuration Patterns
|
||
|
||
| Need | Pattern |
|
||
| ------------ | --------------------------------------------------------- |
|
||
| Settings | Plugins:MyPlugin:* in appsettings.json. |
|
||
| Secrets | Redis secure:<plugin>:<key> (encrypted per TLS provider). |
|
||
| Dynamic cron | Implement ICronConfigurable; UI exposes editor. |
|
||
|
||
## 11 Testing & CI
|
||
|
||
| Layer | Tool | Gate |
|
||
| ----------- | -------------------------- | ------------------- |
|
||
| Unit | xUnit + Moq | ≥ 50 % lines |
|
||
| Integration | Testcontainers ‑ run in CI | Job completes < 5 s |
|
||
| Style | dotnet | format 0 warnings |
|
||
|
||
Use the pre‑baked workflow in StellaOps.Templates as starting point.
|
||
|
||
## 12 Publishing to the Community Marketplace
|
||
|
||
Tag Git release plugin‑vX.Y.Z and attach the signed ZIP.
|
||
Submit a PR to stellaops/community-plugins.json with metadata & git URL.
|
||
On merge, the plug‑in shows up in the UI Marketplace.
|
||
|
||
## 13 Common Pitfalls
|
||
|
||
| Symptom | Root cause | Fix |
|
||
| ------------------- | -------------------------- | ------------------------------------------- |
|
||
| NotDetected | .sig missing | cosign sign … |
|
||
| VersionGateMismatch | Backend 2.1 vs plug‑in 2.0 | Re‑compile / bump attribute |
|
||
| FileLoadException | Duplicate | StellaOps.Common Ensure PrivateAssets="all" |
|
||
| Redis | timeouts Large writes | Batch or use Mongo |
|
||
|
||
---
|
||
|
||
## 14 Plugin Version Compatibility (v2.0)
|
||
|
||
**IMPORTANT:** All plugins **must** declare a `[StellaPluginVersion]` attribute. Plugins without this attribute will be rejected by the host loader.
|
||
|
||
Declare your plugin's version and host compatibility requirements:
|
||
|
||
```csharp
|
||
using StellaOps.Plugin.Versioning;
|
||
|
||
// In AssemblyInfo.cs or any file at assembly level
|
||
[assembly: StellaPluginVersion("1.2.0", MinimumHostVersion = "1.0.0", MaximumHostVersion = "2.0.0")]
|
||
```
|
||
|
||
| Property | Purpose | Required |
|
||
|----------|---------|----------|
|
||
| `pluginVersion` (constructor) | Your plugin's semantic version | **Yes** |
|
||
| `MinimumHostVersion` | Lowest host version that can load this plugin | Recommended |
|
||
| `MaximumHostVersion` | Highest host version supported | Recommended for cross-major compatibility |
|
||
| `RequiresSignature` | Whether signature verification is mandatory (default: true) | No |
|
||
|
||
### Version Compatibility Rules
|
||
|
||
1. **Attribute Required:** Plugins without `[StellaPluginVersion]` are rejected
|
||
2. **Minimum Version:** Host version must be ≥ `MinimumHostVersion`
|
||
3. **Maximum Version:** Host version must be ≤ `MaximumHostVersion` (if specified)
|
||
4. **Strict Major Version:** If `MaximumHostVersion` is not specified, the plugin is assumed to only support the same major version as `MinimumHostVersion`
|
||
|
||
### Examples
|
||
|
||
```csharp
|
||
// Plugin works with host 1.0.0 through 2.x (explicit range)
|
||
[assembly: StellaPluginVersion("1.0.0", MinimumHostVersion = "1.0.0", MaximumHostVersion = "2.99.99")]
|
||
|
||
// Plugin works with host 2.x only (strict - no MaximumHostVersion means same major version)
|
||
[assembly: StellaPluginVersion("1.0.0", MinimumHostVersion = "2.0.0")]
|
||
|
||
// Plugin version 3.0.0 with no host constraints (uses plugin major version as reference)
|
||
[assembly: StellaPluginVersion("3.0.0")]
|
||
```
|
||
|
||
---
|
||
|
||
## 15 Plugin Host Configuration (v2.0)
|
||
|
||
Configure the plugin loader with security-first defaults in `PluginHostOptions`:
|
||
|
||
```csharp
|
||
var options = new PluginHostOptions
|
||
{
|
||
// Version enforcement (all default to true for security)
|
||
HostVersion = new Version(2, 0, 0),
|
||
EnforceVersionCompatibility = true, // Reject incompatible plugins
|
||
RequireVersionAttribute = true, // Reject plugins without [StellaPluginVersion]
|
||
StrictMajorVersionCheck = true, // Reject plugins crossing major version boundaries
|
||
|
||
// Signature verification (opt-in, requires infrastructure)
|
||
EnforceSignatureVerification = true,
|
||
SignatureVerifier = new CosignPluginVerifier(new CosignVerifierOptions
|
||
{
|
||
PublicKeyPath = "/keys/cosign.pub",
|
||
UseRekorTransparencyLog = true,
|
||
AllowUnsigned = false
|
||
})
|
||
};
|
||
|
||
var result = await PluginHost.LoadPluginsAsync(options, logger);
|
||
|
||
// Check for failures
|
||
if (result.HasFailures)
|
||
{
|
||
foreach (var failure in result.Failures)
|
||
{
|
||
logger.LogError("Plugin {Path} failed: {Reason} - {Message}",
|
||
failure.AssemblyPath, failure.Reason, failure.Message);
|
||
}
|
||
}
|
||
```
|
||
|
||
### Host Options Reference
|
||
|
||
| Option | Default | Purpose |
|
||
|--------|---------|---------|
|
||
| `HostVersion` | null | The host application version for compatibility checking |
|
||
| `EnforceVersionCompatibility` | **true** | Reject plugins that fail version checks |
|
||
| `RequireVersionAttribute` | **true** | Reject plugins without `[StellaPluginVersion]` |
|
||
| `StrictMajorVersionCheck` | **true** | Reject plugins that don't explicitly support the host's major version |
|
||
| `EnforceSignatureVerification` | false | Reject plugins without valid signatures |
|
||
| `SignatureVerifier` | null | The verifier implementation (e.g., `CosignPluginVerifier`) |
|
||
|
||
### Failure Reasons
|
||
|
||
| Reason | Description |
|
||
|--------|-------------|
|
||
| `LoadError` | Assembly could not be loaded (missing dependencies, corrupt file) |
|
||
| `SignatureInvalid` | Signature verification failed |
|
||
| `IncompatibleVersion` | Plugin version constraints not satisfied |
|
||
| `MissingVersionAttribute` | Plugin lacks required `[StellaPluginVersion]` attribute |
|
||
|
||
---
|
||
|
||
## 16 Fail-Fast Options Validation (v2.0)
|
||
|
||
Use the fail-fast validation pattern to catch configuration errors at startup:
|
||
|
||
```csharp
|
||
using StellaOps.DependencyInjection.Validation;
|
||
|
||
// Register options with automatic startup validation
|
||
services.AddOptionsWithValidation<MyPluginOptions, MyPluginOptionsValidator>(
|
||
MyPluginOptions.SectionName);
|
||
|
||
// Or with data annotations
|
||
services.AddOptionsWithDataAnnotations<MyPluginOptions>(
|
||
MyPluginOptions.SectionName);
|
||
```
|
||
|
||
Create validators using the base class:
|
||
|
||
```csharp
|
||
public sealed class MyPluginOptionsValidator : OptionsValidatorBase<MyPluginOptions>
|
||
{
|
||
protected override string SectionPrefix => "Plugins:MyPlugin";
|
||
|
||
protected override void ValidateOptions(MyPluginOptions options, ValidationContext context)
|
||
{
|
||
context
|
||
.RequireNotEmpty(options.BaseUrl, nameof(options.BaseUrl))
|
||
.RequirePositive(options.TimeoutSeconds, nameof(options.TimeoutSeconds))
|
||
.RequireInRange(options.MaxRetries, nameof(options.MaxRetries), 0, 10);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 17 Available Templates (v2.0)
|
||
|
||
Install and use the official plugin templates:
|
||
|
||
```bash
|
||
# Install from local templates directory
|
||
dotnet new install ./templates
|
||
|
||
# Or install from NuGet
|
||
dotnet new install StellaOps.Templates
|
||
|
||
# Create a connector plugin
|
||
dotnet new stellaops-plugin-connector -n MyCompany.AcmeConnector
|
||
|
||
# Create a scheduled job plugin
|
||
dotnet new stellaops-plugin-scheduler -n MyCompany.CleanupJob
|
||
```
|
||
|
||
Templates include:
|
||
- Plugin entry point with version attribute
|
||
- Options class with data annotations
|
||
- Options validator with fail-fast pattern
|
||
- DI routine registration
|
||
- README with build/sign instructions
|
||
|
||
---
|
||
|
||
## 18 Migration Guide: v2.0 to v2.1
|
||
|
||
### Breaking Change: Version Attribute Required
|
||
|
||
As of v2.1, all plugins **must** include a `[StellaPluginVersion]` attribute. Plugins without this attribute will be rejected with `MissingVersionAttribute` failure.
|
||
|
||
**Before (v2.0):** Optional, plugins without attribute loaded with warning.
|
||
**After (v2.1):** Required, plugins without attribute are rejected.
|
||
|
||
### Migration Steps
|
||
|
||
1. Add the version attribute to your plugin's AssemblyInfo.cs:
|
||
```csharp
|
||
[assembly: StellaPluginVersion("1.0.0", MinimumHostVersion = "2.0.0", MaximumHostVersion = "2.99.99")]
|
||
```
|
||
|
||
2. If your plugin must support multiple major host versions, explicitly set `MaximumHostVersion`:
|
||
```csharp
|
||
// Supports host 1.x through 3.x
|
||
[assembly: StellaPluginVersion("1.0.0", MinimumHostVersion = "1.0.0", MaximumHostVersion = "3.99.99")]
|
||
```
|
||
|
||
3. Rebuild and re-sign your plugin.
|
||
|
||
### Opt-out (Not Recommended)
|
||
|
||
If you must load legacy plugins without version attributes:
|
||
```csharp
|
||
var options = new PluginHostOptions
|
||
{
|
||
RequireVersionAttribute = false, // Allow unversioned plugins (NOT recommended)
|
||
StrictMajorVersionCheck = false // Allow cross-major version loading
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## Change Log
|
||
|
||
| Version | Date | Changes |
|
||
|---------|------|---------|
|
||
| v2.1 | 2025-12-14 | **Breaking:** `[StellaPluginVersion]` attribute now required by default. Added `RequireVersionAttribute`, `StrictMajorVersionCheck` options. Added `MissingVersionAttribute` failure reason. |
|
||
| v2.0 | 2025-12-14 | Added StellaPluginVersion attribute, Cosign verification options, fail-fast validation, new templates |
|
||
| v1.5 | 2025-07-11 | Template install, no hot-reload, IoC conventions |
|