httpproxy_controller.go

// SPDX-License-Identifier: AGPL-3.0-only

package controller

import (
	"context"
	"errors"
	"fmt"
	"net"
	"net/url"
	"slices"
	"strconv"
	"strings"

	envoygatewayv1alpha1 "github.com/envoyproxy/gateway/api/v1alpha1"
	v1 "k8s.io/api/core/v1"
	discoveryv1 "k8s.io/api/discovery/v1"
	"k8s.io/apimachinery/pkg/api/equality"
	apierrors "k8s.io/apimachinery/pkg/api/errors"
	apimeta "k8s.io/apimachinery/pkg/api/meta"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/types"
	"k8s.io/apimachinery/pkg/util/sets"
	"k8s.io/utils/ptr"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/cluster"
	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
	"sigs.k8s.io/controller-runtime/pkg/handler"
	"sigs.k8s.io/controller-runtime/pkg/log"
	gatewayv1 "sigs.k8s.io/gateway-api/apis/v1"
	mcbuilder "sigs.k8s.io/multicluster-runtime/pkg/builder"
	mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager"
	"sigs.k8s.io/multicluster-runtime/pkg/multicluster"
	mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile"
	mcsource "sigs.k8s.io/multicluster-runtime/pkg/source"

	networkingv1alpha "go.datum.net/network-services-operator/api/v1alpha"
	networkingv1alpha1 "go.datum.net/network-services-operator/api/v1alpha1"
	"go.datum.net/network-services-operator/internal/config"
	downstreamclient "go.datum.net/network-services-operator/internal/downstreamclient"
	conditionutil "go.datum.net/network-services-operator/internal/util/condition"
	gatewayutil "go.datum.net/network-services-operator/internal/util/gateway"
	"go.datum.net/network-services-operator/internal/util/resourcename"
	dnsv1alpha1 "go.miloapis.com/dns-operator/api/v1alpha1"
)

// HTTPProxyReconciler reconciles a HTTPProxy object
type HTTPProxyReconciler struct {
	mgr    mcmanager.Manager
	Config config.NetworkServicesOperator

	DownstreamCluster cluster.Cluster
}

type desiredHTTPProxyResources struct {
	gateway          *gatewayv1.Gateway
	httpRoute        *gatewayv1.HTTPRoute
	endpointSlices   []*discoveryv1.EndpointSlice
	httpRouteFilters []*envoygatewayv1alpha1.HTTPRouteFilter
}

const httpProxyFinalizer = "networking.datumapis.com/httpproxy-cleanup"
const connectorOfflineFilterPrefix = "connector-offline"

// BackendCertHostnameAnnotation is set on the upstream EndpointSlice by the
// HTTPProxy controller to record the hostname expected on the backend's TLS
// certificate. The gateway controller reads it when building a
// BackendTLSPolicy so SAN validation continues to target the real backend
// FQDN even when URLRewrite.Hostname has been redirected to a user-supplied
// Host header override.
const BackendCertHostnameAnnotation = "networking.datumapis.com/backend-cert-hostname"

const (
	SchemeHTTP  = "http"
	SchemeHTTPS = "https"

	DefaultHTTPPort  = 80
	DefaultHTTPSPort = 443
)

// +kubebuilder:rbac:groups=networking.datumapis.com,resources=httpproxies,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=networking.datumapis.com,resources=httpproxies/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=networking.datumapis.com,resources=httpproxies/finalizers,verbs=update
// +kubebuilder:rbac:groups=networking.datumapis.com,resources=connectors,verbs=get;list;watch
// +kubebuilder:rbac:groups=gateway.envoyproxy.io,resources=httproutefilters,verbs=get;list;watch;create;update;patch;delete
// HTTPProxy controller reads cert-manager Certificate resources in the downstream cluster for status; ensure downstream role has cert-manager.io/certificates get;list;watch.

