three 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c4018a469715b0050959db01c36db56f214d9ccd
-  data.tar.gz: bd36ca9b6b88aad4869562354fae9d518e88c194
+  metadata.gz: 009a9b99cbdffb05a9e283827b05e3fe0e1eb082
+  data.tar.gz: 4e4faa7324a05ef27b3ebba6301ca763f9821dd1
 SHA512:
-  metadata.gz: e4deed1807609d3bac89dfc02501d5995cc116d66699d763a79e4c1a6674cd397ec9351c42f34c1629981a9b70e34194d21395d9a960443d2db7ff8e2ab3d7f2
-  data.tar.gz: 4a35b37082a40d2e5209f03875287acd110297cdc4da31dcf256bc138676de5148e0895ca84960b70e129b59c07415df07da59cf961b2e350e6a9cedcdc2f1a6
+  metadata.gz: 10c756626332c5b7805ecb2edac547b1723d730a364e067d02a97bda858f981617f3e0071bc987e06b189a477c3a5f365106a2b859dff24b535ffb30eb38db1f
+  data.tar.gz: 818711ac6b94bd8b2c7cfdbfe6cec906ee75128eca5847bba58c772f8068e89dc668760ffae78cf3ea024a49275ea6dd96224c8e72d7b7268039e63f7397ea46

data/.gitignore

@@ -1,2 +1,2 @@
 .rvmrc
-.Gemfile.lock
+Gemfile.lock

data/README.markdown

@@ -168,3 +168,21 @@ evaluator.rescue_errors = false
 evaluator.allowed? nil, :watch_out # POW an error was raised
 
 ```
+
+### Tracing
+
+Ok, so if your security rights are broken out into many different classes, it might be helpful to which one is allowing or preventing permissions.
+
+If you'd like to take a peek behind the curtain, try the following:
+
+```ruby
+Three.when_tracing do |what, details|
+  # "what" will be :allowed/:prevented
+  #   details is a hash with the following:
+  #   subject     # the subject of the rules check
+  #   target      # the target, if one was provided
+  #   permissions # the permissions either allowed or prevented
+  #   rule        # the rule making the check
+  puts [what, details].inspect
+end
+```

data/changelog.txt

@@ -0,0 +1,5 @@
+v 1.1.0
+  - Added ability to "prevent" rules. Works just like "allowed", but allows a rule to block out a permission.
+
+v 1.2.0
+  - Added tracing.  This allows the user to provide a method to trace what rules are providing which permissions.

data/lib/three.rb

@@ -6,4 +6,12 @@ module Three
     Three::Evaluator.new(rules)
   end
 
+  def self.trace what, details
+    @trace_method.call(what, details) if @trace_method
+  end
+
+  def self.when_tracing &block
+    @trace_method = block
+  end
+
 end

data/lib/three/evaluator.rb

@@ -58,15 +58,17 @@ module Three
     end
 
     def execute_rule rule, method, subject, target
-      if rescue_errors
-        begin
-          rule.send(method, subject, target)
-        rescue
-          []
-        end
-      else
-        rule.send(method, subject, target)
-      end
+      permissions = if rescue_errors
+                      begin
+                        rule.send(method, subject, target)
+                      rescue
+                        []
+                      end
+                    else
+                      rule.send(method, subject, target)
+                    end
+      Three.trace method, { subject: subject, target: target, permissions: permissions, rule: rule }
+      permissions
     end
 
     def flatten_permissions permissions

data/lib/three/version.rb

@@ -1,3 +1,3 @@
 module Three
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/spec/three/evaluator_spec.rb

@@ -86,4 +86,49 @@ describe Three::Evaluator do
 
   end
 
+  describe "noting important things" do
+
+    let(:the_subject) { Object.new }
+    let(:the_target)  { Object.new }
+    let(:permission)  { SecureRandom.uuid.to_sym }
+
+    let(:permission_to_prevent) { SecureRandom.uuid.to_sym }
+
+    let(:rule) do
+      Object.new.tap do |r|
+        r.stubs(:allowed).returns [permission]
+        r.stubs(:prevented).returns [permission_to_prevent]
+      end
+    end
+
+    let(:evaluator) { Three.evaluator_for rule }
+
+    before { Three.stubs :trace }
+
+    it "should trace the allowed permission build-up" do
+      Three.expects(:trace).with do |what, stuff|
+        what == :allowed &&
+          stuff[:rule].object_id == rule.object_id &&
+          stuff[:permissions].count == 1 && stuff[:permissions][0] == permission &&
+          stuff[:subject].object_id == the_subject.object_id &&
+          stuff[:target].object_id == the_target.object_id
+      end
+
+      evaluator.allowed?(the_subject, permission, the_target)
+    end
+
+    it "should trace the prevented permission build-up" do
+      Three.expects(:trace).with do |what, stuff|
+        what == :prevented &&
+          stuff[:rule].object_id == rule.object_id &&
+          stuff[:permissions].count == 1 && stuff[:permissions][0] == permission_to_prevent &&
+          stuff[:subject].object_id == the_subject.object_id &&
+          stuff[:target].object_id == the_target.object_id
+      end
+
+      evaluator.allowed?(the_subject, permission, the_target)
+    end
+
+  end
+
 end

data/spec/three_spec.rb

@@ -234,4 +234,25 @@ describe Three do
 
   end
 
+  describe "tracing" do
+
+    before { Three.instance_eval { @trace_method = nil } }
+    after  { Three.instance_eval { @trace_method = nil } }
+
+    it "should do nothing by default" do
+      Three.trace nil, nil
+    end
+
+    it "should allow me to register a new way to handle nothing" do
+      one, two, thing = Object.new, Object.new, Object.new
+      Three.when_tracing { |a, b| [a, b, thing] }
+
+      result = Three.trace one, two
+      result[0].must_be_same_as one
+      result[1].must_be_same_as two
+      result[2].must_be_same_as thing
+    end
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: three
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Darren Cauthon
@@ -52,6 +52,7 @@ files:
 - ORIGINAL_LICENSE
 - README.markdown
 - Rakefile
+- changelog.txt
 - lib/three.rb
 - lib/three/evaluator.rb
 - lib/three/version.rb
@@ -78,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: three