switchboard

README

Prototype for programmable reverse proxy rules.

Users write request rules in Go, compile them to WebAssembly with TinyGo, upload immutable bundles to object storage, and proxy instances poll a channel pointer to hot-swap the active rule without restarting the proxy.

Switchboard keeps the long-lived dataplane stable, moves fast-changing request policy into versioned Wasm guests, and activates versions only after validation. It applies that pattern to ordinary reverse proxy deployments instead of requiring a custom CDN or edge network.

Rule deployments do not restart the proxy. Bundles are downloaded, verified, compiled, warmed, and validated off the request path, then activated with an atomic swap. In-flight requests continue using the runtime version they started with. If activation fails, the last known-good version remains active.

func Handle(req sdk.Request) sdk.Action {
	if req.Path() == "/blocked" {
		return sdk.Deny(403).WithReason("blocked-path")
	}

	return sdk.Next().SetRequestHeader("x-powered-by", "switchboard")
}

Architecture

• CLI: init, build, test, eval, replay, deploy, promote, rollback, and more
• Registry: S3-compatible object storage, local file://, or read-only https://
• Proxy: Caddy handler module (http.handlers.switchboard), standalone switchboard serve, or embeddable Go middleware
• Runtime: wazero with enforced timeouts, memory caps, and output validation
• Guests: TinyGo WASI modules against a small host ABI (switchboard/v4)

Install

go install github.com/ethndotsh/switchboard/cmd/switchboard@latest

Caddy with the module built in:

docker pull ghcr.io/ethndotsh/switchboard-caddy:latest
# or
xcaddy build --with github.com/ethndotsh/switchboard/caddy@latest

You'll also need TinyGo to build rules.

Quickstart

No object store required; the file:// registry works out of the box:

mkdir my-rules && cd my-rules
switchboard init --name my-rules --registry file://./registry

switchboard build      # compile the rule + embed its tests
switchboard test       # run the behavioral suite
switchboard deploy     # upload + repoint the channel

switchboard serve --listen :8080 --upstream localhost:3000 \
  --registry file://./registry --channel prod

Edit the rule, switchboard build && switchboard deploy, and the running proxy hot-swaps it within seconds. Broke something? switchboard rollback --channel prod.

Documentation

Full docs live in docs/: concepts, guides, and a complete CLI/SDK/Caddyfile reference.

cd docs && pnpm install && pnpm dev

Highlights:

• Quickstart: first rule to live traffic in five minutes
• Concepts: architecture, bundles/channels/revisions, the reliability model
• Guides: writing rules, testing, replaying production traffic, deploying, Caddy integration, registries
• Reference: every CLI flag, Caddyfile directive, SDK method, and schema

Examples

Real-world rules, each with a behavioral test suite, under examples/: auth gating, legacy redirects, security headers, maintenance mode, metadata-driven canary routing, a data-file-driven IP allowlist, and a typed-config feature-flags rule.

Limitations

Rules cannot read request/response bodies, make network calls, or hold state. They can read immutable data files baked into the bundle (allowlists, redirect maps, cohort tables), which keeps lookups deterministic and replayable without reintroducing state. Switchboard is not a CDN, cache, or hosted control plane. Caddy is the reference adapter.

Prior art

Architectural lessons from Railway's Hikari CDN (stable dataplane, versioned guests, reconcile + atomic swap) and Arcjet's production wazero writeups (precompile, never instantiate on the request path).

License

See LICENSE.

Documentation

Index

• type Action
• type Decision
• type HeaderOp
• type HeaderOpType
• type Request
• type RequestPatch
  • func (p RequestPatch) IsZero() bool
• type Response

Types

type Action

type Action struct {
	Decision Decision          `json:"decision"`
	Patch    RequestPatch      `json:"patch,omitempty"`
	Response Response          `json:"response,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
	Reason   string            `json:"reason,omitempty"`
}

type Decision

type Decision string

const (
	DecisionNext     Decision = "next"
	DecisionDeny     Decision = "deny"
	DecisionRedirect Decision = "redirect"
	DecisionRewrite  Decision = "rewrite"
	DecisionRespond  Decision = "respond"
)

type HeaderOp

type HeaderOp struct {
	Op    HeaderOpType `json:"op"`
	Name  string       `json:"name"`
	Value string       `json:"value,omitempty"`
}

type HeaderOpType

type HeaderOpType string

const (
	HeaderOpSet    HeaderOpType = "set"
	HeaderOpAdd    HeaderOpType = "add"
	HeaderOpDelete HeaderOpType = "delete"
)

type Request

type Request struct {
	Method     string              `json:"method"`
	Scheme     string              `json:"scheme,omitempty"`
	Host       string              `json:"host,omitempty"`
	Path       string              `json:"path"`
	RawQuery   string              `json:"raw_query,omitempty"`
	Protocol   string              `json:"protocol,omitempty"`
	Headers    map[string][]string `json:"headers"`
	RemoteAddr string              `json:"remote_addr,omitempty"`
	ClientIP   string              `json:"client_ip,omitempty"`
	TLS        bool                `json:"tls,omitempty"`
}

type RequestPatch

type RequestPatch struct {
	Headers []HeaderOp `json:"headers,omitempty"`
	Host    *string    `json:"host,omitempty"`
	Path    *string    `json:"path,omitempty"`
	Query   *string    `json:"query,omitempty"`
}

RequestPatch mutates the request before it continues down the chain; nil pointer fields leave the component unchanged.

func (RequestPatch) IsZero

func (p RequestPatch) IsZero() bool

type Response

type Response struct {
	Status   int        `json:"status,omitempty"`
	Location string     `json:"location,omitempty"`
	Headers  []HeaderOp `json:"headers,omitempty"`
	Body     []byte     `json:"body,omitempty"`
}