func (r *HTTPProxyReconciler) Reconcile(ctx context.Context, req mcreconcile.Request) (_ ctrl.Result, err error) {
	logger := log.FromContext(ctx, "cluster", req.ClusterName)
	ctx = log.IntoContext(ctx, logger)

	cl, err := r.mgr.GetCluster(ctx, req.ClusterName)
	if err != nil {
		return ctrl.Result{}, err
	}

	var httpProxy networkingv1alpha.HTTPProxy
	if err := cl.GetClient().Get(ctx, req.NamespacedName, &httpProxy); err != nil {
		if apierrors.IsNotFound(err) {
			return ctrl.Result{}, nil
		}
		return ctrl.Result{}, err
	}

	if !httpProxy.DeletionTimestamp.IsZero() {
		if controllerutil.ContainsFinalizer(&httpProxy, httpProxyFinalizer) {
			if err := r.cleanupConnectorEnvoyPatchPolicy(ctx, cl.GetClient(), string(req.ClusterName), &httpProxy); err != nil {
				return ctrl.Result{}, err
			}
			controllerutil.RemoveFinalizer(&httpProxy, httpProxyFinalizer)
			if err := cl.GetClient().Update(ctx, &httpProxy); err != nil {
				return ctrl.Result{}, err
			}
		}
		return ctrl.Result{}, nil
	}

	logger.Info("reconciling httpproxy")
	defer logger.Info("reconcile complete")

	if !controllerutil.ContainsFinalizer(&httpProxy, httpProxyFinalizer) {
		controllerutil.AddFinalizer(&httpProxy, httpProxyFinalizer)
		if err := cl.GetClient().Update(ctx, &httpProxy); err != nil {
			return ctrl.Result{}, err
		}
		return ctrl.Result{}, nil
	}

	httpProxyCopy := httpProxy.DeepCopy()

	acceptedCondition := &metav1.Condition{
		Type:               networkingv1alpha.HTTPProxyConditionAccepted,
		Status:             metav1.ConditionFalse,
		Reason:             networkingv1alpha.HTTPProxyReasonPending,
		ObservedGeneration: httpProxy.Generation,
		Message:            "The HTTPProxy has not been scheduled",
	}

	programmedCondition := &metav1.Condition{
		Type:               networkingv1alpha.HTTPProxyConditionProgrammed,
		Status:             metav1.ConditionFalse,
		Reason:             networkingv1alpha.HTTPProxyReasonPending,
		ObservedGeneration: httpProxy.Generation,
		Message:            "The HTTPProxy has not been programmed",
	}

	tunnelMetadataCondition := &metav1.Condition{
		Type:               networkingv1alpha.HTTPProxyConditionConnectorMetadataProgrammed,
		Status:             metav1.ConditionFalse,
		Reason:             networkingv1alpha.HTTPProxyReasonPending,
		ObservedGeneration: httpProxy.Generation,
		Message:            "Waiting for envoy to be configured",
	}
	setTunnelMetadataCondition := false

	defer func() {
		apimeta.SetStatusCondition(&httpProxyCopy.Status.Conditions, *acceptedCondition)
		apimeta.SetStatusCondition(&httpProxyCopy.Status.Conditions, *programmedCondition)
		if setTunnelMetadataCondition {
			apimeta.SetStatusCondition(&httpProxyCopy.Status.Conditions, *tunnelMetadataCondition)
		} else {
			apimeta.RemoveStatusCondition(&httpProxyCopy.Status.Conditions, networkingv1alpha.HTTPProxyConditionConnectorMetadataProgrammed)
		}

		if !equality.Semantic.DeepEqual(httpProxy.Status, httpProxyCopy.Status) {
			httpProxy.Status = httpProxyCopy.Status
			if statusErr := cl.GetClient().Status().Update(ctx, &httpProxy); statusErr != nil {
				err = errors.Join(err, fmt.Errorf("failed updating httpproxy status: %w", statusErr))
			}
			logger.Info("httpproxy status updated")
		}
	}()

	desiredResources, err := r.collectDesiredResources(ctx, cl.GetClient(), &httpProxy)
	if err != nil {
		return ctrl.Result{}, fmt.Errorf("failed to collect desired resources: %w", err)
	}

	// Maintain a Gateway for the HTTPProxy, handle conflicts in names by updating the
	// Programmed condition with info about the conflict.

	gateway := desiredResources.gateway.DeepCopy()

	result, err := controllerutil.CreateOrUpdate(ctx, cl.GetClient(), gateway, func() error {
		if hasControllerConflict(gateway, &httpProxy) {
			// return already exists error - a gateway exists with the name we want to
			// use, but it's owned by a different resource.
			return apierrors.NewAlreadyExists(gatewayv1.Resource(KindGateway), gateway.Name)
		}

		if err := controllerutil.SetControllerReference(&httpProxy, gateway, cl.GetScheme()); err != nil {
			return fmt.Errorf("failed to set controller on gateway: %w", err)
		}

		// Special handling for default gateway listeners, as the hostnames will be
		// updated by the controller. Only required on updates.
		if !gateway.CreationTimestamp.IsZero() {
			defaultHTTPListener := gatewayutil.GetListenerByName(gateway.Spec.Listeners, gatewayutil.DefaultHTTPListenerName)
			if defaultHTTPListener != nil {
				gatewayutil.SetListener(desiredResources.gateway, *defaultHTTPListener)
			}

			defaultHTTPSListener := gatewayutil.GetListenerByName(gateway.Spec.Listeners, gatewayutil.DefaultHTTPSListenerName)
			if defaultHTTPSListener != nil {
				gatewayutil.SetListener(desiredResources.gateway, *defaultHTTPSListener)
			}
		}

		gateway.Spec = desiredResources.gateway.Spec

		return nil
	})
	if err != nil {
		if apierrors.IsAlreadyExists(err) {
			programmedCondition.Status = metav1.ConditionFalse
			programmedCondition.Reason = networkingv1alpha.HTTPProxyReasonConflict
			programmedCondition.Message = fmt.Sprintf("Underlying Gateway with the name %q already exists and is owned by a different resource.", gateway.Name)
			return ctrl.Result{}, nil
		}
		return ctrl.Result{}, fmt.Errorf("failed updating gateway resource: %w", err)
	}

	logger.Info("processed gateway", jsonKeyName, gateway.Name, "result", result)

	// Maintain an HTTPRoute for all rules in the HTTPProxy

	if len(desiredResources.httpRouteFilters) == 0 {
		if err := cleanupConnectorOfflineHTTPRouteFilter(ctx, cl.GetClient(), &httpProxy); err != nil {
			return ctrl.Result{}, err
		}
	} else {
		for _, desiredFilter := range desiredResources.httpRouteFilters {
			httpRouteFilter := desiredFilter.DeepCopy()
			result, err := controllerutil.CreateOrUpdate(ctx, cl.GetClient(), httpRouteFilter, func() error {
				if err := controllerutil.SetControllerReference(&httpProxy, httpRouteFilter, cl.GetScheme()); err != nil {
					return fmt.Errorf("failed to set controller on HTTPRouteFilter: %w", err)
				}
				httpRouteFilter.Spec = desiredFilter.Spec
				return nil
			})
			if err != nil {
				return ctrl.Result{}, fmt.Errorf("failed updating httproutefilter resource: %w", err)
			}
			logger.Info("processed httproutefilter", jsonKeyName, httpRouteFilter.Name, "result", result)
		}
	}

	httpRoute := desiredResources.httpRoute.DeepCopy()

	result, err = controllerutil.CreateOrUpdate(ctx, cl.GetClient(), httpRoute, func() error {
		if hasControllerConflict(httpRoute, &httpProxy) {
			// return already exists error - an httproute exists with the name we want to
			// use, but it's owned by a different resource.
			return apierrors.NewAlreadyExists(gatewayv1.Resource("HTTPRoute"), httpRoute.Name)
		}

		if err := controllerutil.SetControllerReference(&httpProxy, httpRoute, cl.GetScheme()); err != nil {
			return fmt.Errorf("failed to set controller on httproute: %w", err)
		}

		httpRoute.Spec = desiredResources.httpRoute.Spec

		return nil
	})
	if err != nil {
		if apierrors.IsAlreadyExists(err) {
			programmedCondition.Status = metav1.ConditionFalse
			programmedCondition.Reason = networkingv1alpha.HTTPProxyReasonConflict
			programmedCondition.Message = fmt.Sprintf("Underlying HTTPRoute with the name %q already exists and is owned by a different resource.", httpRoute.Name)
			return ctrl.Result{}, nil
		}
		return ctrl.Result{}, fmt.Errorf("failed updating httproute resource: %w", err)
	}

	logger.Info("processed httproute", jsonKeyName, httpRoute.Name, "result", result)

	for _, desiredEndpointSlice := range desiredResources.endpointSlices {
		endpointSlice := desiredEndpointSlice.DeepCopy()

		result, err := controllerutil.CreateOrUpdate(ctx, cl.GetClient(), endpointSlice, func() error {
			if hasControllerConflict(endpointSlice, &httpProxy) {
				// return already exists error - an endpointslice exists with the name we want to
				// use, but it's owned by a different resource.
				return apierrors.NewAlreadyExists(discoveryv1.Resource("EndpointSlice"), endpointSlice.Name)
			}

			if err := controllerutil.SetControllerReference(&httpProxy, endpointSlice, cl.GetScheme()); err != nil {
				return fmt.Errorf("failed to set controller reference on endpointslice: %w", err)
			}

			endpointSlice.AddressType = desiredEndpointSlice.AddressType
			endpointSlice.Endpoints = desiredEndpointSlice.Endpoints
			endpointSlice.Ports = desiredEndpointSlice.Ports

			// Keep the backend cert hostname annotation in sync. The gateway
			// controller reads this to build the BackendTLSPolicy when the
			// URLRewrite filter carries a user Host override instead of the
			// real backend FQDN.
			if v, ok := desiredEndpointSlice.Annotations[BackendCertHostnameAnnotation]; ok {
				if endpointSlice.Annotations == nil {
					endpointSlice.Annotations = map[string]string{}
				}
				endpointSlice.Annotations[BackendCertHostnameAnnotation] = v
			} else {
				delete(endpointSlice.Annotations, BackendCertHostnameAnnotation)
			}
			return nil
		})

		if err != nil {
			if apierrors.IsAlreadyExists(err) {
				programmedCondition.Status = metav1.ConditionFalse
				programmedCondition.Reason = networkingv1alpha.HTTPProxyReasonConflict
				programmedCondition.Message = fmt.Sprintf("Underlying EndpointSlice with the name %q already exists and is owned by a different resource.", endpointSlice.Name)
				return ctrl.Result{}, nil
			}

			return ctrl.Result{}, fmt.Errorf("failed to create or update endpointslice: %w", err)
		}

		logger.Info("processed endpointslice", "result", result, jsonKeyName, desiredEndpointSlice.Name)
	}

	// Gate connector EPP emission behind the feature flag. When disabled the
	// extension server handles connector xDS mutation via PostTranslateModify;
	// NSO emits ZERO connector EPPs and does NOT delete existing ones.
	// patchPolicy=nil and hasConnectorBackends=false causes the
	// ConnectorMetadataProgrammed condition to be cleared (not tracked by NSO
	// when the extension server owns this path).
	var patchPolicy *envoygatewayv1alpha1.EnvoyPatchPolicy
	var hasConnectorBackends bool
	if r.Config.Gateway.IsEPPEmissionEnabled() {
		patchPolicy, hasConnectorBackends, err = r.reconcileConnectorEnvoyPatchPolicy(
			ctx,
			cl.GetClient(),
			string(req.ClusterName),
			&httpProxy,
			gateway,
		)
		if err != nil {
			programmedCondition.Status = metav1.ConditionFalse
			programmedCondition.Reason = networkingv1alpha.HTTPProxyReasonPending
			programmedCondition.Message = err.Error()
			return ctrl.Result{}, err
		}
	}

	httpProxyCopy.Status.Addresses = gateway.Status.Addresses

	if c := apimeta.FindStatusCondition(gateway.Status.Conditions, string(gatewayv1.GatewayConditionAccepted)); c != nil {
		logger.Info("gateway accepted status", "status", c.Status)
		if c.Status == metav1.ConditionTrue {
			acceptedCondition.Status = metav1.ConditionTrue
			acceptedCondition.Reason = networkingv1alpha.HTTPProxyReasonAccepted
			acceptedCondition.Message = "The HTTPProxy has been scheduled"
		} else {
			acceptedCondition.Reason = c.Reason
		}
	}

	if c := apimeta.FindStatusCondition(gateway.Status.Conditions, string(gatewayv1.GatewayConditionProgrammed)); c != nil {
		if c.Status == metav1.ConditionTrue {
			programmedCondition.Status = metav1.ConditionTrue
			programmedCondition.Reason = networkingv1alpha.HTTPProxyReasonProgrammed
			programmedCondition.Message = "The HTTPProxy has been programmed"
		} else {
			programmedCondition.Reason = c.Reason
		}
	}

	if hasConnectorBackends {
		connectorPolicyReady, connectorPolicyMessage := downstreamPatchPolicyReady(
			patchPolicy,
			r.Config.Gateway.DownstreamGatewayClassName,
		)
		if !connectorPolicyReady {
			programmedCondition.Status = metav1.ConditionFalse
			programmedCondition.Reason = networkingv1alpha.HTTPProxyReasonPending
			if connectorPolicyMessage == "" {
				connectorPolicyMessage = "Waiting for downstream EnvoyPatchPolicy to be accepted and programmed"
			}
			programmedCondition.Message = connectorPolicyMessage

			tunnelMetadataCondition.Status = metav1.ConditionFalse
			tunnelMetadataCondition.Reason = networkingv1alpha.HTTPProxyReasonPending
			tunnelMetadataCondition.Message = connectorPolicyMessage
		} else {
			tunnelMetadataCondition.Status = metav1.ConditionTrue
			tunnelMetadataCondition.Reason = networkingv1alpha.HTTPProxyReasonConnectorMetadataApplied
			tunnelMetadataCondition.Message = "Connector tunnel metadata applied"
		}
		setTunnelMetadataCondition = true
	} else {
		apimeta.RemoveStatusCondition(&httpProxyCopy.Status.Conditions, networkingv1alpha.HTTPProxyConditionConnectorMetadataProgrammed)
	}

	r.reconcileHTTPProxyHostnameStatus(ctx, cl.GetClient(), gateway, httpProxyCopy, string(req.ClusterName))

	return ctrl.Result{}, nil
}

