har-diff

A blazing-fast, zero-dependency infrastructure utility written in Rust to guarantee API response contract and data-type parity during major database migrations, refactors, or ORM updates.

The Core Problem It Solves

When rewriting database schemas, migrating engine providers (e.g., Oracle/SQL Server to PostgreSQL), or changing underlying data access layers, the core systemic risk is breaking upstream API contracts. Subtle variances—such as an integer column accidentally serializing as a string, dropped properties, or shifted nested objects—will bypass structural compiler checks but crash consumer applications.

Writing exhaustive integration test assertions for thousands of fields is tedious and fragile. har-diff solves this by utilizing network recordings (.har logs) of actual frontend sessions, parsing them at line-speed, and isolating structural schema variances cleanly.

Key Features & Optimization Architecture

• Deterministic Array Stabilization: Database engine swaps often alter default row index traversal orders. A query missing an explicit ORDER BY statement can return elements out of sequence across environments, generating thousands of false-positive text diffs. har-diff walks the JSON data structures recursively and sorts arrays deterministically by their string values before saving them.
• Transient Payload Masking: Eliminates log noise by replacing variable runtime fields (like incremental IDs, timestamps, processing metrics, or session states) with an immutable static placeholder (<MASKED>), isolating raw schema modifications.
• URL Parameterization: Strips query arrays and normalizes dynamic route fragments (like /api/users/1025 and /api/users/1026) down into flat, file-system safe descriptors (GET__api_users_:id.json) so they map perfectly across extraction passes.
• Zero Visualization Bloat: Offloads directory structural analysis, side-by-side positioning, and syntax highlighting entirely to your system's native Git diffing engine or editor setup.

---

Installation & Compilation

Ensure you have the Rust toolchain installed. Clone this repository and compile using optimized release profiles:

cargo build --release

Configuration

The utility looks for a .hardiffrc file in your current execution context directory to parameterize evaluation rules.

• ignore_keys: An array of object keys whose values should be structural-masked.

• ignore_routes: Exact filenames generated by the path parameterizer to skip during unpacking (ideal for dropping health checks or heavy analytical noise).

Workflow Guide

1. Capture the Traffic

Open your browser dev tools, navigate through your target user application journey targeting your baseline backend service, and export the session network log as source_capture.har. Swap your system context to your modified database backend instance, repeat the exact functional pipeline, and export as target_capture.har. OR To test it, make some changes in target_capture.har

2. Run it

cargo run --release source_capture.har target_capture.har

3. Review the Parity Variances

Leverage Git's optimization boundaries to execute an out-of-index folder diff:

git diff --no-index .hardiff/workspace/source .hardiff/workspace/target

OR open it in your browser:

Uses diff2html-cli

git diff --no-index .hardiff/workspace/source .hardiff/workspace/target | npx --package=diff2html-cli diff2html -i stdin