[Nbd] [PATCH v3 1/2] doc: Use dedicated reply types for NBD_OPT_INFO/GO

[Eric Blake <eblake@...696...>]

Since NBD_OPT_INFO and NBD_OPT_GO are experimental, we still have
a chance to fix them up before promoting them to stable.

Attempting to reuse NBD_OPT_SERVER as the reply to NBD_OPT_INFO and
NBD_OPT_GO has a few problems: clients must be prepared to parse
two different styles of the reply, based on which option request
the reply is answering.  Extending the information to provide even
more details, like block sizing, is awkward (the only way to do it
within a single reply is to have multiple length fields that must
all be consistent; and pre-computing the overall header length may
be difficult).  And requiring the server to parrot back the export
name is wasteful if the client's name is already in canonical
form.

Solve this by instead making the valid response be a series of reply
messages (similar to how NBD_OPT_LIST has a series).  The series
is always ended by the new NBD_REP_EXPORT, which is basically a
structured header pasted in front of the original response to
NBD_OPT_EXPORT_NAME.  But prior to that terminal message, the
server can now send as many additional optional items of
information as it wants (clients must ignore the ones they don't
recognize).  This patch starts with a single piece of information:
an alternate name for the export.  A future patch will then add
another piece of information, for advertising server block sizes.

Additionally:

- The wording was a bit repetitive; say the same thing in fewer
sentences.

- Swap paragraph ordering so that NBD_REP_INFO/EXPORT details aren't
split by a side-note about NBD_REP_ERR_UNSUP.

Signed-off-by: Eric Blake <eblake@...696...>
---
 doc/proto.md | 107 ++++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 69 insertions(+), 38 deletions(-)

diff --git a/doc/proto.md b/doc/proto.md
index fca85e2..8d1bd5e 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -753,11 +753,12 @@ during option haggling in the fixed newstyle negotiation.

 * `NBD_REP_SERVER` (2)

-    A description of an export. Data:
+    A description of an export name. Data:

     - 32 bits, length of name (unsigned); MUST be no larger than the
       reply packet header length - 4
     - String, name of the export, as expected by `NBD_OPT_EXPORT_NAME`
+      or `NBD_OPT_INFO`
     - If length of name < (reply packet header length - 4), then the
       rest of the data contains some implementation-specific details
       about the export. This is not currently implemented, but future
@@ -766,9 +767,13 @@ during option haggling in the fixed newstyle negotiation.
       particular client request, this field is defined to be a string
       suitable for direct display to a human being.

-    The experimental `INFO` extension (see below) adds two client
-    option requests where the extra data has a definition other than a
-    text string.
+* `NBD_REP_INFO` (3)
+
+    Defined by the experimental `INFO` extension; see below.
+
+* `NBD_REP_EXPORT` (4)
+
+    Defined by the experimental `INFO` extension; see below.

 There are a number of error reply types, all of which are denoted by
 having bit 31 set. All error replies MAY have some data set, in which
@@ -1000,13 +1005,13 @@ any structured message). This is a result of a (misguided) attempt to
 keep backwards compatibility with non-fixed newstyle negotiation.

 To remedy this, an `INFO` extension is envisioned. This extension adds
-two option requests and one error reply type, and extends one existing
-option reply type.
+two option requests, two option reply types, and one error reply type.

-Both options have identical formats for requests and replies. The
-only difference is that after a successful reply to `NBD_OPT_GO`
-(i.e. an `NBD_REP_SERVER`), transmission mode is entered immediately.
-Therefore these commands share common documentation.
+Both options have identical formats for requests and replies. The only
+difference is that after a successful reply to `NBD_OPT_GO` (i.e. zero
+or more `NBD_REP_INFO` then an `NBD_REP_EXPORT`), transmission mode is
+entered immediately.  Therefore these commands share common
+documentation.

 * `NBD_OPT_INFO` and `NBD_OPT_GO`

@@ -1038,52 +1043,78 @@ Therefore these commands share common documentation.
       server.
     - `NBD_REP_ERR_TLS_REQD`: The server does not wish to export this
       block device unless the client initiates TLS first.
-    - `NBD_REP_SERVER`: The server accepts the chosen export.
+    - A series of zero or more `NBD_REP_INFO`, followed by a terminating
+      `NBD_REP_EXPORT`: The server accepts the chosen export.

     Additionally, if TLS has not been initiated, the server MAY reply
     with `NBD_REP_ERR_TLS_REQD` (instead of `NBD_REP_ERR_UNKNOWN`)
     to requests for exports that are unknown. This is so that clients
     that have not initiated TLS cannot enumerate exports.

