cerbos 0.10.0 → 0.12.0

data/lib/cerbos/hub/circuit_breaker.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    # @private
+    def self.with_circuit_breaker(&)
+      CIRCUIT_BREAKER.run(&)
+    end
+
+    # @private
+    class CircuitBreaker
+      def initialize(error_rate_threshold: 0.6, volume_threshold: 5, reset_timeout: 60, window_duration: 15, ignore_errors: [
+        GRPC::Aborted,
+        GRPC::AlreadyExists,
+        GRPC::Cancelled,
+        GRPC::DeadlineExceeded,
+        GRPC::FailedPrecondition
+      ])
+        @error_rate_threshold = error_rate_threshold
+        @volume_threshold = volume_threshold
+        @reset_timeout = reset_timeout
+        @ignore_errors = ignore_errors
+        @counter = Counter.new(window_duration:)
+        @state = Concurrent::AtomicReference.new(:closed)
+      end
+
+      def run
+        start
+        yield.tap do
+          succeeded
+        end
+      rescue => error
+        failed error
+        raise error
+      end
+
+      private
+
+      def start
+        loop do
+          case state = @state.get
+          when Numeric
+            raise circuit_open if now < state + @reset_timeout
+            return if @state.compare_and_set(state, :half_open)
+
+          when :half_open
+            return
+
+          when :closed
+            succeeded, failed = @counter.stats
+            volume = succeeded + failed
+            return if volume < @volume_threshold
+
+            error_rate = failed.fdiv(volume)
+            return if error_rate < @error_rate_threshold
+
+            @state.compare_and_set(state, now)
+            raise circuit_open
+          end
+        end
+      end
+
+      def succeeded
+        @counter.add_success
+        @state.compare_and_set(:half_open, :closed)
+      end
+
+      def failed(error)
+        return if @ignore_errors.any? { |ignored_error| error.is_a?(ignored_error) }
+
+        @counter.add_failure
+        @state.compare_and_set(:half_open, now)
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :second)
+      end
+
+      def circuit_open
+        Error::Cancelled.new(details: "Too many failures")
+      end
+
+      # @private
+      class Counter
+        def initialize(window_duration:)
+          @lock = Concurrent::ReadWriteLock.new
+          @window_duration = window_duration
+          @buckets = []
+          @current_bucket = nil
+        end
+
+        def add_success
+          current_bucket.add_success
+        end
+
+        def add_failure
+          current_bucket.add_failure
+        end
+
+        def stats
+          @lock.with_read_lock do
+            time = now
+
+            index = 0
+
+            loop do
+              return [0, 0] if index == @buckets.size
+              break if valid?(@buckets[index], time)
+
+              index += 1
+            end
+
+            successes = 0
+            failures = 0
+
+            loop do
+              bucket = @buckets[index]
+              successes += bucket.successes
+              failures += bucket.failures
+
+              index += 1
+              return [successes, failures] if index == @buckets.size
+            end
+          end
+        end
+
+        private
+
+        def current_bucket
+          time = now
+          bucket = @lock.with_read_lock { @current_bucket }
+          return bucket if bucket&.time == time
+
+          @lock.with_write_lock do
+            return @current_bucket if @current_bucket&.time == time
+
+            @current_bucket = Bucket.new(time:)
+            @buckets.push @current_bucket
+            @buckets.shift until valid?(@buckets.first, time)
+
+            @current_bucket
+          end
+        end
+
+        def valid?(bucket, time)
+          bucket.time >= time - @window_duration
+        end
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC, :second)
+        end
+
+        # @private
+        class Bucket
+          attr_reader :time
+
+          def initialize(time:)
+            @time = time
+            @successes = Concurrent::AtomicFixnum.new
+            @failures = Concurrent::AtomicFixnum.new
+          end
+
+          def add_success
+            @successes.increment
+          end
+
+          def add_failure
+            @failures.increment
+          end
+
+          def successes
+            @successes.value
+          end
+
+          def failures
+            @failures.value
+          end
+        end
+      end
+    end
+
+    CIRCUIT_BREAKER = CircuitBreaker.new
+    private_constant :CIRCUIT_BREAKER
+  end
+end

