Documentation

Diffsurge is a CLI tool and infrastructure for catching breaking API changes. Compare schemas, capture traffic, and replay requests against staging builds.

Installation

Install the Surge CLI globally via npm:

npm install -g diffsurge

Or use Docker (no install required):

docker run equixankit/diffsurge-cli --help

Verify the installation:

surge --help

Available platforms: macOS (Intel & Apple Silicon), Linux (x64, ARM64), Windows (x64).

Quick Start

Compare two API schemas and detect breaking changes in under 30 seconds:

# Compare two OpenAPI schemas
surge schema diff \
  --old api-v1.yaml \
  --new api-v2.yaml \
  --fail-on-breaking

# Compare two JSON response files
surge diff --old response-v1.json --new response-v2.json

# Replay captured traffic against staging
surge replay \
  --source traffic.json \
  --target http://staging.example.com

Schema Diff

Compare two OpenAPI 3.x schema files and detect breaking changes like removed endpoints, type changes, and new required parameters.

surge schema diff \
  --old api-v1.yaml \
  --new api-v2.yaml \
  --fail-on-breaking \
  --format text

Flags:

--old — Path to the old/original schema file (required)

--new — Path to the new/modified schema file (required)

--fail-on-breaking — Exit with code 1 if breaking changes found

--breaking-only — Show only breaking changes

--format — Output format: text or json

--output — Write output to a file

Exit codes:

0 — No breaking changes

1 — Breaking changes detected (with --fail-on-breaking)

2 — Error occurred

JSON Diff

Compare two JSON files and produce a detailed diff report with type changes, additions, and removals.

surge diff \
  --old response-v1.json \
  --new response-v2.json \
  --array-as-set \
  --format json

Flags:

--old — Path to the old JSON file (required)

--new — Path to the new JSON file (required)

--array-as-set — Compare arrays as sets (ignore order)

--ignore — JSON paths to ignore (comma-separated)

--format — Output format: text or json

Traffic Proxy

Deploy the Diffsurge proxy to capture production traffic. It runs as a reverse proxy, sampling request/response pairs with automatic PII redaction.

docker run -d \
  -e TVC_STORAGE_POSTGRES_URL=postgresql://... \
  -e TVC_STORAGE_REDIS_URL=rediss://... \
  -p 8081:8080 \
  equixankit/diffsurge-proxy

The proxy adds less than 5ms of latency at p95. It uses async buffering so the forwarding path is never blocked by storage I/O. Configure sampling rates to capture 1-100% of traffic.

Replay Engine

Replay captured traffic against a target server and compare every response semantically.

surge replay \
  --source traffic.json \
  --target http://staging.example.com \
  --workers 20 \
  --rate-limit 500 \
  --format json \
  --output drift-report.json

Flags:

--source — Traffic JSON file (required)

--target — Target server URL (required)

--workers — Concurrent workers (default: 10)

--rate-limit — Max requests per second (0 = unlimited)

--timeout — Per-request timeout (default: 30s)

--max-retries — Max retries per request (default: 2)

CI/CD Integration

Add Diffsurge to your CI/CD pipeline to automatically block deploys with breaking changes.

GitHub Actions:

# .github/workflows/api-check.yml
name: API Schema Check
on: [pull_request]

jobs:
  schema-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Surge CLI
        run: npm install -g diffsurge

      - name: Check for breaking changes
        run: |
          surge schema diff \
            --old api/schema-main.yaml \
            --new api/schema.yaml \
            --fail-on-breaking

The CLI returns standard exit codes so your pipeline blocks automatically: 0 = clean, 1 = breaking changes, 2 = error.