flipper 0.3.0 → 0.4.0

data/lib/flipper/adapter.rb

@@ -1,3 +1,5 @@
+require 'flipper/instrumenters/noop'
+
 module Flipper
   # Internal: Adapter wrapper that wraps vanilla adapter instances. Adds things
   # like local caching and convenience methods for adding/reading features from
@@ -19,6 +21,10 @@ module Flipper
   # To see an example adapter that this would wrap, checkout the [memory
   # adapter included with flipper](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/adapters/memory.rb).
   class Adapter
+    # Private: The name of instrumentation events.
+    InstrumentationName = "adapter_operation.#{InstrumentationNamespace}"
+
+    # Private: The name of the key that stores the set of known features.
     FeaturesKey = 'features'
 
     # Internal: Wraps vanilla adapter instance for use internally in flipper.
@@ -37,89 +43,168 @@ module Flipper
     #   # => Flipper::Adapter instance
     #
     # Returns Flipper::Adapter instance
-    def self.wrap(object)
+    def self.wrap(object, options = {})
       if object.is_a?(Flipper::Adapter)
         object
       else
-        new(object)
+        new(object, options)
       end
     end
 
-    attr_reader :adapter, :local_cache
+    # Private: What adapter is being wrapped and will ultimately be used.
+    attr_reader :adapter
+
+    # Private: The name of the adapter. Based on the class name.
+    attr_reader :name
+
+    # Private: What is used to store the local cache.
+    attr_reader :local_cache
+
+    # Private: What is used to instrument all the things.
+    attr_reader :instrumenter
 
-    # Internal: Initializes a new instance
+    # Internal: Initializes a new adapter instance.
     #
     # adapter - Vanilla adapter instance to wrap. Just needs to respond to
     #           read, write, delete, set_members, set_add, and set_delete.
     #
-    # local_cache - Where to store the local cache data (default: {}).
-    #               Must respond to fetch(key, block), delete(key) and clear.
-    def initialize(adapter, local_cache = {})
+    # options - The Hash of options.
+    #           :local_cache - Where to store the local cache data (default: {}).
+    #                          Must respond to fetch(key, block), delete(key)
+    #                          and clear.
+    #           :instrumenter - What to use to instrument all the things.
+    #
+    def initialize(adapter, options = {})
       @adapter = adapter
-      @local_cache = local_cache
+      @name = adapter.class.name.split('::').last.downcase.to_sym
+      @local_cache = options[:local_cache] || {}
+      @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
     end
 
+    # Public: Turns local caching on/off.
+    #
+    # value - The Boolean that decides if local caching is on.
     def use_local_cache=(value)
       local_cache.clear
       @use_local_cache = value
     end
 
+    # Public: Returns true for using local cache, false for not.
     def using_local_cache?
       @use_local_cache == true
     end
 
+    # Public: Reads a key.
     def read(key)
-      perform_read(key) { @adapter.read(key) }
+      perform_read(:read, key)
     end
 
+    # Public: Set a key to a value.
     def write(key, value)
-      perform_update(key) { @adapter.write(key, value) }
+      perform_update(:write, key, value.to_s)
     end
 
+    # Public: Deletes a key.
     def delete(key)
-      perform_update(key) { @adapter.delete(key) }
+      perform_delete(:delete, key)
     end
 
+    # Public: Returns the members of a set.
     def set_members(key)
-      perform_read(key) { @adapter.set_members(key) }
+      perform_read(:set_members, key)
     end
 
+    # Public: Adds a value to a set.
     def set_add(key, value)
-      perform_update(key) { @adapter.set_add(key, value) }
+      perform_update(:set_add, key, value.to_s)
     end
 
+    # Public: Deletes a value from a set.
     def set_delete(key, value)
-      perform_update(key) { @adapter.set_delete(key, value) }
+      perform_update(:set_delete, key, value.to_s)
     end
 
+    # Public: Determines equality for an adapter instance when compared to
+    # another object.
     def eql?(other)
       self.class.eql?(other.class) && adapter == other.adapter
     end
-    alias :== :eql?
+    alias_method :==, :eql?
 
+    # Public: Returns all the features that the adapter knows of.
     def features
       set_members(FeaturesKey)
     end
 
+    # Internal: Adds a known feature to the set of features.
     def feature_add(name)
       set_add(FeaturesKey, name.to_s)
     end
 