data/lib/cerbos/hub/service.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    # @private
+    class Service
+      def initialize(client_id:, client_secret:, stub:, credentials: GRPC::Core::ChannelCredentials.new, **options)
+        @access_token = AccessToken.new(client_id:, client_secret:, **options)
+        @service = Cerbos::Service.new(stub:, credentials:, **options)
+      end
+
+      def call(rpc, request, metadata)
+        access_token = @access_token.fetch
+        Hub.with_circuit_breaker { @service.call(rpc, request, metadata.merge({"x-cerbos-auth": access_token})) }
+      end
+    end
+  end
+end

data/lib/cerbos/hub/stores/client.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    module Stores
+      # A client for interacting with policy stores in Cerbos Hub.
+      class Client
+        # Create a client for interacting with policy stores in Cerbos Hub.
+        #
+        # @param client_id [String] ID of the client credential to authenticate with Cerbos Hub.
+        # @param client_secret [String] secret of the client credential to authenticate with Cerbos Hub.
+        # @param target [String] address of the Cerbos Hub server.
+        # @param grpc_channel_args [Hash{String, Symbol => String, Integer}] low-level settings for the gRPC channel (see [available keys in the gRPC documentation](https://grpc.github.io/grpc/core/group__grpc__arg__keys.html)).
+        # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to every request to the PDP.
+        # @param timeout [Numeric, nil] timeout for gRPC calls, in seconds (`nil` to never time out).
+        def initialize(client_id:, client_secret:, target: "api.cerbos.cloud:443", grpc_channel_args: {}, grpc_metadata: {}, timeout: nil)
+          @service = Service.new(
+            client_id:,
+            client_secret:,
+            stub: Protobuf::Cerbos::Cloud::Store::V1::CerbosStoreService::Stub,
+            target:,
+            grpc_channel_args:,
+            grpc_metadata:,
+            timeout:
+          )
+        end
+
+        # Get file contents from a policy store.
+        #
+        # @param store_id [String] ID of the store from which to get files.
+        # @param files [Array<String>] paths of the files to retrieve.
+        # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
+        #
+        # @return [Output::GetFiles]
+        #
+        # @example
+        #   client.get_files(store_id: "MWPKEMFX3CK1", files: ["path/to/policy.yaml"])
+        def get_files(store_id:, files:, grpc_metadata: {})
+          Error.handle do
+            request = Protobuf::Cerbos::Cloud::Store::V1::GetFilesRequest.new(store_id:, files:)
+
+            response = @service.call(:get_files, request, grpc_metadata)
+
+            Output::GetFiles.from_protobuf(response)
+          end
+        end
+
+        # List file paths in a policy store.
+        #
+        # @param store_id [String] ID of the store from which to list files.
+        # @param filter [Input::FileFilter, Hash, nil] filter to limit which files are listed.
+        # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
+        #
+        # @return [Output::ListFiles]
+        #
+        # @example
+        #   client.list_files(store_id: "MWPKEMFX3CK1")
+        def list_files(store_id:, filter: nil, grpc_metadata: {})
+          Error.handle do
+            request = Protobuf::Cerbos::Cloud::Store::V1::ListFilesRequest.new(
+              store_id:,
+              filter: Cerbos::Input.coerce_optional(filter, Input::FileFilter)&.to_protobuf
+            )
+
+            response = @service.call(:list_files, request, grpc_metadata)
+
+            Output::ListFiles.from_protobuf(response)
+          end
+        end
+
+        # Modify files in a policy store.
+        #
+        # This is a "patch" operation; files that aren't included in the request won't be modified.
+        #
+        # @param store_id [String] ID of the store in which to modify files.
+        # @param operations [Array<Input::FileOperation, Hash>] modifications to make.
+        # @param condition [Input::FileModificationCondition, Hash, nil] a condition that must be met for the modifications to be made.
+        # @param change_details [Input::ChangeDetails, Hash, nil] metadata describing the change being made.
+        # @param allow_unchanged [Boolean] allow modifications that do not change the state of the store. If `false` (the default), an {Error::OperationDiscarded} will be thrown if the modifications leave the store unchanged. If `true`, no error will be thrown and the current store version will be returned.
+        # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
+        #
+        # @return [Output::ModifyFiles]
+        #
+        # @example
+        #   client.modify_files(
+        #     store_id: "MWPKEMFX3CK1",
+        #     operations: [{add_or_update: {path: "policy.yaml", contents: ::File.binread("path/to/policy.yaml")}}]
+        #   )
+        def modify_files(store_id:, operations:, condition: nil, change_details: nil, allow_unchanged: false, grpc_metadata: {})
+          Error.handle do
+            request = Protobuf::Cerbos::Cloud::Store::V1::ModifyFilesRequest.new(
+              store_id:,
+              operations: Cerbos::Input.coerce_array(operations, Input::FileOperation).map(&:to_protobuf),
+              condition: Cerbos::Input.coerce_optional(condition, Input::FileModificationCondition)&.to_protobuf_modify_files,
+              change_details: Cerbos::Input.coerce_optional(change_details, Input::ChangeDetails)&.to_protobuf
+            )
+
+            response = @service.call(:modify_files, request, grpc_metadata)
+
+            Output::ModifyFiles.from_protobuf(response)
+          end
+        rescue Error::OperationDiscarded => error
+          raise unless allow_unchanged
+
+          Output::ModifyFiles.new(
+            new_store_version: error.current_store_version,
+            changed: false
+          )
+        end
+
+        # Replace files in a policy store.
+        #
+        # This is a "put" operation; files that aren't included in the request will be removed from the store.
+        #
+        # @param store_id [String] ID of the store in which to replace files.
+        # @param files [Array<File, Hash>, nil] files to upload to the store. Mutually exclusive with `zipped_contents`.
+        # @param zipped_contents [String, nil] binary-encoded string containing zipped files to upload to the store.
+        # @param condition [Input::FileModificationCondition, Hash, nil] a condition that must be met for the replacement to be made.
+        # @param change_details [Input::ChangeDetails, Hash, nil] metadata describing the change being made.
+        # @param allow_unchanged [Boolean] allow replacements that do not change the state of the store. If `false` (the default), an {Error::OperationDiscarded} will be thrown if the contents match those of the store. If `true`, no error will be thrown and the current store version will be returned.
+        # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
+        #
+        # @return [Output::ReplaceFiles]
+        #
+        # @example Upload individual files
+        #   client.replace_files(
+        #     store_id: "MWPKEMFX3CK1",
+        #     files: [{path: "policy.yaml", contents: ::File.binread("path/to/policy.yaml")}]
+        #   )
+        #
+        # @example Upload zipped files
+        #   client.replace_files(
+        #     store_id: "MWPKEMFX3CK1",
+        #     zipped_contents: ::File.binread("path/to/policies.zip")
+        #   )
+        def replace_files(store_id:, files: nil, zipped_contents: nil, condition: nil, change_details: nil, allow_unchanged: false, grpc_metadata: {})
+          Error.handle do
+            request = Protobuf::Cerbos::Cloud::Store::V1::ReplaceFilesRequest.new(
+              store_id:,
+              files: files && Protobuf::Cerbos::Cloud::Store::V1::ReplaceFilesRequest::Files.new(files: files.map { |file| Cerbos::Input.coerce_required(file, File).to_protobuf }),
+              zipped_contents:,
+              condition: Cerbos::Input.coerce_optional(condition, Input::FileModificationCondition)&.to_protobuf_replace_files,
+              change_details: Cerbos::Input.coerce_optional(change_details, Input::ChangeDetails)&.to_protobuf
+            )
+
+            response = @service.call(:replace_files, request, grpc_metadata)
+
+            Output::ReplaceFiles.from_protobuf(response)
+          end
+        rescue Error::OperationDiscarded => error
+          raise unless allow_unchanged
+
+          Output::ReplaceFiles.new(
+            new_store_version: error.current_store_version,
+            ignored_files: error.ignored_files,
+            changed: false
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cerbos/hub/stores/error.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    module Stores
+      # Namespace for errors specific to Cerbos Hub stores.
+      module Error
+        # Error thrown when attempting to modify a store that is connected to a Git repository.
+        class CannotModifyGitConnectedStore < Cerbos::Error::NotOK
+          # @private
+          def initialize(error, _detail)
+            super(code: error.code, details: error.details, metadata: error.metadata)
+          end
+        end
+
+        # Error thrown when a store modification is rejected because the condition specified in the request wasn't met.
+        class ConditionUnsatisfied < Cerbos::Error::NotOK
+          # The current version of the store.
+          attr_reader :current_store_version
+
+          # @private
+          def initialize(error, detail)
+            super(code: error.code, details: error.details, metadata: error.metadata)
+            @current_store_version = detail.current_store_version
+          end
+        end
+
+        # Error thrown when {Client#replace_files} fails because the request didn't contain any usable files.
+        class NoUsableFiles < Cerbos::Error::NotOK
+          # Paths of files that were provided in the request but were ignored.
+          #
+          # Files with unexpected paths, for example hidden files, will be ignored.
+          attr_reader :ignored_files
+
+          # @private
+          def initialize(error, detail)
+            super(code: error.code, details: error.details, metadata: error.metadata)
+            @ignored_files = detail.ignored_files
+          end
+        end
+
+        # Error thrown when a store modification is aborted because it doesn't change the state of the store.
+        #
+        # Use the `allow_unchanged` request parameter to avoid throwing an error and return the current store version instead.
+        class OperationDiscarded < Cerbos::Error::NotOK
+          # The current version of the store.
+          attr_reader :current_store_version
+
+          # Paths of files that were provided in the request but were ignored.
+          #
+          # Files with unexpected paths, for example hidden files, will be ignored.
+          attr_reader :ignored_files
+
+          # @private
+          def initialize(error, detail)
+            super(code: error.code, details: error.details, metadata: error.metadata)
+            @current_store_version = detail.current_store_version
+            @ignored_files = detail.ignored_files
+          end
+        end
+
+        # Error thrown when a store modification is rejected because it contains invalid files.
+        class ValidationFailure < Cerbos::Error::NotOK
+          # The validation failures.
+          attr_reader :errors
+
+          # @private
+          def initialize(error, detail)
+            super(code: error.code, details: error.details, metadata: error.metadata)
+            @errors = detail.errors.map { |file_error| Output::FileError.from_protobuf(file_error) }
+          end
+        end
+
+        # @private
+        def self.handle
+          Cerbos::Error.handle do
+            yield
+          rescue GRPC::BadStatus => error
+            raise from_grpc_bad_status(error)
+          end
+        end
+
+        # @private
+        def self.from_grpc_bad_status(error)
+          status = error.to_rpc_status
+          return error if status.nil?
+
+          status.details.each do |detail|
+            ERROR_FROM_DETAILS.each do |detail_class, error_class|
+              return error_class.new(error, detail.unpack(detail_class)) if detail.is(detail_class)
+            end
+          end
+
+          error
+        end
+
+        ERROR_FROM_DETAILS = {
+          Protobuf::Cerbos::Cloud::Store::V1::ErrDetailCannotModifyGitConnectedStore => CannotModifyGitConnectedStore,
+          Protobuf::Cerbos::Cloud::Store::V1::ErrDetailConditionUnsatisfied => ConditionUnsatisfied,
+          Protobuf::Cerbos::Cloud::Store::V1::ErrDetailNoUsableFiles => NoUsableFiles,
+          Protobuf::Cerbos::Cloud::Store::V1::ErrDetailOperationDiscarded => OperationDiscarded,
+          Protobuf::Cerbos::Cloud::Store::V1::ErrDetailValidationFailure => ValidationFailure
+        }.freeze
+        private_constant :ERROR_FROM_DETAILS
+      end
+    end
+  end
+end

data/lib/cerbos/hub/stores/file.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    module Stores
+      # A file in a store.
+      File = Output.new_class(:path, :contents) do
+        # @!attribute [r] path
+        #   The path of the file.
+        #
+        #   @return [String]
+
+        # @!attribute [r] contents
+        #   The contents of the file (with binary encoding).
+        #
+        #   @return [String]
+        def self.from_protobuf(file)
+          new(path: file.path, contents: file.contents)
+        end
+
+        # @private
+        def to_protobuf
+          Protobuf::Cerbos::Cloud::Store::V1::File.new(path:, contents:)
+        end
+      end
+    end
+  end
+end

data/lib/cerbos/hub/stores/input/change_details/origin.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    module Stores
+      module Input
+        class ChangeDetails
+          # Origin of a change that was made to a store.
+          #
+          # @abstract
+          class Origin
+            include AbstractClass
+
+            # Details of a change made to a store when syncing it with a Git repository.
+            class Git < Origin
+              # The Git repository with which the store was synced.
+              #
+              # @return [String]
+              attr_reader :repo
+
+              # The Git ref with which the store was synced.
+              #
+              # @return [String]
+              attr_reader :ref
+
+              # The hash of the commit with which the store was synced.
+              #
+              # @return [String]
+              attr_reader :hash
+
+              # The message of the commit with which the store was synced.
+              #
+              # @return [String]
+              attr_reader :message
+
+              # The committer of the commit with which the store was synced.
+              #
+              # @return [String]
+              attr_reader :committer
+
+              # The commit date of the commit with which the store was synced.
+              #
+              # @return [Time]
+              # @return [nil] if not provided
+              attr_reader :commit_date
+
+              # The author of the commit with which the store was synced.
+              #
+              # @return [String]
+              attr_reader :author
+
+              # The author date of the commit with which the store was synced.
+              #
+              # @return [Time]
+              # @return [nil] if not provided
+              attr_reader :author_date
+
+              # Specify details of a change made to a store when syncing it with a Git repository.
+              #
+              # @param repo [String] the Git repository with which the store was synced.
+              # @param ref [String] the Git ref with which the store was synced.
+              # @param hash [String] the hash of the commit with which the store was synced.
+              # @param message [String] the message of the commit with which the store was synced.
+              # @param committer [String] the committer of the commit with which the store was synced.
+              # @param commit_date [Time, nil] the commit date of the commit with which the store was synced.
+              # @param author [String] the author of the commit with which the store was synced.
+              # @param author_date [Time, nil] the author date of the commit with which the store was synced.
+              def initialize(
+                repo: "",
+                ref: "",
+                hash: "",
+                message: "",
+                committer: "",
+                commit_date: nil,
+                author: "",
+                author_date: nil
+              )
+                @repo = repo
+                @ref = ref
+                @hash = hash
+                @message = message
+                @committer = committer
+                @commit_date = commit_date
+                @author = author
+                @author_date = author_date
+              end
+
+              # @private
+              def to_protobuf
+                Protobuf::Cerbos::Cloud::Store::V1::ChangeDetails::Git.new(
+                  repo:,
+                  ref:,
+                  hash:,
+                  message:,
+                  committer:,
+                  commit_date: commit_date && Google::Protobuf::Timestamp.new.from_time(commit_date),
+                  author:,
+                  author_date: author_date && Google::Protobuf::Timestamp.new.from_time(author_date)
+                )
+              end
+            end
+
+            # Details of a change made to a store by an internal application.
+            class Internal < Origin
+              # The source of the change.
+              #
+              # @return [String]
+              attr_reader :source
+
+              # User-defined metadata about the origin of the change.
+              #
+              # @return [Cerbos::Input::Attributes]
+              attr_reader :metadata
+
+              # Specify details of a change made to a store by an internal application.
+              #
+              # @param source [String] the source of the change.
+              # @param metadata [Cerbos::Input::Attributes, Hash] user-defined metadata about the origin of the change.
+              def initialize(source: "", metadata: {})
+                @source = source
+                @metadata = Cerbos::Input.coerce_required(metadata, Cerbos::Input::Attributes)
+              end
+
+              # @private
+              def to_protobuf
+                Protobuf::Cerbos::Cloud::Store::V1::ChangeDetails::Internal.new(source:, metadata: metadata.to_protobuf)
+              end
+            end
+
+            # @private
+            def self.from_h(**origin)
+              case origin
+              in git:, **nil
+                Git.new(**git)
+              in internal:, **nil
+                Internal.new(**internal)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cerbos/hub/stores/input/change_details/uploader.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Hub
+    module Stores
+      module Input
+        class ChangeDetails
+          # Metadata describing the uploader who made a change to a store.
+          class Uploader
+            # The name of the uploader.
+            #
+            # @return [String]
+            attr_reader :name
+
+            # User-defined metadata about the origin of the change.
+            #
+            # @return [Cerbos::Input::Attributes]
+            attr_reader :metadata
+
+            # Specify metadata describing the uploader who made a change to a store.
+            #
+            # @param name [String] the name of the uploader.
+            # @param metadata [Cerbos::Input::Attributes, Hash] user-defined metadata about the origin of the change.
+            def initialize(name: "", metadata: {})
+              @name = name
+              @metadata = Cerbos::Input.coerce_required(metadata, Cerbos::Input::Attributes)
+            end
+
+            # @private
+            def to_protobuf
+              Protobuf::Cerbos::Cloud::Store::V1::ChangeDetails::Uploader.new(name:, metadata: metadata.to_protobuf)
+            end
+          end
+        end
+      end
+    end
+  end
+end