62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# Normal run output ABI
|
|
|
|
This document defines the compatibility surface between the existing `rpki`
|
|
runtime and `panda-rpki-validator`. It covers normal snapshot and delta runs;
|
|
`verification-only` is deliberately outside this component.
|
|
|
|
## Persistent volume
|
|
|
|
The image exposes one data root, `/var/lib/panda-rpki-validator` by default.
|
|
The root may be changed by deployment configuration, but the relative layout
|
|
must remain:
|
|
|
|
```text
|
|
<data-root>/
|
|
├── state/
|
|
│ ├── db/ # work DB and repo-bytes state
|
|
│ ├── rsync-mirror/ # reusable rsync mirror when enabled
|
|
│ └── ... # lifecycle, TA refresh and failure-isolation state
|
|
├── runs/run_XXXX/ # retained normal run directories
|
|
├── logs/
|
|
└── tmp/
|
|
```
|
|
|
|
The component and the old runtime must never share a state root during A/B
|
|
comparison.
|
|
|
|
## Required normal-run files
|
|
|
|
Every successful snapshot/delta run must produce the following files under its
|
|
run directory:
|
|
|
|
| File | Contract |
|
|
|---|---|
|
|
| `run-meta.json` | run id/sequence, status, sync mode, timing and lifecycle metadata |
|
|
| `run-summary.json` | status, counts, artifact index, stage timing and exit information |
|
|
| `daemon-status.json` | current runner status and last-run information |
|
|
| `report.json` | validation report and object/publication-point summaries |
|
|
| `input.cir` | canonical synchronized validation input |
|
|
| `result.ccr` | canonical validated state/cache output |
|
|
| `vrps.csv` | VRP payload with the existing header, order and canonical sorting |
|
|
| `vaps.csv` | VAP payload with the existing header, order and canonical sorting |
|
|
| `validation-contract.json` | effective validation configuration and binding |
|
|
| `stage-timing.json` | stage-level timing used by diagnostics and performance gates |
|
|
| `stdout.log` / `stderr.log` | child process logs |
|
|
| `process-time.txt` | resource/time measurement when enabled |
|
|
|
|
`db-stats-estimate.txt` and lifecycle helper files remain part of the diagnostic
|
|
surface whenever the corresponding feature is enabled. Missing required files,
|
|
changed schema, changed CSV columns/order, or an undeclared semantic difference
|
|
fails compatibility even if a VRP count is produced.
|
|
|
|
## Canonical comparison
|
|
|
|
The compatibility harness compares exit code, sync mode, publication-point
|
|
outcome, accepted/rejected objects, VRP/VAP, report, CIR/CCR and state/cache
|
|
digests. It normalizes only lifecycle wall-clock timestamps, CCR `producedAt`,
|
|
absolute paths, fields explicitly marked as component/image version or
|
|
provenance, and runtime duration/resource telemetry (including digests derived
|
|
from timestamped audit events). The validation time is a fixed input and is
|
|
compared exactly. Every normalization is recorded in the baseline manifest;
|
|
output differences outside that list are failures.
|