feat(ffi): Add support for serializing/deserializing user-defined stream-level metadata.

components/core/src/clp/ffi/ir_stream/Deserializer.hpp

@@ -110,13 +110,21 @@ class Deserializer {
 
     [[nodiscard]] auto get_ir_unit_handler() -> IrUnitHandler& { return m_ir_unit_handler; }
 
+    /**
+     * @return The metadata associated with the deserialized stream.
+     */
+    [[nodiscard]] auto get_metadata() const -> nlohmann::json const& { return m_metadata; }
+
 private:
     // Constructor
-    Deserializer(IrUnitHandler ir_unit_handler) : m_ir_unit_handler{std::move(ir_unit_handler)} {}
+    Deserializer(IrUnitHandler ir_unit_handler, nlohmann::json metadata)
+            : m_ir_unit_handler{std::move(ir_unit_handler)},
+              m_metadata(std::move(metadata)) {}
 
     // Variables
     std::shared_ptr<SchemaTree> m_auto_gen_keys_schema_tree{std::make_shared<SchemaTree>()};
     std::shared_ptr<SchemaTree> m_user_gen_keys_schema_tree{std::make_shared<SchemaTree>()};
+    nlohmann::json m_metadata;
     UtcOffset m_utc_offset{0};
     IrUnitHandler m_ir_unit_handler;
     bool m_is_complete{false};
@@ -160,7 +168,7 @@ auto Deserializer<IrUnitHandler>::create(ReaderInterface& reader, IrUnitHandler
         return std::errc::protocol_not_supported;
     }
 
-    return Deserializer{std::move(ir_unit_handler)};
+    return Deserializer{std::move(ir_unit_handler), std::move(metadata_json)};
 }
 
 template <IrUnitHandlerInterface IrUnitHandler>

components/core/src/clp/ffi/ir_stream/Serializer.cpp

@@ -1,14 +1,14 @@
 #include "Serializer.hpp"
 
 #include <concepts>
-#include <cstddef>
 #include <cstdint>
 #include <optional>
 #include <span>
 #include <sstream>
 #include <string>
 #include <string_view>
 #include <system_error>
+#include <utility>
 #include <vector>
 
 #include <json/single_include/nlohmann/json.hpp>
@@ -522,8 +522,9 @@ template <
 }  // namespace
 
 template <typename encoded_variable_t>
