more docs

Author: cwaldren-ld

libs/common/include/config/detail/config_builder.hpp

@@ -18,7 +18,7 @@ namespace launchdarkly::config::detail {
 template <typename SDK>
 class ConfigBuilder {
    public:
-    using EndpointsBuilder = detail::HostsBuilder<SDK>;
+    using HostsBuilder = detail::HostsBuilder<SDK>;
     using EventsBuilder = detail::EventsBuilder<SDK>;
     using ConfigType = detail::Config<SDK>;
     /**
@@ -28,12 +28,12 @@ class ConfigBuilder {
     ConfigBuilder(std::string sdk_key);
 
     /**
-     * To customize the endpoints the SDK uses for streaming, polling, and
-     * events, pass in an EndpointsBuilder.
-     * @param builder An EndpointsBuilder.
+     * To customize the hosts the SDK uses for streaming, polling, and
+     * events, pass in an HostsBuilder.
+     * @param builder A HostsBuilder.
      * @return Reference to this builder.
      */
-    ConfigBuilder& service_endpoints(EndpointsBuilder builder);
+    ConfigBuilder& service_hosts(HostsBuilder builder);
 
     /**
      * To include metadata about the application that is utilizing the SDK,
@@ -68,7 +68,7 @@ class ConfigBuilder {
    private:
     std::string sdk_key_;
     std::optional<bool> offline_;
-    std::optional<EndpointsBuilder> service_endpoints_builder_;
+    std::optional<HostsBuilder> service_hosts_builder_;
     std::optional<ApplicationInfo> application_info_builder_;
     std::optional<EventsBuilder> events_builder_;
 };

libs/common/include/config/detail/events.hpp

@@ -7,35 +7,73 @@
 #include "attribute_reference.hpp"
 namespace launchdarkly::config::detail {
 
+/**
+ * Specifies the security regime for event delivery.
+ */
 enum class TransportSecurity {
+    // Plaintext event delivery.
     None = 0,
+    // Event delivery secured by Transport Layer Security.
     TLS = 1,
 };
 
 struct Events {
    public:
     template <typename SDK>
     friend class EventsBuilder;
+    /**
+     * Constructs configuration for the event subsystem.
+     * @param capacity How many events can queue in memory before new events
+     * are dropped.
+     * @param flush_interval How often events are automatically flushed to LaunchDarkly.
+     * @param path The path component of the LaunchDarkly event delivery endpoint.
+     * @param all_attributes_private Whether all attributes should be treated as private or not.
+     * @param private_attrs Which attributes should be treated as private, if all_attributes_private is false.
+     * @param security Whether a plaintext or encrypted client should be used for event delivery.
+     */
     Events(std::size_t capacity,
            std::chrono::milliseconds flush_interval,
            std::string path,
            bool all_attributes_private,
            AttributeReference::SetType private_attrs,
            TransportSecurity security);
-    std::size_t capacity() const;
-    std::chrono::milliseconds flush_interval() const;
-    std::string const& path() const;
-    bool all_attributes_private() const;
-    AttributeReference::SetType const& private_attributes() const;
-    TransportSecurity transport_security() const;
+
+    /**
+     * Capacity of the event processor.
+     */
+    [[nodiscard]] std::size_t capacity() const;
+
+    /**
+     * Flush interval of the event processor, in milliseconds.
+     */
+    [[nodiscard]] std::chrono::milliseconds flush_interval() const;
+
+    /**
+     * Path component of the LaunchDarkly event delivery endpoint.
+     */
+    [[nodiscard]] std::string const& path() const;
+
+    /**
+     * Whether all attributes should be considered private or not.
+     */
+    [[nodiscard]] bool all_attributes_private() const;
+
+    /**
+     * Set of individual attributes that should be considered private.
+     */
+    [[nodiscard]] AttributeReference::SetType const& private_attributes() const;
+
+    /**
+     * Requested transport security.
+     */
+    [[nodiscard]] TransportSecurity transport_security() const;
 
    private:
     std::size_t capacity_;
     std::chrono::milliseconds flush_interval_;
     std::string path_;
     bool all_attributes_private_;
     AttributeReference::SetType private_attributes_;
-
     TransportSecurity transport_security_;
 };
 

libs/common/include/config/detail/events_builder.hpp

@@ -38,7 +38,7 @@ class EventsBuilder {
      * Sets the capacity of the event processor. When more events are generated
      * within the processor's flush interval than this value, events will be
      * dropped.
-     * @param capacity Event capacity.
+     * @param capacity Event queue capacity.
      * @return Reference to this builder.
      */
     EventsBuilder& capacity(std::size_t capacity);
@@ -79,15 +79,22 @@ class EventsBuilder {
     EventsBuilder& all_attributes_private(bool);
 
     /**
-     * Specify an AttributePolicy for individual attributes.
-     * @return
+     * Specify that a set of attributes are private.
+     * @return Reference to this builder.
      */
     EventsBuilder& private_attributes(
         AttributeReference::SetType private_attrs);
 
     /**
-     * Builds Events configuration, if the configuration is valid. If not,
-     * returns an error.
+     * Specify the transport security regime for event delivery. By default,
+     * events are delivered using TLS.
+     * @param regime Security regime.
+     * @return Reference to this builder.
+     */
+    EventsBuilder& transport_security(TransportSecurity regime);
+
+    /**
+     * Builds Events configuration, if the configuration is valid.
      * @return Events config, or error.
      */
     [[nodiscard]] tl::expected<Events, Error> build();

libs/common/src/config/config_builder.cpp

@@ -6,12 +6,12 @@ template <typename SDK>
 ConfigBuilder<SDK>::ConfigBuilder(std::string sdk_key)
     : sdk_key_(std::move(sdk_key)),
       offline_(std::nullopt),
-      service_endpoints_builder_(std::nullopt) {}
+      service_hosts_builder_(std::nullopt) {}
 
 template <typename SDK>
-ConfigBuilder<SDK>& ConfigBuilder<SDK>::service_endpoints(
+ConfigBuilder<SDK>& ConfigBuilder<SDK>::service_hosts(
     detail::HostsBuilder<SDK> builder) {
-    service_endpoints_builder_ = std::move(builder);
+    service_hosts_builder_ = std::move(builder);
     return *this;
 }
 
@@ -40,7 +40,7 @@ typename ConfigBuilder<SDK>::ConfigType ConfigBuilder<SDK>::build(
     Logger& logger) const {
     auto key = sdk_key_;
     auto offline = offline_.value_or(Defaults<detail::AnySDK>::offline());
-    auto endpoints = service_endpoints_builder_.value_or(EndpointsBuilder());
+    auto endpoints = service_hosts_builder_.value_or(HostsBuilder());
     auto events = events_builder_.value_or(EventsBuilder());
     std::optional<std::string> app_tag;
     if (application_info_builder_) {

libs/common/src/config/events_builder.cpp

@@ -33,6 +33,13 @@ EventsBuilder<SDK>& EventsBuilder<SDK>::private_attributes(
     return *this;
 }
 
+template <typename SDK>
+EventsBuilder<SDK>& EventsBuilder<SDK>::transport_security(
+    TransportSecurity regime) {
+    config_.transport_security_ = regime;
+    return *this;
+}
+
 template <typename SDK>
 tl::expected<Events, Error> EventsBuilder<SDK>::build() {
     if (config_.capacity() == 0) {

libs/common/tests/config_builder_test.cpp

@@ -31,7 +31,7 @@ TEST_F(ConfigBuilderTest,
     using namespace launchdarkly::client;
     ConfigBuilder builder("sdk-123");
     Config cfg = builder.build(logger);
-    ASSERT_EQ(cfg.hosts_builder, ConfigBuilder::EndpointsBuilder());
+    ASSERT_EQ(cfg.hosts_builder, ConfigBuilder::HostsBuilder());
 }
 
 TEST_F(ConfigBuilderTest,
@@ -48,7 +48,7 @@ TEST_F(ConfigBuilderTest, CustomBuilderReflectsChanges) {
     auto config =
         ConfigBuilder("sdk-123")
             .offline(true)
-            .service_endpoints(HostsBuilder().relay_proxy("foo"))
+            .service_hosts(HostsBuilder().relay_proxy("foo"))
             .application_info(
                 ApplicationInfo().app_identifier("bar").app_version("baz"))
             .build(logger);