[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

[Nbd] [RFC PATCH] doc: In STRUCTURED_REPLY, make error types easy to recognize

We may add future structured error replies; making it easy
for older clients to properly treat such new reply types as
an error gives us a bit more flexibility on introducing new
errors to existing commands.  Of course, good design practice
says we should try hard to prevent the server from sending
something the client isn't expecting, but covering the
situation from both sides never hurts.  Also, marking error
types resembles how NBD_REP_ERR_* has a common layout.

Signed-off-by: Eric Blake <eblake@...696...>
---

Applies on top of the v6 SHOULD/MUST/MAY patch.

 doc/proto.md | 98 ++++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 59 insertions(+), 39 deletions(-)

diff --git a/doc/proto.md b/doc/proto.md
index 0c5bb5d..6c40ce7 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -935,8 +935,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
     These values are used in the "type" field of a structured reply.
     Some chunk types can additionally be categorized by role, such as
     *error chunks* or *content chunks*.  Each type determines how to
-    interpret the "length" bytes of payload.  If the client receives
-    an unknown or unexpected type, it MUST close the connection.
+    interpret the "length" bytes of payload.

     - `NBD_REPLY_TYPE_NONE` (0)

@@ -947,42 +946,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
       chunks were sent, then this type implies that the overall client
       request is successful.  Valid as a reply to any request.

-    - `NBD_REPLY_TYPE_ERROR` (1)
-
-      This chunk type is in the error chunk category.  *length* MUST
-      be at least 4.  This chunk represents that an error occurred,
-      and the client MAY NOT make any assumptions about partial
-      success. This type SHOULD NOT be used more than once in a
-      structured reply.  Valid as a reply to any request.
-
-      The payload is structured as:
-
-      32 bits: error (MUST be nonzero)  
-      *length - 4* bytes: optional string suitable for
-         direct display to a human being
-
-    - `NBD_REPLY_TYPE_ERROR_OFFSET` (2)
-
-      This chunk type is in the error chunk category.  *length* MUST
-      be at least 12.  This reply represents that an error occurred at
-      a given offset, which MUST lie within the original offset and
-      length of the request; the client can use this offset to
-      determine if request had any partial success.  This chunk type
-      MAY appear multiple times in a structured reply, although the
-      same offset SHOULD NOT be repeated.  Likewise, if content chunks
-      were sent earlier in the structured reply, the server SHOULD NOT
-      send multiple distinct offsets that lie within the bounds of a
-      single content chunk.  Valid as a reply to `NBD_CMD_READ`,
-      `NBD_CMD_WRITE`, `NBD_CMD_WRITE_ZEROES`, and `NBD_CMD_TRIM`.
-
-      The payload is structured as:
-
-      32 bits: error (MUST be non-zero)  
-      64 bits: offset (unsigned)  
-      *length - 12* bytes: optional string suitable for
-         direct display to a human being
-
-    - `NBD_REPLY_TYPE_OFFSET_DATA` (3)
+    - `NBD_REPLY_TYPE_OFFSET_DATA` (1)

       This chunk type is in the content chunk category.  *length* MUST
       be at least 9.  It represents the contents of *length - 8* bytes
@@ -998,7 +962,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
       64 bits: offset (unsigned)  
       *length - 8* bytes: data  

-    - `NBD_REPLY_TYPE_OFFSET_HOLE` (4)
+    - `NBD_REPLY_TYPE_OFFSET_HOLE` (2)

       This chunk type is in the content chunk category.  *length* MUST
       be exactly 12.  It represents that the contents of *hole size*
@@ -1015,6 +979,62 @@ error, and alters the reply to the `NBD_CMD_READ` request.
       64 bits: offset (unsigned)  
       32 bits: hole size (unsigned, MUST be nonzero)  

+    All error chunk types have bit 15 set, and begin with the same
+    *error* and *message length* fields as `NBD_REPLY_TYPE_ERROR`
+    (note that *message length* is optional only in
+    `NBD_REPLY_TYPE_ERROR`; it MUST be present in all other error
+    types).  If non-zero, *message length* indicates that an optional
+    error string message occupies the final bytes of the chunk,
+    suitable for display to a human user.
+
+    - `NBD_REPLY_TYPE_ERROR` (2^15 + 1)
+
+      This chunk type is in the error chunk category.  *length* MUST
+      be either exactly 4 or at least 8.  As a special case, the
+      server MAY omit the *message length* field if there is no
+      message string.  This chunk represents that an error occurred,
+      and the client MAY NOT make any assumptions about partial
+      success. This type SHOULD NOT be used more than once in a
+      structured reply.  Valid as a reply to any request.
+
+      The payload is structured as:
+
+      32 bits: error (MUST be nonzero)  
+      32 bits: message length, optional, but MUST be the header
+        *length* - 8 if present, and MUST be present if a message is
+	included  
+      *message length* bytes: optional string suitable for
+        direct display to a human being  
+
+    - `NBD_REPLY_TYPE_ERROR_OFFSET` (2^15 + 2)
+
+      This chunk type is in the error chunk category.  *length* MUST
+      be at least 16.  This reply represents that an error occurred at
+      a given offset, which MUST lie within the original offset and
+      length of the request; the client can use this offset to
+      determine if request had any partial success.  This chunk type
+      MAY appear multiple times in a structured reply, although the
+      same offset SHOULD NOT be repeated.  Likewise, if content chunks
+      were sent earlier in the structured reply, the server SHOULD NOT
+      send multiple distinct offsets that lie within the bounds of a
+      single content chunk.  Valid as a reply to `NBD_CMD_READ`,
+      `NBD_CMD_WRITE`, `NBD_CMD_WRITE_ZEROES`, and `NBD_CMD_TRIM`.
+
+      The payload is structured as:
+
+      32 bits: error (MUST be non-zero)  
+      32 bits: message length, MUST be *length* - 16  
+      64 bits: offset (unsigned)  
+      *message length* bytes: optional string suitable for
+         direct display to a human being  
+
+    If the client receives an unknown or unexpected type with bit 15
+    set, it MUST consider the current reply as errored, but MAY
+    continue transmission unless it detects that *length* is
+    inconsistent with *message length*.  For all other messages with
+    unknown or unexpected type or inconsistent contents, the client
+    MUST close the connection.
+
 * `NBD_OPT_STRUCTURED_REPLY`

     The client wishes to use structured replies during the
-- 
2.5.5
Reply to: