ldclient-rb 5.4.3 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2234ff7c3580f12b981ce3bc6eb3215969d4a7e8
-  data.tar.gz: d8c999182feacf6436ff83c896b3c44e36fbe62e
+  metadata.gz: 90690758415a43472c7c84ddd5f7d61b31849622
+  data.tar.gz: 2b3707dabf16cafd991c439b44c7ae4d14b4c94d
 SHA512:
-  metadata.gz: 96b9510d2429a9ba9bc4bb2eb974acf37d86c566946696dd4987b4d267362c8a451856afd958e54f5f59b9de6713cea14f9bc91385927adc9f06e43101af4729
-  data.tar.gz: '0891e7f45ac4fb5b7bb85ba234bdded350ccc45e6cc0db0a4e35f0a6699aac9b0041f2f0dad4f57f25ddf77e75b834d65a1335038b3501996a3fb176b1dc33ac'
+  metadata.gz: ee7396394f16fe7c98f49e293b1cf89956959ace1320bc8e5f6fa8c3c4bb8f8bc5b07e0a6bcd69f0a23007d41e6efa5b1bffa91bb3a8e96fbb73824226293f96
+  data.tar.gz: e91e83451a673f51f28b8d5c24e35192838e13e95eda4cc67db81d43e7766a071b3819646171cfa4800caaf748ae598f972c2e2bec889dece954a48a785fdebb

data/.circleci/config.yml

@@ -19,7 +19,7 @@ ruby-docker-template: &ruby-docker-template
           gem install jruby-openssl; # required by bundler, no effect on Ruby MRI
         fi
     - run: ruby -v
-    - run: gem install bundler -v "~> 1.7"
+    - run: gem install bundler -v 1.17.3
     - run: bundle install
     - run: mkdir ./rspec
     - run: bundle exec rspec --format progress --format RspecJunitFormatter -o ./rspec/rspec.xml spec
@@ -32,28 +32,38 @@ jobs:
   test-2.2:
     <<: *ruby-docker-template
     docker:
-      - image: circleci/ruby:2.2.9-jessie
+      - image: circleci/ruby:2.2.10-jessie
+      - image: consul
       - image: redis
+      - image: amazon/dynamodb-local
   test-2.3:
     <<: *ruby-docker-template
     docker:
-      - image: circleci/ruby:2.3.6-jessie
+      - image: circleci/ruby:2.3.7-jessie
+      - image: consul
       - image: redis
+      - image: amazon/dynamodb-local
   test-2.4:
     <<: *ruby-docker-template
     docker:
-      - image: circleci/ruby:2.4.4-stretch
+      - image: circleci/ruby:2.4.5-stretch
+      - image: consul
       - image: redis
+      - image: amazon/dynamodb-local
   test-2.5:
     <<: *ruby-docker-template
     docker:
-      - image: circleci/ruby:2.5.1-stretch
+      - image: circleci/ruby:2.5.3-stretch
+      - image: consul
       - image: redis
+      - image: amazon/dynamodb-local
   test-jruby-9.2:
     <<: *ruby-docker-template
     docker:
       - image: circleci/jruby:9-jdk
+      - image: consul
       - image: redis
+      - image: amazon/dynamodb-local
 
   # The following very slow job uses an Ubuntu container to run the Ruby versions that
   # CircleCI doesn't provide Docker images for.
@@ -63,8 +73,11 @@ jobs:
     environment:
       - RUBIES: "jruby-9.1.17.0"
     steps:
+      - run: sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
       - run: sudo apt-get -q update
       - run: sudo apt-get -qy install redis-server
+      - run: sudo apt-cache policy docker-ce
+      - run: sudo apt-get -qy install docker-ce      
       - checkout
       - run:
           name: install all Ruby versions
@@ -82,10 +95,24 @@ jobs:
               fi
               # bundler 2.0 may be preinstalled, we need to remove it if so
               yes | gem uninstall bundler --version '>=2.0' || true;
-              gem install bundler -v "~> 1.7";
+              gem install bundler -v 1.17.3;
               bundle install;
               mv Gemfile.lock "Gemfile.lock.$i"
             done
