f98cea3bcf
- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings. - Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations. - Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration. - Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options. - Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations. - Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client. - Updated project file to include necessary package references for the new Issuer Directory Client library.
105 lines
5.2 KiB
Markdown
105 lines
5.2 KiB
Markdown
# Surface.Validation Design (Epic: SURFACE-SHARING)
|
|
|
|
> **Status:** Draft v1.0 — aligns with tasks `SURFACE-VAL-01..05`, `LANG-SURFACE-01..03`, `ENTRYTRACE-SURFACE-01..02`, `ZASTAVA-SURFACE-02`, `SCANNER-SECRETS-01..03`.
|
|
>
|
|
> **Audience:** Engineers integrating Surface Env/FS/Secrets, QA guild, Security guild.
|
|
|
|
## 1. Objectives
|
|
|
|
Surface.Validation provides a shared validator framework to ensure all surface consumers meet configuration and data preconditions before performing work. It prevents subtle runtime errors by failing fast with actionable diagnostics.
|
|
|
|
## 2. Core Interfaces
|
|
|
|
```csharp
|
|
public interface ISurfaceValidator
|
|
{
|
|
ValueTask<SurfaceValidationResult> ValidateAsync(SurfaceValidationContext context, CancellationToken ct = default);
|
|
}
|
|
|
|
public sealed record SurfaceValidationContext(
|
|
IServiceProvider Services,
|
|
string ComponentName,
|
|
SurfaceEnvironmentSettings Environment,
|
|
IReadOnlyDictionary<string, object?> Properties)
|
|
{
|
|
public static SurfaceValidationContext Create(
|
|
IServiceProvider services,
|
|
string componentName,
|
|
SurfaceEnvironmentSettings environment,
|
|
IReadOnlyDictionary<string, object?>? properties = null);
|
|
}
|
|
|
|
public interface ISurfaceValidatorRunner
|
|
{
|
|
ValueTask<SurfaceValidationResult> RunAllAsync(SurfaceValidationContext context, CancellationToken ct = default);
|
|
ValueTask EnsureAsync(SurfaceValidationContext context, CancellationToken ct = default);
|
|
}
|
|
|
|
public sealed record SurfaceValidationIssue(
|
|
string Code,
|
|
string Message,
|
|
SurfaceValidationSeverity Severity,
|
|
string? Hint = null);
|
|
```
|
|
|
|
`Properties` carries optional context-specific metadata (e.g., `jobId`, `imageDigest`, cache paths) so validators can tailor diagnostics without pulling additional services. Validators register with DI (`services.AddSurfaceValidation()`). Hosts call `ISurfaceValidatorRunner.RunAllAsync()` during startup and before workload execution to capture misconfiguration early; `EnsureAsync()` rethrows when `Surface:Validation:ThrowOnFailure=true`.
|
|
|
|
## 3. Built-in Validators
|
|
|
|
| Code | Severity | Description |
|
|
|------|----------|-------------|
|
|
| `SURFACE_ENV_MISSING_ENDPOINT` | Error | Raised when `SurfaceFsEndpoint` absent. |
|
|
| `SURFACE_ENV_CACHE_DIR_UNWRITABLE` | Error | Cache root not writable or disk full. |
|
|
| `SURFACE_SECRET_MISSING` | Error | Secret provider cannot locate required secret type. |
|
|
| `SURFACE_SECRET_STALE` | Warning | Secret older than rotation window. |
|
|
| `SURFACE_FS_ENDPOINT_REACHABILITY` | Error | HEAD request to Surface.FS endpoint failed. |
|
|
| `SURFACE_FS_BUCKET_MISMATCH` | Error | Provided bucket does not exist / lacks permissions. |
|
|
| `SURFACE_FEATURE_UNKNOWN` | Warning | Feature flag not recognised. |
|
|
| `SURFACE_TENANT_MISMATCH` | Error | Tenant from environment differs from Authority token tenant. |
|
|
|
|
Validation pipeline stops on the first error (severity `Error`) unless `Surface:Validation:ContinueOnError=true` is set (useful for diagnostics mode).
|
|
|
|
## 4. Extensibility
|
|
|
|
Consumers can register custom validators:
|
|
|
|
```csharp
|
|
services.AddSurfaceValidation(builder =>
|
|
builder.AddValidator<RegistryCredentialsValidator>()
|
|
.AddValidator<RuntimeCacheWarmupValidator>());
|
|
```
|
|
|
|
Validators can access DI services (e.g., HttpClient, Authority token provider) through the context. To avoid long-running checks, recommended max validation time is 500ms per validator.
|
|
|
|
## 5. Reporting & Observability
|
|
|
|
- Results exposed via `ISurfaceValidationReporter` (default logs structured JSON to `Validation` category).
|
|
- Metrics: `surface_validation_issues_total{code,severity}`.
|
|
- Optional debug endpoint `/internal/surface/validation` (Scanner WebService) returns last validation run.
|
|
|
|
## 6. Integration Guidelines
|
|
|
|
- **Scanner Worker/WebService**: fail startup if any error-level issue occurs; log warnings but continue running.
|
|
- **Scanner EntryTrace**: execute `RunAllAsync` for each scan job with properties `{imageDigest, jobId, configPath, rootPath}`. If the result contains errors, skip analysis and log the issue summary instead of failing the entire scan.
|
|
- **Zastava Webhook**: treat validation errors as fatal (webhook should not enforce policies when surface preconditions fail). Display validation error summary in `/readyz` response to aid debugging.
|
|
- **Analysers**: call `SurfaceValidation.Ensure()` before executing heavy work to catch misconfiguration during integration tests.
|
|
|
|
## 7. Testing Strategy
|
|
|
|
- Unit tests for built-in validators using in-memory providers.
|
|
- Integration tests in Scanner/Zastava verifying validators run during startup and produce expected outcomes.
|
|
- Negative tests simulating missing secrets, unreachable endpoints, or mismatched tenants.
|
|
|
|
## 8. Error Handling & Remediation
|
|
|
|
- Each issue includes a hint describing remediation steps (e.g., “Verify `SCANNER_SURFACE_FS_ENDPOINT` is reachable from worker nodes”).
|
|
- DevOps runbooks should reference issue codes in troubleshooting sections.
|
|
- `surface_validation.json` file stored alongside application logs summarises the last run for offline support.
|
|
|
|
## 9. References
|
|
|
|
- `docs/modules/scanner/design/surface-env.md`
|
|
- `docs/modules/scanner/design/surface-fs.md`
|
|
- `docs/modules/scanner/design/surface-secrets.md`
|
|
- `docs/modules/devops/runbooks/zastava-deployment.md`
|