Rewind User Guide

Getting Started

Setup

1. Start MongoDB

   mongod --dbpath /path/to/data

2. Start Backend API (requires admin for capture)

   cd services/backend-api
   sudo bun run dev

3. Start Frontend

   cd services/frontend
   bun run dev

4. Open http://localhost:5173

---

Dashboard

The main dashboard displays all captured HTTP sessions with:

• Method, URI, status code, source/destination IPs
• Real-time updates via WebSocket
• Color-coded status indicators (2xx green, 3xx blue, 4xx yellow, 5xx red)
• Pending badge for sessions without responses

---

Search & Filtering

Simple Search

Type in the search bar to filter by method, URI, IP, or status code.

Advanced Filters

Click Filters to filter by HTTP method and status range dropdowns.

RQL (Rewind Query Language)

Switch to RQL mode for expressive queries:

method == "GET" AND status >= 400
uri contains "/api" AND ip.src == "192.168.1.0/24"
status == 5xx OR response_time > 2000
NOT method == "OPTIONS"
host startswith "api."
port.dst == 443

Fields: method, status, uri, host, ip.src, ip.dst, port.src, port.dst, timestamp

Operators: ==, !=, >, <, >=, <=, contains, matches, startswith

Logical: AND, OR, NOT

Special values: Status ranges (2xx, 5xx), CIDR notation (192.168.1.0/24), durations

RQL can also be used via the CLI: bun run src/cli.ts query 'status >= 400'

---

Session Details

Click any session to view:

• Request - Method, URI, headers, body, query params, cookies
• Response - Status, headers, body
• Actions - Replay request, copy as cURL, delete

---

Capture Management

Controls

• Start - Launch the C++ capture agent
• Stop - Graceful shutdown (SIGTERM with SIGKILL fallback)
• Restart - Stop and restart the agent

In-Browser Terminal

Real-time log output from the capture agent with interactive interface selection.

Capture Filters

Configure host and URI patterns in services/capture-agent/config/config.yaml to selectively capture traffic. Patterns use regex matching.

---

Captures

Navigate to /captures to view sessions grouped by capture run.

Each capture run shows:

• Session count
• Duration
• Start time
• Capture session ID

Click a capture run to view its sessions and export them.

Export

From a capture run detail page, export all sessions in:

• HAR - For Chrome DevTools, Postman
• JSON - Raw session data
• CSV - For Excel, Google Sheets

---

Alerts

Creating Rules

1. Go to Alerts page
2. Click Create Alert Rule
3. Set name, severity (info/warning/error/critical), and cooldown
4. Add conditions (all must match):

Condition	Operators	Example
Status Code	equals, not_equals, greater_than, less_than	500
Status Range	equals	5xx
Response Time	greater_than, less_than	2000 (ms)
HTTP Method	equals, not_equals	POST
URL Pattern	contains, regex	/api/users

Managing Rules

• Toggle enable/disable
• Edit conditions
• Delete rules

---

Notifications

When an alert triggers:

1. Notification stored in database
2. Appears in UI via WebSocket
3. Sent to configured channels (Email, Slack, Discord)

Notification Channels

Email - SMTP-based with HTML templates. Configure in .env:

EMAIL_ENABLED=true
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=your-email@gmail.com
EMAIL_SMTP_PASS=app-password
EMAIL_RECIPIENT=admin@example.com

Slack - Webhook-based with formatted messages:

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

Discord - Webhook-based with embeds:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

See EMAIL_SETUP_GUIDE.md for detailed email setup.

---

SDK & CLI

The @rewind/sdk package (packages/sdk/) provides a CLI and TypeScript client for interacting with the Rewind backend.

CLI Commands

cd packages/sdk

bun run src/cli.ts sessions list                    # list sessions
bun run src/cli.ts sessions list --limit 50         # paginated
bun run src/cli.ts sessions get <id>                # session details
bun run src/cli.ts sessions export -o out.json      # export to file
bun run src/cli.ts sessions export -q 'status>=400' # export filtered
bun run src/cli.ts sessions clear                   # clear all

bun run src/cli.ts query 'method == "POST"'         # RQL query
bun run src/cli.ts query 'status == 5xx' -f json    # as JSON

bun run src/cli.ts capture status                   # agent status
bun run src/cli.ts capture start                    # start agent
bun run src/cli.ts capture stop                     # stop agent
bun run src/cli.ts capture restart                  # restart

bun run src/cli.ts alerts list                      # list rules
bun run src/cli.ts alerts toggle <id>               # toggle rule
bun run src/cli.ts alerts delete <id>               # delete rule

bun run src/cli.ts stats                            # traffic stats
bun run src/cli.ts health                           # health check
bun run src/cli.ts config show                      # CLI config
bun run src/cli.ts config set url http://host:8000  # change backend URL

TypeScript Client

import { RewindClient } from '@rewind/sdk';

const client = new RewindClient({ baseUrl: 'http://localhost:8000' });
const { sessions } = await client.sessions.list();
const { sessions: filtered } = await client.sessions.query('status >= 400');
const status = await client.capture.status();

---

Request Replay

1. Open any session detail page
2. Click Replay Request
3. View the response (status, headers, body, timing)

Replays are sent from the backend server, not the browser.

---

FAQ

Why are sessions "Pending"? The request was captured but no response received yet.

Can I capture HTTPS? Rewind captures encrypted packets but cannot decrypt HTTPS without a MITM proxy.

What's the performance impact? The C++ agent is optimized for minimal overhead. The Bun backend and SvelteKit frontend are designed for real-time performance.