func (r *HTTPProxyReconciler) reconcileHTTPProxyHostnameStatus(
	ctx context.Context,
	cl client.Client,
	gateway *gatewayv1.Gateway,
	httpProxyCopy *networkingv1alpha.HTTPProxy,
	clusterName string,
) {
	logger := log.FromContext(ctx)

	gatewayAcceptedCondition := apimeta.FindStatusCondition(gateway.Status.Conditions, string(gatewayv1.GatewayConditionAccepted))
	if gatewayAcceptedCondition == nil {
		// Should never happen due to defaulting, but just in case
		logger.Info("accepted condition not found on gateway")
		return
	} else if gatewayAcceptedCondition.ObservedGeneration != gateway.Generation {
		logger.Info(
			"observed generation on accepted condition does not match generation on gateway, delaying processing",
			"gateway_generation", gateway.Generation,
			"condition_generation", gatewayAcceptedCondition.ObservedGeneration,
		)
		return
	}
	logger.Info("updating hostname status")

	// CanonicalHostname is the platform-managed hostname we create for the HTTPProxy.
	httpProxyCopy.Status.CanonicalHostname = gatewayCanonicalHostnameForConfig(r.Config.Gateway, gateway)

	currentListenerStatus := map[gatewayv1.SectionName]gatewayv1.ListenerStatus{}
	for _, listener := range gateway.Status.Listeners {
		currentListenerStatus[listener.Name] = *listener.DeepCopy()
	}

	acceptedHostnames := sets.New[gatewayv1.Hostname]()
	nonAcceptedHostnames := sets.New[string]()
	inUseHostnames := sets.New[string]()
	for _, listener := range gateway.Spec.Listeners {
		if listener.Hostname == nil {
			// Should only happen shortly after creation, before the default hostnames
			// are assigned
			continue
		}

		listenerStatus, ok := currentListenerStatus[listener.Name]
		if !ok {
			logger.Info("listener status not found", "listener_name", listener.Name)
			continue
		}

		listenerAcceptedCondition := apimeta.FindStatusCondition(listenerStatus.Conditions, string(gatewayv1.ListenerConditionAccepted))
		if listenerAcceptedCondition != nil {
			if listenerAcceptedCondition.Status == metav1.ConditionTrue {
				acceptedHostnames.Insert(*listener.Hostname)
			} else if listenerAcceptedCondition.Reason == networkingv1alpha.HostnameInUseReason {
				inUseHostnames.Insert(string(*listener.Hostname))
			} else {
				nonAcceptedHostnames.Insert(string(*listener.Hostname))
			}
		} else {
			nonAcceptedHostnames.Insert(string(*listener.Hostname))
		}
	}

	acceptedHostnamesSlice := acceptedHostnames.UnsortedList()
	slices.Sort(acceptedHostnamesSlice)
	hostnames := make([]gatewayv1.Hostname, 0, len(acceptedHostnamesSlice))
	//nolint:staticcheck // SA1019: Hostnames is deprecated but still populated for backwards compatibility
	httpProxyCopy.Status.Hostnames = append(hostnames, acceptedHostnamesSlice...)

	if len(httpProxyCopy.Spec.Hostnames) > 0 {
		hostnamesVerifiedCondition := conditionutil.FindStatusConditionOrDefault(httpProxyCopy.Status.Conditions, &metav1.Condition{
			Type:   networkingv1alpha.HTTPProxyConditionHostnamesVerified,
			Status: metav1.ConditionFalse,
		})
		hostnamesVerifiedCondition.ObservedGeneration = httpProxyCopy.Generation

		if nonAcceptedHostnames.Len() > 0 {
			nonAcceptedHostnamesSlice := nonAcceptedHostnames.UnsortedList()
			slices.Sort(nonAcceptedHostnamesSlice)
			hostnamesVerifiedCondition.Status = metav1.ConditionFalse
			hostnamesVerifiedCondition.Reason = networkingv1alpha.UnverifiedHostnamesPresent
			hostnamesVerifiedCondition.Message = fmt.Sprintf("unverified hostnames present, check status of Domains in the same namespace: %s", strings.Join(nonAcceptedHostnamesSlice, ","))
		} else if acceptedHostnames.Len() == len(httpProxyCopy.Spec.Hostnames) || acceptedHostnames.Len() == len(httpProxyCopy.Spec.Hostnames)+1 {
			// acceptedHostnames may contain the default listener hostname if it has
			// not been removed by the user.
			hostnamesVerifiedCondition.Status = metav1.ConditionTrue
			hostnamesVerifiedCondition.Reason = networkingv1alpha.HTTPProxyReasonHostnamesVerified
			hostnamesVerifiedCondition.Message = "All hostnames have been accepted and programmed"
		} else {
			hostnamesVerifiedCondition.Status = metav1.ConditionFalse
			hostnamesVerifiedCondition.Reason = networkingv1alpha.HTTPProxyReasonPending
			hostnamesVerifiedCondition.Message = "Pending downstream Gateway status updates"
		}

		apimeta.SetStatusCondition(&httpProxyCopy.Status.Conditions, *hostnamesVerifiedCondition)

		if inUseHostnames.Len() > 0 {
			inUseHostnamesSlice := inUseHostnames.UnsortedList()
			slices.Sort(inUseHostnamesSlice)
			apimeta.SetStatusCondition(&httpProxyCopy.Status.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HTTPProxyConditionHostnamesInUse,
				Status:             metav1.ConditionTrue,
				ObservedGeneration: httpProxyCopy.Generation,
				Reason:             networkingv1alpha.HostnameInUseReason,
				Message:            fmt.Sprintf("Hostnames are already attached to another resource: %s", strings.Join(inUseHostnamesSlice, ",")),
			})
		} else {
			apimeta.RemoveStatusCondition(&httpProxyCopy.Status.Conditions, networkingv1alpha.HTTPProxyConditionHostnamesInUse)
		}
	} else {
		apimeta.RemoveStatusCondition(&httpProxyCopy.Status.Conditions, networkingv1alpha.HTTPProxyConditionHostnamesVerified)
		apimeta.RemoveStatusCondition(&httpProxyCopy.Status.Conditions, networkingv1alpha.HTTPProxyConditionHostnamesInUse)
	}

	// Build per-hostname statuses
	availabilityStatuses := buildAvailabilityStatuses(acceptedHostnames, inUseHostnames, httpProxyCopy.Generation)
	dnsStatuses := r.buildDNSStatuses(ctx, cl, gateway, httpProxyCopy.Generation)
	certificateStatuses := r.buildCertificateStatuses(ctx, cl, clusterName, gateway, httpProxyCopy)
	previousHostnameStatuses := httpProxyCopy.Status.HostnameStatuses
	httpProxyCopy.Status.HostnameStatuses = mergeHostnameStatuses(availabilityStatuses, dnsStatuses, certificateStatuses)
	preserveHostnameConditionTransitions(httpProxyCopy.Status.HostnameStatuses, previousHostnameStatuses)

	r.setCertificatesReadyCondition(httpProxyCopy, certificateStatuses, gateway)
}

// SetupWithManager sets up the controller with the Manager.
func (r *HTTPProxyReconciler) SetupWithManager(mgr mcmanager.Manager) error {
	r.mgr = mgr

	builder := mcbuilder.ControllerManagedBy(mgr).
		For(&networkingv1alpha.HTTPProxy{}).
		Owns(&gatewayv1.Gateway{}).
		Owns(&gatewayv1.HTTPRoute{}).
		Owns(&discoveryv1.EndpointSlice{}).
		// Watch Connectors and reconcile HTTPProxies that reference them.
		// This ensures EnvoyPatchPolicy headers are updated when a Connector's
		// publicKey.id changes (e.g., after connector restart/reconnect).
		Watches(
			&networkingv1alpha1.Connector{},
			func(clusterName multicluster.ClusterName, cl cluster.Cluster) handler.TypedEventHandler[client.Object, mcreconcile.Request] {
				return handler.TypedEnqueueRequestsFromMapFunc(func(ctx context.Context, obj client.Object) []mcreconcile.Request {
					logger := log.FromContext(ctx)

					connector, ok := obj.(*networkingv1alpha1.Connector)
					if !ok {
						return nil
					}

					// List all HTTPProxies in the same namespace
					var httpProxies networkingv1alpha.HTTPProxyList
					if err := cl.GetClient().List(ctx, &httpProxies, client.InNamespace(connector.Namespace)); err != nil {
						logger.Error(err, "failed to list HTTPProxies for Connector watch", "connector", connector.Name)
						return nil
					}

					var requests []mcreconcile.Request
					for i := range httpProxies.Items {
						httpProxy := &httpProxies.Items[i]
						// Check if this HTTPProxy references the changed Connector
						if httpProxyReferencesConnector(httpProxy, connector.Name) {
							requests = append(requests, mcreconcile.Request{
								ClusterName: clusterName,
								Request: ctrl.Request{
									NamespacedName: client.ObjectKeyFromObject(httpProxy),
								},
							})
						}
					}

					if len(requests) > 0 {
						logger.Info("Connector changed, requeueing HTTPProxies",
							"connector", connector.Name,
							"httpProxyCount", len(requests))
					}

					return requests
				})
			},
		)

	if r.DownstreamCluster != nil {
		downstreamPolicySource := mcsource.TypedKind(
			&envoygatewayv1alpha1.EnvoyPatchPolicy{},
			downstreamclient.TypedEnqueueRequestForUpstreamOwner[*envoygatewayv1alpha1.EnvoyPatchPolicy](&networkingv1alpha.HTTPProxy{}),
		)

		downstreamPolicyClusterSource, _, _ := downstreamPolicySource.ForCluster("", r.DownstreamCluster)
		builder = builder.WatchesRawSource(downstreamPolicyClusterSource)

		// Watch downstream cert-manager Certificates so HTTPProxy certificate status
		// is updated when certificates become ready or fail.
		downstreamCertificateSource := mcsource.TypedKind(
			newUnstructuredForGVK(certificateGVK),
			r.enqueueHTTPProxyForDownstreamCertificate(),
		)
		downstreamCertificateClusterSource, _, _ := downstreamCertificateSource.ForCluster("", r.DownstreamCluster)
		builder = builder.WatchesRawSource(downstreamCertificateClusterSource)
	}

	return builder.Named("httpproxy").Complete(r)
}

