sinatra-bouncer 1.0.2 → 1.1

data/README.md

@@ -25,7 +25,7 @@ gem install sinatra-bouncer
 require 'sinatra'
 require 'sinatra/bouncer'
 
-# ... routes and other config
+   # ... routes and other config
 ```
 
 **Modular**
@@ -40,39 +40,73 @@ class MyApp < Sinatra::Base
 end
 ```
 
+After registration, Bouncer will reject any request that either:
+* has no rule associated with it, or
+* has no associated rule that returns `true`
+
 ###Step 2: Declare Bouncer Rules
+Call `rules` with a block that uses `can` and `can_sometimes` to declare which paths legal. 
+The rules block is run in the context of the request, which means you will have access to sinatra helpers, 
+the `request` object, and `params`.
 
-#### allow
-Bouncer is stored in Sinatra's `settings` object, under `settings.bouncer`.
+**Example**
+```ruby
+require 'sinatra'
+require 'sinatra/bouncer'
 
-By default, Bouncer will reject any request that either:
-* has no rule associated with it, or
-* has no associated rule that returns `true`
+rules do
+  can(:get, :all)
+  
+  # logged in users can edit their account
+  if(current_user)
+    can(:post, '/user_edits_account')
+  end
+end
+
+# ... route declarations as normal below
+```
 
-Declare rules by calling `bouncer.allow` and providing a rule block. Rule blocks **must return an explicit boolean** (ie. `true` or `false`) to avoid any accidental truthy values creating unwanted access. 
+#### can
+Any route declared with #can will be accepted this request without further challenge. 
 
 ```ruby
-bouncer.allow('/user_posts_blog') do
-    # calculate and return some boolean result
+rules do
+   can(:post, '/user_posts_blog')
 end
 ```
 
-####allow(:all)
-`allow(:all)` will match any path. 
+####can_sometimes
+`can_sometimes` is for occasions that you to check further, but want to defer that choice until the path is actually attempted.
+`can_sometimes` takes a block that will be run once the path is attempted. This block **must return an explicit boolean** 
+(ie. `true` or `false`) to avoid any accidental truthy values creating unwanted access.
 
+**Example**
 ```ruby
-allow(:all) do
-    # assuming a current_user helper to load the user object (like with warden)
-    current_user.admin?
+rules do
+    can_sometimes('/login') # Anyone can access this path
 end
 ```
 
-####always_allow
-`always_allow(...)` is shorthand for `allow(..) { true }`. 
+#### :any and :all special parameters
+Passing `can` or `can_sometimes`:
+ * `:any` to the first parameter will match any HTTP method. 
+ * `:all` to the second parameter will match any path. 
 
+**Examples**
 ```ruby
-  always_allow('/login') # Anyone can access this path
+# this allows get on all paths
+can(:get, :all)
+
+# this allows any method type to run on the /login path
+can(:any, '/login')
 ```
 
-###Customization
-The default bounce acion is to `halt 401`. Call `bounce_with` with a block to change that behaviour. 
+###Bounce Customization
+The default bounce action is to `halt 401`. Call `bounce_with` with a block that takes the sinatra application to change that behaviour. 
+
+**Example**
+```ruby
+bounce_with do |application|
+  application.redirect '/login'
+end
+```

data/lib/sinatra/bouncer.rb

@@ -24,62 +24,101 @@
 module Sinatra
   module Bouncer
     def self.registered(base_class)
-      base_class.set :bouncer, BasicBouncer.new
+      base_class.helpers HelperMethods
+
+      bouncer = BasicBouncer.new
+
+      # TODO: can we instead store it somehow on the actual temp request object?
+      base_class.set :bouncer, bouncer
 
       base_class.before do
-        unless settings.bouncer.allows? request.path
-          settings.bouncer.bounce(self)
+        bouncer.reset! # must clear all rules otherwise will leave doors open
+
+        self.instance_exec &bouncer.rules_initializer
+
+        http_method = request.request_method.downcase.to_sym
+        path = request.path.downcase
+
+        unless bouncer.can?(http_method, path)
+          bouncer.bounce(self)
         end
       end
     end
 
+    # Start ExtensionMethods
     def bounce_with(&block)
       bouncer.bounce_with = block
     end
 
+    def rules(&block)
+      bouncer.rules_initializer = block
+    end
+
+    # End ExtensionMethods
+
+    module HelperMethods
+      def can(*args)
+        settings.bouncer.can(*args)
+      end
+
+      def can_sometimes(*args, &block)
+        settings.bouncer.can_sometimes(*args, &block)
+      end
+    end
+
+    # Data class
     class BasicBouncer
       attr_accessor :bounce_with
+      attr_accessor :rules_initializer
 
       def initialize
-        @rules = Hash.new do |rules_hash, key|
-          rules_hash[key] = []
+        @rules = Hash.new do |method_to_paths, method|
+          method_to_paths[method] = Hash.new do |path_to_rules, path|
+            path_to_rules[path] = []
+          end
         end
+
+        @rules_initializer = Proc.new {}
+      end
+
+      def reset!
+        @rules.clear
       end
 
-      def always_allow(paths)
-        self.allow(paths) do
+      def can(method, *paths)
+        if block_given?
+          raise BouncerError.new('You cannot provide a block to #can. If you wish to conditionally allow, use #can_sometimes instead.')
+        end
+
+        can_sometimes(method, *paths) do
           true
         end
       end
 
-      def allow(paths, &block)
-        unless block
-          raise Sinatra::Bouncer::BouncerError.new('You must provide a block to #allow. If you wish to always allow, either return true or use #always_allow instead')
+      def can_sometimes(method, *paths, &block)
+        unless block_given?
+          raise BouncerError.new('You must provide a block to #can_sometimes. If you wish to always allow, use #can instead.')
         end
 
-        paths = [paths] unless paths.is_a? Array
-
         paths.each do |path|
-          @rules[path] << block
+          @rules[method][path] << block
         end
       end
 
-      def allows?(path)
-        rules = @rules[:all] + @rules[path]
-
-        # rules = @rules[path]
+      def can?(method, path)
+        rules = @rules[:any_method][path] + @rules[method][:all] + @rules[method][path] #@rules[:all] + @rules[method]
 
         rules.any? do |rule_block|
-          ruling = rule_block.call
+          ruling = rule_block.call #(app)
 
-          if ruling == true || ruling == false
-            ruling
-          else
+          if ruling != true && ruling != false
             source = rule_block.source_location.join(':')
             raise BouncerError.new("Rule block at does not return explicit true/false.\n\n"+
                                        "Rules must return explicit true or false to prevent accidental truthy values.\n\n"+
                                        "Source: #{source}\n")
           end
+
+          ruling
         end
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-bouncer
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: '1.1'
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-24 00:00:00.000000000 Z
+date: 2015-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra