feat: Use attr for principal and resource attributes (#157)

Signed-off-by: Andrew Haines <[email protected]>
cerbos · Jun 7, 2024 · 23e976d · 23e976d
1 parent 3a17a58
commit 23e976d
Show file tree

Hide file tree

Showing 8 changed files with 97 additions and 35 deletions.
diff --git a/.rspec b/.rspec
@@ -1 +1,2 @@
 --require spec_helper
+--warnings
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,11 @@
 ## [Unreleased]
 
-No notable changes.
+### Changed
+
+- Use `attr` for principal and resource attributes ([#157](https://github.com/cerbos/cerbos-sdk-ruby/pull/157))
+
+  This makes the API consistent with policy expressions.
+  `attributes` is still supported for backwards compatibility, but is now deprecated.
 
 ## [0.8.0] - 2024-01-12
 

diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ decision = client.check_resource(
   resource: {
     kind: "document",
     id: "1",
-    attributes: {
+    attr: {
       owner: "[email protected]"
     }
   },

diff --git a/lib/cerbos.rb b/lib/cerbos.rb
@@ -10,6 +10,17 @@
 #
 # Create a {Client} instance to interact with the Cerbos policy decision point server over gRPC.
 module Cerbos
+  # @private
+  def self.deprecation_warning(message)
+    return unless Warning[:deprecated]
+
+    message = "[cerbos] #{message}"
+
+    location = caller_locations.find { |location| !location.absolute_path.start_with?(__dir__) }
+    message = "#{location.path}:#{location.lineno}: #{message}" unless location.nil?
+
+    warn message, category: :deprecated
+  end
 end
 
 require_relative "cerbos/client"

diff --git a/lib/cerbos/input/principal.rb b/lib/cerbos/input/principal.rb
@@ -17,7 +17,7 @@ class Principal
       # Application-specific attributes describing the principal.
       #
       # @return [Attributes]
-      attr_reader :attributes
+      attr_reader :attr
 
       # The policy version to use when authorizing the principal.
       #
@@ -37,23 +37,38 @@ class Principal
       #
       # @param id [String] a unique identifier for the principal.
       # @param roles [Array<String>] the roles held by the principal.
-      # @param attributes [Attributes, Hash] application-specific attributes describing the principal.
+      # @param attr [Attributes, Hash] application-specific attributes describing the principal.
+      # @param attributes [Attributes, Hash] deprecated (use `attr` instead).
       # @param policy_version [String, nil] the policy version to use when authorizing the principal (`nil` to use the Cerbos policy decision point server's configured default version).
       # @param scope [String, nil] the policy scope to use when authorizing the principal.
-      def initialize(id:, roles:, attributes: {}, policy_version: nil, scope: nil)
+      def initialize(id:, roles:, attr: {}, attributes: nil, policy_version: nil, scope: nil)
+        unless attributes.nil?
+          Cerbos.deprecation_warning "The `attributes` keyword argument is deprecated. Use `attr` instead."
+          attr = attributes
+        end
+
         @id = id
         @roles = roles
-        @attributes = Input.coerce_required(attributes, Attributes)
+        @attr = Input.coerce_required(attr, Attributes)
         @policy_version = policy_version
         @scope = scope
       end
 
+      # Application-specific attributes describing the principal.
+      #
+      # @deprecated Use {#attr} instead.
+      # @return [Attributes]
+      def attributes
+        Cerbos.deprecation_warning "The `attributes` method is deprecated. Use `attr` instead."
+        attr
+      end
+
       # @private
       def to_protobuf
         Protobuf::Cerbos::Engine::V1::Principal.new(
           id: id,
           roles: roles,
-          attr: attributes.to_protobuf,
+          attr: attr.to_protobuf,
           policy_version: policy_version,
           scope: scope
         )

diff --git a/lib/cerbos/input/resource.rb b/lib/cerbos/input/resource.rb
@@ -17,7 +17,7 @@ class Resource
       # Application-specific attributes describing the resource.
       #
       # @return [Attributes]
-      attr_reader :attributes
+      attr_reader :attr
 
       # The policy version to use when checking the principal's permissions on the resource.
       #
@@ -37,23 +37,38 @@ class Resource
       #
       # @param kind [String] the type of resource.
       # @param id [String] a unique identifier for the resource.
-      # @param attributes [Attributes, Hash] application-specific attributes describing the resource.
+      # @param attr [Attributes, Hash] application-specific attributes describing the resource.
+      # @param attributes [Attributes, Hash] deprecated (use `attr` instead).
       # @param policy_version [String, nil] the policy version to use when checking the principal's permissions on the resource (`nil` to use the Cerbos policy decision point server's configured default version).
       # @param scope [String, nil] the policy scope to use when checking the principal's permissions on the resource.
-      def initialize(kind:, id:, attributes: {}, policy_version: nil, scope: nil)
+      def initialize(kind:, id:, attr: {}, attributes: nil, policy_version: nil, scope: nil)
+        unless attributes.nil?
+          Cerbos.deprecation_warning "The `attributes` keyword argument is deprecated. Use `attr` instead."
+          attr = attributes
+        end
+
         @kind = kind
         @id = id
-        @attributes = Input.coerce_required(attributes, Attributes)
+        @attr = Input.coerce_required(attr, Attributes)
         @policy_version = policy_version
         @scope = scope
       end
 
+      # Application-specific attributes describing the resource.
+      #
+      # @deprecated Use {#attr} instead.
+      # @return [Attributes]
+      def attributes
+        Cerbos.deprecation_warning "The `attributes` method is deprecated. Use `attr` instead."
+        attr
+      end
+
       # @private
       def to_protobuf
         Protobuf::Cerbos::Engine::V1::Resource.new(
           kind: kind,
           id: id,
-          attr: attributes.to_protobuf,
+          attr: attr.to_protobuf,
           policy_version: policy_version,
           scope: scope
         )

diff --git a/lib/cerbos/input/resource_query.rb b/lib/cerbos/input/resource_query.rb
@@ -12,7 +12,7 @@ class ResourceQuery
       # Any application-specific attributes describing the resources to be queried that are known in advance.
       #
       # @return [Attributes]
-      attr_reader :attributes
+      attr_reader :attr
 
       # The policy version to use when planning the query.
       #
@@ -31,21 +31,36 @@ class ResourceQuery
       # Specify partial details of resources to be queried.
       #
       # @param kind [String] the type of resources to be queried.
-      # @param attributes [Attributes, Hash] any application-specific attributes describing the resources to be queried that are known in advance.
+      # @param attr [Attributes, Hash] any application-specific attributes describing the resources to be queried that are known in advance.
+      # @param attributes [Attributes, Hash] deprecated (use `attr` instead).
       # @param policy_version [String, nil] the policy version to use when planning the query (`nil` to use the Cerbos policy decision point server's configured default version).
       # @param scope [String, nil] the policy scope to use when planning the query.
-      def initialize(kind:, attributes: {}, policy_version: nil, scope: nil)
+      def initialize(kind:, attr: {}, attributes: nil, policy_version: nil, scope: nil)
+        unless attributes.nil?
+          Cerbos.deprecation_warning "The `attributes` keyword argument is deprecated. Use `attr` instead."
+          attr = attributes
+        end
+
         @kind = kind
-        @attributes = Input.coerce_required(attributes, Attributes)
+        @attr = Input.coerce_required(attr, Attributes)
         @policy_version = policy_version
         @scope = scope
       end
 
+      # Any application-specific attributes describing the resources to be queried that are known in advance.
+      #
+      # @deprecated Use {#attr} instead.
+      # @return [Attributes]
+      def attributes
+        Cerbos.deprecation_warning "The `attributes` method is deprecated. Use `attr` instead."
+        attr
+      end
+
       # @private
       def to_protobuf
         Protobuf::Cerbos::Engine::V1::PlanResourcesInput::Resource.new(
           kind: kind,
-          attr: attributes.to_protobuf,
+          attr: attr.to_protobuf,
           policy_version: policy_version,
           scope: scope
         )

diff --git a/spec/cerbos/client_spec.rb b/spec/cerbos/client_spec.rb
@@ -20,7 +20,7 @@
             policy_version: "1",
             scope: "test",
             roles: ["USER"],
-            attributes: {
+            attr: {
               country: {
                 alpha2: "",
                 alpha3: "NZL"
@@ -32,7 +32,7 @@
             id: "mine",
             policy_version: "1",
             scope: "test",
-            attributes: {
+            attr: {
               owner: "[email protected]"
             }
           },
@@ -59,7 +59,7 @@
             policy_version: "1",
             scope: "test",
             roles: ["USER"],
-            attributes: {
+            attr: {
               country: {
                 alpha2: "",
                 alpha3: "NZL"
@@ -71,7 +71,7 @@
             id: "mine",
             policy_version: "1",
             scope: "test",
-            attributes: {
+            attr: {
               owner: "[email protected]"
             }
           },
@@ -146,7 +146,7 @@
             policy_version: "1",
             scope: "test",
             roles: ["USER"],
-            attributes: {
+            attr: {
               country: {
                 alpha2: "",
                 alpha3: "NZL"
@@ -160,7 +160,7 @@
                 id: "mine",
                 policy_version: "1",
                 scope: "test",
-                attributes: {
+                attr: {
                   owner: "[email protected]"
                 }
               },
@@ -172,7 +172,7 @@
                 id: "theirs",
                 policy_version: "1",
                 scope: "test",
-                attributes: {
+                attr: {
                   owner: "[email protected]"
                 }
               },
@@ -184,7 +184,7 @@
                 id: "invalid",
                 policy_version: "1",
                 scope: "test",
-                attributes: {
+                attr: {
                   owner: 123
                 }
               },
@@ -367,7 +367,7 @@
             policy_version: "1",
             scope: "test",
             roles: ["USER"],
-            attributes: {
+            attr: {
               country: {
                 alpha2: "",
                 alpha3: "NZL"
@@ -378,7 +378,7 @@
             kind: "document",
             policy_version: "1",
             scope: "test",
-            attributes: {}
+            attr: {}
           },
           action: "edit",
           aux_data: {
@@ -450,7 +450,7 @@
               policy_version: "1",
               scope: "test",
               roles: ["USER"],
-              attributes: {
+              attr: {
                 country: {
                   alpha2: "",
                   alpha3: "NZL"
@@ -462,7 +462,7 @@
               id: "invalid",
               policy_version: "1",
               scope: "test",
-              attributes: {
+              attr: {
                 owner: 123
               }
             },
@@ -496,7 +496,7 @@
               policy_version: "1",
               scope: "test",
               roles: ["USER"],
-              attributes: {
+              attr: {
                 country: {
                   alpha2: "",
                   alpha3: "NZL"
@@ -507,7 +507,7 @@
               kind: "document",
               policy_version: "1",
               scope: "test",
-              attributes: {}
+              attr: {}
             },
             action: "edit"
           )
@@ -535,7 +535,7 @@
             policy_version: "1",
             scope: "test",
             roles: ["USER"],
-            attributes: {
+            attr: {
               country: {
                 alpha2: "",
                 alpha3: "NZL"
@@ -547,7 +547,7 @@
             id: "invalid",
             policy_version: "1",
             scope: "test",
-            attributes: {
+            attr: {
               owner: 123
             }
           },
@@ -577,7 +577,7 @@
             policy_version: "1",
             scope: "test",
             roles: ["USER"],
-            attributes: {
+            attr: {
               country: {
                 alpha2: "",
                 alpha3: "NZL"
@@ -588,7 +588,7 @@
             kind: "document",
             policy_version: "1",
             scope: "test",
-            attributes: {}
+            attr: {}
           },
           action: "edit"
         )