// enqueueHTTPProxyForDownstreamCertificate returns a watch handler that enqueues
// the HTTPProxy (same name/namespace as the owning Gateway) when a downstream
// cert-manager Certificate changes, so certificate status is updated.
func (r *HTTPProxyReconciler) enqueueHTTPProxyForDownstreamCertificate() func(clusterName multicluster.ClusterName, cl cluster.Cluster) handler.TypedEventHandler[*unstructured.Unstructured, mcreconcile.Request] {
	return func(_ multicluster.ClusterName, cl cluster.Cluster) handler.TypedEventHandler[*unstructured.Unstructured, mcreconcile.Request] {
		return handler.TypedEnqueueRequestsFromMapFunc(func(ctx context.Context, cert *unstructured.Unstructured) []mcreconcile.Request {
			logger := log.FromContext(ctx)
			ownerRef := metav1.GetControllerOf(cert)
			if ownerRef == nil {
				return nil
			}
			if ownerRef.Kind != KindGateway {
				return nil
			}
			gatewayKey := client.ObjectKey{Namespace: cert.GetNamespace(), Name: ownerRef.Name}
			var gateway gatewayv1.Gateway
			if err := cl.GetClient().Get(ctx, gatewayKey, &gateway); err != nil {
				if apierrors.IsNotFound(err) {
					return nil
				}
				logger.Error(err, "failed to get Gateway owner of Certificate", "certificate", cert.GetName(), "gateway", gatewayKey)
				return nil
			}
			labels := gateway.GetLabels()
			upstreamNs := labels[downstreamclient.UpstreamOwnerNamespaceLabel]
			upstreamName := labels[downstreamclient.UpstreamOwnerNameLabel]
			upstreamCluster := labels[downstreamclient.UpstreamOwnerClusterNameLabel]
			if upstreamNs == "" || upstreamName == "" || upstreamCluster == "" {
				return nil
			}
			clusterName := multicluster.ClusterName(downstreamclient.UpstreamClusterNameFromLabel(upstreamCluster))
			return []mcreconcile.Request{{
				ClusterName: clusterName,
				Request:     ctrl.Request{NamespacedName: types.NamespacedName{Namespace: upstreamNs, Name: upstreamName}},
			}}
		})
	}
}

// httpProxyReferencesConnector checks if an HTTPProxy has any backends
// that reference the given Connector name.
func httpProxyReferencesConnector(httpProxy *networkingv1alpha.HTTPProxy, connectorName string) bool {
	for _, rule := range httpProxy.Spec.Rules {
		for _, backend := range rule.Backends {
			if backend.Connector != nil && backend.Connector.Name == connectorName {
				return true
			}
		}
	}
	return false
}

// extractHostHeaderOverride returns the Host header value from a
// RequestHeaderModifier filter, if present. Header names are matched
// case-insensitively per RFC 7230. The returned bool indicates whether a
// Host header override was found.
//
// Envoy Gateway does not accept Host header manipulation via
// RequestHeaderModifier — it must go through URLRewrite.Hostname instead.
// collectDesiredResources uses this helper to translate the user-facing
// RequestHeaderModifier{Host} shape (which round-trips with datumctl and
// the cloud portal) into the URLRewrite{Hostname} that Envoy actually
// honours at egress.
func extractHostHeaderOverride(filters []gatewayv1.HTTPRouteFilter) (string, bool) {
	for _, filter := range filters {
		if filter.Type != gatewayv1.HTTPRouteFilterRequestHeaderModifier || filter.RequestHeaderModifier == nil {
			continue
		}
		for _, h := range filter.RequestHeaderModifier.Set {
			if strings.EqualFold(string(h.Name), "Host") {
				return h.Value, true
			}
		}
	}
	return "", false
}

// stripHostFromRequestHeaderModifier returns the filter list with any
// Host entry removed from each RequestHeaderModifier's Set list. If a
// RequestHeaderModifier ends up empty (no add/set/remove), the filter
// itself is dropped. This keeps Envoy Gateway from rejecting the route
// because of an "empty" RequestHeaderModifier after we've moved the
// Host override into URLRewrite.
func stripHostFromRequestHeaderModifier(filters []gatewayv1.HTTPRouteFilter) []gatewayv1.HTTPRouteFilter {
	out := make([]gatewayv1.HTTPRouteFilter, 0, len(filters))
	for _, filter := range filters {
		if filter.Type != gatewayv1.HTTPRouteFilterRequestHeaderModifier || filter.RequestHeaderModifier == nil {
			out = append(out, filter)
			continue
		}
		modifier := filter.RequestHeaderModifier
		filtered := make([]gatewayv1.HTTPHeader, 0, len(modifier.Set))
		for _, h := range modifier.Set {
			if strings.EqualFold(string(h.Name), "Host") {
				continue
			}
			filtered = append(filtered, h)
		}
		if len(filtered) == 0 && len(modifier.Add) == 0 && len(modifier.Remove) == 0 {
			// Drop the now-empty RequestHeaderModifier filter entirely.
			continue
		}
		newFilter := filter
		newModifier := *modifier
		newModifier.Set = filtered
		newFilter.RequestHeaderModifier = &newModifier
		out = append(out, newFilter)
	}
	return out
}

