authorize 0.0.1

data/lib/authorize/graph/undirected_graph.rb

@@ -0,0 +1,14 @@
+require 'authorize/redis'
+
+module Authorize
+  module Graph
+    class UndirectedGraph < Graph
+      # Join two vertices symmetrically so that they become adjacent.  Graphs built uniquely with
+      # this method will be undirected.
+      def join(id, v0, v1, *args)
+        edge_id = id || subordinate_key("_edges", true)
+        !!(edge(edge_id + "-01", v0, v1, *args) && edge(edge_id + "-10", v1, v0, *args))
+      end
+    end
+  end
+end

data/lib/authorize/graph/vertex.rb

@@ -0,0 +1,53 @@
+module Authorize
+  module Graph
+    class Vertex < Redis::Hash
+      def self.exists?(id)
+        super(subordinate_key(id, '_'))
+      end
+
+      def self.load_all(namespace = name)
+        redis_glob = subordinate_key(namespace, '*', '_')
+        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(properties = {})
+        super()
+        # Because a degenerate vertex can have neither properties nor edges, we must store a marker to indicate existence
+        self.class.db.set(subordinate_key('_'), nil)
+        merge(properties) if properties.any?
+      end
+
+      def destroy
+        outbound_edges.each{|e| e.destroy}
+        outbound_edges.destroy
+        inbound_edges.each{|e| e.destroy}
+        inbound_edges.destroy
+        self.class.db.del(subordinate_key('_'))
+        super
+      end
+
+      def adjacencies
+        outbound_edges.map(&:to)
+      end
+      alias neighbors adjacencies
+
+      def outbound_edges
+        @edges || Redis::ModelSet.new(subordinate_key('edge_ids'), Edge)
+      end
+      alias edges outbound_edges
+
+      # This index is required for efficient backlinking, such as when deleting a vertex.
+      def inbound_edges
+        @inbound_edges || Redis::ModelSet.new(subordinate_key('inbound_edge_ids'), Edge)
+      end
+
+      # Visit this vertex via the given edge
+      def visit(edge, &block)
+        yield self
+      end
+    end
+  end
+end

data/lib/authorize/permission.rb

