cerbos 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07ade13e70cd396203ce234a92079eac80d83ff17ee6e106ee63ea58352b2790
-  data.tar.gz: 988e7d8eb63d51c9ed1c7e705095dcaddb7d56efecc5302695106971cf07b169
+  metadata.gz: b1f96bbfba8e309d992b65cff1615eed19a8731c1b16c69f7cd9eb578e8f3f11
+  data.tar.gz: 934e07596201c3638201af7546ac1bd428ff2c4779cb8b25916a66fbb2d58fc4
 SHA512:
-  metadata.gz: 5e39a03911131fc3500f98c0ccd5c2fc8ff7317e6b34101632fd1bfe46b84a66b9cb236aa3697361a78e32db8f5ad39642e07ffc65d3e91f0fb960a5380ed969
-  data.tar.gz: 7d98aab58a966f4dad4a5f3866b766bf90e1a88aea850ceab101f7aee2e05192ab86058bb693a8c2cb7ec66bb65b2a3fe7555b3e07dadce62f10637184bc7f11
+  metadata.gz: 97b55e3a336f6389b899e62c3f19bf5411d85c319866b46ccc736c08d3869b89dcf930887fe650c6d151841047009b8ceadca315b83ac5214b5a3059cc2f77e5
+  data.tar.gz: fc2c68df0275eb67f3f2f6000f3f452d045f1de5dab1d56e593e3e5cb631e16052d59dbf1af293b5466adffcc0f7518cd5c210a3b0edec832b5524b3b3712f6e

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 No notable changes.
 
