Merge branch 'main' into feat/stackable-telemetry-options

Author: NickLarsenNZ

crates/stackable-versioned-macros/fixtures/inputs/default/convert_with.rs

@@ -0,0 +1,12 @@
+#[versioned(version(name = "v1alpha1"), version(name = "v1"), version(name = "v2"))]
+// ---
+struct Foo {
+    #[versioned(
+        // This tests two additional things:
+        // - that both unquoted and quoted usage works
+        // - that the renamed name does get picked up correctly by the conversion function
+        changed(since = "v1", from_type = "u16", from_name = "bar", convert_with = u16_to_u32),
+        changed(since = "v2", from_type = "u32", convert_with = "u32_to_u64")
+    )]
+    baz: u64,
+}

crates/stackable-versioned-macros/fixtures/snapshots/stackable_versioned_macros__test__default_snapshots@convert_with.rs.snap

@@ -237,6 +237,19 @@ impl CommonItemAttributes {
                     );
                 }
             }
+
+            // The convert_with argument only makes sense to use when the
+            // type changed
+            if let Some(convert_func) = change.convert_with.as_ref() {
+                if change.from_type.is_none() {
+                    errors.push(
+                        Error::custom(
+                            "the `convert_with` argument must be used in combination with `from_type`",
+                        )
+                        .with_span(&convert_func.span()),
+                    );
+                }
+            }
         }
 
         errors.finish()
