Re: [PATCH] PoC: Rust binding for QAPI (qemu-ga only, for now)

[Daniel P . Berrangé]

On Tue, Sep 22, 2020 at 05:09:56PM +0200, Markus Armbruster wrote:
> Marc-André Lureau <marcandre.lureau@redhat.com> writes:
> 
> > Hi
> >
> > On Mon, Sep 21, 2020 at 1:16 PM Markus Armbruster <armbru@redhat.com> wrote:
> >>
> >> We've made use of this extensively.  See also
> >> docs/devel/qapi-code-gen.txt section "Compatibility considerations."
> >>
> >> How do such changes affect clients of the proposed D-Bus interface?
> >
> > The introspection XML will always reflect the expected signature. You
> > should bump your interface version whenever you make incompatible
> > changes.
> 
> How do "interface versions" work?  Client's and server's version need to
> match, or else no go?

Yes, both client and server need to support the same "interface" in order
to talk to each other. If a service makes an incompatible API change, then
then change the interface name. It is common to include a number in the
interface name.

Of course some changes can be made in a backwards compatible manner so
don't require changing the interface. eg adding new methods, adding
new signals (aka async events), adding new properties.

Adding/changing/removing parameters  in an existing method is what
causes an interface incompatability.

You can potentially mitigate the inability to change parameters by
modelling parameters in a variety of ways.

Many of the tricks common in traditional C libraries for future
proofing API designs will apply equally well to DBus APIs.

For example, instead of modelling everything as a distinct positional
parameter, you can model them as optional named parameters. These would
be exposed as an array(map(string-variant)) - basically think of it as a
hash table. This is a half-way house between very strongly typed and very
weakly typed worlds.  Libvirt takes this approach with some of our C APIs
that we expect to grow parameters over time.

A variant on this is to expose some data in a custom document format
as a single parameter. For example if there was an API requesting a
description of a block backend properties, instead of having a DBus
API where all the block backend props were explicitly modelled, just
have a single string parameter that returns a JSON/XML doc. You can
extend that doc at will without impacting the DBus API. Again libvirt
takes this approach with our XML doc schema.

A final useful technique is to have a generic "int flags" parameter as
a way to express new functional behaviour by defining extra flags.


The challenge with all these ideas is figuring out whether there's
a viable way to map them into how we describe the current QMP protocol.
I don't think there's a especially good answer to do a 100% automated
mapping from QMP to DBus, while keeping extensibility and also maximising
strong type checking benefits. There's a tradeoff between extensibility
and strong typing that needs some intelligent thought on a case by case
basis IMHO.

For an automated mapping, either we go fully strong typed and accept
that we'll be breaking DBus interface compatibility continually, or
we go full weakly typed and accept that clients won't get much type
validation benefits at build time.

It is the inherant problem with using something weakly typed as the
master specification and trying to translate it to something strongly
typed.

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 :|