test(extension-server): drop shorthand label from connector test comment

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: scotwells

api/v1alpha1/connector_types.go

@@ -181,38 +181,25 @@ const (
 
 const ConnectorNameAnnotation = "networking.datum.org/connector-name"
 
-// ConnectorLivenessAnnotation carries a compact snapshot of a Connector's
-// authoritative upstream liveness down to edge member clusters.
-//
-// A Connector's Ready condition and ConnectionDetails are computed in the
-// Project control plane and stored in the Connector's status subresource. The
-// edge extension server reads connectors from the local member-cluster cache to
-// decide whether a tunnel is online. Karmada propagates a resource template's
-// spec and metadata (labels/annotations) to member clusters but NOT the status
-// subresource, so the member-cluster Connector never carries Ready or
-// ConnectionDetails. To bridge that gap the replicator stamps the liveness onto
-// this annotation — which Karmada DOES propagate — and the extension server
-// reads it from there, falling back to status when the annotation is absent.
-//
-// The value is a JSON-marshalled ConnectorLiveness. Keep the JSON schema in
-// sync with that type.
+// ConnectorLivenessAnnotation carries a Connector's liveness down to edge
+// member clusters. Connector Ready + ConnectionDetails are authoritative in the
+// Project control plane and live in the status subresource, but Karmada
+// propagates a resource template's spec + metadata to members, NOT its status.
+// The replicator stamps liveness onto this annotation (which Karmada does
+// propagate) so the edge extension server can read it. Value is a
+// JSON-marshalled ConnectorLiveness; keep the schema in sync.
 const ConnectorLivenessAnnotation = "networking.datumapis.com/connector-liveness"
 
 // ConnectorLiveness is the JSON payload stored in ConnectorLivenessAnnotation.
-//
-// It carries only the status-derived fields the extension server needs to
-// classify a connector online/offline and to build the data-plane tunnel
-// cluster. It deliberately does NOT include the tunnel TargetHost/TargetPort:
-// those are derived from the referencing HTTPProxy backend endpoint URL, not
-// from Connector status.
+// It carries only the status-derived fields the extension server consumes.
+// TargetHost/TargetPort are intentionally absent: they derive from the
+// referencing HTTPProxy backend endpoint, not from Connector status.
 type ConnectorLiveness struct {
 	// Ready mirrors the upstream Connector's Ready condition being True.
 	Ready bool `json:"ready"`
 
-	// NodeID is the connector's public-key id, taken from
-	// Status.ConnectionDetails.PublicKey.Id when the connector is ready and
-	// advertises PublicKey connection details. Empty otherwise. Used as the
-	// tunnel endpoint_id in the data-plane connector cluster.
+	// NodeID is Status.ConnectionDetails.PublicKey.Id, used as the tunnel
+	// endpoint_id in the data-plane connector cluster.
 	NodeID string `json:"nodeID,omitempty"`
 }
 

internal/controller/gateway_resource_replicator_controller.go

@@ -74,25 +74,20 @@ type replicationResourceConfig struct {
 	conditionHandlers conditionReasonHandlers
 
 	// mirrorStatusDownstream copies upstream status → downstream status after
-	// each spec sync. Used for resource types whose status is authoritative in
-	// the upstream cluster and must be readable by consumers in the downstream
-	// cluster. When true, skipUpstreamStatusSync is implicitly honoured as well.
+	// each spec sync, for resource types whose status is authoritative upstream.
+	// When true, skipUpstreamStatusSync is implicitly honoured as well.
 	//
-	// NOTE: this does NOT work across a Karmada hub→member boundary — Karmada
-	// propagates a resource template's spec + metadata to members but NOT the
-	// status subresource. For the Connector type (whose downstream consumer, the
-	// edge extension server, lives on a member cluster) use
-	// writeLivenessAnnotation instead, which rides an annotation Karmada does
-	// propagate.
+	// NOTE: ineffective across a Karmada hub→member boundary — Karmada does not
+	// propagate the status subresource to members. For the Connector type (read
+	// by the edge extension server on a member cluster) use
+	// writeLivenessAnnotation instead.
 	mirrorStatusDownstream bool
 
-	// writeLivenessAnnotation, when true, derives a compact liveness snapshot
-	// from the upstream Connector's status and stores it as the
-	// ConnectorLivenessAnnotation on the downstream object's metadata. Karmada
-	// propagates resource-template annotations (but NOT the status subresource)
-	// to member clusters, so this is how connector liveness reaches the edge
-	// extension server. Used instead of mirrorStatusDownstream for the Connector
-	// type. Implies skipUpstreamStatusSync should also be set.
+	// writeLivenessAnnotation derives a compact liveness snapshot from the
+	// upstream Connector's status and stores it as ConnectorLivenessAnnotation
+	// on the downstream object's metadata. Karmada propagates metadata (but not
+	// status) to members, so this is how connector liveness reaches the edge
+	// extension server. Implies skipUpstreamStatusSync should also be set.
 	writeLivenessAnnotation bool
 
 	// skipUpstreamStatusSync suppresses the normal downstream→upstream status
@@ -163,13 +158,10 @@ func initReplicationResourceConfigs() map[string]replicationResourceConfig {
 		}
 	}
 
-	// Connector liveness (Ready condition + connectionDetails) is authoritative
-	// upstream and must be readable by the edge extension server so it can
-	// determine whether a tunnel is online before injecting connector cluster
-	// patches. The extension server runs on a member cluster, and Karmada does
-	// not propagate the status subresource hub→member — only spec + metadata.
-	// Carry liveness down through an annotation (which Karmada DOES propagate)
-	// instead of mirroring status. Do not propagate status back upstream.
+	// Connector liveness (Ready + connectionDetails) is authoritative upstream
+	// and read by the edge extension server on a member cluster. Karmada does
+	// not propagate status hub→member, so carry liveness down via an annotation
+	// instead. Do not propagate status back upstream.
 	connectorGVK := schema.GroupVersionKind{Group: groupNetworkingDatumAPIs, Version: versionV1Alpha1, Kind: KindConnector}
 	configs[gvkKey(connectorGVK)] = replicationResourceConfig{
 		writeLivenessAnnotation: true,
@@ -334,10 +326,8 @@ func (r *GatewayResourceReplicatorReconciler) ensureDownstreamResource(
 			return fmt.Errorf("failed to set downstream controller reference: %w", err)
 		}
 
-		// Stamp the connector liveness annotation onto the downstream object's
-		// metadata. This is part of the same CreateOrUpdate Update, so it is
-		// persisted as ordinary metadata (which Karmada propagates to members) —
-		// no status subresource write involved.
+		// Persisted as ordinary metadata via this same CreateOrUpdate Update —
+		// no status subresource write — so Karmada propagates it to members.
 		if resource.replicationResourceConfig.writeLivenessAnnotation {
 			if err := setConnectorLivenessAnnotation(downstreamObj, upstreamObj); err != nil {
 				return err
@@ -457,12 +447,10 @@ func (r *GatewayResourceReplicatorReconciler) mirrorUpstreamStatusToDownstream(
 	return nil
 }
 
-// setConnectorLivenessAnnotation derives a compact liveness snapshot from the
-// upstream Connector's status and stores it as ConnectorLivenessAnnotation on
-// the downstream object's metadata. It is the Karmada-friendly replacement for
-// mirroring the status subresource downstream: Karmada propagates a resource
-// template's metadata (annotations) to member clusters but not its status, so
-// the edge extension server reads liveness from this annotation instead.
+// setConnectorLivenessAnnotation stamps the upstream Connector's liveness onto
+// the downstream object's metadata. Karmada propagates metadata (but not the
+// status subresource) to members, so the edge extension server reads liveness
+// from this annotation rather than from downstream status.
 func setConnectorLivenessAnnotation(downstreamObj, upstreamObj *unstructured.Unstructured) error {
 	liveness, err := connectorLivenessFromUpstream(upstreamObj)
 	if err != nil {
@@ -483,10 +471,8 @@ func setConnectorLivenessAnnotation(downstreamObj, upstreamObj *unstructured.Uns
 	return nil
 }
 
-// connectorLivenessFromUpstream extracts the Ready condition and PublicKey node
-// ID from an upstream Connector's (unstructured) status. A connector with no
-// status, a non-True Ready condition, or no PublicKey connection details yields
-// a not-ready liveness with an empty NodeID.
+// connectorLivenessFromUpstream extracts Ready and the PublicKey node ID from an
+// upstream Connector's (unstructured) status.
 func connectorLivenessFromUpstream(upstreamObj *unstructured.Unstructured) (networkingv1alpha1.ConnectorLiveness, error) {
 	var liveness networkingv1alpha1.ConnectorLiveness
 

internal/extensionserver/cache/index.go

@@ -165,18 +165,12 @@ func populateFromClient(ctx context.Context, cl client.Client, idx *PolicyIndex,
 	return nil
 }
 
-// connectorLiveness determines whether a connector is online and, if so, its
-// tunnel node ID. It prefers the ConnectorLivenessAnnotation, which is how
-// connector liveness reaches edge member clusters: a Connector's Ready condition
-// and ConnectionDetails are authoritative in the Project control plane and live
-// in its status subresource, but Karmada propagates a resource template's spec +
-// metadata (annotations) to members, NOT the status subresource. The replicator
-// stamps the liveness onto the annotation; this reads it back.
-//
-// When the annotation is absent or unparseable — single-cluster deployments
-// (where the local object carries real status), or member-cluster objects
-// written before this rollout — it falls back to the status-based
-// classification, preserving the previous behaviour.
+// connectorLiveness reports whether a connector is online and its tunnel node
+// ID. It prefers ConnectorLivenessAnnotation: on member clusters Karmada
+// delivers a connector's metadata but not its status, so liveness rides the
+// annotation. It falls back to status when the annotation is absent or
+// unparseable — single-cluster deployments and objects written before this
+// rollout — preserving the previous behaviour.
 func connectorLiveness(connector *networkingv1alpha1.Connector) (online bool, nodeID string) {
 	if raw, ok := connector.Annotations[networkingv1alpha1.ConnectorLivenessAnnotation]; ok {
 		var liveness networkingv1alpha1.ConnectorLiveness

internal/extensionserver/mutate/connector_test.go

@@ -310,7 +310,7 @@ func TestApplyConnectorRoutes_Offline_Prepends503Route_NoDomain(t *testing.T) {
 		"offline route body must be 'Tunnel not online' per STATE.md contract")
 
 	// Second route: the original user-facing forwarding route must now be a
-	// direct_response 503 too (Gap B), NOT a cluster route to the empty cluster.
+	// direct_response 503 too, NOT a cluster route to the empty cluster.
 	fwd := vh.Routes[1]
 	assert.Equal(t, "fwd", fwd.GetName(), "forwarding route identity preserved")
 	assert.Empty(t, routeCluster(fwd),