Handlers

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(json)
 
{
  "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(json)
 
{
  "path": "/api/:service/*",
  "handler": {
    "export": "urlRewriteHandler",
    "module": "@zuplo/runtime",
    "options": {
      "pattern": "^/api/([^/]+)/(.*)$",
      "rewrite": "https://$1.internal.example.com/$2"
    }
  }
}

Conditional Redirects

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

Lambda Integration

Code(json)
 
{
  "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(ts)
 
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(json)
 
{
  "handler": {
    "export": "handlerName",
    "module": "@zuplo/runtime",
    "options": {
      // Handler-specific options
    }
  }
}

Error Handling

Built-in handlers follow standard error handling patterns:

Network errors return 502 Bad Gateway
Invalid configurations return 500 Internal Server Error
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)