authorize 0.0.1

data/lib/authorize/bitmask.rb

@@ -0,0 +1,84 @@
+require 'set'
+
+class Authorize::Bitmask < Set
+  include Comparable
+
+  class << self
+    attr_reader :name_values
+    def new(fixnum_or_enum = Set.new)
+      enum = fixnum_or_enum.kind_of?(Fixnum) ? enum(fixnum_or_enum) : fixnum_or_enum
+      super(enum)
+    end
+
+    # Record bit names and define dynamic methods
+    def name_values=(h)
+      h.each do |n, v|
+        define_method("_#{n}") {include?(n) ? true : false}
+        define_method("_#{n}=") {|v| v ? self.add(n) : self.delete(n)}
+        alias_method "_#{n}?", "_#{n}"
+      end
+      @name_values = h
+    end
+
+    # The maximum value this bitmask can hold (in which every named bit is set).
+    def max
+      name_values.values.inject{|memo, v| memo | v}
+    end
+
+    # Enumerates all operations included in the given mask
+    def enum(mask)
+      raise RangeError, "Unnamed bits in mask (#{mask.to_s(2)})" unless (mask | max) == max
+      name_values.inject(Set[]){|s, (p, v)| s << p if (v == (mask & v)); s }
+    end
+  end
+
+  def add(el)
+    raise ArgumentError, "Unrecognized bit name (#{el})" unless self.class.name_values.keys.include?(el)
+    super
+  end
+  alias << add
+
+  # Calculate the integer value for the mask
+  def to_i
+    inject(0) {|memo, n| memo | self.class.name_values[n]}
+  end
+  alias to_int to_i
+
+  def valid?
+    inject(true) {|memo, n| memo && !!self.class.name_values[n]}
+  end
+
+  # Return an equivalent Bitmask using only fundamental names, never aggregate names
+  def fundamental
+    complete.to_canonical_array.inject(self.class.new) do |memo, n|
+      memo << n unless (memo.to_i & self.class.name_values[n]) == self.class.name_values[n]
+      memo
+    end
+  end
+
+  # Return an equivalent Bitmask using aggregated names to replace fundamental names where possible
+  def minimal
+    complete.to_canonical_array.reverse.inject(self.class.new) do |memo, n|
+      memo << n unless (memo.to_i & self.class.name_values[n]) == self.class.name_values[n]
+      memo
+    end
+  end
+
+  # Return an equivalent Bitmask using all possible names (fundamental and aggregate)
+  def complete
+    self.class.new(to_int)
+  end
+
+  # Comparability derives from integer representation
+  def <=>(other)
+    to_int <=> other.to_int
+  end
+
+  def to_s
+    to_canonical_array.join("|")
+  end
+
+  def to_canonical_array
+    sort_by{|name| self.class.name_values[name]}
+  end
+end

data/lib/authorize/exceptions.rb

@@ -0,0 +1,30 @@
+module Authorize #:nodoc:
+
+  # Base error class for Authorization module
+  class AuthorizationError < StandardError
+  end
+  
+  # Raised when the authorization expression is invalid (cannot be parsed)
+  class AuthorizationExpressionInvalid < AuthorizationError
+  end
+  
+  # Raised when we can't find the current user
+  class CannotObtainTokens < AuthorizationError
+  end
+  
+  # Raised when an authorization expression contains a model class that doesn't exist
+  class CannotObtainModelClass < AuthorizationError
+  end
+  
+  # Raised when an authorization expression contains a model reference that doesn't exist
+  class CannotObtainModelObject < AuthorizationError
+  end
+  
+  # Raised when the obtained trustee object doesn't implement #has_role?
+  class TrusteeDoesntImplementRoles < AuthorizationError
+  end
+  
+  # Raised when the obtained model doesn't implement #accepts_role?
+  class ModelDoesntImplementRoles < AuthorizationError
+  end
+end

data/lib/authorize/graph.rb

@@ -0,0 +1,4 @@
+module Authorize
+  module Graph
+  end
+end

data/lib/authorize/graph/directed_acyclic_graph.rb

@@ -0,0 +1,10 @@
+require 'authorize/redis'
+module Authorize
+  module Graph
+    class DirectedAcyclicGraph < DirectedGraph
+      def traverse(*args, &block)
+        DirectedAcyclicGraphTraverser.traverse(*args, &block)
+      end
+    end
+  end
+end