-    private
+    # Public: Pretty string version for debugging.
+    def inspect
+      attributes = [
+        "name=#{name.inspect}",
+        "use_local_cache=#{@use_local_cache.inspect}"
+      ]
+      "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
+    end
 
-    def perform_read(key)
+    # Private
+    def perform_read(operation, key)
       if using_local_cache?
-        local_cache.fetch(key.to_s) { local_cache[key.to_s] = yield }
+        local_cache.fetch(key.to_s) {
+          local_cache[key.to_s] = @adapter.send(operation, key)
+        }
       else
-        yield
+        payload = {
+          :key => key,
+          :operation => operation,
+          :adapter_name => @name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = @adapter.send(operation, key)
+        }
+      end
+    end
+
+    # Private
+    def perform_update(operation, key, value)
+      payload = {
+        :key => key,
+        :value => value,
+        :operation => operation,
+        :adapter_name => @name,
+      }
+
+      result = @instrumenter.instrument(InstrumentationName, payload) { |payload|
+        payload[:result] = @adapter.send(operation, key, value)
+      }
+
+      if using_local_cache?
+        local_cache.delete(key.to_s)
       end
+
+      result
     end
 
-    def perform_update(key)
-      result = yield
+    # Private
+    def perform_delete(operation, key)
+      payload = {
+        :key => key,
+        :operation => operation,
+        :adapter_name => @name,
+      }
+
+      result = @instrumenter.instrument(InstrumentationName, payload) { |payload|
+        payload[:result] = @adapter.send(operation, key)
+      }
+
       if using_local_cache?
         local_cache.delete(key.to_s)
       end
+
       result
     end
   end

data/lib/flipper/adapters/memoized.rb

@@ -3,41 +3,48 @@ require 'set'
 module Flipper
   module Adapters
     class Memoized
+      # Public
       def initialize(adapter, cache = {})
         @adapter = adapter
         @cache = cache
       end
 
+      # Public
       def read(key)
         @cache.fetch(key) {
           @cache[key] = @adapter.read(key)
         }
       end
 
+      # Public
       def write(key, value)
         result = @adapter.write(key, value)
         @cache.delete(key)
         result
       end
 
+      # Public
       def delete(key)
         result = @adapter.delete(key)
         @cache.delete(key)
         result
       end
 
+      # Public
       def set_add(key, value)
         result = @adapter.set_add(key, value)
         @cache.delete(key)
         result
       end
 
+      # Public
       def set_delete(key, value)
         result = @adapter.set_delete(key, value)
         @cache.delete(key)
         result
       end
 
+      # Public
       def set_members(key)
         @cache.fetch(key) {
           @cache[key] = @adapter.set_members(key)

data/lib/flipper/adapters/memory.rb

@@ -3,32 +3,39 @@ require 'set'
 module Flipper
   module Adapters
     class Memory
+      # Public
       def initialize(source = nil)
         @source = source || {}
       end
 
+      # Public
       def read(key)
         @source[key.to_s]
       end
 
+      # Public
       def write(key, value)
-        @source[key.to_s] = value
+        @source[key.to_s] = value.to_s
       end
 
+      # Public
       def delete(key)
         @source.delete(key.to_s)
       end
 
+      # Public
       def set_add(key, value)
         ensure_set_initialized(key)
-        @source[key.to_s].add(value)
+        @source[key.to_s].add(value.to_s)
       end
 
+      # Public
       def set_delete(key, value)
         ensure_set_initialized(key)
-        @source[key.to_s].delete(value)
+        @source[key.to_s].delete(value.to_s)
       end
 
+      # Public
       def set_members(key)
         ensure_set_initialized(key)
         @source[key.to_s]

data/lib/flipper/adapters/operation_logger.rb

@@ -13,36 +13,43 @@ module Flipper
       SetDelete = Struct.new(:key, :value)
       SetMember = Struct.new(:key)
 
+      # Public
       def initialize(adapter)
         @operations = []
         @adapter = adapter
       end
 
+      # Public
       def read(key)
         @operations << Read.new(key.to_s)
         @adapter.read key
       end
 
+      # Public
       def write(key, value)
         @operations << Write.new(key.to_s, value)
         @adapter.write key, value
       end
 
+      # Public
       def delete(key)
         @operations << Delete.new(key.to_s, nil)
         @adapter.delete key
       end
 
+      # Public
       def set_add(key, value)
         @operations << SetAdd.new(key.to_s, value)
         @adapter.set_add key, value
       end
 
+      # Public
       def set_delete(key, value)
         @operations << SetDelete.new(key.to_s, value)
         @adapter.set_delete key, value
       end
 
+      # Public
       def set_members(key)
         @operations << SetMembers.new(key.to_s)
         @adapter.set_members key

data/lib/flipper/dsl.rb

@@ -1,61 +1,118 @@
 require 'flipper/adapter'
+require 'flipper/instrumenters/noop'
 
 module Flipper
   class DSL
+    # Private
     attr_reader :adapter
 
-    def initialize(adapter)
-      @adapter = Adapter.wrap(adapter)
+    # Private: What is being used to instrument all the things.
+    attr_reader :instrumenter
+
+    # Public: Returns a new instance of the DSL.
+    #
+    # adapter - The adapter that this DSL instance should use.
+    # options - The Hash of options.
+    #           :instrumenter - What should be used to instrument all the things.
+    def initialize(adapter, options = {})
+      @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
+      @adapter = Adapter.wrap(adapter, :instrumenter => @instrumenter)
+      @memoized_features = {}
     end
 
+    # Public: Check if a feature is enabled.
+    #
+    # name - The String or Symbol name of the feature.
+    # args - The args passed through to the enabled check.
+    #
+    # Returns true if feature is enabled, false if not.
     def enabled?(name, *args)
       feature(name).enabled?(*args)
     end
 
-    def disabled?(name, *args)
-      !enabled?(name, *args)
-    end
-
+    # Public: Enable a feature.
+    #
+    # name - The String or Symbol name of the feature.
+    # args - The args passed through to the feature instance enable call.
+    #
+    # Returns the result of the feature instance enable call.
     def enable(name, *args)
       feature(name).enable(*args)
     end
 
+    # Public: Disable a feature.
+    #
+    # name - The String or Symbol name of the feature.
+    # args - The args passed through to the feature instance enable call.
+    #
+    # Returns the result of the feature instance disable call.
     def disable(name, *args)
       feature(name).disable(*args)
     end
 
+    # Public: Access a feature instance by name.
+    #
+    # name - The String or Symbol name of the feature.
+    #
+    # Returns an instance of Flipper::Feature.
     def feature(name)
-      memoized_features[name.to_sym] ||= Feature.new(name, @adapter)
+      @memoized_features[name.to_sym] ||= Feature.new(name, @adapter, {
+        :instrumenter => instrumenter,
+      })
     end
 
-    alias :[] :feature
+    # Public: Shortcut access to a feature instance by name.
+    #
+    # name - The String or Symbol name of the feature.
+    #
+    # Returns an instance of Flipper::Feature.
+    alias_method :[], :feature
 
+    # Public: Access a flipper group by name.
+    #
+    # name - The String or Symbol name of the feature.
+    #
+    # Returns an instance of Flipper::Group.
+    # Raises Flipper::GroupNotRegistered if group has not been registered.
     def group(name)
       Flipper.group(name)
     end
 
+    # Public: Wraps an object as a flipper actor.
+    #
+    # thing - The object that you would like to wrap.
+    #
+    # Returns an instance of Flipper::Types::Actor.
+    # Raises ArgumentError if thing not wrappable.
     def actor(thing)
       Types::Actor.new(thing)
     end
 
+    # Public: Shortcut for getting a percentage of random instance.
+    #
+    # number - The percentage of random that should be enabled.
+    #
+    # Returns Flipper::Types::PercentageOfRandom.
     def random(number)
       Types::PercentageOfRandom.new(number)
     end
-    alias :percentage_of_random :random
+    alias_method :percentage_of_random, :random
 
+    # Public: Shortcut for getting a percentage of actors instance.
+    #
+    # number - The percentage of actors that should be enabled.
+    #
+    # Returns Flipper::Types::PercentageOfActors.
     def actors(number)
       Types::PercentageOfActors.new(number)
     end
-    alias :percentage_of_actors :actors
+    alias_method :percentage_of_actors, :actors
 
+    # Internal: Returns a Set of the known features for this adapter.
+    #
+    # Returns Set of Flipper::Feature instances.
     def features
       adapter.features.map { |name| feature(name) }.to_set
     end
-
-    private
-
-    def memoized_features
-      @memoized_features ||= {}
-    end
   end
 end