flip_fork 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 13d411c043eedc95154d47015e144ecdbc709a19
+  data.tar.gz: 9aabaffe9b990127475615b59e3ba06a06c038e4
+SHA512:
+  metadata.gz: 1aece50a74ff32c555fadf7cf4348cc9dcaa50ce104a23f266a9763dfc86cd16cba3c204e58bae87b86565ac401a91980d8a9f0b7498b306fced53fa2a569c97
+  data.tar.gz: e5a34425077ce23c1f5abb8b77c65472a2339a31502878affae1e052611ded057886d542955151c64542c4d5a2f764048214e1661ddfaec948dbc92d2ec9f14d

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - 1.9.2
+  - jruby-19mode
+  - rbx-19mode

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/README.md

@@ -0,0 +1,161 @@
+Flip — flip your features
+================
+
+[![Build Status](https://travis-ci.org/pda/flip.png)](https://travis-ci.org/pda/flip)
+
+**Flip** provides a declarative, layered way of enabling and disabling application functionality at run-time.
+
+This gem optimizes for:
+
+* developer ease-of-use,
+* visibility and control for other stakeholders (like marketing); and
+* run-time performance
+
+There are three layers of strategies per feature:
+
+* default
+* database, to flip features site-wide for all users
+* cookie, to flip features just for you (or someone else)
+
+There is also a configurable system-wide default - !Rails.env.production?` works nicely.
+
+Flip has a dashboard UI that's easy to understand and use.
+
+![Feature Flipper Dashboard](https://dl.dropbox.com/u/13833591/flip-gem-dashboard.png "Feature Flipper Dashboard")
+
+Install
+-------
+
+**Rails 3.0, 3.1 and 3.2+**
+
+    # Gemfile
+    gem "flip"
+    
+    # Generate the model and migration
+    > rails g flip:install
+    
+    # Run the migration
+    > rake db:migrate
+
+
+Declaring Features
+------------------
+
+```ruby
+# This is the model class generated by rails g flip:install
+class Feature < ActiveRecord::Base
+  include Flip::Declarable
+
+  # The recommended Flip strategy stack.
+  strategy Flip::CookieStrategy
+  strategy Flip::DatabaseStrategy
+  strategy Flip::DefaultStrategy
+  default false
+
+  # A basic feature declaration.
+  feature :shiny_things
+
+  # Override the system-wide default.
+  feature :world_domination, default: true
+
+  # Enabled half the time..? Sure, we can do that.
+  feature :flakey,
+    default: proc { rand(2).zero? }
+
+  # Provide a description, normally derived from the feature name.
+  feature :something,
+    default: true,
+    description: "Ability to purchase enrollments in courses",
+
+end
+```
+
+
+Checking Features
+-----------------
+
+`Flip.on?` or the dynamic predicate methods are used to check feature state:
+
+```ruby
+Flip.on? :world_domination   # true
+Flip.world_domination?       # true
+
+Flip.on? :shiny_things       # false
+Flip.shiny_things?           # false
+```
+
+Views and controllers use the `feature?(key)` method:
+
+```erb
+<div>
+  <% if feature? :world_domination %>
+    <%= link_to "Dominate World", world_dominations_path %>
+  <% end %>
+</div>
+```
+
+
+Feature Flipping Controllers
+----------------------------
+
+The `Flip::ControllerFilters` module is mixed into the base `ApplicationController` class.  The following controller will respond with 404 Page Not Found to all but the `index` action unless the :new_stuff feature is enabled:
+
+```ruby
+class SampleController < ApplicationController
+
+  require_feature :something, :except => :index
+
+  def show
+  end
+
+  def index
+  end
+
+end
+```
+
+Dashboard
+---------
+
+The dashboard provides visibility and control over the features.
+
+The gem includes some basic styles:
+
+```haml
+= content_for :stylesheets_head do
+  = stylesheet_link_tag "flip"
+```
+
+You probably don't want the dashboard to be public.  Here's one way of implementing access control.
+
+app/controllers/admin/features_controller.rb:
+
+```ruby
+class Admin::FeaturesController < Flip::FeaturesController
+  before_filter :assert_authenticated_as_admin
+end
+```
+
+app/controllers/admin/feature_strategies_controller.rb:
+
+```ruby
+class Admin::FeatureStrategiesController < Flip::FeaturesController
+  before_filter :assert_authenticated_as_admin
+end
+```
+
+routes.rb:
+
+```ruby
+namespace :admin do
+  resources :features, only: [ :index ] do
+    resources :feature_strategies, only: [ :update, :destroy ]
+  end
+end
+
+mount Flip::Engine => "/admin/features"
+```
+
+----
+Created by Paul Annesley
+Copyright © 2011-2013 Learnable Pty Ltd, [MIT Licence](http://www.opensource.org/licenses/mit-license.php).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+desc "Run all tests"
+task :default => :spec
+
+desc "Run specs"
+task :spec do
+  system 'bundle exec rspec --color --format documentation spec/*_spec.rb'
+end

data/TODO

@@ -0,0 +1,3 @@
+FlipHelper view/controller helper.
+Optimize DatabaseStrategy.
+CookieStrategy::Loader before/after, not around.

data/app/assets/stylesheets/flip.css

@@ -0,0 +1,70 @@
+/* Flip */
+
+.flip {
+  margin: 0;
+}
+
+.flip h1 {
+  color:#666666;
+  font-size: 229%;
+  line-height: 44.928px;
+  margin: 13.5px 0;
+}
+
+.flip th.name, .flip th.description, .flip th.status {
+  visibility: hidden;
+}
+
+.flip td.name {
+  font-family: Monaco, sans-serif;
+  font-weight: bold;
+}
+
+.flip td.name, .flip td.description {
+  vertical-align: top;
+}
+
+.flip th {
+  font-weight: normal;
+  text-align: left;
+  vertical-align: top;
+}
+
+.flip th .description {
+  font-weight: normal;
+  display: block;
+  font-size: 80%;
+}
+
+.flip th, .flip td {
+  padding: 5px 10px;
+  width: 160px;
+  height: 40px;
+}
+
+.flip td.off, .flip td.on, .flip td.pass {
+  text-align: center;
+  text-transform: capitalize;
+}
+
+.flip td.off {
+  background-color: #fbb;
+}
+
+.flip td.on {
+  background-color: #cfc;
+}
+
+.flip td.pass {
+  background-color: #eef;
+}
+
+.flip form {
+  display: inline;
+}
+
+.flip form input[type=submit] {
+  font-size: 80%;
+  padding: 2px 5px;
+  margin: 0;
+}

data/app/controllers/flip/features_controller.rb

@@ -0,0 +1,47 @@
+module Flip
+  class FeaturesController < ApplicationController
+
+    def index
+      @p = FeaturesPresenter.new(FeatureSet.instance)
+    end
+
+    class FeaturesPresenter
+
+      include Flip::Engine.routes.url_helpers
+
+      def initialize(feature_set)
+        @feature_set = feature_set
+      end
+
+      def strategies
+        @feature_set.strategies
+      end
+
+      def definitions
+        @feature_set.definitions
+      end
+
+      def status(definition)
+        @feature_set.on?(definition.key) ? "on" : "off"
+      end
+
+      def default_status(definition)
+        @feature_set.default_for(definition) ? "on" : "off"
+      end
+
+      def strategy_status(strategy, definition)
+        if strategy.knows? definition
+          strategy.on?(definition) ? "on" : "off"
+        end
+      end
+
+      def switch_url(strategy, definition)
+        feature_strategy_path \
+          definition.key,
+          strategy.name.underscore
+      end
+
+    end
+
+  end
+end

data/app/controllers/flip/strategies_controller.rb

@@ -0,0 +1,31 @@
+module Flip
+  class StrategiesController < ApplicationController
+
+    include Flip::Engine.routes.url_helpers
+
+    def update
+      strategy.switch! feature_key, turn_on?
+      redirect_to features_url
+    end
+
+    def destroy
+      strategy.delete! feature_key
+      redirect_to features_url
+    end
+
+    private
+
+    def turn_on?
+      params[:commit] == "Switch On"
+    end
+
+    def feature_key
+      params[:feature_id].to_sym
+    end
+
+    def strategy
+      FeatureSet.instance.strategy(params[:id])
+    end
+
+  end
+end

data/app/helpers/flip_helper.rb

@@ -0,0 +1,9 @@
+# Access to feature-flipping configuration.
+module FlipHelper
+
+  # Whether the given feature is switched on
+  def feature?(key)
+    Flip.on? key
+  end
+
+end

data/app/views/flip/features/index.html.erb

@@ -0,0 +1,62 @@
+<div class="flip">
+  <h1>Feature Flippers</h1>
+
+  <table>
+    <thead>
+      <th class="name">Feature Name</th>
+      <th class="description">Description</th>
+      <th class="status">Status</th>
+      <% @p.strategies.each do |strategy| %>
+        <th>
+          <%= strategy.name %>
+          <span class="description"><%= strategy.description %></span>
+        </th>
+      <% end %>
+      <th>
+        Default
+        <span class="description">The system default when no strategies match.</span>
+      </th>
+    </thead>
+    <tbody>
+    <% @p.definitions.each do |definition| %>
+      <tr>
+        <td class="name"><%= definition.name %></td>
+
+        <td class="description"><%= definition.description %></td>
+
+        <%= content_tag :td, class: @p.status(definition) do %>
+          <%= @p.status definition %>
+        <% end %>
+
+        <% @p.strategies.each do |strategy| %>
+          <%= content_tag :td, class: @p.strategy_status(strategy, definition) || "pass" do %>
+            <%= @p.strategy_status strategy, definition %>
+
+            <% if strategy.switchable? %>
+              <%= form_tag(@p.switch_url(strategy, definition), method: :put) do %>
+                <% unless @p.strategy_status(strategy, definition) == "on" %>
+                  <%= submit_tag "Switch On" %>
+                <% end %>
+                <% unless @p.strategy_status(strategy, definition) == "off" %>
+                  <%= submit_tag "Switch Off" %>
+                <% end %>
+              <% end %>
+              <% unless @p.strategy_status(strategy, definition).blank? %>
+                <%= form_tag(@p.switch_url(strategy, definition), method: :delete) do %>
+                  <%= submit_tag "Delete" %>
+                <% end %>
+              <% end %>
+            <% end %>
+
+          <% end %>
+        <% end %>
+
+        <%= content_tag :td, class: @p.default_status(definition) do %>
+          <%= @p.default_status definition %>
+        <% end %>
+
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+</div>

data/config/routes.rb

@@ -0,0 +1,14 @@
+Flip::Engine.routes.draw do
+
+  scope module: "Flip" do
+
+    resources :features, path: "", only: [ :index ] do
+
+      resources :strategies,
+        only: [ :update, :destroy ]
+
+    end
+
+  end
+
+end

data/flip.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "flip/version"
+
+Gem::Specification.new do |s|
+  s.name        = "flip_fork"
+  s.version     = Flip::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Paul Annesley", "Brandt Lareau"]
+  s.email       = ["paul@annesley.cc, brandt.lareau@gmail.com"]
+  s.homepage    = "https://github.com/newdark/flip"
+  s.summary     = %q{A feature flipper for Rails web applications.}
+  s.description = %q{Declarative API for specifying features, switchable in declaration, database and cookies.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency("activesupport", "~> 3.0")
+  s.add_dependency("i18n")
+
+  s.add_development_dependency("rspec", "~> 2.5")
+  s.add_development_dependency("rake")
+end

data/lib/flip/abstract_strategy.rb

@@ -0,0 +1,26 @@
+module Flip
+  class AbstractStrategy
+
+    def name
+      self.class.name.split("::").last.gsub(/Strategy$/, "").underscore
+    end
+
+    def description; ""; end
+
+    # Whether the strategy knows the on/off state of the switch.
+    def knows? definition; raise; end
+
+    # Given the state is known, whether it is on or off.
+    def on? definition; raise; end
+
+    # Whether the feature can be switched on and off at runtime.
+    # If true, the strategy must also respond to switch! and delete!
+    def switchable?
+      false
+    end
+
+    def switch! key, on; raise; end
+    def delete! key; raise; end
+
+  end
+end

data/lib/flip/controller_filters.rb

@@ -0,0 +1,21 @@
+module Flip
+  module ControllerFilters
+
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      def require_feature key, options = {}
+        before_filter options do
+          flip_feature_disabled key unless Flip.on? key
+        end
+      end
+
+    end
+
+    def flip_feature_disabled key
+      raise Flip::Forbidden.new(key)
+    end
+
+  end
+end

data/lib/flip/cookie_strategy.rb

@@ -0,0 +1,62 @@
+# Uses cookie to determine feature state.
+module Flip
+  class CookieStrategy < AbstractStrategy
+
+    def description
+      "Uses cookies to apply only to your session."
+    end
+
+    def knows? definition
+      cookies.key? cookie_name(definition)
+    end
+
+    def on? definition
+      cookies[cookie_name(definition)] === "true"
+    end
+
+    def switchable?
+      true
+    end
+
+    def switch! key, on
+      cookies[cookie_name(key)] = on ? "true" : "false"
+    end
+
+    def delete! key
+      cookies.delete cookie_name(key)
+    end
+
+    def self.cookies= cookies
+      @cookies = cookies
+    end
+
+    def cookie_name(definition)
+      definition = definition.key unless definition.is_a? Symbol
+      "flip_#{definition}"
+    end
+
+    private
+
+    def cookies
+      self.class.instance_variable_get(:@cookies) || {}
+    end
+
+    # Include in ApplicationController to push cookies into CookieStrategy.
+    # Users before_filter and after_filter rather than around_filter to
+    # avoid pointlessly adding to stack depth.
+    module Loader
+      extend ActiveSupport::Concern
+      included do
+        before_filter :flip_cookie_strategy_before
+        after_filter :flip_cookie_strategy_after
+      end
+      def flip_cookie_strategy_before
+        CookieStrategy.cookies = cookies
+      end
+      def flip_cookie_strategy_after
+        CookieStrategy.cookies = nil
+      end
+    end
+
+  end
+end

data/lib/flip/database_strategy.rb

@@ -0,0 +1,40 @@
+# Database backed system-wide
+module Flip
+  class DatabaseStrategy < AbstractStrategy
+
+    def initialize(model_klass = Feature)
+      @klass = model_klass
+    end
+
+    def description
+      "Database backed, applies to all users."
+    end
+
+    def knows? definition
+      !!feature(definition)
+    end
+
+    def on? definition
+      feature(definition).enabled?
+    end
+
+    def switchable?
+      true
+    end
+
+    def switch! key, enable
+      @klass.find_or_initialize_by_key(key.to_s).update_attributes! enabled: enable
+    end
+
+    def delete! key
+      @klass.find_by_key(key.to_s).try(:destroy)
+    end
+
+    private
+
+    def feature(definition)
+      @klass.find_by_key definition.key.to_s
+    end
+
+  end
+end

data/lib/flip/declarable.rb

@@ -0,0 +1,24 @@
+module Flip
+  module Declarable
+
+    def self.extended(base)
+      FeatureSet.reset
+    end
+
+    # Adds a new feature definition, creates predicate method.
+    def feature(key, options = {})
+      FeatureSet.instance << Flip::Definition.new(key, options)
+    end
+
+    # Adds a strategy for determining feature status.
+    def strategy(strategy)
+      FeatureSet.instance.add_strategy strategy
+    end
+
+    # The default response, boolean or a Proc to be called.
+    def default(default)
+      FeatureSet.instance.default = default
+    end
+
+  end
+end

data/lib/flip/declaration_strategy.rb

@@ -0,0 +1,20 @@
+# Uses :default option passed to feature declaration.
+# May be boolean or a Proc to be passed the definition.
+module Flip
+  class DeclarationStrategy < AbstractStrategy
+
+    def description
+      "The default status declared with the feature."
+    end
+
+    def knows? definition
+      !definition.options[:default].nil?
+    end
+
+    def on? definition
+      default = definition.options[:default]
+      default.is_a?(Proc) ? default.call(definition) : default
+    end
+
+  end
+end

data/lib/flip/definition.rb

@@ -0,0 +1,21 @@
+module Flip
+  class Definition
+
+    attr_accessor :key
+    attr_accessor :options
+
+    def initialize(key, options = {})
+      @key = key
+      @options = options.reverse_merge \
+        description: key.to_s.humanize + "."
+    end
+
+    alias :name :key
+    alias :to_s :key
+
+    def description
+      options[:description]
+    end
+
+  end
+end

data/lib/flip/engine.rb

@@ -0,0 +1,9 @@
+module Flip
+  class Engine < ::Rails::Engine
+
+    initializer "flip.blarg" do
+      ActionController::Base.send(:include, Flip::CookieStrategy::Loader)
+    end
+
+  end
+end