feat: Expose pact_matching and pact_models over FFI.

rust/Cargo.toml

@@ -7,6 +7,7 @@
 members = [
     "pact_models",
     "pact_matching",
+    "pact_matching_ffi",
     "pact_mock_server",
     "pact_mock_server_cli",
     "pact_mock_server_ffi",

rust/pact_matching_ffi/.gitignore

@@ -0,0 +1 @@
+/build*

rust/pact_matching_ffi/ARCHITECTURE.md

@@ -0,0 +1,156 @@
+
+# Architecture
+
+The `pact_matching_ffi` crate is built with one goal and a couple constraints.
+The goal is that it expose all of `pact_matching` for use by other languages.
+
+The constraints are:
+
+1. It should be non-invasive (meaning it doesn't require changes to
+   `pact_matching` to, for example, use FFI-friendly types which could be
+   exposed directly to C).
+2. It should introduce limited performance overhead.
+3. It should be easy to call from C.
+4. It should be easy for other languages to wrap.
+5. It should provide strong support for error handling and logging.
+6. It should preserve and document any safety guarantees or requirements. 
+
+The design of the crate is done with these goals in mind. Before getting into
+how the wrapping of `pact_matching` is performed, it's worthwhile to describe
+the mechanisms around it.
+
+## Error Handling
+
+Error handling in Rust is robust, using the `Option` and `Result` types to
+indicate when data may be missing or errors may occur. Error handling in C
+is less powerful, usually using some sentinel values in the return value of
+a function to indicate an error has occured. There is also the `errno` API
+from the C standard library, which permits reporting of a standardized set
+of error codes, but that mechanism doesn't permit custom error information,
+and would require us to create a mapping from all possible `pact_matching`
+errors into `errno` error codes.
+
+Instead, the error handling system in `pact_matching_ffi` is based around
+1) signaling of errors through sentinel values, and 2) permitting C-side
+collection of error messages through the `get_error_message` function.
+This design is based on the work of Michael F. Bryan in the
+[unofficial Rust FFI Guide][ffi_guide], which was based on the error handling
+in `libgit2`.
+
+In short: errors are collected from all FFI code, and stored in a
+thread-local variable called `LAST_ERROR`. The `get_error_message` function
+pulls the latest error message from `LAST_ERROR` and reports it to the
+user. All the mechanisms in `pact_matching_ffi/src/error` exist to handle
+this error collection and reporting.
+
+## Logging
+
+Logging is a crucial part of any application, and just because `pact_matching`
+is being called from another language is no reason to render logging info
+from it unavailable. For this reason, `pact_matching_ffi` provides a way for
+C callers to initialize a logger and direct logging output to a location of
+their choice.
+
+First, they call `logger_init`, which begins the logging setup by creating
+a log dispatcher with no sinks. Then they call `logger_attach_sink` to add
+sinks, to which any logs matching the filtering level will be sent. Finally,
+after all `logger_attach_sink` calls are done, they call `logger_apply` to
+apply the logger and complete setup.
+
+The remainder of the code in `pact_matching_ffi/src/log` is plumbing for this
+logging setup process.
+
+## The `ffi_fn` macro
+
+FFI functions have to be written with some boilerplate. First, they must be
+marked `#[no_mangle]` so their names are exported as-written for C to call.
+Second, they must be marked `pub extern` so they're exported and picked up
+by `cbindgen`, the tool we use for generating the C header which users of
+`pact_matching_ffi` will need.
+
+Then, within the functions themselves, we want to be sure that certain FFI
+information is logged, and that errors are captured and reported consistently
+and correctly.
+
+For this purpose, we use the `ffi_fn` macro, found in
+`pact_matching_ffi/src/util/ffi.rs`. This macro is inspired by a
+[macro of the same name][hyper_macro] from the `hyper` crate's C API
+(created for use of Hyper in `curl`). Our macro does considerably more work
+to capture errors and ensure complete logging, but the idea is the same. The
+macro also ensures panics are captured and packaged up like regular errors.
+This includes panics due to allocation failure, although we don't do anything
+to handle this case specifically.
+
+One thing to note is that most functions using the macro will be written
+slightly differently from normal Rust functions. If the function being
+wrapped is fallible, then a second block is needed after the function body
+block showing what to return in the case of any unexpected failure (usually
+either a null pointer of the appropriate `const`-ness and type, or a
+sentinel integer value signalling an error occurred).
+
+Here's an example of the macro in use.
+
+```rust
+ffi_fn! {
+    /// Get a mutable pointer to a newly-created default message on the heap.
+    fn message_new() -> *mut Message {
+        let message = Message::default();
+        ptr::raw_to(message)
+    } {
+        ptr::null_mut_to::<Message>()
+    }
+}
+```
+
+For destructors, or other functions which have no return value, no second
+block is required.
+
+```rust
+ffi_fn! {
+    /// Destroy the `Message` being pointed to.
+    fn message_delete(message: *mut Message) {
+        ptr::drop_raw(message);
+    }
+}
+```
+
+## Opaque Pointers
+
+The `pact_matching_ffi` crate is [_non-invasive_][non_invasive], meaning it
+doesn't involve the modification of types in `pact_matching` to be exposable
+over the FFI boundary (which would at minimum mean marking them `#[repr(C)]`).
+Instead, we expose types in almost all cases as an "opaque pointer," meaning
+C knows the _name_ of the type, but not its _contents_, and works only with
+pointers to that type.
+
+On the one hand, this is convenient, because it keeps the FFI boundary clear
+and separate. On the other hand, it means that C code has to make function
+calls to the Rust side rather than accessing fields directly, and that certain
+optimizations may be missed because of the indirection. This can be addressed
+at least in part through use of cross-language [Link Time Optimization (LTO)][lto]
+
+## Strings
+
+For the most part, to avoid issues with buffer sizing and fallible operations
+against output parameters, the `pact_matching_ffi` crate is designed, when
+returning strings, to return them as `const char *`, pointing to a
+heap-allocated string buffer which must be deleted by calling the provided
+`string_delete` function when finished.
+
+One exception is returning the error message, where the user provides a buffer
+and the size of that buffer, and the operation to fill the buffer with the
+error message may fail. This is because error handling is expected to be very
+common, so buffer reuse is ideal.
+
+Additionally, `pact_matching_ffi` returns exclusively UTF-8-encoded strings,
+and expects all strings it receives to be UTF-8 encoded.
+
+## Buffers
+
+Whenever `pact_matching_ffi` writes to a buffer, it zeroes out any excess
+capacity in the buffer for security reasons.
+
+[ffi_guide]: https://michael-f-bryan.github.io/rust-ffi-guide/errors/index.html
+[hyper_macro]: https://github.com/hyperium/hyper/blob/master/src/ffi/macros.rs
+[non_invasive]: https://www.possiblerust.com/guide/inbound-outbound-ffi#non-invasive-outbound-ffi
+[lto]: http://blog.llvm.org/2019/09/closing-gap-cross-language-lto-between.html