proxy-replay

name	proxy-replay
description	Replay recorded HTTP/HTTPS traffic using dev-proxy-recorder. Covers starting replay mode, selecting sessions, miss handling, and switching between record and replay.

proxy-replay skill

Use this skill when the user wants to:

• Run tests without hitting external APIs
• Replay previously recorded responses
• Debug why a replayed request returns a 502 (miss)
• Switch between record and replay mode

Starting replay mode

# Replay from the most recent session
dpr start --replay

# Replay from a specific session
dpr start --replay --session stripe-checkout-flow

# Or by session ID
dpr start --replay --session 2

In replay mode: no upstream connections are made. All responses come from the SQLite database.

Replay matching logic

For each incoming request, the proxy looks up a match in the active session:

1. Exact match: method + url + SHA-256(request body) - strongest match
2. Fuzzy fallback: method + url ignoring body - used when body hash does not match
3. Returns the most recently recorded match within the session

If no match is found: returns 502 {"error":"no recording found","method":"POST","url":"https://api.stripe.com/v1/refunds"}

Handling misses

A miss means a request was made that was never recorded in the chosen session.

To fix:

1. Switch back to record mode and make the missing request
2. Then switch back to replay

Via web UI (Settings > Proxy mode) or environment:

DPR_REPLAY=0 dpr start     # record mode
DPR_REPLAY=1 dpr start     # replay mode

Via API:

POST /api/mode
{ "replay": true, "sessionId": 1 }

Switching mode at runtime

Via the web UI dashboard Settings page: toggle between RECORD and REPLAY without restarting.

Via CLI:

# Check current status
curl http://localhost:3400/api/status
# {"mode":"replay","sessionId":1,"sessionName":"stripe-checkout-flow","requestCount":48}

Using replay in tests

Jest / Vitest example

import { beforeAll, afterAll } from 'vitest';
import { execSync } from 'child_process';

let dprProcess;

beforeAll(() => {
  // Start replay proxy in background
  dprProcess = require('child_process').spawn('node', [
    'dist/dpr.js', 'start', '--replay', '--session', 'stripe-checkout-flow',
    '--no-web'
  ], { detached: true });

  // Point app at proxy
  process.env.HTTP_PROXY = 'http://127.0.0.1:8080';
  process.env.HTTPS_PROXY = 'http://127.0.0.1:8080';
});

afterAll(() => {
  dprProcess.kill();
});

Replay response fidelity

Replayed responses include:

• Original HTTP status code and status text
• All original response headers (Content-Type, etc.)
• Original response body (exact bytes)
• Response time: ~1ms (not the original upstream latency)

The X-DPR-Replay: true header is added to all replayed responses so your app can detect replay mode if needed.

Selecting which session to replay

Via CLI flag: --session <name-or-id>

Via env var: DPR_REPLAY_SESSION=stripe-checkout-flow

Default: the most recently created session.

Replay mode in CI

# .github/workflows/test.yml
- name: Start replay proxy
  run: |
    DPR_REPLAY=1 DPR_REPLAY_SESSION=ci-fixtures \
    DPR_WEB_ENABLED=0 node dist/dpr.js start &
    sleep 1  # wait for proxy to bind

- name: Run tests
  run: pnpm test
  env:
    HTTPS_PROXY: http://127.0.0.1:8080
    NODE_EXTRA_CA_CERTS: ~/.dpr/ca.crt