fgerlits commented on code in PR #2186: URL: https://github.com/apache/nifi-minifi-cpp/pull/2186#discussion_r3604473135
########## minifi_rust/README.md: ########## @@ -0,0 +1,75 @@ +# MiNiFi Native Rust + +This repository provides a safe, idiomatic, and high-performance Rust framework for building native extensions (processors) for [Apache NiFi MiNiFi C++](https://github.com/apache/nifi-minifi-cpp) + +It is designed to offer a robust developer experience, allowing you to write powerful and reliable data processing components in safe Rust. + +The framework completely encapsulates the unsafe C FFI (Foreign Function Interface) boundary, providing a pure Rust API that is fully mockable for unit testing. + +## Project Philosophy + - **Safety First**: Leverage Rust's compile-time guarantees to prevent common bugs like null pointers, buffer overflows, and data races. + - **Zero-Cost Abstraction**: The safe API wrapper is designed to compile down with zero runtime overhead compared to writing raw C code. + - **Ergonomics**: Provide a clean, idiomatic Rust API that is a pleasure to use. Developers should not need to think about unsafe code or C++ interoperability. + - **Testability**: Every component of a processor's logic should be unit-testable in a pure Rust environment, without needing a C++ host. + - **Cross Platform**: The library should work on all platforms that are supported by [Apache NiFi MiNiFi C++](https://github.com/apache/nifi-minifi-cpp) + - macOS (aarch64) + - Linux (x86_64, aarch64) + - Windows (x86_64) + + +The project is structured as a Cargo workspace with a clear, layered architecture: +### [minifi-native-sys](minifi_native_sys) +Contains the raw, unsafe FFI bindings to the minifi-api.h C API. +### [minifi-native](minifi_native) +Provides the public, safe, and idiomatic Rust API. This is the crate that developers will use to build their processors. +#### API Traits +Pure Rust traits (Processor, ProcessSession, Logger, etc.) that define the abstract behavior of the MiNiFi environment. +#### Higher level API +Pure rust traits that simplify the requirements for a working processor + - FlowFileTransform + - FlowFileSource +#### FFI Wrappers +Concrete structs (CffiSession, CffiLogger, etc.) that implement the API traits by calling the unsafe functions from minifi-native-sys. +#### Thread safety +The trait system differentiates between thread-safe (&self) and single-threaded (&mut self) processors at compile time. +#### Comprehensive Mocking: +A full suite of mock objects allows for fast and reliable unit testing of all processor logic. +### [minifi_native_macros](minifi_native_macros) +Helper crate that includes the procedural macros +### [minifi_rs_behave](minifi_rs_behave) +Run the behave integration tests using Minifi's docker framework. This will test the release artifacts against the latest released [MiNiFi native docker container](https://hub.docker.com/r/apache/nifi-minifi-cpp). +There is a handy alias to initiate all behave tests. + +`cargo behave` + +## Creating an Extension +Building an extension is straightforward. The framework provides a declare_minifi_extension! macro that automatically generates the C-compatible entry points and registers your components. + +```rust +declare_minifi_extension!( + processors: [ + (FlowFileSourceProcessorType, Concurrent, MyFlowFileSource), + (FlowFileTransformProcessorType, Exclusive, MyDataTransformer), + ], Review Comment: There could be a sub-section which explains what the various Processor types are. We should also make it clear that `Concurrent` and `Exclusive` are the same thing as what was called "thread-safe" and "single-threaded" earlier (line 34). -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
