V3 Specification Release

[mefellows]

Summary

This issue tracks the major changes required to get Pact JS 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 Path length for nested Ruby files is excessive. #64 and a number in the pact-node repo)
2. Confusion between Pact Node and Pact JS (pact-js vs. pact-node #408)
3. 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.
4. Security: following from (3), 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.
5. Support for modern Pact features in the v3 and v4 specification, things like XML matching, binary payloads and more.

Current Status

Beta (see "beta" tag https://www.npmjs.com/package/@pact-foundation/pact)

npm i @pact-foundation/pact@beta

See https://github.com/pact-foundation/pact-js#pact-js-v3 for examples on how to use the package.

Feature Overview: Specification Version 3.0

(see https://github.com/pact-foundation/pact-js/tree/feat/v3.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
• Add XML matching DSL
• Implement provider state parameters (Provider state parameters not implemented #372)
• Matcher support for query parameters
• Matcher support for headers
• Matcher support for paths
• Message Pact Consumer DSL
• JSON Generators
• XML Generators
• Support running tests in parallel
• Multiple provider states
• Mac Support
• Linux Support
• Windows 32bit support
• Windows 64 bit support
• TLS support
• TLS with self-signed certificates

Provider Side

• Handle provider state callbacks (Provider state parameters not implemented #372)
• Handle Request Filters
• XML support
• JSON Generators
• XML Generators
• Inject values from provider states
• WIP Pacts
• Pending Pacts
• Multiple provider states
• Native Provider States (incl. support for promises)
• Provider states with parameters
• Request Filters
• Before/After hooks
• Support Node in-process debugger
• Message Pact Provider DSL
• TLS support (useful for when pointing at internal environments with self-signed certificates)

Rust integration activities

• Ensure consistent logging between JS and Rust framework
• Natively (that is, it should look native to Node) support for TLS

Release Activities

• Update builds to release native Pact JS (Neon) extension to all os/arch/node version combinations
• Update usage documentation
• Create Developer Documentation
• Add OSX builds on Travis
• Add security audit to builds (https://github.com/RustSec/cargo-audit)
• Support Alpine linux (MUSL)
• Allow customisation of shared lib path (e.g. https://github.com/pact-foundation/pact-node#pact-download-location)
• Renable linting (and fix any issues) - see Consolidate linting and formatting in examples #586 and fix: Linting code #584 for some context.

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

Miscellaneous

• Full TypeScript type definitions
• Support users manually downloading the Rust dependency, and specifying the path (see https://github.com/pact-foundation/pact-node#installation)
• Track Pact JS downloads (as per https://github.com/pact-foundation/pact-node#installation)
• Pact Node - update documentation to describe it's purpose in life
• Support Node in-process debugger
• Update Rust FFI docs (seem to be out of date and broken links to www.pact.io)
• Compatibility / Consideration for jest-pact and related community projects
• Instrumentation to log incoming/outgoing requests and transformations

Pact Web Support

The current way of running Pact with Rust will not work - we may need to look at WebAssembly or another alternative for this.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[FRosner]

Hi @mefellows!

I was wondering about "Implement provider state parameters (#372)". The box is checked but I'm unable to find the code anywhere. In #372 you mentioned that you wanted to create a separate issue to track that but I was unable to locate this one as well.

What I wanted to do is to formulate a contract that has multiple provider states so I can compose them as outlined in https://github.com/pact-foundation/pact-specification/tree/version-3#allow-multiple-provider-states-with-parameters:

Is it correct that this is not supported in the current v3 branch?

Edit: I can get this to work even with the current latest (non-beta) version by ignoring TypeScript and passing an array instead of a string:

provider.addInteraction({
  state: [
    {'name': 'customer exists'},
    {'name': 'user is logged in'}
  ],
  ...
});

[mefellows]

The above list is a bit of a WP a checklist for Ron and I when working through the new v3 (native) branch: https://github.com/pact-foundation/pact-js/tree/feat/v3.0.0

The multiple/parameters are still TBC in the main version, but you can test it our in the beta v3 branch: see https://github.com/pact-foundation/pact-js/#pact-js-v3

It is functional and has some new powerful v3 features (+ XML support). Just note that there are still outstanding features required for it to be a production ready thing, but any feedback of course would be great.

[FRosner]

Thanks @mefellows. I got what you are saying (read the README) but unfortunately I was not able to see this change in the beta version or even in the feat/v3.0.0 branch. So I was wondering if I was missing something.

However, no worries, as I was able to work around that by simply putting the multiple states even in the existing version.

[mefellows]

Yes, it "sort of" works by accident the way it is today (but you don't get parameters, although they may also accidentally work also. See #407)

See this on the v3 branch https://github.com/pact-foundation/pact-js/blob/feat/v3.0.0/examples/v3/e2e/test/consumer.spec.js#L171-L172. You can pass in params too

[FRosner]

I found the example you linked as well but when I look at the code (https://github.com/pact-foundation/pact-js/blob/feat/v3.0.0/src/dsl/interaction.ts#L54 and https://github.com/pact-foundation/pact-js/blob/feat/v3.0.0/src/dsl/interaction.ts#L38) I can't see how this is supposed to actually work. Am I looking at the right place?

[mefellows]

That branch still contains both code bases - all of the V3 exports are in the src/v3 folder e.g. https://github.com/pact-foundation/pact-js/blob/feat/v3.0.0/src/v3/pact.ts.

When the v3 branch is released, it will still have backwards-compatible support for the previous versions, so we've ported the new stuff to a separate package. Hope that makes sense.