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).

All three send functions take guac_user, so each RPC exchange targets
one specific user rather than broadcasting via the client socket. This
avoids the N-done-per-req problem in shared sessions where every
joined user would otherwise receive the same req.

API surface:

* guac_protocol_send_req(user, id, name, body, body_len) and
  guac_protocol_send_done(user, id, status, body, body_len) in
  protocol.h / protocol.c. Each allocates a stream against the user,
  ships the body over the paired pipe via user->socket, then sends
  the trailing instruction. Body may be NULL with body_len 0.
* guac_protocol_send_cancel(user, 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.

Also adds an optional destructor callback on guac_stream, called from
guac_user_free_stream and guac_client_free_stream, and from
guac_user_free and guac_client_free for any streams still open at
disconnect. The RPC body assembly installs the destructor when it
allocates, so an in-progress body that never reaches end is freed at
disconnect. Existing handlers are unaffected since the field defaults
to NULL.

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/client.c

@@ -139,13 +139,21 @@ guac_stream* guac_client_alloc_stream(guac_client* client) {
     allocd_stream->ack_handler = NULL;
     allocd_stream->blob_handler = NULL;
     allocd_stream->end_handler = NULL;
+    allocd_stream->destructor = NULL;
 
     return allocd_stream;
 
 }
 
 void guac_client_free_stream(guac_client* client, guac_stream* stream) {
 
+    /* Run the registered destructor for the stream's data, if any */
+    if (stream->destructor != NULL) {
+        stream->destructor(stream->data);
+        stream->destructor = NULL;
+        stream->data = NULL;
+    }
+
     /* Mark stream as closed */
     int freed_index = stream->index;
     stream->index = GUAC_CLIENT_CLOSED_STREAM_INDEX;
@@ -289,6 +297,7 @@ guac_client* guac_client_alloc(void) {
 
     for (i=0; i<GUAC_CLIENT_MAX_STREAMS; i++) {
         client->__output_streams[i].index = GUAC_CLIENT_CLOSED_STREAM_INDEX;
+        client->__output_streams[i].destructor = NULL;
     }
 
     /* Init locks */
@@ -344,6 +353,15 @@ void guac_client_free(guac_client* client) {
     guac_pool_free(client->__buffer_pool);
     guac_pool_free(client->__layer_pool);
 
+    /* Run any registered destructors for streams still open at
+     * disconnect so their data pointers do not leak */
+    for (int i = 0; i < GUAC_CLIENT_MAX_STREAMS; i++) {
+        guac_stream* stream = &client->__output_streams[i];
+        if (stream->index != GUAC_CLIENT_CLOSED_STREAM_INDEX
+                && stream->destructor != NULL)
+            stream->destructor(stream->data);
+    }
+
     /* Free streams */
     guac_mem_free(client->__output_streams);
 

src/libguac/guacamole/protocol.h

@@ -28,13 +28,15 @@
  * @file protocol.h
  */
 
+#include "client-types.h"
 #include "layer-types.h"
 #include "object-types.h"
 #include "protocol-constants.h"
 #include "protocol-types.h"
 #include "socket-types.h"
 #include "stream-types.h"
 #include "timestamp-types.h"
+#include "user-types.h"
 
 #include <cairo/cairo.h>
 #include <stdarg.h>
@@ -1119,6 +1121,93 @@ 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" to the given user, starting a typed request/response
+ * exchange. 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.
+ *
+ * Callers on the same guac_user must serialize calls to this and
+ * guac_protocol_send_done so the four wire instructions (pipe, blobs,
+ * end, req or done) for one exchange are not interleaved with those of
+ * another. The receive side tracks at most one in-flight body per user;
+ * concurrent senders that interleave would race that slot.
+ *
+ * @param user
+ *     The guac_user to send the request to. The body stream is
+ *     allocated against this user 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_user* user, const char* id,
+        const char* name, const void* body, int body_len);
+
+/**
+ * Sends a "done" to the given user, settling a previously received "req"
+ * with a status. The body ships first on a pipe in the same way as
+ * guac_protocol_send_req, including the same per-user serialization
+ * requirement.
+ *
+ * @param user
+ *     The guac_user to send the response to. The body stream is
+ *     allocated against this user 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_user* user, const char* id,
+        const char* status, const void* body, int body_len);
+
+/**
+ * Sends a "cancel" to the given user, requesting that a previously-issued
+ * "req" 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 user
+ *     The guac_user to send the cancellation to.
+ *
+ * @param id
+ *     The correlation identifier of the request to cancel.
+ *
+ * @return
+ *     Zero on success, non-zero on error.
+ */
+int guac_protocol_send_cancel(guac_user* user, const char* id);
+
 /**
  * Decodes the given base64-encoded string in-place. The base64 string must
  * be NULL-terminated.

src/libguac/guacamole/stream.h

@@ -105,6 +105,34 @@ struct guac_stream {
      */
     guac_user_end_handler* end_handler;
 
+    /**
+     * Optional cleanup callback for whatever the stream's data pointer
+     * holds. Called from guac_user_free_stream when the stream is freed,
+     * and from guac_user_free for any streams still open when the user
+     * disconnects. NULL if no cleanup is needed.
+     *
+     * Example:
+     * @code
+     *     static void my_data_free(void* data) {
+     *         my_data* d = (my_data*) data;
+     *         free(d->buffer);
+     *         free(d);
+     *     }
+     *
+     *     int my_pipe_handler(guac_user* user, guac_stream* stream,
+     *             char* mimetype, char* name) {
+     *         my_data* d = malloc(sizeof(*d));
+     *         d->buffer = NULL;
+     *         stream->data = d;
+     *         stream->blob_handler = my_blob_handler;
+     *         stream->end_handler = my_end_handler;
+     *         stream->destructor = my_data_free;
+     *         return 0;
+     *     }
+     * @endcode
+     */
+    void (*destructor)(void* data);
+
 };
 
 #endif

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