data/lib/authorize/graph/directed_acyclic_graph_reverse_traverser.rb

@@ -0,0 +1,27 @@
+require 'enumerator'
+
+module Authorize
+  module Graph
+    class DirectedAcyclicGraphReverseTraverser < DirectedAcyclicGraphTraverser
+      private
+      # Recursively traverse vertices breadth-wise, in reverse.
+      # Traversal is pruned if the block returns an untrue value.
+      def _traverse_breadth_first(start, depth, &block)
+        depth += 1
+        start.inbound_edges.select{|e| yield(e.from, e, depth)}.each do |e|
+          _traverse_breadth_first(e.from, depth, &block)
+        end
+      end
+
+      # Recursively traverse vertices depth-wise, in reverse.
+      # Traversal is pruned if the block returns an untrue value.
+      def _traverse_depth_first(start, depth, &block)
+        depth += 1
+        start.inbound_edges.each do |e|
+          _traverse_depth_first(e.from, depth, &block) if yield(e.from, e, depth)
+        end
+      end
+      alias _traverse _traverse_depth_first
+    end
+  end
+end

data/lib/authorize/graph/directed_acyclic_graph_traverser.rb

@@ -0,0 +1,30 @@
+require 'enumerator'
+
+module Authorize
+  module Graph
+    class DirectedAcyclicGraphTraverser < Traverser
+      def traverse(check = false, &block)
+        super(&block) unless check
+        t = self.class.new(self, :traverse)
+        if check
+          t.cycle_detector.pruner.cost_collector
+        else
+          t.pruner.cost_collector
+        end
+      end
+
+      # Detect cycles in the graph by recording the path taken (effectively an array of visited vertices indexed by
+      # depth).  When a cycle is detected (by finding the current vertex earlier in the path), raise an exception.
+      def cycle_detector(&block)
+        return self.class.new(self, :cycle_detector) unless block_given?
+        seen = ::Array.new
+        self.each do |vertex, edge, depth|
+          found = seen.index(vertex)
+          raise "Cycle detected at #{vertex} along #{edge} at depth #{found} and #{depth}" if found && (found < depth)
+          seen[depth] = vertex
+          yield vertex, edge, depth
+        end
+      end
+    end
+  end
+end

data/lib/authorize/graph/directed_graph.rb

@@ -0,0 +1,27 @@
+require 'authorize/redis'
+module Authorize
+  module Graph
+    # A directed graph implementation.  Every edge either connects "to" a vertex or "from" it.
+    # This implementation ensures that edges are not duplicated (which precludes multigraphs).  In
+    # cases where a duplicate edge is requested, the given properties are merged with the properties
+    # of the existing edge and the existing edge is returned.
+
+    # Notes:
+    #   Edges are created in the context of a graph in order to allow for graph-specific indexing
+    class DirectedGraph < Graph::Graph
+      # Find or create a directed edge joining the given vertices
+      def join(name, v0, v1, properties = {})
+        existing_edge = v0.edges.detect{|e| v1.eql?(e.to)}
+        existing_edge.try(:merge, properties)
+        existing_edge || edge(name, v0, v1, properties)
+      end
+
+      def disjoin(v0, v1)
+        return unless existing_edge = v0.edges.detect{|e| v1.eql?(e.to)}
+        existing_edge.tap do |edge|
+          edge.destroy
+        end
+      end
+    end
+  end
+end

data/lib/authorize/graph/edge.rb

