Configuration

Learn how to configure the Proxy package.

Configuration Formats

The Proxy supports two configuration formats:

1. coreGroups (Recommended) - Group routes by monolith server
2. cores (Legacy) - Flat list of core configurations

Core Groups (Recommended)

The coreGroups format organizes routes by the serverless-monolith server they belong to:

import { ProxyServer } from '@serverless-monolith/proxy';

const proxy = new ProxyServer({
  port: 5454,
  cors: true,
  logRequests: true,
  coreGroups: [
    {
      coreName: 'serverless-sst',
      baseUrl: 'http://localhost:4005',
      routes: [
        {
          name: 'scheduling-imports',
          pathPrefix: '/api/http/scheduling-imports/',
          timeout: 30000,
        },
        {
          name: 'documents',
          pathPrefix: '/api/http/documents/',
        },
        {
          name: 'global',
          routeByPath: {
            'v2/employee': {
              pathPrefix: '/api/http/employee/',
              preserveMatchedPath: true,
            },
            '': {
              pathPrefix: '/api/http/global/',
            },
          },
        },
      ],
    },
    {
      coreName: 'serverless-onboarding',
      baseUrl: 'http://localhost:4006',
      routes: [
        {
          name: 'company',
          pathPrefix: '/api/http/company/',
        },
        {
          name: 'employee',
          pathPrefix: '/api/http/employee/',
        },
      ],
    },
  ],
});

CoreGroup Options

Option	Type	Required	Description
coreName	string	✓	Name of the monolith server (e.g., 'serverless-sst')
baseUrl	string	✓	Base URL of the server (e.g., 'http://localhost:4005')
routes	RouteConfig[]	✓	Array of route configurations

Route Options (within CoreGroup)

Option	Type	Required	Description
name	string	✓	Route name (becomes the path: /name/*)
pathPrefix	string		Path prefix to add to backend URL
timeout	number		Request timeout in milliseconds
headers	object		Custom headers to add to requests
routeByPath	object		Advanced path-based sub-routing
aliases	string[]		Alternative route names

RouteByPath within CoreGroup

When using routeByPath inside a CoreGroup route, paths are relative to the baseUrl:

{
  coreName: 'serverless-sst',
  baseUrl: 'http://localhost:4005',
  routes: [
    {
      name: 'global',
      routeByPath: {
        'v2/employee': {
          pathPrefix: '/api/http/employee/',  // Relative to baseUrl
          preserveMatchedPath: true,
        },
        'company-exam': {
          pathPrefix: '/api/http/company-exam-applications/',
          fallbackUrls: ['http://localhost:4006/api/http/company-exam/'],
        },
        '': {
          pathPrefix: '/api/http/global/',  // Catch-all
        },
      },
    },
  ],
}

Complete CoreGroup Example

const proxy = new ProxyServer({
  port: 5454,
  cors: true,
  defaultTimeout: 30000,
  coreGroups: [
    {
      coreName: 'serverless-sst',
      baseUrl: 'http://localhost:4005',
      routes: [
        // Simple route
        {
          name: 'scheduling-imports',
          pathPrefix: '/api/http/scheduling-imports/',
        },
        // Route with aliases
        {
          name: 'documents',
          aliases: ['docs', 'files'],
          pathPrefix: '/api/http/documents/',
        },
        // Complex routing
        {
          name: 'global',
          routeByPath: {
            'v2/employee': {
              pathPrefix: '/api/http/employee/',
              preserveMatchedPath: true,
              transformPath: (path) => path.replace('/v2/', '/'),
            },
            'scheduling': {
              pathPrefix: '/api/http/scheduling/',
              timeout: 60000,
            },
            '': {
              pathPrefix: '/api/http/global/',
            },
          },
        },
      ],
    },
    {
      coreName: 'serverless-onboarding',
      baseUrl: 'http://localhost:4006',
      routes: [
        {
          name: 'company',
          pathPrefix: '/api/http/company/',
        },
        {
          name: 'employee',
          pathPrefix: '/api/http/employee/',
          fallbackUrls: [
            'http://localhost:4005/api/http/employee/',
          ],
        },
      ],
    },
  ],
});

---

Cores (Legacy Format)

The cores format is still supported but coreGroups is recommended:

const proxy = new ProxyServer({
  port: 5454,
  cors: true,
  cores: [
    {
      name: 'my-service',
      url: 'http://localhost:4005/api/http/',
      pathPrefix: '/api',
    },
  ],
});

Core Options

Option	Type	Required	Description
name	string	✓	Core identifier
url	string	✓	Backend URL
pathPrefix	string		Path prefix to match
timeout	number		Override default timeout
fallbackUrls	string[]		Fallback URLs on failure
routeByPath	object		Advanced path-based routing
aliases	string[]		Alternative names
targets	CoreTarget[]		Multiple targets for load balancing
loadBalanceStrategy	string		'round-robin', 'failover', or 'random'

---

Server Options

Option	Type	Default	Description
port	number	5454	Proxy server port
cors	boolean | CorsOptions	true	CORS configuration
logRequests	boolean	true	Log incoming requests
defaultTimeout	number	30000	Default request timeout (ms)
prefix	string	''	Global route prefix

CORS Configuration

Simple CORS

{
  cors: true  // Allow all origins
}

Advanced CORS

{
  cors: {
    origin: ['https://app.example.com', 'http://localhost:3000'],
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization'],
    credentials: true,
    maxAge: 86400,
  }
}

SQS Configuration

Enable SQS routing through the proxy:

{
  sqs: {
    enabled: true,
    refreshInterval: 30000,      // Refresh queues every 30s
    enableManagementRoutes: true, // Enable /sqs/* routes
    routePrefix: '/sqs',
    discoveryTimeout: 5000,
  }
}

SQS Options

Option	Type	Default	Description
enabled	boolean	false	Enable SQS routing
refreshInterval	number	30000	Queue refresh interval (ms)
enableManagementRoutes	boolean	true	Enable SQS management routes
routePrefix	string	'/sqs'	Prefix for SQS routes
discoveryTimeout	number	5000	Queue discovery timeout (ms)

Timeout Configuration

{
  defaultTimeout: 30000,  // Global default
  coreGroups: [
    {
      coreName: 'api',
      baseUrl: 'http://localhost:4005',
      routes: [
        {
          name: 'fast-service',
          pathPrefix: '/api/http/fast/',
          timeout: 5000,  // Override for this route
        },
        {
          name: 'slow-service',
          pathPrefix: '/api/http/slow/',
          timeout: 60000,  // Longer timeout
        },
      ],
    },
  ],
}

Environment-Based Configuration

const isDev = process.env.NODE_ENV !== 'production';

const proxy = new ProxyServer({
  port: parseInt(process.env.PROXY_PORT || '5454'),
  cors: isDev,
  logRequests: isDev,
  coreGroups: [
    {
      coreName: 'api',
      baseUrl: process.env.API_URL || 'http://localhost:4005',
      routes: [
        {
          name: 'main',
          pathPrefix: '/api/http/',
        },
      ],
    },
  ],
});

Next Steps

• Routing - Path-based routing
• Load Balancing - Fallback strategies