func (r *HTTPProxyReconciler) collectDesiredResources(
	ctx context.Context,
	cl client.Client,
	httpProxy *networkingv1alpha.HTTPProxy,
) (*desiredHTTPProxyResources, error) {

	gateway := &gatewayv1.Gateway{
		ObjectMeta: metav1.ObjectMeta{
			Namespace: httpProxy.Namespace,
			Name:      httpProxy.Name,
		},
		Spec: gatewayv1.GatewaySpec{
			GatewayClassName: r.Config.HTTPProxy.GatewayClassName,
		},
	}

	// Hostname fields will be nil on the default listeners until the gateway
	// controller updates them. There's special handling for this in the
	// CreateOrUpdate logic for maintaining the gateway.
	gatewayutil.SetDefaultListeners(gateway, r.Config.Gateway)

	// Add listeners for each hostname
	for i, hostname := range httpProxy.Spec.Hostnames {
		gateway.Spec.Listeners = append(gateway.Spec.Listeners, gatewayv1.Listener{
			Name:     gatewayv1.SectionName(fmt.Sprintf("%s-hostname-%d", SchemeHTTP, i)),
			Protocol: gatewayv1.HTTPProtocolType,
			Port:     DefaultHTTPPort,
			Hostname: ptr.To(hostname),
			AllowedRoutes: &gatewayv1.AllowedRoutes{
				Namespaces: &gatewayv1.RouteNamespaces{
					From: ptr.To(gatewayv1.NamespacesFromSame),
				},
			},
		})

		gateway.Spec.Listeners = append(gateway.Spec.Listeners, gatewayv1.Listener{
			Name:     gatewayv1.SectionName(fmt.Sprintf("%s-hostname-%d", SchemeHTTPS, i)),
			Protocol: gatewayv1.HTTPSProtocolType,
			Port:     DefaultHTTPSPort,
			Hostname: ptr.To(hostname),
			AllowedRoutes: &gatewayv1.AllowedRoutes{
				Namespaces: &gatewayv1.RouteNamespaces{
					From: ptr.To(gatewayv1.NamespacesFromSame),
				},
			},
			TLS: &gatewayv1.ListenerTLSConfig{
				Mode:    ptr.To(gatewayv1.TLSModeTerminate),
				Options: r.Config.Gateway.ListenerTLSOptions,
			},
		})
	}

	httpRoute := &gatewayv1.HTTPRoute{
		ObjectMeta: metav1.ObjectMeta{
			Namespace: httpProxy.Namespace,
			Name:      httpProxy.Name,
		},
		Spec: gatewayv1.HTTPRouteSpec{
			CommonRouteSpec: gatewayv1.CommonRouteSpec{
				ParentRefs: []gatewayv1.ParentReference{
					{
						Name: gatewayv1.ObjectName(gateway.Name),
					},
				},
			},
		},
	}

	var desiredEndpointSlices []*discoveryv1.EndpointSlice
	var desiredRouteFilters []*envoygatewayv1alpha1.HTTPRouteFilter

	desiredRouteRules := make([]gatewayv1.HTTPRouteRule, len(httpProxy.Spec.Rules))
	for ruleIndex, rule := range httpProxy.Spec.Rules {
		ruleFilters := slices.Clone(rule.Filters)
		backendRefs := make([]gatewayv1.HTTPBackendRef, len(rule.Backends))
		offlineRuleSet := false

		// Validation will prevent this from occurring, unless the maximum items for
		// backends is adjusted. The following error has been placed here so that
		// if/when that occurs, we're sure to address obvious programming changes
		// required (which should happen anyways, but just to be safe...).
		if len(rule.Backends) > 1 {
			return nil, fmt.Errorf("invalid number of backends for rule - expected 1 got %d", len(rule.Backends))
		}

		for backendIndex, backend := range rule.Backends {
			// Offline-connector handling differs by emission mode:
			//
			//   * EPP mode (legacy): emit a backend-less route rule. EG translates
			//     it into a virtual_host, and the connector EPP
			//     (buildConnectorOfflineEnvoyPatches) inserts the direct_response 503
			//     "Tunnel not online" CONNECT route at the front.
			//   * Extension-server mode: the ext-server keys its offline-503 handling
			//     on the presence of a connector *cluster*, which EG only emits when
			//     the route rule carries a backendRef. So we must NOT null the
			//     backendRef here — fall through and emit the same connector.local
			//     placeholder EndpointSlice + backendRef as the online case. The
			//     ext-server then sees the cluster, classifies the connector offline
			//     from the replicated Connector Ready condition, and inserts the 503
			//     route itself. Nulling the backendRef leaves EG with a backend-less
			//     route, which it renders as a bare direct_response 500 (no offline
			//     page) — the regression this guards against.
			if backend.Connector != nil && r.Config.Gateway.IsEPPEmissionEnabled() {
				ready, err := connectorReady(ctx, cl, httpProxy.Namespace, backend.Connector.Name)
				if err != nil {
					return nil, err
				}
				if !ready {
					// Connector is offline: keep the route rule with no backends so EG
					// can translate it (creating virtual_hosts). The connector EPP
					// (buildConnectorOfflineEnvoyPatches) inserts a direct_response CONNECT
					// route at the front, which is the canonical offline-503 mechanism.
					// Do NOT add an ExtensionRef→HTTPRouteFilter.DirectResponse here:
					// EG v1.7.3 cannot translate that filter shape and the HTTPRoute
					// status would show UnsupportedValue, preventing EPP programming.
					desiredRouteRules[ruleIndex] = gatewayv1.HTTPRouteRule{
						Name:        rule.Name,
						Matches:     rule.Matches,
						Filters:     ruleFilters,
						BackendRefs: nil,
					}
					offlineRuleSet = true
					break
				}
			}

			appProtocol := SchemeHTTP
			backendPort := DefaultHTTPPort

			u, err := url.Parse(backend.Endpoint)
			if err != nil {
				return nil, fmt.Errorf("failed parsing endpoint for backend %d in rule %d: %w", backendIndex, ruleIndex, err)
			}

			if u.Scheme == SchemeHTTPS {
				backendPort = DefaultHTTPSPort
				appProtocol = SchemeHTTPS
			}

			if endpointPort := u.Port(); endpointPort != "" {
				backendPort, err = strconv.Atoi(endpointPort)
				if err != nil {
					return nil, fmt.Errorf("failed parsing endpoint port for backend %d in rule %d: %w", backendIndex, ruleIndex, err)
				}
			}

			// TODO(jreese) Move away from FQDN and EndpointSlices
			//
			// The FQDN AddressType has been deprecated, but as we control the
			// programming of an HTTPProxy, we can easily transition to an alternative
			// once we have one. This is in an effort to not block MVP goals.
			addressType := discoveryv1.AddressTypeFQDN

			host := u.Hostname()
			endpointHost := host
			isIPAddress := false
			if backend.Connector != nil {
				// Connector backends don't rely on EndpointSlice addresses; use a safe placeholder.
				endpointHost = "connector.local"
				addressType = discoveryv1.AddressTypeFQDN
			} else if ip := net.ParseIP(host); ip != nil {
				isIPAddress = true
				if i := ip.To4(); i != nil && len(i) == net.IPv4len {
					addressType = discoveryv1.AddressTypeIPv4
				} else {
					addressType = discoveryv1.AddressTypeIPv6
				}
			}

			// Resolve the user's Host header override, if any. Envoy Gateway
			// rejects RequestHeaderModifier filters that touch Host; the Host
			// rewrite must be expressed as URLRewrite.Hostname instead. We
			// translate the user-facing RequestHeaderModifier{Host} shape
			// (which is what datumctl and the cloud portal write) into the
			// URLRewrite.Hostname value Envoy will honour at egress, then
			// strip the now-redundant Host entry from the RequestHeaderModifier
			// so EG doesn't see the conflicting combination.
			userHostOverride, hasUserHost := extractHostHeaderOverride(ruleFilters)
			if !hasUserHost {
				userHostOverride, hasUserHost = extractHostHeaderOverride(backend.Filters)
			}
			if hasUserHost {
				ruleFilters = stripHostFromRequestHeaderModifier(ruleFilters)
				backend.Filters = stripHostFromRequestHeaderModifier(backend.Filters)
			}

			// Track the backend cert hostname separately from the Host
			// rewrite value. The two can diverge when the user sets a Host
			// override — URLRewrite.Hostname carries the user's value to
			// Envoy, while certHostname (propagated via an EndpointSlice
			// annotation and read by the gateway controller) is used for
			// BackendTLSPolicy SAN validation against the real backend.
			var certHostname string

			// For HTTPS endpoints with IP addresses, require tls.hostname for certificate validation
			// and use it as the Host header for the upstream request.
			if u.Scheme == SchemeHTTPS && isIPAddress {
				if backend.TLS == nil || backend.TLS.Hostname == nil || *backend.TLS.Hostname == "" {
					return nil, fmt.Errorf("HTTPS endpoint with IP address requires tls.hostname for backend %d in rule %d", backendIndex, ruleIndex)
				}
				certHostname = *backend.TLS.Hostname
				rewriteHostname := certHostname
				if hasUserHost {
					rewriteHostname = userHostOverride
				}
				// Use tls.hostname (or the user override) for the Host header rewrite
				hostnameRewriteFound := false
				for i, filter := range ruleFilters {
					if filter.Type == gatewayv1.HTTPRouteFilterURLRewrite {
						ruleFilters[i].URLRewrite.Hostname = ptr.To(gatewayv1.PreciseHostname(rewriteHostname))
						hostnameRewriteFound = true
						break
					}
				}
				if !hostnameRewriteFound {
					ruleFilters = append(ruleFilters, gatewayv1.HTTPRouteFilter{
						Type: gatewayv1.HTTPRouteFilterURLRewrite,
						URLRewrite: &gatewayv1.HTTPURLRewriteFilter{
							Hostname: ptr.To(gatewayv1.PreciseHostname(rewriteHostname)),
						},
					})
				}
			} else if !isIPAddress && backend.Connector == nil {
				// For FQDN endpoints, rewrite the Host header to match the
				// backend hostname — or to the user's override if they set
				// one via RequestHeaderModifier.
				certHostname = host
				rewriteHostname := host
				if hasUserHost {
					rewriteHostname = userHostOverride
				}
				hostnameRewriteFound := false
				for i, filter := range ruleFilters {
					if filter.Type == gatewayv1.HTTPRouteFilterURLRewrite {
						ruleFilters[i].URLRewrite.Hostname = ptr.To(gatewayv1.PreciseHostname(rewriteHostname))
						hostnameRewriteFound = true
						break
					}
				}

				if !hostnameRewriteFound {
					ruleFilters = append(ruleFilters, gatewayv1.HTTPRouteFilter{
						Type: gatewayv1.HTTPRouteFilterURLRewrite,
						URLRewrite: &gatewayv1.HTTPURLRewriteFilter{
							Hostname: ptr.To(gatewayv1.PreciseHostname(rewriteHostname)),
						},
					})
				}
			}

			epAnnotations := map[string]string{}
			if certHostname != "" {
				// Surface the backend cert hostname so the gateway controller
				// can build the BackendTLSPolicy without relying on the
				// URLRewrite filter (which may now carry a user-supplied Host
				// override instead of the real backend FQDN).
				epAnnotations[BackendCertHostnameAnnotation] = certHostname
			}
			endpointSlice := &discoveryv1.EndpointSlice{
				ObjectMeta: metav1.ObjectMeta{
					Namespace:   httpProxy.Namespace,
					Name:        fmt.Sprintf("%s-%d-%d", httpProxy.Name, ruleIndex, backendIndex),
					Annotations: epAnnotations,
				},
				AddressType: addressType,
				Endpoints: []discoveryv1.Endpoint{
					{
						Addresses: []string{
							endpointHost,
						},
						Conditions: discoveryv1.EndpointConditions{
							Ready:       ptr.To(true),
							Serving:     ptr.To(true),
							Terminating: ptr.To(false),
						},
					},
				},
				Ports: []discoveryv1.EndpointPort{
					{
						Name:        ptr.To(fmt.Sprintf("httpproxy-%d-%d", ruleIndex, backendIndex)),
						Protocol:    ptr.To(v1.ProtocolTCP),
						AppProtocol: ptr.To(appProtocol),
						Port:        ptr.To(int32(backendPort)),
					},
				},
			}

			desiredEndpointSlices = append(desiredEndpointSlices, endpointSlice)

			backendRefs[backendIndex] = gatewayv1.HTTPBackendRef{
				BackendRef: gatewayv1.BackendRef{
					BackendObjectReference: gatewayv1.BackendObjectReference{
						Group: ptr.To(gatewayv1.Group("discovery.k8s.io")),
						Kind:  ptr.To(gatewayv1.Kind("EndpointSlice")),
						Name:  gatewayv1.ObjectName(endpointSlice.Name),
						Port:  ptr.To(gatewayv1.PortNumber(backendPort)),
					},
				},
				Filters: backend.Filters,
			}
		}

		if offlineRuleSet {
			continue
		}

		desiredRouteRules[ruleIndex] = gatewayv1.HTTPRouteRule{
			Name:        rule.Name,
			Matches:     rule.Matches,
			Filters:     ruleFilters,
			BackendRefs: backendRefs,
		}
	}

	httpRoute.Spec.Rules = desiredRouteRules

	return &desiredHTTPProxyResources{
		gateway:          gateway,
		httpRoute:        httpRoute,
		endpointSlices:   desiredEndpointSlices,
		httpRouteFilters: desiredRouteFilters,
	}, nil
}

func hasControllerConflict(obj, owner metav1.Object) bool {
	if t := obj.GetCreationTimestamp(); t.IsZero() {
		return false
	}

	return controllerutil.HasControllerReference(obj) && !metav1.IsControlledBy(obj, owner)
}

// buildAvailabilityStatuses builds HostnameStatus entries with the Available
// condition based on which hostnames were accepted vs in-use.
func buildAvailabilityStatuses(
	acceptedHostnames sets.Set[gatewayv1.Hostname],
	inUseHostnames sets.Set[string],
	generation int64,
) []networkingv1alpha.HostnameStatus {
	statuses := make([]networkingv1alpha.HostnameStatus, 0, acceptedHostnames.Len()+inUseHostnames.Len())

	for hostname := range acceptedHostnames {
		hs := networkingv1alpha.HostnameStatus{Hostname: string(hostname)}
		apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
			Type:               networkingv1alpha.HostnameConditionAvailable,
			Status:             metav1.ConditionTrue,
			Reason:             networkingv1alpha.HostnameAvailableReasonClaimed,
			Message:            "Hostname successfully claimed",
			ObservedGeneration: generation,
		})
		statuses = append(statuses, hs)
	}

	for hostname := range inUseHostnames {
		hs := networkingv1alpha.HostnameStatus{Hostname: hostname}
		apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
			Type:               networkingv1alpha.HostnameConditionAvailable,
			Status:             metav1.ConditionFalse,
			Reason:             networkingv1alpha.HostnameAvailableReasonInUse,
			Message:            "Hostname is already in use by another resource",
			ObservedGeneration: generation,
		})
		statuses = append(statuses, hs)
	}

	return statuses
}