@@ -0,0 +1,58 @@
+module Authorize
+  module Graph
+    # An edge connects two vertices.  The order in which the vertices are supplied is preserved and can be
+    # used to imply direction.
+    # TODO: persist the connected vertices in an array.
+    # TODO: a hyperedge can be modeled with a set of vertices instead of explicit left and right vertices.
+    class Edge < Redis::Hash
+      include Redis::ModelReference
+
+      def self.exists?(id)
+        super(subordinate_key(id, 'l_id'))
+      end
+
+      def self.load_all(namespace = name)
+        redis_glob = subordinate_key(namespace, '*', 'l_id')
+        re = Regexp.new(subordinate_key(namespace, ".+(?=#{NAMESPACE_SEPARATOR})"))
+        keys = db.keys(redis_glob)
+        keys = keys.map{|m| m.slice(re)}
+        keys.map{|id| load(id)}
+      end
+
+      def initialize(v0, v1, properties = {})
+        super()
+        set_reference(subordinate_key('l_id'), v0)
+        set_reference(subordinate_key('r_id'), v1)
+        v0.outbound_edges << self
+        v1.inbound_edges << self
+        merge(properties) if properties.any?
+      end
+
+      def from
+        load_reference(subordinate_key('l_id'), Vertex)
+      end
+      alias left from
+
+      def to
+        load_reference(subordinate_key('r_id'), Vertex)
+      end
+      alias right to
+
+      def vertices
+        [from, to]
+      end
+
+      def destroy
+        from && from.outbound_edges.delete(self)
+        to && to.inbound_edges.delete(self)
+        self.class.db.del(subordinate_key('l_id'))
+        self.class.db.del(subordinate_key('r_id'))
+        super
+      end
+
+      def valid?
+        from && to && super
+      end
+    end
+  end
+end

data/lib/authorize/graph/factory.rb

@@ -0,0 +1,39 @@
+require 'authorize/graph/vertex'
+require 'authorize/graph/edge'
+require 'authorize/redis/factory'
+
+module Authorize
+  module Graph
+    class Factory < Redis::Factory
+      def directed_graph(name, value = Set[], options = {}, &block)
+        options = {:edge_ids => ::Set[]}.merge(options)
+        obj = set(name, value) do
+          set('edge_ids', options[:edge_ids])
+          yield if block_given?
+        end
+        DirectedGraph.load(obj.id)
+      end
+
+      def vertex(name, value = {}, options = {}, &block)
+        options = {:edge_ids => ::Set[], :inbound_edge_ids => ::Set[]}.merge(options)
+        obj = hash(name, value) do
+          string('_', nil)
+          set('edge_ids', options[:edge_ids])
+          set('inbound_edge_ids', options[:inbound_edge_ids])
+          yield if block_given?
+        end
+        Vertex.load(obj.id)
+      end
+
+      def edge(name, value = {}, options = {}, &block)
+        options = {:l_id => nil, :r_id => nil}.merge(options)
+        obj = hash(name, value) do
+          string(:l_id, options[:l_id])
+          string(:r_id, options[:r_id])
+          yield if block_given?
+        end
+        Edge.load(obj.id)
+      end
+    end
+  end
+end

data/lib/authorize/graph/fixtures.rb

@@ -0,0 +1,33 @@
+require 'active_support/test_case'
+require 'active_record/fixtures'
+
+module Authorize
+  module Graph
+    module Fixtures
+      YAML.add_domain_type("hapgoods.com,2010", 'graph') do |type, value|
+        process(Role.graph, value)
+      end
+
+      def create_fixtures(db = Redis::Base.db, pathname = Pathname.new(ActiveSupport::TestCase.fixture_path).join('authorize', 'role_graph.yml'), flush = true)
+        db.flushdb if flush
+        YAML.load(ERB.new(pathname.read).result)
+      end
+      module_function :create_fixtures
+
+      def self.process(graph, nodes, parent = nil)
+        nodes.each do |node|
+          name = node.respond_to?(:keys) ? node.keys.first : node
+          children = node.respond_to?(:values) ? node.values.first : []
+          key = name_to_key(name)
+          vertex = graph.vertex(key)
+          graph.edge(nil, parent, vertex) if parent
+          process(graph, children, vertex) unless children.empty?
+        end
+      end
+
+      def self.name_to_key(name)
+        ::Fixtures.identify(name).to_s
+      end
+    end
+  end
+end

data/lib/authorize/graph/graph.rb

