cerbos 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09d04980a1c08690efeeac6d04608e47e18def9b0f2ab6a5c256b4b22576464d'
-  data.tar.gz: 61968be4473d1a480979d9e2d2af05f0911f1d8b4a8c90947d8dce72910565f7
+  metadata.gz: c6961d2c4bf6227d115dfa027f8823762bba4725c3d0dbe0c884ba2d69d0a253
+  data.tar.gz: 45d8c99f6aaeaa8aea2f30a0b0c4befbed70c6feb97f53f5f6c2288eada4919b
 SHA512:
-  metadata.gz: 788ca1b6ff6c4e3a1ea71c791fef64f5802a89423d21dba5da7f91f7fc697ff91f1aa7ebcedab4d4bde807c531b3b13b4ac5e95a53b93d76c79077e214ecd54b
-  data.tar.gz: 2115919d8cb958b0c347c09710d780d7748fec5933f65f4e91d2af7c937ec0e151ad7cfa808526213a788839ea8360fcfa153b94b9574d9ce6facabdca56fab1
+  metadata.gz: 50f06f8fc92658d6ade88f5ccfc92c899e8584aeb0c043faa1d350493645c49674ca0a1faff8484ba07d53f6243436622fb855fed1cdff47705d1dfde0c8c735
+  data.tar.gz: 2d440c072fb8554ed687004ca97ed1717e9735d031f385350da15ddf5bd52fe427837c5a330bbc2cb82bbdc3fcfe733f924bcb9cae1c597bed4eec5b79ebc490

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 No notable changes.
 
+## [0.8.0] - 2024-01-12
+
+### Added
+
+- `grpc_metadata` option to `Cerbos::Client` constructor and request methods to add gRPC metadata (a.k.a. HTTP headers) to requests to the policy decision point ([#132](https://github.com/cerbos/cerbos-sdk-ruby/pull/132))
+
 ## [0.7.0] - 2023-06-07
 
 ### Added
@@ -68,7 +74,8 @@ 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.7.0...HEAD
+[Unreleased]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/cerbos/cerbos-sdk-ruby/compare/v0.5.0...v0.6.0

data/lib/cerbos/client.rb

@@ -4,14 +4,22 @@ module Cerbos
   # A client for interacting with the Cerbos policy decision point (PDP) server over gRPC.
   #
   # An instance of the client may be shared between threads.
-  # However, due to [an issue in the underlying `grpc` gem](https://github.com/grpc/grpc/issues/8798), it's not possible to use the client before and after process forks.
-  # If your application runs on a forking webserver (for example, Puma in clustered mode), then you'll need to ensure that you only create client instances in the child (worker) processes.
+  #
+  # Due to [a limitation in the underlying `grpc` gem](https://github.com/grpc/grpc/issues/8798), creating a client instance before a process fork is [only (experimentally) supported on Linux](https://github.com/grpc/grpc/pull/33430) and requires you to
+  # - have at least v1.57.0 of the `grpc` gem installed,
+  # - set the `GRPC_ENABLE_FORK_SUPPORT` environment variable to `1`,
+  # - call `GRPC.prefork` before forking,
+  # - call `GRPC.postfork_parent` in the parent process after forking, and
+  # - call `GRPC.postfork_child` in the child processes after forking.
+  #
+  # Otherwise, if your application runs on a forking webserver (for example, Puma in clustered mode), then you'll need to ensure that you only create client instances in the child (worker) processes.
   class Client
     # Create a client for interacting with the Cerbos PDP server over gRPC.
     #
     # @param target [String] Cerbos PDP server address (`"host"`, `"host:port"`, or `"unix:/path/to/socket"`).
     # @param tls [TLS, MutualTLS, false] gRPC connection encryption settings (`false` for plaintext).
     # @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 on_validation_error [:return, :raise, #call] action to take when input fails schema validation (`:return` to return the validation errors in the response, `:raise` to raise {Error::ValidationFailed}, or a callback to invoke).
     # @param playground_instance [String, nil] identifier of the playground instance to use when prototyping against the hosted demo PDP.
     # @param timeout [Numeric, nil] timeout for gRPC calls, in seconds (`nil` to never time out).
@@ -30,7 +38,8 @@ 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: {}, on_validation_error: :return, playground_instance: nil, timeout: nil)
+    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
@@ -60,6 +69,7 @@ module Cerbos
     # @param action [String] the action to check.
     # @param aux_data [Input::AuxData, Hash, nil] auxiliary data.
     # @param request_id [String] identifier for tracing the request.
+    # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
     #
     # @return [Boolean]
     #
@@ -69,13 +79,14 @@ module Cerbos
     #     resource: {kind: "document", id: "1"},
     #     action: "view"
     #   ) # => true
-    def allow?(principal:, resource:, action:, aux_data: nil, request_id: SecureRandom.uuid)
+    def allow?(principal:, resource:, action:, aux_data: nil, request_id: SecureRandom.uuid, grpc_metadata: {})
       check_resource(
         principal: principal,
         resource: resource,
         actions: [action],
         aux_data: aux_data,
-        request_id: request_id
+        request_id: request_id,
+        grpc_metadata: grpc_metadata
       ).allow?(action)
     end
 
@@ -87,6 +98,7 @@ module Cerbos
     # @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.
+    # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
     #
     # @return [Output::CheckResources::Result]
     #
@@ -98,14 +110,15 @@ module Cerbos
     #   )
     #
     #   decision.allow?("view") # => true
-    def check_resource(principal:, resource:, actions:, aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid)
+    def check_resource(principal:, resource:, actions:, aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid, grpc_metadata: {})
       handle_errors do
         check_resources(
           principal: principal,
           resources: [Input::ResourceCheck.new(resource: resource, actions: actions)],
           aux_data: aux_data,
           include_metadata: include_metadata,
-          request_id: request_id
+          request_id: request_id,
+          grpc_metadata: grpc_metadata
         ).find_result(resource)
       end
     end
@@ -117,6 +130,7 @@ module Cerbos
     # @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.
+    # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
     #
     # @return [Output::CheckResources]
     #
@@ -136,7 +150,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)
+    def check_resources(principal:, resources:, aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid, grpc_metadata: {})
       handle_errors do
         request = Protobuf::Cerbos::Request::V1::CheckResourcesRequest.new(
           principal: Input.coerce_required(principal, Input::Principal).to_protobuf,
@@ -146,7 +160,7 @@ module Cerbos
           request_id: request_id
         )
 
