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.

[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.

[mrlubos]

Hey @mefellows, thank you for your work on v3! Is there any approximate release date for this version?

[mefellows]

Thanks! There is some really good progress happening. So perhaps I can give an update:

The shared core (used across all new projects) has pretty much everything we need to move forward, except for 3 things: the ability to log into it (for consistent logging), verifying metadata in message pacts and supporting XML.

pact-js-core has the FFI bindings for the provider added, and a branch has been created bi @TimothyJones that shows it's almost compatible with the current interface (this would support both v2 and v3 pacts). Message support is the only lacking feature.

Once the ability to log into the core, and message can be verified and it's been tested thoroughly, I think we can release the provider verification into main.

From there, we need to then add consumer bindings into pact-js-core, and then update the consumer DSL. There is more API design work there. It's not difficult, but might require a few iterations.

TL;DR - a couple of months away I'd say. In case it's not clear above, there is a v3 beta release that you can use. It's not stable yet, so a few API changes are likely to occur.

@TimothyJones anything else you'd like to add as an update?

[TimothyJones]

I think that is an excellent summary!

The only thing I’d add is that we are an open source project, so development ebbs and flows with the availability of contributors. I’m very excited about getting V3 out the door, though, since it’s clearly going to be useful for a lot of people (and as maintainers, pulling this into main is going to make our lives a lot easier). It is definitely the number one priority.

[mrlubos]

Thank you both @mefellows @TimothyJones.

[KevinConti]

Hey contributors. The last update on this discussion was over a year ago. Has PactJS finished v3 support in that time?

[mefellows]

Ah yes, the latest version (10.x.x) supports v3 and more, and has been out as a stable release for a few months now. The main readme should get you going