feat: expose prerequisite relations in AllFlags API (#463)

Updates the `AllFlags()` API to gather and expose prerequisite
information for flags.

The prereqs are available via `State::Prerequisites()`, and are more
importantly serialized in the JSON representation of the bootstrap
payload.

The implementation strategy was to create a custom `IEventProcessor`
specifically for `AllFlags` usage. Previously, `AllFlags` invoked the
evaluator with a no-op `EventScope`, which made event creation a no-op
within the eval algorithm.

This change now passes in a `PrereqEventRecorder` which tracks the
top-level prerequisites of each flag.

Author: cwaldren-ld

contract-tests/server-contract-tests/src/main.cpp

@@ -47,6 +47,8 @@ int main(int argc, char* argv[]) {
         srv.add_capability("tls:custom-ca");
         srv.add_capability("filtering");
         srv.add_capability("filtering-strict");
+        srv.add_capability("client-prereq-events");
+
         net::signal_set signals{ioc, SIGINT, SIGTERM};
 
         boost::asio::spawn(ioc.get_executor(), [&](auto yield) mutable {

libs/internal/include/launchdarkly/events/data/common_events.hpp

@@ -8,7 +8,6 @@
 
 #include <chrono>
 #include <cstdint>
-#include <variant>
 
 namespace launchdarkly::events {
 

libs/internal/include/launchdarkly/events/data/events.hpp

@@ -3,6 +3,8 @@
 #include <launchdarkly/events/data/common_events.hpp>
 #include <launchdarkly/events/data/server_events.hpp>
 
+#include <variant>
+
 namespace launchdarkly::events {
 
 using InputEvent = std::variant<FeatureEventParams,

libs/internal/include/launchdarkly/events/event_processor_interface.hpp

@@ -12,7 +12,7 @@ class IEventProcessor {
      * capacity.
      * @param event InputEvent to deliver.
      */
-    virtual void SendAsync(events::InputEvent event) = 0;
+    virtual void SendAsync(InputEvent event) = 0;
     /**
      * Asynchronously flush's the processor's events, returning as soon as
      * possible. Flushing may be a no-op if a flush is ongoing.

libs/server-sdk/include/launchdarkly/server_side/all_flags_state.hpp

@@ -7,6 +7,7 @@
 #include <optional>
 #include <string>
 #include <unordered_map>
+#include <vector>
 
 namespace launchdarkly::server_side {
 
@@ -62,6 +63,14 @@ class AllFlagsState {
               bool track_reason,
               std::optional<std::uint64_t> debug_events_until_date);
 
+        State(std::uint64_t version,
+              std::optional<std::int64_t> variation,
+              std::optional<EvaluationReason> reason,
+              bool track_events,
+              bool track_reason,
+              std::optional<std::uint64_t> debug_events_until_date,
+              std::vector<std::string> prerequisites);
+
         /**
          * @return The flag's version number when it was evaluated.
          */
@@ -110,6 +119,12 @@ class AllFlagsState {
          */
         [[nodiscard]] bool OmitDetails() const;
 
+        /**
+         * @return The list of prerequisites for this flag in the order they
+         * were evaluated.
+         */
+        [[nodiscard]] std::vector<std::string> const& Prerequisites() const;
+
         friend class AllFlagsStateBuilder;
 
        private:
@@ -120,6 +135,7 @@ class AllFlagsState {
         bool track_reason_;
         std::optional<std::uint64_t> debug_events_until_date_;
         bool omit_details_;
+        std::vector<std::string> prerequisites_;
     };
 
     /**

libs/server-sdk/src/CMakeLists.txt

@@ -30,6 +30,8 @@ target_sources(${LIBNAME}
         all_flags_state/json_all_flags_state.cpp
         all_flags_state/all_flags_state_builder.cpp
         integrations/data_reader/kinds.cpp
+        prereq_event_recorder/prereq_event_recorder.cpp
+        prereq_event_recorder/prereq_event_recorder.hpp
         data_components/change_notifier/change_notifier.hpp
         data_components/change_notifier/change_notifier.cpp
         data_components/dependency_tracker/dependency_tracker.hpp

libs/server-sdk/src/all_flags_state/all_flags_state.cpp

@@ -3,19 +3,36 @@
 namespace launchdarkly::server_side {
 
 AllFlagsState::State::State(
-    std::uint64_t version,
-    std::optional<std::int64_t> variation,
+    std::uint64_t const version,
+    std::optional<std::int64_t> const variation,
     std::optional<EvaluationReason> reason,
-    bool track_events,
-    bool track_reason,
-    std::optional<std::uint64_t> debug_events_until_date)
+    bool const track_events,
+    bool const track_reason,
+    std::optional<std::uint64_t> const debug_events_until_date)
+    : State(version,
+            variation,
+            std::move(reason),
+            track_events,
+            track_reason,
+            debug_events_until_date,
+            std::vector<std::string>{}) {}
+
+AllFlagsState::State::State(
+    std::uint64_t const version,
+    std::optional<std::int64_t> const variation,
+    std::optional<EvaluationReason> reason,
+    bool const track_events,
+    bool const track_reason,
+    std::optional<std::uint64_t> const debug_events_until_date,
+    std::vector<std::string> prerequisites)
     : version_(version),
       variation_(variation),
-      reason_(reason),
+      reason_(std::move(reason)),
       track_events_(track_events),
       track_reason_(track_reason),
       debug_events_until_date_(debug_events_until_date),
-      omit_details_(false) {}
+      omit_details_(false),
+      prerequisites_(std::move(prerequisites)) {}
 
 std::uint64_t AllFlagsState::State::Version() const {
     return version_;
@@ -37,6 +54,10 @@ bool AllFlagsState::State::TrackReason() const {
     return track_reason_;
 }
 
+std::vector<std::string> const& AllFlagsState::State::Prerequisites() const {
+    return prerequisites_;
+}
+
 std::optional<std::uint64_t> const& AllFlagsState::State::DebugEventsUntilDate()
     const {
     return debug_events_until_date_;
@@ -80,7 +101,8 @@ bool operator==(AllFlagsState::State const& lhs,
            lhs.TrackEvents() == rhs.TrackEvents() &&
            lhs.TrackReason() == rhs.TrackReason() &&
            lhs.DebugEventsUntilDate() == rhs.DebugEventsUntilDate() &&
-           lhs.OmitDetails() == rhs.OmitDetails();
+           lhs.OmitDetails() == rhs.OmitDetails() &&
+           lhs.Prerequisites() == rhs.Prerequisites();
 }
 
 }  // namespace launchdarkly::server_side

libs/server-sdk/src/all_flags_state/json_all_flags_state.cpp

@@ -31,6 +31,11 @@ void tag_invoke(boost::json::value_from_tag const& unused,
             obj.emplace("debugEventsUntilDate", boost::json::value_from(*date));
         }
     }
+
+    if (auto const& prerequisites = state.Prerequisites();
+        !prerequisites.empty()) {
+        obj.emplace("prerequisites", boost::json::value_from(prerequisites));
+    }
 }
 
 void tag_invoke(boost::json::value_from_tag const& unused,

libs/server-sdk/src/client_impl.cpp

@@ -5,6 +5,7 @@
 #include "data_systems/lazy_load/lazy_load_system.hpp"
 #include "data_systems/offline.hpp"
 #include "evaluation/evaluation_stack.hpp"
+#include "prereq_event_recorder/prereq_event_recorder.hpp"
 
 #include "data_interfaces/system/idata_system.hpp"
 
@@ -181,8 +182,6 @@ AllFlagsState ClientImpl::AllFlagsState(Context const& context,
 
     AllFlagsStateBuilder builder{options};
 
-    EventScope no_events;
-
     auto all_flags = data_system_->AllFlags();
 
     // Because evaluating the flags may access many segments, tell the data
@@ -191,7 +190,7 @@ AllFlagsState ClientImpl::AllFlagsState(Context const& context,
     // memory.)
     auto _ = data_system_->AllSegments();
 
-    for (auto const& [k, v] : all_flags) {
+    for (auto const& [key, v] : all_flags) {
         if (!v || !v->item) {
             continue;
         }
@@ -203,15 +202,20 @@ AllFlagsState ClientImpl::AllFlagsState(Context const& context,
             continue;
         }
 
-        EvaluationDetail<Value> detail =
-            evaluator_.Evaluate(flag, context, no_events);
+        PrereqEventRecorder recorder{key};
+
+        EvaluationDetail<Value> detail = evaluator_.Evaluate(
+            flag, context,
+            EventScope{&recorder, EventFactory::WithoutReasons()});
 
         bool in_experiment = flag.IsExperimentationEnabled(detail.Reason());
-        builder.AddFlag(k, detail.Value(),
+
+        builder.AddFlag(key, detail.Value(),
                         AllFlagsState::State{
                             flag.Version(), detail.VariationIndex(),
                             detail.Reason(), flag.trackEvents || in_experiment,
-                            in_experiment, flag.debugEventsUntilDate});
+                            in_experiment, flag.debugEventsUntilDate,
+                            std::move(recorder).TakePrerequisites()});
     }
 
     return builder.Build();

libs/server-sdk/src/events/event_factory.cpp

@@ -3,8 +3,7 @@
 #include <chrono>
 namespace launchdarkly::server_side {
 
-EventFactory::EventFactory(
-    launchdarkly::server_side::EventFactory::ReasonPolicy reason_policy)
+EventFactory::EventFactory(ReasonPolicy const reason_policy)
     : reason_policy_(reason_policy),
       now_([]() { return events::Date{std::chrono::system_clock::now()}; }) {}
 

libs/server-sdk/src/prereq_event_recorder/prereq_event_recorder.cpp

@@ -0,0 +1,30 @@
+#include "prereq_event_recorder.hpp"
+
+namespace launchdarkly::server_side {
+
+PrereqEventRecorder::PrereqEventRecorder(std::string flag_key)
+    : flag_key_(std::move(flag_key)) {}
+
+void PrereqEventRecorder::SendAsync(events::InputEvent const event) {
+    if (auto const* feat = std::get_if<events::FeatureEventParams>(&event)) {
+        if (auto const prereq_of = feat->prereq_of) {
+            if (*prereq_of == flag_key_) {
+                prereqs_.push_back(feat->key);
+            }
+        }
+    }
+}
+
+void PrereqEventRecorder::FlushAsync() {}
+
+void PrereqEventRecorder::ShutdownAsync() {}
+
+std::vector<std::string> const& PrereqEventRecorder::Prerequisites() const {
+    return prereqs_;
+}
+
+std::vector<std::string>&& PrereqEventRecorder::TakePrerequisites() && {
+    return std::move(prereqs_);
+}
+
+}  // namespace launchdarkly::server_side

libs/server-sdk/src/prereq_event_recorder/prereq_event_recorder.hpp

@@ -0,0 +1,43 @@
+#pragma once
+
+#include <launchdarkly/events/event_processor_interface.hpp>
+
+#include <string>
+#include <vector>
+
+namespace launchdarkly::server_side {
+
+/**
+ * This class is meant only to record direct prerequisites of a flag. That is,
+ * although it will be passed events for all prerequisites seen during an
+ * evaluation via SendAsync, it will only store those that are a direct
+ * prerequisite of the parent flag passed in the constructor.
+ *
+ * As a future improvement, it would be possible to unify the EventScope
+ * mechanism currently used by the Evaluator to send events with a class
+ * similar to this one, or to refactor the Evaluator to include prerequisite
+ * information in the returned EvaluationDetail (or a new Result class, which
+ * would be a composite of the EvaluationDetail and a vector of prerequisites.)
+ */
+class PrereqEventRecorder final : public events::IEventProcessor {
+   public:
+    explicit PrereqEventRecorder(std::string flag_key);
+
+    void SendAsync(events::InputEvent event) override;
+
+    /* No-op */
+    void FlushAsync() override;
+
+    /* No-op */
+    void ShutdownAsync() override;
+
+    std::vector<std::string> const& Prerequisites() const;
+
+    std::vector<std::string>&& TakePrerequisites() &&;
+
+   private:
+    std::string const flag_key_;
+    std::vector<std::string> prereqs_;
+};
+
+}  // namespace launchdarkly::server_side