familia 2.0.0.pre15 → 2.0.0.pre17

data/examples/permissions.rb

@@ -1,240 +0,0 @@
-# examples/bit_encoding_integration.rb
-#
-# Production Integration Example: Document Management System with Fine-Grained Permissions
-#
-# This example demonstrates how to use Familia's bit encoding permission system
-# in a real-world document management scenario with sophisticated access control.
-
-require_relative '../lib/familia'
-require_relative '../lib/familia/features/relationships/score_encoding'
-require_relative '../lib/familia/features/relationships/permission_management'
-
-# Document Management System Classes
-class User < Familia::Horreum
-  logical_database 14
-
-  identifier_field :user_id
-  field :user_id
-  field :email
-  field :name
-  field :role # admin, editor, viewer, guest
-  field :created_at
-
-  sorted_set :documents # Documents this user can access
-  sorted_set :recent_activity # Recent document access
-end
-
-class Document < Familia::Horreum
-  include Familia::Features::Relationships::PermissionManagement
-
-  logical_database 14
-
-  # Enable fine-grained permission tracking
-  permission_tracking :user_permissions
-
-  identifier_field :doc_id
-  field :doc_id
-  field :title
-  field :owner_id
-  field :content
-  field :created_at
-  field :updated_at
-  field :document_type # public, private, confidential
-
-  sorted_set :collaborators # Users with access to this document
-  list :audit_log # Track permission changes and access
-
-  # Add document to user's collection with specific permissions
-  def share_with_user(user, *permissions)
-    permissions = [:read] if permissions.empty?
-
-    # Create time-based score with permissions encoded
-    timestamp = updated_at || Time.now
-    score = Familia::Features::Relationships::ScoreEncoding.encode_score(timestamp, permissions)
-
-    # Add to user's document list
-    user.documents.add(score, doc_id)
-
-    # Add user to document's collaborator list
-    collaborators.add(score, user.user_id)
-
-    # Grant permissions via permission management
-    grant(user, *permissions)
-
-    # Log the permission grant
-    log_entry = "#{Time.now.iso8601}: Granted #{permissions.join(', ')} to #{user.email}"
-    audit_log.push(log_entry)
-  end
-
-  # Remove user access
-  def revoke_access(user)
-    user.documents.zrem(doc_id)
-    collaborators.zrem(user.user_id)
-    revoke(user, :read, :write, :edit, :delete, :configure, :transfer, :admin)
-
-    log_entry = "#{Time.now.iso8601}: Revoked all access from #{user.email}"
-    audit_log.push(log_entry)
-  end
-
-  # Get users with specific permission level or higher
-  def users_with_permission(*required_permissions)
-    all_permissions.select do |_user_id, user_perms|
-      required_permissions.all? { |perm| user_perms.include?(perm) }
-    end.keys
-  end
-
-  # Advanced: Get document access history for analytics
-  def access_analytics(days_back = 30)
-    start_time = Time.now - (days_back * 24 * 60 * 60)
-    end_time = Time.now
-
-    # Use score range to get recent access
-    range = Familia::Features::Relationships::ScoreEncoding.score_range(
-      start_time,
-      end_time,
-      min_permissions: [:read]
-    )
-
-    # Get collaborators active in time range
-    active_users = collaborators.rangebyscore(*range)
-
-    {
-      active_users: active_users,
-      total_collaborators: collaborators.size,
-      permission_breakdown: all_permissions,
-      audit_entries: audit_log.range(0, 50),
-    }
-  end
-end
-
-# Document Management Service - Business Logic Layer
-class DocumentService
-  # Permission role definitions matching business needs
-  ROLE_PERMISSIONS = {
-    guest: [:read],
-    viewer: [:read],
-    commenter: %i[read append],
-    editor: %i[read write edit],
-    reviewer: %i[read write edit delete],
-    admin: %i[read write edit delete configure transfer admin],
-  }.freeze
-
-  def self.create_document(owner, title, content, doc_type = 'private')
-    doc = Document.new(
-      doc_id: "doc_#{Time.now.to_i}_#{rand(1000)}",
-      title: title,
-      content: content,
-      owner_id: owner.user_id,
-      document_type: doc_type,
-      created_at: Time.now,
-      updated_at: Time.now
-    )
-
-    # Owner gets full admin access
-    doc.share_with_user(owner, *ROLE_PERMISSIONS[:admin])
-    doc
-  end
-
-  def self.share_document(document, user, role)
-    permissions = ROLE_PERMISSIONS[role] || ROLE_PERMISSIONS[:viewer]
-    document.share_with_user(user, *permissions)
-  end
-
-  def self.can_user_perform?(user, document, action)
-    case action
-    when :view, :read
-      document.can?(user, :read)
-    when :comment, :append
-      document.can?(user, :read, :append)
-    when :edit, :modify
-      document.can?(user, :read, :write, :edit)
-    when :delete, :remove
-      document.can?(user, :delete)
-    when :share, :configure
-      document.can?(user, :configure)
-    when :transfer_ownership
-      document.can?(user, :admin)
-    else
-      false
-    end
-  end
-
-  def self.bulk_permission_update(documents, users, role)
-    permissions = ROLE_PERMISSIONS[role]
-
-    documents.each do |doc|
-      users.each do |user|
-        doc.revoke_access(user) # Clear existing
-        doc.share_with_user(user, *permissions) if permissions
-      end
-    end
-  end
-end
-
-# Example Usage and Demonstration
-if __FILE__ == $0
-  puts '🚀 Familia Bit Encoding Integration Example'
-  puts '=' * 50
-
-  # Create users
-  alice = User.new(user_id: 'alice', email: 'alice@company.com', name: 'Alice Smith', role: 'admin')
-  bob = User.new(user_id: 'bob', email: 'bob@company.com', name: 'Bob Jones', role: 'editor')
-  charlie = User.new(user_id: 'charlie', email: 'charlie@company.com', name: 'Charlie Brown', role: 'viewer')
-
-  # Create documents
-  doc1 = DocumentService.create_document(alice, 'Q4 Financial Report', 'Confidential financial data...', 'confidential')
-  doc2 = DocumentService.create_document(alice, 'Team Meeting Notes', 'Weekly standup notes...', 'private')
-  doc3 = DocumentService.create_document(bob, 'Project Proposal', 'New feature proposal...', 'public')
-
-  # Share documents with different permission levels
-  puts "\n📄 Document Sharing:"
-  DocumentService.share_document(doc1, bob, :reviewer)     # Bob can review financial report
-  DocumentService.share_document(doc1, charlie, :viewer)   # Charlie can only view
-
-  DocumentService.share_document(doc2, bob, :editor)       # Bob can edit meeting notes
-  DocumentService.share_document(doc2, charlie, :commenter) # Charlie can comment
-
-  DocumentService.share_document(doc3, alice, :admin)      # Alice gets admin on Bob's doc
-  DocumentService.share_document(doc3, charlie, :editor)   # Charlie can edit proposal
-
-  # Test permission checks
-  puts "\n🔐 Permission Testing:"
-  puts "Can Bob edit financial report? #{DocumentService.can_user_perform?(bob, doc1, :edit)}"
-  puts "Can Bob delete financial report? #{DocumentService.can_user_perform?(bob, doc1, :delete)}"
-  puts "Can Charlie comment on meeting notes? #{DocumentService.can_user_perform?(charlie, doc2, :comment)}"
-  puts "Can Charlie edit project proposal? #{DocumentService.can_user_perform?(charlie, doc3, :edit)}"
-
-  # Advanced analytics
-  puts "\n📊 Document Analytics:"
-  analytics = doc1.access_analytics
-  puts "Financial Report - Active Users: #{analytics[:active_users].size}"
-  puts "Total Collaborators: #{analytics[:total_collaborators]}"
-  puts 'Permission Breakdown:'
-  analytics[:permission_breakdown].each do |user_id, perms|
-    puts "  #{user_id}: #{perms.join(', ')}"
-  end
-
-  # Demonstrate bit encoding efficiency
-  puts "\n⚡ Bit Encoding Efficiency:"
-  score = Familia::Features::Relationships::ScoreEncoding.encode_score(Time.now, %i[read write edit delete])
-  decoded = Familia::Features::Relationships::ScoreEncoding.decode_score(score)
-  puts "Encoded score: #{score}"
-  puts "Decoded permissions: #{decoded[:permission_list].join(', ')}"
-  puts "Permission bits: #{decoded[:permissions]} (#{decoded[:permissions].to_s(2).rjust(8, '0')})"
-
-  # Cleanup
-  puts "\n🧹 Cleanup:"
-  [alice, bob, charlie].each { |user| user.documents.clear }
-  [doc1, doc2, doc3].each do |doc|
-    doc.clear_all_permissions
-    doc.collaborators.clear
-  end
-
-  puts '✅ Integration example completed successfully!'
-  puts "\nThis demonstrates:"
-  puts '• Fine-grained permission management with 8-bit encoding'
-  puts '• Role-based access control with business logic'
-  puts '• Time-based analytics and audit trails'
-  puts '• Efficient Redis storage with sorted sets'
-  puts '• Production-ready error handling and validation'
-end

