request-scope-api

Zero-friction API request observability for Express.js applications.

request-scope-api captures HTTP requests and responses, stores them in your database, and provides a dashboard for inspection. It's designed to be production-ready with minimal configuration and zero performance impact on your application.

Installation

npm install request-scope-api

Quick Start

Installation Order

Important: The setup() function should be called after body parser middleware (like express.json()) and before your route definitions. This ensures the request body is already parsed when the package attempts to capture it.

import express from 'express';
import { setup } from 'request-scope-api';

const app = express();

// 1. Body parser middleware (REQUIRED)
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// 2. RequestScope setup (AFTER body parser, BEFORE routes)
setup(app, {
  mode: 'development',
  storage: {
    type: 'mongodb',
    uri: 'mongodb://localhost:27017/myapp'
  }
});

// 3. Your routes (AFTER RequestScope setup)
app.get('/api/users', (req, res) => {
  res.json({ message: 'Hello' });
});

app.listen(3000);

MongoDB

import express from 'express';
import { setup } from 'request-scope-api';

const app = express();

setup(app, {
  mode: 'development', // or 'production' to disable tracking
  storage: {
    type: 'mongodb',
    uri: 'mongodb://localhost:27017/myapp'
  }
});

app.listen(3000);

MySQL

import express from 'express';
import { setup } from 'request-scope-api';

const app = express();

setup(app, {
  mode: 'development', // or 'production' to disable tracking
  storage: {
    type: 'mysql',
    host: 'localhost',
    port: 3306,
    database: 'truck_match_live_leatest',
    username: 'root',
    password: ''
  },
  retentionDays: 30,
  ignore: ['/health', '/favicon.ico'],
  maskFields: ['password']
});

app.listen(3000);

PostgreSQL

import express from 'express';
import { setup } from 'request-scope-api';

const app = express();

setup(app, {
  mode: 'development', // or 'production' to disable tracking
  storage: {
    type: 'postgresql',
    host: 'localhost',
    port: 5432,
    database: 'myapp',
    username: 'user',
    password: 'pass'
  }
});

app.listen(3000);

Features

• Zero Configuration: Works out of the box with sensible defaults
• Multiple Storage Backends: MongoDB, MySQL, PostgreSQL support
• Automatic Retention: Configurable data retention with automatic cleanup
• Sensitive Field Masking: Built-in masking for passwords, tokens, and API keys
• Request/Response Body Capture: Captures full request and response bodies (with size limits)
• Error Tracking: Captures error messages and stack traces
• Performance Metrics: Records response time and body sizes
• Dashboard UI: Web interface for browsing and filtering requests
• Basic Auth: Optional authentication for dashboard access
• Production Mode: Completely disables tracking in production for security and performance

Mode Configuration

The package supports two modes: development and production.

Development Mode (Default)

• Enables all request tracking, logging, and data collection
• Runs retention scheduler and background processing
• Dashboard is accessible
• Ideal for local development and testing

Production Mode

• Completely disables request tracking and data collection
• No database connections are established
• No background services or retention jobs run
• Dashboard is disabled
• Acts as a no-op middleware for security and performance

// Development mode (default)
setup(app, {
  mode: 'development',
  storage: { /* ... */ }
});

// Production mode - tracking disabled
setup(app, {
  mode: 'production',
  storage: { /* ... */ }
});

Note: In production mode, the package does not establish any database connections and has zero performance impact on your application.

Sensitive Field Masking

request-scope-api automatically masks sensitive fields in request headers, request body, and response headers. Built-in sensitive field names (case-insensitive):

• password
• token
• authorization
• apiKey
• secret

Add custom fields to mask via the maskFields configuration:

setup(app, {
  storage: { /* ... */ },
  maskFields: ['creditCard', 'ssn', 'apiKey']
});

Ignoring Paths

Skip capture for specific URL paths:

setup(app, {
  storage: { /* ... */ },
  ignore: ['/health', '/metrics', '/favicon.ico']
});

Error Handling

To capture error data, use the provided error middleware:

import { setup, errorHandler } from 'request-scope-api';

setup(app, { /* ... */ });  
app.use(errorHandler);

// Your routes
app.get('/api/users', async (req, res, next) => {
  try {
    // ...
  } catch (err) {
    next(err); // Error will be captured
  }
});