@@ -307,9 +320,10 @@ impl CommonItemAttributes {
                 actions.insert(
                     *change.since,
                     ItemStatus::Change {
+                        convert_with: change.convert_with.as_deref().cloned(),
                         from_ident: from_ident.clone(),
-                        to_ident: ident,
                         from_type: from_ty.clone(),
+                        to_ident: ident,
                         to_type: ty,
                     },
                 );
@@ -356,9 +370,10 @@ impl CommonItemAttributes {
                 actions.insert(
                     *change.since,
                     ItemStatus::Change {
+                        convert_with: change.convert_with.as_deref().cloned(),
                         from_ident: from_ident.clone(),
-                        to_ident: ident,
                         from_type: from_ty.clone(),
+                        to_ident: ident,
                         to_type: ty,
                     },
                 );
@@ -431,12 +446,14 @@ fn default_default_fn() -> SpannedValue<Path> {
 ///
 /// Example usage:
 /// - `changed(since = "...", from_name = "...")`
-/// - `changed(since = "...", from_name = "..." from_type="...")`
+/// - `changed(since = "...", from_name = "...", from_type="...")`
+/// - `changed(since = "...", from_name = "...", from_type="...", convert_with = "...")`
 #[derive(Clone, Debug, FromMeta)]
-pub(crate) struct ChangedAttributes {
-    pub(crate) since: SpannedValue<Version>,
-    pub(crate) from_name: Option<SpannedValue<String>>,
-    pub(crate) from_type: Option<SpannedValue<Type>>,
+pub struct ChangedAttributes {
+    pub since: SpannedValue<Version>,
+    pub from_name: Option<SpannedValue<String>>,
+    pub from_type: Option<SpannedValue<Type>>,
+    pub convert_with: Option<SpannedValue<Path>>,
 }
 
 /// For the deprecated() action

crates/stackable-versioned-macros/src/attrs/item/mod.rs

@@ -167,18 +167,29 @@ impl VersionedField {
                         _,
                         ItemStatus::Change {
                             from_ident: old_field_ident,
+                            convert_with,
                             to_ident,
                             ..
                         },
-                    ) => {
-                        quote! {
+                    ) => match convert_with {
+                        // The user specified a custom conversion function which
+                        // will be used here instead of the default .into() call
+                        // which utilizes From impls.
+                        Some(convert_fn) => quote! {
+                            #to_ident: #convert_fn(#from_struct_ident.#old_field_ident),
+                        },
+                        // Default .into() call using From impls.
+                        None => quote! {
                             #to_ident: #from_struct_ident.#old_field_ident.into(),
-                        }
-                    }
+                        },
+                    },
                     (old, next) => {
                         let next_field_ident = next.get_ident();
                         let old_field_ident = old.get_ident();
 
+                        // NOTE (@Techassi): Do we really need .into() here. I'm
+                        // currently not sure why it is there and if it is needed
+                        // in some edge cases.
                         quote! {
                             #next_field_ident: #from_struct_ident.#old_field_ident.into(),
                         }

crates/stackable-versioned-macros/src/codegen/item/field.rs

@@ -72,7 +72,7 @@ impl From<&ModuleAttributes> for Vec<VersionDefinition> {
 }
 
 #[derive(Debug, PartialEq)]
-pub(crate) enum ItemStatus {
+pub enum ItemStatus {
     Addition {
         ident: IdentString,
         default_fn: Path,
@@ -81,6 +81,7 @@ pub(crate) enum ItemStatus {
         ty: Type,
     },
     Change {
+        convert_with: Option<Path>,
         from_ident: IdentString,
         to_ident: IdentString,
         from_type: Type,

crates/stackable-versioned-macros/src/codegen/mod.rs

@@ -29,7 +29,7 @@ mod utils;
 /// example, `#[automatically_derived]` and `#[allow(deprecated)]` are removed
 /// in most examples to reduce visual clutter.
 ///
-/// ## Declaring Versions
+/// <div class="warning">
 ///
 /// It is **important** to note that this macro must be placed before any other
 /// (derive) macros and attributes. Macros supplied before the versioned macro
@@ -38,16 +38,29 @@ mod utils;
 /// attributes are applied to the generated versioned instances of the
 /// container.
 ///
+/// </div>
+///
+/// ## Declaring Versions
+///
 /// Before any of the fields or variants can be versioned, versions need to be
 /// declared at the container level. Each version currently supports two
 /// parameters: `name` and the `deprecated` flag. The `name` must be a valid
 /// (and supported) format.
 ///
 /// <div class="warning">
+///
 /// Currently, only Kubernetes API versions are supported. The macro checks each
 /// declared version and reports any error encountered during parsing.
+///
 /// </div>
 ///
+/// It should be noted that the defined struct always represents the **latest**
+/// version, eg: when defining three versions `v1alpha1`, `v1beta1`, and `v1`,
+/// the struct will describe the structure of the data in `v1`. This behaviour
+/// is especially noticeable in the [`changed()`](#changed-action) action which
+/// works "backwards" by describing how a field looked before the current
+/// (latest) version.
+///
 /// ```
 /// # use stackable_versioned_macros::versioned;
 /// #[versioned(version(name = "v1alpha1"))]
@@ -252,12 +265,6 @@ mod utils;
 /// }
 /// ```
 ///
-/// <div class="warning">
-/// It is planned to move the <code>preserve_module</code> flag into the
-/// <code>options()</code> argument list, but currently seems tricky to
-/// implement.
-/// </div>
-///
 /// ## Item Actions
 ///
 /// This crate currently supports three different item actions. Items can
@@ -393,6 +400,10 @@ mod utils;
 /// - `since` to indicate since which version the item is changed.
 /// - `from_name` to indicate from which previous name the field is renamed.
 /// - `from_type` to indicate from which previous type the field is changed.
+/// - `convert_with` to provide a custom conversion function instead of using
+///   a [`From`] implementation by default. This argument can only be used in
+///   combination with the `from_type` argument. The expected function signature
+///   is: `fn (OLD_TYPE) -> NEW_TYPE`. This function must not fail.
 ///
 /// ```
 /// # use stackable_versioned_macros::versioned;
@@ -514,6 +525,61 @@ mod utils;
 /// This automatic generation can be skipped to enable a custom implementation
 /// for more complex conversions.
 ///
+/// ### Custom conversion function at field level
+///
+/// As stated in the [`changed()`](#changed-action) section, a custom conversion
+/// function can be provided using the `convert_with` argument. A simple example
+/// looks like this:
+///
+/// ```
+/// # use stackable_versioned_macros::versioned;
+/// #[versioned(
+///     version(name = "v1alpha1"),
+///     version(name = "v1beta1")
+/// )]
+/// pub struct Foo {
+///     #[versioned(changed(
+///         since = "v1beta1",
+///         from_type = "u8",
+///         convert_with = "u8_to_u16"
+///     ))]
+///     bar: u16,
+/// }
+///
+/// fn u8_to_u16(old: u8) -> u16 {
+///     old as u16
+/// }
+/// ```
+///
+/// <details>
+/// <summary>Expand Generated Code</summary>
+///
+/// ```ignore
+/// pub mod v1alpha1 {
+///     use super::*;
+///     pub struct Foo {
+///         pub bar: u8,
+///     }
+/// }
+///
+/// impl ::std::convert::From<v1alpha1::Foo> for v1beta1::Foo {
+///     fn from(__sv_foo: v1alpha1::Foo) -> Self {
+///         Self {
+///             bar: u8_to_u16(__sv_foo.bar),
+///         }
+///     }
+/// }
+///
+/// pub mod v1beta1 {
+///     use super::*;
+///     pub struct Foo {
+///         pub bar: u16,
+///     }
+/// }
+/// ```
+///
+/// </details>
+///
 /// ### Skipping at the Container Level
 ///
 /// Disabling this behavior at the container level results in no `From`
@@ -601,6 +667,11 @@ println!("{}", serde_yaml::to_string(&merged_crd).unwrap());
 # }
 ```
 
+The generated `merged_crd` method is a wrapper around [kube's `merge_crds`][1]
+function. It automatically calls the `crd` methods of the CRD in all of its
+versions and additionally provides a strongly typed selector for the stored
+API version.
+
 Currently, the following arguments are supported:
 
 - `group`: Set the group of the CR object, usually the domain of the company.

crates/stackable-versioned-macros/src/lib.rs

@@ -30,7 +30,7 @@ struct Foo {
     /// My docs
     #[versioned(
         added(since = "v1alpha1"),
-        renamed(since = "v1beta1", from = "gau"),
+        changed(since = "v1beta1", from_name = "gau"),
         deprecated(since = "v2", note = "not required anymore")
     )]
     deprecated_bar: usize,