Handlers

Copy page

Zuplo provides several built-in handlers for common API gateway scenarios. These handlers can be used directly in your route configuration without writing custom code.

Available Handlers

Request Handlers

• awsLambdaHandler - Invoke AWS Lambda functions
• mcpServerHandler - Model Context Protocol server handler
• openApiSpecHandler - Serve OpenAPI specifications
• redirectHandler - HTTP redirects
• urlForwardHandler - Forward requests to another URL
• urlRewriteHandler - Rewrite request URLs
• webSocketHandler - WebSocket connections
• webSocketPipelineHandler - WebSocket with pipeline support

Usage in Routes

Handlers are configured in your route definition:

Code
 
{
  "routes": [
    {
      "path": "/lambda/*",
      "methods": ["GET", "POST"],
      "handler": {
        "export": "awsLambdaHandler",
        "module": "@zuplo/runtime"
      }
    },
    {
      "path": "/old-path",
      "methods": ["GET"],
      "handler": {
        "export": "redirectHandler",
        "module": "@zuplo/runtime",
        "options": {
          "location": "/new-path",
          "status": 301
        }
      }
    }
  ]
}

Handler Types

1. Proxy Handlers

These handlers forward requests to other services:

• urlForwardHandler - Simple URL forwarding
• urlRewriteHandler - URL rewriting with pattern matching
• awsLambdaHandler - AWS Lambda integration

2. Response Handlers

These handlers generate responses directly:

• redirectHandler - HTTP redirects
• openApiSpecHandler - OpenAPI documentation
• mcpServerHandler - MCP protocol responses

3. Protocol Handlers

These handlers support specific protocols:

• webSocketHandler - Basic WebSocket support
• webSocketPipelineHandler - WebSocket with policy pipeline

Common Patterns

Dynamic URL Forwarding

Code
 
{
  "path": "/api/:service/*",
  "handler": {
    "export": "urlRewriteHandler",
    "module": "@zuplo/runtime",
    "options": {
      "pattern": "^/api/([^/]+)/(.*)$",
      "rewrite": "https://$1.internal.example.com/$2"
    }
  }
}

Conditional Redirects

Code
 
{
  "path": "/docs",
  "handler": {
    "export": "redirectHandler",
    "module": "@zuplo/runtime",
    "options": {
      "location": "https://docs.example.com",
      "status": 302
    }
  }
}

Lambda Integration

Code
 
{
  "path": "/functions/:functionName",
  "handler": {
    "export": "awsLambdaHandler",
    "module": "@zuplo/runtime"
  },
  "policies": {
    "inbound": ["api-key-auth", "rate-limit"]
  }
}

Custom Handler Implementation

If built-in handlers don't meet your needs, you can create custom handlers:

Code
 
import { ZuploContext, ZuploRequest } from "@zuplo/runtime";

export default async function customHandler(
  request: ZuploRequest,
  context: ZuploContext,
): Promise<Response> {
  // Your custom logic here
  return new Response("Hello from custom handler!");
}

Handler Options

Most handlers accept options to configure their behavior:

Code
 
{
  "handler": {
    "export": "handlerName",
    "module": "@zuplo/runtime",
    "options": {
      // Handler-specific options
    }
  }
}

Error Handling

Built-in handlers follow standard error handling patterns:

1. Network errors return 502 Bad Gateway
2. Invalid configurations return 500 Internal Server Error
3. Client errors are passed through from upstream services

Performance Considerations

• Built-in handlers are optimized for performance
• Handlers run at the edge for low latency
• Connection pooling is handled automatically
• Automatic retries for transient failures (where appropriate)

See Also

• Custom Handlers - Building custom handlers
• Route Configuration - Configuring routes
• Policies - Adding policies to handlers