Clarify message-related FFI

JP-Ellis commented 3 months ago

Summary

We need to clarify how the Foreign Function Interface (FFI) should be used in relation to message interactions. Currently, there is confusion regarding the purpose and distinction between the following elements:

PactHandle vs MessagePactHandle
InteractionHandle vs MessageHandle

Motivation

Recent contributions to Pact Python have added support for message pacts using the FFI library, which has been greatly appreciated. However, this has also highlighted some ambiguities in how best to use the FFI for message interactions. Clarifying these distinctions will improve usability and reduce confusion for developers.

Proposed Solution

The goal is to deprecate MessagePactHandle in favor of PactHandle, and MessageHandle in favor of InteractionHandle. Where overlapping functionality exists, a simple deprecation notice will be sufficient initially.

In cases where functionality exclusive to MessagePactHandle or MessageHandle needs to be incorporated into their respective replacements (PactHandle or InteractionHandle), those features should be added before deprecation.

Tasks

[ ] #439
[ ] to identify
[ ] Document how FFI should be used when verifying message pacts

Once the FFI is disambiguated, there is still a need for a clear description as to how messages should be verified by the upstream languages. This is needed because the transport mechanism (e.g., queuing system) is abstracted away and the upstream language needs to handle that.

YOU54F commented 3 months ago

this confused me when trying to create a repro with a v4 pact so clarification is certainly welcome

https://github.com/pact-foundation/pact-reference/pull/437/files#diff-d6fdf640e7952e605d5a425978e18d3aa2606501c1b9743426f76dc5989178daR1458

YOU54F commented 3 months ago

if that deeplink doesnt work this is the test

https://github.com/pact-foundation/pact-reference/blob/37bc38f11969e1f463b02c5b493d66da35b94bc5/rust/pact_ffi/tests/tests.rs#L1458

pact-foundation / pact-reference