Doc/example request: using nested messages

[davechallis]

Feature Request

Documentation or examples on how to use nested message types from Rust, e.g. for something like:

message SearchResponse {
  message Result {
    string url = 1;
    string title = 2;
    repeated string snippets = 3;
  }
  repeated Result results = 1;
}

Motivation

Just to make getting started with using Tonic a bit easier, since it's not as obvious how nested data structures might be handled in Rust.

[LucioFranco]

@davechallis Hi! I'm not exactly sure how this is actually handled, I would assume prost builds two structs. I'm not sure if the docs proprely belong in tonic or with prost. I think what might be good would to build out a set of guides around the full stack version of tonic.

[JohnDoneth]

For prost the nested types are put into their own module and the outermost items themselves are generated outside of that new module.

Example:

message MyOuterMessage {
  string message = 1;
  
  enum MyInnerEnum {
    FOO = 0;
    BAR = 1;
  }
}

Generated:

#[derive(Clone, PartialEq, ::prost::Message)]
pub struct MyOuterMessage {
    #[prost(string, tag = "1")]
    pub message: std::string::String,
}
pub mod my_outer_message {
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
    #[repr(i32)]
    pub enum MyInnerEnum {
        Foo = 0,
        Bar = 1,
    }
}

Nesting further puts the items deeper in the generated modules.

message Level1 {
  message Level2 {
    message Level3 {
      string foo = 1;
    }
  }
}

#[derive(Clone, PartialEq, ::prost::Message)]
pub struct Level1 {}
pub mod level1 {
    #[derive(Clone, PartialEq, ::prost::Message)]
    pub struct Level2 {}
    pub mod level2 {
        #[derive(Clone, PartialEq, ::prost::Message)]
        pub struct Level3 {
            #[prost(string, tag = "1")]
            pub foo: std::string::String,
        }
    }
}

[davechallis]

@JohnDoneth many thanks for posting those, that's very helpful.

[LucioFranco]

@davechallis hopefully this answered your question, I think we can close this issue now?

[davechallis]

@LucioFranco yes, please go ahead and close, I've made a note to try and work these into an example when I get the chance.

[LucioFranco]

@davechallis that would be great!