fix(connector): carry full connectionDetails in liveness annotation

The connector liveness annotation previously carried a reduced
{ready, nodeID} snapshot, hard-coding the assumption that the tunnel
node ID is the PublicKey id. Carry the upstream Connector's full
status.connectionDetails (type discriminator + type-specific block)
alongside ready instead, so additional connection types can be
supported without changing the annotation's JSON schema.

The extension server now derives the tunnel node ID via a type-aware
ConnectorConnectionDetails.TunnelNodeID() that switches on the
connection type, with an empty-string default for unknown types, and
keeps the existing status fallback when the annotation is absent or
unparseable.

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

Author: scotwells

api/v1alpha1/connector_types.go

@@ -200,20 +200,40 @@ 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 the upstream Connector's Ready classification plus its full
+// ConnectionDetails. Embedding the complete ConnectionDetails — including the
+// type discriminator and the type-specific block — lets the extension server
+// derive the tunnel node ID for any connection type the API supports, today and
+// in future, without changing this annotation's JSON schema. It deliberately
+// does NOT include the tunnel TargetHost/TargetPort: those are derived from the
+// referencing HTTPProxy backend endpoint URL, 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 string `json:"nodeID,omitempty"`
+	// ConnectionDetails is the upstream Connector's full
+	// Status.ConnectionDetails, copied verbatim so the extension server can
+	// extract the tunnel node ID in a type-aware way (see TunnelNodeID). Nil
+	// when the upstream connector has not yet published connection details.
+	ConnectionDetails *ConnectorConnectionDetails `json:"connectionDetails,omitempty"`
+}
+
+// TunnelNodeID returns the data-plane tunnel endpoint_id for these connection
+// details, dispatching on the connection Type so new connection types can be
+// added by extending the switch rather than by assuming PublicKey. It returns
+// an empty string for nil details or any type that does not (yet) advertise a
+// node ID.
+func (d *ConnectorConnectionDetails) TunnelNodeID() string {
+	if d == nil {
+		return ""
+	}
+	switch d.Type {
+	case PublicKeyConnectorConnectionType:
+		if d.PublicKey != nil {
+			return d.PublicKey.Id
+		}
+	}
+	return ""
 }
 
 // +kubebuilder:object:root=true

api/v1alpha1/zz_generated.deepcopy.go

@@ -483,10 +483,12 @@ 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 the Ready condition and the full
+// ConnectionDetails from an upstream Connector's (unstructured) status. A
+// connector with no status yields a not-ready liveness with nil
+// ConnectionDetails. The complete ConnectionDetails is carried so the extension
+// server can derive the tunnel node ID for any connection type without an
+// annotation-schema change.
 func connectorLivenessFromUpstream(upstreamObj *unstructured.Unstructured) (networkingv1alpha1.ConnectorLiveness, error) {
 	var liveness networkingv1alpha1.ConnectorLiveness
 
@@ -505,13 +507,7 @@ func connectorLivenessFromUpstream(upstreamObj *unstructured.Unstructured) (netw
 	}
 
 	liveness.Ready = apimeta.IsStatusConditionTrue(status.Conditions, networkingv1alpha1.ConnectorConditionReady)
-	if liveness.Ready {
-		if details := status.ConnectionDetails; details != nil &&
-			details.Type == networkingv1alpha1.PublicKeyConnectorConnectionType &&
-			details.PublicKey != nil {
-			liveness.NodeID = details.PublicKey.Id
-		}
-	}
+	liveness.ConnectionDetails = status.ConnectionDetails
 	return liveness, nil
 }
 

internal/controller/gateway_resource_replicator_controller.go

@@ -441,9 +441,9 @@ func TestReplicatorMirrorsNSOPolicyTypesSkipsUpstreamStatusSync(t *testing.T) {
 // TestReplicatorMirrorsConnectorSpecAndLivenessAnnotation verifies that when the
 // replicator handles a Connector it:
 //   - copies spec into the downstream ns-<uid> namespace, AND
-//   - stamps the ConnectorLivenessAnnotation (ready + nodeID) onto the
-//     downstream object's metadata so the edge extension server can read tunnel
-//     liveness locally.
+//   - stamps the ConnectorLivenessAnnotation (ready + full connectionDetails)
+//     onto the downstream object's metadata so the edge extension server can read
+//     tunnel liveness locally.
 //
 // The annotation — not the status subresource — carries liveness because Karmada
 // propagates a resource template's spec + metadata to member clusters but NOT
@@ -526,12 +526,21 @@ func TestReplicatorMirrorsConnectorSpecAndLivenessAnnotation(t *testing.T) {
 		"downstream spec must mirror upstream spec")
 
 	// Key assertion: the liveness annotation reflects the upstream Ready
-	// condition and the PublicKey node ID.
-	expected, err := json.Marshal(networkingv1alpha1.ConnectorLiveness{Ready: true, NodeID: "node-abc"})
+	// condition and carries the full upstream connectionDetails (type
+	// discriminator + type-specific block), not a reduced node-ID-only view.
+	expected, err := json.Marshal(networkingv1alpha1.ConnectorLiveness{
+		Ready: true,
+		ConnectionDetails: &networkingv1alpha1.ConnectorConnectionDetails{
+			Type: networkingv1alpha1.PublicKeyConnectorConnectionType,
+			PublicKey: &networkingv1alpha1.ConnectorConnectionDetailsPublicKey{
+				Id: "node-abc",
+			},
+		},
+	})
 	assert.NoError(t, err)
 	assert.Equal(t, string(expected),
 		downstream.GetAnnotations()[networkingv1alpha1.ConnectorLivenessAnnotation],
-		"downstream liveness annotation must carry ready + nodeID derived from upstream status")
+		"downstream liveness annotation must carry ready + the full upstream connectionDetails")
 
 	// The replicator must NOT mirror the status subresource downstream (Karmada
 	// would not propagate it to members anyway).

internal/controller/gateway_resource_replicator_controller_test.go

@@ -181,7 +181,10 @@ func connectorLiveness(connector *networkingv1alpha1.Connector) (online bool, no
 	if raw, ok := connector.Annotations[networkingv1alpha1.ConnectorLivenessAnnotation]; ok {
 		var liveness networkingv1alpha1.ConnectorLiveness
 		if err := json.Unmarshal([]byte(raw), &liveness); err == nil {
-			return liveness.Ready, liveness.NodeID
+			// TunnelNodeID dispatches on the connection type, so a new
+			// connection type is supported by extending that switch rather than
+			// by changing the annotation schema here.
+			return liveness.Ready, liveness.ConnectionDetails.TunnelNodeID()
 		}
 		// Unparseable annotation: fall through to status-based classification.
 	}
@@ -191,11 +194,7 @@ func connectorLiveness(connector *networkingv1alpha1.Connector) (online bool, no
 		networkingv1alpha1.ConnectorConditionReady,
 	)
 	if online {
-		if details := connector.Status.ConnectionDetails; details != nil &&
-			details.Type == networkingv1alpha1.PublicKeyConnectorConnectionType &&
-			details.PublicKey != nil {
-			nodeID = details.PublicKey.Id
-		}
+		nodeID = connector.Status.ConnectionDetails.TunnelNodeID()
 	}
 	return online, nodeID
 }

internal/extensionserver/cache/index.go

@@ -910,6 +910,17 @@ func TestBuildPolicyIndexFromClient_ConnectorResolution_NonConnectorBackend_Skip
 // status-fallback classification.
 // =============================================================================
 
