Pact 2.x.x Consumer API

[mefellows]

Background / Problem
See this Draft PR for background.

Seeing version numbers as part of function names in an exported API is a bit awkward, leading to this sort of thing:

	// V2 specification
	mockProvider, err := consumer.NewV2Pact(consumer.MockHTTPProviderConfig{
		Consumer: "PactGoV2ConsumerMatch",
		Provider: "V2ProviderMatch",
		Host:     "127.0.0.1",
		TLS:      true,
	})

	// V3 Specification
	mockProvider, err := NewV3Pact(MockHTTPProviderConfig{
		Consumer: "PactGoV3Consumer",
		Provider: "V3Provider",
		Host:     "127.0.0.1",
		TLS:      true,
	})

        // We have a similarly named method for Messages also
	provider, err := NewMessagePactV3(MessageConfig{
		Consumer: "PactGoV3MessageConsumer",
		Provider: "V3MessageProvider", // must be different to the HTTP one, can't mix both interaction styles
	})

1. Given the interface is so similar, could we look to combine them and reduce the noise in the API?
2. Could Messages be amalgamated into a single entry point also or should they remain separate?

Challenges

1. There are some features of the V3 API that aren't compatible with the V2 one. For example, parameters on provider states (GivenWithParam) and multiple states per interaction. V2 doesn't support Message Pact which is currently supported via a separate API.

(see the full list here: https://github.com/pact-foundation/pact-specification/tree/version-3)

2. The v4 adds some significant differences, most notably extension via plugins and synchronous messages. These won't be available to previous APIs.

Example plugin API:

    let csv_service = PactBuilder::new_v4("CsvClient", "CsvServer")
      .using_plugin("csv", None).await
      .interaction("request for to store a report", "core/interaction/http", |mut i| async move {
        i.request
          .path("/reports/report001.csv")
          .method("POST")
          .contents(ContentType::from("text/csv"), json!({
            "csvHeaders": false,
            "column:1": "matching(type,'Name')",
            "column:2": "matching(number,100)",
            "column:3": "matching(datetime, 'yyyy-MM-dd','2000-01-01')"
          })).await;

(via https://github.com/pact-foundation/pact-plugins/blob/7378ab4846a60af7513d69f6ea4c2fdd3c19363f/examples/csv/csv-consumer-rust/src/lib.rs#L87-L98)

Solution Proposal 1: Functional Options

See this article for more on the pattern.

It would result in an interface that looks more like this:

        // V2 Specification
	mockProvider, err := NewPact(MockHTTPProviderConfig{
		Consumer: "PactGoProductAPIConsumer",
		Provider: "PactGoProductAPI",
	}, consumer.OptionV2Pact())

Whilst this is more visually appealing, it doesn't address the challenges brought with v4 and we'd need to work around things that aren't compatible in v2 (probably manageable).

Solution Proposal 2: Type state pattern

	// V2 Specification
	mockProvider, err := NewPact(MockHTTPProviderConfig{
		Consumer: "PactGoProductAPIConsumer",
		Provider: "PactGoProductAPI",
	}).WithV2Specification()
		.AddInteraction()
		...

	// V3 Specification
	mockProvider, err := NewPact(MockHTTPProviderConfig{
		Consumer: "PactGoProductAPIConsumer",
		Provider: "PactGoProductAPI",
	}).WithV3Specification()
		.AddInteraction()
		...
		.AddMessage() // NOTE: would NOT be allowed alongside AddInteraction

	// V4 Specification
	mockProvider, err := NewPact(MockHTTPProviderConfig{
		Consumer: "PactGoProductAPIConsumer",
		Provider: "PactGoProductAPI",
	}).WithV4Specification()
		.AddInteraction()
		...
		.AddMessage() // NOTE: would be allowed alongside the other interaction types
		...
		.AddSyncMessage() // NOTE: would be allowed alongside the other interaction types
		...
		.WithPlugin() // NOTE: would be allowed alongside the other interaction types

The upside of this approach, is that you still start with a single entrypoint and can control what behaviour is allowed via the return types, and ensure the system can't get into an invalid state. The main draw back is that there is more types that would need managing from a Maintainer perspective.

[dabfleming]

Glad to see the discussion get started and a good outline of the questions / challenges.

Some questions on this block from the proposed Type State Pattern example (final code block):

	// V3 Specification
	mockProvider, err := NewPact(MockHTTPProviderConfig{
		Consumer: "PactGoProductAPIConsumer",
		Provider: "PactGoProductAPI",
	}).WithV2Specification()
		.AddInteraction()
		...
		.AddMessage() // NOTE: would NOT be allowed alongside AddInteraction

• I assume the WithV2Specification() is a typo and should be V3.
• Interactions and messages are currently split between consumer.NewV3Pact(conf).AddInteraction() and message.NewMessagePactV3(conf).AddMessage() (error handling removed for brevity), but in this example are shown together. Are you thinking of unifying the API for Interactions and Messages currently? Can Interactions and Message pacts not be represented together in the same v3 pact file? For some reason I thought this was possible.

I have some other thoughts but some of it is dependent on answers to the above questions.

One question I did have... Is it possible to just not support V2 pact creation in pact-go@v2? The provider would still be able to verify existing v2 pacts but part of migrating to pact-go@v2 would be migrating any pact creation to v3, which doesn't impose any loss of functionality, only a slightly greater difference in the API. As a code change is required as part of the migration anyway, impact seems minimal to me, but there may be factors I am missing.

[mefellows]

• I assume the WithV2Specification() is a typo and should be V3.

Yep, that was a mistake thanks. Fixed.

• Interactions and messages are currently split between consumer.NewV3Pact(conf).AddInteraction() and message.NewMessagePactV3(conf).AddMessage() (error handling removed for brevity), but in this example are shown together. Are you thinking of unifying the API for Interactions and Messages currently? Can Interactions and Message pacts not be represented together in the same v3 pact file? For some reason I thought this was possible.

They can't in the v3 spec, but it is supported in v4. That does present a challenge for the API, unfortunately.

One question I did have... Is it possible to just not support V2 pact creation in pact-go@v2? The provider would still be able to verify existing v2 pacts but part of migrating to pact-go@v2 would be migrating any pact creation to v3, which doesn't impose any loss of functionality, only a slightly greater difference in the API. As a code change is required as part of the migration anyway, impact seems minimal to me, but there may be factors I am missing.

I did seriously consider it, but I don't believe it is the right thing to do. We need to support v2 in Pact Go, because one of the key benefits of Pact is interoperating with other languages. Not all languages will be able to support the latest versions, and not all users will be able to immediately upgrade either. Forcing them to do so is not ideal, despite it being much easier for us! We currently have 12 other languages that we need to interoperate with, so it's a non-trivial problem.

Of course, people could still use the current 1.x.x branch for this purpose, but I'd like to deprecate that as soon as possible because that will create more of a maintenance burden than supporting it in the new 2.x.x line. I don't think V2 creates a significant burden on the new API, because there are differences between V3 and V4 that we'll need to account for anyway, and probably V4 to V5 when that happens (i.e. I assume the API will continue to evolve in ways we can't predict).