MINIFICPP-2850 Finalize stable API before 1.0 (#2205)

This commit finalizes the “stable” MiNiFi C/C++ extension API surface in preparation for a 1.0 release by renaming and normalizing exported C symbols/headers, updating the C++ extension framework wrappers, and migrating extensions/tests to the new API (including new metrics reporting and trigger-when-empty control paths).

* removed MINIFI_NULL
* removed struct typedefs
* snake_case type and function names
* removed stdbool.h, in C23, bool, true, and false are keywords
* PropertyDefinition: type -> allowed_type
* getTriggerWhenEmpty member -> setTriggerWhenEmpty free function, to be called from onSchedule
* onTrigger -> trigger, onSchedule -> schedule, onUnSchedule -> unschedule
* calculate_metrics -> call report_metrics on process_context instead of callback
* processor_class_definition: removed class_ prefixes from members
* minifi-c.h -> minifi-api.h
* removed get/setTriggerWhenEmpty from ProcessorApi
* moved MinifiLoggerSetMaxLogSize, MinifiLoggerLevel to AdvancedLogger
* moved AdvancedLogger.h to minifi-api/include/minifi-cpp/core/logging/AdvancedLogger.h
* minifi_processor_class_definition -> minifi_processor_definition
* minifi_controller_service_class_definition -> minifi_controller_service_definition
* removed <= c23 workarounds
* removed unused macro magic

Author: martinzink

.clang-format

@@ -5,10 +5,11 @@ AlignConsecutiveAssignments: None
 AlignOperands: DontAlign
 AllowAllParametersOfDeclarationOnNextLine: true
 AllowAllConstructorInitializersOnNextLine: false
-AllowShortBlocksOnASingleLine: Always
-AllowShortCaseLabelsOnASingleLine: true
-AllowShortFunctionsOnASingleLine: Inline
-AllowShortIfStatementsOnASingleLine: Always
+AllowShortBlocksOnASingleLine: Empty
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortEnumsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: WithoutElse
 AllowShortLambdasOnASingleLine: All
 AllowShortLoopsOnASingleLine: false
 AlwaysBreakAfterReturnType: None

.github/references/ubuntu_22_04_clang_arm_manifest.json

@@ -11089,13 +11089,13 @@
                 "type": "org.apache.nifi.minifi.api_testing.DogController",
                 "providedApiImplementations": [
                     {
-                        "artifact": "minifi-system",
-                        "group": "org.apache.nifi.minifi",
+                        "artifact": "minifi-stable-api-testing",
+                        "group": "org.apache.nifi.minifi.api_testing",
                         "type": "org.apache.nifi.minifi.api_testing.CanFlyControllerApi"
                     },
                     {
-                        "artifact": "minifi-system",
-                        "group": "org.apache.nifi.minifi",
+                        "artifact": "minifi-stable-api-testing",
+                        "group": "org.apache.nifi.minifi.api_testing",
                         "type": "org.apache.nifi.minifi.api_testing.NumberOfLegsControllerApi"
                     }
                 ]
@@ -11107,13 +11107,13 @@
                 "type": "org.apache.nifi.minifi.api_testing.DuckController",
                 "providedApiImplementations": [
                     {
-                        "artifact": "minifi-system",
-                        "group": "org.apache.nifi.minifi",
+                        "artifact": "minifi-stable-api-testing",
+                        "group": "org.apache.nifi.minifi.api_testing",
                         "type": "org.apache.nifi.minifi.api_testing.CanFlyControllerApi"
                     },
                     {
-                        "artifact": "minifi-system",
-                        "group": "org.apache.nifi.minifi",
+                        "artifact": "minifi-stable-api-testing",
+                        "group": "org.apache.nifi.minifi.api_testing",
                         "type": "org.apache.nifi.minifi.api_testing.NumberOfLegsControllerApi"
                     }
                 ]

.github/workflows/create-release-artifacts.yml

@@ -95,8 +95,8 @@ jobs:
           mkdir minifi-native-sdk
           
           cp behave_framework/dist/*.whl minifi-native-sdk/
-          cp minifi-api/minifi-c-api.def minifi-native-sdk/
-          cp minifi-api/include/minifi-c/minifi-c.h minifi-native-sdk/
+          cp minifi-api/minifi-api.def minifi-native-sdk/
+          cp minifi-api/include/minifi-api.h minifi-native-sdk/
           
           zip -r minifi-native-sdk.zip minifi-native-sdk/
 

Extensions.md

@@ -20,36 +20,36 @@ To enable all extensions for your platform, you may use -DENABLE_ALL=TRUE OR sel
 Extensions are dynamic libraries loaded at runtime by the agent.
 
 ## C extensions
-You can build shared libraries using the API defined in `minifi-c.h`
-For the shared library to be considered a valid extension, it must export a global symbol with the name `MinifiApiVersion`
-with its value equal to the uint32_t constant `MINIFI_API_VERSION` from `minifi-c.h`.
+You can build shared libraries using the API defined in `minifi-api.h`
+For the shared library to be considered a valid extension, it must export a global symbol with the name `minifi_api_version`
+with its value equal to the uint32_t constant `MINIFI_API_VERSION` from `minifi-api.h`.
 
 ### Resource Lifetime
 
-Unless otherwise specified, the following lifetime rules apply to all functions called by the agent (e.g., `MinifiInitExtension`, `MinifiProcessorCallbacks::onTrigger`, or other callbacks):
+Unless otherwise specified, the following lifetime rules apply to all functions called by the agent (e.g., `minifi_init_extension`, `minifi_processor_callbacks::trigger`, or other callbacks):
 
 * Arguments: The lifetime of any resource provided as a function argument is limited to the duration of that function call.
 
-* Created Resources: The lifetime of resources created within these functions (e.g., a handle returned by `MinifiProcessSessionGet` inside `MinifiProcessorCallbacks::onTrigger`)
+* Created Resources: The lifetime of resources created within these functions (e.g., a handle returned by `minifi_process_session_get` inside `minifi_processor_callbacks::trigger`)
 is limited to the scope of the innermost callback.
-(the return value of `MinifiRegisterExtension` is only valid during the execution of `MinifiInitExtension`).
+(the return value of `minifi_register_extension` is only valid during the execution of `minifi_init_extension`).
 
-Because of these scoping rules, all processor and controller service registrations must occur within the `MinifiInitExtension` call.
+Because of these scoping rules, all processor and controller service registrations must occur within the `minifi_init_extension` call.
 One possible example of this is:
 
 ```C++
-extern "C" const uint32_t MinifiApiVersion = MINIFI_API_VERSION;
+extern "C" const uint32_t minifi_api_version = MINIFI_API_VERSION;
 
-extern "C" void MinifiInitExtension(MinifiExtensionContext* extension_context) {
-  MinifiExtensionDefinition extension_definition{
+extern "C" void minifi_init_extension(minifi_extension_context* extension_context) {
+  minifi_extension_definition extension_definition{
     .name = minifi::api::utils::toStringView(MAKESTRING(EXTENSION_NAME)),
     .version = minifi::api::utils::toStringView(MAKESTRING(EXTENSION_VERSION)),
     .deinit = nullptr,
     .user_data = nullptr
   };
-  auto* extension = MinifiRegisterExtension(extension_context, &extension_definition);
-  minifi::api::core::useProcessorClassDefinition<minifi::extensions::llamacpp::processors::RunLlamaCppInference>([&] (const MinifiProcessorClassDefinition& definition) {
-    MinifiRegisterProcessor(extension, &definition);
+  auto* extension = minifi_register_extension(extension_context, &extension_definition);
+  minifi::api::core::useProcessorClassDefinition<minifi::extensions::llamacpp::processors::RunLlamaCppInference>([&] (const minifi_processor_definition& definition) {
+    minifi_register_processor(extension, &definition);
   });
 }
 ```
@@ -73,18 +73,18 @@ REGISTER_RESOURCE(RESTSender, DescriptionOnly);
 ```
 
 Some extensions (e.g. `Python`) require initialization before use.
-You need to define an `MinifiInitCppExtension` function of type `MinifiExtension*(MinifiExtensionContext*)` to be called.
+You need to define an `minifi_init_cpp_extension` function with signature `void minifi_init_cpp_extension(minifi_extension_context*)` to be called.
 
 ```C++
-extern "C" void MinifiInitCppExtension(MinifiExtensionContext* extension_context) {
+extern "C" void minifi_init_cpp_extension(minifi_extension_context* extension_context) {
   static PythonLibLoader python_lib_loader([&] (std::string_view key) -> std::optional<std::string> {
     std::optional<std::string> result;
-    MinifiConfigGet(extension_context, minifi::utils::toStringView(key), [] (void* user_data, MinifiStringView value) {
+    minifi_config_get(extension_context, minifi::utils::toStringView(key), [] (void* user_data, minifi_string_view value) {
       *static_cast<std::optional<std::string>*>(user_data) = std::string{value.data, value.length};
     }, &result);
     return result;
   });
-  MinifiExtensionDefinition extension_definition{
+  minifi_extension_definition extension_definition{
     .name = minifi::utils::toStringView(MAKESTRING(MODULE_NAME)),
     .version = minifi::utils::toStringView(minifi::AgentBuild::VERSION),
     .deinit = nullptr,

core-framework/include/core/ProcessorImpl.h

@@ -87,14 +87,6 @@ class ProcessorImpl : public virtual ProcessorApi {
 
   std::string getProcessorType() const override = 0;
 
-  void setTriggerWhenEmpty(bool trigger_when_empty) {
-    trigger_when_empty_ = trigger_when_empty;
-  }
-
-  bool getTriggerWhenEmpty() const override {
-    return trigger_when_empty_;
-  }
-
   void initialize(ProcessorDescriptor& self) final;
 
   void setSupportedRelationships(std::span<const RelationshipDefinition> relationships);
@@ -140,8 +132,6 @@ class ProcessorImpl : public virtual ProcessorApi {
 
   ProcessorMetadata metadata_;
 
-  std::atomic<bool> trigger_when_empty_;
-
   std::shared_ptr<ProcessorMetricsExtension> metrics_extension_;
 
   std::shared_ptr<logging::Logger> logger_;

core-framework/src/core/ProcessorImpl.cpp

@@ -44,7 +44,6 @@ namespace org::apache::nifi::minifi::core {
 
 ProcessorImpl::ProcessorImpl(ProcessorMetadata metadata)
     : metadata_(std::move(metadata)),
-      trigger_when_empty_(false),
       logger_(metadata_.logger) {
   logger_->log_debug("Processor {} created with uuid {}", getName(), getUUIDStr());
 }

extension-framework/cpp-extension-lib/include/api/core/ControllerServiceContext.h

@@ -17,25 +17,25 @@
 
 #pragma once
 
-#include <string>
 #include <expected>
+#include <string>
 
-#include "minifi-c.h"
+#include "minifi-api.h"
 #include "minifi-cpp/core/PropertyDefinition.h"
 
 namespace org::apache::nifi::minifi::api::core {
 
 class ControllerServiceContext {
  public:
-  explicit ControllerServiceContext(MinifiControllerServiceContext* impl) : impl_(impl) {}
+  explicit ControllerServiceContext(minifi_controller_service_context* impl) : impl_(impl) {}
 
   [[nodiscard]] std::expected<std::string, std::error_code> getProperty(std::string_view name) const;
   [[nodiscard]] std::expected<std::string, std::error_code> getProperty(const minifi::core::PropertyReference& property_reference) const {
     return getProperty(property_reference.name);
   }
 
  private:
-  MinifiControllerServiceContext* impl_;
+  minifi_controller_service_context* impl_;
 };
 
 }  // namespace org::apache::nifi::minifi::api::core

extension-framework/cpp-extension-lib/include/api/core/ControllerServiceImpl.h

@@ -43,15 +43,15 @@ class ControllerServiceImpl {
 
   virtual ~ControllerServiceImpl();
 
-  MinifiStatus enable(ControllerServiceContext&);
+  minifi_status enable(ControllerServiceContext&);
   void disable();
 
   [[nodiscard]] std::string getName() const;
   [[nodiscard]] minifi::utils::Identifier getUUID() const;
   [[nodiscard]] minifi::utils::SmallString<36> getUUIDStr() const;
 
  protected:
-  virtual MinifiStatus enableImpl(api::core::ControllerServiceContext&) = 0;
+  virtual minifi_status enableImpl(api::core::ControllerServiceContext&) = 0;
   virtual void disableImpl() {}
 
   minifi::core::ControllerServiceMetadata metadata_;

extension-framework/cpp-extension-lib/include/api/core/FlowFile.h

@@ -21,12 +21,12 @@
 #include <memory>
 #include <stdexcept>
 
-#include "minifi-c.h"
+#include "minifi-api.h"
 
 namespace org::apache::nifi::minifi::api::core {
 
 struct EnsureMovedFromDeleter {
-  void operator()(MinifiFlowFile* ff) {
+  void operator()(minifi_flow_file* ff) {
     if (ff) {
       if (std::uncaught_exceptions()) {
         // there is already an exception in progress, do not terminate the process (although there are scenarios we could throw here)
@@ -37,6 +37,6 @@ struct EnsureMovedFromDeleter {
   }
 };
 
-using FlowFile = std::unique_ptr<MinifiFlowFile, EnsureMovedFromDeleter>;
+using FlowFile = std::unique_ptr<minifi_flow_file, EnsureMovedFromDeleter>;
 
 }  // namespace org::apache::nifi::minifi::api::core

extension-framework/cpp-extension-lib/include/api/core/ProcessContext.h

@@ -20,10 +20,11 @@
 #include <expected>
 #include <string>
 
+#include "PublishedMetrics.h"
 #include "api/core/FlowFile.h"
 #include "api/utils/Proxy.h"
 #include "api/utils/Ssl.h"
-#include "minifi-c.h"
+#include "minifi-api.h"
 #include "minifi-cpp/core/PropertyDefinition.h"
 
 namespace org::apache::nifi::minifi::api::core {
@@ -40,32 +41,36 @@ class ProcessContext {
 
   [[nodiscard]] virtual std::expected<std::string, std::error_code> getProperty(const minifi::core::PropertyReference& prop,
       const FlowFile* ff) const = 0;
-  [[nodiscard]] virtual std::expected<MinifiControllerService*, std::error_code> getControllerService(const minifi::core::PropertyReference& prop) const = 0;
-  [[nodiscard]] virtual bool hasNonEmptyProperty(std::string_view name) const = 0;
+  [[nodiscard]] virtual std::expected<minifi_controller_service*, std::error_code> getControllerService(const minifi::core::PropertyReference& prop) const = 0;
   [[nodiscard]] virtual std::map<std::string, std::string> getDynamicProperties(const FlowFile* flow_file) const = 0;
 
   [[nodiscard]] virtual std::expected<std::optional<utils::net::SslData>, std::error_code> getSslData(const minifi::core::PropertyReference& prop) const = 0;
   [[nodiscard]] virtual std::expected<std::optional<utils::ProxyData>, std::error_code> getProxyData(const minifi::core::PropertyReference& prop) const = 0;
+
+  [[nodiscard]] virtual std::expected<void, std::error_code> reportMetrics(const PublishedMetrics& metrics) const = 0;
+  [[nodiscard]] virtual std::expected<void, std::error_code> setTriggerWhenEmpty(bool) = 0;
 };
 
 class CffiProcessContext : public ProcessContext {
  public:
-  explicit CffiProcessContext(MinifiProcessContext* impl) : impl_(impl) {}
+  explicit CffiProcessContext(minifi_process_context* impl) : impl_(impl) {}
 
   [[nodiscard]] std::expected<std::string, std::error_code> getProperty(const minifi::core::PropertyReference& property_reference,
       const FlowFile* flow_file) const override;
-  [[nodiscard]] std::expected<MinifiControllerService*, std::error_code> getControllerService(const minifi::core::PropertyReference& prop) const override;
+  [[nodiscard]] std::expected<minifi_controller_service*, std::error_code> getControllerService(const minifi::core::PropertyReference& prop) const override;
   [[nodiscard]] std::map<std::string, std::string> getDynamicProperties(const FlowFile* flow_file) const override;
-  [[nodiscard]] bool hasNonEmptyProperty(std::string_view name) const override;
 
   [[nodiscard]] std::expected<std::optional<utils::net::SslData>, std::error_code> getSslData(const minifi::core::PropertyReference& prop) const override;
   [[nodiscard]] std::expected<std::optional<utils::ProxyData>, std::error_code> getProxyData(const minifi::core::PropertyReference& prop) const override;
 
+  [[nodiscard]] std::expected<void, std::error_code> reportMetrics(const PublishedMetrics& metrics) const override;
+  [[nodiscard]] std::expected<void, std::error_code> setTriggerWhenEmpty(bool) override;
+
  private:
   [[nodiscard]] std::expected<std::string, std::error_code> getProperty(std::string_view name, const FlowFile* flow_file) const;
 
  private:
-  MinifiProcessContext* impl_;
+  minifi_process_context* impl_;
 };
 
 }  // namespace org::apache::nifi::minifi::api::core