// buildDNSStatuses queries DNSRecordSets owned by the Gateway and builds
// HostnameStatus entries with the DNSRecordProgrammed condition.
func (r *HTTPProxyReconciler) buildDNSStatuses(
	ctx context.Context,
	cl client.Client,
	gateway *gatewayv1.Gateway,
	generation int64,
) []networkingv1alpha.HostnameStatus {
	if !r.Config.Gateway.EnableDNSIntegration {
		return nil
	}

	logger := log.FromContext(ctx)

	var recordSets dnsv1alpha1.DNSRecordSetList
	if err := cl.List(ctx, &recordSets,
		client.InNamespace(gateway.Namespace),
		client.MatchingLabels{
			labelDNSManaged:    labelValueTrue,
			labelDNSSourceKind: KindGateway,
			labelDNSSourceName: gateway.Name,
		},
	); err != nil {
		// Log error but don't fail - DNS statuses are supplementary
		logger.Error(err, "failed to list DNSRecordSets for hostname status")
		return nil
	}

	statuses := make([]networkingv1alpha.HostnameStatus, 0, len(recordSets.Items))
	for _, rs := range recordSets.Items {
		hostname := rs.Annotations[annotationDNSHostname]
		if hostname == "" {
			continue
		}

		hs := networkingv1alpha.HostnameStatus{Hostname: hostname}

		// Check DNSRecordSet's Programmed condition
		programmedCond := apimeta.FindStatusCondition(rs.Status.Conditions, conditionTypeProgrammed)
		if programmedCond != nil && programmedCond.Status == metav1.ConditionTrue {
			apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HostnameConditionDNSRecordProgrammed,
				Status:             metav1.ConditionTrue,
				Reason:             networkingv1alpha.DNSRecordReasonCreated,
				Message:            "DNS record is programmed",
				ObservedGeneration: generation,
			})
		} else {
			reason := networkingv1alpha.DNSRecordReasonPending
			message := "DNS record is pending"
			if programmedCond != nil {
				reason = programmedCond.Reason
				message = programmedCond.Message
			}
			apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HostnameConditionDNSRecordProgrammed,
				Status:             metav1.ConditionFalse,
				Reason:             reason,
				Message:            message,
				ObservedGeneration: generation,
			})
		}

		statuses = append(statuses, hs)
	}

	return statuses
}

// buildCertificateStatuses reads cert-manager Certificate resources from the
// downstream cluster for each HTTPS listener and returns HostnameStatus entries
// with the CertificateReady condition set. Returns nil when DownstreamCluster is
// nil (downstream unavailable).
func (r *HTTPProxyReconciler) buildCertificateStatuses(
	ctx context.Context,
	upstreamClient client.Client,
	clusterName string,
	gateway *gatewayv1.Gateway,
	httpProxy *networkingv1alpha.HTTPProxy,
) []networkingv1alpha.HostnameStatus {
	if r.DownstreamCluster == nil {
		return nil
	}

	downstreamStrategy := downstreamclient.NewMappedNamespaceResourceStrategy(
		clusterName,
		upstreamClient,
		r.DownstreamCluster.GetClient(),
	)
	downstreamNamespaceName, err := downstreamStrategy.GetDownstreamNamespaceNameForUpstreamNamespace(ctx, httpProxy.Namespace)
	if err != nil {
		log.FromContext(ctx).Error(err, "failed to get downstream namespace for certificate status")
		return nil
	}

	downstreamClient := downstreamStrategy.GetClient()
	httpsListenerCount := 0
	for _, l := range gateway.Spec.Listeners {
		if l.Protocol == gatewayv1.HTTPSProtocolType && l.Hostname != nil {
			httpsListenerCount++
		}
	}
	statuses := make([]networkingv1alpha.HostnameStatus, 0, httpsListenerCount)

	wildcardSuffix := "." + r.Config.Gateway.TargetDomain

	for _, l := range gateway.Spec.Listeners {
		if l.Protocol != gatewayv1.HTTPSProtocolType || l.Hostname == nil {
			continue
		}

		hs := networkingv1alpha.HostnameStatus{Hostname: string(*l.Hostname)}

		hostname := string(*l.Hostname)
		hostnameUnderWildcard := strings.HasSuffix(hostname, wildcardSuffix) || hostname == r.Config.Gateway.TargetDomain
		useSharedTLS := hostnameUnderWildcard && r.Config.Gateway.HasDefaultListenerTLSSecret()

		if useSharedTLS {
			apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HostnameConditionCertificateReady,
				Status:             metav1.ConditionTrue,
				Reason:             networkingv1alpha.CertificateReadyReasonCertificateIssued,
				Message:            "Using shared wildcard TLS certificate",
				ObservedGeneration: httpProxy.Generation,
			})
			statuses = append(statuses, hs)
			continue
		}

		certName := resourcename.GetValidDNS1123Name(fmt.Sprintf("%s-%s", gateway.Name, l.Name))
		certificate := newUnstructuredForGVK(certificateGVK)
		certKey := client.ObjectKey{Namespace: downstreamNamespaceName, Name: certName}

		if err := downstreamClient.Get(ctx, certKey, certificate); err != nil {
			if apierrors.IsNotFound(err) {
				apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
					Type:               networkingv1alpha.HostnameConditionCertificateReady,
					Status:             metav1.ConditionFalse,
					Reason:             networkingv1alpha.CertificateReadyReasonPending,
					Message:            "Certificate not found in downstream cluster",
					ObservedGeneration: httpProxy.Generation,
				})
			} else {
				apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
					Type:               networkingv1alpha.HostnameConditionCertificateReady,
					Status:             metav1.ConditionUnknown,
					Reason:             networkingv1alpha.CertificateReadyReasonPending,
					Message:            fmt.Sprintf("Failed to get certificate: %v", err),
					ObservedGeneration: httpProxy.Generation,
				})
			}
			statuses = append(statuses, hs)
			continue
		}

		ready, err := isCertificateReady(certificate)
		if err != nil {
			apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HostnameConditionCertificateReady,
				Status:             metav1.ConditionUnknown,
				Reason:             networkingv1alpha.CertificateReadyReasonPending,
				Message:            fmt.Sprintf("Failed to check certificate status: %v", err),
				ObservedGeneration: httpProxy.Generation,
			})
			statuses = append(statuses, hs)
			continue
		}

		if ready {
			apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HostnameConditionCertificateReady,
				Status:             metav1.ConditionTrue,
				Reason:             networkingv1alpha.CertificateReadyReasonCertificateIssued,
				Message:            "Certificate is ready",
				ObservedGeneration: httpProxy.Generation,
			})
		} else {
			reason, message := getCertificateReadyConditionReason(certificate)
			apimeta.SetStatusCondition(&hs.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HostnameConditionCertificateReady,
				Status:             metav1.ConditionFalse,
				Reason:             reason,
				Message:            message,
				ObservedGeneration: httpProxy.Generation,
			})
		}
		statuses = append(statuses, hs)
	}

	return statuses
}

// getCertificateReadyConditionReason returns the reason and message for the
// CertificateReady condition based on the cert-manager Certificate's Ready condition.
func getCertificateReadyConditionReason(certificate *unstructured.Unstructured) (string, string) {
	conditions, found, err := unstructured.NestedSlice(certificate.Object, jsonKeyStatus, "conditions")
	if err != nil || !found {
		return networkingv1alpha.CertificateReadyReasonPending, "Certificate status not yet available"
	}

	for _, cond := range conditions {
		condMap, ok := cond.(map[string]any)
		if !ok {
			continue
		}
		if condMap[jsonKeyType] != certManagerConditionTypeReady {
			continue
		}
		if condMap[jsonKeyStatus] == string(metav1.ConditionTrue) {
			return networkingv1alpha.CertificateReadyReasonCertificateIssued, "Certificate is ready"
		}
		// Ready=False
		reason, _ := condMap["reason"].(string)
		message, _ := condMap["message"].(string)
		if message == "" {
			message = "Certificate is not ready"
		}
		// Treat known failure reasons as ProvisioningFailed
		switch reason {
		case "InvalidCertificate", "CertificateRequestFailed":
			return networkingv1alpha.CertificateReadyReasonProvisioningFailed, message
		case "DoesNotExist":
			// cert-manager: "Issuing certificate as Secret does not exist" — normal during first issuance
			return networkingv1alpha.CertificateReadyReasonPending, "We're provisioning and applying a certificate to this hostname - it may take a few minutes"
		default:
			// Translate raw cert-manager message when it's the "Secret does not exist" issuance message
			if strings.Contains(message, "Issuing certificate as Secret does not exist") {
				return networkingv1alpha.CertificateReadyReasonPending, "We're provisioning and applying a certificate to this hostname - it may take a few minutes"
			}
			return networkingv1alpha.CertificateReadyReasonPending, message
		}
	}

	return networkingv1alpha.CertificateReadyReasonPending, "Certificate status not yet available"
}

