[Merged by Bors] - Ensure that explicit YAML documents are generated for CRDs

CHANGELOG.md

@@ -8,13 +8,19 @@ All notable changes to this project will be documented in this file.
 
 - Cluster resources can be added to a struct which determines the orphaned
   resources and deletes them ([#436]).
+- YAML module added with a function to serialize a data structure as an
+  explicit YAML document. The YAML documents generated by the functions in
+  `crd::CustomResourceExt` are now explicit documents and can be safely
+  concatenated to produce a YAML stream ([#450]).
 
 ### Changed
 
 - BREAKING: The `managed_by` label must be passed explicitly to the
   `ObjectMetaBuilder::with_recommended_labels` function ([#436]).
+- serde\_yaml 0.8.26 -> 0.9 ([#450])
 
 [#436]: https://github.com/stackabletech/operator-rs/pull/436
+[#450]: https://github.com/stackabletech/operator-rs/pull/450
 
 ## [0.23.0] - 2022-07-26
 

Cargo.toml

@@ -23,7 +23,7 @@ regex = "1.6.0"
 schemars = "0.8.10"
 serde = { version = "1.0.140", features = ["derive"] }
 serde_json = "1.0.82"
-serde_yaml = "0.8.26"
+serde_yaml = "0.9"
 strum = { version = "0.24.1", features = ["derive"] }
 thiserror = "1.0.31"
 tokio = { version = "1.20.1", features = ["macros", "rt-multi-thread"] }
@@ -39,7 +39,6 @@ stackable-operator-derive = { path = "stackable-operator-derive" }
 [dev-dependencies]
 rstest = "0.15.0"
 tempfile = "3.3.0"
-serde_yaml = "0.8"
 
 [features]
 default = ["native-tls"]

src/cli.rs

@@ -11,10 +11,10 @@
 //! ```no_run
 //! // Handle CLI arguments
 //! use clap::{crate_version, Parser};
-//! use kube::{CustomResource, CustomResourceExt};
+//! use kube::CustomResource;
 //! use schemars::JsonSchema;
 //! use serde::{Deserialize, Serialize};
-//! use stackable_operator::cli;
+//! use stackable_operator::{CustomResourceExt, cli};
 //! use stackable_operator::error::OperatorResult;
 //!
 //! #[derive(Clone, CustomResource, Debug, JsonSchema, Serialize, Deserialize)]
@@ -55,11 +55,10 @@
 //! let opts = Opts::from_args();
 //!
 //! match opts.command {
-//!     cli::Command::Crd => println!(
-//!         "{}{}",
-//!         serde_yaml::to_string(&FooCluster::crd())?,
-//!         serde_yaml::to_string(&BarCluster::crd())?,
-//!     ),
+//!     cli::Command::Crd => {
+//!         FooCluster::print_yaml_schema()?;
+//!         BarCluster::print_yaml_schema()?;
+//!     },
 //!     cli::Command::Run { .. } => {
 //!         // Run the operator
 //!     }

src/commons/s3.rs

@@ -220,6 +220,7 @@ impl Default for S3AccessStyle {
 mod test {
     use crate::commons::s3::{S3AccessStyle, S3ConnectionDef};
     use crate::commons::s3::{S3BucketSpec, S3ConnectionSpec};
+    use crate::yaml;
 
     #[test]
     fn test_ser_inline() {
@@ -235,14 +236,13 @@ mod test {
         };
 
         assert_eq!(
-            serde_yaml::to_string(&bucket).unwrap(),
+            yaml::to_explicit_document_string(&bucket).unwrap(),
             "---
 bucketName: test-bucket-name
-connection:
-  inline:
-    host: host
-    port: 8080
-    accessStyle: VirtualHosted
+connection: !inline
+  host: host
+  port: 8080
+  accessStyle: VirtualHosted
 "
             .to_owned()
         )

src/crd.rs

@@ -5,6 +5,7 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 use crate::error::{Error, OperatorResult};
+use crate::yaml;
 use std::fs::File;
 use std::io::Write;
 use std::path::Path;
@@ -72,28 +73,36 @@ pub trait HasApplication {
 /// (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) -> OperatorResult<()>
     where
         W: Write,
     {
-        let schema = serde_yaml::to_string(&Self::crd())?;
+        let schema = yaml::to_explicit_document_string(&Self::crd())?;
         writer.write_all(schema.as_bytes())?;
         Ok(())
     }
 
     /// 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) -> OperatorResult<()> {
         let writer = File::create(path)?;
         Self::generate_yaml_schema(writer)
     }
 
     /// Generates a YAML CustomResourceDefinition and prints it to stdout.
+    ///
+    /// The printed YAML string is an explicit document with leading dashes (`---`).
     fn print_yaml_schema() -> OperatorResult<()> {
         let writer = std::io::stdout();
         Self::generate_yaml_schema(writer)
     }
 
     // Returns the YAML schema of this CustomResourceDefinition as a string.
+    ///
+    /// The written YAML string is an explicit document with leading dashes (`---`).
     fn yaml_schema() -> OperatorResult<String> {
         let mut writer = Vec::new();
         Self::generate_yaml_schema(&mut writer)?;

src/error.rs

@@ -9,6 +9,9 @@ pub enum Error {
         source: serde_yaml::Error,
     },
 
+    #[error("Failed to process YAML document: {message}")]
+    UnsupportedYamlDocumentError { message: String },
+
     #[error("Kubernetes reported error: {source}")]
     KubeError {
         #[from]

src/lib.rs

@@ -16,6 +16,7 @@ pub mod product_config_utils;
 pub mod role_utils;
 pub mod utils;
 pub mod validation;
+pub mod yaml;
 
 pub use crate::crd::CustomResourceExt;
 

src/yaml.rs

@@ -0,0 +1,95 @@
+//! Utility functions for processing data in the YAML file format
+use serde::ser;
+
+use crate::error::{Error, OperatorResult};
+
+/// A YAML document type
+///
+/// For a detailled description, see the
+/// [YAML specification](https://yaml.org/spec/1.2.2/#rule-l-any-document).
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum DocumentType {
+    DirectiveDocument,
+    ExplicitDocument,
+    BareDocument,
+}
+
+/// Serializes the given data structure as an explicit YAML document.
+///
+/// # Errors
+///
+/// Serialization can fail if `T`'s implementation of `Serialize` decides to return an error.
+///
+/// An [`Error::UnsupportedYamlDocumentError`] is returned if the used `serde_yaml` version
+/// generates a directive document.
+pub fn to_explicit_document_string<T>(value: &T) -> OperatorResult<String>
+where
+    T: ?Sized + ser::Serialize,
+{
+    // The returned document type depends on the serde_yaml version.
+    let document = serde_yaml::to_string(value)?;
+
+    match determine_document_type(&document) {
+        DocumentType::DirectiveDocument => Err(Error::UnsupportedYamlDocumentError {
+            message: "serde_yaml::to_string generated a directive document which cannot be \
+                converted to an explicit document."
+                .into(),
+        }),
+        DocumentType::ExplicitDocument => Ok(document),
+        DocumentType::BareDocument => Ok(format!("---\n{}", document)),
+    }
+}
+
+/// Determines the type of the given YAML document.
+///
+/// It is assumend that the given string contains a valid YAML document.
+pub fn determine_document_type(document: &str) -> DocumentType {
+    if document.starts_with('%') {
+        DocumentType::DirectiveDocument
+    } else if document.starts_with("---") {
+        DocumentType::ExplicitDocument
+    } else {
+        DocumentType::BareDocument
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::BTreeMap;
+
+    use super::*;
+
+    #[test]
+    fn value_can_be_serialized_to_an_explicit_document_string() {
+        let value: BTreeMap<_, _> = [("key", "value")].into();
+
+        let actual_yaml = to_explicit_document_string(&value).expect("serializable value");
+
+        let expected_yaml = "\
+            ---\n\
+            key: value\n";
+
+        assert_eq!(expected_yaml, actual_yaml);
+    }
+
+    #[test]
+    fn document_type_can_be_determined() {
+        let directive_document = "\
+            %YAML 1.2\n\
+            ---\n\
+            key: value";
+        let explicit_document = "\
+            ---\n\
+            key: value";
+        let bare_document = "\
+            key: value";
+
+        let directive_document_type = determine_document_type(directive_document);
+        let explicit_document_type = determine_document_type(explicit_document);
+        let bare_document_type = determine_document_type(bare_document);
+
+        assert_eq!(DocumentType::DirectiveDocument, directive_document_type);
+        assert_eq!(DocumentType::ExplicitDocument, explicit_document_type);
+        assert_eq!(DocumentType::BareDocument, bare_document_type);
+    }
+}