@@ -0,0 +1,97 @@
+require 'authorize/bitmask'
+
+class Authorize::Permission < ActiveRecord::Base
+  class Mask < Authorize::Bitmask;end
+
+  set_table_name 'authorize_permissions'
+  # This is of questionable value given the specific implementation of mask attribute methods.  It also requires
+  # table inspection, so we skip it if the table does not yet exist.
+  cache_attributes('mask') if table_exists?
+
+  belongs_to :_resource, :polymorphic => true, :foreign_type => 'resource_type', :foreign_key => 'resource_id'
+  belongs_to :role, :class_name => "Authorize::Role"
+  validates_presence_of :role
+  validates_presence_of :resource
+
+  before_save :set_mandatory_list_mode
+
+  # Returns the explicit authorizations over a subject. The resource can be any one of the following
+  #   Object                global permissions are returned
+  #   <Resource Class>      global and class permissions are returned
+  #   <Resource Instance>   global, class and instance permissions are returned
+  # This exists to simplify finding and creating global and class permissions.  For resource instance
+  # permissions, use the standard Rails association (#permissions) created for authorizable resources.
+  named_scope :for, lambda {|resource|
+    resource_conditions = if (resource == Object) then
+       {:resource_id => nil, :resource_type => nil}
+    elsif resource.is_a?(Class) then
+       {:resource_id => nil, :resource_type => resource.to_s}
+    else
+       {:resource_id => resource.id, :resource_type => resource.class.to_s}
+    end
+    {:conditions => resource_conditions}
+  }
+  # Returns the effective permissions over a resource.
+  named_scope :over, lambda {|resource|
+    resource_conditions = if (resource == Object) then
+       {:resource_id => nil, :resource_type => nil}
+    elsif resource.is_a?(Class) then
+      c1 = sanitize_sql_hash_for_conditions(:resource_type => nil)
+      c2 = sanitize_sql_hash_for_conditions(:resource_type => resource.base_class.name, :resource_id => nil)
+      "#{c1} OR (#{c2})"
+    else
+      c1 = sanitize_sql_hash_for_conditions(:resource_type => nil)
+      c2 = sanitize_sql_hash_for_conditions(:resource_type => resource.class.base_class.name)
+      c3 = sanitize_sql_hash_for_conditions(:resource_id => resource.quoted_id)
+      c4 = sanitize_sql_hash_for_conditions(:resource_id => nil)
+      "#{c1} OR (#{c2} AND (#{c3} OR #{c4}))"
+    end
+    {:conditions => resource_conditions}
+  }
+  named_scope :to_do, lambda {|mask| {:conditions =>"mask & #{mask.to_i} = #{mask.to_i}"}}
+  named_scope :as, lambda {|roles| {:conditions => {:role_id => roles.map(&:id)}}}
+  named_scope :global, :conditions => {:resource_type => nil, :resource_id => nil}
+
+  # Determine if the aggregate mask includes the requested modes.
+  def self.permit?(requested_modes)
+    requested_modes.subset?(aggregate_mask)
+  end
+
+  # Find the aggregate permission mask for the current scope
+  # This calculation could be more effectively performed at the database using an aggregate function.  For
+  # MySQL, a bit_or function exists.  For SQLite3, it is necessary to code an extension.  For an example,
+  # see:  http://snippets.dzone.com/posts/show/3717
+  def self.aggregate_mask
+    Mask.new(all.inject(Set.new){|memo, p| memo | p.mask})
+  end
+
+  # Because the list mode is always assumed to be set for performance, we expose that assumption explicitly.
+  def set_mandatory_list_mode
+    self['mask'] |= Mask.name_values[:list]
+    @attributes_cache.delete('mask')
+  end
+
+  # Virtual attribute that expands the common belongs_to association with a three-level hierarchy
+  def resource
+    return Object unless resource_type
+    return resource_type.constantize unless resource_id
+    return _resource
+  end
+
+  def resource=(res)
+    return self._resource = res unless res.kind_of?(Class)
+    self.resource_id = nil
+    return self[:resource_type] = nil if res == Object
+    return self[:resource_type] = res.to_s
+  end
+
+  def mask(reload = false)
+    cached = @attributes_cache['mask'] # undocumented hash of cache nicely invalidated by write_attribute
+    return cached if cached && !reload
+    @attributes_cache['mask'] = Mask.new(read_attribute('mask')) # Ensure we always return a Mask instance
+  end
+
+  def to_s
+    "#{role} over #{resource} (#{mask})"
+  end
+end

data/lib/authorize/redis.rb

@@ -0,0 +1,2 @@
+require 'redis'
+require 'authorize/redis/base'

data/lib/authorize/redis/array.rb

@@ -0,0 +1,36 @@
+module Authorize
+  module Redis
+    class Array < Base
+      undef to_a # In older versions of Ruby, Object#to_a is invoked and #method_missing is never called.
+
+      def valid?
+        %w(none list).include?(db.type(id))
+      end
+
+      def [](index)
+        if index.respond_to?(:first)
+          db.lrange(id, index.first, index.last)
+        else
+          db.lindex(id, index)
+        end
+      end
+
+      def []=(index, v)
+        db.lset(id, index, v)
+      end
+
+      def push(v)
+        db.rpush(id, v)
+      end
+      alias << push
+
+      def pop
+        db.rpop(id)
+      end
+
+      def __getobj__
+        db.lrange(id, 0, -1)
+      end
+    end
+  end
+end

data/lib/authorize/redis/base.rb

