ee_arturo 1.3.4

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NjI3NWU5NDQ3N2EwZGY5Y2RjZjA2M2ZkNzIzMDUzZjllN2FjMDM5MA==
+  data.tar.gz: !binary |-
+    MjkzYzk0NDQxMDJjYjI4YjJmYjFjYjAwM2JjYzk5ZmUzNDQwZDUyMg==
+SHA512:
+  metadata.gz: !binary |-
+    ZjNjM2QzMDg5MjRkNTcxYzRhMjZiNDUxZDI4NTZjODMzNjczNzU0N2YwN2Y0
+    ZDRmYjRjOTk4YTk5NjI1Yjk5NjU0N2ZlYjFiOWY1NDZjMGRiOTM1MDUwMjE2
+    Y2JlNTA5YmFiOWExYjM0MjFkM2MyODIxYTY5NGI5MTExYmRlMDg=
+  data.tar.gz: !binary |-
+    YmEyYjFiZGZiYWM4NDk1MTcxOWIyNTgyZTZjMGFjMDQ1ZTJjNDczYjVlMjM3
+    ZmFmOGZhZmRjZWZlY2I4ZmNjZjMxYWVmOWFlZTUyYmMxYWRkNjc1YWEzYjU4
+    ZTJlM2Y1Y2EzNjE3MmNlYzc1YmE1M2UyOWE2Y2EyYmQ2YmEyMmQ=

data/HISTORY.md

@@ -0,0 +1,16 @@
+## v 1.1.0 - cleanup
+ * changed `require_feature!` to `require_feature`
+ * replaced `Arturo.permit_management` and `Arturo.feature_recipient`
+   blocks with instance methods
+   `Arturo::FeatureManagement.may_manage_features?` and
+   `Arturo::FeatureAvailability.feature_recipient`
+
+## v 1.0.0 - Initial Release
+ * `require_feature!` controller filter
+ * `if_feature_enabled` controller and view method
+ * `feature_enabled?` controller and view method
+ * CRUD for features
+ * `Arturo.permit_management` to configure management permission
+ * `Arturo.feature_recipient` to configure on what basis features are deployed
+ * whitelists and blacklists
+ 

data/README.md

