granity 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 165420efec85cf4fcec2feb3fd44a51da6efd978bc552c2301ac5d4cc7b0f4ee
-  data.tar.gz: 5595acb02ddd28a9e0a6fde235d03c8a295262249c74c9246fc7fa901fbf51d7
+  metadata.gz: d187a969f4aa61ad031d5eff41882fba68796b1455f8ea11011663d51fea4960
+  data.tar.gz: b11f5bf0eb6fa7576d505f4f168a4b4bc4c7353f87b0d4120484347616228629
 SHA512:
-  metadata.gz: d38148344bdab1966672fedc51ae902810b1ff2d0e4f3af534798b6f9c42c441995520f97a5edefdd6bfe049974153e0c73a792b29eb94bb25fb6658c4e1886e
-  data.tar.gz: 2eaf91f2f46b48f32092e0651e91376da80efe5170e3de6132c4132a85365a5fb4cdf208332af15a923d017258ef69aaaec200102bc05dc672118a2823f31e14
+  metadata.gz: 1f2ee84f563fb463429658e3d55125db8cbe70bad1369d01d8c5f3514a929f2d2127fc58b4133691abc1d3bfabc9d5dff028e73c32a077ae0e944e6f96f22c0c
+  data.tar.gz: db09edf1bc7eb3df8d97240f6e030782cc5fe9f9b17f92c44935b11ef2a3a0864113674dfbf5f1f3702285bd3b4a14e8ee576fe1abcbd0aca57aba910ca2bec8

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright Yatish Mehta
+Copyright TODO: Write your name
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,28 +1,224 @@
 # Granity
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+Granity is a fine-grained authorization engine for Ruby on Rails applications. It provides a flexible DSL for defining authorization rules and efficient permission checking.
 
 ## Installation
-Add this line to your application's Gemfile:
+
+Add this gem to your application's Gemfile:
 
 ```ruby
-gem "granity"
+gem 'granity'
 ```
 
-And then execute:
+Then execute:
+
 ```bash
-$ bundle
+$ bundle install
 ```
 
-Or install it yourself as:
+Run the migrations:
+
 ```bash
-$ gem install granity
+$ rails granity:install:migrations
+$ rails db:migrate
+```
+
+## Configuration
+
+Create an initializer for Granity:
+
+```ruby
+# config/initializers/granity.rb
+Granity.configure do |config|
+  config.cache_provider = Rails.cache # Optional: Uses Rails.cache if provided
+  config.cache_ttl = 10.minutes
+  config.max_cache_size = 10_000
+  config.enable_tracing = !Rails.env.production?
+  config.max_traversal_depth = 10
+end
+```
+
+## Defining Authorization Schema
+
+Use the Granity DSL to define your authorization schema:
+
+```ruby
+# config/initializers/granity.rb
+Granity.define do
+  resource_type :user do
+    # User schema
+  end
+
+  resource_type :document do
+    relation :owner, type: :user
+    relation :viewer, type: :user
+    relation :team, type: :team
+
+    permission :view do
+      include_any do
+        include_relation :owner
+        include_relation :viewer
+        include_relation :admin from :team
+      end
+    end
+
+    permission :edit do
+      include_relation :owner
+    end
+  end
+
+  resource_type :team do
+    relation :member, type: :user
+    relation :admin, type: :user
+  end
+end
+```
+
+## Usage
+
+### Checking Permissions
+
+```ruby
+# Check if a user has permission on a resource
+if Granity.check_permission(
+  subject_type: 'user',
+  subject_id: current_user.id,
+  permission: 'view',
+  resource_type: 'document',
+  resource_id: document.id
+)
+  # User can view the document
+end
+```
+
+### Creating Relations
+
+```ruby
+# Grant a user owner access to a document
+Granity.create_relation(
+  object_type: 'document',
+  object_id: document.id,
+  relation: 'owner',
+  subject_type: 'user',
+  subject_id: user.id
+)
+```
+
+### Finding Subjects
+
+```ruby
+# Find all users who can view a document
+viewers = Granity.find_subjects(
+  resource_type: 'document',
+  resource_id: document.id,
+  permission: 'view'
+)
+```
+
+### Integration with Rails Controllers
+
+```ruby
+class ApplicationController < ActionController::Base
+  def authorize!(resource, permission)
+    unless Granity.check_permission(
+      subject_type: 'user',
+      subject_id: current_user.id,
+      permission: permission,
+      resource_type: resource.model_name.singular,
+      resource_id: resource.id
+    )
+      raise Unauthorized, "Not authorized to #{permission} this #{resource.model_name.human}"
+    end
+  end
+end
+
+class DocumentsController < ApplicationController
+  def show
+    @document = Document.find(params[:id])
+    authorize!(@document, :view)
+    # ...
+  end
+
+  def update
+    @document = Document.find(params[:id])
+    authorize!(@document, :edit)
+    # ...
+  end
+end
+```
+
+## DSL Reference
+
+### Resource Types
+
+Define the entities in your authorization model:
+
+```ruby
+resource_type :document do
+  # Resource definition
+end
 ```
 
