This is offered as a straw-man for comment. The rationale for it has been discussed on-list and is in the documentation.
This applies on top of: [PATCHv5] docs/proto.md: Clarify SHOULD / MUST / MAY etc so it can take advantage of the 'exposes' language. Signed-off-by: Alex Bligh <[email protected]> --- doc/proto.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/doc/proto.md b/doc/proto.md index e5042aa..88d74ca 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -342,6 +342,7 @@ The field has the following format: experimental `WRITE_ZEROES` extension; see below. - bit 7, `NBD_FLAG_SEND_DF`: defined by the experimental `STRUCTURED_REPLY` extension; see below. +- bit 8, `NBD_FLAG_SEND_CLOSE`: exposes support for `NBD_CMD_CLOSE`. Clients SHOULD ignore unknown flags. @@ -608,6 +609,11 @@ The following request types exist: The values of the length and offset fields in a disconnect request are not defined. + A client SHOULD NOT send `NBD_CMD_DISC` if `NBD_FLAG_SEND_CLOSE` + is set in the transmission flags field, but SHOULD use + `NBD_CMD_CLOSE` instead; in such circumstances if it cannot wait + for inflight requests to complete it SHOULD simply disconnect. + * `NBD_CMD_FLUSH` (3) A flush request; a write barrier. The server MUST NOT send a @@ -638,6 +644,59 @@ The following request types exist: Defined by the experimental `WRITE_ZEROES` extension; see below. +* `NBD_CMD_CLOSE` (7) + + A close request. The server MUST handle all outstanding + requests (there should be none by the spec), and then MUST send an + `NBD_REP_ACK`. The server MUST NOT send an error reply. + The server MUST NOT send anything after sending an `NBD_REP_ACK` + in response to an `NBD_CMD_DISC`. + + If the server receives `NBD_CMD_CLOSE` it MUST treat + the close as a safe close (i.e. one where all operations have + been peformed) at the point where the request is received + (this relies on the client complying to the requirement of + no outstanding requests). + + A client MUST wait until there are no outstanding requests + before sending an `NBD_CMD_CLOSE`, and following this + point it MUST treat either the receipt of an `NBD_REP_ACK` + or a TCP level disconnect as a safe close. + + A disconnect in any other circumstances MUST be considered an + unsafe close, except for NBD_CMD_DISC sent or received without + outstanding requests, which the server or client MAY treat + as it wishes. + + A client MUST NOT send anything to the server after sending an + `NBD_CMD_CLOSE` command. On receipt of an `NBD_REP_ACK` in + response to a `NBD_CMD_CLOSE`, the client MUST close the + connection. + + The server MAY close the connection after sending `NBD_REP_ACK` + provided it has first ensured all network traffic has been + flushed to the socket (especially important if using TLS). + + The length and offset fields in an `NBD_CMD_CLOSE` request + MUST both be zero. + + A client MUST NOT send a `NBD_CMD_CLOSE` unless + `NBD_FLAG_SEND_CLOSE` was set in the transmission flags + field. + + The rationale for `NBD_CMD_CLOSE` is as follows. When a + client sends an `NBD_CMD_DISC`, it does not know whether it + has been processed or not, hence if it sees a disconnection it + cannot easily distinguish this from an error. When a client + sends an `NBD_CMD_DISC`, it (logically) also wishes to close + the connection; clients often do so to avoid the situation + where a server never closes the connection. This close often + happens before the server has received or processed the + `NBD_CMD_DISC`, particularly when TLS is enabled. This + extension allows both client and server to be sure a connection + has been closed safely and to differentiate TCP level disconnects + from closes of other sorts. + * Other requests Some third-party implementations may require additional protocol -- 1.9.1 ------------------------------------------------------------------------------ _______________________________________________ Nbd-general mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/nbd-general
