Routing

Learn how the Proxy routes requests to backend services.

Basic Routing

Using Core Groups (Recommended)

Routes are matched by route name and forwarded using pathPrefix:

{
  coreGroups: [
    {
      coreName: 'api',
      baseUrl: 'http://localhost:4005',
      routes: [
        {
          name: 'users',
          pathPrefix: '/api/http/user/',
        },
      ],
    },
  ]
}

Request	Routed To
GET /users	http://localhost:4005/api/http/user/
GET /users/123	http://localhost:4005/api/http/user/123
POST /users	http://localhost:4005/api/http/user/

Using Cores (Legacy)

Routes are matched by pathPrefix:

{
  cores: [
    {
      name: 'users',
      url: 'http://localhost:4005/api/http/user/',
      pathPrefix: '/users',
    },
  ]
}

Path Prefix Behavior

The route name is removed from the path before forwarding, and pathPrefix is applied:

Request:  GET /users/123/orders
Route:    name: 'users'
Backend:  baseUrl: 'http://localhost:4005', pathPrefix: '/api/http/user/'
Result:   GET http://localhost:4005/api/http/user/123/orders

Route By Path

For complex routing scenarios, use routeByPath:

Within Core Groups

{
  coreGroups: [
    {
      coreName: 'api',
      baseUrl: 'http://localhost:4005',
      routes: [
        {
          name: 'global',
          routeByPath: {
            'v2/users': {
              pathPrefix: '/api/http/users/',
              preserveMatchedPath: true,
            },
            'v2/orders': {
              pathPrefix: '/api/http/orders/',
              preserveMatchedPath: true,
            },
            '': {
              pathPrefix: '/api/http/global/',
            },
          },
        },
      ],
    },
  ]
}

Routing Flow

Request: GET /global/v2/users/123

1. Match route: 'global' ✓
2. Remaining path: v2/users/123
3. Match routeByPath: "v2/users" ✓
4. preserveMatchedPath: true → keep "v2/users"
5. Final: GET http://localhost:4005/api/http/users/v2/users/123

Preserve Matched Path

Controls whether the matched path segment is included:

preserveMatchedPath: true

{
  routeByPath: {
    'v2/users': {
      pathPrefix: '/api/http/users/',
      preserveMatchedPath: true,
    }
  }
}

Request: GET /global/v2/users/123
Result:  GET http://localhost:4005/api/http/users/v2/users/123

preserveMatchedPath: false (default)

{
  routeByPath: {
    'v2/users': {
      pathPrefix: '/api/http/users/',
      preserveMatchedPath: false,
    }
  }
}

Request: GET /global/v2/users/123
Result:  GET http://localhost:4005/api/http/users/123

Path Transformation

Use transformPath for custom transformations:

{
  routeByPath: {
    'v2/users': {
      pathPrefix: '/api/http/users/',
      transformPath: (path) => {
        // Remove version prefix
        return path.replace('/v2/', '/');
      },
    }
  }
}

Request: GET /global/v2/users/123
After transform: /users/123
Result:  GET http://localhost:4005/api/http/users/users/123

Route Priority

Routes are matched in order:

1. Longer prefixes match first
2. More specific routeByPath keys match first
3. Empty string '' acts as catch-all

{
  routeByPath: {
    'v2/users/admin': { pathPrefix: '...' },  // Most specific
    'v2/users': { pathPrefix: '...' },         // Medium
    'v2': { pathPrefix: '...' },               // Less specific
    '': { pathPrefix: '...' },                 // Catch-all
  }
}

Query Parameters

Query parameters are preserved:

Request: GET /users?page=1&limit=10
Result:  GET http://localhost:4005/api/http/user/?page=1&limit=10

Headers

Headers are forwarded automatically:

• All request headers are forwarded
• Host header is rewritten to match the backend
• X-Forwarded-* headers are added

Examples

Version-based Routing

{
  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/' },
      ],
    },
  ]
}

Service-based Routing

{
  coreGroups: [
    {
      coreName: 'users-svc',
      baseUrl: 'http://users-svc:4000',
      routes: [{ name: 'users', pathPrefix: '/api/http/' }],
    },
    {
      coreName: 'orders-svc',
      baseUrl: 'http://orders-svc:4000',
      routes: [{ name: 'orders', pathPrefix: '/api/http/' }],
    },
    {
      coreName: 'products-svc',
      baseUrl: 'http://products-svc:4000',
      routes: [{ name: 'products', pathPrefix: '/api/http/' }],
    },
  ]
}

Module-based Routing

Multiple modules on a single backend:

{
  coreGroups: [
    {
      coreName: 'serverless-sst',
      baseUrl: 'http://localhost:4005',
      routes: [
        { name: 'users', pathPrefix: '/api/http/user/' },
        { name: 'orders', pathPrefix: '/api/http/order/' },
        { name: 'documents', pathPrefix: '/api/http/documents/' },
        { name: 'scheduling', pathPrefix: '/api/http/scheduling/' },
      ],
    },
  ]
}

Next Steps

• Load Balancing - Fallback strategies
• Examples - Complete examples