feat: add framework builder, kvp, and utility modules

Port remaining framework modules from the opensearch-operator reference:
builder (meta, pdb, pod, statefulset), kvp labels, product logging,
cluster resources, controller utils, role/role-group utilities.

These provide infallible wrappers around stackable-operator builder APIs
and type-safe resource name derivation with compile-time length assertions.
All code is currently unused and will be wired into the controller in the
next commit.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: adwk67

rust/operator-binary/src/framework.rs

@@ -21,7 +21,21 @@
 
 use types::kubernetes::Uid;
 
+#[allow(dead_code)]
+pub mod builder;
+#[allow(dead_code)]
+pub mod cluster_resources;
+#[allow(dead_code)]
+pub mod controller_utils;
+#[allow(dead_code)]
+pub mod kvp;
 pub mod macros;
+#[allow(dead_code)]
+pub mod product_logging;
+#[allow(dead_code)]
+pub mod role_group_utils;
+#[allow(dead_code)]
+pub mod role_utils;
 pub mod types;
 
 /// Has a non-empty name
@@ -34,11 +48,13 @@ pub trait HasName {
 }
 
 /// Has a Kubernetes UID
+#[allow(dead_code)]
 pub trait HasUid {
     fn to_uid(&self) -> Uid;
 }
 
 /// The name is a valid label value
+#[allow(dead_code)]
 pub trait NameIsValidLabelValue {
     fn to_label_value(&self) -> String;
 }

rust/operator-binary/src/framework/builder.rs

@@ -0,0 +1,8 @@
+#[allow(dead_code)]
+pub mod meta;
+#[allow(dead_code)]
+pub mod pdb;
+#[allow(dead_code)]
+pub mod pod;
+#[allow(dead_code)]
+pub mod statefulset;

rust/operator-binary/src/framework/builder/meta.rs

@@ -0,0 +1,108 @@
+use stackable_operator::{
+    builder::meta::OwnerReferenceBuilder,
+    k8s_openapi::apimachinery::pkg::apis::meta::v1::OwnerReference, kube::Resource,
+};
+
+use crate::framework::{HasName, HasUid};
+
+/// Infallible variant of
+/// [`stackable_operator::builder::meta::ObjectMetaBuilder::ownerreference_from_resource`]
+pub fn ownerreference_from_resource(
+    resource: &(impl Resource<DynamicType = ()> + HasName + HasUid),
+    block_owner_deletion: Option<bool>,
+    controller: Option<bool>,
+) -> OwnerReference {
+    OwnerReferenceBuilder::new()
+        // Set api_version, kind, name and additionally the UID if it exists.
+        .initialize_from_resource(resource)
+        // Ensure that the name is set.
+        .name(resource.to_name())
+        // Ensure that the UID is set.
+        .uid(resource.to_uid().to_string())
+        .block_owner_deletion_opt(block_owner_deletion)
+        .controller_opt(controller)
+        .build()
+        .expect(
+            "OwnerReference should be created because the resource has an api_version, kind, name \
+            and uid.",
+        )
+}
+
+#[cfg(test)]
+mod tests {
+    use std::borrow::Cow;
+
+    use stackable_operator::{
+        k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta, kube::Resource,
+    };
+
+    use crate::framework::{
+        HasName, HasUid, builder::meta::ownerreference_from_resource, types::kubernetes::Uid,
+    };
+
+    struct TestCluster {
+        object_meta: ObjectMeta,
+    }
+
+    impl TestCluster {
+        fn new() -> Self {
+            TestCluster {
+                object_meta: ObjectMeta {
+                    name: Some("test-cluster".to_owned()),
+                    uid: Some("a6b89911-d48e-4328-88d6-b9251226583d".to_owned()),
+                    ..ObjectMeta::default()
+                },
+            }
+        }
+    }
+
+    impl Resource for TestCluster {
+        type DynamicType = ();
+        type Scope = ();
+
+        fn kind(_dt: &Self::DynamicType) -> Cow<'_, str> {
+            Cow::from("HiveCluster")
+        }
+
+        fn group(_dt: &Self::DynamicType) -> Cow<'_, str> {
+            Cow::from("hive.stackable.tech")
+        }
+
+        fn version(_dt: &Self::DynamicType) -> Cow<'_, str> {
+            Cow::from("v1alpha1")
+        }
+
+        fn plural(_dt: &Self::DynamicType) -> Cow<'_, str> {
+            Cow::from("hiveclusters")
+        }
+
+        fn meta(&self) -> &ObjectMeta {
+            &self.object_meta
+        }
+
+        fn meta_mut(&mut self) -> &mut ObjectMeta {
+            &mut self.object_meta
+        }
+    }
+
+    impl HasName for TestCluster {
+        fn to_name(&self) -> String {
+            self.object_meta.name.clone().expect("set in new()")
+        }
+    }
+
+    impl HasUid for TestCluster {
+        fn to_uid(&self) -> Uid {
+            Uid::from_str_unsafe(&self.object_meta.uid.clone().expect("set in new()"))
+        }
+    }
+
+    #[test]
+    fn test_ownerreference_from_resource() {
+        let owner_ref = ownerreference_from_resource(&TestCluster::new(), Some(true), Some(true));
+        assert_eq!(owner_ref.name, "test-cluster");
+        assert_eq!(owner_ref.uid, "a6b89911-d48e-4328-88d6-b9251226583d");
+        assert_eq!(owner_ref.controller, Some(true));
+        assert_eq!(owner_ref.block_owner_deletion, Some(true));
+    }
+}

