Echoproof

Echoproof

Bahasa Indonesia | English

Verifikasi perilaku API untuk setiap perubahan kode, berdasarkan traffic nyata.

Echoproof merekam request dan response asli dari service Anda, memutarnya ulang ke build hasil perubahan kode, lalu melaporkan apa yang berubah, di endpoint dan field mana, pada berapa persen request, dan apakah perubahan itu memang diniatkan. Hasilnya bisa dipakai sebagai gate di CI atau langsung oleh coding agent (Claude Code, Cursor, dan sejenisnya) untuk memeriksa pekerjaannya sendiri.

record  ->  replay ke build lama dan baru  ->  diff semantik  ->  nilai terhadap niat  ->  gate

Daftar isi

• Mengapa Echoproof
• Fitur utama
• Instalasi
• Mulai cepat
• Demo
• Konsep
• Referensi perintah
• Konfigurasi
• Membaca laporan
• Integrasi CI
• Integrasi coding agent (MCP)
• Keamanan dan privasi
• Batasan
• Pengembangan
• Lisensi

Mengapa Echoproof

Saat sebagian besar kode ditulis oleh AI agent, jumlah perubahan naik jauh lebih cepat daripada kemampuan manusia untuk meninjaunya. Tes yang lulus dan diff yang tampak rapi belum menjamin perilaku sistem tetap benar, karena tes ditulis dari asumsi, sedangkan bug sering muncul dari kombinasi data nyata yang tidak terpikirkan.

Echoproof menjawab satu pertanyaan yang tidak dijawab oleh tes unit maupun code review:

Apakah perubahan ini mengubah perilaku sistem terhadap traffic nyata, dan apakah perubahan itu memang yang dimaksud?

Contoh yang ditangkap Echoproof: sebuah PR berniat "menambah field currency di katalog", tetapi tanpa sengaja salah menempatkan satu argumen. Akibatnya harga 3 dari 8 menu berubah, sementara 5 menu lainnya tetap benar. Tes unit lulus dan diff kode terlihat wajar. Echoproof melaporkan products[*].price: 18000 -> 22000 pada setiap request katalog dan menandainya sebagai regresi.

Fitur utama

• Rekam dari traffic nyata. Reverse proxy yang merekam setiap request dan response, dengan data sensitif disamarkan sebelum ditulis ke disk.
• Diff semantik. JSON dibandingkan per field, bukan per baris teks. Perubahan dikelompokkan per endpoint dan field, lalu diklasifikasikan sebagai breaking, behavior, atau additive.
• Tahan noise. UUID, timestamp, dan nilai acak dikenali otomatis. Field yang berubah sendiri antar-run dipelajari dengan me-replay build lama dua kali.
• Aman terhadap state. Request tulis tidak di-replay kecuali diizinkan per endpoint. Build lama dan baru dibandingkan di atas data yang sama, dengan perintah reset di antara setiap putaran.
• Sadar niat perubahan. Setiap kelompok perubahan bisa dinilai oleh Claude terhadap deskripsi PR atau tugas agent. Perubahan yang tidak dijelaskan oleh niat ditandai sebagai regresi.
• Siap untuk CI dan agent. Exit code untuk gate merge, laporan Markdown untuk komentar PR, JSON untuk otomasi, dan server MCP untuk coding agent.

Instalasi

Homebrew (macOS dan Linux)

brew install est57/tap/echoproof

Binary siap pakai (disarankan)

Unduh arsip untuk platform Anda dari halaman rilis, atau lewat terminal:

VERSION=v0.1.0

TARGET=aarch64-apple-darwin # atau x86_64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu curl -sLO https://github.com/est57/echoproof/releases/download/$VERSION/echoproof-$VERSION-$TARGET.tar.gz curl -sLO https://github.com/est57/echoproof/releases/download/$VERSION/echoproof-$VERSION-$TARGET.tar.gz.sha256 shasum -a 256 -c echoproof-$VERSION-$TARGET.tar.gz.sha256 tar -xzf echoproof-$VERSION-$TARGET.tar.gz sudo mv echoproof-$VERSION-$TARGET/echoproof /usr/local/bin/

echoproof --version

Dengan Cargo

Jika Rust 1.85 atau lebih baru sudah terpasang:

cargo install echoproof

Dari source code

Kebutuhan: Rust 1.85 atau lebih baru. curl diperlukan untuk menjalankan demo.

git clone https://github.com/est57/echoproof.git

cd echoproof cargo install --path crates/echoproof-cli

Binary echoproof dipasang di ~/.cargo/bin. Pastikan folder itu ada di PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

echoproof --version

Mulai cepat

Langkah berikut memeriksa sebuah perubahan kode pada service yang berjalan di lingkungan uji Anda.

1. Buat file konfigurasi (opsional, semua pengaturan punya nilai default):

echoproof init

2. Rekam traffic. Jalankan proxy di depan service, lalu arahkan aplikasi, Postman, atau tes otomatis ke alamat proxy:

echoproof record --upstream http://127.0.0.1:8000 --listen 127.0.0.1:8080 --out traffic.jsonl

Hentikan dengan Ctrl-C setelah traffic yang representatif terkumpul.