@@ -0,0 +1,165 @@
+module Authorize
+  module Redis
+    # The key feature of this module is that it presents a coherent view of the database in memory.  For
+    # each database entry, at most one in-memory Ruby object will exist, and all state for the object will
+    # be atomically persisted to the database.  This behavior introduces the following constraints:
+    #   1.  The database is viewed through an identity map (http://en.wikipedia.org/wiki/Identity_map) to
+    #       ensure in-thread coherency.  Consequently, the record's key must be known prior to initialization,
+    #       allowing new objects to be instantiated only if no previously instantiated object with that key is
+    #       already in memory.
+    #   2.  In order to allow Redis::Base#initialize to set values (which are atomically persisted), the id must
+    #       be available at the _start_ of initialization.  This is accomplished by overriding Redis.new and
+    #       assigning the id immediately after allocation.
+    # TODO: YAML serialization (http://groups.google.com/group/comp.lang.ruby/browse_thread/thread/c855253c9d8f482e)
+    class Base
+      NAMESPACE_SEPARATOR = '::'
+      @base = true
+      class << self
+        attr_writer :logger
+        attr_writer :connection_specification
+
+        # Should this class establish a connection instead of relying on a superclass' connection?
+        def connection_base?
+          @base || @connection_specification
+        end
+
+        # Search up the inheritance chain for a manager unless a connection is specified here.
+        def connection_manager
+          @manager ||= (connection_base? ? Redis::ConnectionManager.new(@connection_specification) : superclass.connection_manager)
+        end
+
+        def connection
+          connection_manager.connection
+        end
+        alias db connection
+      end
+
+      def self.logger
+        @logger ||= (@base ? nil : superclass.logger)
+      end
+
+      def self.subordinate_key(*keys)
+        keys.compact.join(NAMESPACE_SEPARATOR)
+      end
+
+      def self.next_counter(key)
+        db.incr(key)
+      end
+
+      def self.generate_key
+        subordinate_key(name, next_counter(name))
+      end
+
+      def self.index
+        @index ||= ::Hash.new
+      end
+
+      def self.exists?(id)
+        db.exists(id)
+      end
+
+      # Load all model objects in the given namespace
+      def self.load_all(namespace = name)
+        redis_glob = subordinate_key(namespace, '*')
+        re = Regexp.new(subordinate_key(namespace, ".+(?=#{NAMESPACE_SEPARATOR})"))
+        db.keys(redis_glob).map{|m| m.slice(re)}.map{|id| load(id)}
+      end
+
+      def self.new(id = nil, *args, &block)
+        id ||= generate_key
+        index[id] = allocate.tap do |o|
+          o.instance_variable_set(:@id, id)
+          o.send(:initialize, *args, &block)
+        end
+      end
+
+      def self.load(id)
+        index[id] ||= allocate.tap do |o|
+          o.instance_variable_set(:@id, id)
+          o.send(:reload)
+        end
+      end
+      def self._load(id);load(id);end
+
+      attr_reader :id
+      alias to_s id
+
+      def logger
+        self.class.logger
+      end
+
+      def db
+        self.class.db
+      end
+
+      def eql?(other)
+        id.eql?(other.id) && other.is_a?(self.class)
+      end
+
+      def hash
+        id.hash
+      end
+
+      def ==(other)
+        id.eql?(other.id) && other.is_a?(self.class)
+      end
+
+      # Note that requesting a counter value "steals" from the class counter.
+      def subordinate_key(name, counter = false)
+        k = self.class.subordinate_key(id, name)
+        counter ? self.class.subordinate_key(k, self.class.next_counter(k)) : k
+      end
+
+      # This hook restores a re-instantiated object that has previously been initialized and then persisted.
+      # Non-idempotent operations should be used with great care.
+      def reload;end
+
+      def _dump(depth = nil)
+        id
+      end
+
+      # Emit this Redis object with a a magic type and simple scalar identifier.  The (poorly documented) "type id" format
+      # allows for a succinct one-line YAML expression for a Redis instance (no indented attributes hash required) which in
+      # turn simplifies automatic YAMLification of collections of Redis objects.  Arguably, it's more readable as well.
+      def to_yaml(opts = {})
+        YAML.quick_emit(self.id, opts) {|out| out.scalar("tag:hapgoods.com,2010-08-11:#{self.class.name}", id)}
+      end
+
+      def destroy
+        db.del(id) # This operation will remove all native Redis types (String, Hash, List, Set, etc.) in one shot.
+        self.class.index.delete(id)
+        freeze
+      end
+
+      def exists?
+        self.class.exists?(id)
+      end
+
+      def valid?
+        raise "Abstract class requires implementation"
+      end
+
+      # Methods that don't change the state of the object can safely delegate to a Ruby proxy object
+      def __getobj__
+        raise "Abstract class requires implementation"
+      end
+
+      def method_missing(m, *args, &block)
+        proxy = __getobj__ # Performance tweak
+        return super unless proxy.respond_to?(m) # If there is going to be an explosion, let superclass handle it.
+        proxy.freeze.__send__(m, *args, &block) # Ensure no state can be changed and send the method on its way.
+      end
+
+      def respond_to?(m, include_private = false)
+        return true if super
+        __getobj__.respond_to?(m, include_private)
+      end
+    end
+  end
+end
+
+YAML.add_domain_type("hapgoods.com,2010-08-11", "") do |type, val|
+  md = /tag:(.*),([^:]*):((?:\w+)(?:::\w+)*)/.match(type)
+  domain, version, klass = *md[1..3]
+  klass.constantize.load(val)
+end

data/lib/authorize/redis/connection_manager.rb

@@ -0,0 +1,88 @@
+require 'monitor'
+require 'set'
+
+module Authorize
+  module Redis
+    # This class arbitrates access to a Redis server ensuring that threads don't concurrently access the same connection
+    # http://yehudakatz.com/2010/08/14/threads-in-ruby-enough-already/
+    # http://blog.headius.com/2008/08/qa-what-thread-safe-rails-means.html
+    # Inspired by the ConnectionPool class in Rails 2.3
+    # Notes on thread-safety: Because instances of this class are expected to be shared
+    # across threads, access to all non-local variables and "constants" need to be synchronized.
+    # We assume that Hash read/assign operations are thread-safe.  We also require that the
+    # value returned by #current_connection_id not be shared across threads.
+    class ConnectionManager
+      class ConnectionError < RuntimeError; end
+
+      attr_reader :pool
+
+      # Creates a new ConnectionPool object. +specification+ is a ConnectionSpecification
+      # object which describes database connection parameters
+      def initialize(specification, options = {})
+        @options = {:size => 5}.merge(options)
+        @pool = ResourcePool.new(@options[:size], lambda {specification.connect!})
+        @connection_map = {} # Connections mapped to threads
+        @mutex = Monitor.new
+      end
+
+      # Retrieve the connection associated with the current thread, or checkout one from the pool as required.
+      # #connection can be called any number of times; the connection is held in a hash with a thread-specific key.
+      def acquire_connection
+        @connection_map[current_connection_id] ||= @pool.checkout(10)
+      end
+      alias connection acquire_connection
+
+      # Signal that the thread is finished with the current connection.
+      # #release_connection releases the connection-thread association
+      # and returns the connection to the pool.
+      def release_connection
+        c = @connection_map.delete(current_connection_id)
+        @pool.checkin(c) if c
+      end
+
+      # Checks out a connection from the pool, yields it to a block and checks it back into the pool when the block finishes.
+      def with_connection
+        c = @pool.checkout
+        yield c
+      ensure
+        @pool.checkin(c)
+      end
+
+      # Identifies connections in the death grip of defunct threads, removes them from the map and checks them back into the pool
+      # Because this method operates across connections for multiple threads (not just the current thread), concurrent execution
+      # needs to be synchronized to be thread-safe.
+      def recover_unused_connections
+        tids = Thread.list.select{|t| t.alive?}.map(&:object_id)
+        @mutex.synchronize do
+          cids = @connection_map.keys
+          (cids - tids).each do |sid|
+            c = @connection_map.delete(sid)
+            @pool.checkin(c)
+          end
+        end
+      end
+
+      # Expire stale connections
+      def expire_stale_connections!
+        @pool.expire do |connection, reserved_flag|
+          !connection.client.connected?
+        end
+      end
+
+      # Revert to a freshly initialized state
+      def reset!
+        @mutex.synchronize do
+          @pool.clear!
+          @connection_map.clear
+        end
+        self
+      end
+
+      private
+      # In order to guarantee thread-safety, this value must never be shared across threads.
+      def current_connection_id #:nodoc:
+        Thread.current.object_id
+      end
+    end
+  end
+end