data/lib/familia/features/relationships/cascading.rb

@@ -1,437 +0,0 @@
-# lib/familia/features/relationships/cascading.rb
-
-module Familia
-  module Features
-    module Relationships
-      # Cascading module for handling cascade operations during object lifecycle
-      # Supports multi-presence scenarios where objects exist in multiple collections
-      module Cascading
-        # Cascade strategies
-        STRATEGIES = {
-          remove: :remove_from_collections,
-          ignore: :ignore_collections,
-          cascade: :cascade_destroy_dependents
-        }.freeze
-
-        # Class-level cascade configurations
-        def self.included(base)
-          base.extend ClassMethods
-          base.include InstanceMethods
-          super
-        end
-
-        module ClassMethods
-          # Get cascade strategies for all relationships
-          def cascade_strategies
-            strategies = {}
-
-            # Collect strategies from tracking relationships
-            if respond_to?(:tracking_relationships)
-              tracking_relationships.each do |config|
-                key = "#{config[:context_class_name]}.#{config[:collection_name]}"
-                strategies[key] = {
-                  type: :tracking,
-                  strategy: config[:on_destroy] || :remove,
-                  config: config
-                }
-              end
-            end
-
-            # Collect strategies from membership relationships
-            if respond_to?(:membership_relationships)
-              membership_relationships.each do |config|
-                key = "#{config[:owner_class_name]}.#{config[:collection_name]}"
-                strategies[key] = {
-                  type: :membership,
-                  strategy: config[:on_destroy] || :remove,
-                  config: config
-                }
-              end
-            end
-
-            # Collect strategies from indexing relationships
-            if respond_to?(:indexing_relationships)
-              indexing_relationships.each do |config|
-                key = if config[:context_class_name] == 'global'
-                        "global.#{config[:index_name]}"
-                      else
-                        "#{config[:context_class_name]}.#{config[:index_name]}"
-                      end
-                strategies[key] = {
-                  type: :indexing,
-                  strategy: :remove, # Indexes should always be cleaned up
-                  config: config
-                }
-              end
-            end
-
-            strategies
-          end
-        end
-
-        # Instance methods for cascade operations
-        module InstanceMethods
-          # Execute cascade operations during destroy
-          def execute_cascade_operations
-            strategies = self.class.cascade_strategies
-
-            # Group operations by strategy for efficient execution
-            remove_operations = []
-            cascade_operations = []
-
-            strategies.each_value do |strategy_info|
-              case strategy_info[:strategy]
-              when :remove
-                remove_operations << strategy_info
-              when :cascade
-                cascade_operations << strategy_info
-              when :ignore
-                # Do nothing
-              end
-            end
-
-            # Execute remove operations first (cleanup this object's presence)
-            execute_remove_operations(remove_operations) if remove_operations.any?
-
-            # Then execute cascade operations (may trigger other destroys)
-            execute_cascade_operations_recursive(cascade_operations) if cascade_operations.any?
-          end
-
-          # Remove this object from all collections without cascading
-          def remove_from_all_collections
-            strategies = self.class.cascade_strategies
-            remove_operations = strategies.values.reject { |s| s[:strategy] == :ignore }
-            execute_remove_operations(remove_operations)
-          end
-
-          # Check if destroying this object would trigger cascades
-          def cascade_impact
-            strategies = self.class.cascade_strategies
-            impact = {
-              removals: 0,
-              cascades: 0,
-              affected_collections: [],
-              cascade_targets: []
-            }
-
-            strategies.each do |key, strategy_info|
-              case strategy_info[:strategy]
-              when :remove
-                impact[:removals] += 1
-                impact[:affected_collections] << key
-              when :cascade
-                impact[:cascades] += 1
-                impact[:affected_collections] << key
-
-                # Estimate cascade targets (this is expensive, use carefully)
-                targets = estimate_cascade_targets(strategy_info)
-                impact[:cascade_targets].concat(targets)
-              end
-            end
-
-            impact
-          end
-
-          private
-
-          # Execute removal operations atomically
-          def execute_remove_operations(remove_operations)
-            return if remove_operations.empty?
-
-            dbclient.pipelined do |pipeline|
-              remove_operations.each do |operation|
-                case operation[:type]
-                when :tracking
-                  remove_from_tracking_collections(pipeline, operation[:config])
-                when :membership
-                  remove_from_membership_collections(pipeline, operation[:config])
-                when :indexing
-                  remove_from_indexing_collections(pipeline, operation[:config])
-                end
-              end
-            end
-          end
-
-          # Remove from tracking collections
-          def remove_from_tracking_collections(pipeline, config)
-            context_class_name = config[:context_class_name]
-            collection_name = config[:collection_name]
-
-            # Find all collections this object is tracked in
-            pattern = "#{context_class_name.downcase}:*:#{collection_name}"
-
-            dbclient.scan_each(match: pattern) do |key|
-              pipeline.zrem(key, identifier)
-            end
-          end
-
-          # Remove from membership collections
-          def remove_from_membership_collections(pipeline, config)
-            owner_class_name = config[:owner_class_name]
-            collection_name = config[:collection_name]
-            type = config[:type]
-
-            # Find all collections this object is a member of
-            pattern = "#{owner_class_name.downcase}:*:#{collection_name}"
-
-            dbclient.scan_each(match: pattern) do |key|
-              case type
-              when :sorted_set
-                pipeline.zrem(key, identifier)
-              when :set
-                pipeline.srem(key, identifier)
-              when :list
-                pipeline.lrem(key, 0, identifier)
-              end
-            end
-          end
-
-          # Remove from indexing collections
-          def remove_from_indexing_collections(pipeline, config)
-            context_class_name = config[:context_class_name]
-            index_name = config[:index_name]
-            field = config[:field]
-
-            field_value = send(field) if respond_to?(field)
-            return unless field_value
-
-            if context_class_name == 'global'
-              index_key = "global:#{index_name}"
-              pipeline.hdel(index_key, field_value.to_s)
-            else
-              # Find all indexes this object appears in
-              pattern = "#{context_class_name.downcase}:*:#{index_name}"
-
-              dbclient.scan_each(match: pattern) do |key|
-                pipeline.hdel(key, field_value.to_s)
-              end
-            end
-          end
-
-          # Execute cascade operations that may trigger dependent destroys
-          def execute_cascade_operations_recursive(cascade_operations)
-            cascade_operations.each do |operation|
-              case operation[:type]
-              when :tracking
-                cascade_tracking_dependents(operation[:config])
-              when :membership
-                cascade_membership_dependents(operation[:config])
-              end
-            end
-          end
-
-          # Cascade destroy for tracking relationships
-          def cascade_tracking_dependents(config)
-            # This is a complex operation that depends on the specific business logic
-            # For now, we'll provide a framework that can be customized
-
-            context_class_name = config[:context_class_name]
-            collection_name = config[:collection_name]
-
-            # Find all contexts that track this object
-            pattern = "#{context_class_name.downcase}:*:#{collection_name}"
-
-            dbclient.scan_each(match: pattern) do |key|
-              # Check if this object is the only member
-              if dbclient.zcard(key) == 1 && dbclient.zscore(key, identifier)
-                context_id = key.split(':')[1]
-
-                # Optionally destroy the context if it becomes empty
-                # This is application-specific logic
-                trigger_cascade_callback(:tracking, context_class_name, context_id, collection_name)
-              end
-            end
-          end
-
-          # Cascade destroy for membership relationships
-          def cascade_membership_dependents(config)
-            # Similar to tracking, this depends on business logic
-
-            owner_class_name = config[:owner_class_name]
-            collection_name = config[:collection_name]
-            type = config[:type]
-
-            # Find all owners that contain this object
-            pattern = "#{owner_class_name.downcase}:*:#{collection_name}"
-
-            dbclient.scan_each(match: pattern) do |key|
-              # Check if this object exists in the collection
-              is_member = case type
-                          when :sorted_set
-                            dbclient.zscore(key, identifier) != nil
-                          when :set
-                            dbclient.sismember(key, identifier)
-                          when :list
-                            dbclient.lpos(key, identifier) != nil
-                          end
-
-              if is_member
-                owner_id = key.split(':')[1]
-                trigger_cascade_callback(:membership, owner_class_name, owner_id, collection_name)
-              end
-            end
-          end
-
-          # Trigger application-specific cascade callbacks
-          def trigger_cascade_callback(relationship_type, class_name, object_id, collection_name)
-            # This method can be overridden by applications to implement
-            # custom cascade logic
-
-            callback_method = "on_cascade_#{relationship_type}_#{collection_name}"
-
-            return unless respond_to?(callback_method, true)
-
-            send(callback_method, class_name, object_id)
-          end
-
-          # Estimate objects that would be affected by cascading (expensive operation)
-          def estimate_cascade_targets(strategy_info)
-            targets = []
-
-            case strategy_info[:type]
-            when :tracking
-              config = strategy_info[:config]
-              context_class_name = config[:context_class_name]
-              collection_name = config[:collection_name]
-
-              pattern = "#{context_class_name.downcase}:*:#{collection_name}"
-              dbclient.scan_each(match: pattern) do |key|
-                if dbclient.zscore(key, identifier)
-                  context_id = key.split(':')[1]
-                  targets << {
-                    type: :context,
-                    class: context_class_name,
-                    id: context_id,
-                    collection: collection_name
-                  }
-                end
-              end
-
-            when :membership
-              config = strategy_info[:config]
-              owner_class_name = config[:owner_class_name]
-              collection_name = config[:collection_name]
-              type = config[:type]
-
-              pattern = "#{owner_class_name.downcase}:*:#{collection_name}"
-              dbclient.scan_each(match: pattern) do |key|
-                is_member = case type
-                            when :sorted_set
-                              dbclient.zscore(key, identifier) != nil
-                            when :set
-                              dbclient.sismember(key, identifier)
-                            when :list
-                              dbclient.lpos(key, identifier) != nil
-                            end
-
-                if is_member
-                  owner_id = key.split(':')[1]
-                  targets << {
-                    type: :owner,
-                    class: owner_class_name,
-                    id: owner_id,
-                    collection: collection_name
-                  }
-                end
-              end
-            end
-
-            targets
-          end
-
-          # Dry run cascade operations (for testing/preview)
-          def cascade_dry_run
-            strategies = self.class.cascade_strategies
-
-            preview = {
-              removals: [],
-              cascades: [],
-              affected_keys: []
-            }
-
-            strategies.each do |key, strategy_info|
-              case strategy_info[:strategy]
-              when :remove
-                affected_keys = find_affected_keys(strategy_info)
-                preview[:removals] << {
-                  relationship: key,
-                  keys: affected_keys,
-                  count: affected_keys.length
-                }
-                preview[:affected_keys].concat(affected_keys)
-
-              when :cascade
-                cascade_targets = estimate_cascade_targets(strategy_info)
-                preview[:cascades] << {
-                  relationship: key,
-                  targets: cascade_targets,
-                  count: cascade_targets.length
-                }
-              end
-            end
-
-            preview[:affected_keys].uniq!
-            preview
-          end
-
-          # Find all Redis keys that would be affected by removing this object
-          def find_affected_keys(strategy_info)
-            affected_keys = []
-
-            case strategy_info[:type]
-            when :tracking
-              config = strategy_info[:config]
-              context_class_name = config[:context_class_name]
-              collection_name = config[:collection_name]
-              pattern = "#{context_class_name.downcase}:*:#{collection_name}"
-
-              dbclient.scan_each(match: pattern) do |key|
-                affected_keys << key if dbclient.zscore(key, identifier)
-              end
-
-            when :membership
-              config = strategy_info[:config]
-              owner_class_name = config[:owner_class_name]
-              collection_name = config[:collection_name]
-              type = config[:type]
-              pattern = "#{owner_class_name.downcase}:*:#{collection_name}"
-
-              dbclient.scan_each(match: pattern) do |key|
-                is_member = case type
-                            when :sorted_set
-                              dbclient.zscore(key, identifier) != nil
-                            when :set
-                              dbclient.sismember(key, identifier)
-                            when :list
-                              dbclient.lpos(key, identifier) != nil
-                            end
-                affected_keys << key if is_member
-              end
-
-            when :indexing
-              config = strategy_info[:config]
-              context_class_name = config[:context_class_name]
-              index_name = config[:index_name]
-              field = config[:field]
-
-              field_value = send(field) if respond_to?(field)
-              if field_value
-                if context_class_name == 'global'
-                  index_key = "global:#{index_name}"
-                  affected_keys << index_key if dbclient.hexists(index_key, field_value.to_s)
-                else
-                  pattern = "#{context_class_name.downcase}:*:#{index_name}"
-                  dbclient.scan_each(match: pattern) do |key|
-                    affected_keys << key if dbclient.hexists(key, field_value.to_s)
-                  end
-                end
-              end
-            end
-
-            affected_keys
-          end
-        end
-      end
-    end
-  end
-end