Config Snapshot + Diff

[Azhovan]

Introduction

This design extends Rigging’s existing DumpEffective and Provenance capabilities to add durable configuration snapshots and diff/baseline comparison.

The goal is to make it trivial to answer:

• What is this service actually running with?
• What changed between release X and Y?
• Why is staging fine but prod is broken?
• Does this config still match our approved baseline?

Design Principles

• Minimal new concepts – Build on existing dump/provenance infrastructure
• Pluggability – Custom diff logic, storage backends, and metadata injection
• Async operations – Don’t block application startup on I/O
• Scale – Support large configs (1000+ fields, 100MB+ snapshots)
• Security – HMAC signing for tamper detection + redaction
• Observability – Structured logging and basic metrics for all operations

Core Features (v1 Scope)

This MVP focuses on delivering the 80/20 of value:

Snapshot Management:

• Snapshot creation with automatic provenance tracking
• File-based persistence with atomic writes (temp file + rename)
• Template variables for dynamic naming: {{timestamp}} and {{hostname}}
• Simple field exclusion (e.g., exclude sensitive paths)
• Automatic rotation based on count (keep last N) or age (delete older than X days)
• Size limits (100MB max per snapshot) to prevent resource exhaustion

Diff and Comparison:

• Basic diff computation: added, removed, and changed fields
• Severity categorization: critical, high, medium, low (for programmatic use)
• Baseline comparison with configurable fail-on-drift behavior
• Human-readable text output and machine-readable JSON output
• Secret redaction using existing Rigging mechanisms

CLI Tool:

• Standalone rigging-diff binary for CI/CD and local development
• Read snapshots from files or stdin
• Simple exit codes: 0 (no changes), 1 (diff detected), 2 (error)
• Flags: --format, --exclude, --ignore-redacted, --baseline, --sign, --verify

Security:

• HMAC-SHA256 signing for baseline snapshots
• Signature verification to detect tampering
• Secret redaction in snapshot output
• Audit metadata: timestamp, operator, deployment ID, Git commit SHA

Integration:

• Loader API integration: WithSnapshotWriter() and WithBaselineSnapshot()
• Pluggable storage via SnapshotWriter interface (file-based default, custom for S3/GCS)
• Structured JSON logging for all snapshot operations
• Simple retry with exponential backoff for transient failures

High-Level Components

• Snapshot: Snapshot Core V1 #22

Data Models

TBD

[asadijabar]

The feature is quite big, needs to be done in few stages.

The first stage requires defining high-level components and data models for a configuration snapshot and diff system

[Azhovan]

First component Snapshot persistence:

• Snapshot: Snapshot Core V1 #22