or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

body-processing.mderror-handling.mdfiltering.mdindex.mdnetwork-configuration.mdpath-resolution.mdrequest-modification.mdresponse-processing.md
tile.json

index.mddocs/

Express HTTP Proxy

Express HTTP Proxy is a middleware for Express.js that enables proxying HTTP requests to another host and passing the response back to the original caller. It provides comprehensive request and response modification capabilities through customizable decorators, supports both streaming and buffering modes for optimal performance, and implements Promise-based asynchronous operations throughout the workflow.

Package Information

  • Package Name: express-http-proxy
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install express-http-proxy

Core Imports

const proxy = require('express-http-proxy');

ES6 import (CommonJS module):

import proxy from 'express-http-proxy';

Basic Usage

const express = require('express');
const proxy = require('express-http-proxy');

const app = express();

// Basic proxy setup
app.use('/api', proxy('https://api.example.com'));

// Proxy with options
app.use('/proxy', proxy('www.google.com', {
  proxyReqPathResolver: function (req) {
    return req.url;
  },
  userResDecorator: function(proxyRes, proxyResData, userReq, userRes) {
    // Modify response before sending to client
    return proxyResData;
  }
}));

app.listen(3000);

Architecture

Express HTTP Proxy processes requests through a well-defined pipeline of discrete steps:

  • Request Filtering: Determine whether to proxy the request
  • Request Building: Construct the proxy request object
  • Host Resolution: Resolve the target proxy host
  • Request Decoration: Apply request modifications and headers
  • Path Resolution: Determine the final request path
  • Body Processing: Handle request body encoding and transformation
  • Proxy Execution: Send the request and receive response
  • Response Processing: Apply response modifications and headers
  • Client Response: Send the final response to the original client

The library supports both streaming mode (default) for optimal performance and buffering mode when response modification is required.

Capabilities

Core Proxy Function

The main export function that creates Express middleware for HTTP proxying.

/**
 * Creates Express middleware for proxying HTTP requests
 * @param {string|function} host - Target host URL or function returning host URL
 * @param {object} [options] - Configuration options
 * @returns {function} Express middleware function (req, res, next) => void
 */
function proxy(host, options);

Request Path Resolution

Control how request paths are resolved before proxying, with support for dynamic path modification and Promise-based async operations.

interface PathResolverOptions {
  /** Function to resolve request path before proxying (supports Promises) */
  proxyReqPathResolver?: (req) => string | Promise<string>;
}

Request Path Resolution

Request Modification

Comprehensive request modification capabilities including headers, body, and HTTP options.

interface RequestModificationOptions {
  /** Modify request options before sending (supports Promises) */
  proxyReqOptDecorator?: (proxyReqOpts, srcReq) => object | Promise<object>;
  /** Modify request body before sending (supports Promises) */
  proxyReqBodyDecorator?: (bodyContent, srcReq) => any | Promise<any>;
}

Request Modification

Response Processing

Modify proxy responses before sending to the client, including headers and body transformation.

interface ResponseProcessingOptions {
  /** Modify response data before sending to client (supports Promises) */
  userResDecorator?: (proxyRes, proxyResData, userReq, userRes) => any | Promise<any>;
  /** Modify response headers */
  userResHeaderDecorator?: (headers, userReq, userRes, proxyReq, proxyRes) => object;
}

Response Processing

Request Filtering

Control which requests get proxied using filter functions and conditional logic.

interface FilteringOptions {
  /** Determine whether to proxy the request (supports Promises) */
  filter?: (req, res) => boolean | Promise<boolean>;
  /** Inspect proxy response and decide whether to continue processing (supports Promises) */
  skipToNextHandlerFilter?: (proxyRes) => boolean | Promise<boolean>;
}

Request Filtering

Body Processing Configuration

Control how request bodies are parsed, encoded, and handled during proxying.

interface BodyProcessingOptions {
  /** Whether to parse request body (default: true) */
  parseReqBody?: boolean;
  /** Encode request body as Node Buffer (default: false) */
  reqAsBuffer?: boolean;
  /** Encoding for request body parsing (default: 'utf-8') */
  reqBodyEncoding?: string | null;
  /** Body size limit (default: '1mb') */
  limit?: string;
}

Body Processing

Network Configuration

Configure network-related options including HTTPS, ports, timeouts, and headers.

interface NetworkOptions {
  /** Force HTTPS for proxy request */
  https?: boolean;
  /** Specific port for proxy request */
  port?: number;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Additional headers to add to proxy request */
  headers?: object;
  /** Copy host header to proxied request */
  preserveHostHdr?: boolean;
}

Network Configuration

Error Handling

Customize error handling behavior for proxy failures and network issues.

interface ErrorHandlingOptions {
  /** Custom error handler for proxy errors */
  proxyErrorHandler?: (err, res, next) => void;
}

Error Handling

Host Configuration

Control how proxy host resolution is cached between requests for optimal performance.

/**
 * Whether to memoize (cache) host resolution between requests
 * @type {boolean}
 * @default true
 */
memoizeHost?: boolean;

When true, the host argument is parsed once on the first request and cached for subsequent requests. When false, the host is parsed on every request, allowing for dynamic host selection.

Session Handling

Control how Express session data is preserved during proxying operations.

/**
 * Preserve request session data on proxy request
 * @type {boolean}
 * @default false
 */
preserveReqSession?: boolean;

When enabled, the original request's session data is passed through to the proxy request object.

Types

interface HostConfigOptions {
  /** Whether to memoize host resolution (default: true) */
  memoizeHost?: boolean;
}

interface SessionOptions {
  /** Preserve request session data on proxy request */
  preserveReqSession?: boolean;
}

interface ProxyOptions extends 
  PathResolverOptions,
  RequestModificationOptions, 
  ResponseProcessingOptions,
  FilteringOptions,
  BodyProcessingOptions,
  NetworkOptions,
  ErrorHandlingOptions,
  HostConfigOptions,
  SessionOptions {
}