or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

body-processing.md error-handling.md filtering.md index.md network-configuration.md path-resolution.md request-modification.md response-processing.md

tile.json

Network Configuration

Configure network-related options for proxy requests including HTTPS enforcement, port specification, timeouts, headers, and host header preservation.

Capabilities

Force HTTPS

Force the proxy request to use HTTPS regardless of the original protocol specified in the host parameter.

/**
 * Force HTTPS for proxy request
 * @type {boolean}
 * @default false
 */
https?: boolean;

Usage Examples:

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

// Force HTTPS even if host is specified as HTTP
app.use('/secure', proxy('api.example.com', {
  https: true // Will use https://api.example.com regardless of host protocol
}));

// Mixed configuration
app.use('/mixed', proxy('legacy-api.com', {
  https: true, // Upgrade to HTTPS
  port: 8443   // Use custom HTTPS port
}));

Port Configuration

Specify a custom port for the proxy request, overriding any port specified in the host URL.

/**
 * Specific port for proxy request
 * @type {number}
 * @default undefined (uses port from host URL or protocol default)
 */
port?: number;

Usage Examples:

// Custom port for development
app.use('/dev', proxy('localhost', {
  port: 3001 // Connect to localhost:3001
}));

// Custom HTTPS port
app.use('/custom-https', proxy('secure-api.com', {
  https: true,
  port: 8443 // Use custom HTTPS port
}));

// Load balancer port
app.use('/lb', proxy('load-balancer.internal', {
  port: 8080 // Internal load balancer port
}));

Request Timeout

Set a timeout for proxy requests in milliseconds. Timed-out requests will respond with a 504 status code and an X-Timeout-Reason header.

/**
 * Request timeout in milliseconds
 * @type {number}
 * @default undefined (no timeout, uses Node.js default)
 */
timeout?: number;

Usage Examples:

// Short timeout for fast APIs
app.use('/fast', proxy('fast-api.com', {
  timeout: 2000 // 2 seconds
}));

// Long timeout for slow operations
app.use('/slow', proxy('slow-service.com', {
  timeout: 30000 // 30 seconds
}));

// Critical service with reasonable timeout
app.use('/critical', proxy('critical-service.com', {
  timeout: 5000 // 5 seconds
}));

Additional Headers

Add custom headers to all proxy requests. These headers will be merged with existing request headers.

/**
 * Additional headers to add to proxy request
 * @type {object}
 * @default undefined
 */
headers?: object;

Usage Examples:

// API key authentication
app.use('/authenticated', proxy('secure-api.com', {
  headers: {
    'X-API-Key': process.env.API_KEY,
    'X-Client-Version': '2.1.1'
  }
}));

// Service identification
app.use('/service', proxy('backend.example.com', {
  headers: {
    'X-Forwarded-By': 'express-http-proxy',
    'X-Service-Name': 'web-frontend',
    'User-Agent': 'MyApp/1.0'
  }
}));

// Custom authentication
app.use('/custom-auth', proxy('auth-service.com', {
  headers: {
    'Authorization': 'Bearer ' + process.env.SERVICE_TOKEN,
    'X-Request-Source': 'proxy-middleware'
  }
}));

Preserve Host Header

Copy the original Host header from the incoming request to the proxied request.

/**
 * Copy host header to proxied request
 * @type {boolean}
 * @default false
 */
preserveHostHdr?: boolean;

Usage Examples:

// Preserve original host for virtual hosting
app.use('/vhost', proxy('backend-cluster.internal', {
  preserveHostHdr: true // Backend can route based on original Host header
}));

// Multi-tenant application
app.use('/tenant', proxy('multi-tenant-service.com', {
  preserveHostHdr: true, // Tenant identified by Host header
  headers: {
    'X-Tenant-Routing': 'enabled'
  }
}));

Advanced Network Configuration

Dynamic Headers Based on Request

app.use('/dynamic', proxy('api.example.com', {
  proxyReqOptDecorator: function(proxyReqOpts, srcReq) {
    // Dynamic headers based on request
    proxyReqOpts.headers['X-User-ID'] = srcReq.user?.id || 'anonymous';
    proxyReqOpts.headers['X-Request-Time'] = new Date().toISOString();
    proxyReqOpts.headers['X-Client-IP'] = srcReq.ip;
    
    return proxyReqOpts;
  },
  
  // Static headers
  headers: {
    'X-Service': 'frontend-proxy',
    'X-Version': '2.1.1'
  }
}));

