Documentation
¶
Overview ¶
Package proxy implements the Diverge reverse proxy for subdomain-based routing of requests to preview environments.
Index ¶
- Constants
- Variables
- func CORSMiddleware(previewDomain string, next http.Handler) http.Handler
- func LoggingMiddleware(next http.Handler) http.Handler
- type ActivatorProxyConfig
- type ActivatorServer
- type Config
- type EnvironmentInfo
- type EnvironmentLister
- type K8sEnvironmentLister
- type NotFoundData
- type ReadinessChecker
- type Server
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 CORSMiddleware ¶
CORSMiddleware validates the request Origin against the preview domain. Only origins ending with the previewDomain are trusted.
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 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 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 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.
Source Files