+## [0.12.0] - 2025-08-12
+
+### Added
+
+- `Cerbos::Hub::Stores::Client` for interacting with policy stores in Cerbos Hub ([#251](https://github.com/cerbos/cerbos-sdk-ruby/pull/251))
+
+## [0.11.0] - 2025-06-03
+
+### Added
+
+- Support for multiple actions in `Cerbos::Client#plan_resources` ([#239](https://github.com/cerbos/cerbos-sdk-ruby/pull/239))
+
+  Requires a policy decision point server running Cerbos 0.44+.
+
+### Removed
+
+- Support for Ruby 3.1 ([#234](https://github.com/cerbos/cerbos-sdk-ruby/pull/234))
+
 ## [0.10.0] - 2025-02-06
 
 ### Added
@@ -101,7 +119,9 @@ No notable changes.
 
 - Initial implementation of `Cerbos::Client` ([#2](https://github.com/cerbos/cerbos-sdk-ruby/pull/2))
 
-[Unreleased]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.8.0...v0.9.0

data/README.md

@@ -7,12 +7,12 @@
 [Cerbos](https://cerbos.dev) helps you super-charge your authorization implementation by writing context-aware access control policies for your application resources.
 Author access rules using an intuitive YAML configuration language, use your Git-ops infrastructure to test and deploy them, and make simple API requests to the Cerbos policy decision point (PDP) server to evaluate the policies and make dynamic access decisions.
 
-The Cerbos Ruby SDK makes it easy to interact with the Cerbos PDP from your Ruby applications.
+The Cerbos Ruby SDK makes it easy to interact with the [Cerbos PDP](https://www.cerbos.dev/product-cerbos-pdp) and [Cerbos Hub](https://www.cerbos.dev/product-cerbos-hub) from your Ruby applications.
 
 ## Prerequisites
 
 - Cerbos 0.16+
-- Ruby 3.1+
+- Ruby 3.2+
 
 ## Installation
 
@@ -30,7 +30,11 @@ $ gem install cerbos
 
 ## Example usage
 
+### Cerbos PDP
+
 ```ruby
+require "cerbos"
+
 client = Cerbos::Client.new("localhost:3593", tls: false)
 
 decision = client.check_resource(
@@ -52,12 +56,36 @@ decision.allow?("view") # => true
 decision.allow?("edit") # => false
 ```
 
-For more details, [see the `Client` documentation](https://www.rubydoc.info/gems/cerbos/Cerbos/Client).
+For more details, [see the `Cerbos::Client` documentation](https://www.rubydoc.info/gems/cerbos/Cerbos/Client).
+
+### Cerbos Hub [policy stores](https://docs.cerbos.dev/cerbos-hub/policy-stores)
+
+```ruby
+require "cerbos"
+
+client = Cerbos::Hub::Stores::Client.new(
+  client_id: ENV.fetch("CERBOS_HUB_CLIENT_ID"),
+  client_secret: ENV.fetch("CERBOS_HUB_CLIENT_SECRET")
+)
+
+response = client.modify_files(
+  store_id: ENV.fetch("CERBOS_HUB_STORE_ID"),
+  operations: [
+    {add_or_update: {path: "foo.yaml", contents: File.binread("path/to/foo.yaml")}},
+    {delete: "bar.yaml"}
+  ]
+)
+
+puts response.new_store_version
+```
+
+For more details, [see the `Cerbos::Hub::Stores::Client` documentation](https://www.rubydoc.info/gems/cerbos/Cerbos/Hub/Stores/Client).
 
 ## Further reading
 
 - [API reference](https://www.rubydoc.info/gems/cerbos/Cerbos)
 - [Cerbos documentation](https://docs.cerbos.dev)
+- [Cerbos Hub documentation](https://docs.cerbos.dev/cerbos-hub/)
 
 ## Get help
 

data/cerbos.gemspec

@@ -31,7 +31,8 @@ Gem::Specification.new do |spec|
     "yard_extensions.rb"
   ]
 
-  spec.required_ruby_version = ">= 3.1.0"
-  spec.add_dependency "grpc", "~> 1.46"
+  spec.required_ruby_version = ">= 3.2.0"
+  spec.add_dependency "concurrent-ruby", "~> 1.2"
+  spec.add_dependency "grpc", "~> 1.52"
   spec.add_dependency "google-protobuf", ">= 3.21.12", "< 5.0"
 end

data/lib/cerbos/abstract_class.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Cerbos
+  # @private
+  module AbstractClass
+    def initialize
+      raise NoMethodError, "Can't initialize #{self.class.name} directly, initialize a subclass instead (#{self.class.subclasses.map(&:name).join(", ")})"
+    end
+  end
+end

data/lib/cerbos/client.rb

@@ -39,32 +39,31 @@ module Cerbos
     # @example Invoke a callback when input fails schema validation
     #   client = Cerbos::Client.new("localhost:3593", tls: false, on_validation_error: ->(validation_errors) { do_something_with validation_errors })
     def initialize(target, tls:, grpc_channel_args: {}, grpc_metadata: {}, on_validation_error: :return, playground_instance: nil, timeout: nil)
-      @grpc_metadata = grpc_metadata.transform_keys(&:to_sym)
       @on_validation_error = on_validation_error
 
-      handle_errors do
+      Error.handle do
         credentials = tls ? tls.to_channel_credentials : :this_channel_is_insecure
 
         unless playground_instance.nil?
           credentials = credentials.compose(GRPC::Core::CallCredentials.new(->(*) { {"playground-instance" => playground_instance} }))
         end
 
-        channel_args = grpc_channel_args.merge({
-          "grpc.primary_user_agent" => [grpc_channel_args["grpc.primary_user_agent"], "cerbos-sdk-ruby/#{VERSION}"].compact.join(" ")
-        })
-
-        @cerbos_service = Protobuf::Cerbos::Svc::V1::CerbosService::Stub.new(
-          target,
-          credentials,
-          channel_args: channel_args,
-          timeout: timeout
+        @cerbos_service = Service.new(
+          stub: Protobuf::Cerbos::Svc::V1::CerbosService::Stub,
+          target:,
+          credentials:,
+          grpc_channel_args:,
+          grpc_metadata:,
+          timeout:
         )
 
-        @health_service = Protobuf::Grpc::Health::V1::Health::Stub.new(
-          target,
-          credentials,
-          channel_args: channel_args,
-          timeout: timeout
+        @health_service = Service.new(
+          stub: Protobuf::Grpc::Health::V1::Health::Stub,
+          target:,
+          credentials:,
+          grpc_channel_args:,
+          grpc_metadata:,
+          timeout:
         )
       end
     end
@@ -111,10 +110,10 @@ module Cerbos
     #   admin_api = client.check_health(service: "cerbos.svc.v1.CerbosAdminService")
     #   admin_api.status # => :DISABLED
     def check_health(service: "cerbos.svc.v1.CerbosService", grpc_metadata: {})
-      handle_errors do
+      Error.handle do
         request = Protobuf::Grpc::Health::V1::HealthCheckRequest.new(service: service)
 
-        response = perform_request(@health_service, :check, request, grpc_metadata)
+        response = @health_service.call(:check, request, grpc_metadata)
 
         Output::HealthCheck.from_protobuf(response)
       end
@@ -145,7 +144,7 @@ module Cerbos
     #
     #   decision.allow?("view") # => true
     def check_resource(principal:, resource:, actions:, aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid, grpc_metadata: {})
-      handle_errors do
+      Error.handle do
         check_resources(
           principal: principal,
           resources: [Input::ResourceCheck.new(resource: resource, actions: actions)],
@@ -185,7 +184,7 @@ module Cerbos
     #
     #   decision.allow?(resource: {kind: "document", id: "1"}, action: "view") # => true
     def check_resources(principal:, resources:, aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid, grpc_metadata: {})
-      handle_errors do
+      Error.handle do
         request = Protobuf::Cerbos::Request::V1::CheckResourcesRequest.new(
           principal: Input.coerce_required(principal, Input::Principal).to_protobuf,
           resources: Input.coerce_array(resources, Input::ResourceCheck).map(&:to_protobuf),
@@ -194,7 +193,7 @@ module Cerbos
           request_id: request_id
         )
 
-        response = perform_request(@cerbos_service, :check_resources, request, grpc_metadata)
+        response = @cerbos_service.call(:check_resources, request, grpc_metadata)
 
         Output::CheckResources.from_protobuf(response).tap do |output|
           handle_validation_errors output
@@ -206,7 +205,8 @@ module Cerbos
     #
     # @param principal [Input::Principal, Hash] the principal for whom to plan.
     # @param resource [Input::ResourceQuery, Hash] partial details of the resources for which to plan.
-    # @param action [String] the action for which to plan.
+    # @param action [String] deprecated (use `actions` instead).
+    # @param actions [Array<String>] the actions for which to plan (requires a policy decision point server running Cerbos v0.44+).
     # @param aux_data [Input::AuxData, Hash, nil] auxiliary data.
     # @param include_metadata [Boolean] `true` to include additional metadata ({Output::CheckResources::Result::Metadata}) in the results.
     # @param request_id [String] identifier for tracing the request.
@@ -218,23 +218,24 @@ module Cerbos
     #   plan = client.plan_resources(
     #     principal: {id: "user@example.com", roles: ["USER"]},
     #     resource: {kind: "document"},
-    #     action: "view"
+    #     actions: ["view"]
     #   )
     #
     #   plan.conditional? # => true
     #   plan.condition # => #<Cerbos::Output::PlanResources::Expression ...>
-    def plan_resources(principal:, resource:, action:, aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid, grpc_metadata: {})
-      handle_errors do
+    def plan_resources(principal:, resource:, action: "", actions: [], aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid, grpc_metadata: {})
+      Error.handle do
         request = Protobuf::Cerbos::Request::V1::PlanResourcesRequest.new(
           principal: Input.coerce_required(principal, Input::Principal).to_protobuf,
           resource: Input.coerce_required(resource, Input::ResourceQuery).to_protobuf,
           action: action,
+          actions: actions,
           aux_data: Input.coerce_optional(aux_data, Input::AuxData)&.to_protobuf,
           include_meta: include_metadata,
           request_id: request_id
         )
 
-        response = perform_request(@cerbos_service, :plan_resources, request, grpc_metadata)
+        response = @cerbos_service.call(:plan_resources, request, grpc_metadata)
 
         Output::PlanResources.from_protobuf(response).tap do |output|
           handle_validation_errors output
@@ -248,10 +249,10 @@ module Cerbos
     #
     # @return [Output::ServerInfo]
     def server_info(grpc_metadata: {})
-      handle_errors do
+      Error.handle do
         request = Protobuf::Cerbos::Request::V1::ServerInfoRequest.new
 
-        response = perform_request(@cerbos_service, :server_info, request, grpc_metadata)
+        response = @cerbos_service.call(:server_info, request, grpc_metadata)
 
         Output::ServerInfo.from_protobuf(response)
       end
@@ -259,18 +260,6 @@ module Cerbos
 
     private
 
-    def handle_errors
-      yield
-    rescue Error
-      raise
-    rescue ArgumentError, TypeError => error
-      raise Error::InvalidArgument.new(details: error.message)
-    rescue GRPC::BadStatus => error
-      raise Error::NotOK.from_grpc_bad_status(error)
-    rescue => error
-      raise Error, error.message
-    end
-
     def handle_validation_errors(output)
       return if @on_validation_error == :return
 
@@ -281,9 +270,5 @@ module Cerbos
 
       @on_validation_error.call validation_errors
     end
-
-    def perform_request(service, rpc, request, metadata)
-      service.public_send(rpc, request, metadata: @grpc_metadata.merge(metadata.transform_keys(&:to_sym)))
-    end
   end
 end

data/lib/cerbos/error.rb

@@ -56,80 +56,149 @@ module Cerbos
       end
     end
 
-    # The gRPC operation was cancelled.
+    # The operation was aborted.
+    class Aborted < NotOK
+      def initialize(code: GRPC::Core::StatusCodes::ABORTED, **args)
+        super
+      end
+    end
+
+    # The entity that the client attempted to create already exists.
+    class AlreadyExists < NotOK
+      def initialize(code: GRPC::Core::StatusCodes::ALREADY_EXISTS, **args)
+        super
+      end
+    end
+
+    # The operation was cancelled.
     class Cancelled < NotOK
       def initialize(code: GRPC::Core::StatusCodes::CANCELLED, **args)
         super
       end
     end
 
-    # The gRPC operation timed out.
+    # The operation resulted in unrecoverable data loss or corruption.
+    class DataLoss < NotOK
+      def initialize(code: GRPC::Core::StatusCodes::DATA_LOSS, **args)
+        super
+      end
+    end
+
+    # The operation timed out.
     class DeadlineExceeded < NotOK
       def initialize(code: GRPC::Core::StatusCodes::DEADLINE_EXCEEDED, **args)
         super
       end
     end
 
-    # The gRPC operation failed due to an internal error.
+    # The operation was rejected because the system is not in a state required for the operation's execution.
+    class FailedPrecondition < NotOK
+      def initialize(code: GRPC::Core::StatusCodes::FAILED_PRECONDITION, **args)
+        super
+      end
+    end
+
+    # The operation failed due to an internal error.
     class InternalError < NotOK
       def initialize(code: GRPC::Core::StatusCodes::INTERNAL, **args)
         super
       end
     end
 
-    # The gRPC operation was rejected because an argument was invalid.
+    # The operation was rejected because an argument was invalid.
     class InvalidArgument < NotOK
       def initialize(code: GRPC::Core::StatusCodes::INVALID_ARGUMENT, **args)
         super
       end
     end
 
-    # The gRPC operation was rejected because the requested entity was not found.
+    # The requested entity was not found.
     class NotFound < NotOK
       def initialize(code: GRPC::Core::StatusCodes::NOT_FOUND, **args)
         super
       end
     end
 
-    # The gRPC operation failed because a resource has been exhausted.
+    # The operation was attempted past the valid range.
+    class OutOfRange < NotOK
+      def initialize(code: GRPC::Core::StatusCodes::OUT_OF_RANGE, **args)
+        super
+      end
+    end
+
+    # The caller does not have permission to execute the specified operation.
+    class PermissionDenied < NotOK
+      def initialize(code: GRPC::Core::StatusCodes::PERMISSION_DENIED, **args)
+        super
+      end
+    end
+
+    # The operation failed because a resource has been exhausted.
     class ResourceExhausted < NotOK
       def initialize(code: GRPC::Core::StatusCodes::RESOURCE_EXHAUSTED, **args)
         super
       end
     end
 
-    # The gRPC operation was rejected because it did not have valid authentication credentials.
+    # The operation was rejected because it did not have valid authentication credentials.
     class Unauthenticated < NotOK
       def initialize(code: GRPC::Core::StatusCodes::UNAUTHENTICATED, **args)
         super
       end
     end
 
-    # The gRPC operation failed because the service is unavailable.
+    # The operation failed because the service is unavailable.
     class Unavailable < NotOK
       def initialize(code: GRPC::Core::StatusCodes::UNAVAILABLE, **args)
         super
       end
     end
 
-    # The gRPC operation is not supported.
+    # The operation is not supported.
     class Unimplemented < NotOK
       def initialize(code: GRPC::Core::StatusCodes::UNIMPLEMENTED, **args)
         super
       end
     end
 
+    # An unknown error occurred.
+    class Unknown < NotOK
+      def initialize(code: GRPC::Core::StatusCodes::UNKNOWN, **args)
+        super
+      end
+    end
+
     GRPC_BAD_STATUS_ERROR_CLASS = {
+      GRPC::Aborted => Aborted,
+      GRPC::AlreadyExists => AlreadyExists,
       GRPC::Cancelled => Cancelled,
+      GRPC::DataLoss => DataLoss,
       GRPC::DeadlineExceeded => DeadlineExceeded,
+      GRPC::FailedPrecondition => FailedPrecondition,
       GRPC::Internal => InternalError,
       GRPC::InvalidArgument => InvalidArgument,
       GRPC::NotFound => NotFound,
+      GRPC::OutOfRange => OutOfRange,
+      GRPC::PermissionDenied => PermissionDenied,
       GRPC::ResourceExhausted => ResourceExhausted,
       GRPC::Unauthenticated => Unauthenticated,
       GRPC::Unavailable => Unavailable,
-      GRPC::Unimplemented => Unimplemented
+      GRPC::Unimplemented => Unimplemented,
+      GRPC::Unknown => Unknown
     }.freeze
     private_constant :GRPC_BAD_STATUS_ERROR_CLASS
+
+    # @private
+    def self.handle
+      yield
+    rescue Error
+      raise
+    rescue ArgumentError, TypeError => error
+      raise InvalidArgument.new(details: error.message)
+    rescue GRPC::BadStatus => error
+      raise NotOK.from_grpc_bad_status(error)
+    rescue => error
+      raise Error, error.message
+    end
   end
 end

data/lib/cerbos/hub/access_token.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    # @private
+    class AccessToken
+      def initialize(client_id:, client_secret:, **options)
+        @client_id = client_id
+        @client_secret = client_secret
+
+        @lock = Concurrent::ReadWriteLock.new
+        @result = None.new
+
+        @service = Cerbos::Service.new(
+          stub: Protobuf::Cerbos::Cloud::Apikey::V1::ApiKeyService::Stub,
+          credentials: GRPC::Core::ChannelCredentials.new,
+          **options
+        )
+      end
+
+      def fetch
+        token = @lock.with_read_lock { @result.token }
+        return token unless token.nil?
+
+        @lock.with_write_lock do
+          token = @result.token
+          return token unless token.nil?
+
+          attempt = @result.next_attempt
+          attempted_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          Error.handle do
+            request = Protobuf::Cerbos::Cloud::Apikey::V1::IssueAccessTokenRequest.new(
+              client_id: @client_id,
+              client_secret: @client_secret
+            )
+
+            response = Hub.with_circuit_breaker { @service.call(:issue_access_token, request, {}) }
+
+            @result = Success.new(response:, attempted_at:)
+          end
+
+          @result.token
+        rescue Error => error
+          @result = Failure.new(error:, attempt:, attempted_at:)
+          raise
+        end
+      end
+
+      private
+
+      # @private
+      class None
+        def token
+          nil
+        end
+
+        def next_attempt
+          1
+        end
+      end
+      private_constant :None
+
+      # @private
+      class Success
+        def initialize(response:, attempted_at:)
+          @token = response.access_token
+          @refresh_at = attempted_at + response.expires_in.seconds - 300
+        end
+
+        def token
+          @token if Process.clock_gettime(Process::CLOCK_MONOTONIC) < @refresh_at
+        end
+
+        def next_attempt
+          1
+        end
+      end
+      private_constant :Success
+
+      # @private
+      class Failure
+        def initialize(error:, attempt:, attempted_at:)
+          @error = error
+          @attempt = attempt
+          @retry_at = attempted_at + retry_in
+        end
+
+        def token
+          remaining = @retry_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return nil if remaining <= 0
+          raise @error if remaining.infinite?
+
+          begin
+            raise @error
+          rescue
+            raise Error::Cancelled.new(details: "Previous authentication attempt failed, backing off for %.3gs" % remaining)
+          end
+        end
+
+        def next_attempt
+          @attempt + 1
+        end
+
+        private
+
+        def retry_in
+          case @error
+          when Error::Aborted, Error::Cancelled
+            -Float::INFINITY # immediately
+          when Error::Unauthenticated
+            Float::INFINITY # never
+          else
+            backoff
+          end
+        end
+
+        MIN_INTERVAL = 0.5
+        MAX_INTERVAL = 60
+        MULTIPLIER = 1.5
+        RANDOMIZATION_FACTOR = 0.5
+        USE_MAX_INTERVAL_AFTER_ATTEMPT = (Math.log(MAX_INTERVAL / MIN_INTERVAL) / Math.log(MULTIPLIER)).ceil
+
+        def backoff
+          interval = if @attempt > USE_MAX_INTERVAL_AFTER_ATTEMPT
+            MAX_INTERVAL
+          else
+            MULTIPLIER**(@attempt - 1) * MIN_INTERVAL
+          end
+
+          interval * (1 + (2 * rand - 1) * RANDOMIZATION_FACTOR)
+        end
+      end
+      private_constant :Failure
+    end
+  end
+end