periscope 0.1.0

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/README.rdoc

@@ -0,0 +1,58 @@
+= Periscope
+
+Bring your models' scopes up above the surface.
+
+Periscope acts like +attr_accessible+ or +attr_protected+, but for your models' scopes.
+
+== The Problem
+
+More often than not, the index action in a RESTful Rails controller is expected to do a lot more than simply return all the records for a given model. We ask it to do all sorts of stuff like filtering, sorting and paginating results. Of course, this is typically done using _scopes_.
+
+But sometimes it can get ugly building long, complicated chains of scope in the controller, especially when you try to give your users control over the scoping. Picture this:
+
+  def index
+    @articles = Article.scoped
+    @articles = @articles.published_after(params[:published_after]) if params.key?(:published_after)
+    @articles = @articles.published_before(params[:published_before]) if params.key?(:published_before)
+  end
+
+You can imagine how bad this would get if more than two scopes were involved.
+
+== The Solution
+
+With Periscope, you can have this instead:
+
+  def index
+    @articles = Article.periscope(request.query_parameters)
+  end
+
+The +periscope+ method will find keys in your params matching your scope names and chain your scopes for you.
+
+<b>Note:</b> We're using <code>request.query_parameters</code> so we can exclude your controller and action params. <code>request.query_parameters</code> will just return the params that show up after the "?" in the URL.
+
+== But Wait!
+
+"What if I don't want to make all my scopes publicly accessible?"
+
+In your model you can use either the +scope_accessible+ or +scope_protected+ method to specify which scopes you want Periscope to pay attention to.
+
+  class User < ActiveRecord::Base
+    attr_accessible :name, :gender, :salary
+  
+    scope :gender, lambda{|g| where(:gender => g) }
+    scope :makes_more_than, lambda{|s| where('users.salary >= ?', s) }
+  
+    scope_accessible :gender
+  end
+
+And in your controller:
+
+  class UsersController < ApplicationController
+    def index
+      @users = User.periscope(request.query_parameters)
+    end
+  end
+
+Now, requests to <code>/users?gender=male</code> will filter results to only male users. But a request to <code>/users?makes_more_than=1000000</code> will return all users, silently ignoring the protected scope.
+
+By default, all scopes are protected.

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/init.rb

@@ -0,0 +1 @@
+require 'periscope'

data/lib/periscope.rb

@@ -0,0 +1,6 @@
+require 'active_support'
+require 'periscope/version'
+
+Dir[File.expand_path('../periscope/adapters/**/*.rb', __FILE__)].each{|f| require f }
+
+ActiveRecord::Base.send(:include, Periscope::Adapters::ActiveRecord) if defined?(ActiveRecord::Base)

data/lib/periscope/adapters/abstract.rb

@@ -0,0 +1,67 @@
+require 'active_support/core_ext/class/attribute.rb'
+require 'periscope/permission_set'
+
+module Periscope
+  module Adapters
+    module Abstract
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_accessible_scopes
+        class_attribute :_protected_scopes
+        class_attribute :_periscope_authorizer
+      end
+
+      module ClassMethods
+        def periscope(*)
+          raise NotImplementedError
+        end
+
+        def scope_protected(*scopes)
+          self._protected_scopes = protected_scopes + scopes
+          self._periscope_authorizer = _protected_scopes
+        end
+
+        alias_method :down_periscope, :scope_protected
+
+        def scope_accessible(*scopes)
+          self._accessible_scopes = accessible_scopes + scopes
+          self._periscope_authorizer = _accessible_scopes
+        end
+
+        alias_method :up_periscope, :scope_accessible
+
+        def protected_scopes
+          self._protected_scopes ||= BlackList.new.tap do |list|
+            list.logger = logger if respond_to?(:logger)
+          end
+        end
+
+        def accessible_scopes
+          self._accessible_scopes ||= WhiteList.new(scopes_accessible_by_default).tap do |list|
+            list.logger = logger if respond_to?(:logger)
+          end
+        end
+
+        def periscope_authorizer
+          self._periscope_authorizer ||= accessible_scopes
+        end
+
+        def scopes_accessible_by_default
+          []
+        end
+      end
+
+      module InstanceMethods
+        protected
+          def sanitize_for_search(params)
+            search_authorizer.sanitize(params)
+          end
+
+          def search_authorizer
+            self.class.periscope_authorizer
+          end
+      end
+    end
+  end
+end

data/lib/periscope/adapters/active_record.rb

@@ -0,0 +1,18 @@
+require 'periscope/adapters/abstract'
+
+module Periscope
+  module Adapters
+    module ActiveRecord
+      extend ActiveSupport::Concern
+      include Abstract
+
+      module ClassMethods
+        def periscope(params = {})
+          periscope_authorizer.sanitize(params).inject(scoped) do |chain, (key, value)|
+            chain.send(key, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/periscope/permission_set.rb

@@ -0,0 +1,34 @@
+require 'set'
+require 'periscope/sanitizer'
+
+module Periscope
+  class PermissionSet < Set
+    def initialize(values = nil)
+      super(values, &:to_s)
+    end
+
+    def +(values)
+      super(values.map(&:to_s))
+    end
+
+    def include?(value)
+      super(value.to_s)
+    end
+  end
+
+  class WhiteList < PermissionSet
+    include Sanitizer
+
+    def deny?(value)
+      !include?(value)
+    end
+  end
+
+  class BlackList < PermissionSet
+    include Sanitizer
+
+    def deny?(value)
+      include?(value)
+    end
+  end
+end

data/lib/periscope/sanitizer.rb

@@ -0,0 +1,27 @@
+module Periscope
+  module Sanitizer
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :logger
+    end
+
+    module InstanceMethods
+      def sanitize(params)
+        params.reject{|k,v| deny?(k) }.tap do |sanitized|
+          debug_protected_scope_removal(params, sanitized)
+        end
+      end
+
+      protected
+        def debug_protected_scope_removal(params, sanitized)
+          removed = params.keys - sanitized.keys
+          warn!(removed) if removed.any?
+        end
+
+        def warn!(scopes)
+          logger.debug("WARNING: Can't search protected scopes: #{scopes.join(', ')}") if logger
+        end
+    end
+  end
+end

data/lib/periscope/version.rb

@@ -0,0 +1,3 @@
+module Periscope
+  VERSION = '0.1.0'
+end

data/periscope.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'periscope/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'periscope'
+  s.version     = Periscope::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Steve Richert']
+  s.email       = ['steve.richert@gmail.com']
+  s.homepage    = 'https://github.com/laserlemon/periscope'
+  s.summary     = %(Bring your models' scopes up above the surface.)
+  s.description = %(Periscope acts like attr_accessible or attr_protected, but for your models' scopes.)
+
+  s.rubyforge_project = 'periscope'
+
+  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.0'
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'sqlite3'
+  s.add_development_dependency 'activerecord', '>= 3.0.0'
+end

data/spec/periscope/adapters/active_record_spec.rb

@@ -0,0 +1,129 @@
+require 'spec_helper'
+
+module Periscope
+  module Adapters
+    describe ActiveRecord do
+      it_should_behave_like 'an adapter'
+
+      describe :periscope do
+        subject do
+          Class.new(User).tap do |klass|
+            klass.class_eval do
+              scope :gender, lambda{|g| where(:gender => g) }
+              scope :makes, lambda{|s| where('users.salary >= ?', s) }
+              scope :rich, where('users.salary >= 1000000')
+            end
+          end
+        end
+
+        context 'ignores' do
+          specify 'all scopes by default' do
+            subject.should_receive(:gender).never
+            subject.should_receive(:makes).never
+
+            subject.periscope(:gender => 'male', :makes => 100000)
+          end
+
+          specify 'all scopes when none are accessible' do
+            subject.scope_accessible
+
+            subject.should_receive(:gender).never
+            subject.should_receive(:makes).never
+
+            subject.periscope(:gender => 'male', :makes => 100000)
+          end
+
+          specify 'protected scopes' do
+            subject.scope_protected :makes
+
+            subject.should_receive(:gender).with('male').once
+            subject.should_receive(:makes).never
+
+            subject.periscope(:gender => 'male', :makes => 100000)
+          end
+        end
+
+        context 'uses' do
+          specify 'all scopes when none are protected' do
+            subject.scope_protected
+
+            subject.should_receive(:gender).with('male').once
+            subject.should_receive(:makes).with(100000).once
+
+            subject.periscope(:gender => 'male', :makes => 100000)
+          end
+
+          specify 'accessible scopes' do
+            subject.scope_accessible :gender
+
+            subject.should_receive(:gender).with('male').once
+            subject.should_receive(:makes).never
+
+            subject.periscope(:gender => 'male', :makes => 100000)
+          end
+
+          specify 'accessible, zero-arity scopes' do
+            subject.scope_accessible :rich
+
+            subject.should_receive(:rich).with(true).once
+
+            lambda{ subject.periscope(:rich => true) }.should_not raise_error
+          end
+        end
+
+        context 'returns' do
+          before do
+            subject.delete_all
+            subject.create(:name => 'Henry', :gender => 'male', :salary => 50_000)
+            subject.create(:name => 'Penny', :gender => 'female', :salary => 1_000_000)
+            subject.create(:name => 'Sammy', :gender => 'male', :salary => 100_000)
+          end
+
+          let(:params){ {:gender => 'male', :rich => true} }
+
+          context 'all records' do
+            specify 'for no params' do
+              subject.periscope.map(&:name).should == %w(Henry Penny Sammy)
+            end
+
+            specify 'for empty params' do
+              subject.periscope({}).map(&:name).should == %w(Henry Penny Sammy)
+            end
+
+            specify 'for no accessible scopes' do
+              subject.scope_accessible
+
+              subject.periscope(params).map(&:name).should == %w(Henry Penny Sammy)
+            end
+
+            specify 'for all protected scopes' do
+              subject.scope_protected :gender, :rich
+
+              subject.periscope(params).map(&:name).should == %w(Henry Penny Sammy)
+            end
+          end
+
+          context 'scoped results' do
+            specify 'for an accessible scope' do
+              subject.scope_accessible :rich
+
+              subject.periscope(params).map(&:name).should == %w(Penny)
+            end
+
+            specify 'for an unprotected scope' do
+              subject.scope_protected :gender
+
+              subject.periscope(params).map(&:name).should == %w(Penny)
+            end
+
+            specify 'for multiple accessible scopes' do
+              subject.scope_accessible :gender, :rich
+
+              subject.periscope(params).should be_empty
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/periscope/black_list_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+module Periscope
+  describe BlackList do
+    it_should_behave_like 'a permission set'
+    it_should_behave_like 'a sanitizer'
+
+    let(:values){ %w(one two three) }
+    subject{ described_class.new(values) }
+
+    it 'denies an included value' do
+      subject.deny?(values.first).should == true
+    end
+
+    it 'accepts an excluded value' do
+      subject.deny?('four').should == false
+    end
+  end
+end

data/spec/periscope/version_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+module Periscope
+  describe VERSION do
+    it 'is a major/minor/patch version string' do
+      should be_a String
+      should match /^\d+\.\d+\.\d+$/
+    end
+  end
+end

data/spec/periscope/white_list_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+module Periscope
+  describe WhiteList do
+    it_should_behave_like 'a permission set'
+    it_should_behave_like 'a sanitizer'
+
+    let(:values){ %w(one two three) }
+    subject{ described_class.new(values) }
+
+    it 'accepts an included value' do
+      subject.deny?(values.first).should == false
+    end
+
+    it 'denies an excluded value' do
+      subject.deny?('four').should == true
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+Dir[File.expand_path('../support/**/*.rb', __FILE__)].each{|f| require f }
+
+require 'periscope'
+
+class FakeLogger
+  def debug(message)
+    output << message
+  end
+
+  def output
+    @output ||= []
+  end
+end
+

data/spec/support/abstract_examples.rb

@@ -0,0 +1,89 @@
+shared_examples_for 'an adapter' do
+  subject do
+    Class.new.tap do |klass|
+      klass.send(:include, described_class)
+    end
+  end
+
+  it 'adds accessible scopes' do
+    subject.scope_accessible :current, :expired
+
+    subject.accessible_scopes.should include(:current)
+    subject.accessible_scopes.should include(:expired)
+  end
+
+  it 'adds protected scopes' do
+    subject.scope_protected :current, :expired
+
+    subject.protected_scopes.should include(:current)
+    subject.protected_scopes.should include(:expired)
+  end
+
+  it 'stacks accessible scopes' do
+    subject.scope_accessible :current
+    subject.scope_accessible :expired
+
+    subject.accessible_scopes.should include(:current)
+    subject.accessible_scopes.should include(:expired)
+  end
+
+  it 'stacks protected scopes' do
+    subject.scope_protected :current
+    subject.scope_protected :expired
+
+    subject.protected_scopes.should include(:current)
+    subject.protected_scopes.should include(:expired)
+  end
+
+  it 'uses accessible scopes if defined last' do
+    subject.scope_protected :current
+    subject.scope_accessible :expired
+
+    subject.periscope_authorizer.should be_a(Periscope::WhiteList)
+    subject.periscope_authorizer.should == subject.accessible_scopes
+  end
+
+  it 'uses protected scopes if defined last' do
+    subject.scope_accessible :current
+    subject.scope_protected :expired
+
+    subject.periscope_authorizer.should be_a(Periscope::BlackList)
+    subject.periscope_authorizer.should == subject.protected_scopes
+  end
+
+  it 'defaults to using accessible scopes' do
+    subject.periscope_authorizer.should be_a(Periscope::WhiteList)
+    subject.periscope_authorizer.should == subject.accessible_scopes
+  end
+
+  it 'has no accesible scopes by default' do
+    subject.accessible_scopes.should be_empty
+  end
+
+  it 'has no protected scopes by default' do
+    subject.protected_scopes.should be_empty
+  end
+
+  it 'can override the default accessible scopes' do
+    subject.class_eval do
+      def self.scopes_accessible_by_default
+        [:current]
+      end
+    end
+
+    subject.accessible_scopes.should include(:current)
+  end
+
+  it 'makes its authorizer available to its instances' do
+    subject.scope_accessible :current
+
+    subject.new.send(:search_authorizer).should == subject.accessible_scopes
+  end
+
+  it 'sanitizes params from its instances' do
+    params = {:current => 'yes', :expired => 'no'}
+    subject.scope_accessible :current
+
+    subject.new.send(:sanitize_for_search, params).should == params.slice(:current)
+  end
+end

data/spec/support/connections/active_record.rb

@@ -0,0 +1,17 @@
+require 'active_record'
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'sqlite3',
+  :database => ':memory:'
+)
+
+ActiveRecord::Schema.define do
+  create_table :users do |t|
+    t.string :name
+    t.string :gender
+    t.integer :salary
+  end
+end
+
+class User < ActiveRecord::Base
+end

data/spec/support/permission_set_examples.rb

@@ -0,0 +1,35 @@
+shared_examples_for 'a permission set' do
+  it 'has unique values' do
+    values = %w(one two two three)
+
+    permission_set = described_class.new(values)
+    permission_set.to_a.should == values.uniq
+  end
+
+  it 'initializes with no values' do
+    lambda{ described_class.new }.should_not raise_error
+    described_class.new.should be_empty
+  end
+
+  it 'stringifies values when initializing' do
+    values = [:one, :two, :three]
+
+    permission_set = described_class.new(values)
+    permission_set.to_a.should == values.map(&:to_s)
+  end
+
+  it 'stringifies values when adding' do
+    values = [:one, :two, :three]
+
+    permission_set = described_class.new + values
+    permission_set.to_a.should == values.map(&:to_s)
+  end
+
+  it 'stringifies a value when checking for inclusion' do
+    values = %w(one two three)
+    value = values.first.to_sym
+
+    permission_set = described_class.new(values)
+    permission_set.should include(value)
+  end
+end

data/spec/support/sanitizer_examples.rb

@@ -0,0 +1,66 @@
+require 'active_support/core_ext/hash/slice'
+
+shared_examples_for 'a sanitizer' do
+  subject{ described_class.new }
+
+  let(:logger){ FakeLogger.new }
+  let(:params){ {:one => 1, :two => 2} }
+
+  it 'has its own logger' do
+    logger.should_receive(:debug).once
+
+    subject.logger = logger
+    subject.logger.should == logger
+
+    subject.logger.debug
+  end
+
+  it 'removes denied keys from a hash' do
+    subject.stub(:deny?).with(:one).and_return(false)
+    subject.stub(:deny?).with(:two).and_return(true)
+    subject.sanitize(params).should == params.slice(:one)
+  end
+
+  it "doesn't remove keys if none are denied" do
+    subject.stub(:deny? => false)
+    subject.sanitize(params).should == params
+  end
+
+  it 'debugs removed keys' do
+    subject.logger = logger
+    subject.logger.should_receive(:debug).once
+
+    subject.stub(:deny? => true)
+    subject.sanitize(params)
+  end
+
+  it "doesn't debug if there's no logger" do
+    subject.logger.should be_nil
+
+    allow_message_expectations_on_nil
+    subject.logger.should_receive(:debug).never
+
+    subject.stub(:deny? => true)
+    subject.sanitize(params)
+  end
+
+  it "doesn't debug if no keys are removed" do
+    subject.logger = logger
+    subject.logger.should_receive(:debug).never
+
+    subject.stub(:deny? => false)
+    subject.sanitize(params)
+  end
+
+  it 'only debugs the removed keys' do
+    subject.logger = logger
+
+    subject.stub(:deny?).with(:one).and_return(false)
+    subject.stub(:deny?).with(:two).and_return(true)
+    subject.sanitize(params)
+
+    message = subject.logger.output.pop
+    message.should_not match(/\bone\b/)
+    message.should match(/\btwo\b/)
+  end
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification 
+name: periscope
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Steve Richert
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-03 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: sqlite3
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :development
+  version_requirements: *id004
+description: Periscope acts like attr_accessible or attr_protected, but for your models' scopes.
+email: 
+- steve.richert@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.rdoc
+- Rakefile
+- init.rb
+- lib/periscope.rb
+- lib/periscope/adapters/abstract.rb
+- lib/periscope/adapters/active_record.rb
+- lib/periscope/permission_set.rb
+- lib/periscope/sanitizer.rb
+- lib/periscope/version.rb
+- periscope.gemspec
+- spec/periscope/adapters/active_record_spec.rb
+- spec/periscope/black_list_spec.rb
+- spec/periscope/version_spec.rb
+- spec/periscope/white_list_spec.rb
+- spec/spec_helper.rb
+- spec/support/abstract_examples.rb
+- spec/support/connections/active_record.rb
+- spec/support/permission_set_examples.rb
+- spec/support/sanitizer_examples.rb
+has_rdoc: true
+homepage: https://github.com/laserlemon/periscope
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: periscope
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Bring your models' scopes up above the surface.
+test_files: 
+- spec/periscope/adapters/active_record_spec.rb
+- spec/periscope/black_list_spec.rb
+- spec/periscope/version_spec.rb
+- spec/periscope/white_list_spec.rb
+- spec/spec_helper.rb
+- spec/support/abstract_examples.rb
+- spec/support/connections/active_record.rb
+- spec/support/permission_set_examples.rb
+- spec/support/sanitizer_examples.rb