Ffi¶
Python bindings for the Pact FFI.
This module provides a Python interface to the Pact FFI. It is a thin wrapper around the C API, and is intended to be used by the Pact Python client library to provide a Pythonic interface to Pact.
Warning
This module is not intended to be used directly by Pact users. Pact users should use the Pact Python client library instead. No guarantees are made about the stability of this module's API.
Developer Notes¶
This modules should provide the following only:
- Basic Enum classes
- Simple wrappers around functions, including the casting of input and output values between the high level Python types and the low level C types.
- Simple wrappers around some of the low-level types. Specifically designed to automatically handle the freeing of memory when the Python object is destroyed.
These low-level functions may then be combined into higher level classes and modules. Ideally, all code outside of this module should be written in pure Python and not worry about allocating or freeing memory.
During initial implementation, a lot of these functions will simply raise a
NotImplementedError
.
For those unfamiliar with CFFI, please make sure to read the CFFI documentation.
Handles¶
The Rust library exposes a number of handles to internal data structures. This is done to avoid exposing the internal implementation details of the library to users of the library, and avoid unnecessarily casting to and from possibly complicated structs.
In the Rust library, the handles are thin wrappers around integers, and unfortunately the CFFI interface sees this and automatically unwraps them, exposing the underlying integer. As a result, we must re-wrap the integer returned by the CFFI interface. This unfortunately means that we may be subject to changes in private implementation details upstream.
Freeing Memory¶
Python has a garbage collector, and as a result, we don't need to worry about manually freeing memory. Having said that, Python's garbace collector is only aware of Python objects, and not of any memory allocated by the Rust library.
To ensure that the memory allocated by the Rust library is freed, we must make
sure to define the
__del__
method to call the appropriate free function whenever the Python object is
destroyed.
Note that there are some rather subtle details as to when this is called, when
it may never be called, and what global variables are accessible. This is
explained in the documentation for __del__
above, and in Python's garbage
collection module.
Error Handling¶
The FFI function should handle all errors raised by the function call, and raise an appropriate Python exception. The exception should be raised using the appropriate Python exception class, and should be documented in the function's docstring.
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
AsynchronousMessage
¶
Consumer
¶
ExpressionValueType
¶
Bases: Enum
Expression Value Type.
Attributes¶
BOOLEAN = lib.ExpressionValueType_Boolean
class-attribute
instance-attribute
¶
DECIMAL = lib.ExpressionValueType_Decimal
class-attribute
instance-attribute
¶
INTEGER = lib.ExpressionValueType_Integer
class-attribute
instance-attribute
¶
NUMBER = lib.ExpressionValueType_Number
class-attribute
instance-attribute
¶
STRING = lib.ExpressionValueType_String
class-attribute
instance-attribute
¶
UNKNOWN = lib.ExpressionValueType_Unknown
class-attribute
instance-attribute
¶
Generator
¶
GeneratorCategory
¶
Bases: Enum
Generator Category.
Attributes¶
BODY = lib.GeneratorCategory_BODY
class-attribute
instance-attribute
¶
HEADER = lib.GeneratorCategory_HEADER
class-attribute
instance-attribute
¶
METADATA = lib.GeneratorCategory_METADATA
class-attribute
instance-attribute
¶
METHOD = lib.GeneratorCategory_METHOD
class-attribute
instance-attribute
¶
PATH = lib.GeneratorCategory_PATH
class-attribute
instance-attribute
¶
QUERY = lib.GeneratorCategory_QUERY
class-attribute
instance-attribute
¶
STATUS = lib.GeneratorCategory_STATUS
class-attribute
instance-attribute
¶
GeneratorCategoryIterator
¶
GeneratorKeyValuePair
¶
HttpRequest
¶
HttpResponse
¶
InteractionHandle(ref: int)
¶
Handle to a HTTP Interaction.
PARAMETER | DESCRIPTION |
---|---|
ref |
Reference to the Interaction Handle.
TYPE:
|
Source code in src/pact/v3/ffi.py
LevelFilter
¶
Bases: Enum
Level Filter.
Attributes¶
DEBUG = lib.LevelFilter_Debug
class-attribute
instance-attribute
¶
ERROR = lib.LevelFilter_Error
class-attribute
instance-attribute
¶
INFO = lib.LevelFilter_Info
class-attribute
instance-attribute
¶
OFF = lib.LevelFilter_Off
class-attribute
instance-attribute
¶
TRACE = lib.LevelFilter_Trace
class-attribute
instance-attribute
¶
WARN = lib.LevelFilter_Warn
class-attribute
instance-attribute
¶
MatchingRule
¶
MatchingRuleCategory
¶
Bases: Enum
Matching Rule Category.
Attributes¶
BODY = lib.MatchingRuleCategory_BODY
class-attribute
instance-attribute
¶
CONTENST = lib.MatchingRuleCategory_CONTENTS
class-attribute
instance-attribute
¶
HEADER = lib.MatchingRuleCategory_HEADER
class-attribute
instance-attribute
¶
METADATA = lib.MatchingRuleCategory_METADATA
class-attribute
instance-attribute
¶
METHOD = lib.MatchingRuleCategory_METHOD
class-attribute
instance-attribute
¶
PATH = lib.MatchingRuleCategory_PATH
class-attribute
instance-attribute
¶
QUERY = lib.MatchingRuleCategory_QUERY
class-attribute
instance-attribute
¶
STATUS = lib.MatchingRuleCategory_STATUS
class-attribute
instance-attribute
¶
MatchingRuleCategoryIterator
¶
MatchingRuleDefinitionResult
¶
MatchingRuleIterator
¶
MatchingRuleKeyValuePair
¶
MatchingRuleResult
¶
Message
¶
MessageContents
¶
MessageHandle
¶
MessageMetadataIterator
¶
MessageMetadataPair
¶
MessagePact
¶
MessagePactHandle
¶
MessagePactMessageIterator
¶
MessagePactMetadataIterator
¶
MessagePactMetadataTriple
¶
Mismatch
¶
Mismatches
¶
MismatchesIterator
¶
OwnedString(ptr: cffi.FFI.CData)
¶
Bases: str
A string that owns its own memory.
This is used to ensure that the memory is freed when the string is destroyed.
As this is subclassed from str
, it can be used in place of a normal string
in most cases.
PARAMETER | DESCRIPTION |
---|---|
ptr |
CFFI data structure.
TYPE:
|
Source code in src/pact/v3/ffi.py
Pact
¶
PactHandle(ref: int)
¶
Handle to a Pact.
PARAMETER | DESCRIPTION |
---|---|
ref |
Rust library reference to the Pact Handle.
TYPE:
|
Source code in src/pact/v3/ffi.py
PactInteraction
¶
PactInteractionIterator(ptr: cffi.FFI.CData)
¶
Iterator over a Pact's interactions.
Interactions encompasses all types of interactions, including HTTP interactions and messages.
PARAMETER | DESCRIPTION |
---|---|
ptr |
CFFI data structure.
TYPE:
|
Source code in src/pact/v3/ffi.py
PactMessageIterator(ptr: cffi.FFI.CData)
¶
Iterator over a Pact's asynchronous messages.
PARAMETER | DESCRIPTION |
---|---|
ptr |
CFFI data structure.
TYPE:
|
Source code in src/pact/v3/ffi.py
PactServerHandle(ref: int)
¶
Handle to a Pact Server.
This does not have an exact correspondance in the Rust library. It is used to manage the lifecycle of the mock server.
Implementation Notes¶
The Rust library uses the port number as a unique identifier, in much the same was as it uses a wrapped integer for the Pact handle.
PARAMETER | DESCRIPTION |
---|---|
ref |
Rust library reference to the Pact Server.
TYPE:
|
Source code in src/pact/v3/ffi.py
PactSpecification
¶
Bases: Enum
Pact Specification.
Attributes¶
UNKNOWN = lib.PactSpecification_Unknown
class-attribute
instance-attribute
¶
V1 = lib.PactSpecification_V1
class-attribute
instance-attribute
¶
V1_1 = lib.PactSpecification_V1_1
class-attribute
instance-attribute
¶
V2 = lib.PactSpecification_V2
class-attribute
instance-attribute
¶
V3 = lib.PactSpecification_V3
class-attribute
instance-attribute
¶
V4 = lib.PactSpecification_V4
class-attribute
instance-attribute
¶
Functions¶
from_str(version: str) -> PactSpecification
classmethod
¶
Instantiate a Pact Specification from a string.
This method is case-insensitive, and allows for the version to be specified with or without a leading "V", and with either a dot or an underscore as the separator.
PARAMETER | DESCRIPTION |
---|---|
version |
The version of the Pact Specification.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
PactSpecification
|
The Pact Specification. |
Source code in src/pact/v3/ffi.py
PactSyncHttpIterator(ptr: cffi.FFI.CData)
¶
Iterator over a Pact's synchronous HTTP interactions.
PARAMETER | DESCRIPTION |
---|---|
ptr |
CFFI data structure.
TYPE:
|
Source code in src/pact/v3/ffi.py
PactSyncMessageIterator(ptr: cffi.FFI.CData)
¶
Iterator over a Pact's synchronous messages.
PARAMETER | DESCRIPTION |
---|---|
ptr |
CFFI data structure.
TYPE:
|
Source code in src/pact/v3/ffi.py
Provider
¶
ProviderState
¶
ProviderStateIterator
¶
ProviderStateParamIterator
¶
ProviderStateParamPair
¶
StringResult(cdata: cffi.FFI.CData)
¶
String result.
PARAMETER | DESCRIPTION |
---|---|
cdata |
CFFI data structure.
TYPE:
|
Source code in src/pact/v3/ffi.py
Attributes¶
is_failed: bool
property
¶
Whether the result is an error.
is_ok: bool
property
¶
Whether the result is ok.
text: str
property
¶
The text of the result.
Functions¶
raise_exception() -> None
¶
Raise an exception with the text of the result.
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the result is an error. |
SynchronousHttp
¶
SynchronousMessage
¶
VerifierHandle(ref: cffi.FFI.CData)
¶
Handle to a Verifier.
PARAMETER | DESCRIPTION |
---|---|
ref |
Rust library reference to the Verifier Handle.
TYPE:
|
Source code in src/pact/v3/ffi.py
Functions¶
add_text_comment(interaction: InteractionHandle, comment: str) -> None
¶
Add a text comment to the interaction.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Interaction handle to set the comments for.
TYPE:
|
comment |
Comment value. This is a regular string value.
TYPE:
|
Source code in src/pact/v3/ffi.py
async_message_delete(message: AsynchronousMessage) -> None
¶
Destroy the AsynchronousMessage
being pointed to.
Rust pactffi_async_message_delete
Source code in src/pact/v3/ffi.py
async_message_get_contents(message: AsynchronousMessage) -> MessageContents
¶
Get the message contents of an AsynchronousMessage
as a MessageContents
pointer.
Rust
pactffi_async_message_get_contents
Safety¶
The data pointed to by the pointer this function returns will be deleted when the message is deleted. Trying to use if after the message is deleted will result in undefined behaviour.
Error Handling¶
If the message is NULL, returns NULL.
Source code in src/pact/v3/ffi.py
async_message_get_contents_bin(message: AsynchronousMessage) -> str
¶
Get the contents of an AsynchronousMessage
as bytes.
Rust
pactffi_async_message_get_contents_bin
Safety¶
The number of bytes in the buffer will be returned by
pactffi_async_message_get_contents_length
. It is safe to use the pointer
while the message is not deleted or changed. Using the pointer after the
message is mutated or deleted may lead to undefined behaviour.
Error Handling¶
If the message is NULL, returns NULL. If the body of the message is missing, then this function also returns NULL.
Source code in src/pact/v3/ffi.py
async_message_get_contents_length(message: AsynchronousMessage) -> int
¶
Get the length of the contents of a AsynchronousMessage
.
Rust
pactffi_async_message_get_contents_length
Safety¶
This function is safe.
Error Handling¶
If the message is NULL, returns 0. If the body of the request is missing, then this function also returns 0.
Source code in src/pact/v3/ffi.py
async_message_get_contents_str(message: AsynchronousMessage) -> str
¶
Get the message contents of an AsynchronousMessage
in string form.
Rust pactffi_async_message_get_contents_str
Safety¶
The returned string must be deleted with pactffi_string_delete
.
The returned string can outlive the message.
Error Handling¶
If the message is NULL, returns NULL. If the body of the message is missing, then this function also returns NULL. This means there's no mechanism to differentiate with this function call alone between a NULL message and a missing message body.
Source code in src/pact/v3/ffi.py
async_message_get_description(message: AsynchronousMessage) -> str
¶
Get a copy of the description.
Rust
pactffi_async_message_get_description
Safety¶
The returned string must be deleted with pactffi_string_delete
.
Since it is a copy, the returned string may safely outlive the
AsynchronousMessage
.
Errors¶
On failure, this function will return a NULL pointer.
This function may fail if the Rust string contains embedded null ('\0') bytes.
Source code in src/pact/v3/ffi.py
async_message_get_provider_state(message: AsynchronousMessage, index: int) -> ProviderState
¶
Get a copy of the provider state at the given index from this message.
Rust
pactffi_async_message_get_provider_state
Safety¶
The returned structure must be deleted with provider_state_delete
.
Since it is a copy, the returned structure may safely outlive the
AsynchronousMessage
.
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.
Source code in src/pact/v3/ffi.py
async_message_get_provider_state_iter(message: AsynchronousMessage) -> ProviderStateIterator
¶
Get an iterator over provider states.
Rust pactffi_async_message_get_provider_state_iter
Safety¶
The underlying data must not change during iteration.
Error Handling¶
Returns NULL if an error occurs.
Source code in src/pact/v3/ffi.py
async_message_new() -> AsynchronousMessage
¶
Get a mutable pointer to a newly-created default message on the heap.
Rust pactffi_async_message_new
Safety¶
This function is safe.
Error Handling¶
Returns NULL on error.
Source code in src/pact/v3/ffi.py
async_message_set_contents_bin(message: AsynchronousMessage, contents: str, len: int, content_type: str) -> None
¶
Sets the contents of the message as an array of bytes.
Rust
pactffi_async_message_set_contents_bin
message
- the message to set the contents forcontents
- pointer to contents to copy fromlen
- number of bytes to copy from the contents pointercontent_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.
Source code in src/pact/v3/ffi.py
async_message_set_contents_str(message: AsynchronousMessage, contents: str, content_type: str) -> None
¶
Sets the contents of the message as a string.
Rust
pactffi_async_message_set_contents_str
message
- the message to set the contents forcontents
- 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.
Source code in src/pact/v3/ffi.py
async_message_set_description(message: AsynchronousMessage, description: str) -> int
¶
Write the description
field on the AsynchronousMessage
.
Rust pactffi_async_message_set_description
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.
Source code in src/pact/v3/ffi.py
check_regex(regex: str, example: str) -> bool
¶
Checks that the example string matches the given regex.
Safety¶
Both the regex and example pointers must be valid pointers to NULL-terminated strings. Invalid pointers will result in undefined behaviour.
Source code in src/pact/v3/ffi.py
cleanup_mock_server(mock_server_handle: PactServerHandle) -> None
¶
External interface to cleanup a mock server.
This function will try terminate the mock server with the given port number and cleanup any memory allocated for it.
Rust
pactffi_cleanup_mock_server
PARAMETER | DESCRIPTION |
---|---|
mock_server_handle |
Handle to the mock server to cleanup.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the mock server could not be cleaned up. |
Source code in src/pact/v3/ffi.py
cleanup_plugins(pact: PactHandle) -> None
¶
Decrement the access count on any plugins that are loaded for the Pact.
This will shutdown any plugins that are no longer required (access count is zero).
Source code in src/pact/v3/ffi.py
consumer_get_name(consumer: Consumer) -> str
¶
Get a copy of this consumer's name.
Rust pactffi_consumer_get_name
The copy must be deleted with pactffi_string_delete
.
Usage¶
// Assuming `file_name` and `json_str` are already defined.
MessagePact *message_pact = pactffi_message_pact_new_from_json(file_name, json_str);
if (message_pact == NULLPTR) {
// handle error.
}
Consumer *consumer = pactffi_message_pact_get_consumer(message_pact);
if (consumer == NULLPTR) {
// handle error.
}
char *name = pactffi_consumer_get_name(consumer);
if (name == NULL) {
// handle error.
}
printf("%s\n", name);
pactffi_string_delete(name);
Errors¶
This function will fail if it is passed a NULL pointer, or the Rust string contains an embedded NULL byte. In the case of error, a NULL pointer will be returned.
Source code in src/pact/v3/ffi.py
create_mock_server(pact_str: str, addr_str: str, *, tls: bool) -> int
¶
[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.
Rust
pactffi_create_mock_server
pact_str
- Pact JSONaddr_str
- Address to bind to in the form name:port (i.e. 127.0.0.1:80)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 | A null pointer was received |
-2 | The pact JSON could not be parsed |
-3 | The mock server could not be started |
-4 | The method panicked |
-5 | The address is not valid |
-6 | Could not create the TLS configuration with the self-signed certificate |
Source code in src/pact/v3/ffi.py
create_mock_server_for_pact(pact: PactHandle, addr_str: str, *, tls: bool) -> int
¶
[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.
Rust
pactffi_create_mock_server_for_pact
pact
- Handle to a Pact model created with created withpactffi_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. 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 |
-6 | Could not create the TLS configuration with the self-signed certificate |
Source code in src/pact/v3/ffi.py
create_mock_server_for_transport(pact: PactHandle, addr: str, port: int, transport: str, transport_config: str | None) -> PactServerHandle
¶
Create a mock server for the provided Pact handle and transport.
Rust
pactffi_create_mock_server_for_transport
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to the Pact model.
TYPE:
|
addr |
The address to bind to.
TYPE:
|
port |
The port number to bind to. A value of zero will result in the operating system allocating an available port.
TYPE:
|
transport |
The transport to use (i.e. http, https, grpc). The underlying Pact library will interpret this, typically in a case-sensitive way.
TYPE:
|
transport_config |
Configuration to be passed to the transport. This must be a valid
JSON string, or
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
PactServerHandle
|
A handle to the mock server. |
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the mock server could not be created. The error message will contain details of the error. |
Source code in src/pact/v3/ffi.py
4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 |
|
enable_ansi_support() -> None
¶
Enable ANSI coloured output on Windows.
On non-Windows platforms, this function is a no-op.
Rust
pactffi_enable_ansi_support
Safety¶
This function is safe.
Source code in src/pact/v3/ffi.py
fetch_log_buffer(log_id: str) -> str
¶
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 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).
Returns a NULL pointer if the buffer can't be fetched. This can occur is there is not sufficient memory to make a copy of the contents or the buffer contains non-UTF-8 characters.
Safety¶
This function will fail if the log_id pointer is invalid or does not point to a NULL terminated string.
Source code in src/pact/v3/ffi.py
free_message_pact_handle(pact: MessagePactHandle) -> int
¶
Delete a Pact handle and free the resources used by it.
Rust
pactffi_free_message_pact_handle
Error Handling¶
On failure, this function will return a positive integer value.
1
- The handle is not valid or does not refer to a valid Pact. Could be that it was previously deleted.
Source code in src/pact/v3/ffi.py
free_pact_handle(pact: PactHandle) -> None
¶
Delete a Pact handle and free the resources used by it.
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the handle could not be freed. |
Source code in src/pact/v3/ffi.py
free_string(s: str) -> None
¶
[DEPRECATED] Frees the memory allocated to a string by another function.
This function is deprecated. Use pactffi_string_delete
instead.
Safety¶
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.
Source code in src/pact/v3/ffi.py
generate_datetime_string(format: str) -> StringResult
¶
Generates a datetime value from the provided format string.
This uses the current system date and time NOTE: The memory for the returned
string needs to be freed with the pactffi_string_delete
function
Rust
pactffi_generate_datetime_string
Safety¶
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.
Source code in src/pact/v3/ffi.py
generate_regex_value(regex: str) -> StringResult
¶
Generates an example string based on the provided regex.
NOTE: The memory for the returned string needs to be freed with the
pactffi_string_delete
function.
Rust
pactffi_generate_regex_value
Safety¶
The regex pointer must be a valid pointer to a NULL-terminated string. Invalid pointers will result in undefined behaviour.
Source code in src/pact/v3/ffi.py
generator_generate_integer(generator: Generator, context_json: str) -> int
¶
Generate an integer value using the provided generator.
An optional JSON payload containing any generator context can be given. The
context value is used for generators like ProviderStateGenerator
(which
should be the values returned from the Provider State callback function).
Rust
pactffi_generator_generate_integer
If anything goes wrong or the generator is not a type that can generate an integer value, it will return a zero value.
Source code in src/pact/v3/ffi.py
generator_generate_string(generator: Generator, context_json: str) -> str
¶
Generate a string value using the provided generator.
An optional JSON payload containing any generator context ca be given. The
context value is used for generators like MockServerURL
(which should
contain details about the running mock server) and ProviderStateGenerator
(which should be the values returned from the Provider State callback
function).
Rust
pactffi_generator_generate_string
If anything goes wrong, it will return a NULL pointer.
Source code in src/pact/v3/ffi.py
generator_to_json(generator: Generator) -> str
¶
Get the JSON form of the generator.
Rust
pactffi_generator_to_json
The returned string must be deleted with pactffi_string_delete
.
Safety¶
This function will fail if it is passed a NULL pointer, or the owner of the generator has been deleted.
Source code in src/pact/v3/ffi.py
generators_iter_delete(iter: GeneratorCategoryIterator) -> None
¶
Free the iterator when you're done using it.
Rust
pactffi_generators_iter_delete
Source code in src/pact/v3/ffi.py
generators_iter_next(iter: GeneratorCategoryIterator) -> GeneratorKeyValuePair
¶
Get the next path and generator out of the iterator, if possible.
Rust
pactffi_generators_iter_next
The returned pointer must be deleted with
pactffi_generator_iter_pair_delete
.
Safety¶
The underlying data is owned by the GeneratorKeyValuePair
, so is always
safe to use.
Error Handling¶
If no further data is present, returns NULL.
Source code in src/pact/v3/ffi.py
generators_iter_pair_delete(pair: GeneratorKeyValuePair) -> None
¶
Free a pair of key and value returned from pactffi_generators_iter_next
.
Rust
pactffi_generators_iter_pair_delete
Source code in src/pact/v3/ffi.py
get_error_message(length: int = 1024) -> str | None
¶
Provide the error message from LAST_ERROR
to the calling C code.
Rust
pactffi_get_error_message
This function should be called after any other function in the pact_matching FFI indicates a failure with its own error message, if the caller wants to get more context on why the error happened.
Do note that this error-reporting mechanism only reports the top-level error message, not any source information embedded in the original Rust error type. If you want more detailed information for debugging purposes, use the logging interface.
PARAMETER | DESCRIPTION |
---|---|
length |
The length of the buffer to allocate for the error message. If the error message is longer than this, it will be truncated.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str | None
|
A string containing the error message, or None if there is no error |
str | None
|
message. |
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the error message could not be retrieved. |
Source code in src/pact/v3/ffi.py
get_tls_ca_certificate() -> OwnedString
¶
Fetch the CA Certificate used to generate the self-signed certificate.
Rust
pactffi_get_tls_ca_certificate
NOTE: The string for the result is allocated on the heap, and will have to be freed by the caller using pactffi_string_delete.
Errors¶
An empty string indicates an error reading the pem file.
Source code in src/pact/v3/ffi.py
given(interaction: InteractionHandle, description: str) -> None
¶
Adds a provider state to the Interaction.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
description |
The provider state description. It needs to be unique.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the provider state could not be specified. |
Source code in src/pact/v3/ffi.py
given_with_param(interaction: InteractionHandle, description: str, name: str, value: str) -> None
¶
Adds a parameter key and value to a provider state to the Interaction.
If the provider state does not exist, a new one will be created, otherwise the parameter will be merged into the existing one. The parameter value will be parsed as JSON.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
description |
The provider state description.
TYPE:
|
name |
Parameter name.
TYPE:
|
value |
Parameter value as JSON.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the interaction state could not be updated. |
Source code in src/pact/v3/ffi.py
given_with_params(interaction: InteractionHandle, description: str, params: str) -> None
¶
Adds a provider state to the Interaction.
If the params is not an JSON object, it will add it as a single parameter
with a value
key.
Rust
pactffi_given_with_params
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
description |
The provider state description.
TYPE:
|
params |
Parameter values as a JSON fragment.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the interaction state could not be updated. |
Errors¶
Returns EXIT_FAILURE (1) if the interaction or Pact can't be modified (i.e. the mock server for it has already started).
Returns 2 and sets the error message (which can be retrieved with
pactffi_get_error_message
) if the parameter values con't be parsed as
JSON.
Returns 3 if any of the C strings are not valid.
Source code in src/pact/v3/ffi.py
handle_get_pact_spec_version(handle: PactHandle) -> PactSpecification
¶
Fetches the Pact specification version for the given Pact model.
Rust
pactffi_handle_get_pact_spec_version
PARAMETER | DESCRIPTION |
---|---|
handle |
Handle to a Pact model.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
PactSpecification
|
The spec version for the Pact model. |
Source code in src/pact/v3/ffi.py
init(log_env_var: str) -> None
¶
Initialise the mock server library.
This can provide an environment variable name to use to set the log levels. This function should only be called once, as it tries to install a global tracing subscriber.
Safety¶
log_env_var must be a valid NULL terminated UTF-8 string.
Source code in src/pact/v3/ffi.py
init_with_log_level(level: str = 'INFO') -> None
¶
Initialises logging, and sets the log level explicitly.
This function should only be called once, as it tries to install a global tracing subscriber.
Rust
pactffi_init_with_log_level
PARAMETER | DESCRIPTION |
---|---|
level |
One of TRACE, DEBUG, INFO, WARN, ERROR, NONE/OFF. Case-insensitive.
TYPE:
|
Safety¶
Exported functions are inherently unsafe.
Source code in src/pact/v3/ffi.py
interaction_contents(interaction: InteractionHandle, part: InteractionPart, content_type: str, contents: str) -> None
¶
Setup the interaction part using a plugin.
The contents is a JSON string that will be passed on to the plugin to configure the interaction part. Refer to the plugin documentation on the format of the JSON contents.
Rust
pactffi_interaction_contents
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the interaction to configure.
TYPE:
|
part |
The part of the interaction to configure (request or response). It is ignored for messages.
TYPE:
|
content_type |
Mime type of the contents.
TYPE:
|
contents |
JSON contents that gets passed to the plugin.
TYPE:
|
Source code in src/pact/v3/ffi.py
interaction_test_name(interaction: InteractionHandle, test_name: str) -> None
¶
Sets the test name annotation for the interaction.
This allows capturing the name of the test as metadata. This can only be used with V4 interactions.
Rust
pactffi_interaction_test_name
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
test_name |
The test name to set.
TYPE:
|
Safety¶
The test name parameter must be a valid pointer to a NULL terminated string.
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the test name can not be set. |
Error Handling¶
If the test name can not be set, this will return a positive value.
1
- Function panicked. Error message will be available by callingpactffi_get_error_message
.2
- Handle was not valid.3
- Mock server was already started and the integration can not be modified.4
- Not a V4 interaction.
Source code in src/pact/v3/ffi.py
log_message(message: str, log_level: LevelFilter | str = LevelFilter.ERROR, source: str | None = None) -> None
¶
Log using the shared core logging facility.
This is useful for callers to have a single set of logs.
PARAMETER | DESCRIPTION |
---|---|
message |
The contents written to the log
TYPE:
|
log_level |
The verbosity at which this message should be logged.
TYPE:
|
source |
The source of the log, such as the class, module or caller.
TYPE:
|
Source code in src/pact/v3/ffi.py
log_to_buffer(level_filter: LevelFilter | str = LevelFilter.ERROR) -> None
¶
Convenience function to direct all logging to a task local memory buffer.
Source code in src/pact/v3/ffi.py
log_to_file(file_name: str, level_filter: LevelFilter) -> int
¶
Convenience function to direct all logging to a file.
Safety¶
This function will fail if the file_name pointer is invalid or does not point to a NULL terminated string.
Source code in src/pact/v3/ffi.py
log_to_stderr(level_filter: LevelFilter | str = LevelFilter.ERROR) -> None
¶
Convenience function to direct all logging to stderr.
PARAMETER | DESCRIPTION |
---|---|
level_filter |
The level of logs to filter to. If a string is given, it must match
one of the
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If there was an error setting the logger. |
Source code in src/pact/v3/ffi.py
log_to_stdout(level_filter: LevelFilter) -> int
¶
Convenience function to direct all logging to stdout.
Source code in src/pact/v3/ffi.py
logger_apply() -> int
¶
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.
This function will install a global tracing subscriber. Any attempts to
modify the logger after the call to logger_apply
will fail.
Source code in src/pact/v3/ffi.py
logger_attach_sink(sink_specifier: str, level_filter: LevelFilter) -> int
¶
Attach an additional sink to the thread-local logger.
Rust
pactffi_logger_attach_sink
This logger does nothing until pactffi_logger_apply
has been called.
Types of sinks can be specified:
- stdout (
pactffi_logger_attach_sink("stdout", LevelFilter_Info)
) - stderr (
pactffi_logger_attach_sink("stderr", LevelFilter_Debug)
) - file w/ file path (
pactffi_logger_attach_sink("file /some/file/path", LevelFilter_Trace)
) - buffer (
pactffi_logger_attach_sink("buffer", LevelFilter_Debug)
)
Usage¶
Error Handling¶
The return error codes are as follows:
-1
: Can't set logger (applying the logger failed, perhaps because one is applied already).-2
: No logger has been initialized (callpactffi_logger_init
before any other log function).-3
: The sink specifier was not UTF-8 encoded.-4
: The sink type specified is not a known type (known types: "stdout", "stderr", or "file /some/path").-5
: No file path was specified in a file-type sink specification.-6
: Opening a sink to the specified file path failed (check permissions).
Safety¶
This function checks the validity of the passed-in sink specifier, and errors out if the specifier isn't valid UTF-8. Passing in an invalid or NULL pointer will result in undefined behaviour.
Source code in src/pact/v3/ffi.py
logger_init() -> None
¶
Initialize the FFI logger with no sinks.
This initialized logger does nothing until pactffi_logger_apply
has been called.
Usage¶
Safety¶
This function is always safe to call.
Source code in src/pact/v3/ffi.py
match_message(msg_1: Message, msg_2: Message) -> Mismatches
¶
Match a pair of messages, producing a collection of mismatches.
If the messages match, the returned collection will be empty.
Source code in src/pact/v3/ffi.py
matcher_definition_delete(definition: MatchingRuleDefinitionResult) -> None
¶
Frees the memory used by the result of parsing the matching definition expression.
Rust pactffi_matcher_definition_delete
Source code in src/pact/v3/ffi.py
matcher_definition_error(definition: MatchingRuleDefinitionResult) -> str
¶
Returns any error message from parsing a matching definition expression.
If there is no error, it will return a NULL pointer, otherwise returns the
error message as a NULL-terminated string. The returned string must be freed
using the pactffi_string_delete
function once done with it.
Rust
pactffi_matcher_definition_error
Source code in src/pact/v3/ffi.py
matcher_definition_generator(definition: MatchingRuleDefinitionResult) -> Generator
¶
Returns the generator from parsing a matching definition expression.
If there was an error or there is no associated generator, it will return a NULL pointer, otherwise returns the generator as a pointer.
Rust
pactffi_matcher_definition_generator
The generator pointer will be a valid pointer as long as
pactffi_matcher_definition_delete
has not been called on the definition.
Using the generator pointer after the definition has been deleted will
result in undefined behaviour.
Source code in src/pact/v3/ffi.py
matcher_definition_iter(definition: MatchingRuleDefinitionResult) -> MatchingRuleIterator
¶
Returns an iterator over the matching rules from the parsed definition.
The iterator needs to be deleted with the
pactffi_matching_rule_iter_delete
function once done with it.
Rust
pactffi_matcher_definition_iter
If there was an error parsing the expression, this function will return a NULL pointer.
Source code in src/pact/v3/ffi.py
matcher_definition_value(definition: MatchingRuleDefinitionResult) -> str
¶
Returns the value from parsing a matching definition expression.
If there was an error, it will return a NULL pointer, otherwise returns the
value as a NULL-terminated string. The returned string must be freed using
the pactffi_string_delete
function once done with it.
Rust
pactffi_matcher_definition_value
Note that different expressions values can have types other than a string.
Use pactffi_matcher_definition_value_type
to get the actual type of the
value. This function will always return the string representation of the
value.
Source code in src/pact/v3/ffi.py
matcher_definition_value_type(definition: MatchingRuleDefinitionResult) -> ExpressionValueType
¶
Returns the type of the value from parsing a matching definition expression.
If there was an error parsing the expression, it will return Unknown.
Rust
pactffi_matcher_definition_value_type
Source code in src/pact/v3/ffi.py
matches_binary_value(matching_rule: MatchingRule, expected_value: str, expected_value_len: int, actual_value: str, actual_value_len: int, cascaded: int) -> OwnedString
¶
Determines if the binary value matches the given matching rule.
If the value matches OK, will return a NULL pointer. If the value does not
match, will return a error message as a NULL terminated string. The error
message pointer will need to be deleted with the pactffi_string_delete
function once it is no longer required.
Rust
pactffi_matches_binary_value
- matching_rule - pointer to a matching rule
- expected_value - value we expect to get
- expected_value_len - length of the expected value bytes
- actual_value - value to match
- actual_value_len - length of the actual value bytes
- cascaded - if the matching rule has been cascaded from a parent. 0 == false, 1 == true
Safety¶
The matching rule, expected value and actual value pointers must be a valid pointers. expected_value_len and actual_value_len must contain the number of bytes that the value pointers point to. Passing invalid lengths can lead to undefined behaviour.
Source code in src/pact/v3/ffi.py
matches_bool_value(matching_rule: MatchingRule, expected_value: int, actual_value: int, cascaded: int) -> OwnedString
¶
Determines if the boolean value matches the given matching rule.
If the value matches OK, will return a NULL pointer. If the value does not
match, will return a error message as a NULL terminated string. The error
message pointer will need to be deleted with the pactffi_string_delete
function once it is no longer required.
Rust
pactffi_matches_bool_value
- matching_rule - pointer to a matching rule
- expected_value - value we expect to get, 0 == false and 1 == true
- actual_value - value to match, 0 == false and 1 == true
- cascaded - if the matching rule has been cascaded from a parent. 0 == false, 1 == true
Safety¶
The matching rule pointer must be a valid pointer.
Source code in src/pact/v3/ffi.py
matches_f64_value(matching_rule: MatchingRule, expected_value: float, actual_value: float, cascaded: int) -> OwnedString
¶
Determines if the floating point value matches the given matching rule.
If the value matches OK, will return a NULL pointer. If the value does not
match, will return a error message as a NULL terminated string. The error
message pointer will need to be deleted with the pactffi_string_delete
function once it is no longer required.
Rust
pactffi_matches_f64_value
- matching_rule - pointer to a matching rule
- expected_value - value we expect to get
- actual_value - value to match
- cascaded - if the matching rule has been cascaded from a parent. 0 == false, 1 == true
Safety¶
The matching rule pointer must be a valid pointer.
Source code in src/pact/v3/ffi.py
matches_i64_value(matching_rule: MatchingRule, expected_value: int, actual_value: int, cascaded: int) -> OwnedString
¶
Determines if the signed integer value matches the given matching rule.
If the value matches OK, will return a NULL pointer. If the value does not
match, will return a error message as a NULL terminated string. The error
message pointer will need to be deleted with the pactffi_string_delete
function once it is no longer required.
Rust
pactffi_matches_i64_value
- matching_rule - pointer to a matching rule
- expected_value - value we expect to get
- actual_value - value to match
- cascaded - if the matching rule has been cascaded from a parent. 0 == false, 1 == true
Safety¶
The matching rule pointer must be a valid pointer.
Source code in src/pact/v3/ffi.py
matches_json_value(matching_rule: MatchingRule, expected_value: str, actual_value: str, cascaded: int) -> OwnedString
¶
Determines if the JSON value matches the given matching rule.
If the value matches OK, will return a NULL pointer. If the value does not
match, will return a error message as a NULL terminated string. The error
message pointer will need to be deleted with the pactffi_string_delete
function once it is no longer required.
Rust
pactffi_matches_json_value
- matching_rule - pointer to a matching rule
- expected_value - value we expect to get as a NULL terminated string
- actual_value - value to match as a NULL terminated string
- cascaded - if the matching rule has been cascaded from a parent. 0 == false, 1 == true
Safety¶
The matching rule pointer must be a valid pointer, and the value parameters must be valid pointers to a NULL terminated strings.
Source code in src/pact/v3/ffi.py
matches_string_value(matching_rule: MatchingRule, expected_value: str, actual_value: str, cascaded: int) -> OwnedString
¶
Determines if the string value matches the given matching rule.
If the value matches OK, will return a NULL pointer. If the value does not
match, will return a error message as a NULL terminated string. The error
message pointer will need to be deleted with the pactffi_string_delete
function once it is no longer required.
Rust
pactffi_matches_string_value
- matching_rule - pointer to a matching rule
- expected_value - value we expect to get as a NULL terminated string
- actual_value - value to match as a NULL terminated string
- cascaded - if the matching rule has been cascaded from a parent. 0 == false, 1 == true
Safety¶
The matching rule pointer must be a valid pointer, and the value parameters must be valid pointers to a NULL terminated strings.
Source code in src/pact/v3/ffi.py
matches_u64_value(matching_rule: MatchingRule, expected_value: int, actual_value: int, cascaded: int) -> OwnedString
¶
Determines if the unsigned integer value matches the given matching rule.
If the value matches OK, will return a NULL pointer. If the value does not
match, will return a error message as a NULL terminated string. The error
message pointer will need to be deleted with the pactffi_string_delete
function once it is no longer required.
Rust
pactffi_matches_u64_value
- matching_rule - pointer to a matching rule
- expected_value - value we expect to get
- actual_value - value to match
- cascaded - if the matching rule has been cascaded from a parent. 0 == false, 1 == true
Safety¶
The matching rule pointer must be a valid pointer.
Source code in src/pact/v3/ffi.py
matching_rule_id(rule_result: MatchingRuleResult) -> int
¶
Return the ID of the matching rule.
The ID corresponds to the following rules:
Rule | ID |
---|---|
Equality | 1 |
Regex | 2 |
Type | 3 |
MinType | 4 |
MaxType | 5 |
MinMaxType | 6 |
Timestamp | 7 |
Time | 8 |
Date | 9 |
Include | 10 |
Number | 11 |
Integer | 12 |
Decimal | 13 |
Null | 14 |
ContentType | 15 |
ArrayContains | 16 |
Values | 17 |
Boolean | 18 |
StatusCode | 19 |
NotEmpty | 20 |
Semver | 21 |
EachKey | 22 |
EachValue | 23 |
Safety¶
This function is safe as long as the MatchingRuleResult pointer is a valid pointer and the iterator has not been deleted.
Source code in src/pact/v3/ffi.py
matching_rule_iter_delete(iter: MatchingRuleIterator) -> None
¶
Free the iterator when you're done using it.
Rust pactffi_matching_rule_iter_delete
Source code in src/pact/v3/ffi.py
matching_rule_iter_next(iter: MatchingRuleIterator) -> MatchingRuleResult
¶
Get the next matching rule or reference from the iterator.
As the values returned are owned by the iterator, they do not need to be deleted but will be cleaned up when the iterator is deleted.
Rust
pactffi_matching_rule_iter_next
Will return a NULL pointer when the iterator has advanced past the end of the list.
Safety¶
This function is safe.
Error Handling¶
This function will return a NULL pointer if passed a NULL pointer or if an error occurs.
Source code in src/pact/v3/ffi.py
matching_rule_pointer(rule_result: MatchingRuleResult) -> MatchingRule
¶
Returns the matching rule pointer for the matching rule.
Will return a NULL pointer if the matching rule result was a reference.
Rust
pactffi_matching_rule_pointer
Safety¶
This function is safe as long as the MatchingRuleResult pointer is a valid pointer and the iterator it came from has not been deleted.
Source code in src/pact/v3/ffi.py
matching_rule_reference_name(rule_result: MatchingRuleResult) -> str
¶
Return any matching rule reference to a attribute by name.
This is when the matcher should be configured to match the type of a structure. I.e.,
Rust
pactffi_matching_rule_reference_name
Will return a NULL pointer if the matching rule was not a reference.
Safety¶
This function is safe as long as the MatchingRuleResult pointer is a valid pointer and the iterator has not been deleted.
Source code in src/pact/v3/ffi.py
matching_rule_to_json(rule: MatchingRule) -> str
¶
Get the JSON form of the matching rule.
Rust
pactffi_matching_rule_to_json
The returned string must be deleted with pactffi_string_delete
.
Safety¶
This function will fail if it is passed a NULL pointer, or the iterator that owns the value of the matching rule has been deleted.
Source code in src/pact/v3/ffi.py
matching_rule_value(rule_result: MatchingRuleResult) -> str
¶
Returns the associated value for the matching rule.
If the matching rule does not have an associated value, will return a NULL pointer.
Rust
pactffi_matching_rule_value
The associated values for the rules are:
Rule | ID | VALUE |
---|---|---|
Equality | 1 | NULL |
Regex | 2 | Regex value |
Type | 3 | NULL |
MinType | 4 | Minimum value |
MaxType | 5 | Maximum value |
MinMaxType | 6 | "min:max" |
Timestamp | 7 | Format string |
Time | 8 | Format string |
Date | 9 | Format string |
Include | 10 | String value |
Number | 11 | NULL |
Integer | 12 | NULL |
Decimal | 13 | NULL |
Null | 14 | NULL |
ContentType | 15 | Content type |
ArrayContains | 16 | NULL |
Values | 17 | NULL |
Boolean | 18 | NULL |
StatusCode | 19 | NULL |
NotEmpty | 20 | NULL |
Semver | 21 | NULL |
EachKey | 22 | NULL |
EachValue | 23 | NULL |
Will return a NULL pointer if the matching rule was a reference or does not have an associated value.
Safety¶
This function is safe as long as the MatchingRuleResult pointer is a valid pointer and the iterator it came from has not been deleted.
Source code in src/pact/v3/ffi.py
matching_rules_iter_delete(iter: MatchingRuleCategoryIterator) -> None
¶
Free the iterator when you're done using it.
Rust
pactffi_matching_rules_iter_delete
Source code in src/pact/v3/ffi.py
matching_rules_iter_next(iter: MatchingRuleCategoryIterator) -> MatchingRuleKeyValuePair
¶
Get the next path and matching rule out of the iterator, if possible.
Rust
pactffi_matching_rules_iter_next
The returned pointer must be deleted with
pactffi_matching_rules_iter_pair_delete
.
Safety¶
The underlying data is owned by the MatchingRuleKeyValuePair
, so is always
safe to use.
Error Handling¶
If no further data is present, returns NULL.
Source code in src/pact/v3/ffi.py
matching_rules_iter_pair_delete(pair: MatchingRuleKeyValuePair) -> None
¶
Free a pair of key and value returned from message_metadata_iter_next
.
Rust
pactffi_matching_rules_iter_pair_delete
Source code in src/pact/v3/ffi.py
message_contents_get_contents_bin(contents: MessageContents) -> str
¶
Get the contents of a message as a pointer to an array of bytes.
Rust
pactffi_message_contents_get_contents_bin
Safety¶
The number of bytes in the buffer will be returned by
pactffi_message_contents_get_contents_length
. It is safe to use the
pointer while the message is not deleted or changed. Using the pointer after
the message is mutated or deleted may lead to undefined behaviour.
Error Handling¶
If the message is NULL, returns NULL. If the body of the message is missing, then this function also returns NULL.
Source code in src/pact/v3/ffi.py
message_contents_get_contents_length(contents: MessageContents) -> int
¶
Get the length of the message contents.
Rust pactffi_message_contents_get_contents_length
Safety¶
This function is safe.
Error Handling¶
If the message is NULL, returns 0. If the body of the message is missing, then this function also returns 0.
Source code in src/pact/v3/ffi.py
message_contents_get_contents_str(contents: MessageContents) -> str
¶
Get the message contents in string form.
Rust pactffi_message_contents_get_contents_str
Safety¶
The returned string must be deleted with pactffi_string_delete
.
The returned string can outlive the message.
Error Handling¶
If the message contents is NULL, returns NULL. If the body of the message is missing, then this function also returns NULL. This means there's no mechanism to differentiate with this function call alone between a NULL message and a missing message body.
Source code in src/pact/v3/ffi.py
message_contents_get_generators_iter(contents: MessageContents, category: GeneratorCategory) -> GeneratorCategoryIterator
¶
Get an iterator over the generators for a category of a message.
Rust
pactffi_message_contents_get_generators_iter
The returned pointer must be deleted with pactffi_generators_iter_delete
when done with it.
Safety¶
The iterator contains a copy of the data, so is safe to use when the message or message contents has been deleted.
Error Handling¶
On failure, this function will return a NULL pointer.
Source code in src/pact/v3/ffi.py
message_contents_get_matching_rule_iter(contents: MessageContents, category: MatchingRuleCategory) -> MatchingRuleCategoryIterator
¶
Get an iterator over the matching rules for a category of a message.
Rust
pactffi_message_contents_get_matching_rule_iter
The returned pointer must be deleted with
pactffi_matching_rules_iter_delete
when done with it.
Note that there could be multiple matching rules for the same key, so this iterator will sequentially return each rule with the same key.
For sample, given the following rules:
This iterator will return a sequence of 3 values:
("$.a", Type)
("$.b", Regex("\d+"))
("$.b", Number)
Safety¶
The iterator contains a copy of the data, so is safe to use when the message or message contents has been deleted.
Error Handling¶
On failure, this function will return a NULL pointer.
Source code in src/pact/v3/ffi.py
message_contents_get_metadata_iter(contents: MessageContents) -> MessageMetadataIterator
¶
Get an iterator over the metadata of a message.
Rust
pactffi_message_contents_get_metadata_iter
The returned pointer must be deleted with
pactffi_message_metadata_iter_delete
when done with it.
Safety¶
This iterator carries a pointer to the message contents, and must not outlive the message.
The message metadata also must not be modified during iteration. If it is, the old iterator must be deleted and a new iterator created.
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.
Source code in src/pact/v3/ffi.py
message_contents_set_contents_bin(contents: MessageContents, contents_bin: str, len: int, content_type: str) -> None
¶
Sets the contents of the message as an array of bytes.
Rust
pactffi_message_contents_set_contents_bin
message
- the message contents to set the contents forcontents_bin
- pointer to contents to copy fromlen
- number of bytes to copy from the contents pointercontent_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.
Source code in src/pact/v3/ffi.py
message_contents_set_contents_str(contents: MessageContents, contents_str: str, content_type: str) -> None
¶
Sets the contents of the message as a string.
Rust
pactffi_message_contents_set_contents_str
contents
- the message contents to set the contents forcontents_str
- 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 string 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.
Source code in src/pact/v3/ffi.py
message_delete(message: Message) -> None
¶
Destroy the Message
being pointed to.
message_expects_to_receive(message: MessageHandle, description: str) -> None
¶
Sets the description for the Message.
Rust
pactffi_message_expects_to_receive
description
- The message description. It needs to be unique for each message.
Source code in src/pact/v3/ffi.py
message_find_metadata(message: Message, key: str) -> str
¶
Get a copy of the metadata value indexed by key
.
Rust
pactffi_message_find_metadata
Safety¶
The returned string must be deleted with pactffi_string_delete
.
Since it is a copy, the returned string may safely outlive the Message
.
The returned pointer will be NULL if the metadata does not contain the given key, or if an error occurred.
Error Handling¶
On failure, this function will return a NULL pointer.
This function may fail if the provided key
string contains invalid UTF-8,
or if the Rust string contains embedded null ('\0') bytes.
Source code in src/pact/v3/ffi.py
message_get_contents(message: Message) -> OwnedString | None
¶
Get the contents of a Message
in string form.
Rust
pactffi_message_get_contents
Safety¶
The returned string must be deleted with pactffi_string_delete
and can
outlive the message. This function must only ever be called from a foreign
language. Calling it from a Rust function that has a Tokio runtime in its
call stack can result in a deadlock.
The returned string can outlive the message.
Error Handling¶
If the message is NULL, returns NULL. If the body of the message is missing, then this function also returns NULL. This means there's no mechanism to differentiate with this function call alone between a NULL message and a missing message body.
Source code in src/pact/v3/ffi.py
message_get_contents_bin(message: Message) -> str
¶
Get the contents of a Message
as a pointer to an array of bytes.
Rust
pactffi_message_get_contents_bin
Safety¶
The number of bytes in the buffer will be returned by
pactffi_message_get_contents_length
. It is safe to use the pointer while
the message is not deleted or changed. Using the pointer after the message
is mutated or deleted may lead to undefined behaviour.
Error Handling¶
If the message is NULL, returns NULL. If the body of the message is missing, then this function also returns NULL.
Source code in src/pact/v3/ffi.py
message_get_contents_length(message: Message) -> int
¶
Get the length of the contents of a Message
.
Rust
pactffi_message_get_contents_length
Safety¶
This function is safe.
Error Handling¶
If the message is NULL, returns 0. If the body of the message is missing, then this function also returns 0.
Source code in src/pact/v3/ffi.py
message_get_description(message: Message) -> OwnedString
¶
Get a copy of the description.
Rust
pactffi_message_get_description
Safety¶
The returned string must be deleted with pactffi_string_delete
.
Since it is a copy, the returned string may safely outlive the Message
.
Errors¶
On failure, this function will return a NULL pointer.
This function may fail if the Rust string contains embedded null ('\0') bytes.
Source code in src/pact/v3/ffi.py
message_get_metadata_iter(message: Message) -> MessageMetadataIterator
¶
Get an iterator over the metadata of a message.
Rust
pactffi_message_get_metadata_iter
Safety¶
This iterator carries a pointer to the message, and must not outlive the message.
The message metadata also must not be modified during iteration. If it is, the old iterator must be deleted and a new iterator created.
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.
Source code in src/pact/v3/ffi.py
message_get_provider_state(message: Message, index: int) -> ProviderState
¶
Get a copy of the provider state at the given index from this message.
Rust
pactffi_message_get_provider_state
Safety¶
The returned structure must be deleted with provider_state_delete
.
Since it is a copy, the returned structure may safely outlive the Message
.
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.
Source code in src/pact/v3/ffi.py
message_get_provider_state_iter(message: Message) -> ProviderStateIterator
¶
Get an iterator over provider states.
Rust
pactffi_message_get_provider_state_iter
Safety¶
The underlying data must not change during iteration.
Error Handling¶
Returns NULL if an error occurs.
Source code in src/pact/v3/ffi.py
message_given(message: MessageHandle, description: str) -> None
¶
Adds a provider state to the Interaction.
description
- The provider state description. It needs to be unique for each message
Source code in src/pact/v3/ffi.py
message_given_with_param(message: MessageHandle, description: str, name: str, value: str) -> None
¶
Adds a provider state to the Message with a parameter key and value.
Rust
pactffi_message_given_with_param
description
- The provider state description. It needs to be unique.name
- Parameter name.value
- Parameter value.
Source code in src/pact/v3/ffi.py
message_insert_metadata(message: Message, key: str, value: str) -> int
¶
Insert the (key
, value
) pair into this Message's metadata
HashMap.
Rust
pactffi_message_insert_metadata
Safety¶
This function returns an enum indicating the result; see the comments on HashMapInsertStatus for details.
Error Handling¶
This function may fail if the provided key
or value
strings contain
invalid UTF-8.
Source code in src/pact/v3/ffi.py
message_metadata_iter_delete(iter: MessageMetadataIterator) -> None
¶
Free the metadata iterator when you're done using it.
Rust
pactffi_message_metadata_iter_delete
Source code in src/pact/v3/ffi.py
message_metadata_iter_next(iter: MessageMetadataIterator) -> MessageMetadataPair
¶
Get the next key and value out of the iterator, if possible.
Rust
pactffi_message_metadata_iter_next
The returned pointer must be deleted with
pactffi_message_metadata_pair_delete
.
Safety¶
The underlying data must not change during iteration. This function must only ever be called from a foreign language. Calling it from a Rust function that has a Tokio runtime in its call stack can result in a deadlock.
Error Handling¶
If no further data is present, returns NULL.
Source code in src/pact/v3/ffi.py
message_metadata_pair_delete(pair: MessageMetadataPair) -> None
¶
Free a pair of key and value returned from message_metadata_iter_next
.
Rust
pactffi_message_metadata_pair_delete
Source code in src/pact/v3/ffi.py
message_new() -> Message
¶
Get a mutable pointer to a newly-created default message on the heap.
Safety¶
This function is safe.
Error Handling¶
Returns NULL on error.
Source code in src/pact/v3/ffi.py
message_new_from_body(body: str, content_type: str) -> Message
¶
Constructs a Message
from a body with a given content-type.
Rust
pactffi_message_new_from_body
Safety¶
This function is safe.
Error Handling¶
If the body or content type are invalid or not UTF-8 encoded, returns NULL.
Source code in src/pact/v3/ffi.py
message_new_from_json(index: int, json_str: str, spec_version: PactSpecification) -> Message
¶
Constructs a Message
from the JSON string.
Rust
pactffi_message_new_from_json
Safety¶
This function is safe.
Error Handling¶
If the JSON string is invalid or not UTF-8 encoded, returns a NULL.
Source code in src/pact/v3/ffi.py
message_pact_delete(message_pact: MessagePact) -> None
¶
Delete the MessagePact
being pointed to.
Rust
pactffi_message_pact_delete
Source code in src/pact/v3/ffi.py
message_pact_find_metadata(message_pact: MessagePact, key1: str, key2: str) -> str
¶
Get a copy of the metadata value indexed by key1
and key2
.
Rust
pactffi_message_pact_find_metadata
Safety¶
Since it is a copy, the returned string may safely outlive the Message
.
The returned string must be deleted with pactffi_string_delete
.
The returned pointer will be NULL if the metadata does not contain the given key, or if an error occurred.
Error Handling¶
On failure, this function will return a NULL pointer.
This function may fail if the provided key1
or key2
strings contains
invalid UTF-8, or if the Rust string contains embedded null ('\0') bytes.
Source code in src/pact/v3/ffi.py
message_pact_get_consumer(message_pact: MessagePact) -> Consumer
¶
Get a pointer to the Consumer struct inside the MessagePact.
This is a mutable borrow: The caller may mutate the Consumer through this pointer.
Rust
pactffi_message_pact_get_consumer
Safety¶
This function is safe.
Error Handling¶
This function will only fail if it is passed a NULL pointer. In the case of error, a NULL pointer will be returned.
Source code in src/pact/v3/ffi.py
message_pact_get_message_iter(message_pact: MessagePact) -> MessagePactMessageIterator
¶
Get an iterator over the messages of a message pact.
Rust
pactffi_message_pact_get_message_iter
Safety¶
This iterator carries a pointer to the message pact, and must not outlive the message pact.
The message pact messages also must not be modified during iteration. If they are, the old iterator must be deleted and a new iterator created.
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.
Source code in src/pact/v3/ffi.py
message_pact_get_metadata_iter(message_pact: MessagePact) -> MessagePactMetadataIterator
¶
Get an iterator over the metadata of a message pact.
Rust
pactffi_message_pact_get_metadata_iter
Safety¶
This iterator carries a pointer to the message pact, and must not outlive the message pact.
The message pact metadata also must not be modified during iteration. If it is, the old iterator must be deleted and a new iterator created.
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.
Source code in src/pact/v3/ffi.py
message_pact_get_provider(message_pact: MessagePact) -> Provider
¶
Get a pointer to the Provider struct inside the MessagePact.
This is a mutable borrow: The caller may mutate the Provider through this pointer.
Rust
pactffi_message_pact_get_provider
Safety¶
This function is safe.
Error Handling¶
This function will only fail if it is passed a NULL pointer. In the case of error, a NULL pointer will be returned.
Source code in src/pact/v3/ffi.py
message_pact_message_iter_delete(iter: MessagePactMessageIterator) -> None
¶
Delete the iterator.
Rust
pactffi_message_pact_message_iter_delete
Source code in src/pact/v3/ffi.py
message_pact_message_iter_next(iter: MessagePactMessageIterator) -> Message
¶
Get the next message from the message pact.
Rust
pactffi_message_pact_message_iter_next
Safety¶
This function is safe.
Error Handling¶
This function will return a NULL pointer if passed a NULL pointer or if an error occurs.
Source code in src/pact/v3/ffi.py
message_pact_metadata_iter_delete(iter: MessagePactMetadataIterator) -> None
¶
Free the metadata iterator when you're done using it.
Rust pactffi_message_pact_metadata_iter_delete
Source code in src/pact/v3/ffi.py
message_pact_metadata_iter_next(iter: MessagePactMetadataIterator) -> MessagePactMetadataTriple
¶
Get the next triple out of the iterator, if possible.
Rust
pactffi_message_pact_metadata_iter_next
Safety¶
This operation is invalid if the underlying data has been changed during iteration.
Error Handling¶
Returns null if no next element is present.
Source code in src/pact/v3/ffi.py
message_pact_metadata_triple_delete(triple: MessagePactMetadataTriple) -> None
¶
Free a triple returned from pactffi_message_pact_metadata_iter_next
.
Rust pactffi_message_pact_metadata_triple_delete
Source code in src/pact/v3/ffi.py
message_pact_new_from_json(file_name: str, json_str: str) -> MessagePact
¶
Construct a new MessagePact
from the JSON string.
The provided file name is used when generating error messages.
Rust
pactffi_message_pact_new_from_json
Safety¶
The file_name
and json_str
parameters must both be valid UTF-8 encoded
strings.
Error Handling¶
On error, this function will return a null pointer.
Source code in src/pact/v3/ffi.py
message_reify(message_handle: MessageHandle) -> OwnedString
¶
Reifies the given message.
Reification is the process of stripping away any matchers, and returning the original contents.
Safety¶
The returned string needs to be deallocated with the free_string
function.
This function must only ever be called from a foreign language. Calling it
from a Rust function that has a Tokio runtime in its call stack can result
in a deadlock.
Source code in src/pact/v3/ffi.py
message_set_contents(message: Message, contents: str, content_type: str) -> None
¶
Sets the contents of the message.
Rust
pactffi_message_set_contents
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.
Source code in src/pact/v3/ffi.py
message_set_contents_bin(message: Message, contents: str, len: int, content_type: str) -> None
¶
Sets the contents of the message as an array of bytes.
Rust
pactffi_message_set_contents_bin
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.
Source code in src/pact/v3/ffi.py
message_set_description(message: Message, description: str) -> int
¶
Write the description
field on the Message
.
Rust
pactffi_message_set_description
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.
Source code in src/pact/v3/ffi.py
message_with_contents(message_handle: MessageHandle, content_type: str, body: List[int], size: int) -> None
¶
Adds the contents of the Message.
Rust
pactffi_message_with_contents
Accepts JSON, binary and other payload types. Binary data will be base64 encoded when serialised.
Note: For text bodies (plain text, JSON or XML), you can pass in a C string (NULL terminated) and the size of the body is not required (it will be ignored). For binary bodies, you need to specify the number of bytes in the body.
content_type
- The content type of the body. Defaults totext/plain
, supports JSON structures with matchers and binary data.body
- The body contents as bytes. For text payloads (JSON, XML, etc.), a C string can be used and matching rules can be embedded in the body.content_type
- Expected content type (e.g. application/json, application/octet-stream)size
- number of bytes in the message body to read. This is not required for text bodies (JSON, XML, etc.).
Source code in src/pact/v3/ffi.py
message_with_metadata(message_handle: MessageHandle, key: str, value: str) -> None
¶
Adds expected metadata to the Message.
Rust
pactffi_message_with_metadata
key
- metadata keyvalue
- metadata value.
Source code in src/pact/v3/ffi.py
message_with_metadata_v2(message_handle: MessageHandle, key: str, value: str) -> None
¶
Adds expected metadata to the Message.
Rust
pactffi_message_with_metadata_v2
PARAMETER | DESCRIPTION |
---|---|
message_handle |
Handle to the Message.
TYPE:
|
key |
Metadata key.
TYPE:
|
value |
Metadata value. This may be a simple string in which case it will be used as-is, or it may be a JSON matching rule.
TYPE:
|
To include matching rules for the metadata, include the matching rule JSON format with the value as a single JSON document. I.e.
message_with_metadata_v2(
handle,
"contentType",
json.dumps({
"pact:matcher:type": "regex",
"regex": "text/.*",
}),
)
See IntegrationJson.md.
Source code in src/pact/v3/ffi.py
mismatch_ansi_description(mismatch: Mismatch) -> str
¶
Get an ANSI-compatible description of a mismatch.
Rust pactffi_mismatch_ansi_description
Source code in src/pact/v3/ffi.py
mismatch_description(mismatch: Mismatch) -> str
¶
Get a description of a mismatch.
Rust pactffi_mismatch_description
Source code in src/pact/v3/ffi.py
mismatch_summary(mismatch: Mismatch) -> str
¶
Get a summary of a mismatch.
mismatch_to_json(mismatch: Mismatch) -> str
¶
Get a JSON representation of the mismatch.
Source code in src/pact/v3/ffi.py
mismatch_type(mismatch: Mismatch) -> str
¶
Get the type of a mismatch.
mismatches_delete(mismatches: Mismatches) -> None
¶
Delete mismatches.
mismatches_get_iter(mismatches: Mismatches) -> MismatchesIterator
¶
mismatches_iter_delete(iter: MismatchesIterator) -> None
¶
Delete a mismatches iterator when you're done with it.
Rust pactffi_mismatches_iter_delete
Source code in src/pact/v3/ffi.py
mismatches_iter_next(iter: MismatchesIterator) -> Mismatch
¶
Get the next mismatch from a mismatches iterator.
Rust pactffi_mismatches_iter_next
Returns a null pointer if no mismatches remain.
Source code in src/pact/v3/ffi.py
mock_server_logs(mock_server_handle: PactServerHandle) -> str
¶
Fetch the logs for the mock server.
This needs the memory buffer log sink to be setup before the mock server is started.
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the logs for the mock server can not be retrieved. |
Source code in src/pact/v3/ffi.py
mock_server_matched(mock_server_handle: PactServerHandle) -> bool
¶
External interface to check if a mock server has matched all its requests.
If all requests have been matched, true
is returned. false
is returned
if any request has not been successfully matched, or the method panics.
Rust
pactffi_mock_server_matched
Source code in src/pact/v3/ffi.py
mock_server_mismatches(mock_server_handle: PactServerHandle) -> list[dict[str, Any]]
¶
External interface to get all the mismatches from a mock server.
Rust
pactffi_mock_server_mismatches
Errors¶
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If there is no mock server with the provided port number, or the function panics. |
Source code in src/pact/v3/ffi.py
new_interaction(pact: PactHandle, description: str) -> InteractionHandle
¶
Creates a new HTTP Interaction and returns a handle to it.
Calling this function with the same description as an existing interaction will result in that interaction being replaced with the new one.
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to the Pact model.
TYPE:
|
description |
The interaction description. It needs to be unique for each Pact.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
InteractionHandle
|
Handle to the new Interaction. |
Source code in src/pact/v3/ffi.py
new_message(pact: MessagePactHandle, description: str) -> MessageHandle
¶
Creates a new Message and returns a handle to it.
description
- The message description. It needs to be unique for each Message.
Returns a new MessageHandle
.
Source code in src/pact/v3/ffi.py
new_message_interaction(pact: PactHandle, description: str) -> InteractionHandle
¶
Creates a new message interaction and returns a handle to it.
Calling this function with the same description as an existing interaction will result in that interaction being replaced with the new one.
Rust
pactffi_new_message_interaction
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to the Pact model.
TYPE:
|
description |
The interaction description. It needs to be unique for each Pact.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
InteractionHandle
|
Handle to the new Interaction |
Source code in src/pact/v3/ffi.py
new_message_pact(consumer_name: str, provider_name: str) -> MessagePactHandle
¶
Creates a new Pact Message model and returns a handle to it.
consumer_name
- The name of the consumer for the pact.provider_name
- The name of the provider for the pact.
Returns a new MessagePactHandle
. The handle will need to be freed with the
pactffi_free_message_pact_handle
function to release its resources.
Source code in src/pact/v3/ffi.py
new_pact(consumer_name: str, provider_name: str) -> PactHandle
¶
Creates a new Pact model and returns a handle to it.
PARAMETER | DESCRIPTION |
---|---|
consumer_name |
The name of the consumer for the pact.
TYPE:
|
provider_name |
The name of the provider for the pact.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
PactHandle
|
Handle to the new Pact model. |
Source code in src/pact/v3/ffi.py
new_sync_message_interaction(pact: PactHandle, description: str) -> InteractionHandle
¶
Creates a new synchronous message interaction and returns a handle to it.
Calling this function with the same description as an existing interaction will result in that interaction being replaced with the new one.
Rust
pactffi_new_sync_message_interaction
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to the Pact model.
TYPE:
|
description |
The interaction description. It needs to be unique for each Pact.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
InteractionHandle
|
Handle to the new Interaction |
Source code in src/pact/v3/ffi.py
pact_consumer_delete(consumer: Consumer) -> None
¶
Frees the memory used by the Pact consumer.
Rust pactffi_pact_consumer_delete
Source code in src/pact/v3/ffi.py
pact_get_consumer(pact: Pact) -> Consumer
¶
Get the consumer from a Pact.
This returns a copy of the consumer model, and needs to be cleaned up with
pactffi_pact_consumer_delete
when no longer required.
Rust
pactffi_pact_get_consumer
Errors¶
This function will fail if it is passed a NULL pointer. In the case of error, a NULL pointer will be returned.
Source code in src/pact/v3/ffi.py
pact_get_provider(pact: Pact) -> Provider
¶
Get the provider from a Pact.
This returns a copy of the provider model, and needs to be cleaned up with
pactffi_pact_provider_delete
when no longer required.
Rust
pactffi_pact_get_provider
Errors¶
This function will fail if it is passed a NULL pointer. In the case of error, a NULL pointer will be returned.
Source code in src/pact/v3/ffi.py
pact_handle_get_message_iter(pact: PactHandle) -> PactMessageIterator
¶
Get an iterator over all the messages of the Pact.
Rust
pactffi_pact_handle_get_message_iter
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.
Source code in src/pact/v3/ffi.py
pact_handle_get_sync_http_iter(pact: PactHandle) -> PactSyncHttpIterator
¶
Get an iterator over all the synchronous HTTP request/response interactions.
The returned iterator needs to be freed with
pactffi_pact_sync_http_iter_delete
.
Rust
pactffi_pact_handle_get_sync_http_iter
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.
Source code in src/pact/v3/ffi.py
pact_handle_get_sync_message_iter(pact: PactHandle) -> PactSyncMessageIterator
¶
Get an iterator over all the synchronous messages of the Pact.
The returned iterator needs to be freed with
pactffi_pact_sync_message_iter_delete
.
Rust
pactffi_pact_handle_get_sync_message_iter
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.
Source code in src/pact/v3/ffi.py
pact_handle_to_pointer(pact: PactHandle) -> Pact
¶
Unwraps a Pact handle to the underlying Pact.
The Pact model which has been cloned from the Pact handle's inner Pact model.
The returned Pact model must be freed with the pactffi_pact_model_delete
function when no longer needed.
Source code in src/pact/v3/ffi.py
pact_handle_write_file(pact: PactHandle, directory: Path | str | None, *, overwrite: bool) -> None
¶
External interface to write out the pact file.
Rust
pactffi_pact_handle_write_file
This function should be called if all the consumer tests have passed.
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to a Pact model.
TYPE:
|
directory |
The directory to write the file to. If |
overwrite |
If
TYPE:
|
Source code in src/pact/v3/ffi.py
pact_interaction_as_asynchronous_message(interaction: PactInteraction) -> AsynchronousMessage
¶
Casts this interaction to a AsynchronousMessage
interaction.
Returns a NULL pointer if the interaction can not be casted to a
AsynchronousMessage
interaction (for instance, it is a http interaction).
The returned pointer must be freed with pactffi_async_message_delete
when
no longer required.
Rust
pactffi_pact_interaction_as_asynchronous_message
Note that if the interaction is a V3 Message
, it will be converted to a V4
AsynchronousMessage
before being returned.
Safety This function is safe as long as the interaction pointer is a valid¶
pointer.
Errors On any error, this function will return a NULL pointer.¶
Source code in src/pact/v3/ffi.py
pact_interaction_as_message(interaction: PactInteraction) -> Message
¶
Casts this interaction to a Message
interaction.
Returns a NULL pointer if the interaction can not be casted to a Message
interaction (for instance, it is a http interaction). The returned pointer
must be freed with pactffi_message_delete
when no longer required.
Rust
pactffi_pact_interaction_as_message
Note that if the interaction is a V4 AsynchronousMessage
, it will be
converted to a V3 Message
before being returned.
Safety This function is safe as long as the interaction pointer is a valid¶
pointer.
Errors On any error, this function will return a NULL pointer.¶
Source code in src/pact/v3/ffi.py
pact_interaction_as_synchronous_http(interaction: PactInteraction) -> SynchronousHttp
¶
Casts this interaction to a SynchronousHttp
interaction.
Returns a NULL pointer if the interaction can not be casted to a
SynchronousHttp
interaction (for instance, it is a message interaction).
The returned pointer must be freed with pactffi_sync_http_delete
when no
longer required.
Rust
pactffi_pact_interaction_as_synchronous_http
Safety This function is safe as long as the interaction pointer is a valid¶
pointer.
Errors On any error, this function will return a NULL pointer.¶
Source code in src/pact/v3/ffi.py
pact_interaction_as_synchronous_message(interaction: PactInteraction) -> SynchronousMessage
¶
Casts this interaction to a SynchronousMessage
interaction.
Returns a NULL pointer if the interaction can not be casted to a
SynchronousMessage
interaction (for instance, it is a http interaction).
The returned pointer must be freed with pactffi_sync_message_delete
when
no longer required.
Rust
pactffi_pact_interaction_as_synchronous_message
Safety This function is safe as long as the interaction pointer is a valid¶
pointer.
Errors On any error, this function will return a NULL pointer.¶
Source code in src/pact/v3/ffi.py
pact_interaction_delete(interaction: PactInteraction) -> None
¶
Frees the memory used by the Pact interaction model.
Rust pactffi_pact_interaction_delete
Source code in src/pact/v3/ffi.py
pact_interaction_iter_delete(iter: PactInteractionIterator) -> None
¶
Free the iterator when you're done using it.
Rust
pactffi_pact_interaction_iter_delete
Source code in src/pact/v3/ffi.py
pact_interaction_iter_next(iter: PactInteractionIterator) -> PactInteraction
¶
Get the next interaction from the pact.
Rust
pactffi_pact_interaction_iter_next
Source code in src/pact/v3/ffi.py
pact_message_iter_delete(iter: PactMessageIterator) -> None
¶
Free the iterator when you're done using it.
Rust
pactffi_pact_message_iter_delete
Source code in src/pact/v3/ffi.py
pact_message_iter_next(iter: PactMessageIterator) -> Message
¶
Get the next message from the message pact.
Rust
pactffi_pact_message_iter_next
Source code in src/pact/v3/ffi.py
pact_model_delete(pact: Pact) -> None
¶
Frees the memory used by the Pact model.
pact_model_interaction_iterator(pact: Pact) -> PactInteractionIterator
¶
Returns an iterator over all the interactions in the Pact.
Rust
pactffi_pact_model_interaction_iterator
The iterator will have to be deleted using the
pactffi_pact_interaction_iter_delete
function. The iterator will contain a
copy of the interactions, so it will not be affected but mutations to the
Pact model and will still function if the Pact model is deleted.
Safety This function is safe as long as the Pact pointer is a valid¶
pointer.
Errors On any error, this function will return a NULL pointer.¶
Source code in src/pact/v3/ffi.py
pact_provider_delete(provider: Provider) -> None
¶
Frees the memory used by the Pact provider.
Rust
pactffi_pact_provider_delete
Source code in src/pact/v3/ffi.py
pact_spec_version(pact: Pact) -> PactSpecification
¶
Returns the Pact specification enum that the Pact is for.
Rust pactffi_pact_spec_version
Source code in src/pact/v3/ffi.py
pact_sync_http_iter_delete(iter: PactSyncHttpIterator) -> None
¶
Free the iterator when you're done using it.
Rust
pactffi_pact_sync_http_iter_delete
Source code in src/pact/v3/ffi.py
pact_sync_http_iter_next(iter: PactSyncHttpIterator) -> SynchronousHttp
¶
Get the next synchronous HTTP request/response interaction from the V4 pact.
Rust
pactffi_pact_sync_http_iter_next
Source code in src/pact/v3/ffi.py
pact_sync_message_iter_delete(iter: PactSyncMessageIterator) -> None
¶
Free the iterator when you're done using it.
Rust
pactffi_pact_sync_message_iter_delete
Source code in src/pact/v3/ffi.py
pact_sync_message_iter_next(iter: PactSyncMessageIterator) -> SynchronousMessage
¶
Get the next synchronous request/response message from the V4 pact.
Rust
pactffi_pact_sync_message_iter_next
Source code in src/pact/v3/ffi.py
parse_matcher_definition(expression: str) -> MatchingRuleDefinitionResult
¶
Parse a matcher definition string into a MatchingRuleDefinition.
The MatchingRuleDefition contains the example value, and matching rules and any generator.
Rust
pactffi_parse_matcher_definition
The following are examples of matching rule definitions:
matching(type,'Name')
- type matcher with string value 'Name'matching(number,100)
- number matchermatching(datetime, 'yyyy-MM-dd','2000-01-01')
- datetime matcher with format string
See Matching Rule definition expressions.
The returned value needs to be freed up with the
pactffi_matcher_definition_delete
function.
Errors If the expression is invalid, the MatchingRuleDefinition error will¶
be set. You can check for this value with the
pactffi_matcher_definition_error
function.
Safety¶
This function is safe if the expression is a valid NULL terminated string pointer.
Source code in src/pact/v3/ffi.py
parse_pact_json(json: str) -> Pact
¶
Parses the provided JSON into a Pact model.
The returned Pact model must be freed with the pactffi_pact_model_delete
function when no longer needed.
Error Handling¶
This function will return a NULL pointer if passed a NULL pointer or if an error occurs.
Source code in src/pact/v3/ffi.py
provider_get_name(provider: Provider) -> str
¶
Get a copy of this provider's name.
Rust
pactffi_provider_get_name
The copy must be deleted with pactffi_string_delete
.
Usage¶
// Assuming `file_name` and `json_str` are already defined.
MessagePact *message_pact = pactffi_message_pact_new_from_json(file_name, json_str);
if (message_pact == NULLPTR) {
// handle error.
}
Provider *provider = pactffi_message_pact_get_provider(message_pact);
if (provider == NULLPTR) {
// handle error.
}
char *name = pactffi_provider_get_name(provider);
if (name == NULL) {
// handle error.
}
printf("%s\n", name);
pactffi_string_delete(name);
Errors¶
This function will fail if it is passed a NULL pointer, or the Rust string contains an embedded NULL byte. In the case of error, a NULL pointer will be returned.
Source code in src/pact/v3/ffi.py
provider_state_delete(provider_state: ProviderState) -> None
¶
Free the provider state when you're done using it.
Rust
pactffi_provider_state_delete
Source code in src/pact/v3/ffi.py
provider_state_get_name(provider_state: ProviderState) -> str
¶
Get the name of the provider state as a string.
This needs to be deleted with pactffi_string_delete
.
Rust
pactffi_provider_state_get_name
Safety¶
This function is safe.
Error Handling¶
If the provider_state param is NULL, this returns NULL.
Source code in src/pact/v3/ffi.py
provider_state_get_param_iter(provider_state: ProviderState) -> ProviderStateParamIterator
¶
Get an iterator over the params of a provider state.
Rust
pactffi_provider_state_get_param_iter
Safety¶
This iterator carries a pointer to the provider state, and must not outlive the provider state.
The provider state params also must not be modified during iteration. If it is, the old iterator must be deleted and a new iterator created.
Errors¶
On failure, this function will return a NULL pointer.
This function may fail if any of the Rust strings contain embedded null ('\0') bytes.
Source code in src/pact/v3/ffi.py
provider_state_iter_delete(iter: ProviderStateIterator) -> None
¶
provider_state_iter_next(iter: ProviderStateIterator) -> ProviderState
¶
Get the next value from the iterator.
Rust
pactffi_provider_state_iter_next
Safety¶
The underlying data must not change during iteration.
If a previous call panicked, then the internal mutex will have been poisoned and this function will return NULL.
Error Handling¶
Returns NULL if an error occurs.
Source code in src/pact/v3/ffi.py
provider_state_param_iter_delete(iter: ProviderStateParamIterator) -> None
¶
Free the provider state param iterator when you're done using it.
Rust
pactffi_provider_state_param_iter_delete
Source code in src/pact/v3/ffi.py
provider_state_param_iter_next(iter: ProviderStateParamIterator) -> ProviderStateParamPair
¶
Get the next key and value out of the iterator, if possible.
Rust
pactffi_provider_state_param_iter_next
Returns a pointer to a heap allocated array of 2 elements, the pointer to the key string on the heap, and the pointer to the value string on the heap.
Safety¶
The underlying data must not be modified during iteration.
The user needs to free both the contained strings and the array.
Error Handling¶
Returns NULL if there's no further elements or the iterator is NULL.
Source code in src/pact/v3/ffi.py
provider_state_param_pair_delete(pair: ProviderStateParamPair) -> None
¶
Free a pair of key and value.
Rust
pactffi_provider_state_param_pair_delete
Source code in src/pact/v3/ffi.py
request_contents_get_generators_iter(request: HttpRequest, category: GeneratorCategory) -> GeneratorCategoryIterator
¶
Get an iterator over the generators for a category of an HTTP request.
Rust
pactffi_request_contents_get_generators_iter
The returned pointer must be deleted with pactffi_generators_iter_delete
when done with it.
Safety¶
The iterator contains a copy of the data, so is safe to use when the interaction or request contents has been deleted.
Error Handling¶
On failure, this function will return a NULL pointer.
Source code in src/pact/v3/ffi.py
request_contents_get_matching_rule_iter(request: HttpRequest, category: MatchingRuleCategory) -> MatchingRuleCategoryIterator
¶
Get an iterator over the matching rules for a category of an HTTP request.
Rust pactffi_request_contents_get_matching_rule_iter
The returned pointer must be deleted with
pactffi_matching_rules_iter_delete
when done with it.
For sample, given the following rules:
This iterator will return a sequence of 3 values:
("$.a", Type)
("$.b", Regex("\d+"))
("$.b", Number)
Safety¶
The iterator contains a copy of the data, so is safe to use when the interaction or request contents has been deleted.
Error Handling¶
On failure, this function will return a NULL pointer.
Source code in src/pact/v3/ffi.py
response_contents_get_generators_iter(response: HttpResponse, category: GeneratorCategory) -> GeneratorCategoryIterator
¶
Get an iterator over the generators for a category of an HTTP response.
Rust
pactffi_response_contents_get_generators_iter
The returned pointer must be deleted with pactffi_generators_iter_delete
when done with it.
Safety¶
The iterator contains a copy of the data, so is safe to use when the interaction or response contents has been deleted.
Error Handling¶
On failure, this function will return a NULL pointer.
Source code in src/pact/v3/ffi.py
response_contents_get_matching_rule_iter(response: HttpResponse, category: MatchingRuleCategory) -> MatchingRuleCategoryIterator
¶
Get an iterator over the matching rules for a category of an HTTP response.
Rust pactffi_response_contents_get_matching_rule_iter
The returned pointer must be deleted with
pactffi_matching_rules_iter_delete
when done with it.
For sample, given the following rules:
This iterator will return a sequence of 3 values:
("$.a", Type)
("$.b", Regex("\d+"))
("$.b", Number)
Safety¶
The iterator contains a copy of the data, so is safe to use when the interaction or response contents has been deleted.
Error Handling¶
On failure, this function will return a NULL pointer.
Source code in src/pact/v3/ffi.py
response_status(interaction: InteractionHandle, status: int) -> None
¶
Configures the response for the Interaction.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
status |
The response status. Defaults to 200.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the response status could not be set. |
Source code in src/pact/v3/ffi.py
response_status_v2(interaction: InteractionHandle, status: str) -> None
¶
Configures the response for the Interaction.
Rust
pactffi_response_status_v2
To include matching rules for the status (only statusCode or integer really makes sense to use), include the matching rule JSON format with the value as a single JSON document. I.e.
response_status_v2(
handle,
json.dumps({
"pact:generator:type": "RandomInt",
"min": 100,
"max": 399,
"pact:matcher:type": "statusCode",
"status": "nonError",
}),
)
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
status |
The response status. Defaults to 200. This may be a simple string in which case it will be used as-is, or it may be a JSON matching rule.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the response status could not be set. |
Source code in src/pact/v3/ffi.py
set_comment(interaction: InteractionHandle, key: str, value: str | None) -> None
¶
Add a comment to the interaction.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Interaction handle to set the comments for.
TYPE:
|
key |
Key value
TYPE:
|
value |
Comment value. This may be any valid JSON value, or a
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the comments could not be updated. |
Source code in src/pact/v3/ffi.py
set_header(interaction: InteractionHandle, part: InteractionPart, name: str, value: str) -> None
¶
Sets a header for the Interaction.
Note that this function will overwrite any previously set header values. Also, this function will not process the value in any way, so matching rules and generators can not be configured with it.
If matching rules are required to be set, use pactffi_with_header_v2
.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
part |
The part of the interaction to add the header to (Request or Response).
TYPE:
|
name |
The header name. This is case insensitive.
TYPE:
|
value |
The header value. This is handled as-is, with no processing.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the header could not be set. |
Source code in src/pact/v3/ffi.py
set_key(interaction: InteractionHandle, key: str | None) -> None
¶
Sets the key attribute for the interaction.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Interaction handle to modify.
TYPE:
|
key |
Key value. This must be a valid UTF-8 null-terminated string, or
TYPE:
|
Source code in src/pact/v3/ffi.py
set_pending(interaction: InteractionHandle, *, pending: bool) -> None
¶
Mark the interaction as pending.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Interaction handle to modify.
TYPE:
|
pending |
Boolean value to toggle the pending state of the interaction.
TYPE:
|
Source code in src/pact/v3/ffi.py
string_delete(string: OwnedString) -> None
¶
Delete a string previously returned by this FFI.
Source code in src/pact/v3/ffi.py
sync_http_delete(interaction: SynchronousHttp) -> None
¶
Destroy the SynchronousHttp
interaction being pointed to.
Source code in src/pact/v3/ffi.py
sync_http_get_description(interaction: SynchronousHttp) -> str
¶
Get a copy of the description.
Rust
pactffi_sync_http_get_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.
Source code in src/pact/v3/ffi.py
sync_http_get_provider_state(interaction: SynchronousHttp, index: int) -> ProviderState
¶
Get a copy of the provider state at the given index from this interaction.
Rust
pactffi_sync_http_get_provider_state
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.
Source code in src/pact/v3/ffi.py
sync_http_get_provider_state_iter(interaction: SynchronousHttp) -> ProviderStateIterator
¶
Get an iterator over provider states.
Rust
pactffi_sync_http_get_provider_state_iter
Safety¶
The underlying data must not change during iteration.
Error Handling¶
Returns NULL if an error occurs.
Source code in src/pact/v3/ffi.py
sync_http_get_request(interaction: SynchronousHttp) -> HttpRequest
¶
Get the request of a SynchronousHttp
interaction.
Rust
pactffi_sync_http_get_request
Safety¶
The data pointed to by the pointer this function returns will be deleted when the interaction is deleted. Trying to use if after the interaction is deleted will result in undefined behaviour.
Error Handling¶
If the interaction is NULL, returns NULL.
Source code in src/pact/v3/ffi.py
sync_http_get_request_contents(interaction: SynchronousHttp) -> str
¶
Get the request contents of a SynchronousHttp
interaction in string form.
Rust
pactffi_sync_http_get_request_contents
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.
Source code in src/pact/v3/ffi.py
sync_http_get_request_contents_bin(interaction: SynchronousHttp) -> bytes
¶
Get the request contents of a SynchronousHttp
interaction as bytes.
Rust
pactffi_sync_http_get_request_contents_bin
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.
Source code in src/pact/v3/ffi.py
sync_http_get_request_contents_length(interaction: SynchronousHttp) -> int
¶
Get the length of the request contents of a SynchronousHttp
interaction.
Rust
pactffi_sync_http_get_request_contents_length
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.
Source code in src/pact/v3/ffi.py
sync_http_get_response(interaction: SynchronousHttp) -> HttpResponse
¶
Get the response of a SynchronousHttp
interaction.
Rust
pactffi_sync_http_get_response
Safety¶
The data pointed to by the pointer this function returns will be deleted when the interaction is deleted. Trying to use if after the interaction is deleted will result in undefined behaviour.
Error Handling¶
If the interaction is NULL, returns NULL.
Source code in src/pact/v3/ffi.py
sync_http_get_response_contents(interaction: SynchronousHttp) -> str
¶
Get the response contents of a SynchronousHttp
interaction in string form.
Rust
pactffi_sync_http_get_response_contents
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.
Source code in src/pact/v3/ffi.py
sync_http_get_response_contents_bin(interaction: SynchronousHttp) -> bytes
¶
Get the response contents of a SynchronousHttp
interaction as bytes.
Rust
pactffi_sync_http_get_response_contents_bin
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.
Source code in src/pact/v3/ffi.py
sync_http_get_response_contents_length(interaction: SynchronousHttp) -> int
¶
Get the length of the response contents of a SynchronousHttp
interaction.
Rust
pactffi_sync_http_get_response_contents_length
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.
Source code in src/pact/v3/ffi.py
sync_http_new() -> SynchronousHttp
¶
Get a mutable pointer to a newly-created default interaction on the heap.
Safety¶
This function is safe.
Error Handling¶
Returns NULL on error.
Source code in src/pact/v3/ffi.py
sync_http_set_description(interaction: SynchronousHttp, description: str) -> int
¶
Write the description
field on the SynchronousHttp
.
Rust
pactffi_sync_http_set_description
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.
Source code in src/pact/v3/ffi.py
sync_http_set_request_contents(interaction: SynchronousHttp, contents: str, content_type: str) -> None
¶
Sets the request contents of the interaction.
Rust
pactffi_sync_http_set_request_contents
interaction
- the interaction to set the request contents forcontents
- 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.
Source code in src/pact/v3/ffi.py
sync_http_set_request_contents_bin(interaction: SynchronousHttp, contents: str, len: int, content_type: str) -> None
¶
Sets the request contents of the interaction as an array of bytes.
Rust
pactffi_sync_http_set_request_contents_bin
interaction
- the interaction to set the request contents forcontents
- pointer to contents to copy fromlen
- number of bytes to copy from the contents pointercontent_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.
Source code in src/pact/v3/ffi.py
sync_http_set_response_contents(interaction: SynchronousHttp, contents: str, content_type: str) -> None
¶
Sets the response contents of the interaction.
Rust
pactffi_sync_http_set_response_contents
interaction
- the interaction to set the response contents forcontents
- 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.
Source code in src/pact/v3/ffi.py
sync_http_set_response_contents_bin(interaction: SynchronousHttp, contents: str, len: int, content_type: str) -> None
¶
Sets the response contents of the SynchronousHttp
interaction as bytes.
Rust
pactffi_sync_http_set_response_contents_bin
interaction
- the interaction to set the response contents forcontents
- pointer to contents to copy fromlen
- number of bytes to copycontent_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.
Source code in src/pact/v3/ffi.py
sync_message_delete(message: SynchronousMessage) -> None
¶
Destroy the Message
being pointed to.
Rust
pactffi_sync_message_delete
Source code in src/pact/v3/ffi.py
sync_message_get_description(message: SynchronousMessage) -> str
¶
Get a copy of the description.
Rust
pactffi_sync_message_get_description
Safety¶
The returned string must be deleted with pactffi_string_delete
.
Since it is a copy, the returned string may safely outlive the
SynchronousMessage
.
Errors¶
On failure, this function will return a NULL pointer.
This function may fail if the Rust string contains embedded null ('\0') bytes.
Source code in src/pact/v3/ffi.py
sync_message_get_number_responses(message: SynchronousMessage) -> int
¶
Get the number of response messages in the SynchronousMessage
.
Rust
pactffi_sync_message_get_number_responses
Safety¶
The message pointer must point to a valid SynchronousMessage.
Error Handling¶
If the message is NULL, returns 0.
Source code in src/pact/v3/ffi.py
sync_message_get_provider_state(message: SynchronousMessage, index: int) -> ProviderState
¶
Get a copy of the provider state at the given index from this message.
Rust
pactffi_sync_message_get_provider_state
Safety¶
The returned structure must be deleted with provider_state_delete
.
Since it is a copy, the returned structure may safely outlive the
SynchronousMessage
.
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.
Source code in src/pact/v3/ffi.py
sync_message_get_provider_state_iter(message: SynchronousMessage) -> ProviderStateIterator
¶
Get an iterator over provider states.
Rust
pactffi_sync_message_get_provider_state_iter
Safety¶
The underlying data must not change during iteration.
Error Handling¶
Returns NULL if an error occurs.
Source code in src/pact/v3/ffi.py
sync_message_get_request_contents(message: SynchronousMessage) -> MessageContents
¶
Get the request contents of an SynchronousMessage
as a MessageContents
.
Rust
pactffi_sync_message_get_request_contents
Safety¶
The data pointed to by the pointer this function returns will be deleted when the message is deleted. Trying to use if after the message is deleted will result in undefined behaviour.
Error Handling¶
If the message is NULL, returns NULL.
Source code in src/pact/v3/ffi.py
sync_message_get_request_contents_bin(message: SynchronousMessage) -> bytes
¶
Get the request contents of a SynchronousMessage
as a bytes.
Rust
pactffi_sync_message_get_request_contents_bin
Safety¶
The number of bytes in the buffer will be returned by
pactffi_sync_message_get_request_contents_length
. It is safe to use the
pointer while the message is not deleted or changed. Using the pointer after
the message is mutated or deleted may lead to undefined behaviour.
Error Handling¶
If the message is NULL, returns NULL. If the body of the message is missing, then this function also returns NULL.
Source code in src/pact/v3/ffi.py
sync_message_get_request_contents_length(message: SynchronousMessage) -> int
¶
Get the length of the request contents of a SynchronousMessage
.
Rust
pactffi_sync_message_get_request_contents_length
Safety¶
This function is safe.
Error Handling¶
If the message is NULL, returns 0. If the body of the request is missing, then this function also returns 0.
Source code in src/pact/v3/ffi.py
sync_message_get_request_contents_str(message: SynchronousMessage) -> str
¶
Get the request contents of a SynchronousMessage
in string form.
Rust
pactffi_sync_message_get_request_contents_str
Safety¶
The returned string must be deleted with pactffi_string_delete
.
The returned string can outlive the message.
Error Handling¶
If the message is NULL, returns NULL. If the body of the request message is missing, then this function also returns NULL. This means there's no mechanism to differentiate with this function call alone between a NULL message and a missing message body.
Source code in src/pact/v3/ffi.py
sync_message_get_response_contents(message: SynchronousMessage, index: int) -> MessageContents
¶
Get the response contents of an SynchronousMessage
as a MessageContents
.
Rust
pactffi_sync_message_get_response_contents
Safety¶
The data pointed to by the pointer this function returns will be deleted when the message is deleted. Trying to use if after the message is deleted will result in undefined behaviour.
Error Handling¶
If the message is NULL or the index is not valid, returns NULL.
Source code in src/pact/v3/ffi.py
sync_message_get_response_contents_bin(message: SynchronousMessage, index: int) -> bytes
¶
Get the response contents of a SynchronousMessage
as bytes.
Rust
pactffi_sync_message_get_response_contents_bin
Safety¶
The number of bytes in the buffer will be returned by
pactffi_sync_message_get_response_contents_length
. It is safe to use the
pointer while the message is not deleted or changed. Using the pointer after
the message is mutated or deleted may lead to undefined behaviour.
Error Handling¶
If the message is NULL or the index is not valid, returns NULL. If the body of the message is missing, then this function also returns NULL.
Source code in src/pact/v3/ffi.py
sync_message_get_response_contents_length(message: SynchronousMessage, index: int) -> int
¶
Get the length of the response contents of a SynchronousMessage
.
Rust
pactffi_sync_message_get_response_contents_length
Safety¶
This function is safe.
Error Handling¶
If the message is NULL or the index is not valid, returns 0. If the body of the request is missing, then this function also returns 0.
Source code in src/pact/v3/ffi.py
sync_message_get_response_contents_str(message: SynchronousMessage, index: int) -> str
¶
Get the response contents of a SynchronousMessage
in string form.
Rust
pactffi_sync_message_get_response_contents_str
Safety¶
The returned string must be deleted with pactffi_string_delete
.
The returned string can outlive the message.
Error Handling¶
If the message is NULL or the index is not valid, returns NULL.
If the body of the response message is missing, then this function also returns NULL. This means there's no mechanism to differentiate with this function call alone between a NULL message and a missing message body.
Source code in src/pact/v3/ffi.py
sync_message_new() -> SynchronousMessage
¶
Get a mutable pointer to a newly-created default message on the heap.
Safety¶
This function is safe.
Error Handling¶
Returns NULL on error.
Source code in src/pact/v3/ffi.py
sync_message_set_description(message: SynchronousMessage, description: str) -> int
¶
Write the description
field on the SynchronousMessage
.
Rust
pactffi_sync_message_set_description
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.
Source code in src/pact/v3/ffi.py
sync_message_set_request_contents_bin(message: SynchronousMessage, contents: str, len: int, content_type: str) -> None
¶
Sets the request contents of the message as an array of bytes.
Rust
pactffi_sync_message_set_request_contents_bin
message
- the message to set the request contents forcontents
- pointer to contents to copy fromlen
- number of bytes to copy from the contents pointercontent_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.
Source code in src/pact/v3/ffi.py
sync_message_set_request_contents_str(message: SynchronousMessage, contents: str, content_type: str) -> None
¶
Sets the request contents of the message.
Rust
pactffi_sync_message_set_request_contents_str
message
- the message to set the request contents forcontents
- 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.
Source code in src/pact/v3/ffi.py
sync_message_set_response_contents_bin(message: SynchronousMessage, index: int, contents: str, len: int, content_type: str) -> None
¶
Sets the response contents of the message at the given index as bytes.
If index is greater than the number of responses in the message, the responses will be padded with default values.
Rust
pactffi_sync_message_set_response_contents_bin
message
- the message to set the response contents forindex
- index of the response to set. 0 is the first responsecontents
- pointer to contents to copy fromlen
- number of bytes to copycontent_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.
Source code in src/pact/v3/ffi.py
sync_message_set_response_contents_str(message: SynchronousMessage, index: int, contents: str, content_type: str) -> None
¶
Sets the response contents of the message as a string.
If index is greater than the number of responses in the message, the responses will be padded with default values.
Rust
pactffi_sync_message_set_response_contents_str
message
- the message to set the response contents forindex
- 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.
Source code in src/pact/v3/ffi.py
upon_receiving(interaction: InteractionHandle, description: str) -> None
¶
Sets the description for the Interaction.
This function
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
description |
The interaction description. It needs to be unique for each Pact.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the interaction description could not be set. |
Source code in src/pact/v3/ffi.py
using_plugin(pact: PactHandle, plugin_name: str, plugin_version: str | None) -> None
¶
Add a plugin to be used by the test.
The plugin needs to be installed correctly for this function to work.
Note that plugins run as separate processes, so will need to be cleaned up
afterwards by calling cleanup_plugins
otherwise you will have plugin processes left running.
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to a Pact model.
TYPE:
|
plugin_name |
Name of the plugin to use.
TYPE:
|
plugin_version |
Version of the plugin to use. If
TYPE:
|
Source code in src/pact/v3/ffi.py
validate_datetime(value: str, format: str) -> None
¶
Validates the date/time value against the date/time format string.
Raises an error if the value is not a valid date/time for the format string.
If the value is valid, this function will return a zero status code
(EXIT_SUCCESS). If the value is not valid, will return a value of 1
(EXIT_FAILURE) and set the error message which can be retrieved with
pactffi_get_error_message
.
Rust
pactffi_validate_datetime
Errors If the function receives a panic, it will return 2 and the message¶
associated with the panic can be retrieved with pactffi_get_error_message
.
Safety¶
This function is safe as long as the value and format parameters point to valid NULL-terminated strings.
Source code in src/pact/v3/ffi.py
verifier_add_custom_header(handle: VerifierHandle, header_name: str, header_value: str) -> None
¶
Adds a custom header to be added to the requests made to the provider.
Rust
pactffi_verifier_add_custom_header
Source code in src/pact/v3/ffi.py
verifier_add_directory_source(handle: VerifierHandle, directory: str) -> None
¶
Adds a Pact directory as a source to verify.
All pacts from the directory that match the provider name will be verified.
Rust
pactffi_verifier_add_directory_source
Safety¶
All string fields must contain valid UTF-8. Invalid UTF-8 will be replaced with U+FFFD REPLACEMENT CHARACTER.
Source code in src/pact/v3/ffi.py
verifier_add_file_source(handle: VerifierHandle, file: str) -> None
¶
Adds a Pact file as a source to verify.
Rust
pactffi_verifier_add_file_source
Source code in src/pact/v3/ffi.py
verifier_add_provider_transport(handle: VerifierHandle, protocol: str | None, port: int, path: str | None, scheme: str | None) -> None
¶
Adds a new transport for the given provider.
Rust
pactffi_verifier_add_provider_transport
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
protocol |
In this context, the kind of
TYPE:
|
port |
The port of the provider.
TYPE:
|
path |
The path of the provider.
TYPE:
|
scheme |
The scheme to use, typically one of
TYPE:
|
If any value is None
, the default value as determined by the underlying
FFI library will be used.
Source code in src/pact/v3/ffi.py
verifier_broker_source(handle: VerifierHandle, url: str, username: str | None, password: str | None, token: str | None) -> None
¶
Adds a Pact broker as a source to verify.
Rust
pactffi_verifier_broker_source
This will fetch all the pact files from the broker that match the provider name.
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
url |
The URL to use as a source for the verifier.
TYPE:
|
username |
The username to use when fetching pacts from the broker.
TYPE:
|
password |
The password to use when fetching pacts from the broker.
TYPE:
|
token |
The token to use when fetching pacts from the broker. This will be used as a bearer token.
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_broker_source_with_selectors(handle: VerifierHandle, url: str, username: str | None, password: str | None, token: str | None, enable_pending: int, include_wip_pacts_since: datetime.date | None, provider_tags: List[str], provider_branch: str | None, consumer_version_selectors: List[str], consumer_version_tags: List[str]) -> None
¶
Adds a Pact broker as a source to verify.
Rust
pactffi_verifier_broker_source_with_selectors
This will fetch all the pact files from the broker that match the provider name and the consumer version selectors (See Consumer Version Selectors).
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
url |
The URL to use as a source for the verifier.
TYPE:
|
username |
The username to use when fetching pacts from the broker.
TYPE:
|
password |
The password to use when fetching pacts from the broker.
TYPE:
|
token |
The token to use when fetching pacts from the broker. This will be used as a bearer token.
TYPE:
|
enable_pending |
If pending pacts should be included in the verification process.
TYPE:
|
include_wip_pacts_since |
The date to use to filter out WIP pacts.
TYPE:
|
provider_tags |
The tags to use to filter the provider pacts. |
provider_branch |
The branch to use to filter the provider pacts.
TYPE:
|
consumer_version_selectors |
The consumer version selectors to use to filter the consumer pacts. |
consumer_version_tags |
The tags to use to filter the consumer pacts. |
Source code in src/pact/v3/ffi.py
6850 6851 6852 6853 6854 6855 6856 6857 6858 6859 6860 6861 6862 6863 6864 6865 6866 6867 6868 6869 6870 6871 6872 6873 6874 6875 6876 6877 6878 6879 6880 6881 6882 6883 6884 6885 6886 6887 6888 6889 6890 6891 6892 6893 6894 6895 6896 6897 6898 6899 6900 6901 6902 6903 6904 6905 6906 6907 6908 6909 6910 6911 6912 6913 6914 6915 6916 6917 6918 6919 6920 6921 6922 6923 6924 6925 |
|
verifier_cli_args() -> str
¶
External interface to retrieve the CLI options and arguments.
This available when calling the CLI interface, returning them as a JSON string.
Rust
pactffi_verifier_cli_args
The purpose is to then be able to use in other languages which wrap the FFI library, to implement the same CLI functionality automatically without manual maintenance of arguments, help descriptions etc.
Example structure¶
{
"options": [
{
"long": "scheme",
"help": "Provider URI scheme (defaults to http)",
"possible_values": [
"http",
"https"
],
"default_value": "http"
"multiple": false,
},
{
"long": "file",
"short": "f",
"help": "Pact file to verify (can be repeated)",
"multiple": true
},
{
"long": "user",
"help": "Username to use when fetching pacts from URLS",
"multiple": false,
"env": "PACT_BROKER_USERNAME"
}
],
"flags": [
{
"long": "disable-ssl-verification",
"help": "Disables validation of SSL certificates",
"multiple": false
}
]
}
Safety¶
Exported functions are inherently unsafe.
Source code in src/pact/v3/ffi.py
verifier_execute(handle: VerifierHandle) -> None
¶
Runs the verification.
(https://docs.rs/pact_ffi/0.4.19/pact_ffi/?search=pactffi_verifier_execute)
Source code in src/pact/v3/ffi.py
verifier_json(handle: VerifierHandle) -> OwnedString
¶
Extracts the verification result as a JSON document.
Source code in src/pact/v3/ffi.py
verifier_logs(handle: VerifierHandle) -> OwnedString
¶
Extracts the logs for the verification run.
This needs the memory buffer log sink to be setup before the verification is
executed. The returned string will need to be freed with the free_string
function call to avoid leaking memory.
Source code in src/pact/v3/ffi.py
verifier_logs_for_provider(provider_name: str) -> OwnedString
¶
Extracts the logs for the verification run for the provider name.
Rust
pactffi_verifier_logs_for_provider
This needs the memory buffer log sink to be setup before the verification is
executed. The returned string will need to be freed with the free_string
function call to avoid leaking memory.
Source code in src/pact/v3/ffi.py
verifier_new_for_application() -> VerifierHandle
¶
Get a Handle to a newly created verifier.
Rust
pactffi_verifier_new_for_application
Source code in src/pact/v3/ffi.py
verifier_output(handle: VerifierHandle, strip_ansi: int) -> OwnedString
¶
Extracts the standard output for the verification run.
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
strip_ansi |
This parameter controls ANSI escape codes. Setting it to a non-zero value will cause the ANSI control codes to be stripped from the output.
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_set_coloured_output(handle: VerifierHandle, *, enabled: bool) -> None
¶
Enables or disables coloured output using ANSI escape codes.
Rust
pactffi_verifier_set_coloured_output
By default, coloured output is enabled.
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
enabled |
A boolean value to enable or disable coloured output.
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_set_consumer_filters(handle: VerifierHandle, consumer_filters: Collection[str]) -> None
¶
Set the consumer filters for the Pact verifier.
Rust
pactffi_verifier_set_consumer_filters
Source code in src/pact/v3/ffi.py
verifier_set_filter_info(handle: VerifierHandle, filter_description: str | None, filter_state: str | None, *, filter_no_state: bool) -> None
¶
Set the filters for the Pact verifier.
Rust
pactffi_verifier_set_filter_info
Set filters to narrow down the interactions to verify.
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
filter_description |
A regular expression to filter the interactions by description.
TYPE:
|
filter_state |
A regular expression to filter the interactions by state.
TYPE:
|
filter_no_state |
If
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_set_no_pacts_is_error(handle: VerifierHandle, *, enabled: bool) -> None
¶
Enables or disables if no pacts are found to verify results in an error.
Rust
pactffi_verifier_set_no_pacts_is_error
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
enabled |
If
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_set_provider_info(handle: VerifierHandle, name: str | None, scheme: str | None, host: str | None, port: int | None, path: str | None) -> None
¶
Set the provider details for the Pact verifier.
Rust
pactffi_verifier_set_provider_info
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
name |
A user-friendly name to describe the provider.
TYPE:
|
scheme |
Determine the scheme to use, typically one of
TYPE:
|
host |
The host of the provider. This may be either a hostname to resolve, or an IP address.
TYPE:
|
port |
The port of the provider.
TYPE:
|
path |
The path of the provider.
TYPE:
|
If any value is None
, the default value as determined by the underlying
FFI library will be used.
Source code in src/pact/v3/ffi.py
verifier_set_provider_state(handle: VerifierHandle, url: str, *, teardown: bool, body: bool) -> None
¶
Set the provider state URL for the Pact verifier.
Rust
pactffi_verifier_set_provider_state
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
url |
The URL to use for the provider state.
TYPE:
|
teardown |
If teardown state change requests should be made after an interaction is validated.
TYPE:
|
body |
If state change request data should be sent in the body or the query.
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_set_publish_options(handle: VerifierHandle, provider_version: str, build_url: str | None, provider_tags: List[str] | None, provider_branch: str | None) -> None
¶
Set the options used when publishing verification results to the Broker.
Rust
pactffi_verifier_set_publish_options
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
provider_version |
Version of the provider to publish.
TYPE:
|
build_url |
URL to the build which ran the verification.
TYPE:
|
provider_tags |
Collection of tags for the provider. |
provider_branch |
Name of the branch used for verification.
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_set_verification_options(handle: VerifierHandle, *, disable_ssl_verification: bool, request_timeout: int) -> None
¶
Set the options used by the verifier when calling the provider.
Rust
pactffi_verifier_set_verification_options
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
disable_ssl_verification |
If SSL verification should be disabled.
TYPE:
|
request_timeout |
The timeout for the request in milliseconds.
TYPE:
|
Source code in src/pact/v3/ffi.py
verifier_shutdown(handle: VerifierHandle) -> None
¶
Shutdown the verifier and release all resources.
Rust pactffi_verifier_shutdown
Source code in src/pact/v3/ffi.py
verifier_url_source(handle: VerifierHandle, url: str, username: str | None, password: str | None, token: str | None) -> None
¶
Adds a URL as a source to verify.
Rust
pactffi_verifier_url_source
PARAMETER | DESCRIPTION |
---|---|
handle |
The verifier handle to update.
TYPE:
|
url |
The URL to use as a source for the verifier.
TYPE:
|
username |
The username to use when fetching pacts from the URL.
TYPE:
|
password |
The password to use when fetching pacts from the URL.
TYPE:
|
token |
The token to use when fetching pacts from the URL. This will be used as a bearer token. It is mutually exclusive with the username and password.
TYPE:
|
Source code in src/pact/v3/ffi.py
verify(args: str) -> int
¶
External interface to verifier a provider.
args
- the same as the CLI interface, except newline delimited
Errors¶
Errors are returned as non-zero numeric values.
Error | Description |
---|---|
1 | The verification process failed, see output for errors |
2 | A null pointer was received |
3 | The method panicked |
4 | Invalid arguments were provided to the verification process |
Safety¶
Exported functions are inherently unsafe. Deal.
Source code in src/pact/v3/ffi.py
version() -> str
¶
Return the version of the pact_ffi library.
RETURNS | DESCRIPTION |
---|---|
str
|
The version of the pact_ffi library as a string, in the form of |
Source code in src/pact/v3/ffi.py
with_binary_body(interaction: InteractionHandle, part: InteractionPart, content_type: str | None, body: bytes | None) -> None
¶
Adds the body for the interaction.
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.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
part |
The part of the interaction to add the body to (Request or Response).
TYPE:
|
content_type |
The content type of the body. Will be ignored if a content type
header is already set. If
TYPE:
|
body |
The body contents. If
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the body could not be modified. |
Source code in src/pact/v3/ffi.py
with_binary_file(interaction: InteractionHandle, part: InteractionPart, content_type: str | None, body: bytes | None) -> None
¶
Adds a binary file as the body with the expected content type and contents.
Will use a mime type matcher to match the body. Returns false if the interaction or Pact can't be modified (i.e. the mock server for it has already started)
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.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
part |
The part of the interaction to add the body to (Request or Response).
TYPE:
|
content_type |
The content type of the body. Will be ignored if a content type header is already set.
TYPE:
|
body |
The body contents. If
TYPE:
|
Source code in src/pact/v3/ffi.py
with_body(interaction: InteractionHandle, part: InteractionPart, content_type: str | None, body: str | None) -> None
¶
Adds the body for the interaction.
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.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
part |
The part of the interaction to add the body to (Request or Response).
TYPE:
|
content_type |
The content type of the body. Will be ignored if a content type header is already set.
TYPE:
|
body |
The body contents. For JSON payloads, matching rules can be embedded in the body. See IntegrationJson.md.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the body could not be specified. |
Source code in src/pact/v3/ffi.py
with_header_v2(interaction: InteractionHandle, part: InteractionPart, name: str, index: int, value: str) -> None
¶
Configures a header for the Interaction.
To setup a header with multiple values, you can either call this function multiple times with a different index value:
with_header_v2(handle, part, "Accept-Version", 0, "2")
with_header_v2(handle, part, "Accept-Version", 0, "3")
Or you can call it once with a JSON value that contains multiple values:
The JSON value can also contain a matcher, which will be used to match the query parameter value. For example, a semver matcher might look like this:
with_query_parameter_v2(
handle,
"Accept-Version",
0,
json.dumps({
"value": "1.2.3",
"pact:matcher:type": "regex",
"regex": r"\d+\.\d+\.\d+",
}),
)
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
part |
The part of the interaction to add the header to (Request or Response).
TYPE:
|
name |
The header name. This is case insensitive.
TYPE:
|
index |
The index of the value (starts at 0). You can use this to create a header with multiple values.
TYPE:
|
value |
The header value. This may be a simple string in which case it will be used as-is, or it may be a JSON matching rule.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If there was an error setting the header. |
Source code in src/pact/v3/ffi.py
5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 |
|
with_matching_rules(interaction: InteractionHandle, part: InteractionPart, rules: str) -> None
¶
Add matching rules to the interaction.
Rust
pactffi_with_matching_rules
This function can be called multiple times, in which case the matching rules will be merged.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
part |
Request or response part (if applicable).
TYPE:
|
rules |
JSON string of the matching rules to add to the interaction.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the rules could not be added. |
Source code in src/pact/v3/ffi.py
with_message_pact_metadata(pact: MessagePactHandle, namespace_: str, name: str, value: str) -> None
¶
Sets the additional metadata on the Pact file.
Common uses are to add the client library details such as the name and version
Rust
pactffi_with_message_pact_metadata
pact
- Handle to a Pact modelnamespace
- the top level metadat key to set any key values onname
- the key to setvalue
- the value to set
Source code in src/pact/v3/ffi.py
with_multipart_file(interaction: InteractionHandle, part: InteractionPart, content_type: str, file: str, part_name: str) -> StringResult
¶
Adds a binary file as the body as a MIME multipart.
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) or an error occurs.
Rust
pactffi_with_multipart_file
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 filepart_name
- name for the mime part
This function can be called multiple times. In that case, each subsequent call will be appended to the existing multipart body as a new 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.
Source code in src/pact/v3/ffi.py
with_multipart_file_v2(interaction: InteractionHandle, part: InteractionPart, content_type: str | None, file: Path | None, part_name: str, boundary: str | None) -> None
¶
Adds a binary file as the body as a MIME multipart.
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) or an error occurs.
Rust
pactffi_with_multipart_file_v2
This function can be called multiple times. In that case, each subsequent call will be appended to the existing multipart body as a new part.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
part |
The part of the interaction to add the body to (Request or Response).
TYPE:
|
content_type |
The content type of the body.
TYPE:
|
file |
Path to the file to add. If
TYPE:
|
part_name |
Name for the mime part.
TYPE:
|
boundary |
Boundary for the multipart separation. If
TYPE:
|
Source code in src/pact/v3/ffi.py
with_pact_metadata(pact: PactHandle, namespace: str, name: str, value: str) -> None
¶
Sets the additional metadata on the Pact file.
Common uses are to add the client library details such as the name and version Returns false if the interaction or Pact can't be modified (i.e. the mock server for it has already started)
Rust
pactffi_with_pact_metadata
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to a Pact model
TYPE:
|
namespace |
The top level metadat key to set any key values on
TYPE:
|
name |
The key to set
TYPE:
|
value |
The value to set
TYPE:
|
Source code in src/pact/v3/ffi.py
with_query_parameter_v2(interaction: InteractionHandle, name: str, index: int, value: str) -> None
¶
Configures a query parameter for the Interaction.
Rust
pactffi_with_query_parameter_v2
To setup a query parameter with multiple values, you can either call this function multiple times with a different index value:
with_query_parameter_v2(handle, "version", 0, "2")
with_query_parameter_v2(handle, "version", 0, "3")
Or you can call it once with a JSON value that contains multiple values:
The JSON value can also contain a matcher, which will be used to match the query parameter value. For example, a semver matcher might look like this:
with_query_parameter_v2(
handle,
"version",
0,
json.dumps({
"value": "1.2.3",
"pact:matcher:type": "regex",
"regex": r"\d+\.\d+\.\d+",
}),
)
If you want the matching rules to apply to all values (and not just the one with the given index), make sure to set the value to be an array.
with_query_parameter_v2(
handle,
"id",
0,
json.dumps({
"value": ["2"],
"pact:matcher:type": "regex",
"regex": r"\d+",
}),
)
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
name |
The query parameter name.
TYPE:
|
index |
The index of the value (starts at 0). You can use this to create a query parameter with multiple values.
TYPE:
|
value |
The query parameter value. This may be a simple string in which case it will be used as-is, or it may be a JSON matching rule.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If there was an error setting the query parameter. |
Source code in src/pact/v3/ffi.py
5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 |
|
with_request(interaction: InteractionHandle, method: str, path: str) -> None
¶
Configures the request for the Interaction.
PARAMETER | DESCRIPTION |
---|---|
interaction |
Handle to the Interaction.
TYPE:
|
method |
The request HTTP method.
TYPE:
|
path |
The request path. This may be a simple string in which case it will be used as-is, or it may be a JSON matching rule which allows regex patterns. For examples:
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If the request could not be specified. |
Source code in src/pact/v3/ffi.py
with_specification(pact: PactHandle, version: PactSpecification) -> None
¶
Sets the specification version for a given Pact model.
Rust
pactffi_with_specification
PARAMETER | DESCRIPTION |
---|---|
pact |
Handle to a Pact model.
TYPE:
|
version |
The spec version to use.
TYPE:
|
Source code in src/pact/v3/ffi.py
write_message_pact_file(pact: MessagePactHandle, directory: str, *, overwrite: bool) -> int
¶
External interface to write out the message pact file.
This function should be called if all the consumer tests have passed. The directory to write the file to is passed as the second parameter. If a NULL pointer is passed, the current working directory is used.
Rust
pactffi_write_message_pact_file
If overwrite is true, the file will be overwritten with the contents of the current pact. Otherwise, it will be merged with any existing pact file.
Returns 0 if the pact file was successfully written. Returns a positive code if the file can not be written, or there is no mock server running on that port or the function panics.
Errors¶
Errors are returned as positive values.
Error | Description |
---|---|
1 | The pact file was not able to be written |
2 | The message pact for the given handle was not found |
Source code in src/pact/v3/ffi.py
write_pact_file(mock_server_handle: PactServerHandle, directory: str | Path, *, overwrite: bool) -> None
¶
External interface to trigger a mock server to write out its pact file.
This function should be called if all the consumer tests have passed. The directory to write the file to is passed as the second parameter.
PARAMETER | DESCRIPTION |
---|---|
mock_server_handle |
Handle to the mock server to write the pact file for.
TYPE:
|
directory |
Directory to write the pact file to. |
overwrite |
Whether to overwrite any existing pact files. If this is false, the pact file will be merged with any existing pact file.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
If there was an error writing the pact file. |