Environment-Based Configuration

// Development vs Production configuration
const networkConfig = process.env.NODE_ENV === 'production' 
  ? {
      https: true,
      port: 443,
      timeout: 10000,
      headers: {
        'X-Environment': 'production',
        'X-API-Key': process.env.PROD_API_KEY
      }
    }
  : {
      https: false,
      port: 3001,
      timeout: 30000, // Longer timeout for development
      headers: {
        'X-Environment': 'development',
        'X-Debug': 'true'
      }
    };

app.use('/api', proxy('api.example.com', networkConfig));

Load Balancer Configuration

// Multiple backend servers with round-robin
const backends = ['backend1.com', 'backend2.com', 'backend3.com'];
let currentBackend = 0;

app.use('/lb', proxy(function() {
  const host = backends[currentBackend];
  currentBackend = (currentBackend + 1) % backends.length;
  return host;
}, {
  port: 8080,
  timeout: 5000,
  headers: {
    'X-Forwarded-By': 'load-balancer',
    'X-Backend-Pool': 'primary'
  },
  memoizeHost: false // Don't cache the host selection
}));

Timeout Handling

Timeout Response

When a timeout occurs, express-http-proxy will:

Return HTTP status code 504 Gateway Timeout
Add the header X-Timeout-Reason with details
Terminate the connection

Custom Timeout Handling

app.use('/timeout-handling', proxy('slow-service.com', {
  timeout: 5000,
  
  proxyErrorHandler: function(err, res, next) {
    if (err.code === 'ETIMEDOUT' || err.code === 'ESOCKETTIMEDOUT') {
      res.status(504).json({
        error: 'Service timeout',
        message: 'The upstream service took too long to respond',
        timeout: 5000
      });
    } else {
      next(err);
    }
  }
}));

Security Considerations

Header Security

app.use('/secure', proxy('api.example.com', {
  headers: {
    'X-Forwarded-Proto': 'https',
    'X-Content-Type-Options': 'nosniff'
  },
  
  proxyReqOptDecorator: function(proxyReqOpts, srcReq) {
    // Remove sensitive headers
    delete proxyReqOpts.headers['x-internal-token'];
    delete proxyReqOpts.headers['x-admin-key'];
    
    // Add security headers
    proxyReqOpts.headers['X-Request-ID'] = generateRequestId();
    
    return proxyReqOpts;
  }
}));

HTTPS Enforcement

// Enforce HTTPS in production
app.use('/production', proxy('api.example.com', {
  https: process.env.NODE_ENV === 'production',
  
  proxyReqOptDecorator: function(proxyReqOpts, srcReq) {
    // Add security headers in production
    if (process.env.NODE_ENV === 'production') {
      proxyReqOpts.headers['Strict-Transport-Security'] = 'max-age=31536000';
    }
    
    return proxyReqOpts;
  }
}));

Performance Optimization

Connection Reuse

// Configure for high-performance scenarios
app.use('/high-perf', proxy('fast-api.com', {
  timeout: 2000, // Short timeout for fast responses
  
  // Use static headers for better performance
  headers: {
    'Connection': 'keep-alive',
    'X-Service': 'frontend'
  },
  
  // Avoid header manipulation in hot path
  preserveHostHdr: false
}));

Monitoring and Metrics

app.use('/monitored', proxy('api.example.com', {
  timeout: 10000,
  
  proxyReqOptDecorator: function(proxyReqOpts, srcReq) {
    // Add timing information
    srcReq.proxyStartTime = Date.now();
    
    proxyReqOpts.headers['X-Request-Start'] = srcReq.proxyStartTime;
    
    return proxyReqOpts;
  },
  
  userResHeaderDecorator: function(headers, userReq, userRes, proxyReq, proxyRes) {
    // Add response timing
    const duration = Date.now() - userReq.proxyStartTime;
    headers['X-Response-Time'] = duration + 'ms';
    
    return headers;
  }
}));

Version

Tile

Files