Skip to main content

Proxy Package

Route requests to multiple serverless cores

The @serverless-monolith/proxy package provides a proxy server for managing multiple Serverless Monolith cores. It enables intelligent routing, load balancing, and path transformations.

Installation​

pnpm add @serverless-monolith/proxy

Features​

  • Multi-Core Routing: Route requests to different backends based on path
  • Path Transformations: Transform paths before forwarding
  • Fallback URLs: Try alternative backends on failure
  • Timeout Handling: Configurable timeouts per route
  • CORS Support: Built-in CORS configuration
  • Request Logging: Detailed request/response logging
  • SQS Routing: Proxy SQS messages between cores

Quick Start​

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

const proxy = new ProxyServer({
  port: 5454,
  cors: true,
  coreGroups: [
    {
      coreName: 'serverless-sst',
      baseUrl: 'http://localhost:4005',
      routes: [
        {
          name: 'user-service',
          pathPrefix: '/api/http/user/',
        },
        {
          name: 'order-service',
          pathPrefix: '/api/http/order/',
        },
      ],
    },
    {
      coreName: 'serverless-onboarding',
      baseUrl: 'http://localhost:4006',
      routes: [
        {
          name: 'company',
          pathPrefix: '/api/http/company/',
        },
      ],
    },
  ],
});

await proxy.start();

Using Cores (Legacy)​

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

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

await proxy.start();

How It Works​

Client Request                    Proxy                         Backend
     │                              │                              │
     │  GET /users/123              │                              │
     │─────────────────────────────▶│                              │
     │                              │  Match: /users/* → user-svc  │
     │                              │                              │
     │                              │  GET /api/http/user/123      │
     │                              │─────────────────────────────▶│
     │                              │                              │
     │                              │◀─────────────────────────────│
     │◀─────────────────────────────│                              │
     │                              │                              │

Use Cases​

Local Development​

Run multiple serverless projects and access them through a single endpoint:

http://localhost:5454/users/*     → user-service (port 4005)
http://localhost:5454/orders/*    → order-service (port 4006)
http://localhost:5454/products/*  → product-service (port 4007)

API Gateway Simulation​

Simulate AWS API Gateway routing locally:

{
  coreGroups: [
    {
      coreName: 'api-v1',
      baseUrl: 'http://localhost:4005',
      routes: [
        { name: 'v1', pathPrefix: '/api/http/' },
      ],
    },
    {
      coreName: 'api-v2',
      baseUrl: 'http://localhost:4006',
      routes: [
        { name: 'v2', pathPrefix: '/api/http/' },
      ],
    },
  ]
}

Migration Support​

Route to new service with fallback to old:

{
  coreGroups: [
    {
      coreName: 'new-service',
      baseUrl: 'http://localhost:4005',
      routes: [
        {
          name: 'users',
          pathPrefix: '/api/http/user/',
          routeByPath: {
            '': {
              pathPrefix: '/api/http/user/',
              fallbackUrls: ['http://localhost:4006/api/http/user/'],
            },
          },
        },
      ],
    },
  ]
}

Next Steps​