-    In the case of `NBD_REP_SERVER`, the message's data takes on a different
-    interpretation than the default (so as to provide additional
-    binary information normally sent in reply to `NBD_OPT_EXPORT_NAME`,
-    in place of the default free-form string). The option reply length
-    MUST be *length of name* + 14, and the option data has the following layout:
-
-    - 32 bits, length of name (unsigned)
-    - String: name of the export. This name MAY be different from the one
-      given in the `NBD_OPT_INFO` or `NBD_OPT_GO` option in case the
-      server has multiple alternate names for a single export, or a
-      default export was specified.
-    - 64 bits, size of the export in bytes (unsigned)
-    - 16 bits, transmission flags.
-
-    The server MUST NOT fail an `NBD_OPT_GO` sent with the same parameters
-    as a previous `NBD_OPT_INFO` which returned successfully (i.e. with
-    `NBD_REP_SERVER`), unless in the intervening time the client has
-    negotiated other options. The server MUST return the same transmission
-    flags with `NBD_OPT_GO` as a previous `NBD_OPT_INFO` with the same
-    parameters unless in the intervening time the client has negotiated other
-    options. The values of the transmission flags MAY differ from what was sent
-    earlier in response to an earlier `NBD_OPT_INFO` (if any), and/or
-    the server MAY fail the request, based on other options that were
-    negotiated in the meantime.
-
     For backwards compatibility, clients SHOULD be prepared to also
     handle `NBD_REP_ERR_UNSUP` by falling back to using `NBD_OPT_EXPORT_NAME`.

+    If there are no intervening option requests between a successful
+    `NBD_OPT_INFO` (that is, one where the reply included a final
+    `NBD_REP_EXPORT`) and an `NBD_OPT_GO` with the same parameters,
+    then the server MUST reply with the same set of information, such
+    as `NBD_REP_EXPORT` transmission flags, although the ordering of
+    intermediate `NBD_REP_INFO` messages MAY differ.  Otherwise, due
+    to the intervening option requests or the use of different
+    parameters, the server MAY send different data in the successful
+    response, and/or MAY fail the second request.
+
     The reply to an `NBD_OPT_GO` is identical to the reply to `NBD_OPT_INFO`
-    save that if the reply indicates success (i.e. is `NBD_REP_SERVER`),
+    save that if the reply indicates success (i.e. ends with `NBD_REP_EXPORT`),
     the client and the server both immediately enter the transmission
     phase. The server MUST NOT send any zero padding bytes after the
-    `NBD_REP_SERVER` data, whether or not the client negotiated the
+    `NBD_REP_EXPORT` data, whether or not the client negotiated the
     `NBD_FLAG_C_NO_ZEROES` flag. After sending this reply the server MUST
     immediately move to the transmission phase, and after receiving this
     reply, the client MUST immediately move to the transmission phase;
     therefore, the server MUST NOT send this particular reply until all
     other pending option replies have been sent by the server.

+* `NBD_REP_INFO`
+
+    A detailed description about an aspect of an export.  The response
+    to `NBD_OPT_INFO` and `NBD_OPT_GO` may include zero or more of
+    these messages prior to the final `NBD_REP_EXPORT`, although
+    within the sequence of replies for a single export, the server
+    MUST NOT send a given info type more than once.  Clients MUST
+    ignore info types that it does not recognize.  The acceptable
+    values for the header *length* field are determined by the info
+    type, and includes the 2 bytes for the type designator, in the
+    following general layout:
+
+    - 16 bits, info type  
+    - *length - 2* bytes, info payload  
+
+    The following information types are defined:
+
+    * `NBD_INFO_NAME` (1)
+
+      Represents the server's canonical name of the export. The name
+      MAY differ from the name presented in the client's option
+      request, and the info item SHOULD be omitted unless the server
+      has multiple alternate names for a single export or a default
+      export was specified.  The *length* MUST be at least 2, and the
+      *info payload* is interpreted as:
+
+      - String: name of the export, *length - 2* bytes  
+
+* `NBD_REP_EXPORT`
+
+    The final reply to a successful `NBD_OPT_INFO` or `NBD_OPT_GO`,
+    after zero or more `NBD_REP_INFO`.  Describes the same information
+    that is sent in response to the older `NBD_OPT_EXPORT_NAME`,
+    except that there are no trailing zeroes whether or not
+    `NBD_FLAG_C_NO_ZEROES` was negotiated.  *length* MUST be 10, and
+    the payload is interpreted as follows:
+
+    - 64 bits, size of the export in bytes (unsigned)  
+    - 16 bits, transmission flags  
+
 ### `WRITE_ZEROES` extension

 There exist some cases when a client knows that the data it is going to write
-- 
2.5.5