Master issue for v3.0.0 Specification with Native Rust Support

[mefellows]

Summary

This issue tracks the major changes required to get Pact Go to a full v3.0.0 specification support, including integration with the native pact-reference library.

Moving to the native library will solve a number of pre-existing issues, as well as bring a number of positive new changes to the environment:

1. Windows support: There a number of well documented Windows related issues, the primary being the file path restriction (see numerous issues in pact js/pact node relating to tis)
2. Speed: the version of Traveling Ruby we use is pinned to 2.2 - quite old. This seems to run quite slowly even on modern hardware. Additionally, because we bundle an entire Ruby runtime certain OSs (particularly corporate machines) see Ruby as a threat, and will pre-emptively scan causing builds to slow down. Rust is fast.
3. Security: following from (2), there are some known vulnerabilities in some of the Gems present in the runtime. Whilst we have vetted these issues, it can throw up a red flag which may preclude the use of Pact altogether even if they are false positives.
4. Support for modern Pact features in the v3 and v4 specification, things like XML matching, binary payloads and more.
5. Mac security: recently, Mac has introduced a sandbox for unsigned binaries where manual human intervention is required to allow use before first execution. The impact has not been assessed yet, but it does seem likely it will cause issues.

Current Status

https://github.com/pact-foundation/pact-go/projects/2

Active work in progress: initial consumer and provider API has been implemented for both HTTP and Message pacts. Code is in an experimental state, and is not ready for external testing.

Dates: The current target is to have a beta by Q4 2020 calendar year.

Branch: https://github.com/pact-foundation/pact-go/tree/feat/v2.0.0

If you are interested in being an early tester of a beta branch, please get in contact at slack.pact.io or pact-foundation.slack.com in the #pact-go channel.

Audience

This issue is initially for Pact library maintainers, to document and discuss the implementation of the native Rust library into Pact Go.

Feature Overview: Specification Version 3.0

(see https://github.com/pact-foundation/pact-go/tree/feat/v2.0.0 for current implementation, what is documented below is the known delta).

Consumer Side

• Split v3 functionality into separate sub-package
• New v3 matchers
  • Minmax matcher https://github.com/pact-foundation/pact-specification/tree/version-3#add-a-minmax-type-matcher
  • Equality matcher https://github.com/pact-foundation/pact-specification/tree/version-3#add-an-equality-matcher
  • Include matcher https://github.com/pact-foundation/pact-specification/tree/version-3#add-an-include-matcher
  • Specific type matchers https://github.com/pact-foundation/pact-specification/tree/version-3#add-more-specific-type-matchers
• Add XML matching DSL
• Implement provider state parameters
• Matcher support for query parameters
• Matcher support for headers
• Matcher support for paths
• Message Pact Consumer DSL
• JSON Generators
• XML Generators
• Support generators in struct tags
• Support running tests in parallel
• Multiple provider states
• Query strings as maps (https://github.com/pact-foundation/pact-specification/tree/version-3#query-strings-are-stored-as-map-instead-of-strings)
• Mac Support
• Linux Support
• Windows 32bit support
• Windows 64 bit support
• TLS support
• TLS with user-provided (self-signed) certificates

Provider Side

• Handle provider state callbacks
• Handle Request Filters
• XML support
• JSON Generators
• XML Generators
• Inject values from provider states
• WIP Pacts
• Pending Pacts
• Multiple provider states
• Provider states with parameters
• Request Filters
• Before/After hooks
• Support Golang in-process debugger
• Message Pact Provider DSL
• TLS support (useful for when pointing at internal environments with self-signed certificates)
• Integration with the go test tool (for sub test output)

Pact Broker Integration

• Consumer version selectors
• Basic Auth
• Bearer / API Key Auth
• Publish verification results
• Tag on verification results (consumer/provider version tags)
• Verify using tags
• Publish pacts
• Tag on publish
• Backwards compatible environment vars (PACT_BROKER_*)
• Verify single pact from file, URL or Pact Broker (NOTE: supported via verifier CLI)
• Support XML rendering / matchers in Pactflow

Rust integration activities

• Ensure consistent logging between Go and Rust framework
• Native (that is, it should look native to Go) support for TLS
• Serialise pact go version into metadata body (Rust may need to support this pass through)

Release Activities

• Update usage documentation
• Create Developer Documentation
• Support Alpine linux (MUSL)
• Upgrade advice/documentation
• Allow customisation of shared lib path (e.g. https://github.com/pact-foundation/pact-node#pact-download-location)
• Migration guide from v1
• Migration guide from 0.0.13

Miscellaneous

• Support users manually downloading the Rust dependency, and specifying the path (see https://github.com/pact-foundation/pact-node#installation)
• Track downloads/installs (as per https://github.com/pact-foundation/pact-node#installation)
• Support Golang in-process debugger
• Update Rust FFI docs (seem to be out of date and broken links to www.pact.io)
• Instrumentation to log incoming/outgoing requests and transformations

[scraymondjr]

Any update on this, since the noted target release date (calendar Q4 2020) is a ways behind us now?

[mefellows]

We currently have a beta and are seeking feedback: https://github.com/pact-foundation/pact-go#v3-beta

See also: https://github.com/pact-foundation/pact-go/projects/2