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

Adds three new protocol instructions in libguac:

* "req"   - id, name
* "done"  - id, status
* "cancel" - id

"req" starts a typed request/response exchange with a correlation id
and a method name (by convention "<feature>.<verb>"). The peer settles
it with a "done" carrying the same id and a status, typically "ok",
"error", or "canceled". Either side can issue a "cancel" with the
matching id to abort an in-flight exchange.

The bodies of "req" and "done" ride a paired pipe whose name is the
correlation id and whose mimetype is GUAC_USER_RPC_PAYLOAD_MIMETYPE
("application/x-guacamole-rpc-payload"). libguac buffers the body
under that id and hands it to the user's req or done handler when the
matching instruction arrives. Only one body can be in flight per user;
senders should emit the pipe, its blobs, the end, and the trailing
req or done back to back. The body is capped at
GUAC_USER_MAX_RPC_BODY_LENGTH (64 KiB).

API surface:

* guac_protocol_send_req(client, id, name, body, body_len) and
  guac_protocol_send_done(client, id, status, body, body_len) in
  protocol.h / protocol.c. Each allocates a stream against the client,
  ships the body over the paired pipe, then sends the trailing
  instruction. Body may be NULL with body_len 0.
* guac_protocol_send_cancel(socket, id) for the abort case.
* guac_user_req_handler, guac_user_done_handler, and
  guac_user_cancel_handler typedefs in user-fntypes.h. req and done
  handlers receive the assembled body via (void* body, int body_len),
  owned by libguac and valid only during the call.
* 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. __guac_handle_pipe intercepts the reserved mimetype
  and assembles the body into per-user pending fields.

The instructions carry no feature-specific semantics. The first
consumer is WebAuthn passthrough using "webauthn.create" and
"webauthn.get"; other RPC-style features can reuse the same plumbing.

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,88 @@ 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" over the given client's broadcast socket, starting a
+ * typed request/response exchange with the peer. The body ships first
+ * on a pipe named for the correlation id with the reserved
+ * GUAC_USER_RPC_PAYLOAD_MIMETYPE; the trailing "req" carries only the
+ * id and method name. The peer settles the request with a "done"
+ * carrying the same id, or either side can 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 to ship the body and freed
+ *     before this function returns.
+ *
+ * @param id
+ *     Correlation identifier, typically a UUID string.
+ *
+ * @param name
+ *     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
+ *     Length of the request body in bytes. 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" over the given client's broadcast socket, settling a
+ * previously received "req" with a status. The body ships first on a
+ * pipe in the same way as guac_protocol_send_req.
+ *
+ * @param client
+ *     The guac_client whose broadcast socket should be used. A stream
+ *     is allocated against this client to ship the body and freed
+ *     before this function returns.
+ *
+ * @param id
+ *     Correlation id of the request being settled.
+ *
+ * @param status
+ *     Status of the request. By convention "ok" for success, "error"
+ *     for a method-level failure (with details in the body), or
+ *     "canceled" if the request was aborted.
+ *
+ * @param body
+ *     The response body, opaque to libguac. May be NULL if body_len is
+ *     zero.
+ *
+ * @param body_len
+ *     Length of the response body in bytes. 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,21 @@
  */
 #define GUAC_USER_STREAM_INDEX_MIMETYPE "application/vnd.glyptodon.guacamole.stream-index+json"
 
+/**
+ * Reserved pipe mimetype for the body of a "req" or "done" instruction.
+ * The pipe's name is the correlation id; libguac buffers the body and
+ * hands it to the user's req or done handler when the matching
+ * instruction arrives. Only one body can be in flight per user, so
+ * senders should emit the pipe, its blobs, the end, and the trailing
+ * req or done back to back.
+ */
+#define GUAC_USER_RPC_PAYLOAD_MIMETYPE "application/x-guacamole-rpc-payload"
+
+/**
+ * Maximum size, in bytes, of a single "req" or "done" body buffered by
+ * libguac. Larger bodies are rejected before the user's handler runs.
+ */
+#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,100 @@ 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" starts 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 body comes in on a paired pipe with the correlation id as the name
+ * and GUAC_USER_RPC_PAYLOAD_MIMETYPE as the mimetype. libguac buffers it
+ * and hands it to the handler via body and body_len. The buffer belongs
+ * to libguac and is only valid for this call. If the body is empty,
+ * body is NULL and body_len is 0.
+ *
+ * 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
+ *     Correlation identifier of this request.
+ *
+ * @param name
+ *     Method name identifying what kind of request this is.
+ *
+ * @param body
+ *     The request body assembled from the paired pipe, or NULL if
+ *     empty.
+ *
+ * @param body_len
+ *     Length of the request body in bytes.
+ *
+ * @return
+ *     Zero on success, non-zero on error.
+ */
+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 comes in on a paired pipe in the same
+ * way as the req handler.
+ *
+ * @param user
+ *     The user that sent the response.
+ *
+ * @param id
+ *     Correlation identifier of the request being settled.
+ *
+ * @param status
+ *     Status of the request. By convention "ok", "error", or
+ *     "canceled".
+ *
+ * @param body
+ *     The response body assembled from the paired pipe, or NULL if
+ *     empty.
+ *
+ * @param body_len
+ *     Length of the response body in bytes.
+ *
+ * @return
+ *     Zero on success, non-zero on error.
+ */
+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,77 @@ struct guac_user {
      */
     guac_user_usbdisconnect_handler* usbdisconnect_handler;
 
+    /**
+     * Handler for "req" events sent by the Guacamole web-client. A "req"
+     * starts a typed request/response exchange 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 handed 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 a status. The response
+     * body, if any, is assembled by libguac from the paired payload pipe
+     * and handed 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 most recent payload pipe assembled, still
+     * waiting for the matching req or done. malloc'd, NULL-terminated,
+     * or NULL if nothing is buffered. Internal to libguac.
+     */
+    char* __rpc_pending_id;
+
+    /**
+     * Body bytes for __rpc_pending_id. malloc'd, not NULL-terminated,
+     * undefined when __rpc_pending_id is NULL. Internal to libguac.
+     */
+    char* __rpc_pending_body;
+
+    /**
+     * Length of __rpc_pending_body in bytes. Undefined when
+     * __rpc_pending_id is NULL. Internal to libguac.
+     */
+    int __rpc_pending_body_len;
+
 };
 
 /**