proxy-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

```bash
# 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:
```bash
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:
```bash
# 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

```javascript
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

```yaml
# .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
```