GUACAMOLE-2281: Add generic req/done/cancel instructions to libguac.

Adds a generic request/response RPC primitive to the Guacamole protocol
in the form of three instructions: "req", "done", and "cancel".

A "req" instruction initiates a typed request with three arguments: a
correlation id, a method name (by convention namespaced like
"<feature>.<verb>"), and an opaque payload. The receiving side is
expected to settle the request with a "done" instruction carrying the
same id, a status (typically "ok", "error", or "canceled"), and a
response payload. Either side may issue a "cancel" with the matching id
to abort an in-flight request before its "done" arrives.

The instructions themselves carry no feature-specific semantics; the
method name argument identifies what kind of request is being made, and
the payload is opaque to libguac. This leaves room for any RPC-style
feature to share the same plumbing without needing its own dedicated
opcodes.

Adds the libguac surface for the new primitive:

* guac_protocol_send_req, guac_protocol_send_done, and
  guac_protocol_send_cancel in protocol.h / protocol.c.
* guac_user_req_handler, guac_user_done_handler, and
  guac_user_cancel_handler typedefs in user-fntypes.h.
* req_handler, done_handler, and cancel_handler callback fields on
  guac_user in user.h.
* __guac_handle_req, __guac_handle_done, and __guac_handle_cancel
  dispatchers in user-handlers.c, registered in the instruction handler
  map.

The first intended consumer is WebAuthn passthrough, which will use
this primitive to relay ceremonies between protocol plugins and the
user's local authenticator with method names "webauthn.create" and
"webauthn.get". The primitive is deliberately generic so other
RPC-style features can adopt it without adding more opcodes to the
protocol vocabulary.

Author: aleitner

src/libguac/guacamole/protocol.h

@@ -28,6 +28,7 @@
  * @file protocol.h
  */
 
+#include "client-types.h"
 #include "layer-types.h"
 #include "object-types.h"
 #include "protocol-constants.h"
