Re: [Libguestfs] [libnbd PATCH v3 19/22] api: Add nbd_[aio_]opt_extended_headers()
On Thu, May 25, 2023 at 08:01:05AM -0500, Eric Blake wrote:
> Very similar to the recent addition of nbd_opt_structured_reply,
> giving us fine-grained control over an extended headers request.
>
> Because nbdkit does not yet support extended headers, testsuite
> coverage is limited to interop testing with qemu-nbd. It shows that
> extended headers imply structured replies, regardless of which order
> the two are manually negotiated in.
>
> Signed-off-by: Eric Blake
> ---
> generator/API.ml | 79 +++--
> .../states-newstyle-opt-extended-headers.c| 30 +++-
> generator/states-newstyle.c | 3 +
> lib/opt.c | 44 +
> interop/Makefile.am | 6 +
> interop/opt-extended-headers.c| 153 ++
> interop/opt-extended-headers.sh | 29
> .gitignore| 1 +
> 8 files changed, 329 insertions(+), 16 deletions(-)
> create mode 100644 interop/opt-extended-headers.c
> create mode 100755 interop/opt-extended-headers.sh
>
> diff --git a/generator/API.ml b/generator/API.ml
> index 078f140f..85625bbd 100644
> --- a/generator/API.ml
> +++ b/generator/API.ml
> @@ -825,6 +825,7 @@ "set_request_extended_headers", {
> if L is also set to false,
> since the use of extended headers implies structured replies.";
> see_also = [Link "get_request_extended_headers";
> +Link "opt_extended_headers";
> Link "set_handshake_flags"; Link "set_strict_mode";
> Link "get_extended_headers_negotiated";
> Link "zero"; Link "trim"; Link "cache";
> @@ -856,7 +857,9 @@ "get_extended_headers_negotiated", {
> shortdesc = "see if extended headers are in use";
> longdesc = "\
> After connecting you may call this to find out if the connection is
> -using extended headers.
> +using extended headers. Note that this setting is sticky; this
> +can return true even after a second L
> +returns false because the server detected a duplicate request.
>
> When extended headers are not in use, commands are limited to a
> 32-bit length, even when the libnbd API uses a 64-bit parameter
> @@ -938,7 +941,7 @@ "get_structured_replies_negotiated", {
> attempted.";
> see_also = [Link "set_request_structured_replies";
> Link "get_request_structured_replies";
> -Link "opt_structured_reply";
> +Link "opt_structured_reply"; Link "opt_extended_headers";
> Link "get_protocol";
> Link "get_extended_headers_negotiated"];
>};
> @@ -1211,12 +1214,13 @@ "set_opt_mode", {
> newstyle server. This setting has no effect when connecting to an
> oldstyle server.
>
> -Note that libnbd defaults to attempting C and
> -C before letting you control remaining
> -negotiation steps; if you need control over these steps as well,
> -first set L to C and
> -L to false before starting
> -the connection attempt.
> +Note that libnbd defaults to attempting C,
> +C, and C
> +before letting you control remaining negotiation steps; if you
> +need control over these steps as well, first set L
> +to C, and L
> +or L to false, before
> +starting the connection attempt.
>
> When option mode is enabled, you have fine-grained control over which
> options are negotiated, compared to the default of the server
> @@ -1324,6 +1328,35 @@ "opt_starttls", {
> Link "supports_tls"]
>};
>
> + "opt_extended_headers", {
> +default_call with
> +args = []; ret = RBool;
> +permitted_states = [ Negotiating ];
> +shortdesc = "request the server to enable extended headers";
> +longdesc = "\
> +Request that the server use extended headers, by sending
> +C. This can only be used if
> +L enabled option mode; furthermore, libnbd
> +defaults to automatically requesting this unless you use
> +L or
> +L prior to connecting.
> +This function is mainly useful for integration testing of corner
> +cases in server handling.
> +
> +This function returns true if the server replies with success,
> +false if the server replies with an error, and fails only if
> +the server does not reply (such as for a loss of connection).
> +Note that some servers fail a second request as redundant;
> +libnbd assumes that once one request has succeeded, then
> +extended headers are supported (as visible by
> +L) regardless if
> +later calls to this function return false. If this function
> +returns true, the use of structured replies is implied.";
> +see_also = [Link "set_opt_mode"; Link "aio_opt_extended_headers";
> +Link "opt_go"; Link "set_request_extended_headers";
> +Link "set_request_structured_replies"]
> + };
> +
>"opt_structured_reply", {
> default_call with
> args = []; ret = RBool;
> @@ -1345,7 +1378,9 @@ "opt_structured_reply", {
> libnbd
[Libguestfs] [libnbd PATCH v3 19/22] api: Add nbd_[aio_]opt_extended_headers()
Very similar to the recent addition of nbd_opt_structured_reply,
giving us fine-grained control over an extended headers request.
Because nbdkit does not yet support extended headers, testsuite
coverage is limited to interop testing with qemu-nbd. It shows that
extended headers imply structured replies, regardless of which order
the two are manually negotiated in.
Signed-off-by: Eric Blake
---
generator/API.ml | 79 +++--
.../states-newstyle-opt-extended-headers.c| 30 +++-
generator/states-newstyle.c | 3 +
lib/opt.c | 44 +
interop/Makefile.am | 6 +
interop/opt-extended-headers.c| 153 ++
interop/opt-extended-headers.sh | 29
.gitignore| 1 +
8 files changed, 329 insertions(+), 16 deletions(-)
create mode 100644 interop/opt-extended-headers.c
create mode 100755 interop/opt-extended-headers.sh
diff --git a/generator/API.ml b/generator/API.ml
index 078f140f..85625bbd 100644
--- a/generator/API.ml
+++ b/generator/API.ml
@@ -825,6 +825,7 @@ "set_request_extended_headers", {
if L is also set to false,
since the use of extended headers implies structured replies.";
see_also = [Link "get_request_extended_headers";
+Link "opt_extended_headers";
Link "set_handshake_flags"; Link "set_strict_mode";
Link "get_extended_headers_negotiated";
Link "zero"; Link "trim"; Link "cache";
@@ -856,7 +857,9 @@ "get_extended_headers_negotiated", {
shortdesc = "see if extended headers are in use";
longdesc = "\
After connecting you may call this to find out if the connection is
-using extended headers.
+using extended headers. Note that this setting is sticky; this
+can return true even after a second L
+returns false because the server detected a duplicate request.
When extended headers are not in use, commands are limited to a
32-bit length, even when the libnbd API uses a 64-bit parameter
@@ -938,7 +941,7 @@ "get_structured_replies_negotiated", {
attempted.";
see_also = [Link "set_request_structured_replies";
Link "get_request_structured_replies";
-Link "opt_structured_reply";
+Link "opt_structured_reply"; Link "opt_extended_headers";
Link "get_protocol";
Link "get_extended_headers_negotiated"];
};
@@ -1211,12 +1214,13 @@ "set_opt_mode", {
newstyle server. This setting has no effect when connecting to an
oldstyle server.
-Note that libnbd defaults to attempting C and
-C before letting you control remaining
-negotiation steps; if you need control over these steps as well,
-first set L to C and
-L to false before starting
-the connection attempt.
+Note that libnbd defaults to attempting C,
+C, and C
+before letting you control remaining negotiation steps; if you
+need control over these steps as well, first set L
+to C, and L
+or L to false, before
+starting the connection attempt.
When option mode is enabled, you have fine-grained control over which
options are negotiated, compared to the default of the server
@@ -1324,6 +1328,35 @@ "opt_starttls", {
Link "supports_tls"]
};
+ "opt_extended_headers", {
+default_call with
+args = []; ret = RBool;
+permitted_states = [ Negotiating ];
+shortdesc = "request the server to enable extended headers";
+longdesc = "\
+Request that the server use extended headers, by sending
+C. This can only be used if
+L enabled option mode; furthermore, libnbd
+defaults to automatically requesting this unless you use
+L or
+L prior to connecting.
+This function is mainly useful for integration testing of corner
+cases in server handling.
+
+This function returns true if the server replies with success,
+false if the server replies with an error, and fails only if
+the server does not reply (such as for a loss of connection).
+Note that some servers fail a second request as redundant;
+libnbd assumes that once one request has succeeded, then
+extended headers are supported (as visible by
+L) regardless if
+later calls to this function return false. If this function
+returns true, the use of structured replies is implied.";
+see_also = [Link "set_opt_mode"; Link "aio_opt_extended_headers";
+Link "opt_go"; Link "set_request_extended_headers";
+Link "set_request_structured_replies"]
+ };
+
"opt_structured_reply", {
default_call with
args = []; ret = RBool;
@@ -1345,7 +1378,9 @@ "opt_structured_reply", {
libnbd assumes that once one request has succeeded, then
structured replies are supported (as visible by
L) regardless if
-later calls to this function return false.";
+later calls to this function return false. Similarly, a
+server may fail this request if extended headers are already