// setCertificatesReadyCondition sets or removes the CertificatesReady aggregate
// condition on HTTPProxy status based on per-hostname certificate statuses.
func (r *HTTPProxyReconciler) setCertificatesReadyCondition(
	httpProxy *networkingv1alpha.HTTPProxy,
	certificateStatuses []networkingv1alpha.HostnameStatus,
	gateway *gatewayv1.Gateway,
) {
	hasHTTPSListeners := false
	for _, l := range gateway.Spec.Listeners {
		if l.Protocol == gatewayv1.HTTPSProtocolType && l.Hostname != nil {
			hasHTTPSListeners = true
			break
		}
	}

	if certificateStatuses == nil {
		if hasHTTPSListeners {
			apimeta.SetStatusCondition(&httpProxy.Status.Conditions, metav1.Condition{
				Type:               networkingv1alpha.HTTPProxyConditionCertificatesReady,
				Status:             metav1.ConditionUnknown,
				Reason:             networkingv1alpha.CertificatesReadyReasonCertificatesPending,
				Message:            "Downstream cluster unavailable; certificate status unknown",
				ObservedGeneration: httpProxy.Generation,
			})
		} else {
			apimeta.RemoveStatusCondition(&httpProxy.Status.Conditions, networkingv1alpha.HTTPProxyConditionCertificatesReady)
		}
		return
	}

	if len(certificateStatuses) == 0 {
		apimeta.RemoveStatusCondition(&httpProxy.Status.Conditions, networkingv1alpha.HTTPProxyConditionCertificatesReady)
		return
	}

	byHostname := make(map[string]networkingv1alpha.HostnameStatus)
	for _, hs := range httpProxy.Status.HostnameStatuses {
		byHostname[hs.Hostname] = hs
	}

	anyFailed := false
	anyPending := false
	allReady := true

	for _, hs := range certificateStatuses {
		merged, ok := byHostname[hs.Hostname]
		if !ok {
			anyPending = true
			allReady = false
			continue
		}
		cond := apimeta.FindStatusCondition(merged.Conditions, networkingv1alpha.HostnameConditionCertificateReady)
		if cond == nil {
			anyPending = true
			allReady = false
			continue
		}
		if cond.Status != metav1.ConditionTrue {
			allReady = false
			if cond.Reason == networkingv1alpha.CertificateReadyReasonProvisioningFailed {
				anyFailed = true
			} else {
				anyPending = true
			}
		}
	}

	if anyFailed {
		apimeta.SetStatusCondition(&httpProxy.Status.Conditions, metav1.Condition{
			Type:               networkingv1alpha.HTTPProxyConditionCertificatesReady,
			Status:             metav1.ConditionFalse,
			Reason:             networkingv1alpha.CertificatesReadyReasonCertificatesFailed,
			Message:            "One or more certificates failed to provision",
			ObservedGeneration: httpProxy.Generation,
		})
	} else if anyPending || !allReady {
		apimeta.SetStatusCondition(&httpProxy.Status.Conditions, metav1.Condition{
			Type:               networkingv1alpha.HTTPProxyConditionCertificatesReady,
			Status:             metav1.ConditionFalse,
			Reason:             networkingv1alpha.CertificatesReadyReasonCertificatesPending,
			Message:            "One or more certificates are pending or in progress",
			ObservedGeneration: httpProxy.Generation,
		})
	} else {
		apimeta.SetStatusCondition(&httpProxy.Status.Conditions, metav1.Condition{
			Type:               networkingv1alpha.HTTPProxyConditionCertificatesReady,
			Status:             metav1.ConditionTrue,
			Reason:             networkingv1alpha.CertificatesReadyReasonAllCertificatesReady,
			Message:            "All certificates are ready",
			ObservedGeneration: httpProxy.Generation,
		})
	}
}

// mergeHostnameStatuses merges multiple slices of HostnameStatus, combining
// conditions for the same hostname. Returns a sorted slice for deterministic output.
func mergeHostnameStatuses(statusSets ...[]networkingv1alpha.HostnameStatus) []networkingv1alpha.HostnameStatus {
	byHostname := make(map[string]*networkingv1alpha.HostnameStatus)

	for _, statuses := range statusSets {
		for _, hs := range statuses {
			if existing, ok := byHostname[hs.Hostname]; ok {
				for _, c := range hs.Conditions {
					apimeta.SetStatusCondition(&existing.Conditions, c)
				}
			} else {
				copy := hs
				byHostname[hs.Hostname] = &copy
			}
		}
	}

	result := make([]networkingv1alpha.HostnameStatus, 0, len(byHostname))
	for _, hs := range byHostname {
		result = append(result, *hs)
	}

	// Sort for deterministic output
	slices.SortFunc(result, func(a, b networkingv1alpha.HostnameStatus) int {
		return strings.Compare(a.Hostname, b.Hostname)
	})

	return result
}

// preserveHostnameConditionTransitions retains the original LastTransitionTime
// for hostname conditions whose Status has not changed. Without this, freshly-
// built HostnameStatus objects always get LastTransitionTime=now, which causes
// a spurious status diff on every reconcile and drives an infinite loop.
func preserveHostnameConditionTransitions(
	newStatuses, oldStatuses []networkingv1alpha.HostnameStatus,
) {
	oldByHostname := make(map[string]networkingv1alpha.HostnameStatus, len(oldStatuses))
	for _, hs := range oldStatuses {
		oldByHostname[hs.Hostname] = hs
	}

	for i, newHS := range newStatuses {
		oldHS, ok := oldByHostname[newHS.Hostname]
		if !ok {
			continue
		}
		for j, newCond := range newHS.Conditions {
			oldCond := apimeta.FindStatusCondition(oldHS.Conditions, newCond.Type)
			if oldCond != nil && oldCond.Status == newCond.Status {
				newStatuses[i].Conditions[j].LastTransitionTime = oldCond.LastTransitionTime
			}
		}
	}
}

func (r *HTTPProxyReconciler) reconcileConnectorEnvoyPatchPolicy(
	ctx context.Context,
	upstreamClient client.Client,
	clusterName string,
	httpProxy *networkingv1alpha.HTTPProxy,
	gateway *gatewayv1.Gateway,
) (*envoygatewayv1alpha1.EnvoyPatchPolicy, bool, error) {
	if r.DownstreamCluster == nil {
		return nil, false, nil
	}

	downstreamStrategy := downstreamclient.NewMappedNamespaceResourceStrategy(
		clusterName,
		upstreamClient,
		r.DownstreamCluster.GetClient(),
	)
	downstreamNamespaceName, err := downstreamStrategy.GetDownstreamNamespaceNameForUpstreamNamespace(ctx, httpProxy.Namespace)
	if err != nil {
		return nil, false, err
	}

	policyName := fmt.Sprintf("connector-%s", httpProxy.Name)
	policyKey := client.ObjectKey{Namespace: downstreamNamespaceName, Name: policyName}
	downstreamClient := downstreamStrategy.GetClient()

	// If the HTTPProxy has no connector backends in its spec at all (i.e. the
	// connector was removed, not just temporarily offline), delete the EPP and
	// return. This is distinct from the connector being defined but not-ready,
	// where we keep the EPP alive with offline patches.
	//
	// The anchor ConfigMap is intentionally NOT deleted here — it is tied to the
	// HTTPProxy lifetime, not to whether a connector backend is configured. It
	// will be cleaned up in cleanupConnectorEnvoyPatchPolicy when the HTTPProxy
	// is deleted. Deleting the anchor here would cascade-GC any other downstream
	// resources that share the same anchor as an owner.
	if !httpProxyHasConnectorBackends(httpProxy) {
		var existing envoygatewayv1alpha1.EnvoyPatchPolicy
		if err := downstreamClient.Get(ctx, policyKey, &existing); err != nil {
			if apierrors.IsNotFound(err) {
				return nil, false, nil
			}
			return nil, false, err
		}
		return nil, false, downstreamClient.Delete(ctx, &existing)
	}

	// Wait for the Gateway and default HTTPS listener to be Programmed before
	// creating or updating the EnvoyPatchPolicy. This ensures the target
	// RouteConfiguration exists in Envoy's xDS so patches apply immediately.
	gatewayProgrammed := apimeta.IsStatusConditionTrue(
		gateway.Status.Conditions,
		string(gatewayv1.GatewayConditionProgrammed),
	)
	defaultHTTPSListenerProgrammed := gatewayListenerProgrammed(
		gateway.Status.Listeners,
		gatewayutil.DefaultHTTPSListenerName,
	)
	if !gatewayProgrammed || !defaultHTTPSListenerProgrammed {
		// Gateway/listener not yet programmed; requeue will happen when status changes.
		return nil, true, nil
	}

	if r.Config.Gateway.DownstreamGatewayClassName == "" {
		return nil, true, fmt.Errorf("downstreamGatewayClassName is required for connector patching")
	}

	eligibleHTTPSListeners := eligibleConnectorHTTPSListeners(gateway)

	// Collect connector backends that are currently ready. If none are ready the
	// connector is offline and we keep the EPP alive with a direct_response route
	// so EG never hits a delete+create cycle (which causes the watchable
	// deduplication race that leaves EPP status permanently null).
	connectorBackends, err := collectConnectorBackends(ctx, upstreamClient, httpProxy)
	if err != nil {
		return nil, false, err
	}

	var jsonPatches []envoygatewayv1alpha1.EnvoyJSONPatchConfig
	connectorOnline := len(connectorBackends) > 0
	if !connectorOnline {
		// Connector offline: insert a direct_response CONNECT route so clients
		// receive a clean 503 "Tunnel not online" instead of a connection error.
		jsonPatches, err = buildConnectorOfflineEnvoyPatches(downstreamNamespaceName, gateway, httpProxy, eligibleHTTPSListeners)
	} else {
		jsonPatches, err = buildConnectorEnvoyPatches(
			downstreamNamespaceName,
			r.Config.Gateway.ConnectorTunnelListenerName(),
			gateway,
			httpProxy,
			connectorBackends,
			eligibleHTTPSListeners,
		)
	}
	if err != nil {
		return nil, connectorOnline, err
	}

	policy := envoygatewayv1alpha1.EnvoyPatchPolicy{
		ObjectMeta: metav1.ObjectMeta{
			Namespace: downstreamNamespaceName,
			Name:      policyName,
		},
	}
	_, err = controllerutil.CreateOrUpdate(ctx, downstreamClient, &policy, func() error {
		if err := downstreamStrategy.SetControllerReference(ctx, httpProxy, &policy); err != nil {
			return err
		}
		policy.Spec = envoygatewayv1alpha1.EnvoyPatchPolicySpec{
			TargetRef: gatewayv1.LocalPolicyTargetReference{
				Group: gatewayv1.GroupName,
				Kind:  KindGatewayClass,
				Name:  gatewayv1.ObjectName(r.Config.Gateway.DownstreamGatewayClassName),
			},
			Type:        envoygatewayv1alpha1.JSONPatchEnvoyPatchType,
			JSONPatches: jsonPatches,
		}
		return nil
	})
	if err != nil {
		return nil, connectorOnline, err
	}
	return &policy, connectorOnline, nil
}

