feat!: Add stackable-shared crate

CHANGELOG.md

@@ -6,6 +6,7 @@ Please see the relevant crate changelogs:
 - [stackable-certs](./crates/stackable-certs/CHANGELOG.md)
 - [stackable-operator](./crates/stackable-operator/CHANGELOG.md)
 - [stackable-operator-derive](./crates/stackable-operator-derive/CHANGELOG.md)
+- [stackable-shared](./crates/stackable-shared/CHANGELOG.md)
 - [stackable-telemetry](./crates/stackable-telemetry/CHANGELOG.md)
 - [stackable-versioned](./crates/stackable-versioned/CHANGELOG.md)
 - [stackable-webhook](./crates/stackable-webhook/CHANGELOG.md)

crates/stackable-operator/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Re-export the `YamlSchema` trait and the `stackable-shared` crate as the `shared` module ([#883]).
+
+### Changed
+
+- BREAKING: The `CustomResourceExt` trait is now re-exported from the `stackable-shared` crate. The
+  trait functions use the same parameters but return a different error type ([#883]).
+
+### Removed
+
+- BREAKING: The `CustomResourceExt` trait doesn't provide a `generate_yaml_schema` function any
+  more. Instead, use the high-level functions to write the schema to a file, write it to stdout or
+  use it as a `String`.
+
+[#883]: https://github.com/stackabletech/operator-rs/pull/883
+
 ## [0.78.0] - 2024-09-30
 
 ### Added

crates/stackable-operator/Cargo.toml

@@ -11,7 +11,8 @@ repository.workspace = true
 time = ["dep:time"]
 
 [dependencies]
-stackable-operator-derive = { path = "../stackable-operator-derive" }
+stackable-operator-derive = { path = "../stackable-operator-derive", version = "0.3.1" }
+stackable-shared = { path = "../stackable-shared", version = "0.0.1" }
 
 chrono.workspace = true
 clap.workspace = true

crates/stackable-operator/src/cli.rs

@@ -14,7 +14,7 @@
 //! use kube::CustomResource;
 //! use schemars::JsonSchema;
 //! use serde::{Deserialize, Serialize};
-//! use stackable_operator::{CustomResourceExt, cli, crd};
+//! use stackable_operator::{CustomResourceExt, cli, shared::crd};
 //!
 //! const OPERATOR_VERSION: &str = "23.1.1";
 //!
@@ -106,16 +106,17 @@
 //! ```
 //!
 //!
-use crate::logging::TracingTarget;
-use crate::namespace::WatchNamespace;
-use clap::Args;
-use product_config::ProductConfigManager;
-use snafu::{ResultExt, Snafu};
 use std::{
     ffi::OsStr,
     path::{Path, PathBuf},
 };
 
+use clap::Args;
+use product_config::ProductConfigManager;
+use snafu::{ResultExt, Snafu};
+
+use crate::{logging::TracingTarget, namespace::WatchNamespace};
+
 pub const AUTHOR: &str = "Stackable GmbH - info@stackable.tech";
 
 type Result<T, E = Error> = std::result::Result<T, E>;

crates/stackable-operator/src/crd.rs

@@ -2,40 +2,7 @@ use std::marker::PhantomData;
 
 use derivative::Derivative;
 use schemars::JsonSchema;
-use semver::Version;
 use serde::{Deserialize, Serialize};
-use snafu::{ResultExt, Snafu};
-
-use crate::yaml;
-use std::fs::File;
-use std::io::Write;
-use std::path::Path;
-
-const DOCS_HOME_URL_PLACEHOLDER: &str = "DOCS_BASE_URL_PLACEHOLDER";
-const DOCS_HOME_BASE_URL: &str = "https://docs.stackable.tech/home";
-
-type Result<T, E = Error> = std::result::Result<T, E>;
-
-#[derive(Debug, Snafu)]
-pub enum Error {
-    #[snafu(display("cannot parse version {version:?} as a semantic version"))]
-    InvalidSemverVersion {
-        source: semver::Error,
-        version: String,
-    },
-
-    #[snafu(display("error converting CRD byte array to UTF-8"))]
-    ConvertByteArrayToUtf8 { source: std::string::FromUtf8Error },
-
-    #[snafu(display("failed to serialize YAML"))]
-    SerializeYaml { source: yaml::Error },
-
-    #[snafu(display("failed to write YAML"))]
-    WriteYamlSchema { source: std::io::Error },
-
-    #[snafu(display("failed to create YAML file"))]
-    CreateYamlFile { source: std::io::Error },
-}
 
 /// A reference to a product cluster (for example, a `ZookeeperCluster`)
 ///
@@ -96,83 +63,6 @@ pub trait HasApplication {
     fn get_application_name() -> &'static str;
 }
 
-/// Takes an operator version and returns a docs version
-fn docs_version(operator_version: &str) -> Result<String> {
-    if operator_version == "0.0.0-dev" {
-        Ok("nightly".to_owned())
-    } else {
-        let v = Version::parse(operator_version).context(InvalidSemverVersionSnafu {
-            version: operator_version.to_owned(),
-        })?;
-        Ok(format!("{}.{}", v.major, v.minor))
-    }
-}
-
-/// Given an operator version like 0.0.0-dev or 23.1.1, generate a docs home
-/// component base URL like `https://docs.stackable.tech/home/nightly/` or
-/// `https://docs.stackable.tech/home/23.1/`.
-fn docs_home_versioned_base_url(operator_version: &str) -> Result<String> {
-    Ok(format!(
-        "{}/{}",
-        DOCS_HOME_BASE_URL,
-        docs_version(operator_version)?
-    ))
-}
-
-/// This trait can be implemented to allow automatic handling
-/// (e.g. creation) of `CustomResourceDefinition`s in Kubernetes.
-pub trait CustomResourceExt: kube::CustomResourceExt {
-    /// Generates a YAML CustomResourceDefinition and writes it to a `Write`.
-    ///
-    /// The generated YAML string is an explicit document with leading dashes (`---`).
-    fn generate_yaml_schema<W>(mut writer: W, operator_version: &str) -> Result<()>
-    where
-        W: Write,
-    {
-        let mut buffer = Vec::new();
-        yaml::serialize_to_explicit_document(&mut buffer, &Self::crd())
-            .context(SerializeYamlSnafu)?;
-
-        let yaml_schema = String::from_utf8(buffer)
-            .context(ConvertByteArrayToUtf8Snafu)?
-            .replace(
-                DOCS_HOME_URL_PLACEHOLDER,
-                &docs_home_versioned_base_url(operator_version)?,
-            );
-
-        writer
-            .write_all(yaml_schema.as_bytes())
-            .context(WriteYamlSchemaSnafu)
-    }
-
-    /// Generates a YAML CustomResourceDefinition and writes it to the specified file.
-    ///
-    /// The written YAML string is an explicit document with leading dashes (`---`).
-    fn write_yaml_schema<P: AsRef<Path>>(path: P, operator_version: &str) -> Result<()> {
-        let writer = File::create(path).context(CreateYamlFileSnafu)?;
-        Self::generate_yaml_schema(writer, operator_version)
-    }
-
-    /// Generates a YAML CustomResourceDefinition and prints it to stdout.
-    ///
-    /// The printed YAML string is an explicit document with leading dashes (`---`).
-    fn print_yaml_schema(operator_version: &str) -> Result<()> {
-        let writer = std::io::stdout();
-        Self::generate_yaml_schema(writer, operator_version)
-    }
-
-    /// Returns the YAML schema of this CustomResourceDefinition as a string.
-    ///
-    /// The written YAML string is an explicit document with leading dashes (`---`).
-    fn yaml_schema(operator_version: &str) -> Result<String> {
-        let mut writer = Vec::new();
-        Self::generate_yaml_schema(&mut writer, operator_version)?;
-        String::from_utf8(writer).context(ConvertByteArrayToUtf8Snafu)
-    }
-}
-
-impl<T> CustomResourceExt for T where T: kube::CustomResourceExt {}
-
 #[cfg(test)]
 mod tests {
     use k8s_openapi::api::core::v1::ConfigMap;

crates/stackable-operator/src/helm/mod.rs

@@ -79,7 +79,7 @@ mod tests {
 
     use rstest::rstest;
 
-    use crate::yaml::serialize_to_explicit_document;
+    use stackable_shared::yaml::{serialize as ser, SerializeOptions};
 
     use super::*;
 
@@ -102,7 +102,7 @@ mod tests {
         let expected = std::fs::read_to_string("fixtures/helm/output.yaml").unwrap();
 
         let mut output = Vec::new();
-        serialize_to_explicit_document(&mut output, &values).unwrap();
+        ser(&values, &mut output, SerializeOptions::default()).unwrap();
 
         assert_eq!(std::str::from_utf8(&output).unwrap(), expected);
     }

crates/stackable-operator/src/lib.rs

@@ -20,10 +20,15 @@ pub mod status;
 pub mod time;
 pub mod utils;
 pub mod validation;
-pub mod yaml;
 
-pub use crate::crd::CustomResourceExt;
+// Internal re-exports
+pub use stackable_shared::{crd::CustomResourceExt, yaml::YamlSchema};
 
+pub mod shared {
+    pub use stackable_shared::*;
+}
+
+// External re-exports
 pub use ::k8s_openapi;
 pub use ::kube;
 pub use ::schemars;

crates/stackable-shared/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.0.1]
+
+### Added
+
+- Add YAML and CRD helper functions and traits ([#883]).
+
+[#883]: https://github.com/stackabletech/operator-rs/pull/883

crates/stackable-shared/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "stackable-shared"
+version = "0.0.1"
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+
+[dependencies]
+kube.workspace = true
+semver.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true
+snafu.workspace = true
+
+[dev-dependencies]
+k8s-openapi.workspace = true