Request Replay Debugger

A modular debugging tool that captures and replays HTTP requests for Node.js frameworks. Perfect for debugging API endpoints during development.

Features

• 🎯 Framework Agnostic: Abstract base class with framework-specific implementations
• 📊 Web UI: Clean interface to view and replay requests
• ⚡ Real-time Updates: Live request capture with Server-Sent Events
• 🔍 Filtering: Search and filter by method, URL, status code
• 📋 Request Details: View headers, body, query params, and response comparison
• ⚙️ Configurable: Ignore static files, specific paths, set request limits
• 🔄 One-click Replay: Replay any captured request with a button click

Installation

npm install request-replay-debugger

Quick Start

Express.js

const express = require('express');
const { Express } = require('request-replay-debugger');

const app = express();
app.use(express.json());

// Create recorder instance
const recorder = new Express({
  uiPort: 3001,
  maxRequests: 100,
  ignoreStatic: true,
  ignorePaths: ['/health']
});

// Add middleware to capture requests
app.use(recorder.middleware());

// Your routes
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  
  // Start the UI server
  recorder.startUI().then(() => {
    console.log('Replay UI at http://localhost:3001');
  });
});

Configuration

const recorder = new Express({
  uiPort: 3001,           // Port for the UI server
  maxRequests: 100,       // Maximum requests to store
  ignoreStatic: true,     // Ignore .css, .js, .png, etc.
  ignorePaths: ['/health', '/metrics'], // Paths to ignore
  baseUrl: 'http://localhost:3000',     // Base URL for replays
  enableUI: true          // Enable/disable UI server
});

API

Express Class

const recorder = new Express(config);

// Middleware function
app.use(recorder.middleware());

// Start UI server
await recorder.startUI();

// Stop UI server
recorder.stopUI();

// Get all requests
const requests = recorder.getRequests();

// Get specific request
const request = recorder.getRequest(id);

// Replay request
const result = await recorder.replayRequest(id);

// Clear all requests
recorder.clearRequests();

Events

// Listen for new requests
recorder.on('requestRecorded', (request) => {
  console.log('New request:', request.method, request.url);
});

// Listen for replayed requests
recorder.on('requestReplayed', ({ id, replayResponse }) => {
  console.log('Request replayed:', id);
});

// Listen for cleared requests
recorder.on('requestsCleared', () => {
  console.log('All requests cleared');
});

UI Features

• Request Table: View all captured requests with timestamps
• Search & Filter: Find requests by URL or HTTP method
• One-click Replay: Replay any request and see the response
• Request Details: View headers, body, query parameters
• Response Comparison: Compare original vs replayed responses
• Real-time Updates: New requests appear automatically

Extending for Other Frameworks

Create a new framework implementation by extending BaseRecorder:

const { BaseRecorder } = require('request-replay-debugger');

class MyFramework extends BaseRecorder {
  constructor(config) {
    super(config);
  }

  middleware() {
    return (req, res, next) => {
      // Capture request details
      const record = this.recordRequest(
        req.method,
        req.url,
        req.headers,
        req.body,
        req.query,
        // Optional: original response
        {
          statusCode: res.statusCode,
          headers: res.headers,
          body: responseBody
        }
      );
      
      next();
    };
  }
}

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm run test

# Run linting
npm run lint

# Type checking
npm run typecheck

Example

Check out the complete example in examples/express-example/:

cd examples/express-example
npm install
npm start

Then visit:

• http://localhost:3000 - Your Express app
• http://localhost:3001 - Request Replay UI

License

MIT