[Nbd] [PATCH] doc: Specific error if NBD_OPT_GO refused without NBD_OPT_BLOCK_SIZE

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

While we documented that a server could refuse a client that
did not mention that it would handle non-default block sizes,
we didn't mention what error to use.  For NBD_OPT_EXPORT_NAME,
we have no choice (a hard disconnect is the only way possible).
But for NBD_OPT_GO (and similarly for NBD_OPT_INFO), the
existing NBD_REP_ERR_POLICY and NBD_REP_ERR_INVALID feel rather
weak, so it's better to invent a specific
NBD_REP_ERR_BLOCK_SIZE_REQD.

Suggested-by: Alex Bligh <alex@...872...>
Signed-off-by: Eric Blake <eblake@...696...>
---

Applies to the extension-info branch; although if we split
block-size into its own branch, this would move there.

Also requires a patch to the master branch to reserve the
new error code.  Do you want me to submit that patch, too?

Question: Should we rearrange the various errors, so that
NBD_REP_ERR_UNKNOWN and NBD_REP_ERR_BLOCK_SIZE_REQD are
adjacent (since they are, for now, in the same extension
branch), by hoising NBD_REP_ERR_SHUTDOWN to 2^32 + 6?  We
don't yet have any released versions that use
NBD_REP_ERR_SHUTDOWN, although it was added as normative text
without going through the usual extension work.

 doc/proto.md | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/doc/proto.md b/doc/proto.md
index 5e646cf..8ef339c 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -657,12 +657,14 @@ a client SHOULD assume a default minimum block size of 1, a preferred
 block size of 2^12 (4,096), and a maximum block size of the smaller of
 the export size or 0xffffffff (effectively unlimited).  A server that
 wants to enforce block sizes other than the defaults specified here
-MAY refuse to go into transmission phase with a client that uses `NBD_OPT_EXPORT_NAME`
-or failed to use `NBD_OPT_BLOCK_SIZE`, although a server SHOULD permit
-such clients if block sizes can be agreed on externally.  When
-allowing such clients, the server MUST cleanly error commands that
-fall outside block size parameters without corrupting data; even so,
-this may limit interoperability.
+MAY refuse to go into transmission phase with a client that uses
+`NBD_OPT_EXPORT_NAME` (via a hard disconnect) or which fails to use
+`NBD_OPT_BLOCK_SIZE` (where the server uses
+`NBD_REP_ERR_BLOCK_SIZE_REQD` in response to `NBD_OPT_GO`), although a
+server SHOULD permit such clients if block sizes can be agreed on
+externally.  When allowing such clients, the server MUST cleanly error
+commands that fall outside block size parameters without corrupting
+data; even so, this may limit interoperability.

 A client MAY choose to operate as if tighter block sizes had been
 specified (for example, even when the server advertises the default
@@ -909,6 +911,13 @@ of the newstyle negotiation.
       export.  In this case, a FORCEDTLS server MUST NOT send
       `NBD_REP_INFO` replies, but a SELECTIVETLS server MAY do so if
       this is a TLS-only export.
+    - `NBD_REP_ERR_BLOCK_SIZE_REQD`: The server requires the client to
+      negotiate `NBD_OPT_BLOCK_SIZE` prior to entering transmission
+      phase, because the server will be using non-default block sizes.
+      In this case, the server SHOULD first send at least an
+      `NBD_REP_INFO` reply with `NBD_INFO_BLOCK_SIZE` data.  This
+      error MUST NOT be used if the client has already negotiated
+      `NBD_OPT_BLOCK_SIZE`.

     Additionally, if TLS has not been initiated, the server MAY reply
     with `NBD_REP_ERR_TLS_REQD` (instead of `NBD_REP_ERR_UNKNOWN`) to
@@ -1133,6 +1142,13 @@ case that data is an error message string suitable for display to the user.
     The server is unwilling to continue negotiation as it is in the
     process of being shut down.

+* `NBD_REP_ERR_BLOCK_SIZE_REQD` (2^32 + 8)
+
+    The server is unwilling to enter transmission phase for a given
+    export unless the client first acknowledges (via
+    `NBD_OPT_BLOCK_SIZE`) that it will obey non-default block sizing
+    requirements.
+
 ### Transmission phase

 #### Command flags
-- 
2.5.5