martinzink commented on code in PR #2186: URL: https://github.com/apache/nifi-minifi-cpp/pull/2186#discussion_r3636918215
########## minifi_rust/README.md: ########## @@ -0,0 +1,96 @@ +# MiNiFi Native Rust (tech preview) + +> ⚠️ **Tech Preview** +> +> Only the **Rust bindings** are a technology preview. The Rust source API +> (both the `minifi-native` safe API and the `minifi-native-sys` FFI layer) +> is still evolving, and we are **not yet committed to source-level backward +> compatibility** for the Rust bindings — expect breaking changes in the +> Rust API between MiNiFi C++ releases until the bindings are declared +> stable. +> +> Under the hood, the bindings target the **stable MiNiFi C API**, which +> *does* provide backward compatibility. This means the compiled artifact +> is unaffected by Rust-side churn: an extension built against an older +> version of these bindings will keep loading into newer MiNiFi C++ +> releases. You only need to rebuild against the new bindings if you want +> to pick up new Rust API features — upgrading the agent alone does not +> force a rebuild. + +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. Pick the one that matches your processor's shape — the wrapper takes care of getting/creating the flowfile, wiring up streams, applying attributes, and transferring to the right relationship, so your code only needs to describe the transformation itself. + - [FlowFileTransform](minifi_native/src/api/processor_wrappers/flow_file_transform.rs) + - Consumes a single incoming flowfile, optionally rewrites its content (returned as an in-memory buffer) and/or adds attributes, then routes it to a relationship. Best for buffered, one-in / one-out transforms. Review Comment: the FlowFileStreamTransform allows simultanous read/write (e.g. AsciifyGerman processor) which is not possible with the simple FlowFileTransform (but that does allow easier returns) -- 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]
