proxy-record

# proxy-record skill

Use this skill when the user wants to:
- Capture HTTP or HTTPS traffic from an application
- Create named recording sessions for different test scenarios
- Configure which hosts to record via proxy.yaml
- Set up HTTPS interception with the local CA

## Starting the proxy (record mode)

```bash
dpr start
```

Default output on startup:
- Proxy: http://127.0.0.1:8080
- Web UI: http://127.0.0.1:3400
- Mode: RECORD
- Session: today's date (auto-created)

## Configuring routes (proxy.yaml)

```yaml
routes:
  - match: "api.stripe.com"
    upstream: https://api.stripe.com
    record: true
    replay: true

  - match: "api.sendgrid.com"
    upstream: https://api.sendgrid.com
    record: true
    replay: true

  # Catch-all for any unmatched host
  - match: "*"
    upstream: ""      # pass through without recording
    record: false
    replay: false
```

`match` is an exact hostname or hostname:port. Subdomains are matched if the host ends with `.match`.

## Named sessions

Each recording is grouped into a session. Create named sessions for different scenarios:

```bash
# Create a new session
dpr sessions new stripe-checkout-flow

# List all sessions
dpr sessions

# The session name also sets the active session context
```

Via API:
```
POST /api/sessions
{ "name": "stripe-checkout-flow" }
```

## Configuring your client

### curl
```bash
curl -x http://127.0.0.1:8080 https://api.stripe.com/v1/customers \
  -H "Authorization: Bearer sk_test_..."
```

### Node.js (global proxy env vars)
```bash
HTTP_PROXY=http://127.0.0.1:8080 \
HTTPS_PROXY=http://127.0.0.1:8080 \
node your-app.js
```

### Node.js (axios)
```javascript
const axios = require('axios');
const { HttpProxyAgent } = require('http-proxy-agent');
const { HttpsProxyAgent } = require('https-proxy-agent');

const agent = new HttpsProxyAgent('http://127.0.0.1:8080');
const res = await axios.get('https://api.stripe.com/v1/customers', {
  httpsAgent: agent,
});
```

## HTTPS interception

Required to record HTTPS traffic:

1. Generate and trust the local CA:
```bash
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ~/.dpr/ca.crt
```

2. The CA cert path is `~/.dpr/ca.crt`. Generated automatically on first `dpr start`.

3. For Node.js, you may also need:
```bash
NODE_EXTRA_CA_CERTS=~/.dpr/ca.crt node app.js
```

## Exporting recordings

```bash
# Export as HAR file (stdout)
dpr export stripe-checkout-flow

# Save to file
dpr export stripe-checkout-flow > session.har
```

Or in web UI: Session detail -> Export HAR button.

## Environment variables

```
DPR_PROXY_PORT=8080        Proxy port
DPR_API_PORT=3400          Management API port
DPR_SESSION=my-session     Active session name
DPR_WEB_ENABLED=1          1=show web UI
```