@pact-foundation/pact-core 13.7.6 → 13.7.7

package/ffi/pact-cpp.h

@@ -7,7 +7,7 @@
 #ifndef pact_ffi_h
 #define pact_ffi_h
 
-/* Generated with cbindgen:0.20.0 */
+/* Generated with cbindgen:0.24.3 */
 
 /* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */
 
@@ -134,6 +134,11 @@ struct MismatchesIterator;
  */
 struct PactMessageIterator;
 
+/**
+ * An iterator over synchronous HTTP request/response interactions in a pact.
+ */
+struct PactSyncHttpIterator;
+
 /**
  * An iterator over synchronous request/response messages in a pact.
  */
@@ -162,6 +167,11 @@ struct ProviderStateIterator;
  */
 struct ProviderStateParamIterator;
 
+/**
+ * V4 HTTP Interaction Type
+ */
+struct SynchronousHttp;
+
 /**
  * Synchronous interactions as a request message to a sequence of response messages
  */
@@ -271,13 +281,14 @@ using MessageHandle = uint32_t;
 extern "C" {
 
 /**
- * Get the current library version
+ * Returns the current library version
  */
 const char *pactffi_version();
 
 /**
  * Initialise the mock server library, can provide an environment variable name to use to
- * set the log levels.
+ * set the log levels. This function should only be called once, as it tries to install a global
+ * tracing subscriber.
  *
  * # Safety
  *
@@ -286,7 +297,8 @@ const char *pactffi_version();
 void pactffi_init(const char *log_env_var);
 
 /**
- * Initialises logging, and sets the log level explicitly.
+ * Initialises logging, and sets the log level explicitly. This function should only be called
+ * once, as it tries to install a global tracing subscriber.
  *
  * # Safety
  *
@@ -436,7 +448,7 @@ int pactffi_log_to_file(const char *file_name, LevelFilter level_filter);
 int pactffi_log_to_buffer(LevelFilter level_filter);
 
 /**
- * Initialize the thread-local logger with no sinks.
+ * Initialize the FFI logger with no sinks.
  *
  * This initialized logger does nothing until `pactffi_logger_apply` has been called.
  *
@@ -457,7 +469,7 @@ void pactffi_logger_init();
  *
  * This logger does nothing until `pactffi_logger_apply` has been called.
  *
- * Three types of sinks can be specified:
+ * Types of sinks can be specified:
  *
  * - stdout (`pactffi_logger_attach_sink("stdout", LevelFilter_Info)`)
  * - stderr (`pactffi_logger_attach_sink("stderr", LevelFilter_Debug)`)
@@ -484,22 +496,25 @@ void pactffi_logger_init();
  * # Safety
  *
  * This function checks the validity of the passed-in sink specifier, and errors
- * out if the specifier isn't valid UTF-8.
+ * out if the specifier isn't valid UTF-8. Passing in an invalid or NULL pointer will result in
+ * undefined behaviour.
  */
 int pactffi_logger_attach_sink(const char *sink_specifier,
                                LevelFilter level_filter);
 
 /**
- * Apply the thread-local logger to the program.
+ * Apply the previously configured sinks and levels to the program. If no sinks have been setup,
+ * will set the log level to info and the target to standard out.
  *
- * Any attempts to modify the logger after the call to `logger_apply` will fail.
+ * This function will install a global tracing subscriber. Any attempts to modify the logger
+ * after the call to `logger_apply` will fail.
  */
 int pactffi_logger_apply();
 
 /**
  * Fetch the in-memory logger buffer contents. This will only have any contents if the `buffer`
  * sink has been configured to log to. The contents will be allocated on the heap and will need
- * to be freed with `string_delete`.
+ * to be freed with `pactffi_string_delete`.
  *
  * Fetches the logs associated with the provided identifier, or uses the "global" one if the
  * identifier is not specified (i.e. NULL).
@@ -616,6 +631,21 @@ void pactffi_message_delete(Message *message);
  */
 const char *pactffi_message_get_contents(const Message *message);
 
+/**
+ * Sets the contents of the message.
+ *
+ * # Safety
+ *
+ * The message contents and content type must either be NULL pointers, or point to valid
+ * UTF-8 encoded NULL-terminated strings. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the message contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_message_set_contents(Message *message, const char *contents, const char *content_type);
+
 /**
  * Get the length of the contents of a `Message`.
  *
@@ -646,6 +676,24 @@ size_t pactffi_message_get_contents_length(const Message *message);
  */
 const unsigned char *pactffi_message_get_contents_bin(const Message *message);
 
+/**
+ * Sets the contents of the message as an array of bytes.
+ *
+ * # Safety
+ *
+ * The contents pointer must be valid for reads of `len` bytes, and it must be properly aligned
+ * and consecutive. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the message contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_message_set_contents_bin(Message *message,
+                                      const unsigned char *contents,
+                                      size_t len,
+                                      const char *content_type);
+
 /**
  * Get a copy of the description.
  *
@@ -1089,6 +1137,8 @@ void pactffi_pact_message_iter_delete(PactMessageIterator *iter);
  * iterator, they do not need to be deleted but will be cleaned up when the iterator is
  * deleted.
  *
+ * Will return a NULL pointer when the iterator has advanced past the end of the list.
+ *
  * # Safety
  *
  * This function is safe.
@@ -1106,6 +1156,8 @@ Message *pactffi_pact_message_iter_next(PactMessageIterator *iter);
  * iterator, they do not need to be deleted but will be cleaned up when the iterator is
  * deleted.
  *
+ * Will return a NULL pointer when the iterator has advanced past the end of the list.
+ *
  * # Safety
  *
  * This function is safe.
@@ -1123,6 +1175,43 @@ SynchronousMessage *pactffi_pact_sync_message_iter_next(PactSyncMessageIterator
  */
 void pactffi_pact_sync_message_iter_delete(PactSyncMessageIterator *iter);
 
+/**
+ * Get the next synchronous HTTP request/response interaction from the pact. As the
+ * interactions returned are owned by the iterator, they do not need to be deleted but
+ * will be cleaned up when the iterator is deleted.
+ *
+ * Will return a NULL pointer when the iterator has advanced past the end of the list.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * Deleting an interaction returned by the iterator can lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * This function will return a NULL pointer if passed a NULL pointer or if an error occurs.
+ */
+SynchronousHttp *pactffi_pact_sync_http_iter_next(PactSyncHttpIterator *iter);
+
+/**
+ * Free the iterator when you're done using it.
+ */
+void pactffi_pact_sync_http_iter_delete(PactSyncHttpIterator *iter);
+
+/**
+ * Get a mutable pointer to a newly-created default message on the heap.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * Returns NULL on error.
+ */
+SynchronousMessage *pactffi_sync_message_new();
+
 /**
  * Destroy the `Message` being pointed to.
  */
@@ -1146,6 +1235,27 @@ void pactffi_sync_message_delete(SynchronousMessage *message);
  */
 const char *pactffi_sync_message_get_request_contents(const SynchronousMessage *message);
 
+/**
+ * Sets the request contents of the message.
+ *
+ * * `message` - the message to set the request contents for
+ * * `contents` - pointer to contents to copy from. Must be a valid NULL-terminated UTF-8 string pointer.
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The message contents and content type must either be NULL pointers, or point to valid
+ * UTF-8 encoded NULL-terminated strings. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the message contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_message_set_request_contents(SynchronousMessage *message,
+                                               const char *contents,
+                                               const char *content_type);
+
 /**
  * Get the length of the request contents of a `SynchronousMessage`.
  *
@@ -1176,6 +1286,29 @@ size_t pactffi_sync_message_get_request_contents_length(const SynchronousMessage
  */
 const unsigned char *pactffi_sync_message_get_request_contents_bin(const SynchronousMessage *message);
 
+/**
+ * Sets the request contents of the message as an array of bytes.
+ *
+ * * `message` - the message to set the request contents for
+ * * `contents` - pointer to contents to copy from
+ * * `len` - number of bytes to copy from the contents pointer
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The contents pointer must be valid for reads of `len` bytes, and it must be properly aligned
+ * and consecutive. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the message contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_message_set_request_contents_bin(SynchronousMessage *message,
+                                                   const unsigned char *contents,
+                                                   size_t len,
+                                                   const char *content_type);
+
 /**
  * Get the number of response messages in the `SynchronousMessage`.
  *
@@ -1209,6 +1342,30 @@ size_t pactffi_sync_message_get_number_responses(const SynchronousMessage *messa
 const char *pactffi_sync_message_get_response_contents(const SynchronousMessage *message,
                                                        size_t index);
 
+/**
+ * Sets the response contents of the message. If index is greater than the number of responses
+ * in the message, the responses will be padded with default values.
+ *
+ * * `message` - the message to set the response contents for
+ * * `index` - index of the response to set. 0 is the first response.
+ * * `contents` - pointer to contents to copy from. Must be a valid NULL-terminated UTF-8 string pointer.
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The message contents and content type must either be NULL pointers, or point to valid
+ * UTF-8 encoded NULL-terminated strings. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the response contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_message_set_response_contents(SynchronousMessage *message,
+                                                size_t index,
+                                                const char *contents,
+                                                const char *content_type);
+
 /**
  * Get the length of the response contents of a `SynchronousMessage`.
  *
@@ -1241,6 +1398,33 @@ size_t pactffi_sync_message_get_response_contents_length(const SynchronousMessag
 const unsigned char *pactffi_sync_message_get_response_contents_bin(const SynchronousMessage *message,
                                                                     size_t index);
 
+/**
+ * Sets the response contents of the message at the given index as an array of bytes. If index
+ * is greater than the number of responses in the message, the responses will be padded with
+ * default values.
+ *
+ * * `message` - the message to set the response contents for
+ * * `index` - index of the response to set. 0 is the first response
+ * * `contents` - pointer to contents to copy from
+ * * `len` - number of bytes to copy
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The contents pointer must be valid for reads of `len` bytes, and it must be properly aligned
+ * and consecutive. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the message contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_message_set_response_contents_bin(SynchronousMessage *message,
+                                                    size_t index,
+                                                    const unsigned char *contents,
+                                                    size_t len,
+                                                    const char *content_type);
+
 /**
  * Get a copy of the description.
  *
@@ -1310,23 +1494,301 @@ const ProviderState *pactffi_sync_message_get_provider_state(const SynchronousMe
  */
 ProviderStateIterator *pactffi_sync_message_get_provider_state_iter(SynchronousMessage *message);
 
+/**
+ * Get a mutable pointer to a newly-created default interaction on the heap.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * Returns NULL on error.
+ */
+SynchronousHttp *pactffi_sync_http_new();
+
+/**
+ * Destroy the `SynchronousHttp` interaction being pointed to.
+ */
+void pactffi_sync_http_delete(SynchronousHttp *interaction);
+
+/**
+ * Get the request contents of a `SynchronousHttp` interaction in string form.
+ *
+ * # Safety
+ *
+ * The returned string must be deleted with `pactffi_string_delete`.
+ *
+ * The returned string can outlive the interaction.
+ *
+ * # Error Handling
+ *
+ * If the interaction is NULL, returns NULL. If the body of the request
+ * is missing, then this function also returns NULL. This means there's
+ * no mechanism to differentiate with this function call alone between
+ * a NULL body and a missing body.
+ */
+const char *pactffi_sync_http_get_request_contents(const SynchronousHttp *interaction);
+
+/**
+ * Sets the request contents of the interaction.
+ *
+ * * `interaction` - the interaction to set the request contents for
+ * * `contents` - pointer to contents to copy from. Must be a valid NULL-terminated UTF-8 string pointer.
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The request contents and content type must either be NULL pointers, or point to valid
+ * UTF-8 encoded NULL-terminated strings. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the request contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_http_set_request_contents(SynchronousHttp *interaction,
+                                            const char *contents,
+                                            const char *content_type);
+
+/**
+ * Get the length of the request contents of a `SynchronousHttp` interaction.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * If the interaction is NULL, returns 0. If the body of the request
+ * is missing, then this function also returns 0.
+ */
+size_t pactffi_sync_http_get_request_contents_length(const SynchronousHttp *interaction);
+
+/**
+ * Get the request contents of a `SynchronousHttp` interaction as a pointer to an array of bytes.
+ *
+ * # Safety
+ *
+ * The number of bytes in the buffer will be returned by `pactffi_sync_http_get_request_contents_length`.
+ * It is safe to use the pointer while the interaction is not deleted or changed. Using the pointer
+ * after the interaction is mutated or deleted may lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * If the interaction is NULL, returns NULL. If the body of the request
+ * is missing, then this function also returns NULL.
+ */
+const unsigned char *pactffi_sync_http_get_request_contents_bin(const SynchronousHttp *interaction);
+
+/**
+ * Sets the request contents of the interaction as an array of bytes.
+ *
+ * * `interaction` - the interaction to set the request contents for
+ * * `contents` - pointer to contents to copy from
+ * * `len` - number of bytes to copy from the contents pointer
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The contents pointer must be valid for reads of `len` bytes, and it must be properly aligned
+ * and consecutive. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the request contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_http_set_request_contents_bin(SynchronousHttp *interaction,
+                                                const unsigned char *contents,
+                                                size_t len,
+                                                const char *content_type);
+
+/**
+ * Get the response contents of a `SynchronousHttp` interaction in string form.
+ *
+ * # Safety
+ *
+ * The returned string must be deleted with `pactffi_string_delete`.
+ *
+ * The returned string can outlive the interaction.
+ *
+ * # Error Handling
+ *
+ * If the interaction is NULL, returns NULL.
+ *
+ * If the body of the response is missing, then this function also returns NULL.
+ * This means there's no mechanism to differentiate with this function call alone between
+ * a NULL body and a missing body.
+ */
+const char *pactffi_sync_http_get_response_contents(const SynchronousHttp *interaction);
+
+/**
+ * Sets the response contents of the interaction.
+ *
+ * * `interaction` - the interaction to set the response contents for
+ * * `contents` - pointer to contents to copy from. Must be a valid NULL-terminated UTF-8 string pointer.
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The response contents and content type must either be NULL pointers, or point to valid
+ * UTF-8 encoded NULL-terminated strings. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the response contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_http_set_response_contents(SynchronousHttp *interaction,
+                                             const char *contents,
+                                             const char *content_type);
+
+/**
+ * Get the length of the response contents of a `SynchronousHttp` interaction.
+ *
+ * # Safety
+ *
+ * This function is safe.
+ *
+ * # Error Handling
+ *
+ * If the interaction is NULL or the index is not valid, returns 0. If the body of the response
+ * is missing, then this function also returns 0.
+ */
+size_t pactffi_sync_http_get_response_contents_length(const SynchronousHttp *interaction);
+
+/**
+ * Get the response contents of a `SynchronousHttp` interaction as a pointer to an array of bytes.
+ *
+ * # Safety
+ *
+ * The number of bytes in the buffer will be returned by `pactffi_sync_http_get_response_contents_length`.
+ * It is safe to use the pointer while the interaction is not deleted or changed. Using the pointer
+ * after the interaction is mutated or deleted may lead to undefined behaviour.
+ *
+ * # Error Handling
+ *
+ * If the interaction is NULL, returns NULL. If the body of the response
+ * is missing, then this function also returns NULL.
+ */
+const unsigned char *pactffi_sync_http_get_response_contents_bin(const SynchronousHttp *interaction);
+
+/**
+ * Sets the response contents of the `SynchronousHttp` interaction as an array of bytes.
+ *
+ * * `interaction` - the interaction to set the response contents for
+ * * `contents` - pointer to contents to copy from
+ * * `len` - number of bytes to copy
+ * * `content_type` - pointer to the NULL-terminated UTF-8 string containing the content type of the data.
+ *
+ * # Safety
+ *
+ * The contents pointer must be valid for reads of `len` bytes, and it must be properly aligned
+ * and consecutive. Otherwise behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the response contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as unknown.
+ */
+void pactffi_sync_http_set_response_contents_bin(SynchronousHttp *interaction,
+                                                 const unsigned char *contents,
+                                                 size_t len,
+                                                 const char *content_type);
+
+/**
+ * Get a copy of the description.
+ *
+ * # Safety
+ *
+ * The returned string must be deleted with `pactffi_string_delete`.
+ *
+ * Since it is a copy, the returned string may safely outlive
+ * the `SynchronousHttp` interaction.
+ *
+ * # Errors
+ *
+ * On failure, this function will return a NULL pointer.
+ *
+ * This function may fail if the Rust string contains embedded
+ * null ('\0') bytes.
+ */
+const char *pactffi_sync_http_get_description(const SynchronousHttp *interaction);
+
+/**
+ * Write the `description` field on the `SynchronousHttp`.
+ *
+ * # Safety
+ *
+ * `description` must contain valid UTF-8. Invalid UTF-8
+ * will be replaced with U+FFFD REPLACEMENT CHARACTER.
+ *
+ * This function will only reallocate if the new string
+ * does not fit in the existing buffer.
+ *
+ * # Error Handling
+ *
+ * Errors will be reported with a non-zero return value.
+ */
+int pactffi_sync_http_set_description(SynchronousHttp *interaction, const char *description);
+
+/**
+ * Get a copy of the provider state at the given index from this interaction.
+ *
+ * # Safety
+ *
+ * The returned structure must be deleted with `provider_state_delete`.
+ *
+ * Since it is a copy, the returned structure may safely outlive
+ * the `SynchronousHttp`.
+ *
+ * # Error Handling
+ *
+ * On failure, this function will return a variant other than Success.
+ *
+ * This function may fail if the index requested is out of bounds,
+ * or if any of the Rust strings contain embedded null ('\0') bytes.
+ */
+const ProviderState *pactffi_sync_http_get_provider_state(const SynchronousHttp *interaction,
+                                                          unsigned int index);
+
+/**
+ * Get an iterator over provider states.
+ *
+ * # Safety
+ *
+ * The underlying data must not change during iteration.
+ *
+ * # Error Handling
+ *
+ * Returns NULL if an error occurs.
+ */
+ProviderStateIterator *pactffi_sync_http_get_provider_state_iter(SynchronousHttp *interaction);
+
 /**
  * Delete a string previously returned by this FFI.
  *
  * It is explicitly allowed to pass a null pointer to this function;
  * in that case the function will do nothing.
+ *
+ * # Safety
+ * Passing an invalid pointer, or one that was not returned by a FFI function can result in
+ * undefined behaviour.
  */
 void pactffi_string_delete(char *string);
 
 /**
- * External interface to create a mock server. A pointer to the pact JSON as a C string is passed in,
- * as well as the port for the mock server to run on. A value of 0 for the port will result in a
- * port being allocated by the operating system. The port of the mock server is returned.
+ * [DEPRECATED] External interface to create a HTTP mock server. A pointer to the pact JSON as a NULL-terminated C
+ * string is passed in, as well as the port for the mock server to run on. A value of 0 for the
+ * port will result in a port being allocated by the operating system. The port of the mock server is returned.
  *
  * * `pact_str` - Pact JSON
  * * `addr_str` - Address to bind to in the form name:port (i.e. 127.0.0.1:0)
  * * `tls` - boolean flag to indicate of the mock server should use TLS (using a self-signed certificate)
  *
+ * This function is deprecated and replaced with `pactffi_create_mock_server_for_transport`.
+ *
  * # Errors
  *
  * Errors are returned as negative values.
@@ -1349,30 +1811,32 @@ int32_t pactffi_create_mock_server(const char *pact_str,
  * Fetch the CA Certificate used to generate the self-signed certificate for the TLS mock server.
  *
  * **NOTE:** The string for the result is allocated on the heap, and will have to be freed
- * by the caller using free_string
+ * by the caller using pactffi_string_delete.
  *
  * # Errors
  *
- * An empty string indicates an error reading the pem file
+ * An empty string indicates an error reading the pem file.
  */
 char *pactffi_get_tls_ca_certificate();
 
 /**
- * External interface to create a mock server. A Pact handle is passed in,
+ * [DEPRECATED] External interface to create a HTTP mock server. A Pact handle is passed in,
  * as well as the port for the mock server to run on. A value of 0 for the port will result in a
  * port being allocated by the operating system. The port of the mock server is returned.
  *
- * * `pact` - Handle to a Pact model
- * * `addr_str` - Address to bind to in the form name:port (i.e. 127.0.0.1:0)
+ * * `pact` - Handle to a Pact model created with created with `pactffi_new_pact`.
+ * * `addr_str` - Address to bind to in the form name:port (i.e. 127.0.0.1:0). Must be a valid UTF-8 NULL-terminated string.
  * * `tls` - boolean flag to indicate of the mock server should use TLS (using a self-signed certificate)
  *
+ * This function is deprecated and replaced with `pactffi_create_mock_server_for_transport`.
+ *
  * # Errors
  *
  * Errors are returned as negative values.
  *
  * | Error | Description |
  * |-------|-------------|
- * | -1 | An invalid handle was received |
+ * | -1 | An invalid handle was received. Handles should be created with `pactffi_new_pact` |
  * | -3 | The mock server could not be started |
  * | -4 | The method panicked |
  * | -5 | The address is not valid |
@@ -1383,6 +1847,44 @@ int32_t pactffi_create_mock_server_for_pact(PactHandle pact,
                                             const char *addr_str,
                                             bool tls);
 
+/**
+ * Create a mock server for the provided Pact handle and transport. If the transport is not
+ * provided (it is a NULL pointer or an empty string), will default to an HTTP transport. The
+ * address is the interface bind to, and will default to the loopback adapter if not specified.
+ * Specifying a value of zero for the port will result in the operating system allocating the port.
+ *
+ * Parameters:
+ * * `pact` - Handle to a Pact model created with created with `pactffi_new_pact`.
+ * * `addr` - Address to bind to (i.e. `127.0.0.1` or `[::1]`). Must be a valid UTF-8 NULL-terminated string, or NULL or empty, in which case the loopback adapter is used.
+ * * `port` - Port number to bind to. A value of zero will result in the operating system allocating an available port.
+ * * `transport` - The transport to use (i.e. http, https, grpc). Must be a valid UTF-8 NULL-terminated string, or NULL or empty, in which case http will be used.
+ * * `transport_config` - (OPTIONAL) Configuration for the transport as a valid JSON string. Set to NULL or empty if not required.
+ *
+ * The port of the mock server is returned.
+ *
+ * # Safety
+ * NULL pointers or empty strings can be passed in for the address, transport and transport_config,
+ * in which case a default value will be used. Passing in an invalid pointer will result in undefined behaviour.
+ *
+ * # Errors
+ *
+ * Errors are returned as negative values.
+ *
+ * | Error | Description |
+ * |-------|-------------|
+ * | -1 | An invalid handle was received. Handles should be created with `pactffi_new_pact` |
+ * | -2 | transport_config is not valid JSON |
+ * | -3 | The mock server could not be started |
+ * | -4 | The method panicked |
+ * | -5 | The address is not valid |
+ *
+ */
+int32_t pactffi_create_mock_server_for_transport(PactHandle pact,
+                                                 const char *addr,
+                                                 uint16_t port,
+                                                 const char *transport,
+                                                 const char *transport_config);
+
 /**
  * External interface to check if a mock server has matched all its requests. The port number is
  * passed in, and if all requests have been matched, true is returned. False is returned if there
@@ -1449,41 +1951,46 @@ const char *pactffi_mock_server_logs(int32_t mock_server_port);
 
 /**
  * Generates a datetime value from the provided format string, using the current system date and time
- * NOTE: The memory for the returned string needs to be freed with the free_string function
+ * NOTE: The memory for the returned string needs to be freed with the `pactffi_string_delete` function
  *
  * # Safety
  *
- * Exported functions are inherently unsafe.
+ * If the format string pointer is NULL or has invalid UTF-8 characters, an error result will be
+ * returned. If the format string pointer is not a valid pointer or is not a NULL-terminated string,
+ * this will lead to undefined behaviour.
  */
 StringResult pactffi_generate_datetime_string(const char *format);
 
 /**
- * Checks that the example string matches the given regex
+ * Checks that the example string matches the given regex.
  *
  * # Safety
  *
- * Exported functions are inherently unsafe.
+ * Both the regex and example pointers must be valid pointers to NULL-terminated strings. Invalid
+ * pointers will result in undefined behaviour.
  */
 bool pactffi_check_regex(const char *regex, const char *example);
 
 /**
  * Generates an example string based on the provided regex.
- * NOTE: The memory for the returned string needs to be freed with the free_string function
+ * NOTE: The memory for the returned string needs to be freed with the `pactffi_string_delete` function.
  *
  * # Safety
  *
- * Exported functions are inherently unsafe.
+ * The regex pointer must be a valid pointer to a NULL-terminated string. Invalid pointers will
+ * result in undefined behaviour.
  */
 StringResult pactffi_generate_regex_value(const char *regex);
 
 /**
  * [DEPRECATED] Frees the memory allocated to a string by another function
  *
- * This function is deprecated. Use pactffi_string_delete instead.
+ * This function is deprecated. Use `pactffi_string_delete` instead.
  *
  * # Safety
  *
- * Exported functions are inherently unsafe.
+ * The string pointer can be NULL (which is a no-op), but if it is not a valid pointer the call
+ * will result in undefined behaviour.
  */
 void pactffi_free_string(char *s);
 
@@ -1553,7 +2060,7 @@ bool pactffi_given(InteractionHandle interaction, const char *description);
  *
  * * `1` - Function panicked. Error message will be available by calling `pactffi_get_error_message`.
  * * `2` - Handle was not valid.
- * * `3` - Mock server was already started and the interation can not be modified.
+ * * `3` - Mock server was already started and the integration can not be modified.
  * * `4` - Not a V4 interaction.
  */
 unsigned int pactffi_interaction_test_name(InteractionHandle interaction,
@@ -1578,8 +2085,18 @@ bool pactffi_given_with_param(InteractionHandle interaction,
  *
  * * `method` - The request method. Defaults to GET.
  * * `path` - The request path. Defaults to `/`.
+ *
+ * To include matching rules for the path (only regex really makes sense to use), include the
+ * matching rule JSON format with the value as a single JSON document. I.e.
+ *
+ * ```c
+ * const char* value = "{\"value\":\"/path/to/100\", \"pact:matcher:type\":\"regex\", \"regex\":\"\\/path\\/to\\/\\\\d+\"}";
+ * pactffi_with_request(handle, "GET", value);
+ *
  */
-bool pactffi_with_request(InteractionHandle interaction, const char *method, const char *path);
+bool pactffi_with_request(InteractionHandle interaction,
+                          const char *method,
+                          const char *path);
 
 /**
  * Configures a query parameter for the Interaction. Returns false if the interaction or Pact can't be
@@ -1588,15 +2105,57 @@ bool pactffi_with_request(InteractionHandle interaction, const char *method, con
  * * `name` - the query parameter name.
  * * `value` - the query parameter value.
  * * `index` - the index of the value (starts at 0). You can use this to create a query parameter with multiple values
+ *
+ * **DEPRECATED:** Use `pactffi_with_query_parameter_v2`, which deals with multiple values correctly
  */
 bool pactffi_with_query_parameter(InteractionHandle interaction,
                                   const char *name,
                                   size_t index,
                                   const char *value);
 
+/**
+ * Configures a query parameter for the Interaction. Returns false if the interaction or Pact can't be
+ * modified (i.e. the mock server for it has already started)
+ *
+ * * `name` - the query parameter name.
+ * * `value` - the query parameter value. Either a simple string or a JSON document.
+ * * `index` - the index of the value (starts at 0). You can use this to create a query parameter with multiple values
+ *
+ * To setup a query parameter with multiple values, you can either call this function multiple times
+ * with a different index value, i.e. to create `id=2&id=3`
+ *
+ * ```c
+ * pactffi_with_query_parameter_v2(handle, "id", 0, "2");
+ * pactffi_with_query_parameter_v2(handle, "id", 1, "3");
+ * ```
+ *
+ * Or you can call it once with a JSON value that contains multiple values:
+ *
+ * ```c
+ * const char* value = "{\"value\": [\"2\",\"3\"]}";
+ * pactffi_with_query_parameter_v2(handle, "id", 0, value);
+ * ```
+ *
+ * To include matching rules for the query parameter, include the matching rule JSON format with
+ * the value as a single JSON document. I.e.
+ *
+ * ```c
+ * const char* value = "{\"value\":\"2\", \"pact:matcher:type\":\"regex\", \"regex\":\"\\\\d+\"}";
+ * pactffi_with_query_parameter_v2(handle, "id", 0, value);
+ * ```
+ *
+ * # Safety
+ * The name and value parameters must be valid pointers to NULL terminated strings.
+ * ```
+ */
+bool pactffi_with_query_parameter_v2(InteractionHandle interaction,
+                                     const char *name,
+                                     size_t index,
+                                     const char *value);
+
 /**
  * Sets the specification version for a given Pact model. Returns false if the interaction or Pact can't be
- * modified (i.e. the mock server for it has already started) or the version is invalid
+ * modified (i.e. the mock server for it has already started) or the version is invalid.
  *
  * * `pact` - Handle to a Pact model
  * * `version` - the spec version to use
@@ -1626,6 +2185,8 @@ bool pactffi_with_pact_metadata(PactHandle pact,
  * * `name` - the header name.
  * * `value` - the header value.
  * * `index` - the index of the value (starts at 0). You can use this to create a header with multiple values
+ *
+ * **DEPRECATED:** Use `pactffi_with_header_v2`, which deals with multiple values correctly
  */
 bool pactffi_with_header(InteractionHandle interaction,
                          InteractionPart part,
@@ -1633,6 +2194,47 @@ bool pactffi_with_header(InteractionHandle interaction,
                          size_t index,
                          const char *value);
 
+/**
+ * Configures a header for the Interaction. Returns false if the interaction or Pact can't be
+ * modified (i.e. the mock server for it has already started)
+ *
+ * * `part` - The part of the interaction to add the header to (Request or Response).
+ * * `name` - the header name.
+ * * `value` - the header value.
+ * * `index` - the index of the value (starts at 0). You can use this to create a header with multiple values
+ *
+ * To setup a header with multiple values, you can either call this function multiple times
+ * with a different index value, i.e. to create `x-id=2, 3`
+ *
+ * ```c
+ * pactffi_with_header_v2(handle, InteractionPart::Request, "x-id", 0, "2");
+ * pactffi_with_header_v2(handle, InteractionPart::Request, "x-id", 1, "3");
+ * ```
+ *
+ * Or you can call it once with a JSON value that contains multiple values:
+ *
+ * ```c
+ * const char* value = "{\"value\": [\"2\",\"3\"]}";
+ * pactffi_with_header_v2(handle, InteractionPart::Request, "x-id", 0, value);
+ * ```
+ *
+ * To include matching rules for the header, include the matching rule JSON format with
+ * the value as a single JSON document. I.e.
+ *
+ * ```c
+ * const char* value = "{\"value\":\"2\", \"pact:matcher:type\":\"regex\", \"regex\":\"\\\\d+\"}";
+ * pactffi_with_header_v2(handle, InteractionPart::Request, "id", 0, value);
+ * ```
+ *
+ * # Safety
+ * The name and value parameters must be valid pointers to NULL terminated strings.
+ */
+bool pactffi_with_header_v2(InteractionHandle interaction,
+                            InteractionPart part,
+                            const char *name,
+                            size_t index,
+                            const char *value);
+
 /**
  * Configures the response for the Interaction. Returns false if the interaction or Pact can't be
  * modified (i.e. the mock server for it has already started)
@@ -1649,6 +2251,22 @@ bool pactffi_response_status(InteractionHandle interaction, unsigned short statu
  * * `content_type` - The content type of the body. Defaults to `text/plain`. Will be ignored if a content type
  *   header is already set.
  * * `body` - The body contents. For JSON payloads, matching rules can be embedded in the body.
+ *
+ * For HTTP and async message interactions, this will overwrite the body. With asynchronous messages, the
+ * part parameter will be ignored. With synchronous messages, the request contents will be overwritten,
+ * while a new response will be appended to the message.
+ *
+ * # Safety
+ *
+ * The interaction contents and content type must either be NULL pointers, or point to valid
+ * UTF-8 encoded NULL-terminated strings. Otherwise, behaviour is undefined.
+ *
+ * # Error Handling
+ *
+ * If the contents is a NULL pointer, it will set the body contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will set the content type as TEXT.
+ * Returns false if the interaction or Pact can't be modified (i.e. the mock server for it has
+ * already started) or an error has occurred.
  */
 bool pactffi_with_body(InteractionHandle interaction,
                        InteractionPart part,
@@ -1665,6 +2283,22 @@ bool pactffi_with_body(InteractionHandle interaction,
  * * `content_type` - Expected content type.
  * * `body` - example body contents in bytes
  * * `size` - number of bytes in the body
+ *
+ * For HTTP and async message interactions, this will overwrite the body. With asynchronous messages, the
+ * part parameter will be ignored. With synchronous messages, the request contents will be overwritten,
+ * while a new response will be appended to the message.
+ *
+ * # Safety
+ *
+ * The content type must be a valid UTF-8 encoded NULL-terminated string. The body pointer must
+ * be valid for reads of `size` bytes, and it must be properly aligned and consecutive.
+ *
+ * # Error Handling
+ *
+ * If the body is a NULL pointer, it will set the body contents as null. If the content
+ * type is a null pointer, or can't be parsed, it will return false.
+ * Returns false if the interaction or Pact can't be modified (i.e. the mock server for it has
+ * already started) or an error has occurred.
  */
 bool pactffi_with_binary_file(InteractionHandle interaction,
                               InteractionPart part,
@@ -1675,13 +2309,27 @@ bool pactffi_with_binary_file(InteractionHandle interaction,
 /**
  * Adds a binary file as the body as a MIME multipart with the expected content type and example contents. Will use
  * a mime type matcher to match the body. Returns an error if the interaction or Pact can't be
- * modified (i.e. the mock server for it has already started)
+ * modified (i.e. the mock server for it has already started) or an error occurs.
  *
  * * `interaction` - Interaction handle to set the body for.
  * * `part` - Request or response part.
  * * `content_type` - Expected content type of the file.
  * * `file` - path to the example file
  * * `part_name` - name for the mime part
+ *
+ * # Safety
+ *
+ * The content type, file path and part name must be valid pointers to UTF-8 encoded NULL-terminated strings.
+ * Passing invalid pointers or pointers to strings that are not NULL terminated will lead to undefined
+ * behaviour.
+ *
+ * # Error Handling
+ *
+ * If the file path is a NULL pointer, it will set the body contents as as an empty mime-part.
+ * If the file path does not point to a valid file, or is not able to be read, it will return an
+ * error result. If the content type is a null pointer, or can't be parsed, it will return an error result.
+ * Returns an error if the interaction or Pact can't be modified (i.e. the mock server for it has
+ * already started), the interaction is not an HTTP interaction or some other error occurs.
  */
 StringResult pactffi_with_multipart_file(InteractionHandle interaction,
                                          InteractionPart part,
@@ -1723,6 +2371,23 @@ PactMessageIterator *pactffi_pact_handle_get_message_iter(PactHandle pact);
  */
 PactSyncMessageIterator *pactffi_pact_handle_get_sync_message_iter(PactHandle pact);
 
+/**
+ * Get an iterator over all the synchronous HTTP request/response interactions of the Pact.
+ * The returned iterator needs to be freed with `pactffi_pact_sync_http_iter_delete`.
+ *
+ * # Safety
+ *
+ * The iterator contains a copy of the Pact, so it is always safe to use.
+ *
+ * # Error Handling
+ *
+ * On failure, this function will return a NULL pointer.
+ *
+ * This function may fail if any of the Rust strings contain embedded
+ * null ('\0') bytes.
+ */
+PactSyncHttpIterator *pactffi_pact_handle_get_sync_http_iter(PactHandle pact);
+
 /**
  * Creates a new Pact Message model and returns a handle to it.
  *
@@ -1930,7 +2595,7 @@ int32_t pactffi_verify(const char *args);
  * Get a Handle to a newly created verifier. You should call `pactffi_verifier_shutdown` when
  * done with the verifier to free all allocated resources.
  *
- * This function is deprecated. Use `pactffi_verifier_new_for_application` which allows the
+ * Deprecated: This function is deprecated. Use `pactffi_verifier_new_for_application` which allows the
  * calling application/framework name and version to be specified.
  *
  * # Safety
@@ -2282,12 +2947,13 @@ const char *pactffi_verifier_json(const VerifierHandle *handle);
  * Returns zero on success, and a positive integer value on failure.
  *
  * Note that plugins run as separate processes, so will need to be cleaned up afterwards by
- * calling `pactffi_cleanup_plugins` otherwise you have plugin processes left running.
+ * calling `pactffi_cleanup_plugins` otherwise you will have plugin processes left running.
  *
  * # Safety
  *
  * `plugin_name` must be a valid pointer to a NULL terminated string. `plugin_version` may be null,
- * and if not NULL must also be a valid pointer to a NULL terminated string.
+ * and if not NULL must also be a valid pointer to a NULL terminated string. Invalid
+ * pointers will result in undefined behaviour.
  *
  * # Errors
  *
@@ -2321,7 +2987,8 @@ void pactffi_cleanup_plugins(PactHandle pact);
  *
  * # Safety
  *
- * `content_type` and `contents` must be a valid pointers to NULL terminated strings.
+ * `content_type` and `contents` must be a valid pointers to NULL terminated strings. Invalid
+ * pointers will result in undefined behaviour.
  *
  * # Errors
  *