reverseproxy

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 27, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package reverseproxy provides reverse proxy functionality with automatic TLS via ACME.

Index

Constants

View Source
const (
	HeaderClientCertSubject = "X-Client-Cert-Subject"
	HeaderClientCertIssuer  = "X-Client-Cert-Issuer"
	HeaderClientCertCN      = "X-Client-Cert-CN"
	HeaderClientCertSerial  = "X-Client-Cert-Serial"
)

Headers carrying the verified client certificate identity to backends.

Variables

ClientAuthModes lists every supported mode, in increasing order of strictness.

Functions

This section is empty.

Types

type Backend

type Backend struct {
	// Host is the hostname/pattern to match (e.g., "api.example.com" or "*.example.com").
	// Empty when PathPrefix is set.
	Host string `yaml:"host"`
	// PathPrefix matches requests by URL path prefix (e.g., "/api"). When set, Host is
	// ignored and the prefix is stripped before forwarding.
	PathPrefix string `yaml:"pathPrefix,omitempty"`
	// Target is the backend URL (e.g., "http://localhost:3000")
	Target string `yaml:"target"`
	// StripPrefix removes a path prefix before forwarding
	StripPrefix string `yaml:"stripPrefix,omitempty"`
	// AddHeaders are headers to add to proxied requests
	AddHeaders map[string]string `yaml:"addHeaders,omitempty"`
	// HealthCheck is the health check path
	HealthCheck string `yaml:"healthCheck,omitempty"`
	// CORSOrigin, when non-empty, adds Access-Control-Allow-Origin and related CORS
	// headers to proxied responses. Use "*" to allow all origins.
	CORSOrigin string `yaml:"corsOrigin,omitempty"`
	// TLS configures the client presented to an HTTPS backend that requires mutual TLS.
	TLS *BackendTLS `yaml:"tls,omitempty"`
}

Backend represents a backend server configuration.

type BackendTLS added in v0.2.0

type BackendTLS struct {
	// CertFile is the PEM client certificate to present to the backend.
	CertFile string `yaml:"certFile,omitempty"`
	// KeyFile is the PEM private key for CertFile. If empty, the key is read from CertFile.
	KeyFile string `yaml:"keyFile,omitempty"`
	// CAFile is a PEM bundle of CAs used to verify the backend server certificate. If empty,
	// the system trust store is used.
	CAFile string `yaml:"caFile,omitempty"`
	// InsecureSkipVerify disables verification of the backend server certificate. It exists
	// for self-signed backends in development and must not be used in production.
	InsecureSkipVerify bool `yaml:"insecureSkipVerify,omitempty"`
}

BackendTLS configures the TLS client used to connect to an HTTPS backend, including a client certificate to present when the backend itself requires mutual TLS. It is the mirror of the frontend ClientCAPaths/ClientAuth options: those verify certificates presented by callers, these present a certificate to upstream servers.

type ClientAuthMode added in v0.2.0

type ClientAuthMode string

ClientAuthMode controls how client certificates are requested and verified during the TLS handshake (mutual TLS).

const (
	// ClientAuthNone disables client certificate authentication.
	ClientAuthNone ClientAuthMode = "none"
	// ClientAuthRequest asks for a client certificate but neither requires nor verifies it.
	ClientAuthRequest ClientAuthMode = "request"
	// ClientAuthRequireAny requires a client certificate but does not verify it against the CA pool.
	ClientAuthRequireAny ClientAuthMode = "require-any"
	// ClientAuthVerifyIfGiven verifies a client certificate against the CA pool, but allows
	// connections that offer none.
	ClientAuthVerifyIfGiven ClientAuthMode = "verify-if-given"
	// ClientAuthRequireAndVerify requires a client certificate and verifies it against the
	// CA pool. This is the usual mTLS posture.
	ClientAuthRequireAndVerify ClientAuthMode = "require-and-verify"
)

func (ClientAuthMode) Enabled added in v0.2.0

func (m ClientAuthMode) Enabled() bool

Enabled reports whether the mode requests a client certificate at all.

func (ClientAuthMode) RequiresCAPool added in v0.2.0

func (m ClientAuthMode) RequiresCAPool() bool

RequiresCAPool reports whether the mode verifies client certificates against a CA pool, and therefore needs at least one client CA to be configured.

func (ClientAuthMode) TLSClientAuthType added in v0.2.0

func (m ClientAuthMode) TLSClientAuthType() (tls.ClientAuthType, error)

TLSClientAuthType maps the mode onto its crypto/tls equivalent.

type Config

type Config struct {
	// HTTPPort is the port for HTTP traffic (default: 80)
	HTTPPort int
	// HTTPSPort is the port for HTTPS traffic (default: 443)
	HTTPSPort int
	// Backends is the list of backend configurations
	Backends []Backend
	// ACMEEmail is the email for Let's Encrypt registration
	ACMEEmail string
	// ACMECacheDir is the directory to cache certificates
	ACMECacheDir string
	// ACMEStaging uses Let's Encrypt staging environment (for testing)
	ACMEStaging bool
	// Capturer is the traffic capturer (optional)
	Capturer *capture.Capturer
	// Verbose enables verbose logging
	Verbose bool
	// RedirectHTTP redirects HTTP to HTTPS
	RedirectHTTP bool
	// ClientCAPaths are PEM files holding the CAs used to verify client certificates (mTLS).
	ClientCAPaths []string
	// ClientAuth controls client certificate verification. It defaults to
	// ClientAuthRequireAndVerify when ClientCAPaths is non-empty, and ClientAuthNone otherwise.
	ClientAuth ClientAuthMode
	// StaticDir serves files from this directory as a fallback when no backend matches.
	// Empty disables static file serving.
	StaticDir string
	// Middleware optionally wraps the request-serving handler, e.g. for telemetry. It is
	// applied on the HTTPS listener, and on the HTTP listener when RedirectHTTP is false.
	Middleware func(http.Handler) http.Handler
}

Config holds reverse proxy configuration.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns default reverse proxy configuration.

type ReverseProxy

type ReverseProxy struct {
	// contains filtered or unexported fields
}

ReverseProxy represents a reverse proxy server with ACME support.

func New

func New(cfg *Config) (*ReverseProxy, error)

New creates a new reverse proxy with the given configuration.

func (*ReverseProxy) ClientAuthMode added in v0.2.0

func (rp *ReverseProxy) ClientAuthMode() ClientAuthMode

ClientAuthMode returns the resolved client certificate authentication mode.

func (*ReverseProxy) HealthCheck

func (rp *ReverseProxy) HealthCheck(ctx context.Context) map[string]bool

HealthCheck performs health checks on all backends.

func (*ReverseProxy) ListenAndServe

func (rp *ReverseProxy) ListenAndServe() error

ListenAndServe starts the reverse proxy server.

func (*ReverseProxy) ServeHTTP

func (rp *ReverseProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface.

func (*ReverseProxy) TLSConfig

func (rp *ReverseProxy) TLSConfig() *tls.Config

TLSConfig returns the TLS configuration with ACME support, including client certificate verification (mTLS) when configured.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL