add mapper & identity

Author: mjudeikis

v2/README.md

@@ -60,6 +60,18 @@ v2/
   Connection: writes go through its client, fresh reads through its API reader,
   and status/drift events arrive via a **watch on its cache** (event-driven, not
   polled — a low-frequency resync is only a backstop).
+- **Stop-on-disengage**: a Connection that loses readiness (revoked credential,
+  unreachable provider, withdrawn RBAC) is disengaged, and its per-GVR syncers
+  are torn down rather than left running against a dead cluster. When it becomes
+  Ready again the provider re-engages as a fresh cluster and the syncers are
+  rebuilt against it (a stale syncer would otherwise hold a dead client forever).
+- **Mapper extension point** (`engine/mapper`): the syncer routes every
+  provider-side operation through a `Mapper` that translates the consumer object
+  key to its provider key. Core ships only `Identity` (ns/name unchanged); an
+  out-of-tree build supplies its own via `sync.WithMapper(...)` to restore v1's
+  "Prefixed" key isolation without forking the engine. The interface maps keys
+  only — it cannot change scope (cluster-scoped stays cluster-scoped), and it is
+  deliberately kept out of the CRD API so the core API never promises renaming.
 - **Order-independent apply**: a `Connection` created before its Secret resolves
   when the Secret arrives (the konnector watches referenced Secrets); a binding
   created before its Connection resolves when the Connection goes Ready.
@@ -70,9 +82,10 @@ v2/
   gone, and keeps its Secret alive (via a finalizer) so teardown can still reach
   the provider — so `kubectl delete -f bundle.yaml` is order-don't-care.
 
-Known POC simplifications (tracked against the proposal): the `Mapper`
-extension is not implemented; OpenAPI synthesis is best-effort (fidelity limits
-above); and syncer stop-on-disengage + productionization (RBAC/HA/Helm) remain.
+Known POC simplifications (tracked against the proposal): OpenAPI synthesis is
+best-effort (fidelity limits above); the `Mapper` seam exists but only `Identity`
+ships and `relatedResources` are not yet routed through it; and productionization
+(RBAC/HA/Helm) remains.
 
 ## Build
 

v2/konnector/engine/mapper/mapper.go

@@ -0,0 +1,67 @@
+/*
+Copyright 2026 The Kube Bind Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package mapper defines the Mapper extension point: how the konnector
+// translates object identity (namespace/name) between the consumer and the
+// provider when syncing instances.
+//
+// Core ships exactly one implementation — Identity — and the interface is a
+// compile-time seam so out-of-tree konnector builds can restore tenancy
+// key-mapping (e.g. v1's "Prefixed" isolation) without forking the engine. It
+// is deliberately kept out of the CRD API: the core API never promises
+// renaming.
+//
+// The interface maps KEYS only; it cannot change an object's scope
+// (cluster-scoped stays cluster-scoped). That is the hard line v2 draws — v1's
+// "Namespaced" scope-conversion isolation is intentionally not expressible here.
+// A later, separate Transformer interface (mutating the object payload — label
+// injection, field stripping) is possible but deliberately deferred.
+package mapper
+
+import (
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+// ObjectKey is a namespace/name identity. It aliases controller-runtime's
+// client.ObjectKey for drop-in interop with the syncer.
+type ObjectKey = client.ObjectKey
+
+// Mapper translates object identity between consumer and provider. Core
+// registers exactly one implementation: Identity.
+type Mapper interface {
+	// ToProvider maps a consumer object key to its provider key.
+	ToProvider(gvr schema.GroupVersionResource, key ObjectKey) (ObjectKey, error)
+	// ToConsumer is the inverse of ToProvider; it must round-trip, i.e.
+	// ToConsumer(gvr, ToProvider(gvr, k)) == k.
+	ToConsumer(gvr schema.GroupVersionResource, key ObjectKey) (ObjectKey, error)
+}
+
+// Identity is the core Mapper: the consumer ns/name equals the provider ns/name
+// with no transformation. It is the only mapping core ships.
+type Identity struct{}
+
+// ToProvider returns key unchanged.
+func (Identity) ToProvider(_ schema.GroupVersionResource, key ObjectKey) (ObjectKey, error) {
+	return key, nil
+}
+
+// ToConsumer returns key unchanged.
+func (Identity) ToConsumer(_ schema.GroupVersionResource, key ObjectKey) (ObjectKey, error) {
+	return key, nil
+}
+
+var _ Mapper = Identity{}

v2/konnector/engine/mapper/mapper_test.go

@@ -0,0 +1,70 @@
+/*
+Copyright 2026 The Kube Bind Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package mapper_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+
+	"github.com/kube-bind/kube-bind/v2/konnector/engine/mapper"
+)
+
+var widgetGVR = schema.GroupVersionResource{Group: "example.org", Version: "v1", Resource: "widgets"}
+
+func TestIdentity_RoundTrips(t *testing.T) {
+	m := mapper.Identity{}
+	in := mapper.ObjectKey{Namespace: "team-a", Name: "w1"}
+
+	prov, err := m.ToProvider(widgetGVR, in)
+	require.NoError(t, err)
+	require.Equal(t, in, prov, "Identity must not change the key on the way to the provider")
+
+	back, err := m.ToConsumer(widgetGVR, prov)
+	require.NoError(t, err)
+	require.Equal(t, in, back, "Identity must round-trip")
+}
+
+// prefixMapper is an out-of-tree-style Mapper that prefixes the provider
+// namespace, exercising the interface the way a custom build would (v1's
+// "Prefixed" isolation). It lives in the test to prove the seam is usable and
+// that the round-trip contract is satisfiable by a non-identity mapping.
+type prefixMapper struct{ prefix string }
+
+func (p prefixMapper) ToProvider(_ schema.GroupVersionResource, key mapper.ObjectKey) (mapper.ObjectKey, error) {
+	return mapper.ObjectKey{Namespace: p.prefix + key.Namespace, Name: key.Name}, nil
+}
+
+func (p prefixMapper) ToConsumer(_ schema.GroupVersionResource, key mapper.ObjectKey) (mapper.ObjectKey, error) {
+	return mapper.ObjectKey{Namespace: strings.TrimPrefix(key.Namespace, p.prefix), Name: key.Name}, nil
+}
+
+func TestMapper_NonIdentityRoundTrips(t *testing.T) {
+	var m mapper.Mapper = prefixMapper{prefix: "consumer-7-"}
+	in := mapper.ObjectKey{Namespace: "team-a", Name: "w1"}
+
+	prov, err := m.ToProvider(widgetGVR, in)
+	require.NoError(t, err)
+	require.Equal(t, "consumer-7-team-a", prov.Namespace)
+	require.Equal(t, "w1", prov.Name)
+
+	back, err := m.ToConsumer(widgetGVR, prov)
+	require.NoError(t, err)
+	require.Equal(t, in, back, "a Mapper must round-trip: ToConsumer(ToProvider(k)) == k")
+}

v2/konnector/engine/provider/connection_provider.go

@@ -118,16 +118,34 @@ func (p *ConnectionProvider) Reconcile(ctx context.Context, req reconcile.Reques
 	}
 
 	p.lock.Lock()
-	defer p.lock.Unlock()
+	mcMgr := p.mcMgr
+	_, engaged := p.clusters[key]
+	p.lock.Unlock()
 
-	if p.mcMgr == nil {
+	if mcMgr == nil {
 		return reconcile.Result{RequeueAfter: 2 * time.Second}, nil
 	}
-	if _, ok := p.clusters[key]; ok {
+	// A Connection that is no longer Ready (e.g. its credential was revoked, the
+	// provider became unreachable, or RBAC was withdrawn) must be disengaged, not
+	// just left running against a dead cluster. This also covers a Connection
+	// mid-deletion that has already flipped not-Ready.
+	if !isReady(conn) {
+		if engaged {
+			p.disengage(key)
+			log.Info("Disengaged provider cluster (Connection no longer ready)")
+		} else {
+			log.V(4).Info("Connection not ready yet, not engaging")
+		}
 		return reconcile.Result{}, nil
 	}
-	if !isReady(conn) {
-		log.V(4).Info("Connection not ready yet, not engaging")
+	if engaged {
+		return reconcile.Result{}, nil
+	}
+
+	p.lock.Lock()
+	defer p.lock.Unlock()
+	// Re-check under the lock in case a concurrent reconcile engaged it.
+	if _, ok := p.clusters[key]; ok {
 		return reconcile.Result{}, nil
 	}