@@ -0,0 +1,295 @@
+## What
+
+Arturo provides feature sliders for Rails. It lets you turn features on and off
+just like
+[feature flippers](http://code.flickr.com/blog/2009/12/02/flipping-out/),
+but offers more fine-grained control. It supports deploying features only for
+a given percent* of your users and whitelisting and blacklisting users based
+on any criteria you can express in Ruby.
+
+    * The selection isn't random. It's not even pseudo-random. It's completely
+      deterministic. This assures that if a user has a feature on Monday, the
+      user will still have it on Tuesday (unless, of course, you *decrease*
+      the feature's deployment percentage or change its white- or blacklist
+      settings).
+
+### A quick example
+
+Trish, a developer is working on a new feature: a live feed of recent postings
+in the user's city that shows up in the user's sidebar. First, she uses Arturo's
+view helpers to control who sees the sidebar widget:
+
+    <%# in app/views/layout/_sidebar.html.erb: %>
+    <% if_feature_enabled(:live_postings) do %>
+    <div class='widget'>
+      <h3>Recent Postings</h3>
+      <ol id='live_postings'>
+      </ol>
+    </div>
+    <% end %>
+
+Then Trish writes some Javascript that will poll the server for recent
+postings and put them in the sidebar widget:
+
+    // in public/javascript/live_postings.js:
+    $(function() {
+      var livePostingsList = $('#live_postings');
+      if (livePostingsList.length > 0) {
+        var updatePostingsList = function() {
+          livePostingsList.load('/listings/recent');
+          setTimeout(updatePostingsList, 30);
+        }
+        updatePostingsList();
+      }
+    });
+
+Trish uses Arturo's Controller filters to control who has access to
+the feature:
+
+    # in app/controllers/postings_controller:
+    class PostingsController < ApplicationController
+      require_feature :live_postings, :only => :recent
+      # ...
+    end
+
+Trish then deploys this code to production. Nobody will see the feature yet,
+since it's not on for anyone. (In fact, the feature doesn't yet exist
+in the database, which is the same as being deployed to 0% of users.) A week
+later, when the company is ready to start deploying the feature to a few
+people, the product manager, Vijay, signs in to their site and navigates
+to `/features`, adds a new feature called "live_postings" and sets its
+deployment percentage to 3%. After a few days, the operations team decides
+that the increase in traffic is not going to overwhelm their servers, and
+Vijay can bump the deployment percentage up to 50%. A few more days go by
+and they clean up the last few bugs they found with the "live_postings"
+feature and deploy it to all users.
+
+## Installation
+
+### In Rails 3, with Bundler
+
+    gem 'arturo', '~> 1.0'
+
+### In Rails 3, without Bundler
+
+    $ gem install arturo --version="~> 1.0"
+
+### In Rails 2.3
+
+For Rails 2.3 support, see the
+[`rails_2_3` branch](http://github.com/jamesarosen/arturo/tree/rails_2_3)
+of Arturo.
+
+## Configuration
+
+### In Rails
+
+#### Run the generators:
+
+    $ rails g arturo:migration
+    $ rails g arturo:initializer
+    $ rails g arturo:route
+    $ rails g arturo:assets
+
+#### Run the migration:
+
+    $ rake db:migrate
+
+#### Edit the generated migration as necessary
+
+#### Edit the configuration
+
+##### Initializer
+
+Open up the newly-generated `config/initializers/arturo_initializer.rb`.
+There are configuration options for the following:
+
+ * the method that determines whether a user has permission to manage features
+   (see [admin permissions](#adminpermissions))
+ * the method that returns the object that has features
+   (e.g. User, Person, or Account; see
+   [feature recipients](#featurerecipients))
+ * whitelists and blacklists for features
+   (see [white- and blacklisting](#wblisting))
+
+##### CSS
+
+Open up the newly-generated `public/stylehseets/arturo_customizations.css`.
+You can add any overrides you like to the feature configuration page styles
+here. **Do not** edit `public/stylehseets/arturo.css` as that file may be
+overwritten in future updates to Arturo.
+
+### In other frameworks
+
+Arturo is a Rails engine. I want to promote reuse on other frameworks by
+extracting key pieces into mixins, though this isn't done yet. Open an
+[issue](http://github.com/jamesarosen/arturo/issues) and I'll be happy to
+work with you on support for your favorite framework.
+
+## Deep-Dive
+
+### <span id='adminpermissions'>Admin Permissions</span>
+
+`Arturo::FeatureManagement#may_manage_features?` is a method that is run in
+the context of a Controller or View instance. It should return `true` if
+and only if the current user may manage permissions. The default implementation
+is as follows:
+
+    current_user.present? && current_user.admin?
+
+You can change the implementation in
+`config/initializers/arturo_initializer.rb`. A reasonable implementation
+might be
+
+    Arturo.permit_management do
+      signed_in? && current_user.can?(:manage_features)
+    end
+
+### <span id='featurerecipients'>Feature Recipients</span>
+
+Clients of Arturo may want to deploy new features on a per-user, per-project,
+per-account, or other basis. For example, it is likely Twitter deployed
+"#newtwitter" on a per-user basis. Conversely, Facebook -- at least in its
+early days -- may have deployed features on a per-university basis. It wouldn't
+make much sense to deploy a feature to one user of a Basecamp project but not
+to others, so 37Signals would probably want a per-project or per-account basis.
+
+`Arturo::FeatureAvailability#feature_recipient` is intended to support these
+many use cases. It is a method that returns the current "thing" (a user, account,
+project, university, ...) that is a member of the category that is the basis for
+deploying new features. It should return an `Object` that responds to `#id`.
+
+The default implementation simply returns `current_user`. Like
+`Arturo::FeatureManagement#may_manage_features?`, this method can be configured
+in `config/initializers/arturo_initializer.rb`. If you want to deploy features
+on a per-account basis, a reasonable implementation might be
+
+    Arturo.feature_recipient do
+      current_account
+    end
+
+or
+
+    Arturo.feature_recipient do
+      current_user.account
+    end
+
+If the block returns `nil`, the feature will be disabled.
+
+### <span id='wblisting'>Whitelists & Blacklists</span>
+
+Whitelists and blacklists allow you to control exactly which users or accounts
+will have a feature. For example, if all premium users should have the
+`:awesome` feature, place the following in
+`config/initializers/arturo_initializer.rb`:
+
+    Arturo::Feature.whitelist(:awesome) do |user|
+      user.account.premium?
+    end
+
+If, on the other hand, no users on the free plan should have the
+`:awesome` feature, place the following in
+`config/initializers/arturo_initializer.rb`:
+
+    Arturo::Feature.blacklist(:awesome) do |user|
+      user.account.free?
+    end
+
+### Feature Conditionals
+
+All that configuration is just a waste of time if Arturo didn't modify the
+behavior of your application based on feature availability. There are a few
+ways to do so.
+
+#### Controller Filters
+
+If an action should only be available to those with a feature enabled,
+use a before filter. The following will raise a 403 Forbidden error for
+every action within `BookHoldsController` that is invoked by a user who
+does not have the `:hold_book` feature.
+
+    class BookHoldsController < ApplicationController
+      require_feature :hold_book
+    end
+
+`require_feature` accepts as a second argument a `Hash` that it passes on
+to `before_filter`, so you can use `:only` and `:except` to specify exactly
+which actions are filtered.
+
+If you want to customize the page that is rendered on 403 Forbidden
+responses, put the view in
+`RAILS_ROOT/app/views/arturo/features/forbidden.html.erb`. Rails will
+check there before falling back on Arturo's forbidden page.
+
+#### Conditional Evaluation
+
+Both controllers and views have access to the `if_feature_enabled` and
+`feature_enabled?` methods. The former is used like so:
+
+    <% if_feature_enabled?(:reserve_table) %>
+      <%= link_to 'Reserve a table', new_restaurant_reservation_path(:restaurant_id => @restaurant) %>
+    <% end %>
+
+The latter can be used like so:
+
+    def widgets_for_sidebar
+      widgets = []
+      widgets << twitter_widget if feature_enabled?(:twitter_integration)
+      ...
+      widgets
+    end
+
+#### Rack Middleware
+
+    require 'arturo'
+    use Arturo::Middleware, :feature => :my_feature
+
+#### Outside a Controller
+
+If you want to check availability outside of a controller or view (really
+outside of something that has `Arturo::FeatureAvailability` mixed in), you
+can ask either
+
+    Arturo.feature_enabled_for?(:foo, recipient)
+
+or the slightly fancier
+
+    Arturo.foo_enabled_for?(recipient)
+
+Both check whether the `foo` feature exists and is enabled for `recipient`.
+
+#### Caching
+
+**Note**: Arturo does not yet have caching support. Be very careful when
+caching actions or pages that involve feature detection as you will get
+strange behavior when a user who has access to a feature requests a page
+just after one who does not (and vice versa). The following is the
+**intended** support for caching.
+
+Both the `require_feature` before filter and the `if_feature_enabled` block
+evaluation automatically append a string based on the feature's
+`last_modified` timestamp to cache keys that Rails generates. Thus, you don't
+have to worry about expiring caches when you increase a feature's deployment
+percentage. See `Arturo::CacheSupport` for more information.
+
+## The Name
+
+Arturo gets its name from
+[Professor Maximillian Arturo](http://en.wikipedia.org/wiki/Maximillian_Arturo)
+on [Sliders](http://en.wikipedia.org/wiki/Sliders).
+
+## Contributing ##
+
+For bug reports, open an [issue](https://github.com/jamesarosen/Timecop.js/issues)
+on GitHub.
+
+Timecop.js has a ‘commit-bit’ policy, much like the Rubinius project
+and Gemcutter. Submit a patch that is accepted, and you can get full
+commit access to the project. All you have to do is open an issue
+asking for access and I'll add you as a collaborator.
+Feel free to fork the project though and have fun in your own sandbox.
+
+## Authors ##
+
+* [https://github.com/jamesarosen](James A. Rosen)
+* [https://github.com/plukevdh](Luke van der Hoeven)

data/app/controllers/arturo/features_controller.rb

@@ -0,0 +1,105 @@
+require 'action_controller'
+
+# TODO: this doesn't do anything radically out of the ordinary.
+#       Are there Rails 3 patterns/mixins/methods I can use
+#       to clean it up a bit?
+module Arturo
+
+  # Handles all Feature actions. Clients of the Arturo engine
+  # should redefine Arturo::FeaturesController#permitted? to
+  # return true only for users who are permitted to manage features.
+  class FeaturesController < ApplicationController
+    include Arturo::FeatureManagement
+
+    unloadable
+    respond_to :html, :json, :xml
+    before_filter :require_permission
+    before_filter :load_feature, :only => [ :show, :edit, :update, :destroy ]
+
+    def index
+      @features = Arturo::Feature.all
+      respond_with @features
+    end
+
+    def update_all
+      updated_count = 0
+      errors = []
+      features_params = params[:features] || {}
+      features_params.each do |id, attributes|
+        feature = Arturo::Feature.find_by_id(id)
+        if feature.blank?
+          errors << t('arturo.features.flash.no_such_feature', :id => id)
+        elsif feature.update_attributes(attributes)
+          updated_count += 1
+        else
+          errors << t('arturo.features.flash.error_updating', :id => id)
+        end
+      end
+      if errors.any?
+        flash[:error] = errors
+      else
+        flash[:success] = t('arturo.features.flash.updated_many', :count => updated_count)
+      end
+      redirect_to features_path
+    end
+
+    def show
+      respond_with @feature
+    end
+
+    def new
+      @feature = Arturo::Feature.new(params[:feature])
+      respond_with @feature
+    end
+
+    def create
+      @feature = Arturo::Feature.new(params[:feature])
+      if @feature.save
+        flash[:notice] = t('arturo.features.flash.created', :name => @feature.to_s)
+        redirect_to features_path
+      else
+        flash[:alert] = t('arturo.features.flash.error_creating', :name => @feature.to_s)
+        render :action => 'new'
+      end
+    end
+
+    def edit
+      respond_with @feature
+    end
+
+    def update
+      if @feature.update_attributes(params[:feature])
+        flash[:notice] = t('arturo.features.flash.updated', :name => @feature.to_s)
+        redirect_to feature_path(@feature)
+      else
+          flash[:alert] = t('arturo.features.flash.error_updating', :name => @feature.to_s)
+        render :action => 'edit'
+      end
+    end
+
+    def destroy
+      if @feature.destroy
+        flash[:notice] = t('arturo.features.flash.removed', :name => @feature.to_s)
+      else
+        flash[:alert] = t('arturo.features.flash.error_removing', :name => @feature.to_s)
+      end
+      redirect_to features_path
+    end
+
+    protected
+
+    def require_permission
+      unless may_manage_features?
+        render :action => 'forbidden', :status => 403
+        return false
+      end
+    end
+
+    def load_feature
+      @feature ||= Arturo::Feature.find(params[:id])
+    end
+
+  end
+
+end
+

data/app/helpers/arturo/features_helper.rb

@@ -0,0 +1,27 @@
+require 'action_view/helpers/tag_helper'
+require 'action_view/helpers/form_tag_helper'
+
+module Arturo
+  module FeaturesHelper
+    include ActionView::Helpers::TagHelper
+
+    def deployment_percentage_range_and_output_tags(name, value, options = {})
+      id = sanitize_to_id(name)
+      options = {
+        'type' => 'range',
+        'name' => name,
+        'id' => id,
+        'value' => value,
+        'min' => '0',
+        'max' => '100',
+        'step' => '1',
+        'class' => 'deployment_percentage'
+      }.update(options.stringify_keys)
+      tag(:input, options) + deployment_percentage_output_tag(id, value)
+    end
+
+    def deployment_percentage_output_tag(id, value)
+      content_tag(:output, value, { 'for' => id, 'class' => 'deployment_percentage no_js' })
+    end
+  end
+end

data/app/models/arturo/feature.rb

@@ -0,0 +1,76 @@
+require 'active_record'
+
+# a stub
+# possible TODO: remove and and refactor into an acts_as_feature mixin
+module Arturo
+  class Feature < ::ActiveRecord::Base
+
+    include Arturo::SpecialHandling
+
+    Arturo::Feature::SYMBOL_REGEX = /^[a-zA-z][a-zA-Z0-9_]*$/
+    DEFAULT_ATTRIBUTES = { :deployment_percentage => 0 }.with_indifferent_access
+
+    attr_accessible :symbol, :deployment_percentage if ActiveRecord::VERSION::MAJOR < 4
+    attr_readonly :symbol
+
+    validates_presence_of :symbol, :deployment_percentage
+    validates_uniqueness_of :symbol, :allow_blank => true
+    validates_numericality_of :deployment_percentage,
+                                            :only_integer => true,
+                                            :allow_blank => true,
+                                            :greater_than_or_equal_to => 0,
+                                            :less_than_or_equal_to => 100
+
+    # Looks up a feature by symbol. Also accepts a Feature as input.
+    # @param [Symbol, Arturo::Feature] feature_or_name a Feature or the Symbol of a Feature
+    # @return [Arturo::Feature, nil] the Feature if found, else nil
+    def self.to_feature(feature_or_symbol)
+      return feature_or_symbol if feature_or_symbol.kind_of?(self)
+      self.where(:symbol => feature_or_symbol.to_sym).first
+    end
+
+    # Create a new Feature
+    def initialize(attributes = {})
+      super(DEFAULT_ATTRIBUTES.merge(attributes || {}))
+    end
+
+    # @param [Object] feature_recipient a User, Account,
+    #                 or other model with an #id method
+    # @return [true,false] whether or not this feature is enabled
+    #                      for feature_recipient
+    # @see Arturo::SpecialHandling#whitelisted?
+    # @see Arturo::SpecialHandling#blacklisted?
+    def enabled_for?(feature_recipient)
+      return false if feature_recipient.nil?
+      return false if blacklisted?(feature_recipient)
+      return true if  whitelisted?(feature_recipient)
+      passes_threshold?(feature_recipient)
+    end
+
+    def name
+      return I18n.translate("arturo.feature.nameless") if symbol.blank?
+      I18n.translate("arturo.feature.#{symbol}", :default => symbol.to_s.titleize)
+    end
+
+    def to_s
+      "Feature #{name}"
+    end
+
+    def to_param
+      persisted? ? "#{id}-#{symbol.to_s.parameterize}" : nil
+    end
+
+    def inspect
+      "<Arturo::Feature #{name}, deployed to #{deployment_percentage}%>"
+    end
+
+    protected
+
+    def passes_threshold?(feature_recipient)
+      threshold = self.deployment_percentage || 0
+      return false if threshold == 0
+      return true if threshold == 100
+      (((feature_recipient.id + (self.id || 1) + 17) * 13) % 100) < threshold
+    end
+  end
+end

data/app/views/arturo/features/_feature.html.erb

@@ -0,0 +1,5 @@
+<tr class='feature' id="feature_<%= feature.id %>">
+  <td><code class='ruby symbol'><%= feature.symbol %></code></td>
+  <td><%= deployment_percentage_range_and_output_tags("features[#{feature.id}][deployment_percentage]", feature.deployment_percentage) %></td>
+  <td><%= link_to t('.edit'), edit_feature_path(feature), :rel => 'edit', :class => 'edit' %></td>
+</tr>

data/app/views/arturo/features/_form.html.erb

@@ -0,0 +1,16 @@
+<%= form_for(feature, :as => 'feature', :url => (feature.new_record? ? features_path : feature_path(feature))) do |form| %>
+  <fieldset>
+    <legend><%= legend %></legend>
+
+    <%= form.label(:symbol) %>
+    <%= form.text_field(:symbol, :required => 'required', :pattern => Arturo::Feature::SYMBOL_REGEX.source, :class => 'symbol') %>
+    <%= error_messages_for(feature, :symbol) %>
+
+    <%= form.label(:deployment_percentage) %>
+    <%= form.range_field(:deployment_percentage, :min => '0', :max => '100', :step => '1', :class => 'deployment_percentage') %>
+    <%= deployment_percentage_output_tag 'feature_deployment_percentage', feature.deployment_percentage %>
+    <%= error_messages_for(feature, :deployment_percentage) %>
+
+    <footer><%= form.submit %></footer>
+  </fieldset>
+<% end %>

data/app/views/arturo/features/edit.html.erb

@@ -0,0 +1,2 @@
+<h2><%= t('.title', :name => @feature.name) %></h2>
+<%= render :partial => 'form', :locals => { :feature => @feature, :legend =>  t('.legend', :name => @feature.name) } %>

data/app/views/arturo/features/forbidden.html.erb

@@ -0,0 +1,2 @@
+<h2><%= t('.title') %></h2>
+<p><%= t('.text') %></p>

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

@@ -0,0 +1,29 @@
+<h2><%= t('.title') %></h2>
+<%= form_tag(features_path, :method => 'put', 'data-update-path' => feature_path(:id => ':id'), :remote => true) do %>
+  <fieldset>
+    <legend><%= t('.title') %></legend>
+    <table class='features'>
+      <col class='name' />
+      <col class='deployment_percentage' />
+      <col class='edit' />
+      <thead>
+        <tr>
+          <th><%= t('activerecord.attributes.arturo/feature.name') %></th>
+          <th><%= t('activerecord.attributes.arturo/feature.deployment_percentage') %></th>
+          <th>&nbsp;</th>
+        </tr>
+      </thead>
+      <tfoot>
+        <tr><th colspan='4'><%= link_to t('.new'), new_feature_path %> <%= submit_tag %></th></tr>
+      </tfoot>
+      <tbody>
+        <% @features.each do |f| %>
+          <%= render :partial => 'feature', :locals => { :feature => f } %>
+        <% end %>
+        <% if @features.none? %>
+        <tr class='if_no_features'><td colspan='4'><%= t('.none_yet') %></td></tr>
+        <% end %>
+      </tbody>
+    </table>
+  </fieldset>
+<% end %>

data/app/views/arturo/features/new.html.erb

@@ -0,0 +1,2 @@
+<h2><%= t('.title') %></h2>
+<%= render :partial => 'form', :locals => { :feature => @feature, :legend =>  t('.legend') } %>

data/app/views/arturo/features/show.html.erb

@@ -0,0 +1,2 @@
+<h2><%= t('.title', :name => @feature.name) %></h2>
+<p>Deployment percentage: <%= @feature.deployment_percentage %></p>

data/config/locales/en.yml

@@ -0,0 +1,40 @@
+en:
+  activerecord:
+    models:
+      "arturo/feature": "Feature"
+    attributes:
+      "arturo/feature":
+        symbol: "Symbol"
+        name: "Name"
+        deployment_percentage: "Deployment Percentage"
+  arturo:
+    feature:
+      nameless: "(no name)"
+    features:
+      index:
+        title: 'Features'
+        new: 'New'
+        none_yet: No features yet.
+      new:
+        title: New Feature
+        legend: "New Feature"
+      edit:
+        title: "Edit Feature %{name}"
+        legend: "Edit Feature %{name}"
+      feature:
+        edit: 'Edit'
+      show:
+        title: "Feature %{name}"
+      forbidden:
+        title: Forbidden
+        text: You do not have permission to access that resource.
+      flash:
+        no_such_feature: "No such feature: %{id}"
+        error_updating: "Error updating feature %{id}"
+        updated_many: "Updated %{count} feature(s)"
+        created: "Created %{name}"
+        error_creating: "Sorry, there was an error creating the feature."
+        updated: "Updated %{name}"
+        error_updating: "Sorry, there was an error updating %{name}"
+        removed: "Removed %{name}"
+        error_removing: "Sorry, there was an error removing %{name}"

data/config/routes.rb

@@ -0,0 +1,14 @@
+# In Rails edge, the engine can have its own route set
+# and be mounted within an application at a sub-URL.
+# In 3.0.1, this is not yet available.
+
+# TODO replace this with the commented-out version below
+Rails.application.routes.draw do
+  resources :features, :controller => 'arturo/features'
+  put 'features', :to => 'arturo/features#update_all', :as => 'features'
+end
+
+# Arturo::Engine.routes.draw do
+#   resources :features, :controller => 'arturo/features'
+#   put 'features', :to => 'arturo/features#update_all', :as => 'features'
+# end