Aplikasi Laravel bisa merekam tanpa proxy dengan echoproof/laravel: jalankan composer require echoproof/laravel, isi ECHOPROOF_RECORD=true di .env, dan traffic ditulis ke storage/echoproof/traffic.jsonl dengan aturan sensor yang sama.

3. Jalankan dua build, versi sebelum perubahan (base) dan sesudahnya (PR), memakai database yang sama.

4. Bandingkan:

echoproof check -s traffic.jsonl --base http://127.0.0.1:8001 -t http://127.0.0.1:8002

5. Baca hasilnya. Exit code 0 berarti tidak ada perubahan yang tidak diharapkan, 1 berarti ada regresi, 2 berarti terjadi error. Lihat Membaca laporan.

Untuk menilai perubahan terhadap niatnya, tambahkan deskripsi PR dan diff kodenya:

git diff main...HEAD > change.diff

echoproof check -s traffic.jsonl --base http://127.0.0.1:8001 -t http://127.0.0.1:8002 \ --intent-file pr-description.md --code-diff change.diff --output echoproof-report.md

Demo

Demo lengkap berjalan sekitar 10 detik dan tidak membutuhkan service Anda sendiri:

./scripts/demo.sh

Demo memakai backend POS kecil (examples/demo-shop) yang memiliki state, yaitu stok produk yang berkurang setiap ada order. Sebuah "PR dari agent" berniat menambah field currency pada produk, tetapi juga mengubah cara diskon promo dan voucher digabungkan.

Konsep

Snapshot

Snapshot adalah file JSONL berisi satu pasangan request dan response per baris. Header dan field sensitif sudah disamarkan sebelum ditulis. Snapshot yang sama dapat dipakai berulang kali untuk memeriksa banyak PR.

Dua mode perbandingan

Pada mode base vs PR, response hasil rekaman tidak dipakai sebagai acuan. Echoproof memutar traffic yang sama ke kedua build di atas data yang sama:

reset  ->  replay ke base         ->  acuan

reset -> replay ke base lagi -> field yang berbeda dicatat sebagai noise reset -> replay ke PR -> kandidat diff acuan dan kandidat, abaikan noise

Alamat server masing-masing build (misalnya http://127.0.0.1:8001 di URL gambar atau link pagination) dinormalkan otomatis, sehingga dua build yang berjalan di port berbeda tetap sebanding.

Mode aman

Secara default, hanya method GET, HEAD, dan OPTIONS yang di-replay. Request tulis dilewati dan tidak dihitung lulus: laporan menyebut jumlahnya dan memperingatkan bahwa perilakunya belum terverifikasi.

Izinkan request tulis per endpoint, hanya terhadap lingkungan yang boleh diubah atau dapat di-reset:

echoproof check ... --allow-writes "POST /orders" --allow-writes "PUT /cart/*"

Gunakan --reset (atau replay.reset) untuk mengembalikan state sebelum setiap putaran, misalnya dengan me-restore dump database atau memanggil endpoint reset di lingkungan uji. Echoproof menolak me-replay request tulis tanpa reset bila noise sedang dipelajari, karena perubahan state di antara run akan ikut dianggap noise dan menyembunyikan regresi.

Diff semantik

• JSON dibandingkan per field. 5 dan 5.0 dianggap sama, dan urutan key diabaikan.
• Setiap perubahan diklasifikasikan:

• Path dinormalkan: /products/42 menjadi GET /products/{id}, dan items[3].price menjadi $.items[*].price. Setiap perubahan dihitung sekali per request.
• UUID, ULID, dan date-time dengan bentuk yang sama dianggap noise. Tanggal saja (misalnya 2026-10-14) tetap dibandingkan.

Niat perubahan

Ada dua cara memberi tahu Echoproof perubahan apa yang diharapkan.

--expect meloloskan semua perubahan di endpoint yang disebut. Jika sebuah PR memang mengubah katalog tetapi tanpa sengaja juga merusak harga di katalog, --expect "GET /catalog" tidak akan menangkapnya.

Dengan --intent, setiap kelompok perubahan dinilai oleh Claude dan diberi verdict intended, regression, atau unclear, beserta alasan yang mengutip nilai contoh. Bahan penilaiannya meliputi niat perubahan, diff kode (opsional), persentase request yang terdampak, contoh request yang berubah beserta nilai sebelum dan sesudah, serta contoh request di endpoint yang sama yang tidak berubah sebagai pembanding. Verdict unclear dan kelompok yang tidak dinilai diperlakukan sebagai regresi (fail closed).

Penilaian niat membutuhkan API key Anthropic. Satu run melakukan satu panggilan API, dan hanya jika ada perubahan. Biaya tipikal sekitar USD 0,01 sampai 0,02 per run dengan model default.

Panggilan ke pihak ketiga

Service yang memanggil payment gateway, layanan pesan, atau API lain tidak boleh benar-benar menghubunginya saat replay. Dengan echoproof/laravel, panggilan itu direkam bersama setiap request, dan build yang dijalankan dengan ECHOPROOF_REPLAY=true menjawabnya dari rekaman serta memblokir semua pangg