And, as mentioned, whilst they're on my mind, I wanted to dump on some various reflections regarding model generation in rust, off the back of some painful experience with the Rust Open-API generator...

These are all rather opinionated, so could do with moving to some kind of discussion place / moving off elsewhere, when there's a separate rust repo.

Boxing

To avoid issues with large stack usage and recursive types, there will have to be some use of boxes.

Possibly the least painful place to put them is in enum variants, and Option<Box<T>> - as this prevents the two biggest issues - recursive types and large enum variants causing excessive stack usage in the other variants.

The largest struct stack size then is bounded by the size of the struct definitions open api schema.

But possibly we should also have boxing of struct fields... Open to reflections here:

Are we happy with arbitrarily large structs? (probably?)
We could possibly consider adding boxes into the generated models in particular places dependent on the size of structs below (e.g. after 1KB of stack or something). But this might be rather arbitrary.
Possibly boxing every child struct/enum might be a simpler model, although much more expensive in terms of allocations.
Smithy Rust uses a nice algorithm to make a deterministic choice about where to insert boxes

Iteration order

Ideally the extended "properties" collection would use "insertion" order. That way, { "x" => 1, "a" => 2 } would come out correctly with "x" before "a". This is quite important in some use cases, and would require use of the index_map crate, as hashmap makes no iteration ordering guarantees, and btreemap uses alphabetical ordering.

Perhaps this can be a feature or generation option. Like it is with the rust open api generator.

Inheritance

Note - I love this guide from Redocly regarding common patterns with oneOf/anyOf/allOf and use of discriminators.

Consider:

# Pseudo-Schema (all fields required unless marked with a ?)
AnimalMixin = object:{ name: string }
Gift = object:{ name: string }
FelineMixin = object:{ purrs: bool }:additional_properties=Gift
PetType = string:enum=["Dog", "Cat"]
PetTypeExtensible = string:AnyOf=[PetType, {}] // Makes it extensible
Pet = object:AllOf=[
    AnimalMixin,
    object:{ pet_type: PetType }:discriminator("pet_type", { "dog": Dog, "cat": Cat })
]
Dog = object:AllOf=[Pet, object:{ barks: bool }]
Cat = object:AllOf=[Pet, FelineMixin, object:{ licks: bool }]

Now the interpretation of the above is a bit gnarly, even in a single-parent inheritance language:

