feature_switches 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d9320af56d6df754066bdf4db823d5c5664177df
+  data.tar.gz: 25c88dab2729ecbe5e7e3f65a93d9ecdda97ad22
+SHA512:
+  metadata.gz: 00215b33937508434dca51ab4266de7ee4b54a689695e8ab4a3bacb5ce87dc02f8732f460e279287b92f2d45a74fb5d93a451818f016a205f25f7582af48311d
+  data.tar.gz: cb7f70b4d6a3778dc18db84c2f737ebbc1cf4aaa69cdf6fa2c5efefb4e81db5ff6891b9d70415bb52238254696247ad16ba405ec776776df55d56868782a9310

data/README.md

@@ -0,0 +1,122 @@
+# Feature Switches
+
+### Status: Alpha (Don't use in production)
+
+## Summary
+
+A small gem for putting feature switches into your application that allow you
+to dynamically enable features to a percentage of users or specific cohort
+groups without a code deploy.
+
+There are some excellent gems that provide this functionality already --
+[rollout](https://github.com/jamesgolick/rollout) and [flipper](https://github.com/jnunemaker/flipper).
+This project is an experiment aiming for a specific set of design goals:
+
+1) Reduce the chatter in the protocol between a node checking to see if a
+   feature is enabled and the backend storage system. We're going to be reading
+   this data far more often than we're writing it so we want to aggressively
+   cache, but...
+
+2) Ensure all nodes get the latest configured switches immediately. A cache
+   that expires given a certain TTL can't work as a client isn't guaranteed
+   to talking to the same instance of our application on each request. A
+   feature disappearing and reappearing depending on which application server
+   we instance we hit is a bug.
+
+3) Allow for extension with new backends that support change notification;
+   specifically distributed systems synchronization backends like Zookeeper and
+   perhaps doozerd. Right now it's initially implemented against Redis which is
+   the simplest thing that could possibly work.
+
+5) Ensure that any kind of identifier can be used; not just an object that
+   responds to #id. We want to peg our switches on things that aren't
+   ActiveRecord objects (e.g., incoming phone numbers, time of day, etc).
+
+4) Expose a highly memorable CLI as that's how we're going to be interacting
+   with the switches via `irb`.
+
+
+## Supported Backends
+
+* Redis
+* Postgres
+* In-memory (for testing)
+
+## Design
+
+Switches uses a backend for both storage of feature configuration data and for
+notifying sibling nodes that are change has occurred. We'll look at how this
+works against the Redis backend.
+
+On startup, switches will connect to Redis twice: once for querying and setting
+configuration data and one for subscribing to a pub/sub channel of change
+notifications. When a change is made to configuration data, an extra call is
+made to Redis to publish a change notification. Once this change notification is
+received by other listening nodes, they will refetch the configuration data
+and update their local stores.
+
+
+     Node A            Redis           Node B
+       |                 |               |
+       |                 |<-subscribe----|
+       |                 |               |
+       |------------set->|               |
+       |                 |               |
+       |-publish(update)>|-------update->|
+       |                 |               |
+       |                 |<-get----------|
+       |                 |               |
+       |                 |               |
+
+## Installation
+
+In your Gemfile:
+
+  gem "feature_switches"
+
+## Usage
+
+```ruby
+# Initialize
+$switches = Switches do |config|
+  config.backend = "redis://localhost:6379/0"
+end
+=> #<Switches redis://localhost:6379/12>
+
+# Check to see if a feature is active for an identifier
+$switches.feature(:redesign).on?(current_user.id)
+# => true
+
+$switches.feature(:redesign).on?(current_user.phone_number)
+# => true
+
+$switches.feature(:redesign).on?(Time.now.hour)
+# => true
+
+# Turn a feature on globally
+$switches.feature(:redesign).on
+# => #<Feature redesign; 100%>
+
+# Turn a feature on for a given percentage of identifiers
+$switches.feature(:redesign).on(25)
+# => #<Feature redesign; 25%>
+
+# Turn a feature off globally
+$switches.feature(:redesign).off
+# => #<Feature redesign; 0%>
+
+# Add or remove an identifier from a cohort group
+$switches.cohort(:power_users).add(424)
+# => #<Cohort power_users; 1 member>
+
+$switches.cohort(:power_users).remove(424)
+# => #<Cohort power_users; 0 members>
+
+# Add a cohort group to a feature
+$switches.feature(:redesign).add(:power_users)
+# => #<Feature djsd; 0%; power_users>
+
+# Remove a cohort group from a feature
+$switches.feature(:redesign).remove(:power_users)
+# => #<Feature djsd; 0%>
+```

