up
This commit is contained in:
StellaOps Bot
@@ -7,6 +7,7 @@
|
||||
- 30-Nov-2025 - Standup Sprint Kickstarters
|
||||
|
||||
**Last Updated**: 2025-12-14
|
||||
**Revision**: 1.1 (Corrected to match actual implementation)
|
||||
|
||||
---
|
||||
|
||||
@@ -25,7 +26,7 @@
|
||||
- **SOLID First**: Interface and dependency inversion required
|
||||
- **100-line File Rule**: Files >100 lines must be split/refactored
|
||||
- **Contracts vs Runtime**: Public DTOs/interfaces in `*.Contracts` projects
|
||||
- **Single Composition Root**: DI wiring in `StellaOps.Web/Program.cs` and plugin `IoCConfigurator`
|
||||
- **Single Composition Root**: DI wiring in `StellaOps.Web/Program.cs` and plugin `IDependencyInjectionRoutine`
|
||||
- **No Service Locator**: Constructor injection only
|
||||
- **Fail-fast Startup**: Validate configuration before web host starts
|
||||
- **Hot-load Compatibility**: Avoid static singletons that survive plugin unload
|
||||
@@ -53,8 +54,8 @@
|
||||
- **Namespaces**: File-scoped, `StellaOps.*`
|
||||
- **Classes/records**: PascalCase
|
||||
- **Interfaces**: `I` prefix (`IScannerRunner`)
|
||||
- **Private fields**: `camelCase` (no leading `_`)
|
||||
- **Constants**: `SCREAMING_SNAKE_CASE`
|
||||
- **Private fields**: `_camelCase` (with leading underscore, standard C# convention)
|
||||
- **Constants**: `PascalCase` (standard C# convention, e.g., `MaxRetries`)
|
||||
- **Async methods**: End with `Async`
|
||||
|
||||
### 3.2 Usings
|
||||
@@ -76,7 +77,7 @@
|
||||
### 5.1 Composition Root
|
||||
|
||||
- **One composition root** per process
|
||||
- Plugins contribute via `[ServiceBinding]` or `IoCConfigurator : IDependencyInjectionRoutine`
|
||||
- Plugins contribute via `[ServiceBinding]` attribute or `IDependencyInjectionRoutine` implementations
|
||||
- Default lifetime: **scoped**
|
||||
- Singletons only for stateless, thread-safe helpers
|
||||
- Never use service locator or manually build nested service providers
|
||||
@@ -94,12 +95,13 @@ public class MyService : IMyContract
|
||||
### 5.3 Advanced DI Configuration
|
||||
|
||||
```csharp
|
||||
public class MyPluginIoCConfigurator : IDependencyInjectionRoutine
|
||||
public class MyPluginDependencyInjectionRoutine : IDependencyInjectionRoutine
|
||||
{
|
||||
public void Configure(IServiceCollection services, IConfiguration config)
|
||||
public IServiceCollection Register(IServiceCollection services, IConfiguration configuration)
|
||||
{
|
||||
services.AddScoped<IMyContract, MyService>();
|
||||
services.Configure<MyOptions>(config.GetSection("MyPlugin"));
|
||||
services.Configure<MyOptions>(configuration.GetSection("MyPlugin"));
|
||||
return services;
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -112,12 +114,12 @@ public class MyPluginIoCConfigurator : IDependencyInjectionRoutine
|
||||
|
||||
## 7. TEST LAYERS
|
||||
|
||||
- **Unit**: xUnit
|
||||
- **Property-based**: FsCheck
|
||||
- **Integration**: API with Testcontainers, DB/merge with Mongo + Redis
|
||||
- **Contracts**: gRPC breakage checks with Buf
|
||||
- **Frontend**: Jest (unit), Playwright (e2e), Lighthouse (performance/a11y)
|
||||
- **Non-functional**: k6 (load), Docker (chaos), dependency/license scanning, SBOM reproducibility
|
||||
- **Unit**: xUnit with FluentAssertions
|
||||
- **Property-based**: FsCheck (for fuzz testing in Attestor module)
|
||||
- **Integration**: API with Testcontainers (PostgreSQL)
|
||||
- **Contracts**: OpenAPI validation with Spectral
|
||||
- **Frontend**: Karma/Jasmine (unit), Playwright (e2e), Lighthouse CI (performance/a11y)
|
||||
- **Non-functional**: Dependency/license scanning, SBOM reproducibility, Axe accessibility audits
|
||||
|
||||
## 8. QUALITY GATES
|
||||
|
||||
@@ -131,21 +133,35 @@ public class MyPluginIoCConfigurator : IDependencyInjectionRoutine
|
||||
### 9.1 Plugin Templates
|
||||
|
||||
```bash
|
||||
dotnet new stellaops-plugin-schedule -n MyPlugin.Schedule
|
||||
# Install templates
|
||||
dotnet new install ./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
|
||||
```
|
||||
|
||||
### 9.2 Plugin Publishing
|
||||
|
||||
- Publish signed artifacts to `src/backend/Stella.Ops.Plugin.Binaries/<MyPlugin>/`
|
||||
- Backend verifies Cosign signature
|
||||
- Enforces `[StellaPluginVersion]` compatibility
|
||||
- Publish signed artifacts to `<Module>.PluginBinaries/<MyPlugin>/`
|
||||
- Backend verifies Cosign signature when `EnforceSignatureVerification` is enabled
|
||||
- Enforces `[StellaPluginVersion]` compatibility when `HostVersion` is configured
|
||||
- Loads plugins in isolated `AssemblyLoadContext`s
|
||||
|
||||
### 9.3 Plugin Signing
|
||||
|
||||
```bash
|
||||
dotnet publish -c Release -p:PublishSingleFile=true -o out
|
||||
cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll
|
||||
dotnet publish -c Release -o out
|
||||
cosign sign --key $COSIGN_KEY out/StellaOps.Plugin.MyConnector.dll
|
||||
```
|
||||
|
||||
### 9.4 Plugin Version Attribute
|
||||
|
||||
```csharp
|
||||
// In AssemblyInfo.cs or any file
|
||||
[assembly: StellaPluginVersion("1.0.0", MinimumHostVersion = "1.0.0")]
|
||||
```
|
||||
|
||||
## 10. POLICY DSL (stella-dsl@1)
|
||||
@@ -240,13 +256,17 @@ cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll
|
||||
- Merge strategies named and versioned
|
||||
- Artifacts record which lattice algorithm used
|
||||
|
||||
### 14.5 Sbomer Module
|
||||
### 14.5 SbomService Module
|
||||
|
||||
> Note: This module is implemented as `src/SbomService/` in the codebase.
|
||||
|
||||
- Emit SPDX 3.0.1 and CycloneDX 1.6 with stable ordering and deterministic IDs
|
||||
- Persist raw bytes + canonical form; hash canonical bytes for digest binding
|
||||
- Produce DSSE attestations for SBOM linkage and generation provenance
|
||||
|
||||
### 14.6 Feedser Module
|
||||
### 14.6 Concelier Feed Handling
|
||||
|
||||
> Note: Feed handling is implemented within the Concelier module via connectors in `src/Concelier/__Libraries/`.
|
||||
|
||||
- Treat every feed import as a versioned snapshot (URI + time + content hashes)
|
||||
- Support deterministic export/import for offline bundles
|
||||
@@ -308,9 +328,10 @@ dotnet run --project src/Scanner/StellaOps.Scanner.WebService
|
||||
### 16.2 Log Correlation
|
||||
|
||||
```csharp
|
||||
// Note: Private fields use _camelCase convention
|
||||
using var activity = Activity.Current;
|
||||
activity?.SetTag("scan.id", scanId);
|
||||
_logger.LogInformation("Processing scan {ScanId}", scanId);
|
||||
activity?.SetTag("scan.id", _scanId);
|
||||
_logger.LogInformation("Processing scan {ScanId}", _scanId);
|
||||
```
|
||||
|
||||
### 16.3 OpenTelemetry
|
||||
@@ -442,5 +463,12 @@ dotnet ef database update -p src/Module -s src/WebService
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Document Version**: 1.1
|
||||
**Target Platform**: .NET 10, PostgreSQL ≥16, Angular v17
|
||||
|
||||
## Revision History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.1 | 2025-12-14 | Corrected naming conventions (`_camelCase` for fields, `PascalCase` for constants), updated DI interface name to `IDependencyInjectionRoutine`, corrected test frameworks (PostgreSQL not Mongo/Redis, Karma/Jasmine not Jest), added plugin templates and version attribute documentation, clarified module names (SbomService, Concelier feed handling) |
|
||||
| 1.0 | 2025-12-14 | Initial consolidated reference |
|
||||
|
||||
Reference in New Issue
Block a user