feat: redis data source C bindings (#345)

This adds C bindings for creating a Redis Source, as well as a LazyLoad
config method to accept pointers to the C type representing an
instantiated Redis Source.

Author: cwaldren-ld

examples/hello-cpp-server-redis/main.cpp

@@ -52,7 +52,9 @@ int main() {
     }
 
     config_builder.DataSystem().Method(
-        LazyLoad().Source(*redis).CacheRefresh(std::chrono::seconds(30)));
+        LazyLoad()
+            .Source(std::move(*redis))
+            .CacheRefresh(std::chrono::seconds(30)));
 
     auto config = config_builder.Build();
     if (!config) {

libs/server-sdk-redis-source/include/launchdarkly/server_side/bindings/c/integrations/redis/redis_source.h

@@ -0,0 +1,80 @@
+/** @file redis_source.h
+ * @brief LaunchDarkly Server-side Redis Source C Binding.
+ */
+// NOLINTBEGIN modernize-use-using
+#pragma once
+
+#include <launchdarkly/bindings/c/export.h>
+
+#ifdef __cplusplus
+extern "C" {
+// only need to export C interface if
+// used by C++ source code
+#endif
+
+typedef struct _LDServerLazyLoadRedisSource* LDServerLazyLoadRedisSource;
+
+/* Defines the size of the error message buffer in LDServerLazyLoadResult.
+ */
+#ifndef LDSERVER_LAZYLOAD_REDISSOURCE_ERROR_MESSAGE_SIZE
+#define LDSERVER_LAZYLOAD_REDISSOURCE_ERROR_MESSAGE_SIZE 256
+#endif
+
+/**
+ * @brief Stores the result of calling LDDServerLazyLoadRedisSource_New.
+ *
+ * On successful creation, source will contain a pointer which may be passed
+ * into the LaunchDarkly SDK's configuration.
+ *
+ * On failure, error_message contains a NULL-terminated string describing the
+ * error.
+ *
+ * The message may be truncated if it was originally longer than error_message's
+ * buffer size.
+ */
+struct LDServerLazyLoadRedisResult {
+    LDServerLazyLoadRedisSource source;
+    char error_message[LDSERVER_LAZYLOAD_REDISSOURCE_ERROR_MESSAGE_SIZE];
+};
+
+/**
+ * @brief Creates a new Redis data source suitable for usage in the SDK's
+ * Lazy Load data system.
+ *
+ * In this system, the SDK will query Redis for flag/segment
+ * data as required, with an in-memory cache to reduce the number of queries.
+ *
+ * Data is never written back to Redis.
+ *
+ * @param uri Redis URI string. Must not be NULL or empty string.
+ *
+ * @param prefix Prefix to use when reading SDK data from Redis. This allows
+ * multiple SDK environments to coexist in the same database, or for the SDK's
+ * data to coexist with other unrelated data. Must not be NULL.
+ *
+ * @param out_result Pointer to struct where the source pointer or an error
+ * message should be stored.
+ *
+ * @return True if the source was created successfully; out_result->source
+ * will contain the pointer. The caller must either free the
+ * pointer with LDServerLazyLoadRedisSource_Free, OR pass it into the SDK's
+ * configuration methods which will take ownership (in which case do not call
+ * LDServerLazyLoadRedisSource_Free.)
+ */
+LD_EXPORT(bool)
+LDServerLazyLoadRedisSource_New(char const* uri,
+                                char const* prefix,
+                                struct LDServerLazyLoadRedisResult* out_result);
+
+/**
+ * @brief Frees a Redis data source pointer. Only necessary to call if not
+ * passing ownership to SDK configuration.
+ */
+LD_EXPORT(void)
+LDServerLazyLoadRedisSource_Free(LDServerLazyLoadRedisSource source);
+
+#ifdef __cplusplus
+}
+#endif
+
+// NOLINTEND modernize-use-using

libs/server-sdk-redis-source/include/launchdarkly/server_side/integrations/redis/redis_source.hpp

@@ -56,6 +56,8 @@ class RedisDataSource final : public ISerializedDataReader {
     [[nodiscard]] std::string const& Identity() const override;
     [[nodiscard]] bool Initialized() const override;
 
+    ~RedisDataSource() override;  // = default
+
    private:
     RedisDataSource(std::unique_ptr<sw::redis::Redis> redis,
                     std::string prefix);

libs/server-sdk-redis-source/src/CMakeLists.txt

@@ -14,6 +14,7 @@ target_sources(${LIBNAME}
         PRIVATE
         ${HEADER_LIST}
         redis_source.cpp
+        bindings/redis/redis_source.cpp
 )
 
 

libs/server-sdk-redis-source/src/bindings/redis/redis_source.cpp

@@ -0,0 +1,52 @@
+#include <launchdarkly/server_side/bindings/c/integrations/redis/redis_source.h>
+
+#include <launchdarkly/server_side/integrations/redis/redis_source.hpp>
+
+#include <launchdarkly/detail/c_binding_helpers.hpp>
+#include <launchdarkly/error.hpp>
+
+#include <redis++.h>
+
+using namespace launchdarkly::server_side::integrations;
+
+LD_EXPORT(bool)
+LDServerLazyLoadRedisSource_New(char const* uri,
+                                char const* prefix,
+                                LDServerLazyLoadRedisResult* out_result) {
+    LD_ASSERT_NOT_NULL(uri);
+    LD_ASSERT_NOT_NULL(prefix);
+    LD_ASSERT_NOT_NULL(out_result);
+
+    // Explicitely zero out the exception_msg buffer in case the exception is
+    // shorter than the buffer.
+    memset(out_result->error_message, 0,
+           sizeof(LDServerLazyLoadRedisResult::error_message));
+
+    // Ensure the source pointer isn't garbage.
+    out_result->source = nullptr;
+
+    auto maybe_source = RedisDataSource::Create(uri, prefix);
+    if (!maybe_source) {
+        // Avoid heap allocating another string to pass back to the caller;
+        // instead, we copy into the buffer and ensure a terminator is present.
+        // This does mean the message may be truncated.
+
+        std::size_t const len = maybe_source.error().copy(
+            out_result->error_message, sizeof(out_result->error_message) - 1);
+        out_result->error_message[len] = '\0';
+
+        return false;
+    }
+
+    // The pointer is no longer managed and must either be freed by the caller,
+    // or passed into the SDK which will take ownership.
+    out_result->source =
+        reinterpret_cast<LDServerLazyLoadRedisSource>(maybe_source->release());
+
+    return true;
+}
+
+LD_EXPORT(void)
+LDServerLazyLoadRedisSource_Free(LDServerLazyLoadRedisSource source) {
+    delete reinterpret_cast<RedisDataSource*>(source);
+}

libs/server-sdk-redis-source/src/redis_source.cpp

@@ -14,6 +14,8 @@ RedisDataSource::Create(std::string uri, std::string prefix) {
     }
 }
 
+RedisDataSource::~RedisDataSource() = default;
+
 std::string RedisDataSource::key_for_kind(
     ISerializedItemKind const& kind) const {
     return prefix_ + ":" + kind.Namespace();

libs/server-sdk-redis-source/tests/c_bindings_test.cpp

@@ -0,0 +1,28 @@
+#include <gtest/gtest.h>
+
+#include <launchdarkly/server_side/bindings/c/integrations/redis/redis_source.h>
+
+TEST(RedisBindings, SourcePointerIsStoredOnSuccessfulCreation) {
+    LDServerLazyLoadRedisResult result;
+    ASSERT_TRUE(LDServerLazyLoadRedisSource_New("tcp://localhost:1234", "foo",
+                                                &result));
+    ASSERT_NE(result.source, nullptr);
+    LDServerLazyLoadRedisSource_Free(result.source);
+}
+
+TEST(RedisBindings, ErrorMessageIsPropagatedOnFailure) {
+    LDServerLazyLoadRedisResult result;
+    ASSERT_FALSE(
+        LDServerLazyLoadRedisSource_New("totally not a URI", "foo", &result));
+    // Note: this test might begin failing if the Redis++ library ever returns
+    // a different string here. The important thing is not the exact message,
+    // but that the message was propagated.
+    ASSERT_STREQ(result.error_message, "invalid URI: no scheme");
+}
+
+TEST(RedisBindings, SourcePointerIsNullptrOnFailure) {
+    LDServerLazyLoadRedisResult result;
+    ASSERT_FALSE(
+        LDServerLazyLoadRedisSource_New("totally not a URI", "foo", &result));
+    ASSERT_EQ(result.source, nullptr);
+}

libs/server-sdk/include/launchdarkly/server_side/bindings/c/config/builder.h

@@ -4,6 +4,7 @@
 #pragma once
 
 #include <launchdarkly/server_side/bindings/c/config/config.h>
+#include <launchdarkly/server_side/bindings/c/config/lazy_load_builder/lazy_load_builder.h>
 
 #include <launchdarkly/bindings/c/config/logging_builder.h>
 #include <launchdarkly/bindings/c/export.h>
@@ -218,6 +219,22 @@ LDServerConfigBuilder_DataSystem_BackgroundSync_Polling(
     LDServerConfigBuilder b,
     LDServerDataSourcePollBuilder poll_builder);
 
+/**
+ * Configures the Lazy Load data system. This method is mutually exclusive with
+ * the BackgroundSync_Polling and BackgroundSync_Streaming builders.
+ *
+ * In this mode the SDK will query a data source on-demand as required, with an
+ * in-memory cache to reduce the number of queries.
+ *
+ * @param b Server config builder. Must not be NULL.
+ * @param lazy_load_builder The lazy load builder. The builder is consumed; do
+ * not free it. Must not be NULL.
+ */
+LD_EXPORT(void)
+LDServerConfigBuilder_DataSystem_LazyLoad(
+    LDServerConfigBuilder b,
+    LDServerLazyLoadBuilder lazy_load_builder);
+
 /**
  * Specify if the SDK's data system should be enabled or not.
  *

libs/server-sdk/include/launchdarkly/server_side/bindings/c/config/lazy_load_builder/lazy_load_builder.h

@@ -0,0 +1,98 @@
+/** @file lazy_load_builder.h */
+// NOLINTBEGIN modernize-use-using
+
+#pragma once
+
+#include <launchdarkly/bindings/c/export.h>
+
+#include <stdbool.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {  // only need to export C interface if
+// used by C++ source code
+#endif
+
+typedef struct _LDServerLazyLoadBuilder* LDServerLazyLoadBuilder;
+
+typedef struct _LDServerLazyLoadSourcePtr* LDServerLazyLoadSourcePtr;
+
+/**
+ * @brief Specifies the action taken when a data item within the
+ * in-memory cache expires.
+ *
+ * At this time, the default policy is the only supported policy so there
+ * is no need to explicitely set it.
+ */
+enum LDLazyLoadCacheEvictionPolicy {
+    /* No action taken; cache eviction is disabled. Stale items will be used
+     * in evaluations if they cannot be refreshed. */
+    LD_LAZYLOAD_CACHE_EVICTION_POLICY_DISABLED = 0
+};
+
+/**
+ * Creates a Lazy Load builder which can be used as the SDK's data system.
+ *
+ * In Lazy Load mode, the SDK will query a source for data as required, with an
+ * in-memory cache to reduce the number of queries. This enables usage of
+ * databases for storing feature flag/segment data.
+ *
+ * In contrast, the Background Sync system injects data into the SDK
+ * asynchronously (either instantly as updates happen, in streaming mode; or
+ * periodically, in polling mode).
+ *
+ * Background Sync mode is preferred for most use cases, but Lazy Load may be
+ * beneficial when no connection to LaunchDarkly is required, such as when using
+ * the Relay Proxy to populate a database.
+ */
+LD_EXPORT(LDServerLazyLoadBuilder)
+LDServerLazyLoadBuilder_New();
+
+/**
+ * @brief Frees the memory associated with a Lazy Load builder. Do not call if
+ * the builder was consumed by the SDK config builder.
+ * @param b The builder to free.
+ */
+LD_EXPORT(void)
+LDServerLazyLoadBuilder_Free(LDServerLazyLoadBuilder b);
+
+/**
+ * Configures the Lazy Load system with a source via opaque pointer to
+ * C++ ISerializedDataReader.
+ *
+ * @param b The builder. Must not be NULL.
+ * @param source The source pointer. Behavior is undefined if the pointer is not
+ * an ISerializedDataReader. Must not be NULL.
+ */
+LD_EXPORT(void)
+LDServerLazyLoadBuilder_SourcePtr(LDServerLazyLoadBuilder b,
+                                  LDServerLazyLoadSourcePtr source);
+
+/**
+ * @brief Specify the duration data items should live in-memory
+ * before requiring a refresh via the database. The chosen @ref
+ * LDLazyLoadCacheEvictionPolicy affects usage of this TTL.
+ * @param b The builder. Must not be NULL.
+ * @param milliseconds The time-to-live for an item in milliseconds.
+ */
+LD_EXPORT(void)
+LDServerLazyLoadBuilder_CacheRefreshMs(LDServerLazyLoadBuilder b,
+                                       unsigned int milliseconds);
+
+/**
+ * @brief Specify the eviction policy when a data item's TTL expires.
+ * At this time, only LD_LAZYLOAD_CACHE_EVICTION_POLICY_DISABLED is supported
+ * (the default), which leaves stale items in the cache until they can be
+ * refreshed.
+ * @param b The builder. Must not be NULL.
+ * @param policy The eviction policy.
+ */
+LD_EXPORT(void)
+LDServerLazyLoadBuilder_CachePolicy(LDServerLazyLoadBuilder b,
+                                    enum LDLazyLoadCacheEvictionPolicy policy);
+
+#ifdef __cplusplus
+}
+#endif
+
+// NOLINTEND modernize-use-using

libs/server-sdk/include/launchdarkly/server_side/config/builders/data_system/lazy_load_builder.hpp

@@ -11,7 +11,7 @@
 namespace launchdarkly::server_side::config::builders {
 
 /**
- * \brief LazyLoadBuilder allows for specifying the configuration of
+ * @brief LazyLoadBuilder allows for specifying the configuration of
  * the Lazy Load data system, which is appropriate when a LaunchDarkly
  * environment should be stored external to the SDK (such as in Redis.)
  *
@@ -28,30 +28,33 @@ struct LazyLoadBuilder {
     using SourcePtr = std::shared_ptr<integrations::ISerializedDataReader>;
     using EvictionPolicy = built::LazyLoadConfig::EvictionPolicy;
     /**
-     * \brief Constructs a new LazyLoadBuilder.
+     * @brief Constructs a new LazyLoadBuilder.
      */
     LazyLoadBuilder();
 
     /**
-     * \brief Specify the source of the data.
-     * \param source Component implementing ISerializedDataPullSource.
-     * \return Reference to this.
+     * @brief Specify the source of the data.
+     * @param source Component implementing ISerializedDataReader. Ownership is
+     * shared.
+     * @return Reference to this.
      */
     LazyLoadBuilder& Source(SourcePtr source);
 
     /**
-     * \brief
-     * \param ttl Specify the duration data items should be live in-memory
-     * before being refreshed from the database. The chosen \ref EvictionPolicy
-     * affects usage of this TTL. \return Reference to this.
+     * @brief Specify the duration data items should live in-memory
+     * before requiring a refresh via the database. The chosen @ref
+     * EvictionPolicy affects usage of this TTL.
+     * @param ttl The time-to-live for an item.
+     * @return Reference to this.
      */
     LazyLoadBuilder& CacheRefresh(std::chrono::milliseconds ttl);
 
     /**
-     * \brief Specify the eviction policy when a data item's TTL expires.
+     * @brief Specify the eviction policy when a data item's TTL expires.
      * At this time, only EvictionPolicy::Disabled is supported (the default),
-     * which leaves stale items in the cache until they can be refreshed. \param
-     * policy The EvictionPolicy. \return Reference to this.
+     * which leaves stale items in the cache until they can be refreshed.
+     * @param policy The EvictionPolicy.
+     * @return Reference to this.
      */
     LazyLoadBuilder& CacheEviction(EvictionPolicy policy);
 

libs/server-sdk/include/launchdarkly/server_side/config/built/data_system/lazy_load_config.hpp

@@ -10,6 +10,9 @@ namespace launchdarkly::server_side::config::built {
 struct LazyLoadConfig {
     /**
      * \brief Specifies the action taken when a data item's TTL expires.
+     *
+     * The values must not be changed to ensure backwards compatibility
+     * with the C API.
      */
     enum class EvictionPolicy {
         /* No action taken; eviction is disabled. Stale items will be used