data/lib/switches/backend.rb

@@ -0,0 +1,17 @@
+require "uri"
+
+module Switches
+  class Backend
+    def self.factory(url, instance)
+      uri = URI(url)
+
+      if uri.scheme == "redis"
+        Backends::Redis.new(uri, instance)
+      elsif uri.scheme == "postgres"
+        Backends::Postgres.new(uri, instance)
+      else
+        Backends::Memory.new(uri, instance)
+      end
+    end
+  end
+end

data/lib/switches/backends/memory.rb

@@ -0,0 +1,48 @@
+module Switches
+  module Backends
+    class Memory
+      def initialize(uri, instance)
+        @instance = instance
+        $switches_data ||= {}
+        $switches_listeners ||= Set.new
+      end
+
+      def set(item)
+        $switches_data[key_for(item)] = item.to_json
+      end
+
+      def get(item)
+        if data = $switches_data[key_for(item)]
+          parse(data)
+        end
+      end
+
+      def listen
+        $switches_listeners.add(@instance)
+      end
+
+      def notify(update)
+        $switches_listeners.each do |listener|
+          listener.notified(update)
+        end
+      end
+
+      def clear
+        $switches_data.clear
+        $switches_listeners.clear
+      end
+
+      private
+
+      def key_for(item)
+        [item.class.to_s.downcase, item.name].join(":")
+      end
+
+      def parse(json)
+        JSON.parse(json.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/switches/backends/postgres.rb

@@ -0,0 +1,100 @@
+require "pg"
+
+module Switches
+  module Backends
+    class Postgres
+      TABLE = "switches"
+
+      def initialize(uri, instance)
+        @uri = uri
+        @instance = instance
+      end
+
+      def set(item)
+        result = connection.exec("UPDATE #{TABLE} SET value = $1 WHERE key = $2",
+          [item.to_json, key_for(item)]
+        )
+
+        if result.cmd_tuples == 0
+          connection.exec("INSERT INTO #{TABLE} (key, value) values($1, $2)",
+            [key_for(item), item.to_json]
+          )
+        end
+      end
+
+      def get(item)
+        result = connection.exec("SELECT value FROM #{TABLE} WHERE key = $1 LIMIT 1",
+          [key_for(item)]
+        )
+
+        result.each do |row|
+          return parse(row["value"])
+        end
+
+        nil
+      end
+
+      def listen
+        Thread.new { subscribe }
+      end
+
+      def notify(update)
+        connection.exec("NOTIFY #{TABLE}, '#{update.to_json}'")
+      end
+
+      def clear
+        connection.exec("TRUNCATE TABLE #{TABLE}")
+      end
+
+      private
+
+      def listener
+        @listener ||= connect
+      end
+
+      def connection
+        @connection ||= connect
+      end
+
+      def connect
+        PG.connect(connection_options)
+      end
+
+      def connection_options
+        {
+          user:     @uri.user,
+          password: @uri.password,
+          host:     @uri.host,
+          port:     @uri.port,
+          dbname:   @uri.path[1..-1]
+        }
+      end
+
+      def subscribe
+        loop do
+          listener.exec("LISTEN #{TABLE}")
+          listener.wait_for_notify do |event, pid, message|
+            process(message)
+          end
+        end
+      end
+
+      def key_for(item)
+        [item.type, item.name].join(":")
+      end
+
+      def parse(json)
+        JSON.parse(json.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def process(message)
+        attributes = parse(message)
+        update = Update.new(attributes)
+
+        @instance.notified(update)
+      end
+    end
+  end
+end

data/lib/switches/backends/redis.rb

@@ -0,0 +1,74 @@
+require "redis"
+
+module Switches
+  module Backends
+    class Redis
+      PREFIX = "switches"
+      CHANNEL = [PREFIX, "bus"].join(":")
+
+      def initialize(uri, instance)
+        @uri = uri
+        @instance = instance
+      end
+
+      def set(item)
+        connection.set(key_for(item), item.to_json)
+      end
+
+      def get(item)
+        if data = connection.get(key_for(item))
+          parse(data)
+        end
+      end
+
+      def listen
+        Thread.new { subscribe }
+      end
+
+      def notify(update)
+        connection.publish(CHANNEL, update.to_json)
+      end
+
+      def clear
+        connection.flushdb
+      end
+
+      private
+
+      def listener
+        @listener ||= connect
+      end
+
+      def connection
+        @connection ||= connect
+      end
+
+      def connect
+        ::Redis.new(url: @uri)
+      end
+
+      def subscribe
+        listener.subscribe(CHANNEL) do |on|
+          on.message { |_, message| process(message) }
+        end
+      end
+
+      def key_for(item)
+        [item.type, item.name].join(":")
+      end
+
+      def parse(json)
+        JSON.parse(json.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def process(message)
+        attributes = parse(message)
+        update = Update.new(attributes)
+
+        @instance.notified(update)
+      end
+    end
+  end
+end

data/lib/switches/cohort.rb

@@ -0,0 +1,63 @@
+module Switches
+  class Cohort
+    attr_reader :name
+
+    def initialize(name, instance)
+      @name = name
+      @instance = instance
+      @members = Set.new
+    end
+
+    def reload
+      if data = @instance.get(self)
+        @members = data["members"].to_set
+      end
+
+      self
+    end
+
+    def include?(identifier)
+      @members.include?(identifier)
+    end
+
+    def add(member)
+      @members.add(member.to_s)
+      updated
+    end
+
+    def remove(member)
+      @members.delete(member.to_s)
+      updated
+    end
+
+    def inspect
+      output = "#<Cohort #{@name}"
+      output += "; #{@members.count} member"
+      output += "s" unless @members.count == 1
+      output += ">"
+    end
+
+    def to_json
+      {
+        name: name,
+        members: members
+      }.to_json
+    end
+
+    def members
+      @members.to_a
+    end
+
+    def type
+      "cohort"
+    end
+
+    private
+
+    def updated
+      @instance.set(self)
+      @instance.notify(self)
+      self
+    end
+  end
+end

data/lib/switches/cohorts.rb

@@ -0,0 +1,14 @@
+module Switches
+  class Cohorts
+    def initialize(instance)
+      @cohorts ||= Hash.new do |cohorts, name|
+        name = name.to_sym
+        cohorts[name] = Cohort.new(name, instance).reload
+      end
+    end
+
+    def [](name)
+      @cohorts[name.to_sym]
+    end
+  end
+end

data/lib/switches/configuration.rb

@@ -0,0 +1,9 @@
+module Switches
+  class Configuration
+    attr_accessor :backend
+
+    def initialize
+      yield self if block_given?
+    end
+  end
+end

data/lib/switches/feature.rb

@@ -0,0 +1,89 @@
+module Switches
+  class Feature
+    attr_reader :name, :percentage
+
+    def initialize(name, instance)
+      @name = name
+      @instance = instance
+      @percentage = Percentage(0)
+      @cohorts = Set.new
+    end
+
+    def reload
+      if data = @instance.get(self)
+        @percentage = Percentage(data["percentage"])
+        @cohorts = data["cohorts"].to_set
+      end
+
+      self
+    end
+
+    def on(numeric = 100)
+      @percentage = Percentage(numeric)
+      updated
+    end
+
+    def off
+      @percentage = Percentage(0)
+      updated
+    end
+
+    def add(cohort_name)
+      @cohorts.add(cohort_name.to_s)
+      updated
+    end
+
+    def remove(cohort_name)
+      @cohorts.delete(cohort_name.to_s)
+      updated
+    end
+
+    def inspect
+      output = "#<Feature #{@name}; #{@percentage}"
+      output += "; #{@cohorts.to_a.join(", ")}" if @cohorts.any?
+      output += ">"
+    end
+
+    def to_json
+      {
+        name: name,
+        percentage: percentage.to_i,
+        cohorts: @cohorts.to_a
+      }.to_json
+    end
+
+    def cohorts
+      @cohorts.to_a
+    end
+
+    def on?(identifier)
+      return true if @percentage.max?
+
+      in_cohort?(identifier) || in_percentage?(identifier)
+    end
+
+    def type
+      "feature"
+    end
+
+    private
+
+    def in_cohort?(identifier)
+      @cohorts.any? do |cohort|
+        @instance.cohort(cohort).include?(identifier)
+      end
+    end
+
+    def in_percentage?(identifier)
+      return false if @percentage.min?
+
+      @percentage.include?(identifier)
+    end
+
+    def updated
+      @instance.set(self)
+      @instance.notify(self)
+      self
+    end
+  end
+end

data/lib/switches/features.rb

@@ -0,0 +1,14 @@
+module Switches
+  class Features
+    def initialize(instance)
+      @features ||= Hash.new do |features, name|
+        name = name.to_sym
+        features[name] = Feature.new(name, instance).reload
+      end
+    end
+
+    def [](name)
+      @features[name.to_sym]
+    end
+  end
+end

data/lib/switches/instance.rb

@@ -0,0 +1,86 @@
+module Switches
+  class Instance
+    include MonitorMixin
+
+    attr_reader :node_id
+
+    def initialize(configuration)
+      @url = configuration.backend
+      @node_id = SecureRandom.hex(3)
+
+      mon_initialize
+    end
+
+    def start
+      backend.listen
+      self
+    end
+
+    def feature(name)
+      synchronize do
+        features[name]
+      end
+    end
+
+    def cohort(name)
+      synchronize do
+        cohorts[name]
+      end
+    end
+
+    def get(item)
+      backend.get(item)
+    end
+
+    def set(item)
+      backend.set(item)
+    end
+
+    def notify(item)
+      Switches::Update.new.tap do |update|
+        update.type = item.type
+        update.name = item.name
+        update.node_id = node_id
+
+        backend.notify(update)
+      end
+    end
+
+    def notified(update)
+      return if update.from?(node_id)
+
+      case update.type
+      when "feature"
+        synchronize do
+          features[update.name].reload
+        end
+      when "cohort"
+        synchronize do
+          cohorts[update.name].reload
+        end
+      end
+    end
+
+    def clear
+      backend.clear
+    end
+
+    def inspect
+      "#<Switches #{@url}>"
+    end
+
+    private
+
+    def backend
+      @backend ||= Backend.factory(@url, self)
+    end
+
+    def features
+      @features ||= Features.new(self)
+    end
+
+    def cohorts
+      @cohorts ||= Cohorts.new(self)
+    end
+  end
+end

data/lib/switches/percentage.rb

@@ -0,0 +1,58 @@
+module Switches
+  class Percentage
+    LOWER = 0.0
+    UPPER = 100.0
+
+    include Comparable
+
+    attr_reader :value
+    protected :value
+
+    def initialize(value)
+      @value = clip(value)
+    end
+
+    def <=>(other)
+      @value <=> other.value
+    end
+
+    def include?(identifier)
+      Percentage(Zlib.crc32(identifier) % UPPER) < self
+    end
+
+    def to_i
+      @value.to_i
+    end
+
+    def to_f
+      @value.to_f
+    end
+
+    def to_s
+      "#{@value}%"
+    end
+
+    def inspect
+      to_s
+    end
+
+    def min?
+      @value == LOWER
+    end
+
+    def max?
+      @value == UPPER
+    end
+
+    private
+
+    def clip(value)
+      [LOWER, value.to_i, UPPER].sort[1]
+    end
+  end
+end
+
+def Percentage(value)
+  return value if value.kind_of?(Switches::Percentage)
+  Switches::Percentage.new(value)
+end

data/lib/switches/update.rb

@@ -0,0 +1,23 @@
+module Switches
+  class Update
+    attr_accessor :type, :name, :node_id
+
+    def initialize(attributes = {})
+      @type = attributes["type"]
+      @name = attributes["name"]
+      @node_id = attributes["node_id"]
+    end
+
+    def from?(node_id)
+      @node_id == node_id
+    end
+
+    def to_json
+      {
+        "type" => type,
+        "name" => name,
+        "node_id" => node_id
+      }.to_json
+    end
+  end
+end

data/lib/switches.rb

@@ -0,0 +1,29 @@
+require "securerandom"
+require "thread"
+require "monitor"
+require "json"
+require "set"
+require "zlib"
+
+require "switches/configuration"
+require "switches/instance"
+require "switches/cohorts"
+require "switches/cohort"
+require "switches/features"
+require "switches/feature"
+require "switches/percentage"
+require "switches/update"
+require "switches/backends/redis"
+require "switches/backends/memory"
+require "switches/backends/postgres"
+require "switches/backend"
+
+Thread.abort_on_exception = true
+
+def Switches
+  configuration = Switches::Configuration.new
+  yield configuration
+
+  instance = Switches::Instance.new(configuration)
+  instance.start
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: feature_switches
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- John Pignata
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Feature switches for applications that run on multiple nodes that uses
+  a not-very-chatty protocol
+email:
+- john@pignata.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/switches/backend.rb
+- lib/switches/backends/memory.rb
+- lib/switches/backends/postgres.rb
+- lib/switches/backends/redis.rb
+- lib/switches/cohort.rb
+- lib/switches/cohorts.rb
+- lib/switches/configuration.rb
+- lib/switches/feature.rb
+- lib/switches/features.rb
+- lib/switches/instance.rb
+- lib/switches/percentage.rb
+- lib/switches/update.rb
+- lib/switches.rb
+- README.md
+homepage: http://github.com/jpignata/switches
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0
+signing_key: 
+specification_version: 4
+summary: Feature switches
+test_files: []