Re: [Nbd] [PATCHv3] Docs: improve description of disconnection methods

[Wouter Verhelst <w@...112...>]

On Thu, Apr 14, 2016 at 05:04:57PM -0600, Eric Blake wrote:
> On 04/14/2016 02:12 PM, Alex Bligh wrote:
> > Improve the documentation as per the mailing list discussion.
> > Here's what we decided (broadly).
> > 
> > * One side MAY drop the connection if the other end violates a
> >   MUST condition.
> > 
> > * The server MUST drop the connection in the 'no way out' situations
> >   during the negotiation phase (error on NBD_OPT_EXPORT_NAME, error
> >   in negotiating TLS).
> > 
> > * The server SHOULD NOT otherwise drop the connection. It can wait
> >   and error the next command. Clearly there are situations where
> >   dropping the connection is going to happen anyway (e.g. server
> >   shutdown).
> > 
> > * If the server does need to drop the connection, it SHOULD wait
> >   until there are no commands in-flight in transmission mode,
> >   it possible.
> > 
> > * If the client is going to drop the connection, then other
> >   than in the event of a protocol violation or a 'no way out'
> >   situation (e.g. TLS negotiation fails), it MUST use NBD_CMD_DISC
> >   or NBD_OPT_ABORT
> > 
> > * We should tidy up the semantics and descriptions of NBD_CMD_DISC
> >   and NBD_OPT_ABORT, viz replies or not to the latter, shutting
> >   down TLS properly etc.
> > 
> > Other changes:
> > 
> > * Added a reply to NBD_OPT_ABORT. No harm if the client closes
> >   the connection anyway.
> > 
> > * Said the offset and length fields in NBD_CMD_DISC MUST be zero.
> >   Not doing so is a protocol violation and would only lead to ...
> >   the connection being closed, so this is a useful tidy up.
> > 
> > * Introduced consistent terminology for disconnection throughout.
> > 
> > * Add errors and replies for server shutdown.
> > 
> > Signed-off-by: Alex Bligh <alex@...872...>
> > ---
> >  doc/proto.md | 184 +++++++++++++++++++++++++++++++++++++++++++++--------------
> >  1 file changed, 141 insertions(+), 43 deletions(-)
> 
> Looks okay to me, but I'd also wait for Wouter's review.
> 
> Reviewed-by: Eric Blake <eblake@...696...>

LGTM

-- 
< ron> I mean, the main *practical* problem with C++, is there's like a dozen
       people in the world who think they really understand all of its rules,
       and pretty much all of them are just lying to themselves too.
 -- #debian-devel, OFTC, 2016-02-12