Crate optionable 

Library to derive optioned structs/enums versions of existing types where all fields have been recursively replaced with versions that support setting just a subset of the relevant fields (or none at all).

One motivation for this concept is the common problem when expressing patches that for a given rust struct T a corresponding struct T::Optioned would be required where all fields are recursively optional to specify. While trivial to write for plain structures this quickly becomes tedious for nested structs/enums.

Kubernetes server-side-apply

The library allows to use server-side-apply with built-in Kubernetes types by providing optioned variants for all types from k8s-openapi. It also provides tooling to derive optioned variants for kube::CustomResource implementations.

For detailed documentation, see the documentation in kube for the CRD use case and the examples.

Deriving optional structs/enums

The core utility of this library is to provide an Optionable derive macro that derives such an optioned type and implements the corresponding Optionable trait. It supports nested structures, enums as well as various container types.

The general logic is the same as for other rust derives, If you want to use the Optionable derive macro for a struct/enum every field of it needs to also have implemented the corresponding Optionable trait:

 #[derive(Optionable)]
 #[optionable(derive(Default,Serialize,Deserialize))]
 struct Address {
     street_name: String,
     number: u8,
 }

 let _ = AddressOpt{
    street_name: Some("a".to_owned()),
    // fill the other fields with `None`
    ..Default::default()
 };

The generated optioned types are (shown here with resolved associated types) as follows. They can be also referenced as Address::Optioned and AddressEnum::Optioned respectively.

#[derive(Default,Serialize,Deserialize)]
struct AddressOpt {
    street_name: Option<String>,
    number: Option<u8>,
}

Enum support

Deriving optioned versions also works with enums:

#[derive(Optionable)]
enum AddressEnum {
     Plain(String),
     AddressExplicit { street: String, number: u32 },
     AddressNested(Address)
}

fn example(){
    let _ = AddressEnumOpt::AddressExplicit{
        street: Some("a".to_owned()),
        number: None
    };
}

Core concept

The main Optionable trait is quite simple:

pub trait Optionable {
    type Optioned;
}

It is a marker trait that allows to express for a given type T which type should be considered its T::Optioned type such that Option<T::Optioned> would represent all variants of partial completeness. For types without inner structure this means that the Optioned type will just resolve to the type itself, e.g.

impl Optionable for String {
    type Optioned = String;
}

For many primitive types as well as common wrapper or collection types the Optionable-trait is already implemented.

Conversion

Per default also conversion traits for struct/enums with sized fields will be derived. The relevant traits are OptionableConvert which is an extension trait for sized-fields only Optionable objects. The OptionedConvert described the way back, i.e. conversion from a partial optioned type to a full optionable type. They are (shown here without comments and where clauses):

pub trait OptionableConvert: Sized + Optionable {
    fn into_optioned(self) -> Self::Optioned;
    fn try_from_optioned(value: Self::Optioned) -> Result<Self, Error>;
    fn merge(&mut self, other: Self::Optioned) -> Result<(), Error>;
}

pub trait OptionedConvert<T>: Sized
{
    fn from_optionable(value: T) -> Self;
    fn try_into_optionable(self) -> Result<T, Error>;
}

Crate features

• derive: Default-feature, re-exports the Optionable derive macro.
• std: Default-feature. Adds Optionable-implementations for many std-lib types.
• alloc: Adds Optionable-implementations for alloc types (only useful when not enabling the std feature).
• serde_json: Derive Optionable for serde_json::Value.
• chrono04: Derive Optionable for types from chrono v0.4.
• jiff02: Derive Optionable for types from jiff v0.2.
• k8s_openapi026_v1_(30..=34): Adds Optionable-implementations for all k8s-openapi v0.26 types. Only one feature version, e.g. k8s_openapi026_v1_34 may be enabled at once.
• k8s_openapi_convert: Adds OptionableConvert-implementations for all optioned k8s-openapi types specified by the k8s_openapi026_v1_(30..=34) feature.
• kube: Tooling to derive optioned types for kube CustomResource. Also includes extract-functionality for server-side apply. Will replaced with a versioned kube3 after kube v3 has been released.

Limitations

External types

Due to the orphan rule the usage of the library becomes cumbersome if one has a use case which heavily relies on crate-external types.

If just have a few types from external crates don’t have an Optionable impl the example/orphanrule illustrates how to circumvent this limitation.

For well-established libraries adding corresponding impl to this crate (feature-gated) would be a worthwhile approach.

Resolving associated types

Due to the use of associated types some IDE-hints do not fully resolve the associated types leaving you with <i32 as Optionable>::Optioned instead of i32. Luckily, for checking type correctness and also for error messages when using wrong types the associated types are resolved.

For the derived Optioned-structs/enums a related issue is that other derive macros for those derived types won’t see the resolved associated types. Therefore, corresponding type bounds have to be added (done by the Optionable derive macro) to the Optioned-structs/enums:

#[derive(Optionable)]
#[optionable(derive(Serialize))]
struct DeriveExample<T> {
    name: T,
}

// The generated code for the struct is shown below (name adjusted and simplified)
#[derive(Serialize)]
struct DeriveExampleOpt2<T>
where
    T: Optionable,
    // extra `Serialize` bound on the struct level
    <T as Optionable>::Optioned: Sized + Serialize,
{
    #[serde(skip_serializing_if = "Option::is_none")]
    name: Option<<T as Optionable>::Optioned>
}

Similar crates

One crate with similar scope is optional_struct. It focuses specifically on structs (not enums) and offers a more manual approach, especially in respect to nested sub-struct, providing many fine-grained configuration options.

Another crate is struct-patch. It focuses on patching structs (not enums), especially from serde inputs. Nesting is supported with manual helper annotations.

Modules

kubekube

Tooling to derive optioned types for kube::CustomResource.

Structs

Error

Represents errors that occur when trying to build a full type from its optioned variant.

Traits

Optionable

Marker trait that associated this type with a corresponding type where potential inner sub-fields are recursively optional if possible for the given use case of the type. Implementations of the trait can decide that some fields are also non-optional for the optioned type.

OptionableConvert

Extension trait for sized Optionable to transform in and from optioned objects as well as merging.

OptionedConvert

Trait to transform from the perspective of the optioned type back to an origin Optionable type. OptionedConvert is more general than OptionableConvert as it allows targeting a T which itself does not implement Optionable. This allows to circumvent to some degree orphan rule restrictions when deriving Optionable ( see the optioned_type helper attribute for the Optionable derive macro).

Derive Macros

Optionablederive

Derive macro to derive the Optionable trait for structs/enums recursively by generating a type with all fields recursively replaced with Option versions. All non-required fields have to implement the Optionable trait. This trait is already implemented by this library for many primitive types, wrapper and container types.