-auto Serializer<encoded_variable_t>::create()
-        -> OUTCOME_V2_NAMESPACE::std_result<Serializer<encoded_variable_t>> {
+auto Serializer<encoded_variable_t>::create(
+        std::optional<nlohmann::json> optional_user_defined_metadata
+) -> OUTCOME_V2_NAMESPACE::std_result<Serializer<encoded_variable_t>> {
     static_assert(
             (std::is_same_v<encoded_variable_t, eight_byte_encoded_variable_t>
              || std::is_same_v<encoded_variable_t, four_byte_encoded_variable_t>)
@@ -548,6 +549,13 @@ auto Serializer<encoded_variable_t>::create()
             cProtocol::Metadata::VariableEncodingMethodsIdKey,
             cVariableEncodingMethodsVersion
     );
+    if (optional_user_defined_metadata.has_value()) {
+        metadata.emplace(
+                string{cProtocol::Metadata::UserDefinedMetadataKey},
+                std::move(optional_user_defined_metadata.value())
+        );
+    }
+
     if (false == serialize_metadata(metadata, ir_buf)) {
         return std::errc::protocol_error;
     }
@@ -783,10 +791,12 @@ auto Serializer<encoded_variable_t>::serialize_schema_tree_node(
 
 // Explicitly declare template specializations so that we can define the template methods in this
 // file
-template auto Serializer<eight_byte_encoded_variable_t>::create()
-        -> OUTCOME_V2_NAMESPACE::std_result<Serializer<eight_byte_encoded_variable_t>>;
-template auto Serializer<four_byte_encoded_variable_t>::create()
-        -> OUTCOME_V2_NAMESPACE::std_result<Serializer<four_byte_encoded_variable_t>>;
+template auto Serializer<eight_byte_encoded_variable_t>::create(
+        std::optional<nlohmann::json> optional_user_defined_metadata
+) -> OUTCOME_V2_NAMESPACE::std_result<Serializer<eight_byte_encoded_variable_t>>;
+template auto Serializer<four_byte_encoded_variable_t>::create(
+        std::optional<nlohmann::json> optional_user_defined_metadata
+) -> OUTCOME_V2_NAMESPACE::std_result<Serializer<four_byte_encoded_variable_t>>;
 
 template auto Serializer<eight_byte_encoded_variable_t>::change_utc_offset(UtcOffset utc_offset)
         -> void;

components/core/src/clp/ffi/ir_stream/Serializer.hpp

@@ -2,10 +2,12 @@
 #define CLP_FFI_IR_STREAM_SERIALIZER_HPP
 
 #include <cstdint>
+#include <optional>
 #include <span>
 #include <string>
 #include <vector>
 
+#include <json/single_include/nlohmann/json.hpp>
 #include <msgpack.hpp>
 #include <outcome/single-header/outcome.hpp>
 
@@ -39,11 +41,13 @@ class Serializer {
     // Factory functions
     /**
      * Creates an IR serializer and serializes the stream's preamble.
+     * @param optional_user_defined_metadata Stream-level user-defined metadata.
      * @return A result containing the serializer or an error code indicating the failure:
      * - std::errc::protocol_error on failure to serialize the preamble.
      */
-    [[nodiscard]] static auto create()
-            -> OUTCOME_V2_NAMESPACE::std_result<Serializer<encoded_variable_t>>;
+    [[nodiscard]] static auto create(
+            std::optional<nlohmann::json> optional_user_defined_metadata = std::nullopt
+    ) -> OUTCOME_V2_NAMESPACE::std_result<Serializer<encoded_variable_t>>;
 
     // Disable copy constructor/assignment operator
     Serializer(Serializer const&) = delete;

components/core/src/clp/ffi/ir_stream/protocol_constants.hpp

@@ -32,6 +32,8 @@ constexpr char ReferenceTimestampKey[] = "REFERENCE_TIMESTAMP";
 
 constexpr char VariablesSchemaIdKey[] = "VARIABLES_SCHEMA_ID";
 constexpr char VariableEncodingMethodsIdKey[] = "VARIABLE_ENCODING_METHODS_ID";
+
+constexpr std::string_view UserDefinedMetadataKey{"USER_DEFINED_METADATA"};
 }  // namespace Metadata
 
 namespace Payload {

components/core/tests/test-ir_encoding_methods.cpp

@@ -1223,7 +1223,9 @@ TEMPLATE_TEST_CASE(
     vector<int8_t> ir_buf;
     vector<std::pair<nlohmann::json, nlohmann::json>> expected_auto_gen_and_user_gen_object_pairs;
 
-    auto result{Serializer<TestType>::create()};
+    nlohmann::json const user_defined_metadata
+            = {{"map", {{"int", 0}, {"str", "STRING"}}}, {"array", {0, 0.0, true, "String"}}};
+    auto result{Serializer<TestType>::create(user_defined_metadata)};
     REQUIRE((false == result.has_error()));
 
     auto& serializer{result.value()};
@@ -1308,6 +1310,14 @@ TEMPLATE_TEST_CASE(
     auto deserializer_result{Deserializer<IrUnitHandler>::create(reader, IrUnitHandler{})};
     REQUIRE_FALSE(deserializer_result.has_error());
     auto& deserializer = deserializer_result.value();
+
+    auto const& deserialized_metadata = deserializer.get_metadata();
+    string const user_defined_metadata_key{
+            clp::ffi::ir_stream::cProtocol::Metadata::UserDefinedMetadataKey
+    };
+    REQUIRE(deserialized_metadata.contains(user_defined_metadata_key));
+    REQUIRE((deserialized_metadata.at(user_defined_metadata_key) == user_defined_metadata));
+
     while (true) {
         auto const result{deserializer.deserialize_next_ir_unit(reader)};
         REQUIRE_FALSE(result.has_error());