Proxy

Proxy forwards requests through httputil.ReverseProxy.

app.UsePrefix("/upstream", middleware.Proxy("https://api.example.com"))

The simple constructor is the right default for a single upstream. Zinc rewrites the request scheme, host, and path through the standard library reverse proxy.

Use ProxyWithConfig when the request or response needs adjustment.

app.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{
	Target: "https://api.example.com",
	Director: func(req *http.Request) {
		req.Header.Set("X-Forwarded-App", "zinc")
	},
	Modify: func(resp *http.Response) error {
		resp.Header.Del("Server")
		return nil
	},
}))

Modify is kept for compatibility. New code can use ModifyResponse; both are chained when both are set.

Multiple targets

Proxy can balance across multiple targets. Targets uses round-robin by default.

apiA, _ := url.Parse("https://api-a.example.com")
apiB, _ := url.Parse("https://api-b.example.com")

app.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{
	Targets: []*middleware.ProxyTarget{
		{Name: "a", URL: apiA},
		{Name: "b", URL: apiB},
	},
}))

Use an explicit balancer when the choice should be obvious from the config.

targets := []*middleware.ProxyTarget{
	{Name: "a", URL: apiA},
	{Name: "b", URL: apiB},
}

app.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{
	Balancer: middleware.NewRoundRobinBalancer(targets),
}))

For random target selection:

app.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{
	Balancer: middleware.NewRandomBalancer(targets),
}))

Rewrites

Use Rewrite for exact paths or * suffix rules.

app.UsePrefix("/api", middleware.ProxyWithConfig(middleware.ProxyConfig{
	Target: "https://api.example.com",
	Rewrite: map[string]string{
		"/api/*": "/v1/*",
	},
}))

Use RegexRewrite when wildcard rules are not expressive enough.

app.UsePrefix("/api", middleware.ProxyWithConfig(middleware.ProxyConfig{
	Target: "https://api.example.com",
	RegexRewrite: map[*regexp.Regexp]string{
		regexp.MustCompile(`^/api/users/(\d+)$`): "/v1/users/$1",
	},
}))

Retries

Retries are opt-in.

app.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{
	Target:  "https://api.example.com",
	Retries: 2,
	RetryFilter: func(c *zinc.Context, err error) bool {
		return c.Method() == zinc.MethodGet
	},
}))

Zinc only retries when the request body can be replayed safely: no body, http.NoBody, or a request with GetBody configured.

Transport

Pass a custom transport for timeouts, tracing, connection pools, or tests.

app.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{
	Target:    "https://api.example.com",
	Transport: customTransport,
}))

The target must be a valid absolute URL.