[Libguestfs] [libnbd PATCH v2 11/12] api: Add nbd_[aio_]opt_set_meta_context

[Eric Blake]

On Wed, Aug 31, 2022 at 09:39:27AM -0500, Eric Blake wrote:
> Make it possible for the client to choose when to manually request
> meta contexts when using nbd_set_opt_mode().  By itself, this patch
> allows us to test how a server reacts to NBD_OPT_SET_META_CONTEXT
> without a previous negotiation of structured headers; then an upcoming
> patch will also add APIs for choosing when to negotiate OPT_STARTTLS
> and OPT_STRUCTURED_REPLY for even more fine-grained testing control.
> Most users won't need this API (the automatic defaults are good
> enough), but when writing a server, this level of integration testing
> can be useful.
> 
> Overhaul the comment on OPT_META_CONTEXT.START to explain 5 different
> scenarios that this state group can be reached in, to better document
> which conditionals are in use later in the state machine:
>   - h->current_opt == opt is a witness of whether we are doing a
> mandatory manual LIST/SET request with an expected callback and
> transition to NEGOTIATIONG, or a conditional SET request dependent on
> nbd_set_request_meta_context() and prior negotiation and transition to
> OPT_GO
>  - h->current_opt == NBD_OPT_LIST_META_CONTEXT is a witness of whether
>  we are stateless or modifying h->meta_contexts
> 
> As this is a new API, the unit test in C is included in this patch;
> there is no point in splitting it as reordering the patches would not
> compile.  However, porting the tests to other languages will be done
> in the next commit.
> 
> ---

Also intended to be squashed into this patch:

diff --git a/generator/states-newstyle-opt-meta-context.c b/generator/states-newstyle-opt-meta-context.c
index 03b63c6..49e08bc 100644
--- a/generator/states-newstyle-opt-meta-context.c
+++ b/generator/states-newstyle-opt-meta-context.c
@@ -23,9 +23,24 @@ STATE_MACHINE {
   size_t i;
   uint32_t len, opt;

-  /* If the server doesn't support SRs then we must skip this group.
-   * Also we skip the group if the client didn't request any metadata
-   * contexts, when doing SET (but an empty LIST is okay).
+  /* This state group is reached from:
+   * h->opt_mode == false (h->current_opt == 0):
+   *   nbd_connect_*()
+   *     -> conditionally use SET, next state OPT_GO
+   * h->opt_mode == true (h->current_opt matches calling API):
+   *   nbd_opt_info(), nbd_opt_go()
+   *     -> conditionally use SET, next state OPT_GO
+   *   nbd_opt_list_meta_context()
+   *     -> unconditionally use LIST, next state NEGOTIATING
+   *   nbd_opt_set_meta_context()
+   *     -> unconditionally use SET, next state NEGOTIATING
+   *
+   * If the next state is OPT_GO, we want to clear h->exportsize and friends.
+   * If SET is conditional, we skip it if h->request_meta is false, if
+   * structured replies were not negotiated, or if no contexts to request.
+   * There is a callback if and only if the command is unconditional.
+   * If we use SET, we clear h->meta_contexts and rebuild it.
+   * If we use LIST, we are stateless.
    */
   assert (h->gflags & LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE);
   if (h->opt_current == NBD_OPT_LIST_META_CONTEXT) {


-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org