Pact FFI Tracking Issue

[JP-Ellis]

📝 Background

Pact Python at present makes use of the Ruby executables. The main functionality of the Ruby executables has been replaced by a core library written in Rust (pact-foundation/pact-reference). This library exposes a foreign function interface which other languages can leverage without the need to re-implement a lot of the logic. The core library helps to maintain parity across the different clients and helps with the adoption of new features.

⤴️ Migration Plan

This change will introduce some breaking changes where needed, but it will be done in a staged manner to give everyone the opportunity to migrate.

🚧 Stage 1 (from v2.2)

• The main Pact Python library remains the same. Bugs and minor features will continue to be added to the existing library, but no new major features will be added as the focus will be on the new library.
• The new library is exposed within pact.v3 and can be used alongside the existing library. During this stage, no guarantees are made about the stability of the pact.v3 module.
• Users are not recommended to use the new library in any production critical code at this stage, but are encouraged to try it out and provide feedback.
• The existing library will raise PendingDeprecationWarning warnings when it is used (if these warnings are enabled).

🛠️ Stage 2 (from v2.3, tbc)

• The library within pact.v3 is considered generally stable and users are encouraged to start migrating to it.
• A detailed migration guide will be provided.
• The existing library will raise DeprecationWarning warnings when it is used to help raise awareness of the upcoming change.
• This stage will likely last a few months to give everyone the opportunity to migrate.

🚀 Stage 3 (from v3)

• The pact.v3 module is renamed to pact
  • People who have previously migrated to pact.v3 should be able to do a s/pact.v3/pact/ and have everything work.
  • If the previous stage identifies any breaking changes as necessary, they will be made at this point and a detailed migration guide will be provided.
• The existing library is moved to the pact.v2 scope.
  • ‼️ This will be a very major and breaking change. Previous code running against v2 of Pact Python will not work against v3 of Pact Python.
  • Users still wanting to use the v2 library will need to update their code to use the new pact.v2 module. A s/pact/pact.v2/ should be sufficient.
  • The pact.v2 module will be considered deprecated, and will eventually be removed in a future release. No new features and only critical bug fixes will be made to this part of the library.

✅ Tasks

• Create a Python wheel to bundle the Pact-Rust shared libs #384
• Add PendingDeprecationWarning to the existing library #397
• Implement a thin wrapper for all the FFI functions in the core library #399
• Add support and example for a HTTP consumer test using Rust engine #382
  • Implement all FFI methods relating to Pact #418
  • Implement all FFI methods relating to Interaction #419
• Implement HTTP consumer compatibility suite #420
  • v1/http_consumer.feature #473
  • v2/http_consumer.feature #474
  • v3/http_consumer.feature #475
  • v4/http_consumer.feature #476
• Groundwork API for Provider API using Rust backend #381
• Implement HTTP provider compatibility suite #421
  • v1/http_provider.feature #469
  • v2/http_provider.feature #470
  • v3/http_provider.feature #471
  • v4/http_provider.feature #472
• Add support and example for a message consumer test using Rust engine #380
  • v3/message_consumer.feature
  • v4/message_consumer.feature
• Add support and example for verifying a message provider using the Rust engine #379
  • v3/message_provider.feature
  • v4/message_provider.feature
• Add support and example using V3/V4 matchers and generators #378
• Implement a Matcher interface #746
  • v3/http_matching.feature #759
  • v3/matching_rules.feature
  • v4/matching_rules.feature
• Implement a Generator interface #747
  • v3/http_generators.feature
  • v3/generators.feature
  • v4/generators.feature
• Handle state callbacks in Pact Pyton #748
• Relay messages in Pact Python #749
• Add support and example using V3/V4 support for binary payloads #377
  This may be covered in HTTP consumer/provider implementation above
• Add support and example of a HTTP consumer test using a plugin #376
• Add support and example of verifying a HTTP provider that requires a plugin #375
• Add support and example of a synchronous message consumer test using a plugin (gRPC example) #374
• Add support and example of a synchronous message provider verification using a plugin (gRPC example) #373
• Implement synchronous message compatibility suite:
  • v4/synchronous_message_consumer.feature
  • v4/v4.feature
• Add support and example for a XML consumer test using Rust engine #372
• Stabilise and announce pact.v3, release v2.3 of Pact Python
  • Replace PendingDeprecationWarning with DeprecationWarning
• Create a beta version of Pact-Python that depends on the new wheel #383
• Document migration to v3 of Pact Python
• Release Pact Python v3

🔗 Prior/Related Work

This change has been a long time coming:

• Feat/ffi - load full ffi namespace, initial ffi verifier #357
  Feat/ffi consumer #366
  Feature: PactV3 / VerifierV3 / MessageProvider interface (powered by pact_ffi) #367

  These PRs are all quite large, especially the last with 177 commits and 6.7k lines added. These PRs form the prior attempts to migrate Pact Python to make use of Rust library. While I would have loved to take Feature: PactV3 / VerifierV3 / MessageProvider interface (powered by pact_ffi) #367 on and add to it, I think there's too much in there for a single PR.

  Having said that, a lot of the work done will be re-used in the tasks above.

• Replace ruby plugin #234

  Migrating away from the Ruby executable will resolve this issue.

• Implement FFI interface for Provider #243

  Supplanted by this issue

• Feat/ffi provider #245
  feat: ffi verifier cli #265

  Additional (and very early) PRs with some work on implementing the FFI.

• Contributors wanted: support V3+ of the pact specification (via the pact rust core) #88

  A very early issue detailing the need to implement the FFI core.

[github-actions]

👋 Hi! The 'smartbear-supported' label has just been added to this issue, which will create an internal tracking ticket in PactFlow's Jira (PACT-1353). We will use this to prioritise and assign a team member to this task. All activity will be public on this ticket. For now, sit tight and we'll update this ticket once we have more information on the next steps.

See our documentation for more information.

[canny]

This issue has been linked to a Canny post: Pact V3 Specification for Python 🎉