Documentation
¶
Overview ¶
Package proxy implements the Diverge reverse proxy for subdomain-based routing of requests to preview environments.
Index ¶
- Constants
- Variables
- func BaggageExtractorMiddleware(next http.Handler) http.Handler
- func CORSMiddleware(previewDomain string, next http.Handler) http.Handler
- func CheckLocalhostDNS() bool
- func LoggingMiddleware(next http.Handler) http.Handler
- type ActivatorProxyConfig
- type ActivatorServer
- type Config
- type EnvironmentInfo
- type EnvironmentLister
- type K8sEnvironmentLister
- type LoopbackProxy
- func (p *LoopbackProxy) Addr() string
- func (p *LoopbackProxy) Close() error
- func (p *LoopbackProxy) Mode() ProxyMode
- func (p *LoopbackProxy) Ready() <-chan struct{}
- func (p *LoopbackProxy) Shutdown(ctx context.Context) error
- func (p *LoopbackProxy) Start(ctx context.Context) error
- func (p *LoopbackProxy) UpdateRoutes(services []ServiceRoute)
- type NotFoundData
- type ProxyMode
- type ReadinessChecker
- type RouteTable
- type Server
- type ServiceRoute
Constants ¶
const ResponseHeaderEnvironment = "X-Diverge-Environment"
ResponseHeaderEnvironment is the HTTP response header that identifies which preview environment served the request.
Variables ¶
var ErrCacheNotSynced = fmt.Errorf("cache not synced")
ErrCacheNotSynced is returned when the informer cache has not yet completed its initial sync with the Kubernetes API server.
var ErrEnvironmentNotFound = errors.New("environment not found")
ErrEnvironmentNotFound is returned when an environment cannot be found.
Functions ¶
func BaggageExtractorMiddleware ¶ added in v0.7.0
BaggageExtractorMiddleware reads x-preview-* and x-tenant-id headers and injects them as W3C Baggage entries so they appear in OTel spans.
func CORSMiddleware ¶
CORSMiddleware validates the request Origin against the preview domain. Only origins ending with the previewDomain are trusted.
func CheckLocalhostDNS ¶ added in v0.7.0
func CheckLocalhostDNS() bool
CheckLocalhostDNS tests if the localhost DNS zone is resolvable.
Types ¶
type ActivatorProxyConfig ¶
type ActivatorProxyConfig struct {
Port int
ActivatorURL string
TargetNamespace string
TargetSelector string
TargetPort int
TargetRevision string
PreviewEnvValue string
}
ActivatorProxyConfig holds configuration for the Activator proxy.
type ActivatorServer ¶
type ActivatorServer struct {
// contains filtered or unexported fields
}
ActivatorServer is the reverse proxy server for Knative scale-to-zero.
func NewActivatorServer ¶
func NewActivatorServer(ctx context.Context, cfg ActivatorProxyConfig, kubeClient kubernetes.Interface) (*ActivatorServer, error)
NewActivatorServer creates a new ActivatorServer.
func (*ActivatorServer) Close ¶
func (s *ActivatorServer) Close()
Close stops the internal informer.
func (*ActivatorServer) ServeHTTP ¶
func (s *ActivatorServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP handles incoming requests.
type Config ¶
type Config struct {
// BaseURL is the upstream URL (e.g., https://app.staging.example.com)
BaseURL string
// HeaderKey is the header to inject (default: x-diverge-env)
HeaderKey string
// PreviewDomain is the wildcard domain (e.g., preview.example.com)
PreviewDomain string
// Port to listen on
Port int
// HideEnvironmentList hides active environments on 404
HideEnvironmentList bool
}
Config holds proxy configuration
type EnvironmentInfo ¶
EnvironmentInfo holds metadata about a resolved preview environment, including its deployment phase and upstream target URL.
type EnvironmentLister ¶
type EnvironmentLister interface {
GetEnvironment(ctx context.Context, name string) (*EnvironmentInfo, error)
ListEnvironments(ctx context.Context) ([]EnvironmentInfo, error)
}
EnvironmentLister resolves environment names from the K8s API
type K8sEnvironmentLister ¶
type K8sEnvironmentLister struct {
// contains filtered or unexported fields
}
K8sEnvironmentLister resolves preview environments by watching Environment custom resources. It uses an informer cache for primary lookups, with an optional TTL-based fallback for direct API calls.
func NewK8sEnvironmentLister ¶
func NewK8sEnvironmentLister(ctx context.Context, kubeconfig, namespace string, scheme *runtime.Scheme) (*K8sEnvironmentLister, error)
NewK8sEnvironmentLister creates a Kubernetes-backed EnvironmentLister that watches Environment custom resources via an informer cache. If informer setup fails, it falls back to direct API calls with a short TTL cache.
func (*K8sEnvironmentLister) GetEnvironment ¶
func (l *K8sEnvironmentLister) GetEnvironment(ctx context.Context, name string) (*EnvironmentInfo, error)
GetEnvironment looks up a single environment by name. It returns the cached entry if the informer is synced, falls back to a TTL-cached API call if in fallback mode, or returns ErrCacheNotSynced if the cache is not ready.
func (*K8sEnvironmentLister) HasSynced ¶
func (l *K8sEnvironmentLister) HasSynced() bool
HasSynced reports whether the informer cache has completed its initial list. In fallback mode (no informer), it always returns true.
func (*K8sEnvironmentLister) ListEnvironments ¶
func (l *K8sEnvironmentLister) ListEnvironments(ctx context.Context) ([]EnvironmentInfo, error)
ListEnvironments returns all known environments. In informer mode it reads from the cache; in fallback mode it issues a List call to the Kubernetes API.
type LoopbackProxy ¶ added in v0.7.0
type LoopbackProxy struct {
// contains filtered or unexported fields
}
LoopbackProxy implements a local proxy that routes requests to upstream services.
func NewLoopbackProxy ¶ added in v0.7.0
func NewLoopbackProxy(headerKey, headerValue string, port int, mode ProxyMode) *LoopbackProxy
NewLoopbackProxy creates a new LoopbackProxy that routes requests to upstream services based on the specified mode (host or path), injecting the specified routing header.
func (*LoopbackProxy) Addr ¶ added in v0.7.0
func (p *LoopbackProxy) Addr() string
Addr returns the actual bound address.
func (*LoopbackProxy) Close ¶ added in v0.7.0
func (p *LoopbackProxy) Close() error
Close cleans up resources without graceful shutdown.
func (*LoopbackProxy) Mode ¶ added in v0.7.0
func (p *LoopbackProxy) Mode() ProxyMode
Mode returns the proxy's configured routing mode.
func (*LoopbackProxy) Ready ¶ added in v0.7.0
func (p *LoopbackProxy) Ready() <-chan struct{}
Ready returns a channel that is closed when the proxy is listening.
func (*LoopbackProxy) Shutdown ¶ added in v0.7.0
func (p *LoopbackProxy) Shutdown(ctx context.Context) error
Shutdown gracefully shuts down the server.
func (*LoopbackProxy) Start ¶ added in v0.7.0
func (p *LoopbackProxy) Start(ctx context.Context) error
Start binds the server to a local port and begins serving requests.
func (*LoopbackProxy) UpdateRoutes ¶ added in v0.7.0
func (p *LoopbackProxy) UpdateRoutes(services []ServiceRoute)
UpdateRoutes updates the route table and marks the proxy as ready.
type NotFoundData ¶
type NotFoundData struct {
EnvName string
ActiveEnvs []EnvironmentInfo
HideList bool
}
NotFoundData is the template data for the 404 page, including the requested environment name and a list of currently active environments.
type ProxyMode ¶ added in v0.7.0
type ProxyMode string
ProxyMode defines the routing mode for the proxy.
type ReadinessChecker ¶
type ReadinessChecker interface {
HasSynced() bool
}
ReadinessChecker is optionally implemented by an EnvironmentLister to indicate whether its internal cache has synced with the Kubernetes API.
type RouteTable ¶ added in v0.7.0
type RouteTable struct {
// contains filtered or unexported fields
}
RouteTable manages thread-safe service routing.
func NewRouteTable ¶ added in v0.7.0
func NewRouteTable() *RouteTable
NewRouteTable creates a new RouteTable.
func (*RouteTable) Available ¶ added in v0.7.0
func (rt *RouteTable) Available() []string
Available returns a list of available service names.
func (*RouteTable) Lookup ¶ added in v0.7.0
func (rt *RouteTable) Lookup(name string) (*url.URL, bool)
Lookup finds the upstream URL for a given service name.
func (*RouteTable) Update ¶ added in v0.7.0
func (rt *RouteTable) Update(services []ServiceRoute)
Update replaces the current routes with the provided services.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the Magic URL reverse proxy server
func NewServer ¶
func NewServer(cfg Config, lister EnvironmentLister) (*Server, error)
NewServer creates a new reverse proxy Server. It parses the BaseURL from cfg, configures an httputil.ReverseProxy director, and defaults the header key to "x-diverge-env" if not set. If lister implements ReadinessChecker, readiness probes will reflect cache sync state.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP handles incoming HTTP requests. It serves health and readiness probes, validates the host against the preview domain, resolves the target environment, and either renders a status page or proxies to the upstream.
type ServiceRoute ¶ added in v0.7.0
ServiceRoute represents a mapping from a service name to its upstream URL.