| Message ID | 1261149905-7622-6-git-send-email-lcapitulino@redhat.com |
|---|---|
| State | New |
| Headers | show |
Luiz Capitulino <lcapitulino@redhat.com> writes: [...] > -4. Notes to Client implementors > -------------------------------- > +4. Compatibility Considerations > +-------------------------------- > > -4.1 It is recommended to always start the Server in pause mode, thus the > - Client is able to perform any setup procedure without the risk of > - race conditions and related problems > +In order to achieve maximum compatibility between versions, the following > +changes are forbidden in newer versions of the Server: > > -4.2 It is recommended to always check the capabilities json-array, issued > - with the greeting message, at connection time > +- Removal of commands > +- Removal of command arguments > +- Addition of extra mandatory arguments for commands > +- Modification of arguments types > +- Modification of arguments, commands, events or error names > +- Modification of arguments in replies, events or errors While I think these promises are appropriate for a mature version of the protocol, I do not think we should make them for 0.12. We've just dreamed up version 0.1 of the protocol. It hasn't been used in anger. Yes, we put some serious thought in it, and we even have prototype code using it in libvirt, but let's face it, we're not infallible: we *will* have to evolve stuff. Without a real user, there is no real need to constrict evolution of the protocol in such a harsh way. All it'll buy is is compatibility cruft. Passage of time will bring us plenty of cruft without us setting ourselves up for extras. Let's cut ourselves some slack here, please. [...]
Markus Armbruster wrote: > While I think these promises are appropriate for a mature version of the > protocol, I do not think we should make them for 0.12. > > We've just dreamed up version 0.1 of the protocol. It hasn't been used > in anger. Yes, we put some serious thought in it, and we even have > prototype code using it in libvirt, but let's face it, we're not > infallible: we *will* have to evolve stuff. > > Without a real user, there is no real need to constrict evolution of the > protocol in such a harsh way. All it'll buy is is compatibility cruft. > Passage of time will bring us plenty of cruft without us setting > ourselves up for extras. > > Let's cut ourselves some slack here, please. > I've been working on the release notes and I was intending on announcing the QMP support in 0.12 as a "preview" with full support in 0.13. The idea being that we would try to maintain compatibility but "preview" gives us enough slack that if we break it, we can at least claim that it was just a preview ;-) > [...] >
On Fri, 18 Dec 2009 11:44:27 -0600 Anthony Liguori <aliguori@linux.vnet.ibm.com> wrote: > Markus Armbruster wrote: > > While I think these promises are appropriate for a mature version of the > > protocol, I do not think we should make them for 0.12. > > > > We've just dreamed up version 0.1 of the protocol. It hasn't been used > > in anger. Yes, we put some serious thought in it, and we even have > > prototype code using it in libvirt, but let's face it, we're not > > infallible: we *will* have to evolve stuff. > > > > Without a real user, there is no real need to constrict evolution of the > > protocol in such a harsh way. All it'll buy is is compatibility cruft. > > Passage of time will bring us plenty of cruft without us setting > > ourselves up for extras. > > > > Let's cut ourselves some slack here, please. > > > > I've been working on the release notes and I was intending on announcing > the QMP support in 0.12 as a "preview" with full support in 0.13. > > The idea being that we would try to maintain compatibility but "preview" > gives us enough slack that if we break it, we can at least claim that it > was just a preview ;-) Should I update the spec then?
On Fri, 18 Dec 2009 18:20:52 +0100 Markus Armbruster <armbru@redhat.com> wrote: > Luiz Capitulino <lcapitulino@redhat.com> writes: > > [...] > > -4. Notes to Client implementors > > -------------------------------- > > +4. Compatibility Considerations > > +-------------------------------- > > > > -4.1 It is recommended to always start the Server in pause mode, thus the > > - Client is able to perform any setup procedure without the risk of > > - race conditions and related problems > > +In order to achieve maximum compatibility between versions, the following > > +changes are forbidden in newer versions of the Server: > > > > -4.2 It is recommended to always check the capabilities json-array, issued > > - with the greeting message, at connection time > > +- Removal of commands > > +- Removal of command arguments > > +- Addition of extra mandatory arguments for commands > > +- Modification of arguments types > > +- Modification of arguments, commands, events or error names > > +- Modification of arguments in replies, events or errors > > While I think these promises are appropriate for a mature version of the > protocol, I do not think we should make them for 0.12. > > We've just dreamed up version 0.1 of the protocol. It hasn't been used > in anger. Yes, we put some serious thought in it, and we even have > prototype code using it in libvirt, but let's face it, we're not > infallible: we *will* have to evolve stuff. While I agree with your arguments, I think this will happen to any QMP version or any stable protocol/API. You have the point that QMP is immature at this point, but: 1. Given the current Monitor design, if you want QMP to be perfect to be useful then we're going to have it around QEMU version 10.0 2. I don't think we're going to get any serious user until we declare it stable
Anthony Liguori <aliguori@linux.vnet.ibm.com> writes: > Markus Armbruster wrote: >> While I think these promises are appropriate for a mature version of the >> protocol, I do not think we should make them for 0.12. >> >> We've just dreamed up version 0.1 of the protocol. It hasn't been used >> in anger. Yes, we put some serious thought in it, and we even have >> prototype code using it in libvirt, but let's face it, we're not >> infallible: we *will* have to evolve stuff. >> >> Without a real user, there is no real need to constrict evolution of the >> protocol in such a harsh way. All it'll buy is is compatibility cruft. >> Passage of time will bring us plenty of cruft without us setting >> ourselves up for extras. >> >> Let's cut ourselves some slack here, please. >> > > I've been working on the release notes and I was intending on > announcing the QMP support in 0.12 as a "preview" with full support in > 0.13. > > The idea being that we would try to maintain compatibility but > "preview" gives us enough slack that if we break it, we can at least > claim that it was just a preview ;-) Works for me. But then the unconditional promise in this patch is misleading. If we care, we should amend it to spell out "this is preview, all promises are null and void".
On Fri, 18 Dec 2009 19:06:18 +0100 Markus Armbruster <armbru@redhat.com> wrote: > Anthony Liguori <aliguori@linux.vnet.ibm.com> writes: > > > Markus Armbruster wrote: > >> While I think these promises are appropriate for a mature version of the > >> protocol, I do not think we should make them for 0.12. > >> > >> We've just dreamed up version 0.1 of the protocol. It hasn't been used > >> in anger. Yes, we put some serious thought in it, and we even have > >> prototype code using it in libvirt, but let's face it, we're not > >> infallible: we *will* have to evolve stuff. > >> > >> Without a real user, there is no real need to constrict evolution of the > >> protocol in such a harsh way. All it'll buy is is compatibility cruft. > >> Passage of time will bring us plenty of cruft without us setting > >> ourselves up for extras. > >> > >> Let's cut ourselves some slack here, please. > >> > > > > I've been working on the release notes and I was intending on > > announcing the QMP support in 0.12 as a "preview" with full support in > > 0.13. > > > > The idea being that we would try to maintain compatibility but > > "preview" gives us enough slack that if we break it, we can at least > > claim that it was just a preview ;-) > > Works for me. But then the unconditional promise in this patch is > misleading. If we care, we should amend it to spell out "this is > preview, all promises are null and void". I'd prefer to just drop this part.
Luiz Capitulino <lcapitulino@redhat.com> writes: > On Fri, 18 Dec 2009 18:20:52 +0100 > Markus Armbruster <armbru@redhat.com> wrote: > >> Luiz Capitulino <lcapitulino@redhat.com> writes: >> >> [...] >> > -4. Notes to Client implementors >> > -------------------------------- >> > +4. Compatibility Considerations >> > +-------------------------------- >> > >> > -4.1 It is recommended to always start the Server in pause mode, thus the >> > - Client is able to perform any setup procedure without the risk of >> > - race conditions and related problems >> > +In order to achieve maximum compatibility between versions, the following >> > +changes are forbidden in newer versions of the Server: >> > >> > -4.2 It is recommended to always check the capabilities json-array, issued >> > - with the greeting message, at connection time >> > +- Removal of commands >> > +- Removal of command arguments >> > +- Addition of extra mandatory arguments for commands >> > +- Modification of arguments types >> > +- Modification of arguments, commands, events or error names >> > +- Modification of arguments in replies, events or errors >> >> While I think these promises are appropriate for a mature version of the >> protocol, I do not think we should make them for 0.12. >> >> We've just dreamed up version 0.1 of the protocol. It hasn't been used >> in anger. Yes, we put some serious thought in it, and we even have >> prototype code using it in libvirt, but let's face it, we're not >> infallible: we *will* have to evolve stuff. > > While I agree with your arguments, I think this will happen to any > QMP version or any stable protocol/API. > > You have the point that QMP is immature at this point, but: > > 1. Given the current Monitor design, if you want QMP to be perfect to be > useful then we're going to have it around QEMU version 10.0 No human creation will ever be perfect. > 2. I don't think we're going to get any serious user until we > declare it stable You're quite right about that. But right now QMP doesn't cover enough ground for serious use anyway. Once it does, we'll soon be compelled to declare it stable, and live with the consequences.
diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt index 1cbd21c..3d25156 100644 --- a/QMP/qmp-spec.txt +++ b/QMP/qmp-spec.txt @@ -1,4 +1,4 @@ - QEMU Monitor Protocol Draft Specification - Version 0.1 + QEMU Monitor Protocol Specification - Version 0.1 1. Introduction =============== @@ -27,9 +27,9 @@ the JSON standard: http://www.ietf.org/rfc/rfc4627.txt -For convenience, json-objects mentioned in this document will have its members -in a certain order. However, in real protocol usage json-objects members can -be in ANY order, thus no particular order should be assumed. +For convenience, json-object members and json-array elements mentioned in +this document will be in a certain order. However, in real protocol usage +they can be in ANY order, thus no particular order should be assumed. 2.1 General Definitions ----------------------- @@ -85,12 +85,13 @@ without errors. The format is: -{ "return": json-value, "id": json-value } +{ "return": json-object, "id": json-value } Where, - The "return" member contains the command returned data, which is defined - in a per-command basis or "OK" if the command does not return data + in a per-command basis or an empty json-object if the command does not + return data - The "id" member contains the transaction identification associated with the command execution (if issued by the Client) @@ -102,7 +103,7 @@ completed because of an error condition. The format is: -{ "error": { "class": json-string, "data": json-value, "desc": json-string }, +{ "error": { "class": json-string, "data": json-object, "desc": json-string }, "id": json-value } Where, @@ -110,7 +111,7 @@ The format is: - The "class" member contains the error class name (eg. "ServiceUnavailable") - The "data" member contains specific error data and is defined in a per-command basis, it will be an empty json-object if the error has no data -- The "desc" member is a human-readable error message. Clients should +- The "desc" member is a human-readable error message. Clients should not attempt to parse this message. - The "id" member contains the transaction identification associated with the command execution (if issued by the Client) @@ -127,7 +128,7 @@ to the Client at any time. They are called 'asynchronous events'. The format is: -{ "event": json-string, "data": json-value, +{ "event": json-string, "data": json-object, "timestamp": { "seconds": json-number, "microseconds": json-number } } Where, @@ -135,7 +136,7 @@ The format is: - The "event" member contains the event's name - The "data" member contains event specific data, which is defined in a per-event basis, it is optional -- The "timestamp" member contains the exact time of when the event ocurred +- The "timestamp" member contains the exact time of when the event occurred in the Server. It is a fixed json-object with time in seconds and microseconds @@ -157,19 +158,20 @@ S: {"QMP": {"capabilities": []}} --------------------------- C: { "execute": "stop" } -S: {"return": "OK"} +S: {"return": {}} 3.3 KVM information ------------------- -C: {"execute": "query-kvm", "id": "example"} -S: {"return": "enabled", "id": "example"} +C: { "execute": "query-kvm", "id": "example" } +S: {"return": {"enabled": true, "present": true}, "id": "example"} 3.4 Parsing error ------------------ C: { "execute": } -S: {"error": {"class": "JSONParsing", "data": {}}} +S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": +{}}} 3.5 Powerdown event ------------------- @@ -177,19 +179,34 @@ S: {"error": {"class": "JSONParsing", "data": {}}} S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": "POWERDOWN"} -4. Notes to Client implementors -------------------------------- +4. Compatibility Considerations +-------------------------------- -4.1 It is recommended to always start the Server in pause mode, thus the - Client is able to perform any setup procedure without the risk of - race conditions and related problems +In order to achieve maximum compatibility between versions, the following +changes are forbidden in newer versions of the Server: -4.2 It is recommended to always check the capabilities json-array, issued - with the greeting message, at connection time +- Removal of commands +- Removal of command arguments +- Addition of extra mandatory arguments for commands +- Modification of arguments types +- Modification of arguments, commands, events or error names +- Modification of arguments in replies, events or errors -4.3 Json-objects or json-arrays mentioned in this document are not fixed - and no particular size or number of members/elements should be assumed. - New members/elements can be added at any time. +Likewise, Clients must not assume any particular: -4.4 No particular order of json-objects members should be assumed, they - can change at any time +- Size of json-objects or length of json-arrays +- Order of json-object members or json-array elements +- Amount of errors generated by a command, that is, new errors can be added + to any existing command in newer versions of the Server + +Additionally, Clients should always: + +- Check the capabilities json-array at connection time +- Check the availability of commands with 'query-commands' before issuing them + +5. Recommendations to Client implementors +----------------------------------------- + +5.1 The Server should be always started in pause mode, thus the Client is + able to perform any setup procedure without the risk of race conditions + and related problems
- Remove "draft" status - Change default success response to be json-object - Change error and event data member to be a json-object - Update examples - Add new section "Compatibility Considerations" - Other fixes and clarifications Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> --- QMP/qmp-spec.txt | 69 +++++++++++++++++++++++++++++++++-------------------- 1 files changed, 43 insertions(+), 26 deletions(-)