feat: Add DSL method to capture an external reference agaist a V4 Pact interaction

[rholshausen]

Add AddExternalReference to V4 interactions

Adds a new AddExternalReference(group, name, value string) method to all V4 interaction types, allowing external references to be recorded against a Pact interaction.

This is the Go equivalent of the reference() method added to pact-js, and wraps the pactffi_add_interaction_reference function introduced in pact_ffi v0.5.4.

Usage

The method is available on all three V4 interaction types and can be chained with existing builder methods. It may be called multiple times to record references from different systems.

HTTP interactions

  err = p.AddInteraction().
      UponReceiving("get user").                                                                                                                                 
      AddExternalReference("Jira", "TICKET-123", "https://jira.example.com/browse/TICKET-123").
      WithRequest("GET", "/users/123", func(b *V4RequestBuilder) {}).                                                                                            
      WillRespondWith(200, func(b *V4ResponseBuilder) {}).                                                                                                       
      ExecuteTest(t, func(msc MockServerConfig) error {                                                                                                          
          // test consumer code                                                                                                                                  
          return nil                                                                                                                                             
      })                                                                                                                                                         

Asynchronous message interactions

  err = p.AddAsynchronousMessage().
      AddExternalReference("GitHub", "PR-456", "https://github.com/org/repo/pull/456").
      ExpectsToReceive("a user created event").                                                                                                                  
      WithJSONContent(map[string]string{"event": "user.created"}).                                                                                               
      ConsumedBy(handler).                                                                                                                                       
      Verify(t)                                                                                                                                                  

Synchronous message interactions

  err = p.AddSynchronousMessage("ping").
      AddExternalReference("Jira", "TICKET-789", "https://jira.example.com/browse/TICKET-789").                                                                  
      WithRequest(func(r *SynchronousMessageWithRequestBuilder) {
          r.WithJSONContent(map[string]string{"request": "ping"})                                                                                                
      }).                                                
      WithResponse(func(r *SynchronousMessageWithResponseBuilder) {                                                                                              
          r.WithJSONContent(map[string]string{"response": "pong"})
      }).                                                                                                                                                        
      ExecuteTest(t, handler)

Pact file output

References are stored under comments.references[group][name] in the generated Pact file:

  {                                                                                                                                                              
    "comments": {                                        
      "references": {               
        "Jira": {
          "TICKET-123": "https://jira.example.com/browse/TICKET-123"
        }                                                                                                                                                        
      }
    }                                                                                                                                                            
  }                                                      

Changes

File	Change
internal/native/pact.h	Added pactffi_add_interaction_reference C declaration
internal/native/mock_server.go	Added AddInteractionReference to native Interaction type
internal/native/message_server.go	Added AddInteractionReference to native Message type
consumer/http_v4.go	Added AddExternalReference to V4UnconfiguredInteraction
message/v4/asynchronous_message.go	Added AddExternalReference to AsynchronousMessageBuilder
message/v4/synchronous_message.go	Added AddExternalReference to UnconfiguredSynchronousMessageBuilder
consumer/http_v4_test.go	Added TestV4HTTPAddExternalReference
message/v4/asynchronous_message_test.go	Added TestAsyncAddExternalReference
message/v4/synchronous_message_test.go	Added TestSyncAddExternalReference

[rholshausen]

Just a note that the build is broken because the version of the FFI required has had some deprecated functions removed, namely pactffi_create_mock_server, pactffi_create_mock_server_for_pact and pactffi_verify which pact-go is using.

It will need to be migrated to 0.5.x of the FFI before this PR can be applied.

[mefellows]

@copilot change this and the mock_server.go function to WithReference for consistency with the other APIs, and update usages

[Copilot]

Done in commit 3a66bff. Renamed AddInteractionReference to WithReference in both internal/native/mock_server.go and internal/native/message_server.go, and updated all callers in consumer/http_v4.go, message/v4/asynchronous_message.go, and message/v4/synchronous_message.go.

[Copilot]

Just a note that the build is broken because the version of the FFI required has had some deprecated functions removed, namely pactffi_create_mock_server, pactffi_create_mock_server_for_pact and `...

Fixed in commits 3a66bff and b9fdecc. The three deprecated FFI functions have been replaced:

• pactffi_create_mock_server_for_pact → replaced with pactffi_create_mock_server_for_transport in MockServer.Start()
• pactffi_create_mock_server → removed CreateMockServer() (was test-only); updated mock_server_test.go to use the programmatic NewHTTPPact/NewInteraction API
• pactffi_verify → removed the legacy Verifier.Verify(args) method; the handle-based API (NewVerifier, Execute) was already in place

The build now compiles and links successfully against pact_ffi v0.5.4.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 127.0.0.11
  • Triggering command: REDACTED, pid is -1 (packet block)
• www.google-analytics.com
  • Triggering command: /tmp/go-build2204074937/b001/native.test /tmp/go-build2204074937/b001/native.test -test.testlogfile=/tmp/go-build2204074937/b001/testlog.txt -test.paniconexit0 -test.timeout=2m0s -o /tmp/go-build142-p 4/src/runtime/cgvendor/golang.org/x/net/idna .25.0.linux-amd6-lang=go1.25 -p github.com/pact--quiet t .25.0.linux-amd6/root/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.25.0.linux-amd64/src/os/user ut-7�� /home/REDACTED/go//tmp/go-build2799243979/b197/ t .25.0.linux-amd6x86_64-linux-gnu ctor --64 E=3 .25.0.linux-amd6/tmp/ccbwqibD.o (dns block)
  • Triggering command: /tmp/go-build144549719/b001/consumer.test /tmp/go-build144549719/b001/consumer.test -test.testlogfile=/tmp/go-build144549719/b001/testlog.txt -test.paniconexit0 -test.timeout=2m0s -I g_.a -I 0.1-go1.25.0.linux-amd64/pkg/tool/linux_amd64/vet --gdwarf-5 --64 -o 0.1-go1.25.0.lin-o chai�� chain@v0.0.1-go1-l 81c1097Sl /golang.org/tool-- . --gdwarf2 --64 07.o (dns block)
  • Triggering command: /tmp/go-build1612888099/b001/consumer.test /tmp/go-build1612888099/b001/consumer.test -test.testlogfile=/tmp/go-build1612888099/b001/testlog.txt -test.paniconexit0 -test.timeout=2m0s -o /golang.org/tool--gdwarf-5 -trimpath tnet/tools/as -p crypto/internal/--64 _amd64/asm 9243979/b197/_x0/tmp/ccnGn4TO.o --gd�� in.so /lto-wrapper /usr/bin/gcc /tmp/ccPXy2hm.s -c=4 -nolocalimports /usr/bin/gcc (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)