-## Contributing
-Contribution directions go here.
+### Relations
+
+Define relationships between resources:
+
+```ruby
+relation :owner, type: :user
+relation :parent_folder, type: :folder
+```
+
+### Permissions
+
+Define access rules with Boolean logic:
+
+```ruby
+permission :view do
+  include_any do
+    include_relation :owner
+    include_relation :viewer
+    include_relation :editor
+  end
+end
+```
+
+### Boolean Logic
+
+Combine relations with `include_any` (OR) and `include_all` (AND):
+
+```ruby
+permission :publish do
+  include_all do
+    include_relation :editor
+
+    include_any do
+      include_relation :approved
+      include_relation :admin from :team
+    end
+  end
+end
+```
+
+### Permission Composition
+
+Reuse and compose permissions:
+
+```ruby
+permission :manage do
+  include_permission :view
+  include_permission :edit
+  include_relation :owner
+end
+```
+
+### Relation Traversal
+
+Follow paths through related resources:
+
+```ruby
+include_relation :member from :team
+```
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/models/granity/relation_tuple.rb

@@ -0,0 +1,12 @@
+module Granity
+  class RelationTuple < ActiveRecord::Base
+    self.table_name = "granity_relation_tuples"
+
+    validates :object_type, :object_id, :relation, :subject_type, :subject_id, presence: true
+
+    # Useful scopes for querying
+    scope :for_object, ->(type, id) { where(object_type: type, object_id: id) }
+    scope :for_subject, ->(type, id) { where(subject_type: type, subject_id: id) }
+    scope :with_relation, ->(relation) { where(relation: relation) }
+  end
+end

data/db/migrate/20250317000000_create_granity_relation_tuples.rb

@@ -0,0 +1,20 @@
+class CreateGranityRelationTuples < ActiveRecord::Migration[7.0]
+  def change
+    create_table :granity_relation_tuples do |t|
+      t.string :object_type, null: false
+      t.string :object_id, null: false
+      t.string :relation, null: false
+      t.string :subject_type, null: false
+      t.string :subject_id, null: false
+
+      t.timestamps
+    end
+
+    add_index :granity_relation_tuples, [:object_type, :object_id, :relation],
+      name: "index_granity_tuples_on_object"
+    add_index :granity_relation_tuples, [:subject_type, :subject_id],
+      name: "index_granity_tuples_on_subject"
+    add_index :granity_relation_tuples, [:object_type, :object_id, :relation, :subject_type, :subject_id],
+      unique: true, name: "index_granity_tuples_unique"
+  end
+end

data/lib/generators/granity/install/install_generator.rb

@@ -0,0 +1,16 @@
+module Granity
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration
+        timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        copy_file "create_granity_tables.rb", "db/migrate/#{timestamp}_create_granity_tables.rb"
+      end
+
+      def create_initializer
+        copy_file "initializer.rb", "config/initializers/granity.rb"
+      end
+    end
+  end
+end

data/lib/granity/authorization_engine.rb