+// publicKeyDetails builds ConnectionDetails for the PublicKey connection type
+// advertising the given node id — the only connection type defined today.
+func publicKeyDetails(nodeID string) *networkingv1alpha1.ConnectorConnectionDetails {
+	return &networkingv1alpha1.ConnectorConnectionDetails{
+		Type: networkingv1alpha1.PublicKeyConnectorConnectionType,
+		PublicKey: &networkingv1alpha1.ConnectorConnectionDetailsPublicKey{
+			Id: nodeID,
+		},
+	}
+}
+
 // newConnectorWithLiveness builds a Connector carrying only the liveness
 // annotation (no status) — simulating a member-cluster replica object.
 func newConnectorWithLiveness(ns, name string, liveness networkingv1alpha1.ConnectorLiveness) *networkingv1alpha1.Connector {
@@ -927,10 +938,33 @@ func newConnectorWithLiveness(ns, name string, liveness networkingv1alpha1.Conne
 
 func TestConnectorLiveness_AnnotationOnlineWithNodeID(t *testing.T) {
 	c := newConnectorWithLiveness("ns", "conn",
-		networkingv1alpha1.ConnectorLiveness{Ready: true, NodeID: "node-anno"})
+		networkingv1alpha1.ConnectorLiveness{Ready: true, ConnectionDetails: publicKeyDetails("node-anno")})
 	online, nodeID := connectorLiveness(c)
 	assert.True(t, online, "ready annotation must classify online")
-	assert.Equal(t, "node-anno", nodeID, "nodeID must come from the annotation")
+	assert.Equal(t, "node-anno", nodeID, "nodeID must come from the annotation's connectionDetails")
+}
+
+func TestConnectorLiveness_AnnotationOnlineUnknownTypeEmptyNodeID(t *testing.T) {
+	// A connection type the extension server does not (yet) understand still
+	// classifies online from ready, but yields no node ID rather than panicking
+	// or assuming PublicKey.
+	c := newConnectorWithLiveness("ns", "conn",
+		networkingv1alpha1.ConnectorLiveness{
+			Ready:             true,
+			ConnectionDetails: &networkingv1alpha1.ConnectorConnectionDetails{Type: "FutureType"},
+		})
+	online, nodeID := connectorLiveness(c)
+	assert.True(t, online, "ready annotation must classify online regardless of connection type")
+	assert.Empty(t, nodeID, "unknown connection type must yield an empty node ID")
+}
+
+func TestConnectorLiveness_AnnotationOnlineNilDetailsEmptyNodeID(t *testing.T) {
+	// Ready but no connection details published yet: online, empty node ID.
+	c := newConnectorWithLiveness("ns", "conn",
+		networkingv1alpha1.ConnectorLiveness{Ready: true})
+	online, nodeID := connectorLiveness(c)
+	assert.True(t, online, "ready annotation with nil connectionDetails must classify online")
+	assert.Empty(t, nodeID, "nil connectionDetails must yield an empty node ID")
 }
 
 func TestConnectorLiveness_AnnotationOffline(t *testing.T) {
@@ -945,7 +979,7 @@ func TestConnectorLiveness_AnnotationTakesPrecedenceOverStatus(t *testing.T) {
 	// Annotation says online; status says offline. Annotation wins (it is the
 	// authoritative liveness on member clusters where status never propagates).
 	c := newOfflineConnector("ns", "conn")
-	raw, _ := json.Marshal(networkingv1alpha1.ConnectorLiveness{Ready: true, NodeID: "node-anno"})
+	raw, _ := json.Marshal(networkingv1alpha1.ConnectorLiveness{Ready: true, ConnectionDetails: publicKeyDetails("node-anno")})
 	c.Annotations = map[string]string{networkingv1alpha1.ConnectorLivenessAnnotation: string(raw)}
 
 	online, nodeID := connectorLiveness(c)
@@ -996,7 +1030,7 @@ func TestBuildPolicyIndexFromClient_ConnectorResolution_AnnotationDrivesOnline(t
 
 	proxy := newHTTPProxy(upstreamNS, "http://backend.example.com:9000", connectorName)
 	connector := newConnectorWithLiveness(upstreamNS, connectorName,
-		networkingv1alpha1.ConnectorLiveness{Ready: true, NodeID: nodeID})
+		networkingv1alpha1.ConnectorLiveness{Ready: true, ConnectionDetails: publicKeyDetails(nodeID)})
 
 	cl := fake.NewClientBuilder().
 		WithScheme(scheme).