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

Adds two new protocol instructions in libguac:

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

"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"
or "error".

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

Both 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_user_req_handler and guac_user_done_handler typedefs in
  user-fntypes.h. Both handlers receive the assembled body via
  (void* body, int body_len), owned by libguac and valid only during
  the call.
* req_handler and done_handler callback fields on guac_user in
  user.h.
* __guac_handle_req and __guac_handle_done 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.

Unit tests cover the wire format for send_req and send_done, dispatch
of inbound req and done, the single-slot pending semantics
(end_handler drop-and-replace, req without preceding pipe), and the
new stream destructor (per-free-stream, disconnect-cleanup, opt-in
no-op when unset, and the regression case where __init_input_stream
must reset destructor on slot reuse).

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,75 @@ 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.
+ *
+ * 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);
+
 /**
  * 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,82 @@ 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.
+ *
+ * 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 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,61 @@ 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. 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;
+
+    /**
+     * 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;
+
 };
 
 /**