rust/operator-binary/src/framework/builder/pdb.rs

@@ -0,0 +1,161 @@
+use stackable_operator::{
+    builder::pdb::PodDisruptionBudgetBuilder,
+    k8s_openapi::apimachinery::pkg::apis::meta::v1::LabelSelector,
+    kube::{Resource, api::ObjectMeta},
+};
+
+use crate::framework::{
+    HasName, HasUid, NameIsValidLabelValue,
+    types::operator::{ControllerName, OperatorName, ProductName, RoleName},
+};
+
+/// Infallible variant of
+/// [`stackable_operator::builder::pdb::PodDisruptionBudgetBuilder::new_with_role`]
+pub fn pod_disruption_budget_builder_with_role(
+    owner: &(impl Resource<DynamicType = ()> + HasName + NameIsValidLabelValue + HasUid),
+    product_name: &ProductName,
+    role_name: &RoleName,
+    operator_name: &OperatorName,
+    controller_name: &ControllerName,
+) -> PodDisruptionBudgetBuilder<ObjectMeta, LabelSelector, ()> {
+    PodDisruptionBudgetBuilder::new_with_role(
+        owner,
+        &product_name.to_label_value(),
+        &role_name.to_label_value(),
+        &operator_name.to_label_value(),
+        &controller_name.to_label_value(),
+    )
+    .expect(
+        "PodDisruptionBudgetBuilder should be created because the owner has an object name and UID \
+        and all given parameters produce valid label values.",
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use std::borrow::Cow;
+
+    use stackable_operator::{
+        k8s_openapi::{
+            api::policy::v1::{PodDisruptionBudget, PodDisruptionBudgetSpec},
+            apimachinery::pkg::{
+                apis::meta::v1::{LabelSelector, ObjectMeta, OwnerReference},
+                util::intstr::IntOrString,
+            },
+        },
+        kube::Resource,
+    };
+
+    use crate::framework::{
+        HasName, HasUid, NameIsValidLabelValue,
+        builder::pdb::pod_disruption_budget_builder_with_role,
+        types::{
+            kubernetes::Uid,
+            operator::{ControllerName, OperatorName, ProductName, RoleName},
+        },
+    };
+
+    struct Cluster {
+        object_meta: ObjectMeta,
+    }
+
+    impl Cluster {
+        fn new() -> Self {
+            Cluster {
+                object_meta: ObjectMeta {
+                    name: Some("cluster-name".to_owned()),
+                    uid: Some("a6b89911-d48e-4328-88d6-b9251226583d".to_owned()),
+                    ..ObjectMeta::default()
+                },
+            }
+        }
+    }
+
+    impl Resource for Cluster {
+        type DynamicType = ();
+        type Scope = ();
+
+        fn kind(_dt: &Self::DynamicType) -> Cow<'_, str> { Cow::from("HiveCluster") }
+        fn group(_dt: &Self::DynamicType) -> Cow<'_, str> { Cow::from("hive.stackable.tech") }
+        fn version(_dt: &Self::DynamicType) -> Cow<'_, str> { Cow::from("v1alpha1") }
+        fn plural(_dt: &Self::DynamicType) -> Cow<'_, str> { Cow::from("hiveclusters") }
+
+        fn meta(&self) -> &ObjectMeta { &self.object_meta }
+        fn meta_mut(&mut self) -> &mut ObjectMeta { &mut self.object_meta }
+    }
+
+    impl HasName for Cluster {
+        fn to_name(&self) -> String {
+            self.object_meta.name.clone().expect("set in new()")
+        }
+    }
+
+    impl HasUid for Cluster {
+        fn to_uid(&self) -> Uid {
+            Uid::from_str_unsafe(&self.object_meta.uid.clone().expect("set in new()"))
+        }
+    }
+
+    impl NameIsValidLabelValue for Cluster {
+        fn to_label_value(&self) -> String {
+            self.object_meta.name.clone().expect("set in new()")
+        }
+    }
+
+    #[test]
+    fn test_pod_disruption_budget_builder_with_role() {
+        let actual_pdb = pod_disruption_budget_builder_with_role(
+            &Cluster::new(),
+            &ProductName::from_str_unsafe("my-product"),
+            &RoleName::from_str_unsafe("my-role"),
+            &OperatorName::from_str_unsafe("my-operator"),
+            &ControllerName::from_str_unsafe("my-controller"),
+        )
+        .with_max_unavailable(2)
+        .build();
+
+        let expected_pdb = PodDisruptionBudget {
+            metadata: ObjectMeta {
+                labels: Some(
+                    [
+                        ("app.kubernetes.io/component", "my-role"),
+                        ("app.kubernetes.io/instance", "cluster-name"),
+                        ("app.kubernetes.io/managed-by", "my-operator_my-controller"),
+                        ("app.kubernetes.io/name", "my-product"),
+                    ]
+                    .map(|(k, v)| (k.to_owned(), v.to_owned()))
+                    .into(),
+                ),
+                name: Some("cluster-name-my-role".to_owned()),
+                owner_references: Some(vec![OwnerReference {
+                    api_version: "hive.stackable.tech/v1alpha1".to_owned(),
+                    controller: Some(true),
+                    kind: "HiveCluster".to_owned(),
+                    name: "cluster-name".to_owned(),
+                    uid: "a6b89911-d48e-4328-88d6-b9251226583d".to_owned(),
+                    ..OwnerReference::default()
+                }]),
+                ..ObjectMeta::default()
+            },
+            spec: Some(PodDisruptionBudgetSpec {
+                max_unavailable: Some(IntOrString::Int(2)),
+                selector: Some(LabelSelector {
+                    match_labels: Some(
+                        [
+                            ("app.kubernetes.io/component", "my-role"),
+                            ("app.kubernetes.io/instance", "cluster-name"),
+                            ("app.kubernetes.io/name", "my-product"),
+                        ]
+                        .map(|(k, v)| (k.to_owned(), v.to_owned()))
+                        .into(),
+                    ),
+                    ..LabelSelector::default()
+                }),
+                ..PodDisruptionBudgetSpec::default()
+            }),
+            ..PodDisruptionBudget::default()
+        };
+
+        assert_eq!(expected_pdb, actual_pdb);
+    }
+}

rust/operator-binary/src/framework/builder/pod.rs

@@ -0,0 +1,2 @@
+pub mod container;
+pub mod volume;