feat: Expose pact_matching and pact_models over FFI.

[alilleybrinker]

This is a fairly large PR, so I'll break it down.

This PR introduces a new crate, called pact_matching_ffi, which exposes the internals of pact_matching and some from pact_models for use by other languages over an FFI.

The design and decisions are documented in the ARCHITECTURE.md file. Specifically, it is a non-invasive FFI design, meaning it involves no changes to the contents of the crates it's exposing. The other design decisions stem from this.

The intent of the introduction of this crate is to make it easier to build other language implementations of Pact by having them call the reference implementation under the hood, something my team has already begun doing.

It's built with CMake (a relatively recent version), and includes finder modules for Cargo and cbindgen. It does require a nightly Cargo version to run cbindgen, because the FFI-exposed functions are defined inside of a macro which can only be expanded for use by cbindgen using an unstable flag on rustc. The CMakeLists.txt file checks that a nightly version of Cargo is being used, as without this check an attempt to run the cbindgen step of the CMake build process would error out after a substantial time with an inscrutable error message.

Happy to talk through the design decisions here. We've tried to document the safety and error handling concerns as thoroughly as possible.

This work was done by @cstepanian and @alilleybrinker (me).

Notice

This software was produced for the U. S. Government under Contract No. FA8702-20-C-0001, and is subject to the Rights in Noncommercial Computer Software and Noncommercial Computer Software Documentation Clause DFARS 252.227-7014 (FEB 2014)

Approved for Public Release; Distribution Unlimited. Case Number 19-3203.

(c) 2021 The MITRE Corporation. All Rights Reserved.

[uglyog]

Awesome PR, the patterns will be useful in the other FFI crates as well

[uglyog]

@alilleybrinker I'm having some trouble getting the pact_matching_ffi crate building on CI (GH Actions). I don't have much CMake knowledge, so if someone could review that changes it would be appreciated.

The CMake files needed to be modified in the following manor:

• CMake build fails if doxygen is not present (i.e. on Windows and OSX agents). I was able to put a conditional around it.
• In PactMatchingFfiConfig.cmake.in, set(IMPORT_NAME "") for non-windows causes set_target_properties to fail. I put another conditional around that.
• The CMake build expects output lib files to be named pact_matching_ffi.* but the Rust build generates files with lib prefixed (i.e. libpact_matching_ffi.a)

One issue I could not fix was cbindgen was not generating synthetic structs for the Consumer and Provider Rust struts, so the example projects fail to build. I could not work out why, but those structs are not really required, because they are just used to get the name via a method, so we could just pass in the MessagePact class here instead.

I.e. change

    MessagePact *message_pact = message_pact_new_from_json(file_name, json_str);
     if (message_pact == NULLPTR) {
         // handle error.
     }
    
     Consumer *consumer = message_pact_get_consumer(message_pact);
     if (consumer == NULLPTR) {
         // handle error.
     }
    
     char *name = consumer_get_name(consumer);
     if (name == NULL) {
         // handle error.
     }

to

    MessagePact *message_pact = message_pact_new_from_json(file_name, json_str);
     if (message_pact == NULLPTR) {
         // handle error.
     }
    
     char *name = message_pact_get_consumer_name(message_pact);
     if (name == NULL) {
         // handle error.
     }

[alilleybrinker]

@uglyog we're happy to take a look! I'll hand this off to @cstepanian who was the other contributor to this new crate.

The issue of not generating struct names for Consumer and Provider is interesting. I think it may be because of this line in the cbindgen.toml file, which specifies the dependent crates to process for possible FFI-exposure. Even though pact_matching_ffi re-exports from pact_models, without pact_models also being shown here the symbols likely aren't getting output, as you've observed. This was an oversight on my part.

I think with fixing this that the other API change you show here won't be necessary.