-        response = perform_request(@cerbos_service, :check_resources, request)
+        response = perform_request(@cerbos_service, :check_resources, request, grpc_metadata)
 
         Output::CheckResources.from_protobuf(response).tap do |output|
           handle_validation_errors output
@@ -162,6 +176,7 @@ module Cerbos
     # @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.
+    # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
     #
     # @return [Output::PlanResources]
     #
@@ -174,7 +189,7 @@ module Cerbos
     #
     #   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)
+    def plan_resources(principal:, resource:, action:, aux_data: nil, include_metadata: false, request_id: SecureRandom.uuid, grpc_metadata: {})
       handle_errors do
         request = Protobuf::Cerbos::Request::V1::PlanResourcesRequest.new(
           principal: Input.coerce_required(principal, Input::Principal).to_protobuf,
@@ -185,7 +200,7 @@ module Cerbos
           request_id: request_id
         )
 
-        response = perform_request(@cerbos_service, :plan_resources, request)
+        response = perform_request(@cerbos_service, :plan_resources, request, grpc_metadata)
 
         Output::PlanResources.from_protobuf(response).tap do |output|
           handle_validation_errors output
@@ -195,12 +210,14 @@ module Cerbos
 
     # Retrieve information about the Cerbos PDP server.
     #
+    # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
+    #
     # @return [Output::ServerInfo]
-    def server_info
+    def server_info(grpc_metadata: {})
       handle_errors do
         request = Protobuf::Cerbos::Request::V1::ServerInfoRequest.new
 
-        response = perform_request(@cerbos_service, :server_info, request)
+        response = perform_request(@cerbos_service, :server_info, request, grpc_metadata)
 
         Output::ServerInfo.from_protobuf(response)
       end
@@ -231,8 +248,8 @@ module Cerbos
       @on_validation_error.call validation_errors
     end
 
-    def perform_request(service, rpc, request)
-      service.public_send(rpc, request)
+    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

@@ -12,7 +12,7 @@ module Cerbos
 
       # @private
       def initialize(validation_errors)
-        super "Input failed schema validation"
+        super("Input failed schema validation")
 
         @validation_errors = validation_errors
       end
@@ -48,7 +48,7 @@ module Cerbos
 
       # @private
       def initialize(code:, details:, metadata: {})
-        super "gRPC error #{code}: #{details}"
+        super("gRPC error #{code}: #{details}")
 
         @code = code
         @details = details

data/lib/cerbos/version.rb

@@ -2,5 +2,5 @@
 
 module Cerbos
   # Current version of the `cerbos` gem.
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cerbos
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Cerbos
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-07 00:00:00.000000000 Z
+date: 2024-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grpc
@@ -77,7 +77,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/cerbos/cerbos-sdk-ruby/issues
   changelog_uri: https://github.com/cerbos/cerbos-sdk-ruby/blob/main/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/cerbos/0.7.0
+  documentation_uri: https://www.rubydoc.info/gems/cerbos/0.8.0
   homepage_uri: https://github.com/cerbos/cerbos-sdk-ruby
   source_code_uri: https://github.com/cerbos/cerbos-sdk-ruby
   rubygems_mfa_required: 'true'
@@ -96,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.13
+rubygems_version: 3.5.4
 signing_key:
 specification_version: 4
 summary: Client library for authorization via Cerbos