// eligibleConnectorHTTPSListeners returns the gateway's HTTPS listeners that are
// Programmed. A listener reaches Programmed only once Envoy Gateway has resolved
// its TLS secret and materialized its RouteConfiguration — exactly what the
// connector patch targets — so an unprogrammed listener is skipped to avoid a
// patch stuck Programmed=False/ResourceNotFound.
func eligibleConnectorHTTPSListeners(gateway *gatewayv1.Gateway) sets.Set[string] {
	eligible := sets.New[string]()
	for _, listener := range gateway.Spec.Listeners {
		if listener.Protocol != gatewayv1.HTTPSProtocolType {
			continue
		}
		if gatewayListenerProgrammed(gateway.Status.Listeners, listener.Name) {
			eligible.Insert(string(listener.Name))
		}
	}
	return eligible
}

func (r *HTTPProxyReconciler) cleanupConnectorEnvoyPatchPolicy(
	ctx context.Context,
	upstreamClient client.Client,
	clusterName string,
	httpProxy *networkingv1alpha.HTTPProxy,
) error {
	if r.DownstreamCluster == nil {
		return nil
	}

	downstreamStrategy := downstreamclient.NewMappedNamespaceResourceStrategy(
		clusterName,
		upstreamClient,
		r.DownstreamCluster.GetClient(),
	)
	downstreamNamespaceName, err := downstreamStrategy.GetDownstreamNamespaceNameForUpstreamNamespace(ctx, httpProxy.Namespace)
	if err != nil {
		return err
	}

	downstreamClient := downstreamStrategy.GetClient()

	// When EPP emission is disabled, NSO did not write the connector EPP so we
	// must not delete it (it may have been created before the flag was disabled,
	// or it may belong to the extension server's path). Always clean up NSO's
	// own anchor ConfigMap regardless of the flag.
	if r.Config.Gateway.IsEPPEmissionEnabled() {
		policyName := fmt.Sprintf("connector-%s", httpProxy.Name)
		policyKey := client.ObjectKey{Namespace: downstreamNamespaceName, Name: policyName}

		var policy envoygatewayv1alpha1.EnvoyPatchPolicy
		if err := downstreamClient.Get(ctx, policyKey, &policy); err != nil {
			if apierrors.IsNotFound(err) {
				return downstreamStrategy.DeleteAnchorForObject(ctx, httpProxy)
			}
			return err
		}
		if err := downstreamClient.Delete(ctx, &policy); err != nil {
			return err
		}
	}

	return downstreamStrategy.DeleteAnchorForObject(ctx, httpProxy)
}

func cleanupConnectorOfflineHTTPRouteFilter(ctx context.Context, cl client.Client, httpProxy *networkingv1alpha.HTTPProxy) error {
	filterKey := client.ObjectKey{Namespace: httpProxy.Namespace, Name: connectorOfflineFilterName(httpProxy)}
	var filter envoygatewayv1alpha1.HTTPRouteFilter
	if err := cl.Get(ctx, filterKey, &filter); err != nil {
		if apierrors.IsNotFound(err) {
			return nil
		}
		return err
	}
	return cl.Delete(ctx, &filter)
}

func gatewayListenerProgrammed(listeners []gatewayv1.ListenerStatus, listenerName gatewayv1.SectionName) bool {
	for _, listener := range listeners {
		if listener.Name != listenerName {
			continue
		}
		return apimeta.IsStatusConditionTrue(listener.Conditions, string(gatewayv1.ListenerConditionProgrammed))
	}
	return false
}

func downstreamPatchPolicyReady(policy *envoygatewayv1alpha1.EnvoyPatchPolicy, gatewayClassName string) (bool, string) {
	if policy == nil {
		return false, "Downstream EnvoyPatchPolicy not found"
	}

	if len(policy.Status.Ancestors) == 0 {
		return false, "Downstream EnvoyPatchPolicy has no status yet"
	}

	for _, ancestor := range policy.Status.Ancestors {
		if ptr.Deref(ancestor.AncestorRef.Kind, gatewayv1.Kind("")) != gatewayv1.Kind(KindGatewayClass) ||
			ancestor.AncestorRef.Name != gatewayv1.ObjectName(gatewayClassName) {
			continue
		}

		accepted := apimeta.FindStatusCondition(ancestor.Conditions, conditionTypeAccepted)
		if accepted == nil || accepted.Status != metav1.ConditionTrue {
			return false, formatPolicyConditionMessage(conditionTypeAccepted, accepted)
		}

		programmed := apimeta.FindStatusCondition(ancestor.Conditions, conditionTypeProgrammed)
		if programmed == nil || programmed.Status != metav1.ConditionTrue {
			return false, formatPolicyConditionMessage(conditionTypeProgrammed, programmed)
		}

		return true, ""
	}

	return false, fmt.Sprintf("Downstream EnvoyPatchPolicy has no ancestor status for GatewayClass %q", gatewayClassName)
}

func formatPolicyConditionMessage(conditionType string, condition *metav1.Condition) string {
	if condition == nil {
		return fmt.Sprintf("Downstream EnvoyPatchPolicy is missing %s condition", conditionType)
	}
	if condition.Message == "" {
		return fmt.Sprintf("Downstream EnvoyPatchPolicy %s=%s (%s)", condition.Type, condition.Status, condition.Reason)
	}
	return fmt.Sprintf("Downstream EnvoyPatchPolicy %s=%s (%s): %s", condition.Type, condition.Status, condition.Reason, condition.Message)
}

func collectConnectorBackends(
	ctx context.Context,
	cl client.Client,
	httpProxy *networkingv1alpha.HTTPProxy,
) ([]connectorBackendPatch, error) {
	connectorBackends := make([]connectorBackendPatch, 0)
	for ruleIndex, rule := range httpProxy.Spec.Rules {
		matchCount := len(rule.Matches)
		if matchCount == 0 {
			matchCount = 1
		}
		for matchIndex := 0; matchIndex < matchCount; matchIndex++ {
			for _, backend := range rule.Backends {
				if backend.Connector == nil {
					continue
				}

				targetHost, targetPort, err := backendEndpointTarget(backend)
				if err != nil {
					return nil, err
				}

				connectorReady, nodeID, err := connectorPatchDetails(ctx, cl, httpProxy.Namespace, backend.Connector.Name)
				if err != nil {
					return nil, err
				}
				if !connectorReady {
					continue
				}

				connectorBackends = append(connectorBackends, connectorBackendPatch{
					sectionName: nil,
					ruleIndex:   ruleIndex,
					matchIndex:  matchIndex,
					targetHost:  targetHost,
					targetPort:  targetPort,
					nodeID:      nodeID,
				})
			}
		}
	}
	return connectorBackends, nil
}

func backendEndpointTarget(backend networkingv1alpha.HTTPProxyRuleBackend) (string, int, error) {
	u, err := url.Parse(backend.Endpoint)
	if err != nil {
		return "", 0, fmt.Errorf("failed parsing backend endpoint: %w", err)
	}

	targetHost := u.Hostname()
	if targetHost == "" {
		return "", 0, fmt.Errorf("backend endpoint host is required")
	}

	targetPort := DefaultHTTPPort
	if u.Scheme == SchemeHTTPS {
		targetPort = DefaultHTTPSPort
	}
	if endpointPort := u.Port(); endpointPort != "" {
		targetPort, err = strconv.Atoi(endpointPort)
		if err != nil {
			return "", 0, fmt.Errorf("invalid backend endpoint port: %w", err)
		}
	}

	return targetHost, targetPort, nil
}

func connectorOfflineFilterName(httpProxy *networkingv1alpha.HTTPProxy) string {
	return fmt.Sprintf("%s-%s", connectorOfflineFilterPrefix, httpProxy.Name)
}

// httpProxyHasConnectorBackends returns true if any backend in the HTTPProxy
// spec references a connector, regardless of the connector's readiness state.
// Used to distinguish "connector removed from spec" (→ delete EPP) from
// "connector defined but offline" (→ update EPP with offline patches).
func httpProxyHasConnectorBackends(httpProxy *networkingv1alpha.HTTPProxy) bool {
	for _, rule := range httpProxy.Spec.Rules {
		for _, backend := range rule.Backends {
			if backend.Connector != nil {
				return true
			}
		}
	}
	return false
}

func connectorReady(ctx context.Context, cl client.Client, namespace, name string) (bool, error) {
	var connector networkingv1alpha1.Connector
	if err := cl.Get(ctx, client.ObjectKey{Namespace: namespace, Name: name}, &connector); err != nil {
		return false, err
	}
	return apimeta.IsStatusConditionTrue(connector.Status.Conditions, networkingv1alpha1.ConnectorConditionReady), nil
}

func connectorPatchDetails(ctx context.Context, cl client.Client, namespace, name string) (bool, string, error) {
	var connector networkingv1alpha1.Connector
	if err := cl.Get(ctx, client.ObjectKey{Namespace: namespace, Name: name}, &connector); err != nil {
		return false, "", err
	}

	ready := apimeta.IsStatusConditionTrue(connector.Status.Conditions, networkingv1alpha1.ConnectorConditionReady)
	if !ready {
		return false, "", nil
	}

	details := connector.Status.ConnectionDetails
	if details == nil || details.Type != networkingv1alpha1.PublicKeyConnectorConnectionType || details.PublicKey == nil {
		return false, "", fmt.Errorf("connector %q does not have public key connection details", name)
	}
	if details.PublicKey.Id == "" {
		return false, "", fmt.Errorf("connector %q public key id is empty", name)
	}
	return true, details.PublicKey.Id, nil
}