+      - run:
+          name: start DynamoDB
+          command: docker run -p 8000:8000 amazon/dynamodb-local
+          background: true
+      - run:
+          name: download Consul
+          command: wget https://releases.hashicorp.com/consul/0.8.0/consul_0.8.0_linux_amd64.zip
+      - run:
+          name: extract Consul
+          command: unzip consul_0.8.0_linux_amd64.zip
+      - run:
+          name: start Consul
+          command: ./consul agent -dev
+          background: true
       - run:
           name: run tests for all versions
           shell: /bin/bash -leo pipefail

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to the LaunchDarkly Ruby SDK will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [5.5.0] - 2019-01-17
+### Added:
+- It is now possible to use Consul or DynamoDB as a persistent feature store, similar to the existing Redis integration. See the `LaunchDarkly::Integrations::Consul` and `LaunchDarkly::Integrations::DynamoDB` modules, and the reference guide [Using a persistent feature store](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+- There is now a `LaunchDarkly::Integrations::Redis` module, which is the preferred method for creating a Redis feature store.
+- All of the database feature stores now support local caching not only for individual feature flag queries, but also for `all_flags_state`.
+- The `Config` property `data_source` is the new name for `update_processor` and `update_processor_factory`.
+
+### Changed:
+- The implementation of the SSE protocol for streaming has been moved into a separate gem, [`ld-eventsource`](https://github.com/launchdarkly/ruby-eventsource). This has no effect on streaming functionality.
+
+### Fixed:
+- Added or corrected a large number of documentation comments. All API classes and methods are now documented, and internal implementation details have been hidden from the documentation. You can view the latest documentation on [RubyDoc](https://www.rubydoc.info/gems/ldclient-rb).
+- Fixed a problem in the Redis feature store that would only happen under unlikely circumstances: trying to evaluate a flag when the LaunchDarkly client had not yet been fully initialized and the store did not yet have data in it, and then trying again when the client was still not ready but the store _did_ have data (presumably put there by another process). Previously, the second attempt would fail.
+- In polling mode, the SDK did not correctly handle non-ASCII Unicode characters in feature flag data. ([#90](https://github.com/launchdarkly/ruby-client/issues/90))
+
+### Deprecated:
+- `RedisFeatureStore.new`. This implementation class may be changed or moved in the future; use `LaunchDarkly::Integrations::Redis::new_feature_store`.
+- `Config.update_processor` and `Config.update_processor_factory`; use `Config.data_source`.
+
 ## [5.4.3] - 2019-01-11
 ### Changed:
 - The SDK is now compatible with `net-http-persistent` 3.x. (Thanks, [CodingAnarchy](https://github.com/launchdarkly/ruby-client/pull/113)!)

data/CONTRIBUTING.md

@@ -2,15 +2,3 @@ Contributing to LaunchDarkly SDK for Ruby
 =========================================
 
 We encourage pull-requests and other contributions from the community. We've also published an [SDK contributor's guide](http://docs.launchdarkly.com/docs/sdk-contributors-guide) that provides a detailed explanation of how our SDKs work.
-
-Dependencies
-------------
-[ld-em-eventsource](https://github.com/launchdarkly/em-eventsource)
-
-
-Style
------
-
-Our pull requests have [Hound CI](https://houndci.com/) set up to do style checking.
-We also run [Rubocop](https://github.com/bbatsov/rubocop).
-

data/Gemfile.lock

@@ -5,20 +5,33 @@ PATH
       concurrent-ruby (~> 1.0)
       faraday (>= 0.9, < 2)
       faraday-http-cache (>= 1.3.0, < 3)
-      http_tools (~> 0.4.5)
       json (>= 1.8, < 3)
+      ld-eventsource (~> 1.0)
       net-http-persistent (>= 2.9, < 4.0)
       semantic (~> 1.6)
-      socketry (~> 0.5.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    aws-eventstream (1.0.1)
+    aws-partitions (1.128.0)
+    aws-sdk-core (3.44.2)
+      aws-eventstream (~> 1.0)
+      aws-partitions (~> 1.0)
+      aws-sigv4 (~> 1.0)
+      jmespath (~> 1.0)
+    aws-sdk-dynamodb (1.19.0)
+      aws-sdk-core (~> 3, >= 3.39.0)
+      aws-sigv4 (~> 1.0)
+    aws-sigv4 (1.0.3)
     codeclimate-test-reporter (0.6.0)
       simplecov (>= 0.7.1, < 1.0.0)
     concurrent-ruby (1.1.4)
     connection_pool (2.2.1)
     diff-lcs (1.3)
+    diplomat (2.0.2)
+      faraday (~> 0.9)
+      json
     docile (1.1.5)
     faraday (0.15.4)
       multipart-post (>= 1.2, < 3)
@@ -27,10 +40,14 @@ GEM
     ffi (1.9.25)
     ffi (1.9.25-java)
     hitimes (1.3.0)
-    hitimes (1.3.0-java)
     http_tools (0.4.5)
+    jmespath (1.4.0)
     json (1.8.6)
     json (1.8.6-java)
+    ld-eventsource (1.0.0)
+      concurrent-ruby (~> 1.0)
+      http_tools (~> 0.4.5)
+      socketry (~> 0.5.1)
     listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
@@ -74,9 +91,11 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  aws-sdk-dynamodb (~> 1.18)
   bundler (~> 1.7)
   codeclimate-test-reporter (~> 0)
   connection_pool (>= 2.1.2)
+  diplomat (>= 2.0.2)
   ldclient-rb!
   listen (~> 3.0)
   rake (~> 10.0)

data/README.md

@@ -15,37 +15,37 @@ This version of the LaunchDarkly SDK has a minimum Ruby version of 2.2.6, or 9.1
 Quick setup
 -----------
 
-0. Install the Ruby SDK with `gem`
+1. Install the Ruby SDK with `gem`
 
-```shell
+    ```shell
 gem install ldclient-rb
 ```
 
-1. Require the LaunchDarkly client:
+2. Require the LaunchDarkly client:
 
-```ruby
+    ```ruby
 require 'ldclient-rb'
 ```
 
-2. Create a new LDClient with your SDK key:
+3. Create a new LDClient with your SDK key:
 
-```ruby
+    ```ruby
 client = LaunchDarkly::LDClient.new("your_sdk_key")
 ```
 
 ### Ruby on Rails
 
-0.  Add `gem 'ldclient-rb'` to your Gemfile and `bundle install`
+1. Add `gem 'ldclient-rb'` to your Gemfile and `bundle install`
 
-1.  Initialize the launchdarkly client in `config/initializers/launchdarkly.rb`:
+2. Initialize the launchdarkly client in `config/initializers/launchdarkly.rb`:
 
-```ruby
+    ```ruby
 Rails.configuration.ld_client = LaunchDarkly::LDClient.new("your_sdk_key")
 ```
 
-2.  You may want to include a function in your ApplicationController
+3.  You may want to include a function in your ApplicationController
 
-```ruby
+    ```ruby
     def launchdarkly_settings
       if current_user.present?
         {
@@ -72,31 +72,44 @@ Rails.configuration.ld_client = LaunchDarkly::LDClient.new("your_sdk_key")
     end
 ```
 
-3.  In your controllers, access the client using
+4. In your controllers, access the client using
 
-```ruby
+    ```ruby
 Rails.application.config.ld_client.variation('your.flag.key', launchdarkly_settings, false)
 ```
 
 Note that this gem will automatically switch to using the Rails logger it is detected.
 
 
+Your first feature flag
+-----------------------
+
+1. Create a new feature flag on your [dashboard](https://app.launchdarkly.com).
+2. In your application code, use the feature's key to check whether the flag is on for each user:
+
+```ruby
+if client.variation("your.flag.key", {key: "user@test.com"}, false)
+  # application code to show the feature
+else
+  # the code to run if the feature is off
+end
+```
+
 HTTPS proxy
-------------
-The Ruby SDK uses Faraday and Socketry to handle its network traffic. Both of these provide built-in support for the use of an  HTTPS proxy. If the HTTPS_PROXY environment variable is present then the SDK will proxy all network requests through the URL provided.
+-----------
+
+The Ruby SDK uses Faraday and Socketry to handle its network traffic. Both of these provide built-in support for the use of an  HTTPS proxy. If the HTTPS_PROXY environment variable is present then the SDK will proxy all network requests through the URL provided. (HTTP_PROXY is not used because all LaunchDarkly services require HTTPS.)
 
 How to set the HTTPS_PROXY environment variable on Mac/Linux systems:
 ```
 export HTTPS_PROXY=https://web-proxy.domain.com:8080
 ```
 
-
 How to set the HTTPS_PROXY environment variable on Windows systems:
 ```
 set HTTPS_PROXY=https://web-proxy.domain.com:8080
 ```
 
-
 If your proxy requires authentication then you can prefix the URN with your login information:
 ```
 export HTTPS_PROXY=http://user:pass@web-proxy.domain.com:8080
@@ -106,29 +119,22 @@ or
 set HTTPS_PROXY=http://user:pass@web-proxy.domain.com:8080
 ```
 
+Database integrations
+---------------------
 
-Your first feature flag
------------------------
-
-1. Create a new feature flag on your [dashboard](https://app.launchdarkly.com)
-2. In your application code, use the feature's key to check whether the flag is on for each user:
-
-```ruby
-if client.variation("your.flag.key", {key: "user@test.com"}, false)
-  # application code to show the feature
-else
-  # the code to run if the feature is off
-end
-```
+Feature flag data can be kept in a persistent store using Redis, DynamoDB, or Consul. These adapters are implemented in the `LaunchDarkly::Integrations::Redis`, `LaunchDarkly::Integrations::DynamoDB`, and `LaunchDarkly::Integrations::Consul` modules; to use them, call the `new_feature_store` method in the module, and put the returned object in the `feature_store` property of your client configuration. See the [API documentation](https://www.rubydoc.info/gems/ldclient-rb/LaunchDarkly/Integrations) and the [SDK reference guide](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store) for more information.
 
 Using flag data from a file
 ---------------------------
-For testing purposes, the SDK can be made to read feature flag state from a file or files instead of connecting to LaunchDarkly. See [`file_data_source.rb`](https://github.com/launchdarkly/ruby-client/blob/master/lib/ldclient-rb/file_data_source.rb) for more details.
+
+For testing purposes, the SDK can be made to read feature flag state from a file or files instead of connecting to LaunchDarkly. See `LaunchDarkly::FileDataSource` or the [SDK reference guide](https://docs.launchdarkly.com/v2.0/docs/reading-flags-from-a-file) for more details.
 
 Learn more
 -----------
 
-Check out our [documentation](http://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [complete reference guide for this SDK](http://docs.launchdarkly.com/docs/ruby-sdk-reference).
+Check out our [documentation](http://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [reference guide for this SDK](http://docs.launchdarkly.com/docs/ruby-sdk-reference).
+
+Generated API documentation is on [RubyDoc.info](https://www.rubydoc.info/gems/ldclient-rb).
 
 Testing
 -------
@@ -138,10 +144,10 @@ We run integration tests for all our SDKs using a centralized test harness. This
 Contributing
 ------------
 
-See [Contributing](https://github.com/launchdarkly/ruby-client/blob/master/CONTRIBUTING.md)
+See [Contributing](https://github.com/launchdarkly/ruby-client/blob/master/CONTRIBUTING.md).
 
 About LaunchDarkly
------------
+------------------
 
 * LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard.  With LaunchDarkly, you can:
     * Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
@@ -153,9 +159,9 @@ About LaunchDarkly
     * [JavaScript](http://docs.launchdarkly.com/docs/js-sdk-reference "LaunchDarkly JavaScript SDK")
     * [PHP](http://docs.launchdarkly.com/docs/php-sdk-reference "LaunchDarkly PHP SDK")
     * [Python](http://docs.launchdarkly.com/docs/python-sdk-reference "LaunchDarkly Python SDK")
-    * [Python Twisted](http://docs.launchdarkly.com/docs/python-twisted-sdk-reference "LaunchDarkly Python Twisted SDK")
     * [Go](http://docs.launchdarkly.com/docs/go-sdk-reference "LaunchDarkly Go SDK")
     * [Node.JS](http://docs.launchdarkly.com/docs/node-sdk-reference "LaunchDarkly Node SDK")
+    * [Electron](http://docs.launchdarkly.com/docs/electron-sdk-reference "LaunchDarkly Electron SDK")
     * [.NET](http://docs.launchdarkly.com/docs/dotnet-sdk-reference "LaunchDarkly .Net SDK")
     * [Ruby](http://docs.launchdarkly.com/docs/ruby-sdk-reference "LaunchDarkly Ruby SDK")
     * [iOS](http://docs.launchdarkly.com/docs/ios-sdk-reference "LaunchDarkly iOS SDK")

data/ldclient-rb.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.summary       = "LaunchDarkly SDK for Ruby"
   spec.description   = "Official LaunchDarkly SDK for Ruby"
   spec.homepage      = "https://github.com/launchdarkly/ruby-client"
-  spec.license       = "Apache 2.0"
+  spec.license       = "Apache-2.0"
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
@@ -21,9 +21,11 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.extensions    = 'ext/mkrf_conf.rb'
 
+  spec.add_development_dependency "aws-sdk-dynamodb", "~> 1.18"
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rspec", "~> 3.2"
   spec.add_development_dependency "codeclimate-test-reporter", "~> 0"
+  spec.add_development_dependency "diplomat", ">= 2.0.2"
   spec.add_development_dependency "redis", "~> 3.3.5"
   spec.add_development_dependency "connection_pool", ">= 2.1.2"
   spec.add_development_dependency "rake", "~> 10.0"
@@ -37,6 +39,5 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "semantic", "~> 1.6"
   spec.add_runtime_dependency "net-http-persistent", [">= 2.9", "< 4.0"]
   spec.add_runtime_dependency "concurrent-ruby", "~> 1.0"
-  spec.add_runtime_dependency "http_tools", '~> 0.4.5'
-  spec.add_runtime_dependency "socketry", "~> 0.5.1"
+  spec.add_runtime_dependency "ld-eventsource", '~> 1.0'
 end

data/lib/ldclient-rb.rb

@@ -1,4 +1,12 @@
+
+#
+# Namespace for the LaunchDarkly Ruby SDK.
+#
+module LaunchDarkly
+end
+
 require "ldclient-rb/version"
+require "ldclient-rb/interfaces"
 require "ldclient-rb/util"
 require "ldclient-rb/evaluation"
 require "ldclient-rb/flags_state"
@@ -16,6 +24,6 @@ require "ldclient-rb/simple_lru_cache"
 require "ldclient-rb/non_blocking_thread_pool"
 require "ldclient-rb/event_summarizer"
 require "ldclient-rb/events"
-require "ldclient-rb/redis_store"
 require "ldclient-rb/requestor"
 require "ldclient-rb/file_data_source"
+require "ldclient-rb/integrations"

data/lib/ldclient-rb/cache_store.rb

@@ -7,6 +7,7 @@ module LaunchDarkly
   #
   # @see https://github.com/plataformatec/faraday-http-cache
   # @see https://github.com/ruby-concurrency
+  # @private
   #
   class ThreadSafeMemoryStore
     #

data/lib/ldclient-rb/config.rb

@@ -8,66 +8,36 @@ module LaunchDarkly
   #
   #
   class Config
+    # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
+
     #
     # Constructor for creating custom LaunchDarkly configurations.
     #
     # @param opts [Hash] the configuration options
-    # @option opts [Logger] :logger A logger to use for messages from the
-    #   LaunchDarkly client. Defaults to the Rails logger in a Rails
-    #   environment, or stdout otherwise.
-    # @option opts [String] :base_uri ("https://app.launchdarkly.com") The base
-    #   URL for the LaunchDarkly server. Most users should use the default value.
-    # @option opts [String] :stream_uri ("https://stream.launchdarkly.com") The
-    #   URL for the LaunchDarkly streaming events server. Most users should use the default value.
-    # @option opts [String] :events_uri ("https://events.launchdarkly.com") The
-    #   URL for the LaunchDarkly events server. Most users should use the default value.
-    # @option opts [Integer] :capacity (10000) The capacity of the events
-    #   buffer. The client buffers up to this many events in memory before
-    #   flushing. If the capacity is exceeded before the buffer is flushed,
-    #   events will be discarded.
-    # @option opts [Float] :flush_interval (30) The number of seconds between
-    #   flushes of the event buffer.
-    # @option opts [Float] :read_timeout (10) The read timeout for network
-    #   connections in seconds.
-    # @option opts [Float] :connect_timeout (2) The connect timeout for network
-    #   connections in seconds.
-    # @option opts [Object] :cache_store A cache store for the Faraday HTTP caching
-    #   library. Defaults to the Rails cache in a Rails environment, or a
-    #   thread-safe in-memory store otherwise.
-    # @option opts [Object] :feature_store A store for feature flags and related data. Defaults to an in-memory
-    #   cache, or you can use RedisFeatureStore.
-    # @option opts [Boolean] :use_ldd (false) Whether you are using the LaunchDarkly relay proxy in
-    #   daemon mode. In this configuration, the client will not use a streaming connection to listen
-    #   for updates, but instead will get feature state from a Redis instance. The `stream` and
-    #   `poll_interval` options will be ignored if this option is set to true.
-    # @option opts [Boolean] :offline (false) Whether the client should be initialized in 
-    #   offline mode. In offline mode, default values are returned for all flags and no 
-    #   remote network requests are made.
-    # @option opts [Float] :poll_interval (30) The number of seconds between polls for flag updates
-    #   if streaming is off.
-    # @option opts [Boolean] :stream (true) Whether or not the streaming API should be used to receive flag updates.
-    #   Streaming should only be disabled on the advice of LaunchDarkly support.
-    # @option opts [Boolean] all_attributes_private (false) If true, all user attributes (other than the key)
-    #   will be private, not just the attributes specified in `private_attribute_names`.
-    # @option opts [Array] :private_attribute_names  Marks a set of attribute names private. Any users sent to
-    #  LaunchDarkly with this configuration active will have attributes with these names removed.
-    # @option opts [Boolean] :send_events (true) Whether or not to send events back to LaunchDarkly.
-    #   This differs from `offline` in that it affects only the sending of client-side events, not
-    #   streaming or polling for events from the server.
-    # @option opts [Integer] :user_keys_capacity (1000) The number of user keys that the event processor
-    #   can remember at any one time, so that duplicate user details will not be sent in analytics events.
-    # @option opts [Float] :user_keys_flush_interval (300) The interval in seconds at which the event
-    #   processor will reset its set of known user keys.
-    # @option opts [Boolean] :inline_users_in_events (false) Whether to include full user details in every
-    #   analytics event. By default, events will only include the user key, except for one "index" event
-    #   that provides the full details for the user.
-    # @option opts [Object] :update_processor (DEPRECATED) An object that will receive feature flag data from
-    #   LaunchDarkly. Defaults to either the streaming or the polling processor, can be customized for tests.
-    # @option opts [Object] :update_processor_factory A function that takes the SDK and configuration object
-    #   as parameters, and returns an object that can obtain feature flag data and put it into the feature
-    #   store. Defaults to creating either the streaming or the polling processor, can be customized for tests.
-    # @return [type] [description]
-    # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
+    # @option opts [Logger] :logger See {#logger}.
+    # @option opts [String] :base_uri ("https://app.launchdarkly.com") See {#base_uri}.
+    # @option opts [String] :stream_uri ("https://stream.launchdarkly.com") See {#stream_uri}.
+    # @option opts [String] :events_uri ("https://events.launchdarkly.com") See {#events_uri}.
+    # @option opts [Integer] :capacity (10000) See {#capacity}.
+    # @option opts [Float] :flush_interval (30) See {#flush_interval}.
+    # @option opts [Float] :read_timeout (10) See {#read_timeout}.
+    # @option opts [Float] :connect_timeout (2) See {#connect_timeout}.
+    # @option opts [Object] :cache_store See {#cache_store}.
+    # @option opts [Object] :feature_store See {#feature_store}.
+    # @option opts [Boolean] :use_ldd (false) See {#use_ldd?}.
+    # @option opts [Boolean] :offline (false) See {#offline?}.
+    # @option opts [Float] :poll_interval (30) See {#poll_interval}.
+    # @option opts [Boolean] :stream (true) See {#stream?}.
+    # @option opts [Boolean] all_attributes_private (false) See {#all_attributes_private}.
+    # @option opts [Array] :private_attribute_names See {#private_attribute_names}.
+    # @option opts [Boolean] :send_events (true) See {#send_events}.
+    # @option opts [Integer] :user_keys_capacity (1000) See {#user_keys_capacity}.
+    # @option opts [Float] :user_keys_flush_interval (300) See {#user_keys_flush_interval}.
+    # @option opts [Boolean] :inline_users_in_events (false) See {#inline_users_in_events}.
+    # @option opts [Object] :data_source See {#data_source}.
+    # @option opts [Object] :update_processor Obsolete synonym for `data_source`.
+    # @option opts [Object] :update_processor_factory Obsolete synonym for `data_source`.
+    #
     def initialize(opts = {})
       @base_uri = (opts[:base_uri] || Config.default_base_uri).chomp("/")
       @stream_uri = (opts[:stream_uri] || Config.default_stream_uri).chomp("/")
@@ -90,48 +60,62 @@ module LaunchDarkly
       @user_keys_capacity = opts[:user_keys_capacity] || Config.default_user_keys_capacity
       @user_keys_flush_interval = opts[:user_keys_flush_interval] || Config.default_user_keys_flush_interval
       @inline_users_in_events = opts[:inline_users_in_events] || false
+      @data_source = opts[:data_source] || opts[:update_processor] || opts[:update_processor_factory]
       @update_processor = opts[:update_processor]
       @update_processor_factory = opts[:update_processor_factory]
     end
 
     #
-    # The base URL for the LaunchDarkly server.
+    # The base URL for the LaunchDarkly server. This is configurable mainly for testing
+    # purposes; most users should use the default value.
+    # @return [String]
     #
-    # @return [String] The configured base URL for the LaunchDarkly server.
     attr_reader :base_uri
 
     #
-    # The base URL for the LaunchDarkly streaming server.
+    # The base URL for the LaunchDarkly streaming server. This is configurable mainly for testing
+    # purposes; most users should use the default value.
+    # @return [String]
     #
-    # @return [String] The configured base URL for the LaunchDarkly streaming server.
     attr_reader :stream_uri
 
     #
-    # The base URL for the LaunchDarkly events server.
+    # The base URL for the LaunchDarkly events server. This is configurable mainly for testing
+    # purposes; most users should use the default value.
+    # @return [String]
     #
-    # @return [String] The configured base URL for the LaunchDarkly events server.
     attr_reader :events_uri
 
     #
     # Whether streaming mode should be enabled. Streaming mode asynchronously updates
-    # feature flags in real-time using server-sent events.
+    # feature flags in real-time using server-sent events. Streaming is enabled by default, and
+    # should only be disabled on the advice of LaunchDarkly support.
+    # @return [Boolean]
     #
-    # @return [Boolean] True if streaming mode should be enabled
     def stream?
       @stream
     end
 
     #
-    # Whether to use the LaunchDarkly relay proxy in daemon mode. In this mode, we do
-    # not use polling or streaming to get feature flag updates from the server, but instead
-    # read them from a Redis instance that is updated by the proxy.
+    # Whether to use the LaunchDarkly relay proxy in daemon mode. In this mode, the client does not
+    # use polling or streaming to get feature flag updates from the server, but instead reads them
+    # from the {#feature_store feature store}, which is assumed to be a database that is populated by
+    # a LaunchDarkly relay proxy. For more information, see ["The relay proxy"](https://docs.launchdarkly.com/v2.0/docs/the-relay-proxy)
+    # and ["Using a persistent feature store"](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+    #
+    # All other properties related to streaming or polling are ignored if this option is set to true.
+    #
+    # @return [Boolean]
     #
-    # @return [Boolean] True if using the LaunchDarkly relay proxy in daemon mode
     def use_ldd?
       @use_ldd
     end
     
-    # TODO docs
+    #
+    # Whether the client should be initialized in offline mode. In offline mode, default values are
+    # returned for all flags and no remote network requests are made.
+    # @return [Boolean]
+    #
     def offline?
       @offline
     end
@@ -139,20 +123,23 @@ module LaunchDarkly
     #
     # The number of seconds between flushes of the event buffer. Decreasing the flush interval means
     # that the event buffer is less likely to reach capacity.
+    # @return [Float]
     #
-    # @return [Float] The configured number of seconds between flushes of the event buffer.
     attr_reader :flush_interval
 
     #
     # The number of seconds to wait before polling for feature flag updates. This option has no
-    # effect unless streaming is disabled
+    # effect unless streaming is disabled.
+    # @return [Float]
+    #
     attr_reader :poll_interval
 
     #
     # The configured logger for the LaunchDarkly client. The client library uses the log to
-    # print warning and error messages.
+    # print warning and error messages. If not specified, this defaults to the Rails logger
+    # in a Rails environment, or stdout otherwise.
+    # @return [Logger]
     #
-    # @return [Logger] The configured logger
     attr_reader :logger
 
     #
@@ -161,114 +148,206 @@ module LaunchDarkly
     # the buffer is flushed, events will be discarded.
     # Increasing the capacity means that events are less likely to be discarded,
     # at the cost of consuming more memory.
+    # @return [Integer]
     #
-    # @return [Integer] The configured capacity of the event buffer
     attr_reader :capacity
 
     #
-    # The store for the Faraday HTTP caching library. Stores should respond to
-    # 'read' and 'write' requests.
+    # A store for HTTP caching. This must support the semantics used by the
+    # [`faraday-http-cache`](https://github.com/plataformatec/faraday-http-cache) gem. Defaults
+    # to the Rails cache in a Rails environment, or a thread-safe in-memory store otherwise.
+    # @return [Object]
     #
-    # @return [Object] The configured store for the Faraday HTTP caching library.
     attr_reader :cache_store
 
     #
-    # The read timeout for network connections in seconds.
+    # The read timeout for network connections in seconds. This does not apply to the streaming
+    # connection, which uses a longer timeout since the server does not send data constantly.
+    # @return [Float]
     #
-    # @return [Float] The read timeout in seconds.
     attr_reader :read_timeout
 
     #
     # The connect timeout for network connections in seconds.
+    # @return [Float]
     #
-    # @return [Float] The connect timeout in seconds.
     attr_reader :connect_timeout
 
     #
-    # A store for feature flag configuration rules.
+    # A store for feature flags and related data. The client uses it to store all data received
+    # from LaunchDarkly, and uses the last stored data when evaluating flags. Defaults to
+    # {InMemoryFeatureStore}; for other implementations, see {LaunchDarkly::Integrations}.
+    #
+    # For more information, see ["Using a persistent feature store"](https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store).
+    #
+    # @return [LaunchDarkly::Interfaces::FeatureStore]
     #
     attr_reader :feature_store
 
-    # The proxy configuration string
+    #
+    # The proxy configuration string.
+    # @return [String]
     #
     attr_reader :proxy
 
+    #
+    # True if all user attributes (other than the key) should be considered private. This means
+    # that the attribute values will not be sent to LaunchDarkly in analytics events and will not
+    # appear on the LaunchDarkly dashboard.
+    # @return [Boolean]
+    # @see #private_attribute_names
+    #
     attr_reader :all_attributes_private
 
+    #
+    # A list of user attribute names that should always be considered private. This means that the
+    # attribute values will not be sent to LaunchDarkly in analytics events and will not appear on
+    # the LaunchDarkly dashboard.
+    #
+    # You can also specify the same behavior for an individual flag evaluation by storing an array
+    # of attribute names in the `:privateAttributeNames` property (note camelcase name) of the
+    # user object.
+    #
+    # @return [Array<String>]
+    # @see #all_attributes_private
+    #
     attr_reader :private_attribute_names
     
     #
-    # Whether to send events back to LaunchDarkly.
+    # Whether to send events back to LaunchDarkly. This differs from {#offline?} in that it affects
+    # only the sending of client-side events, not streaming or polling for events from the server.
+    # @return [Boolean]
     #
     attr_reader :send_events
 
     #
-    # The number of user keys that the event processor can remember at any one time, so that
-    # duplicate user details will not be sent in analytics events.
+    # The number of user keys that the event processor can remember at any one time. This reduces the
+    # amount of duplicate user details sent in analytics events.
+    # @return [Integer]
+    # @see #user_keys_flush_interval
     #
     attr_reader :user_keys_capacity
 
     #
     # The interval in seconds at which the event processor will reset its set of known user keys.
+    # @return [Float]
+    # @see #user_keys_capacity
     #
     attr_reader :user_keys_flush_interval
 
     #
-    # Whether to include full user details in every
-    # analytics event. By default, events will only include the user key, except for one "index" event
-    # that provides the full details for the user.
+    # Whether to include full user details in every analytics event. By default, events will only
+    # include the user key, except for one "index" event that provides the full details for the user.
+    # The only reason to change this is if you are using the Analytics Data Stream.
+    # @return [Boolean]
     #
     attr_reader :inline_users_in_events
 
+    #
+    # An object that is responsible for receiving feature flag data from LaunchDarkly. By default,
+    # the client uses its standard polling or streaming implementation; this is customizable for
+    # testing purposes.
+    #
+    # This may be set to either an object that conforms to {LaunchDarkly::Interfaces::DataSource},
+    # or a lambda (or Proc) that takes two parameters-- SDK key and {Config}-- and returns such an
+    # object.
+    #
+    # @return [LaunchDarkly::Interfaces::DataSource|lambda]
+    # @see FileDataSource
+    #
+    attr_reader :data_source
+
+    # @deprecated This is replaced by {#data_source}.
     attr_reader :update_processor
     
+    # @deprecated This is replaced by {#data_source}.
     attr_reader :update_processor_factory
-    
+
     #
     # The default LaunchDarkly client configuration. This configuration sets
     # reasonable defaults for most users.
-    #
     # @return [Config] The default LaunchDarkly configuration.
+    #
     def self.default
       Config.new
     end
 
+    #
+    # The default value for {#capacity}.
+    # @return [Integer] 10000
+    #
     def self.default_capacity
       10000
     end
 
+    #
+    # The default value for {#base_uri}.
+    # @return [String] "https://app.launchdarkly.com"
+    #
     def self.default_base_uri
       "https://app.launchdarkly.com"
     end
 
+    #
+    # The default value for {#stream_uri}.
+    # @return [String] "https://stream.launchdarkly.com"
+    #
     def self.default_stream_uri
       "https://stream.launchdarkly.com"
     end
 
+    #
+    # The default value for {#events_uri}.
+    # @return [String] "https://events.launchdarkly.com"
+    #
     def self.default_events_uri
       "https://events.launchdarkly.com"
     end
 
+    #
+    # The default value for {#cache_store}.
+    # @return [Object] the Rails cache if in Rails, or a simple in-memory implementation otherwise
+    #
     def self.default_cache_store
       defined?(Rails) && Rails.respond_to?(:cache) ? Rails.cache : ThreadSafeMemoryStore.new
     end
 
+    #
+    # The default value for {#flush_interval}.
+    # @return [Float] 10
+    #
     def self.default_flush_interval
       10
     end
 
+    #
+    # The default value for {#read_timeout}.
+    # @return [Float] 10
+    #
     def self.default_read_timeout
       10
     end
 
+    #
+    # The default value for {#connect_timeout}.
+    # @return [Float] 10
+    #
     def self.default_connect_timeout
       2
     end
 
+    #
+    # The default value for {#proxy}.
+    # @return [String] nil
+    #
     def self.default_proxy
       nil
     end
 
+    #
+    # The default value for {#logger}.
+    # @return [Logger] the Rails logger if in Rails, or a default Logger at WARN level otherwise
+    #
     def self.default_logger
       if defined?(Rails) && Rails.respond_to?(:logger)
         Rails.logger 
@@ -279,34 +358,66 @@ module LaunchDarkly
       end
     end
 
+    #
+    # The default value for {#stream?}.
+    # @return [Boolean] true
+    #
     def self.default_stream
       true
     end
 
+    #
+    # The default value for {#use_ldd?}.
+    # @return [Boolean] false
+    #
     def self.default_use_ldd
       false
     end
 
+    #
+    # The default value for {#feature_store}.
+    # @return [LaunchDarkly::Interfaces::FeatureStore] an {InMemoryFeatureStore}
+    #
     def self.default_feature_store
       InMemoryFeatureStore.new
     end
 
+    #
+    # The default value for {#offline?}.
+    # @return [Boolean] false
+    #
     def self.default_offline
       false
     end
 
+    #
+    # The default value for {#poll_interval}.
+    # @return [Float] 30
+    #
     def self.default_poll_interval
       30
     end
 
+    #
+    # The default value for {#send_events}.
+    # @return [Boolean] true
+    #
     def self.default_send_events
       true
     end
 
+    #
+    # The default value for {#user_keys_capacity}.
+    # @return [Integer] 1000
+    #
     def self.default_user_keys_capacity
       1000
     end
 
+    #
+    # The default value for {#user_keys_flush_interval}.
+    # @return [Float] 300
+    #
     def self.default_user_keys_flush_interval
       300
     end