Action Types

Overview

Actions define what the proxy does with incoming requests. Each origin configuration must specify exactly one action type.

Available Action Types

Action Type	Description
proxy	Forward requests to an upstream server
redirect	HTTP redirects with configurable status codes (301, 302, 307, 308). Supports a bulk_list for compiled source-to-destination tables
static	Serve static content directly (text, JSON, base64)
storage	Serve files from cloud storage (S3, GCS, Azure)
load_balancer	Distribute requests across multiple backends with health checks
graphql	GraphQL-aware proxy with query analysis and validation
websocket	WebSocket proxying with connection pooling
grpc	gRPC proxying with HTTP/2 enforcement
echo	Return request information for debugging
beacon	Serve 1x1 tracking pixel for analytics
mcp	Model Context Protocol server for AI tool integration
ai_proxy	Multi-provider LLM gateway with intelligent routing
a2a	Google Agent-to-Agent protocol for inter-agent communication
mock	Synthetic responses for API mocking and testing
noop	No-operation placeholder for testing and defaults

Load Balancer - Algorithms

The load_balancer action distributes requests across multiple backend targets. Ten algorithms are available:

Algorithm	Description
round_robin	Cycle through backends in order
weighted_round_robin	Round-robin respecting backend weights
weighted_random	Random selection weighted by backend weight
random	Uniform random selection
least_connections	Route to the backend with the fewest active connections
ip_hash	Hash the client IP for sticky routing without cookies
uri_hash	Hash the request URI for cache-friendly routing
header_hash	Hash a specific request header (set hash_key to the header name)
cookie_hash	Hash a specific cookie value (set hash_key to the cookie name)
first	Always use the first healthy backend (primary/backup pattern)

Set the algorithm on the action and, for hash-based algorithms that target a specific header or cookie, also set hash_key:

proxy:
  http_bind_port: 8080

origins:
  "api.example.com":
    action:
      type: load_balancer
      algorithm: header_hash
      hash_key: X-Tenant-ID
      targets:
        - url: https://backend-1.internal
        - url: https://backend-2.internal
        - url: https://backend-3.internal

IP hash example for sticky sessions without cookies:

origins:
  "api.example.com":
    action:
      type: load_balancer
      algorithm: ip_hash
      targets:
        - url: https://backend-1.internal
        - url: https://backend-2.internal

Test it:

curl -H "Host: api.example.com" http://localhost:8080/

Load Balancer - DNS SRV Service Discovery

Instead of listing static backend URLs, you can configure the load balancer to discover backends automatically via DNS SRV records. Set discovery.type to dns_srv and point discovery.service at the SRV record name. SBproxy re-resolves the SRV record on the interval specified by discovery.refresh_interval and updates the backend pool without a restart.

This is useful for Kubernetes headless services, Consul (open source DNS-based discovery), and any infrastructure that publishes SRV records.

proxy:
  http_bind_port: 8080

origins:
  "api.example.com":
    action:
      type: load_balancer
      algorithm: round_robin
      discovery:
        type: dns_srv
        service: _http._tcp.api.example.com
        refresh_interval: 30s

Test it:

curl -H "Host: api.example.com" http://localhost:8080/

Example - Basic Proxy

The simplest proxy action forwards all requests to an upstream server:

proxy:
  http_bind_port: 8080

origins:
  "api.example.com":
    action:
      type: proxy
      url: https://test.sbproxy.dev

Test it:

curl -H "Host: api.example.com" http://localhost:8080/

Mock Action

The mock action returns synthetic HTTP responses without forwarding to any backend. It is designed for API mocking, testing, and development scenarios where you need controllable responses with simulated latency. Use static for production static responses (health endpoints, maintenance pages) and mock for development and testing where you need configurable delay.

Fields: status_code, headers, body (supports template variables), delay (simulated latency, up to 30s).

proxy:
  http_bind_port: 8080

origins:
  "api.example.com":
    action:
      type: mock
      status_code: 200
      headers:
        Content-Type: application/json
        X-Mock: "true"
      body: '{"message": "Hello from mock", "timestamp": "{{ request.timestamp }}"}'
      delay: 100ms

Test it:

curl -H "Host: api.example.com" http://localhost:8080/