Documentation
¶
Overview ¶
Package caddymirror provides a Caddy reverse_proxy transport module that duplicates ("mirrors") requests to one or more secondary upstreams while forwarding the real request/response through an underlying HTTP transport.
Mirror responses are always discarded; mirroring never affects the primary request's outcome, latency budget beyond the initial dispatch, or error handling.
Index ¶
- Constants
- type MirrorTransport
- func (*MirrorTransport) CaddyModule() caddy.ModuleInfo
- func (m *MirrorTransport) Cleanup() error
- func (m *MirrorTransport) Provision(ctx caddy.Context) error
- func (m *MirrorTransport) RoundTrip(req *http.Request) (*http.Response, error)
- func (m *MirrorTransport) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
- func (m *MirrorTransport) Validate() error
- type MirrorUpstream
Constants ¶
const DefaultMaxBodySize = 2 << 20 // 2 MiB
DefaultMaxBodySize is used when MaxBodySize is left unset (zero).
const DefaultTimeout = 5 * time.Second
DefaultTimeout is used when Timeout is left unset (zero).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MirrorTransport ¶
type MirrorTransport struct {
// Mirrors is the list of upstreams that receive a duplicated copy of
// each request. An empty list makes this transport a zero-overhead
// passthrough to the primary transport.
Mirrors []*MirrorUpstream `json:"mirrors,omitempty"`
// MaxBodySize is the maximum number of request body bytes that will be
// buffered in order to duplicate them to mirrors. Requests with a
// larger body are still forwarded to the primary upstream normally,
// but are mirrored without a body. Default: 2MiB. A value of -1 means
// unlimited (buffers the entire body in memory).
MaxBodySize int64 `json:"max_body_size,omitempty"`
// Timeout bounds how long a single mirror request is allowed to run,
// independent of the primary request's context. Default: 5s.
Timeout caddy.Duration `json:"timeout,omitempty"`
// Headers manipulates the headers sent to every mirror (not the
// primary upstream). Values may use Caddy placeholders such as
// {env.MY_SECRET} to inject secrets from the environment without
// putting them in the config file directly.
Headers *headers.HeaderOps `json:"headers,omitempty"`
// contains filtered or unexported fields
}
MirrorTransport is a Caddy http.RoundTripper that forwards the request to the primary upstream as usual (via an embedded HTTPTransport), and additionally fires copies of the request at zero or more mirror upstreams. Mirror requests are best-effort, fire-and-forget: their responses are discarded and their errors never affect the primary request/response.
func (*MirrorTransport) CaddyModule ¶
func (*MirrorTransport) CaddyModule() caddy.ModuleInfo
CaddyModule returns the Caddy module information.
func (*MirrorTransport) Cleanup ¶
func (m *MirrorTransport) Cleanup() error
Cleanup closes idle connections held by the primary and mirror transports.
func (*MirrorTransport) Provision ¶
func (m *MirrorTransport) Provision(ctx caddy.Context) error
Provision sets up the primary transport, mirror HTTP client, and defaults.
func (*MirrorTransport) RoundTrip ¶
RoundTrip implements http.RoundTripper. It forwards req to the primary transport and, for each configured mirror selected by its sampling percentage, fires a best-effort duplicate of req in the background.
func (*MirrorTransport) UnmarshalCaddyfile ¶
func (m *MirrorTransport) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
UnmarshalCaddyfile deserializes Caddyfile tokens into m.
transport mirror {
to <address> [<percent>]
max_body_size <size>|unlimited
timeout <duration>
header [+|-]<field> [<value|regexp> [<replacement>]]
}
func (*MirrorTransport) Validate ¶
func (m *MirrorTransport) Validate() error
Validate ensures the configuration is sound.
type MirrorUpstream ¶
type MirrorUpstream struct {
// To is the base URL of the mirror upstream, e.g. "http://mirror:9090".
// If no scheme is given, "http://" is assumed.
To string `json:"to"`
// Percent is the percentage (0-100) of requests duplicated to this
// mirror. Unset (nil) defaults to 100 (mirror every request); an
// explicit 0 disables this mirror without removing its config.
Percent *int `json:"percent,omitempty"`
// contains filtered or unexported fields
}
MirrorUpstream is a single mirror target: an address that receives a sampled duplicate of each request.