Add initial documentation
This commit is contained in:
194
docs/10_PLUGIN_SDK_GUIDE.md
Normal file
194
docs/10_PLUGIN_SDK_GUIDE.md
Normal file
@ -0,0 +1,194 @@
|
||||
# 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 | 9.0.200 |
|
||||
| **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 the static method below:
|
||||
|
||||
~~~csharp
|
||||
namespace StellaOps.DependencyInjection;
|
||||
|
||||
public static class IoCConfigurator
|
||||
{
|
||||
public static IServiceCollection Configure(this 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 |
|
||||
Reference in New Issue
Block a user