Esoteric QMP specification questions of dubious importance

Esoteric QMP specification questions of dubious importance

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 1793 bytes --]

I'm writing a "fake" QMP server for the purposes of creating unit tests for
the python QMP library. In doing so, I am left with some esoteric questions:


(1) qemu-spec.txt, section 2.4.2, "error":

The format of an "error response" is:

> { "error": { "class": json-string, "desc": json-string }, "id":
json-value }

For the purposes of naming internal types in the QMP library, does the
"error" object value have a canonical type name? It's not defined in QAPI
that I can see.


(2) qemu-spec.txt, section 2.2 "Server Greeting":

The greeting message format is:

> { "QMP": { "version": json-object, "capabilities": json-array } }
>
> Where,
>
> - The "version" member contains the Server's version information (the
format
>  is the same of the query-version command)

The layout of the "version" object is not specified in the spec itself,
though it does ask you to refer to the query-version command.
Hypothetically, is an alternate implementation of QMP in a binary that is
*not* QEMU allowed to change the layout of the "version" object (so long as
it matched whatever format it had for a "query-version" command, also not
mandated by the spec), or must it *always* conform to this precise layout?

(qapi/control.json):

> { 'struct': 'VersionInfo',
>    'data': {'qemu': 'VersionTriple', 'package': 'str'} }

If so, what should such a hypothetical client that is *not* QEMU do here?
What version does it report for the "qemu" VersionTriple member? Can I
report 0.0.0?


(3) Does the qmp-spec technically mandate any commands being available?

I believe that qmp_capabilities is definitively a requirement of the spec,
but what about query-commands, query-version, or quit? Are they technically
requirements of the QMP spec, or just requirements of QEMU?


Weird questions, I know.
--js

[-- Attachment #2: Type: text/html, Size: 2552 bytes --]

Re: Esoteric QMP specification questions of dubious importance

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> I'm writing a "fake" QMP server for the purposes of creating unit tests for
> the python QMP library. In doing so, I am left with some esoteric questions:
>
>
> (1) qemu-spec.txt, section 2.4.2, "error":
>
> The format of an "error response" is:
>
>> { "error": { "class": json-string, "desc": json-string }, "id": json-value }
>
> For the purposes of naming internal types in the QMP library, does the
> "error" object value have a canonical type name? It's not defined in QAPI
> that I can see.

No, it isn't.  It's built manually from an Error object in
qmp_error_response():

    rsp = qdict_from_jsonf_nofail("{ 'error': { 'class': %s, 'desc': %s } }",
                                  QapiErrorClass_str(error_get_class(err)),
                                  error_get_pretty(err));

> (2) qemu-spec.txt, section 2.2 "Server Greeting":
>
> The greeting message format is:
>
>> { "QMP": { "version": json-object, "capabilities": json-array } }
>>
>> Where,
>>
>> - The "version" member contains the Server's version information (the format
>>  is the same of the query-version command)
>
> The layout of the "version" object is not specified in the spec itself,
> though it does ask you to refer to the query-version command.
> Hypothetically, is an alternate implementation of QMP in a binary that is
> *not* QEMU allowed to change the layout of the "version" object (so long as
> it matched whatever format it had for a "query-version" command, also not
> mandated by the spec), or must it *always* conform to this precise layout?
>
> (qapi/control.json):
>
>> { 'struct': 'VersionInfo',
>>    'data': {'qemu': 'VersionTriple', 'package': 'str'} }
>
> If so, what should such a hypothetical client that is *not* QEMU do here?
> What version does it report for the "qemu" VersionTriple member? Can I
> report 0.0.0?

Referring to a QMP command is technically a layering violation.  Hasn't
bothered us so far.

qmp-spec.txt was obviously written with a single application in mind:
QEMU.  Evidence: the key for 'VersionTriple' is named 'qemu'.

A second application appeared a year and a half later: the guest agent.
It doesn't fully comply to qmp-spec.txt.  In particular, it doesn't send
a greeting.  Unfortunate, but doesn't seem worth fixing now.

If your application of QMP does send a greeting and has a query-version
command, then it should probably send the same JSON object for both.
Using something other than QEMU's VersionTriple is probably a bad idea.

Whether the actual contents of VersionTriple matters depends on the QMP
client.  In general, clients should use introspection, not version
information.  Whether reporting 0.0.0 is okay depends on what clients
you want to use.

If we want QMP to support applications other than QEMU (and impostors of
QEMU), we have some cleanup work to do on qmp-spec.txt.

> (3) Does the qmp-spec technically mandate any commands being available?
>
> I believe that qmp_capabilities is definitively a requirement of the spec,
> but what about query-commands, query-version, or quit? Are they technically
> requirements of the QMP spec, or just requirements of QEMU?

qmp_capabilities is part of the protocol.

Other commands aren't, although qmp-spec.txt refers to query-version,
query-qmp-schema, and guest-sync-delimited (QGA only).  Can't see any
others.

> Weird questions, I know.

There are no weird questions, only weird people ;-P

Re: Esoteric QMP specification questions of dubious importance

[Eric Blake]

On Thu, Jul 08, 2021 at 01:10:46PM +0200, Markus Armbruster wrote:
> John Snow <jsnow@redhat.com> writes:
> 
> > I'm writing a "fake" QMP server for the purposes of creating unit tests for
> > the python QMP library. In doing so, I am left with some esoteric questions:
> >
> >
> > (1) qemu-spec.txt, section 2.4.2, "error":
> >
> > The format of an "error response" is:
> >
> >> { "error": { "class": json-string, "desc": json-string }, "id": json-value }
> >
> > For the purposes of naming internal types in the QMP library, does the
> > "error" object value have a canonical type name? It's not defined in QAPI
> > that I can see.
> 
> No, it isn't.  It's built manually from an Error object in
> qmp_error_response():
> 
>     rsp = qdict_from_jsonf_nofail("{ 'error': { 'class': %s, 'desc': %s } }",
>                                   QapiErrorClass_str(error_get_class(err)),
>                                   error_get_pretty(err));

If we _need_ it to appear in the QAPI, it should certainly be
possible.  So far, no one has presented a need, but your unit tester
may be the reason to codify it.

> 
> > Weird questions, I know.
> 
> There are no weird questions, only weird people ;-P

Hey, I resemble that remark ;)

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org