Re: [RFC PATCH v1 0/8] qapi: add generator for Golang interface

[Daniel P . Berrangé]

On Wed, May 11, 2022 at 04:17:43PM +0200, Markus Armbruster wrote:
> Daniel P. Berrangé <berrange@redhat.com> writes:
> 
> > On Tue, May 10, 2022 at 01:34:03PM +0100, Daniel P. Berrangé wrote:
> > Having said that, a different way to approach the problem is to expose
> > the versioning directly in the generated code.
> >
> > Consider a QAPI with versioning info about the fields
> >
> >   { 'command': 'block_resize',
> >     'since': '5.0.0',
> >     'data': { 'device': ['type': 'str', 'until': '5.2.0' ],
> >               '*device': ['type': 'str', 'since': '5.2.0', 'until': '7.0.0' 
> > ],
> >               '*node-name': ['type': 'str', 'since': '5.2.0', 'until: 
> > '7.0.0' ],
> >               'node-name': ['type': 'str', 'since': '7.0.0' ],
> >               'size': 'int' } }
> >
> > Meaning
> >
> >   * Introduced in 5.0.0, with 'device' mandatory
> >   * In 5.2.0, 'device' becomes optional, with optional 'node-name' as 
> > alternative
> >   * In 7.0.0, 'device' is deleted, and 'node-name' becomes mandatory
> >
> > Now consider the Go structs
> >
> > In 5.0.0 we can generate:
> >
> >    type BlockResizeArguments struct {
> >        V500 *BlockResizeArguments500
> >    }
> >
> >    type BlockResizeArgumentsV1 struct {
> >         Device string
> >         Size int
> >     }
> >
> > app can use
> >
> >     dev := "dev0"
> >     cmd := BlockResizeArguments{
> >        V500: &BlockResizeArguments500{
> >           Device: dev,
> >       Size: 1 * GiB
> >        }
> >     }
> >
> >
> > In 5.2.0 we can now generate
> >
> >    type BlockResizeArguments struct {
> >        V500 *BlockResizeArgumentsV500
> >        V520 *BlockResizeArgumentsV520
> >    }
> >
> >    type BlockResizeArgumentsV500 struct {
> >         Device string
> >         Size int
> >     }
> >
> >    type BlockResizeArgumentsV520 struct {
> >         Device *string
> >     NodeName *string
> >         Size int
> >     }
> >
> >
> > App can use the same as before, or switch to one of
> >
> >     dev := "dev0"
> >     cmd := BlockResizeArguments{
> >        V520: &BlockResizeArguments520{
> >           Device: &dev,
> >       Size: 1 * GiB
> >        }
> >     }
> >
> > or
> >
> >     node := "nodedev0"
> >     cmd := BlockResizeArguments{
> >        V520: &BlockResizeArguments520{
> >           NodeName: &node,
> >       Size: 1 * GiB
> >        }
> >     }
> >
> >
> >
> > In 7.0.0 we can now generate
> >
> >
> >    type BlockResizeArguments struct {
> >        V500 *BlockResizeArgumentsV500
> >        V520 *BlockResizeArgumentsV520
> >        V700 *BlockResizeArgumentsV700
> >    }
> >
> >    type BlockResizeArgumentsV500 struct {
> >         Device string
> >         Size int
> >    }
> >
> >    type BlockResizeArgumentsV520 struct {
> >         Device *string
> >     NodeName *string
> >         Size int
> >    }
> >
> >    type BlockResizeArgumentsV700 struct {
> >     NodeName string
> >         Size int
> >    }
> >
> >
> >
> > App can use the same as before, or switch to
> >
> >     node := "nodedev0"
> >     cmd := BlockResizeArguments{
> >        V700: &BlockResizeArguments700{
> >           NodeName: node,
> >       Size: 1 * GiB
> >        }
> >     }
> >
> >
> > This kind of per-command/type versioning is not uncommon when defining API
> > protocols/interfaces.
> 
> 1. At every release, put a copy of the QAPI schema in the freezer.
> 
> 2. For every copy, generate Go types with a suitable name suffix.
>    Collect all the name stems.
> 
> 3. For each name stem, define a Go struct that contains all the suffixed
>    Go types with that stem.
> 
> Look Ma, no cluttering the QAPI schema with a full history!  Also no
> complicating the schema language to provide the means for that.

That could indeed be a viable approach. Puts a little more work on the
code generator to match up the types, but probably isn't too hard.

Incidentally, we've intentionally not exposed type names in the QAPI
introspection in QMP.  With code generators, when the generated code
type names driven from QAPI schema, there's likely going to be an
expectation that type names in QAPI have some kind of stability rules.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|