@@ -0,0 +1,155 @@
+module Granity
+  class AuthorizationEngine
+    class << self
+      def check_permission(subject_type:, subject_id:, permission:, resource_type:, resource_id:)
+        cache_key = "granity:permission:#{subject_type}:#{subject_id}:#{permission}:#{resource_type}:#{resource_id}"
+
+        # Try fetching from cache first
+        cached_result = cache.read(cache_key)
+        if cached_result
+          trace("CACHE HIT: #{cache_key} -> #{cached_result}")
+          return cached_result
+        end
+
+        trace("CACHE MISS: #{cache_key}")
+
+        # Generate dependencies for this permission check
+        dependencies = DependencyAnalyzer.analyze_permission_check(
+          subject_type: subject_type,
+          subject_id: subject_id,
+          permission: permission,
+          resource_type: resource_type,
+          resource_id: resource_id
+        )
+
+        # Check the permission
+        result = PermissionEvaluator.evaluate(
+          subject_type: subject_type,
+          subject_id: subject_id,
+          permission: permission,
+          resource_type: resource_type,
+          resource_id: resource_id
+        )
+
+        # Store in cache with all dependency keys
+        cache.write(cache_key, result, dependencies: dependencies)
+        trace("CACHE WRITE: #{cache_key} -> #{result} with dependencies: #{dependencies}")
+
+        result
+      end
+
+      def find_subjects(resource_type:, resource_id:, permission:)
+        cache_key = "granity:subjects:#{permission}:#{resource_type}:#{resource_id}"
+
+        # Try fetching from cache first
+        cached_result = cache.read(cache_key)
+        if cached_result
+          trace("CACHE HIT: #{cache_key}")
+          return cached_result
+        end
+
+        trace("CACHE MISS: #{cache_key}")
+
+        # Generate dependencies for this subjects query
+        dependencies = DependencyAnalyzer.analyze_find_subjects(
+          resource_type: resource_type,
+          resource_id: resource_id,
+          permission: permission
+        )
+
+        # Get the subjects
+        subjects = PermissionEvaluator.find_subjects(
+          resource_type: resource_type,
+          resource_id: resource_id,
+          permission: permission
+        )
+
+        # Store in cache with all dependency keys
+        cache.write(cache_key, subjects, dependencies: dependencies)
+        trace("CACHE WRITE: #{cache_key} with dependencies: #{dependencies}")
+
+        subjects
+      end
+
+      def create_relation(object_type:, object_id:, relation:, subject_type:, subject_id:)
+        # Create the relation tuple in the database
+        tuple = Granity::RelationTuple.create!(
+          object_type: object_type,
+          object_id: object_id,
+          relation: relation,
+          subject_type: subject_type,
+          subject_id: subject_id
+        )
+
+        # Invalidate cache entries that depend on this relation
+        invalidate_cache_for_relation(object_type, object_id, relation)
+
+        tuple
+      rescue ActiveRecord::RecordNotUnique
+        # If the relation already exists, just return it
+        Granity::RelationTuple.find_by(
+          object_type: object_type,
+          object_id: object_id,
+          relation: relation,
+          subject_type: subject_type,
+          subject_id: subject_id
+        )
+      end
+
+      def delete_relation(object_type:, object_id:, relation:, subject_type:, subject_id:)
+        tuple = Granity::RelationTuple.find_by(
+          object_type: object_type,
+          object_id: object_id,
+          relation: relation,
+          subject_type: subject_type,
+          subject_id: subject_id
+        )
+
+        return false unless tuple
+
+        tuple.destroy
+
+        # Invalidate cache entries that depend on this relation
+        invalidate_cache_for_relation(object_type, object_id, relation)
+
+        true
+      end
+
+      def reset_cache
+        cache.clear
+      end
+
+      private
+
+      def cache
+        @cache ||= begin
+          config = Granity.configuration
+          config.cache_provider || Granity::InMemoryCache.new(
+            max_size: config.max_cache_size,
+            ttl: config.cache_ttl
+          )
+        end
+      end
+
+      def invalidate_cache_for_relation(object_type, object_id, relation)
+        # This is a simplified approach. In a real implementation, we would use
+        # a more sophisticated approach to track which cache keys depend on which
+        # relations, possibly using Redis sets or a similar mechanism.
+
+        # For now, we take a conservative approach and invalidate any cache entry
+        # that might depend on this relation being changed
+        dependency_key = "granity:relation:#{object_type}:#{object_id}:#{relation}"
+        cache.invalidate_dependencies([dependency_key])
+
+        trace("CACHE INVALIDATE for dependency: #{dependency_key}")
+      end
+
+      def trace(message)
+        return unless Granity.configuration.enable_tracing
+
+        # In a real implementation, this would use a proper logging system
+        puts "[Granity] #{message}"
+      end
+    end
+  end
+end

data/lib/granity/configuration.rb

@@ -0,0 +1,18 @@
+module Granity
+  # Configuration class to hold Granity settings
+  class Configuration
+    attr_accessor :cache_provider
+    attr_accessor :cache_ttl
+    attr_accessor :max_cache_size
+    attr_accessor :enable_tracing
+    attr_accessor :max_traversal_depth
+
+    def initialize
+      @cache_provider = nil
+      @cache_ttl = 10.minutes
+      @max_cache_size = 10_000
+      @enable_tracing = !defined?(Rails) || !Rails.env.production?
+      @max_traversal_depth = 10
+    end
+  end
+end

data/lib/granity/dependency_analyzer.rb

