master
66cb6c4b8a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform. - Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds. - Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies. - Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
100 lines
4.3 KiB
Markdown
100 lines
4.3 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<ValidationResult> ValidateAsync(SurfaceValidationContext context, CancellationToken ct = default);
|
|
}
|
|
|
|
public sealed record SurfaceValidationContext
|
|
(
|
|
SurfaceEnvironmentSettings Environment,
|
|
IServiceProvider Services,
|
|
string ComponentName
|
|
);
|
|
|
|
public sealed record ValidationResult
|
|
(
|
|
bool IsSuccess,
|
|
IReadOnlyCollection<SurfaceValidationIssue> Issues
|
|
);
|
|
|
|
public sealed record SurfaceValidationIssue
|
|
(
|
|
string Code,
|
|
string Message,
|
|
SurfaceValidationSeverity Severity,
|
|
string? Hint = null
|
|
);
|
|
```
|
|
|
|
Validators register with DI (`services.AddSurfaceValidation()`). Hosts call `ISurfaceValidatorRunner.RunAllAsync()` during startup and periodically (optional) to re-check configuration.
|
|
|
|
## 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.
|
|
- **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`
|