Patchwork QMP: Add "Downstream extension of QMP" to spec

login
register
mail settings
Submitter Markus Armbruster
Date May 7, 2010, 9:49 a.m.
Message ID <m3zl0cm47d.fsf_-_@blackfin.pond.sub.org>
Download mbox | patch
Permalink /patch/51919/
State New
Headers show

Comments

Markus Armbruster - May 7, 2010, 9:49 a.m.
Rules for how to extend QMP downstream (if you really have to) without
creating interoparability hassles.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
Aside:

* Advice on downstream modifications, items 1. and 2. could use a
  rationale.

* Section '5 Compatibility Considerations' could use some love.

 QMP/qmp-spec.txt |   55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 55 insertions(+), 0 deletions(-)
Luiz Capitulino - May 7, 2010, 7:54 p.m.
On Fri, 07 May 2010 11:49:42 +0200
Markus Armbruster <armbru@redhat.com> wrote:

> +Any new names downstream wishes to add must begin with '__'.  To ensure
> +compatibility with other downstreams, it is strongly recommended that
> +you prefix the commands with '__RFQDN_' where RFQDN is a valid, reverse
> +fully qualified domain name which you control.  For example, a qemu-kvm
> +specific monitor command would be:
> +
> +    (qemu) __org.linux-kvm_enable_irqchip

 It's not only for commands, but for async messages and errors as well,
otherwise looks good to me.

Patch

diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index f3c0327..dc2eb4b 100644
--- a/QMP/qmp-spec.txt
+++ b/QMP/qmp-spec.txt
@@ -215,3 +215,58 @@  Additionally, Clients must not assume any particular:
 - 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
+
+6. Downstream extension of QMP
+------------------------------
+
+We recommend that downstream consumers of QEMU do *not* modify QMP.
+Management tools should be able to support both upstream and downstream
+versions of QMP without special logic, and downstream extensions are
+inherently at odds with that.
+
+However, we recognize that it is sometimes impossible for downstreams to
+avoid modifying QMP.  Both upstream and downstream need to take care to
+preserve long-term compatibility and interoperability.
+
+To help with that, QMP reserves JSON object member names beginning with
+'__' (double underscore) for downstream use ("downstream names").  This
+means upstream will never use any downstream names for its commands,
+arguments, errors, asynchronous events, and so forth.
+
+Any new names downstream wishes to add must begin with '__'.  To ensure
+compatibility with other downstreams, it is strongly recommended that
+you prefix the commands with '__RFQDN_' where RFQDN is a valid, reverse
+fully qualified domain name which you control.  For example, a qemu-kvm
+specific monitor command would be:
+
+    (qemu) __org.linux-kvm_enable_irqchip
+
+Downstream must not change the server greeting (section 2.2) other than
+to offer additional capabilities.  But see below for why even that is
+discouraged.
+
+Section '5 Compatibility Considerations' applies to downstream as well
+as to upstream, obviously.  It follows that downstream must behave
+exactly like upstream for any input not containing members with
+downstream names ("downstream members"), except it may add members
+with downstream names to its output.
+
+Thus, a client should not be able to distinguish downstream from
+upstream as long as it doesn't send input with downstream members, and
+properly ignores any downstream members in the output it receives.
+
+Advice on downstream modifications:
+
+1. Introducing new commands is okay.  If you want to extend an existing
+   command, consider introducing a new one with the new behaviour
+   instead.
+
+2. Introducing new asynchronous messages is okay.  If you want to extend
+   an existing message, consider adding a new one instead.
+
+3. Introducing new errors for use in new commands is okay.  Adding new
+   errors to existing commands counts as extension, so 1. applies.
+
+4. New capabilities are strongly discouraged.  Capabilities are for
+   evolving the basic protocol, and multiple diverging basic protocol
+   dialects are most undesirable.