feat(kv-ir): Add QueryHandler API declarations for handling KV-pair IR stream queries.

components/core/CMakeLists.txt

@@ -473,7 +473,11 @@ set(SOURCE_FILES_unitTest
         src/clp/ffi/ir_stream/protocol_constants.hpp
         src/clp/ffi/ir_stream/Serializer.cpp
         src/clp/ffi/ir_stream/Serializer.hpp
+        src/clp/ffi/ir_stream/search/AstEvaluationResult.hpp
+        src/clp/ffi/ir_stream/search/ErrorCode.cpp
+        src/clp/ffi/ir_stream/search/ErrorCode.hpp
         src/clp/ffi/ir_stream/search/NewProjectedSchemaTreeNodeCallbackReq.hpp
+        src/clp/ffi/ir_stream/search/QueryHandler.hpp
         src/clp/ffi/ir_stream/utils.cpp
         src/clp/ffi/ir_stream/utils.hpp
         src/clp/ffi/KeyValuePairLogEvent.cpp

components/core/src/clp/ffi/ir_stream/search/AstEvaluationResult.hpp

@@ -0,0 +1,23 @@
+#ifndef CLP_FFI_IR_STREAM_SEARCH_ASTEVALUATIONRESULT_HPP
+#define CLP_FFI_IR_STREAM_SEARCH_ASTEVALUATIONRESULT_HPP
+
+#include <cstdint>
+
+namespace clp::ffi::ir_stream::search {
+/**
+ * Enum representing the result of evaluating a search AST.
+ *
+ * Possible values:
+ * - True:   The AST evaluates to `true`.
+ * - False:  The AST evaluates to `false`.
+ * - Pruned: The AST evaluation is intentionally skipped because it belongs to a pruned branch of
+ *           the parent tree.
+ */
+enum class AstEvaluationResult : uint8_t {
+    True,
+    False,
+    Pruned,
+};
+}  // namespace clp::ffi::ir_stream::search
+
+#endif  // CLP_FFI_IR_STREAM_SEARCH_ASTEVALUATIONRESULT_HPP

components/core/src/clp/ffi/ir_stream/search/ErrorCode.cpp

@@ -0,0 +1,25 @@
+#include "ErrorCode.hpp"
+
+#include <string>
+
+#include <ystdlib/error_handling/ErrorCode.hpp>
+
+namespace {
+using clp::ffi::ir_stream::search::ErrorCodeEnum;
+using ErrorCategory = ystdlib::error_handling::ErrorCategory<ErrorCodeEnum>;
+}  // namespace
+
+template <>
+auto ErrorCategory::name() const noexcept -> char const* {
+    return "clp::ffi::ir_stream::search::QueryHandlerError";
+}
+
+template <>
+auto ErrorCategory::message(ErrorCodeEnum error_enum) const -> std::string {
+    switch (error_enum) {
+        case ErrorCodeEnum::MethodNotImplemented:
+            return "The requested method is not implemented.";
+        default:
+            return "Unknown error code enum.";
+    }
+}

components/core/src/clp/ffi/ir_stream/search/ErrorCode.hpp

@@ -0,0 +1,21 @@
+#ifndef CLP_FFI_IR_STREAM_SEARCH_QUERYHANDLERERRORCODE_HPP
+#define CLP_FFI_IR_STREAM_SEARCH_QUERYHANDLERERRORCODE_HPP
+
+#include <cstdint>
+
+#include <ystdlib/error_handling/ErrorCode.hpp>
+
+namespace clp::ffi::ir_stream::search {
+/**
+ * This enum class represents all possible error codes related to query handler.
+ */
+enum class ErrorCodeEnum : uint8_t {
+    MethodNotImplemented,
+};
+
+using ErrorCode = ystdlib::error_handling::ErrorCode<ErrorCodeEnum>;
+}  // namespace clp::ffi::ir_stream::search
+
+YSTDLIB_ERROR_HANDLING_MARK_AS_ERROR_CODE_ENUM(clp::ffi::ir_stream::search::ErrorCodeEnum);
+
+#endif  // CLP_FFI_IR_STREAM_SEARCH_QUERYHANDLERERRORCODE_HPP

components/core/src/clp/ffi/ir_stream/search/QueryHandler.hpp

@@ -0,0 +1,111 @@
+#ifndef CLP_FFI_IR_STREAM_SEARCH_QUERYHANDLER_HPP
+#define CLP_FFI_IR_STREAM_SEARCH_QUERYHANDLER_HPP
+
+#include <outcome/outcome.hpp>
+
+#include "../../KeyValuePairLogEvent.hpp"
+#include "../../SchemaTree.hpp"
+#include "AstEvaluationResult.hpp"
+#include "ErrorCode.hpp"
+#include "NewProjectedSchemaTreeNodeCallbackReq.hpp"
+
+namespace clp::ffi::ir_stream::search {
+/**
+ * Class for handing KV-pair IR stream search queries.
+ *
+ * Each query handler stores a KQL query represented as an AST. The handler is responsible for:
+ * - resolving column descriptors to concrete schema tree nodes within the stream.
+ * - evaluating the query against deserialized node-ID-value pairs.
+ *
+ * @tparam NewProjectedSchemaTreeNodeCallbackType Type of the callback to handle new projected
+ * schema tree nodes.
+ */
+template <NewProjectedSchemaTreeNodeCallbackReq NewProjectedSchemaTreeNodeCallbackType>
+class QueryHandler {
+public:
+    // Factory function
+    /**
+     * @param new_projected_schema_tree_node_callback
+     * @return A result containing the newly constructed `QueryHandler` on success, or an error code
+     * indicating the failure:
+     * - TODO
+     */
+    [[nodiscard]] static auto create(
+            NewProjectedSchemaTreeNodeCallbackType new_projected_schema_tree_node_callback
+    ) -> outcome_v2::std_result<QueryHandler>;
+
+    // Delete copy constructor and assignment operator
+    QueryHandler(QueryHandler const&) = delete;
+    auto operator=(QueryHandler const&) -> QueryHandler& = delete;
+
+    // Default move constructor and assignment operator
+    QueryHandler(QueryHandler&&) = default;
+    auto operator=(QueryHandler&&) -> QueryHandler& = default;
+
+    // Destructor
+    ~QueryHandler() = default;
+
+    /**
+     * Processes a newly inserted schema tree node to update the partially-resolved columns.
+     * @param is_auto_generated
+     * @param node_locator
+     * @param node_id
+     * @return A void result on success, or an error code indicating the failure:
+     * - TODO
+     */
+    [[nodiscard]] auto step_column_resolution(
+            bool is_auto_generated,
+            SchemaTree::NodeLocator const& node_locator,
+            SchemaTree::Node::id_t node_id
+    ) -> outcome_v2::std_result<void>;
+
+    /**
+     * Evaluates the given node-ID-value pairs against the underlying query.
+     * @param auto_gen_node_id_value_pairs
+     * @param user_gen_node_id_value_pairs
+     * @return A result containing the evaluation result on success, or an error code indicating
+     * the failure:
+     * - TODO
+     */
+    [[nodiscard]] auto evaluate_node_id_value_pairs(
+            KeyValuePairLogEvent::NodeIdValuePairs const& auto_gen_node_id_value_pairs,
+            KeyValuePairLogEvent::NodeIdValuePairs const& user_gen_node_id_value_pairs
+    ) -> outcome_v2::std_result<AstEvaluationResult>;
+
+private:
+    // Constructor
+    explicit QueryHandler(
+            NewProjectedSchemaTreeNodeCallbackType new_projected_schema_tree_node_callback
+    )
+            : m_new_projected_schema_tree_node_callback{new_projected_schema_tree_node_callback} {}
+
+    NewProjectedSchemaTreeNodeCallbackType m_new_projected_schema_tree_node_callback;
+};
+
+template <NewProjectedSchemaTreeNodeCallbackReq NewProjectedSchemaTreeNodeCallbackType>
+auto QueryHandler<NewProjectedSchemaTreeNodeCallbackType>::create(
+        [[maybe_unused]] NewProjectedSchemaTreeNodeCallbackType
+                new_projected_schema_tree_node_callback
+) -> outcome_v2::std_result<QueryHandler<NewProjectedSchemaTreeNodeCallbackType>> {
+    return ErrorCode{ErrorCodeEnum::MethodNotImplemented};
+}
+
+template <NewProjectedSchemaTreeNodeCallbackReq NewProjectedSchemaTreeNodeCallbackType>
+auto QueryHandler<NewProjectedSchemaTreeNodeCallbackType>::step_column_resolution(
+        [[maybe_unused]] bool is_auto_generated,
+        [[maybe_unused]] SchemaTree::NodeLocator const& node_locator,
+        [[maybe_unused]] SchemaTree::Node::id_t node_id
+) -> outcome_v2::std_result<void> {
+    return ErrorCode{ErrorCodeEnum::MethodNotImplemented};
+}
+
+template <NewProjectedSchemaTreeNodeCallbackReq NewProjectedSchemaTreeNodeCallbackType>
+auto QueryHandler<NewProjectedSchemaTreeNodeCallbackType>::evaluate_node_id_value_pairs(
+        [[maybe_unused]] KeyValuePairLogEvent::NodeIdValuePairs const& auto_gen_node_id_value_pairs,
+        [[maybe_unused]] KeyValuePairLogEvent::NodeIdValuePairs const& user_gen_node_id_value_pairs
+) -> outcome_v2::std_result<AstEvaluationResult> {
+    return ErrorCode{ErrorCodeEnum::MethodNotImplemented};
+}
+}  // namespace clp::ffi::ir_stream::search
+
+#endif  // CLP_FFI_IR_STREAM_SEARCH_QUERYHANDLER_HPP