@@ -0,0 +1,55 @@
+require 'authorize/redis'
+
+module Authorize
+  module Graph
+    # A binary property graph.  Vertices and Edges have an arbitrary set of named properties.
+    # Reference: http://www.nist.gov/dads/HTML/graph.html
+    class Graph < Redis::Set
+      def self.exists?(id)
+        db.keys(subordinate_key(id, '*')).any?
+      end
+
+      attr_writer :edge_namespace, :vertex_namespace
+
+      def edge_namespace
+        @edge_namespace ||= subordinate_key('_edges')
+      end
+
+      def vertex_namespace
+        @vertex_namespace ||= subordinate_key('_vertices')
+      end
+
+      def edges
+        Edge.load_all(edge_namespace)
+      end
+
+      def vertices
+        Vertex.load_all(vertex_namespace)
+      end
+
+      # Create an vertex on this graph with the given name and additional properties.
+      def vertex(name, *args)
+        name ||= self.class.next_counter(vertex_namespace)
+        key = self.class.subordinate_key(vertex_namespace, name)
+        Vertex.new(key, *args)
+      end
+
+      # Create an edge on this graph with the given name and additional properties.
+      def edge(name, *args)
+        name ||= self.class.next_counter(edge_namespace)
+        key = self.class.subordinate_key(edge_namespace, name)
+        Edge.new(key, *args)
+      end
+
+      # Load the existing vertex in this graph with the given name.
+      def vertex_by_name(name)
+        key = self.class.subordinate_key(vertex_namespace, name)
+        Vertex.load(key)
+      end
+
+      def traverse(start = Vertex.load(sort_by{rand}.first))
+        Traverser.traverse(start)
+      end
+    end
+  end
+end

data/lib/authorize/graph/traverser.rb

@@ -0,0 +1,89 @@
+require 'enumerator'
+
+module Authorize
+  module Graph
+    # Traverse the graph by enumerating the encountered vertices.
+    class Traverser < Enumerable::Enumerator
+      # Traverse the graph starting at the given vertex.  A "bootstrap" enumerator is created from the starting
+      # vertex.  The bootstrap enumerator is then passed through a recursive expander and finally, several filters.
+      # In ruby 1.9, bootstrapping could be simplified with an anonymous enumerator (Enumerator.new {})
+      def self.traverse(start, *args, &block)
+        self.new(start, :tap).traverse(*args).visit(&block)
+      end
+
+      # Prune the graph by accumulating a set of visited nodes.  When a vertex has already been visited, interrupt the
+      # visit and signal the yielder.
+      def pruner(&block)
+        return self.class.new(self, :pruner) unless block_given?
+        seen = ::Set.new
+        self.each do |vertex, edge, depth|
+          next false if seen.include?(vertex)
+          seen << vertex
+          yield vertex, edge, depth
+          true # Don't let client block return value influence traversal
+        end
+      end
+
+      # Output the values yielded by the yielder as well as the return value of the supplied block.
+      def debugger(&block)
+        return self.class.new(self, :debugger) unless block_given?
+        count = 0 # A transit counter that
+        self.each do |*args|
+          count += 1
+          block.call(*args).tap do |result|
+            print "#{count}\t#{result}\t" + args.join("\t") + "\n"
+          end
+        end
+      end
+
+      # Return the accumulated cost of traversing the graph.  The default accumulator is a simple transit counter.
+      def cost_collector(cost = 0, f = lambda{|e| 1}, &block)
+        return self.class.new(self, :cost_collector) unless block_given?
+        inject(cost) do |total, (vertex, edge, depth)|
+          yield vertex, edge, depth
+          total + f.call(edge)
+        end
+      end
+
+      # Invoke callback on vertex.  Strip the edge to be more conventional.
+      # This is typically the last filter in the traverse chain.
+      def visit(&block)
+        return self.class.new(self, :visit) unless block_given?
+        self.each do |vertex, edge, depth|
+          vertex.visit(edge, &block)
+        end
+      end
+
+      # Visit the yielded start vertex and traverse to its adjacencies.
+      # This operation effectively "expands" the enumerator.
+      def traverse(&block)
+        return self.class.new(self, :traverse).pruner.cost_collector unless block_given?
+        each do |vertex, edge|
+          depth = 0
+          yield vertex, edge, depth
+          _traverse(vertex, depth, &block)
+        end
+      end
+
+      private
+      # Recursively traverse vertices breadth-wise
+      # Traversal is pruned if the block returns an untrue value.
+      def _traverse_breadth_first(start, depth, &block)
+        depth += 1
+        start.outbound_edges.select{|e| yield(e.to, e, depth)}.each do |e|
+          _traverse_breadth_first(e.to, depth, &block)
+        end
+      end
+
+      # Recursively traverse vertices depth-wise
+      # Traversal is pruned if the block returns an untrue value.
+      def _traverse_depth_first(start, depth, &block)
+        depth += 1
+        start.outbound_edges.each do |e|
+          _traverse_depth_first(e.to, depth, &block) if yield(e.to, e, depth)
+        end
+      end
+      alias _traverse _traverse_depth_first
+    end
+  end
+end