hubbado-policy 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92b2d2ebfeca29045209e9ac790024cfe3be4d6646be7ace9f3678684808cad6
-  data.tar.gz: 88b9eb114f043c6b8f948fb780446566bf4a73771aabc96a9becfb670374a701
+  metadata.gz: 10ac3df17852150db0027d21e4fda49038083e6d825e41227a225864322df576
+  data.tar.gz: 0d303a7756e82512635a6a323939df1f794766cef2182cf405f07e72b96ad4d9
 SHA512:
-  metadata.gz: b28dc471aa7bcbee6db421e41cb4664423a6c58d31ab17e6deb2ae55d0a53fbf1b8c00e5a2ef96c34bd46d325fac68b5fb77fe0c88e59f0ca28eb2359affac28
-  data.tar.gz: 29670f1bb98582426e288fd290091d20ac8bf7ee9606a61f6de6b20a869794342c7646bc630c41bea8c0af1217033612c5455ea32b04aee05c8aa082546455e7
+  metadata.gz: 83232ddd7a934bf3a3381dccfe785be182ef6d03e2fd519bc006f1a17a07c0006b87c1d0e4dd58d442b5739350edf0e6f0ae9153a88676da3a5fcb74f8b5e94f
+  data.tar.gz: 8086d8d2ecbbe4df566560a0d36ebad2c1010b000d70c10bb703fc6c0b0d6c1ea5fd7a8017c70dd940951676090b2afa5ab10b80e02274e109e1152a5c4da231

data/CHANGELOG.md

@@ -5,14 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2025-05-27
+
+### Added
+
+- Policy control is improved:
+  - When using a policy control you could permit or deny with a method
+    ```ruby
+    mimic_policy = Control::Policies::ArticlePolicy.example
+    mimic_policy.permit(:view)
+    # or
+    mimic_policy.deny(:view)
+    mimic_policy.deny(:view, :a_reason) # with a reason
+    mimic_policy.deny(:view, data: :custom_data) # with data
+    mimic_policy.deny(:view, :a_reason, data: :custom_data) # or both
+    ```
+
 ## [1.1.1] - 2025-05-26
 
 ### Fixed
+
 - Railtie is corrected with an initializer to load I18n locales correctly.
 
 ## [1.1.0] - 2025-05-20
 
 ### Added
+
 - Control to mimic policies
 
 ## [1.0.1] - 2025-05-20
@@ -22,6 +40,7 @@ Bump because rubygems does not allow repushing the same version even if it is ya
 ## [1.0.0] - 2025-05-20
 
 ### Added
+
 - Initial release of the hubbado-policy gem
 - `Policy` class with DSL for defining authorization rules
 - `Result` class to represent policy outcomes
@@ -31,6 +50,7 @@ Bump because rubygems does not allow repushing the same version even if it is ya
 - Full compatibility with the eventide-project/dependency gem
 
 ### Documentation
+
 - Comprehensive README with usage examples
 - Detailed explanations of all major components
 - Rails integration guide

data/README.md

@@ -152,11 +152,24 @@ module Control
 end
 
 mimic_policy = Control::Policies::ArticlePolicy.example
-mimic_policy.view? # returns the value from the real policy
-
+mimic_policy.view? # returns false (denied by default)
 
+# Override specific policies
 mimic_policy = Control::Policies::ArticlePolicy.example(view: ArticlePolicy.denied)
 mimic_policy.view? # returns false
+
+# Control policy behavior with permit/deny methods
+mimic_policy = Control::Policies::ArticlePolicy.example
+mimic_policy.permit(:view)
+mimic_policy.view? # returns true
+
+mimic_policy.deny(:view)
+mimic_policy.view? # returns false
+
+# Deny with reason and data
+mimic_policy.deny(:view, :not_authorized)
+mimic_policy.deny(:view, data: { reason: "custom data" })
+mimic_policy.deny(:view, :not_authorized, data: { user_id: 123 })
 ```
 
 ## Result Objects
@@ -190,18 +203,55 @@ end
 - `message` - Returns the localized error message
 - `data` - Returns any additional context data
 
+### Error Handling
+
+Policies validate their inputs and will raise errors for invalid usage:
+
+```ruby
+# Will raise "User not provided" error
+ArticlePolicy.build(nil, article)
+
+# Control policies raise UnkownPolicy for invalid policy names
+mimic_policy = Control::Policies::ArticlePolicy.example
+mimic_policy.permit(:invalid_policy)  # raises UnkownPolicy
+```
+
+### Accessing Result Data
+
+When policies return additional context data, you can access it through the result:
+
+```ruby
+# In your policy
+define_policy :edit do
+  return denied(:quota_exceeded, data: { limit: 10, current: 12 }) if over_quota?
+  permitted
+end
+
+# Using the result
+result = policy.edit
+if result.denied?
+  puts result.message  # "You have exceeded your quota"
+  puts result.data[:limit]    # 10
+  puts result.data[:current]  # 12
+end
+```
+
 ## Scope Objects
 
 Scope objects filter collections based on what a user is authorized to access.
 
 ### Basic Usage
 
+Scope objects require two template methods to be implemented in subclasses:
+
 ```ruby
 class ArticleScope < Hubbado::Policy::Scope
+  # Required: Define the base collection to filter
   def self.default_scope
     Article.all
   end
   
+  # Required: Implement the filtering logic
   def resolve(record, scope, **options)
     return scope if record.admin?
     
@@ -213,6 +263,14 @@ end
 visible_articles = ArticleScope.call(current_user)
 ```
 
+**Required Methods:**
+- `default_scope` - Class method that returns the base collection to filter
+- `resolve(record, scope, **options)` - Instance method that applies filtering logic
+
+Both methods must be implemented or a `MethodMissing` error will be raised.
+
+**Important:** Like policies, use `Scope.call()` instead of manual instantiation to ensure the `configure` method is called if defined.
+
 ### Custom Scopes
 
 You can pass custom base scopes:

data/hubbado-policy.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "hubbado-policy"
-  s.version = "1.1.1"
+  s.version = "1.2.0"
   s.summary = "A lightweight, flexible policy framework for Ruby applications"
 
   s.authors = ["Hubbado Devs"]

data/lib/hubbado/policy/controls/policy.rb

@@ -2,6 +2,8 @@ module Hubbado
   module Policy
     module Controls
       class Policy
+        UnkownPolicy = Class.new(StandardError)
+
         def self.mimic(policy_class)
           policy_class.policies.each do |policy|
             send(:attr_writer, policy)
@@ -14,6 +16,22 @@ module Hubbado
               send(policy).permitted?
             end
           end
+
+          define_method :permit do |policy|
+            unless policy_class.instance_variable_get("@policies").include?(policy)
+              raise UnkownPolicy
+            end
+
+            send("#{policy}=", policy_class.permitted)
+          end
+
+          define_method :deny do |policy, reason = nil, data: nil|
+            unless policy_class.instance_variable_get("@policies").include?(policy)
+              raise UnkownPolicy
+            end
+
+            send("#{policy}=", policy_class.denied(reason, data: data))
+          end
         end
 
         def initialize(policies = {})

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-policy
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Hubbado Devs