feat: Support health checks

Signed-off-by: Andrew Haines <haines@cerbos.dev>

CHANGELOG.md

@@ -1,6 +1,8 @@
 ## [Unreleased]
 
-No notable changes.
+### Added
+
+- `Cerbos::Client#check_health` method to perform health checks on the policy decision point server ([#221](https://github.com/cerbos/cerbos-sdk-ruby/pull/221))
 
 ## [0.9.1] - 2024-07-15
 

Gemfile.lock

@@ -116,4 +116,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.6.2
+   2.6.3

buf.gen.yaml

@@ -5,6 +5,10 @@ inputs:
     types:
       - cerbos.svc.v1.CerbosService
 
+  - module: buf.build/grpc/grpc
+    types:
+      - grpc.health.v1.Health
+
 plugins:
   - remote: buf.build/grpc/ruby
     out: .

lib/cerbos/client.rb

@@ -59,6 +59,13 @@ def initialize(target, tls:, grpc_channel_args: {}, grpc_metadata: {}, on_valida
           channel_args: channel_args,
           timeout: timeout
         )
+
+        @health_service = Protobuf::Grpc::Health::V1::Health::Stub.new(
+          target,
+          credentials,
+          channel_args: channel_args,
+          timeout: timeout
+        )
       end
     end
 
@@ -90,6 +97,33 @@ def allow?(principal:, resource:, action:, aux_data: nil, request_id: SecureRand
       ).allow?(action)
     end
 
+    # Check the health of a service provided by the policy decision point server.
+    #
+    # @param service ["cerbos.svc.v1.CerbosService", "cerbos.svc.v1.CerbosAdminService"] the service to check.
+    # @param grpc_metadata [Hash{String, Symbol => String, Array<String>}] gRPC metadata (a.k.a. HTTP headers) to add to the request.
+    #
+    # @return [Output::HealthCheck]
+    #
+    # @example
+    #   cerbos_api = client.check_health
+    #   cerbos_api.status # => :SERVING
+    #
+    #   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
+        request = Protobuf::Grpc::Health::V1::HealthCheckRequest.new(service: service)
+
+        response = perform_request(@health_service, :check, request, grpc_metadata)
+
+        Output::HealthCheck.from_protobuf(response)
+      end
+    rescue Error::NotFound
+      return Output::HealthCheck.new(status: :DISABLED) if service == "cerbos.svc.v1.CerbosAdminService"
+
+      raise
+    end
+
     # Check a principal's permissions on a resource.
     #
     # @param principal [Input::Principal, Hash] the principal to check.

lib/cerbos/error.rb

@@ -84,6 +84,13 @@ def initialize(code: GRPC::Core::StatusCodes::INVALID_ARGUMENT, **args)
       end
     end
 
+    # The gRPC operation was rejected because 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.
     class ResourceExhausted < NotOK
       def initialize(code: GRPC::Core::StatusCodes::RESOURCE_EXHAUSTED, **args)
@@ -117,6 +124,7 @@ def initialize(code: GRPC::Core::StatusCodes::UNIMPLEMENTED, **args)
       GRPC::DeadlineExceeded => DeadlineExceeded,
       GRPC::Internal => InternalError,
       GRPC::InvalidArgument => InvalidArgument,
+      GRPC::NotFound => NotFound,
       GRPC::ResourceExhausted => ResourceExhausted,
       GRPC::Unauthenticated => Unauthenticated,
       GRPC::Unavailable => Unavailable,

lib/cerbos/output.rb

@@ -34,5 +34,6 @@ def hash
 
 require_relative "output/validation_error"
 require_relative "output/check_resources"
+require_relative "output/health_check"
 require_relative "output/plan_resources"
 require_relative "output/server_info"

lib/cerbos/output/health_check.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Output
+    # Health of a service provided by the Cerbos policy decision point server.
+    HealthCheck = Output.new_class(:status) do
+      # @!attribute [r] status
+      #   The status of the service.
+      #
+      #   @return [:SERVING] if the server is up and serving requests for the specified service.
+      #   @return [:NOT_SERVING] if the server is shutting down.
+      #   @return [:DISABLED] if the service is disabled in the server configuration.
+
+      def self.from_protobuf(health_check)
+        new(status: health_check.status)
+      end
+    end
+  end
+end

lib/cerbos/protobuf.rb

@@ -7,3 +7,4 @@ module Protobuf
 end
 
 require_relative "protobuf/cerbos/svc/v1/svc_services_pb"
+require_relative "protobuf/grpc/health/v1/health_services_pb"