@@ -1119,6 +1120,91 @@ int guac_protocol_send_clipboard(guac_socket* socket, const guac_stream* stream,
  */
 int guac_protocol_send_name(guac_socket* socket, const char* name);
 
+/**
+ * Sends a "req" instruction along the given client's broadcast socket,
+ * initiating a typed request/response exchange with the peer. The body
+ * (if any) is shipped first over a reserved-mimetype pipe stream whose
+ * name is the correlation id; the trailing "req" carries only the id
+ * and method name. The peer is expected to settle the request with a
+ * "done" instruction carrying the same id, or either side may issue a
+ * "cancel" with the same id to abort.
+ *
+ * @param client
+ *     The guac_client whose broadcast socket should be used. A stream is
+ *     allocated against this client for the duration of the body
+ *     transfer and freed before this function returns.
+ *
+ * @param id
+ *     A correlation identifier (typically a UUID string) that uniquely
+ *     identifies this request/response exchange.
+ *
+ * @param name
+ *     The method name identifying what kind of request this is.
+ *
+ * @param body
+ *     The request body, opaque to libguac. May be NULL if body_len is
+ *     zero.
+ *
+ * @param body_len
+ *     The length, in bytes, of the request body. May be zero.
+ *
+ * @return
+ *     Zero on success, non-zero on error.
+ */
+int guac_protocol_send_req(guac_client* client, const char* id,
+        const char* name, const void* body, int body_len);
+
+/**
+ * Sends a "done" instruction along the given client's broadcast socket,
+ * settling a previously-received "req" with a status. The response body
+ * (if any) is shipped first over a reserved-mimetype pipe stream whose
+ * name is the correlation id; the trailing "done" carries only the id
+ * and status.
+ *
+ * @param client
+ *     The guac_client whose broadcast socket should be used. A stream is
+ *     allocated against this client for the duration of the body
+ *     transfer and freed before this function returns.
+ *
+ * @param id
+ *     The correlation identifier of the request being settled.
+ *
+ * @param status
+ *     A short status indicator. By convention, "ok" indicates success,
+ *     "error" indicates a method-level failure (with details in the
+ *     body), and "canceled" indicates the request was aborted.
+ *
+ * @param body
+ *     The response body, opaque to libguac. May be NULL if body_len is
+ *     zero.
+ *
+ * @param body_len
+ *     The length, in bytes, of the response body. May be zero.
+ *
+ * @return
+ *     Zero on success, non-zero on error.
+ */
+int guac_protocol_send_done(guac_client* client, const char* id,
+        const char* status, const void* body, int body_len);
+
+/**
+ * Sends a "cancel" instruction along the given guac_socket connection,
+ * requesting that a previously-issued "req" instruction be aborted before
+ * its "done" arrives. Either side may issue a "cancel"; the peer may
+ * still ultimately respond with a "done" if the cancellation arrives
+ * after the response was already in flight.
+ *
+ * @param socket
+ *     The guac_socket connection to use.
+ *
+ * @param id
+ *     The correlation identifier of the request to cancel.
+ *
+ * @return
+ *     Zero on success, non-zero on error.
+ */
+int guac_protocol_send_cancel(guac_socket* socket, const char* id);
+
 /**
  * Decodes the given base64-encoded string in-place. The base64 string must
  * be NULL-terminated.

src/libguac/guacamole/user-constants.h

@@ -64,5 +64,24 @@
  */
 #define GUAC_USER_STREAM_INDEX_MIMETYPE "application/vnd.glyptodon.guacamole.stream-index+json"
 
+/**
+ * The mimetype reserved for a pipe stream that carries the body of a "req"
+ * or "done" instruction. The pipe's name is the correlation id of the
+ * associated request/response exchange; libguac buffers the body and
+ * delivers it as the body argument to the user's req or done handler
+ * when the matching instruction arrives. Only one payload may be in
+ * flight per user at a time; the convention is that senders emit the
+ * pipe, its blobs, the end, and the trailing req or done as an
+ * uninterrupted sequence.
+ */
+#define GUAC_USER_RPC_PAYLOAD_MIMETYPE "application/x-guacamole-rpc-payload"
+
+/**
+ * The maximum size, in bytes, of any single "req" or "done" body buffered
+ * by libguac. Bodies larger than this are rejected at the pipe layer
+ * before reaching the user's handler.
+ */
+#define GUAC_USER_MAX_RPC_BODY_LENGTH 65536
+
 #endif
 

src/libguac/guacamole/user-fntypes.h

@@ -500,7 +500,7 @@ typedef int guac_user_put_handler(guac_user* user, guac_object* object,
         guac_stream* stream, char* mimetype, char* name);
 
 /**
- * Handler for Guacamole USB connect events, invoked when a "usbconnect" 
+ * Handler for Guacamole USB connect events, invoked when a "usbconnect"
  * instruction has been received from a user. This indicates that the user
  * has connected a USB device via WebUSB and it is available for redirection.
  *
@@ -540,10 +540,109 @@ typedef int guac_user_put_handler(guac_user* user, guac_object* object,
  *     an error occurred.
  */
 typedef int guac_user_usbconnect_handler(guac_user* user, const char* device_id,
-    int vendor_id, int product_id, const char* device_name, 
+    int vendor_id, int product_id, const char* device_name,
     const char* serial_number, int device_class, int device_subclass,
     int device_protocol, const char* interface_data);
 
+/**
+ * Handler for Guacamole "req" events, invoked when a "req" instruction has
+ * been received from a user. A "req" initiates a typed request/response
+ * exchange that is settled by a later "done" instruction carrying the
+ * same id, or aborted by a "cancel" with the same id.
+ *
+ * The body of the request is carried by a paired pipe stream whose name
+ * matches the correlation id and whose mimetype is
+ * GUAC_USER_RPC_PAYLOAD_MIMETYPE. libguac buffers that pipe internally
+ * and delivers the assembled body inline via the body and body_len
+ * parameters; the buffer is owned by libguac and remains valid only
+ * for the duration of this handler call. If the request body is empty,
+ * body will be NULL and body_len will be zero.
+ *
+ * Example:
+ * @code
+ *     int req_handler(guac_user* user, char* id, char* name,
+ *             void* body, int body_len);
+ *
+ *     int guac_user_init(guac_user* user, int argc, char** argv) {
+ *         user->req_handler = req_handler;
+ *     }
+ * @endcode
+ *
+ * @param user
+ *     The user that sent the request.
+ *
+ * @param id
+ *     The correlation identifier of this request.
+ *
+ * @param name
+ *     The method name identifying what kind of request this is.
+ *
+ * @param body
+ *     The request body assembled by libguac from the paired pipe stream,
+ *     or NULL if the body was empty.
+ *
+ * @param body_len
+ *     The length, in bytes, of the request body.
+ *
+ * @return
+ *     Zero if the request was handled successfully, non-zero otherwise.
+ */
+typedef int guac_user_req_handler(guac_user* user, char* id, char* name,
+        void* body, int body_len);
+
+/**
+ * Handler for Guacamole "done" events, invoked when a "done" instruction
+ * has been received from a user. A "done" settles a previously-issued
+ * "req" with a status.
+ *
+ * The body of the response is carried by a paired pipe stream whose name
+ * matches the correlation id and whose mimetype is
+ * GUAC_USER_RPC_PAYLOAD_MIMETYPE. libguac buffers that pipe internally
+ * and delivers the assembled body inline via the body and body_len
+ * parameters; the buffer is owned by libguac and remains valid only
+ * for the duration of this handler call. If the response body is empty,
+ * body will be NULL and body_len will be zero.
+ *
+ * @param user
+ *     The user that sent the response.
+ *
+ * @param id
+ *     The correlation identifier of the request being settled.
+ *
+ * @param status
+ *     The status of the request. By convention "ok", "error", or
+ *     "canceled".
+ *
+ * @param body
+ *     The response body assembled by libguac from the paired pipe
+ *     stream, or NULL if the body was empty.
+ *
+ * @param body_len
+ *     The length, in bytes, of the response body.
+ *
+ * @return
+ *     Zero if the response was handled successfully, non-zero otherwise.
+ */
+typedef int guac_user_done_handler(guac_user* user, char* id, char* status,
+        void* body, int body_len);
+
+/**
+ * Handler for Guacamole "cancel" events, invoked when a "cancel"
+ * instruction has been received from a user. A "cancel" requests that a
+ * previously-issued "req" be aborted before its "done" arrives.
+ *
+ * @param user
+ *     The user that sent the cancellation.
+ *
+ * @param id
+ *     The correlation identifier of the request to cancel.
+ *
+ * @return
+ *     Zero if the cancellation was handled successfully, non-zero
+ *     otherwise.
+ */
+typedef int guac_user_cancel_handler(guac_user* user, char* id);
+
 /**
 * Handler for Guacamole USB data events, invoked when a "usbdata" instruction
 * has been received from a user. This carries data from a client-side USB 

src/libguac/guacamole/user.h

@@ -598,6 +598,81 @@ struct guac_user {
      */
     guac_user_usbdisconnect_handler* usbdisconnect_handler;
 
+    /**
+     * Handler for "req" events sent by the Guacamole web-client. A "req"
+     * initiates a typed request/response exchange that is settled by a
+     * later "done" with the same id, or aborted by a "cancel" with the
+     * same id. The request body, if any, is assembled by libguac from
+     * the paired payload pipe and delivered inline to this handler.
+     *
+     * Example:
+     * @code
+     *     int req_handler(guac_user* user, char* id, char* name,
+     *             void* body, int body_len);
+     *
+     *     int guac_user_init(guac_user* user, int argc, char** argv) {
+     *         user->req_handler = req_handler;
+     *     }
+     * @endcode
+     */
+    guac_user_req_handler* req_handler;
+
+    /**
+     * Handler for "done" events sent by the Guacamole web-client,
+     * settling a previously-issued "req" with status. The response body,
+     * if any, is assembled by libguac from the paired payload pipe and
+     * delivered inline to this handler.
+     *
+     * Example:
+     * @code
+     *     int done_handler(guac_user* user, char* id, char* status,
+     *             void* body, int body_len);
+     *
+     *     int guac_user_init(guac_user* user, int argc, char** argv) {
+     *         user->done_handler = done_handler;
+     *     }
+     * @endcode
+     */
+    guac_user_done_handler* done_handler;
+
+    /**
+     * Handler for "cancel" events sent by the Guacamole web-client,
+     * aborting a previously-issued "req" before its "done" arrives.
+     *
+     * Example:
+     * @code
+     *     int cancel_handler(guac_user* user, char* id);
+     *
+     *     int guac_user_init(guac_user* user, int argc, char** argv) {
+     *         user->cancel_handler = cancel_handler;
+     *     }
+     * @endcode
+     */
+    guac_user_cancel_handler* cancel_handler;
+
+    /**
+     * Correlation id of the "req" or "done" payload pipe most recently
+     * assembled and not yet consumed by its matching instruction.
+     * malloc'd and NULL-terminated, or NULL if no body is buffered.
+     * Used internally by libguac; not intended for direct use by user
+     * code.
+     */
+    char* __rpc_pending_id;
+
+    /**
+     * Body bytes accompanying __rpc_pending_id. malloc'd, not
+     * NULL-terminated, and undefined when __rpc_pending_id is NULL. Used
+     * internally by libguac; not intended for direct use by user code.
+     */
+    char* __rpc_pending_body;
+
+    /**
+     * Length, in bytes, of __rpc_pending_body. Undefined when
+     * __rpc_pending_id is NULL. Used internally by libguac; not intended
+     * for direct use by user code.
+     */
+    int __rpc_pending_body_len;
+
 };
 
 /**