@@ -0,0 +1,127 @@
+module Granity
+  # Analyzes dependencies between relations and permissions for proper cache invalidation
+  class DependencyAnalyzer
+    class << self
+      # Analyze dependencies for a permission check
+      # Returns an array of dependencies for cache invalidation
+      def analyze_permission_check(subject_type:, subject_id:, permission:, resource_type:, resource_id:)
+        deps = []
+
+        # Basic direct dependencies
+        deps << "granity:subject:#{subject_type}:#{subject_id}"
+        deps << "granity:resource:#{resource_type}:#{resource_id}"
+
+        # Get schema dependencies for this permission
+        schema_dependencies = analyze_permission_schema(resource_type, permission)
+        deps.concat(schema_dependencies)
+
+        deps
+      end
+
+      # Analyze dependencies for finding subjects with a permission
+      def analyze_find_subjects(resource_type:, resource_id:, permission:)
+        deps = []
+
+        # Basic resource dependency
+        deps << "granity:resource:#{resource_type}:#{resource_id}"
+
+        # Get schema dependencies for this permission
+        schema_dependencies = analyze_permission_schema(resource_type, permission)
+        deps.concat(schema_dependencies)
+
+        deps
+      end
+
+      private
+
+      # Analyze schema dependencies for a permission
+      def analyze_permission_schema(resource_type, permission)
+        deps = []
+        schema = Granity::Schema.current
+
+        # Add dependency on the permission definition itself
+        deps << "granity:schema:#{resource_type}:permission:#{permission}"
+
+        # Get the resource type from schema
+        resource_type_def = schema.resource_types[resource_type.to_sym]
+        return deps unless resource_type_def
+
+        # Get the permission definition
+        permission_def = resource_type_def.permissions[permission.to_sym]
+        return deps unless permission_def
+
+        # Track visited permissions to prevent cycles
+        visited = Set.new(["#{resource_type}:#{permission}"])
+
+        # Add all relations that this permission depends on
+        relations = extract_relations_from_permission(permission_def, [], visited)
+        relations.each do |relation|
+          deps << "granity:relation:#{resource_type}:#{relation}"
+        end
+
+        deps
+      end
+
+      # Extract all relations used in a permission definition
+      def extract_relations_from_permission(rule_or_permission, relations = [], visited = Set.new)
+        # Handle different types of input
+        if rule_or_permission.is_a?(Granity::Permission)
+          # It's a Permission object with rules
+          rule_or_permission.rules.each do |rule|
+            extract_relations_from_rule(rule, relations, visited, rule_or_permission.resource_type)
+          end
+        else
+          # It's a rule object directly
+          extract_relations_from_rule(rule_or_permission, relations, visited, nil)
+        end
+
+        relations.uniq
+      end
+
+      # Process a single rule to extract relations
+      def extract_relations_from_rule(rule, relations = [], visited = Set.new, resource_type = nil)
+        if rule.is_a?(Granity::Rules::Relation)
+          # Direct relation - add to results
+          relations << rule.relation
+        elsif rule.is_a?(Granity::Rules::Any) || rule.is_a?(Granity::Rules::All)
+          # Container rule - process each subrule
+          rule.rules.each do |subrule|
+            extract_relations_from_rule(subrule, relations, visited, resource_type)
+          end
+        elsif rule.is_a?(Granity::Rules::Permission)
+          # Referenced permission - get from schema and process
+          # Skip if we've already visited this permission to prevent cycles
+          permission_key = "#{resource_type}:#{rule.permission}"
+          return relations if visited.include?(permission_key)
+
+          # Mark as visited to prevent cycles
+          visited.add(permission_key)
+
+          # Get referenced permission from schema (if possible)
+          schema = Granity::Schema.current
+
+          if resource_type && schema.resource_types[resource_type.to_sym]
+            # If we know the resource type, look for the permission there
+            resource_type_def = schema.resource_types[resource_type.to_sym]
+            if resource_type_def.permissions.has_key?(rule.permission)
+              referenced_permission = resource_type_def.permissions[rule.permission]
+              extract_relations_from_permission(referenced_permission, relations, visited)
+            end
+          else
+            # If resource type is unknown, look in all resource types
+            resource_types = schema.resource_types.values
+            resource_types.each do |rt|
+              if rt.permissions.has_key?(rule.permission)
+                referenced_permission = rt.permissions[rule.permission]
+                extract_relations_from_permission(referenced_permission, relations, visited)
+                break
+              end
+            end
+          end
+        end
+
+        relations
+      end
+    end
+  end
+end

data/lib/granity/engine.rb

@@ -1,5 +1,13 @@
 module Granity
   class Engine < ::Rails::Engine
     isolate_namespace Granity
+
+    initializer "granity.load_migrations" do |app|
+      unless app.root.to_s.match root.to_s
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
   end
 end