Should Dog have a pet_type field? Or property / getter? Should it be fixed as "Dog" in the serializer?
- I think given Dog is a Pet and the only valid Pet has "dog", the answer ideally would be "no field", "readonly getter" (but I haven't looked at what kiota does here)
Should Cat inherit from Pet? What about FelineMixin?
- I assume Kiota has Cat inherit from Pet, but I haven't checked what rules it uses.

In any case, I assume kiota must have some default representation of this object in its internal CodeDom representation, but I haven't dug into this too deeply.

We'd then need to work out how to map this to Rust. Personally, I'd propose the following, which would solve some pain points we have with the open api generator we are currently using.

My vision would be roughly:

To have concrete structs for each leaf in the hierachy... and probably each internal node too
To also output enums for any object with a discriminator
Add some ability to interpret descendents as their ancestors in the type hierachy (by using trait objects and From)

enum PetType {
    Dog,
    Cat,
}

enum Pet {
    Dog(Box<Dog>),
    Cat(Box<Dog>),
}

struct Dog { // Implicitly has `pet_name: PetType::Dog`
    pub name: String,
    pub barks: bool,
}

struct Cat { // Implicitly has `pet_name: PetType::Cat`
    pub name: String,
    pub purrs: bool,
    pub licks: bool,
    pub properties: IndexMap<String, Gift>,
}

struct Gift {
    pub name: String,
}

// And then From implementations for the type hierachy
impl From<Dog> for Pet { /* ... */ }
impl From<Dog> for AnimalMixin { /* ... */ }
impl From<Cat> for Pet { /* ... */ }
impl From<Cat> for AnimalMixin { /* ... */ }
impl From<Cat> for FelineMixin { /* ... */ }

// Traits representing the type hierachy; some assorted ones below. Every type could include a trait conceptually.
// For each property `x`:
// * There are `x_ref` and `x_mut` allowing access to a shared or unique reference (naming is in keeping with the `AsRef` / `AsMut` traits)
// * There is a `set_x` method to allow the use of a builder pattern.
// * Sometimes (for types implementing copy: value types or Open API enums) we also implement `get_x` which returns an owned type.
// Additional properties are exposed with a separate `additional_properties_ref` / `additional_properties_mut`
// 
// Note - for each type we have an associated object safe trait, `AsX`, and a full trait `IsX` (names TBC):
// See https://doc.rust-lang.org/reference/items/traits.html#object-safety
trait AsAnimalMixin {
    fn name_ref(&self) -> &str;
    fn name_mut(&self) -> &mut str;
    fn set_name(&mut self, value: String) -> &mut Self;
}
trait IsAnimalMixin: AsAnimalMixin + Into<AnimalMixin> {};
trait AsPet: AsAnimalMixin {
    fn get_pet_type(&self) -> PetType;
    fn pet_type_ref(&self) -> &PetType; // We may need to have a static PetType variant to allow this to work for Cat/Dog
    // NOTE: The following would panic on a discriminated child of Pet e.g. a Cat/Dog which can't mutate PetType.
    fn set_pet_type(&mut self, value: PetType) -> &mut Self;
    fn pet_type_mut(&self) -> &mut PetType;
}
trait IsPet: AsPet + IsAnimalMixin + Into<Pet> {};
trait AsFelineMixin {
    fn get_purrs(&self) -> bool;
    fn set_purrs(&mut self, value: bool) -> &mut Self;
    fn purrs_ref(&self) -> &bool;
    fn purrs_mut(&self) -> &'mut bool;

    fn additional_properties_ref(&self) -> &IndexMap<String, Gift>;
    fn additional_properties_mut(&mut self) -> &mut IndexMap<String, Gift>;
}
trait IsFelineMixin: AsFelineMixin + Into<FelineMixin> {}

// And the trait impls would be as follows:
// * X implements AsX and IsX
// * If X is an ancestor of Y then X implements AsY, and IsY... and Y implements From<X>.
// e.g. for Dog:
impl AsAnimalMixin for Dog { /* ... */ }
impl From<Dog> for AnimalMixin { /* ... */ } // Gives Dog: Into<AnimalMixin>
impl IsAnimalMixin for Dog {}
impl AsPet for Dog { /* ... */ }
impl From<Dog> for Pet { /* ... */ }
impl IsPet for Dog {}
impl AsDog for Dog { /* ... */ }
impl IsDog for Dog {}

API Extensibility and Completeness

For completeness, we may also need some struct representation of each intermediate "class" in the hierachy, such as the "Pet" class without the discriminator.

Even with a discriminator on an OAS type, such a base type is typically used as a fallback by OOP OAS generators in the case where a discriminator doesn't match. This is important for ensuring an Open API client stays compatible with certain kinds of schema extension, allowing API writers to add new variants in particular places without failing the whole request decoding.

// This fits inside the hierachy under Pet
struct PetBase {
    pub name: String,
    pub pet_type: PetType,
}

trait AsPetBase: AsAnimalMixin {
    fn get_pet_type(&self) -> PetType;
    fn set_pet_type(&mut self, value: PetType) -> &mut Self;
}
trait IsPetBase: AsPetBase + IsAnimalMixin + Into<PetBase>;

// We'd then wish to modify Pet as follows:
enum Pet {
    Dog(Box<Dog>),
    Cat(Box<Dog>),
    Unmatched(Box<PetBase>),
}

// And we modify IsPet and AsPet to inherit from IsPetBase instead of IsAnimalMixin
// And we add various impls for IsPetBase and AsPetBase...
impl AsPetBase for PetBase { /* .. */ }
impl AsPetBase for Pet { /* .. */ }
impl AsPetBase for Dog { /* .. */ }
impl AsPetBase for Cat { /* .. */ }

Although in this case, because we are using an enum as a discriminator, this extension wouldn't actually be beneficial, because we can't add a new enum variant without it being a breaking change to the API schema.

So, let's change Pet to use pet_type: PetTypeExtensible (or picked up on some Open API extension which suggested enums were extensible) then I'd expect to generate something like the following. This would allow a new pet such as a "Hamster" to be decoded as a Pet::Unmatched(PetBase { pet_type: PetTypeExtensible::Other("hamster"), .. }) without breaking the rest of the request deserialization:

enum PetTypeExtensible {
    Dog,
    Cat,
    Other(String),
}

// This fits inside the hierachy under Pet
struct PetBase {
    pub name: String,
    pub pet_type: PetTypeExtensible,
}

trait AsPetBase: AsAnimalMixin + Into<PetBase> {
    fn get_pet_type(&self) -> PetTypeExtensible;
    fn set_pet_type(&mut self, value: PetTypeExtensible) -> &mut Self;
}

NOTE: This could also conceivable be allowed as a general option in the schema generation, something like enumUnknownDefaultCase in this comment to allow for extensible enums.

Unions (oneOf, anyOf)

AnyOf / OneOf with a discriminator would also support an enum - but wouldn't support inheritance through it.
AnyOf / OneOf without a discriminator may also likely need to use some kind of struct, with Option<Box<X>> for each of the different options which matched. This would depend on how these are represented/supported in kiota - support for these based on structural validity is one of a number of areas of the Open API spec which is ugly and in-performant to support / be spec-compliant with.

Required and Nullable

A not-required field should map to Option<X>
Nullable should map to kiota_abstractions::Nullable<X>, with options Null and NotNull which should implement many similar things to Option.

A non-required, nullable field would be Option<Nullable<X>>. Ideally we could implement various trait on Option<Nullable<X>> to let you easily create and as_ref / as_mut the value.

Derives

Structs representing Open API objects can implement Clone, Debug, Eq, PartialEq... and I guess I'd consider Ord, PartialOrd, Hash
Enums representing Open API discriminators can implement Clone, Debug, Eq, PartialEq... and I guess I'd consider Ord, PartialOrd, Hash
Enums representing Open API enums can implement Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash

We could also have Default - but only if all its children support default (e.g. enums can't support default) - this has been broken in the past in the Open API generator.

Constructors

I'd be tempted to not have constructors and just make all fields pub. Particularly as Rust doesn't support named parameters like C#.

The Open API generators having default parameters in constructors caused us lots of pain when models changed, and we were missing new fields, or providing values for the wrong fields.

Optional parameters and Defaults

The main issue with this approach may be frustration with elegantly constructing objects with optional parameters, when the object also has one or more required parameters... Although this is a general rust problem when at least one of the fields is not default-able.

You could consider something like default_with_v1, but it requires adding this extra model for the required fields. Another option would be default_with_v2 which sacrifices some type safety / visibility of the field names (by hiding them in the constructor) but gives better code ergonomics:

enum MyEnum {
    A,
    B,
}

struct MyExampleModel {
    optional_1: Option<i32>,
    required_1: i32,
    optional_2: Option<i32>,
    required_2: MyEnum,
    required_3: MyEnum,
}

struct MyExampleModelDefaultRequired {
    required_2: MyEnum,
    required_3: MyEnum,
}

impl MyExampleModel {
    fn default_with_v1(required: MyExampleModelDefaultRequired) -> Self {
        let MyExampleModelDefaultRequired { required_2, required_3, } = required;
        Self {
            optional_1: Default::default(),
            required_1: Default::default(),
            optional_2: Default::default(),
            required_2,
            required_3,
        }
    }

    fn default_with_v2(required_2: MyEnum, required_3: MyEnum) -> Self {
        Self {
            optional_1: Default::default(),
            required_1: Default::default(),
            optional_2: Default::default(),
            required_2,
            required_3,
        }
    }
}

fn my_function() -> MyExampleModel {
    MyExampleModel {
        optional_1: Some(1),
        ...MyExampleModel::default_with(MyExampleModelDefaultRequired {
            required_2: MyEnum::A,
            required_3: MyEnum::B,
        })
    }
}

Integer types

~~I think it makes sense to keep with the interpretation of format from the Open API specification~~

We should use the following:

type: integer, format: int32 => i32
type: integer, format: int64 => i64
type: integer, no format => ~~i64~~ EDIT: Kiota says this is i32
type: number, format: float => f32
type: number, format: double => f64
type: number, no format => ~~f64~~ EDIT: Kiota sets this to f32

There is a question about whether to use the minimum / maximum ranges to further restrict the type (to e.g. i8 / u8 / u32 / u64). For example, if we know that 0 <= x <= 255, we could fit it in a u8, or know it's >=0 and int32, arguably it's a little nicer to stick it into a u32 rather than an i32.

For me, if I were designing things from the ground up, my answer would be "yes, be intelligent here" - but I assume we should go with what kiota's policy is on this, if there is one.

Rust generator support? #4436

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions