On 11/12/2015 03:48 AM, Markus Armbruster wrote:
> Eric Blake <eblake@redhat.com> writes:
> 
>> I noticed that introspection was not documenting either
>> qmp_capabilities nor the ErrorClass enum.  I think this is worth
>> fixing for 2.5 when introspection is brand new, so that if we later
>> extend the ErrorClass enum or add future capability negotiation (and
>> in particular if such additions get backported in downstream builds),
>> a client will be able to use introspection to learn whether the new
>> features are supported, regardless of the qemu version.
>>
>> Note that this also adds qmp_capabilities to 'query-commands'.
>>
>> Yes, this is borderline, and you may decide that it doesn't deserve
>> to be called a bug and should wait for 2.6.
> 
> Before I discuss the error class proposal in more detail, a preliminary
> remark: error classes are a leftover from the days of "rich" error
> objects, and any new use of an error class other than
> ERROR_CLASS_GENERIC_ERROR is immediately suspect.  I'm not saying that
> we won't add such uses anymore, just that there's a significant bar to
> overcome, which we haven't for quite some time now.
> 
> I think I could be persuaded that a client might be able to use
> knowledge on what error classes a specific command can produce.  Of
> course, presence of an error class doesn't tell what actual error
> conditions map to it, i.e. the client still needs to make assumptions on
> the meaning of error classes.  Humans make those, too, but humans can
> read the contract in the comments.

Indeed - knowing the global set of possible errors is NOT the same as
knowing the set of command-specific errors; and the latter is more
likely to be useful.  But exposing the latter would require per-command
documentation in the .json files, and is certainly not doable in time
for 2.5.

> 
> The value of a global list of error classes seems even more dubious,
> though.  Existence of an error class by itself guarantees nothing.  How
> would a client use the information?  Assume that existence of a class
> implies a certain command uses it in a certain way?  That's an even
> bigger jump than above.
> 
> I guess using the presence or absence of an error class as a witness for
> a certain feature or behavior could work.  Seems practical when the
> written contract guarantees the connection between the two (de jure
> connection), or the commit that introduces the feature or behavior also
> adds or removes the error class (de facto connecton).  This applies both
> to a global list of error classes and to per-command lists.
> 

[snip good examples]

> 
> None of these examples is a particularly convincing use case.  Can you
> think of better ones?

No.

> 
> Finally, what happens if error class introspection misses 2.5 and makes
> a later version?
> 

It would not be the first time that libvirt has been coded along the
lines of "if the information is available, trust it; if not, go by a
hard-coded list that matched the upstream state prior to the information
being made available".  It's a bit more work on clients, but not
insurmountable.

> If we add a global error class list like this patch does, a client has
> to assume that anything that doesn't has one has the usual error
> classes: GenericError, CommandNotFound, DeviceEncrypted,
> DeviceNotActive, DeviceNotFound, KVMMissingCap[*].  Whether "doesn't has
> one" is "doesn't has one in query-qmp-schema" or "doesn't even have
> query-qmp-schema" doesn't matter.

Correct - a client can easily hard-code the correct information for all
older qemu (at worse, it will miss an error case that has been
backported - but in all likelihood, if backporting an error was that
important, downstream could also backport the way to introspect for it).

> 
> If we add per-command error class lists, it's the same, only the
> assumptions become a bit more involved.
> 
> Of course, the fewer discernible versions of introspection we have, the
> better.  If we can figure out what we need in time to get it into the
> very first version, great!  But it's awfully late for 2.5, and I'm not
> at all sure we know what we need.  Perhaps we can find out quickly, but
> let's not rush the job.
> 
> 
> [*] Ancient versions may also have MigrationExpected (see above), but
> backporting introspection that far, but not backporting the fix for the
> migration stop/cont race would be insane.

Therefore, I agree with you that there is no rush to get this into 2.5.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org