[JAY-724] Add cluster health interface

CHANGELOG.md

@@ -8,6 +8,12 @@ Please mark backwards incompatible changes with an exclamation mark at the start
 
 ## [Unreleased]
 
+### Added
+- The `#cluster` method to `JayAPI::Elasticsearch::Client`. The method returns
+  an instance of `JayAPI::Elasticsearch::Cluster`.
+- The `Elasticsearch::Cluster` class. The class gives the user access to
+  cluster-level endpoints, currently including cluster health.
+
 ## [29.6.0] - 2026-03-16
 
 ### Deprecated

documentation/source/user_guidelines/elasticsearch/cluster.rst

@@ -0,0 +1,23 @@
+Cluster
+=======
+
+The ``Cluster`` class gives you access to cluster-level endpoints in
+Elasticsearch. The class can be accessed by calling the ``#cluster`` method on
+an instance of the ``Elasticsearch::Client`` class. For example:
+
+.. code-block:: ruby
+
+   require 'jay_api/elasticsearch/client_factory'
+
+   client_factory = JayAPI::Elasticsearch::ClientFactory.new(...)
+   client = client_factory.create
+
+   cluster = client.cluster
+
+The ``Cluster`` class has the following method:
+
+#health
+-------
+
+This method retrieves the cluster health data from the ``/_cluster/health``
+endpoint and returns the response hash from Elasticsearch.

lib/jay_api/elasticsearch.rb

@@ -4,6 +4,7 @@
 require_relative 'elasticsearch/batch_counter'
 require_relative 'elasticsearch/client'
 require_relative 'elasticsearch/client_factory'
+require_relative 'elasticsearch/cluster'
 require_relative 'elasticsearch/errors'
 require_relative 'elasticsearch/index'
 require_relative 'elasticsearch/indexes'

lib/jay_api/elasticsearch/client.rb

@@ -5,6 +5,7 @@
 require 'forwardable'
 
 require_relative 'mixins/retriable_requests'
+require_relative 'cluster'
 require_relative 'stats'
 require_relative 'tasks'
 
@@ -89,6 +90,12 @@ def stats
       def tasks
         @tasks ||= ::JayAPI::Elasticsearch::Tasks.new(client: self)
       end
+
+      # @return [JayAPI::Elasticsearch::Cluster] An instance of the +Cluster+
+      #   class, which gives the caller access to cluster-related endpoints.
+      def cluster
+        @cluster ||= ::JayAPI::Elasticsearch::Cluster.new(transport_client)
+      end
     end
   end
 end

lib/jay_api/elasticsearch/cluster.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative 'mixins/retriable_requests'
+
+module JayAPI
+  module Elasticsearch
+    # Represents the Elasticsearch cluster and provides access to
+    # cluster-level APIs.
+    class Cluster
+      extend Forwardable
+
+      def_delegator :cluster_client, :health
+
+      attr_reader :transport_client
+
+      # @param [Elasticsearch::Transport::Client] transport_client The transport
+      #   client to use to make requests to the cluster.
+      def initialize(transport_client)
+        @transport_client = transport_client
+      end
+
+      private
+
+      # @return [Elasticsearch::API::Cluster::ClusterClient] The client used to
+      #   access cluster-related information.
+      def cluster_client
+        @cluster_client ||= transport_client.cluster
+      end
+    end
+  end
+end

spec/integration/jay_api/elasticsearch/client_spec.rb

@@ -341,4 +341,27 @@
       expect(method_call).to be(tasks)
     end
   end
+
+  describe '#cluster' do
+    subject(:method_call) { client.cluster }
+
+    let(:cluster) do
+      instance_double(
+        JayAPI::Elasticsearch::Cluster
+      )
+    end
+
+    before do
+      allow(JayAPI::Elasticsearch::Cluster).to receive(:new).and_return(cluster)
+    end
+
+    it 'initializes an instance of JayAPI::Elasticsearch::Cluster and passes the transport client to it' do
+      expect(JayAPI::Elasticsearch::Cluster).to receive(:new).with(transport_client)
+      method_call
+    end
+
+    it 'returns the JayAPI::Elasticsearch::Cluster instance' do
+      expect(method_call).to be(cluster)
+    end
+  end
 end

spec/jay_api/elasticsearch/cluster_spec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'jay_api/elasticsearch/cluster'
+
+RSpec.describe JayAPI::Elasticsearch::Cluster do
+  subject(:cluster) { described_class.new(transport_client) }
+
+  let(:cluster_client) do
+    instance_double(
+      Elasticsearch::API::Cluster::ClusterClient,
+      health: transport_response
+    )
+  end
+
+  let(:transport_client) do
+    instance_double(
+      Elasticsearch::Transport::Client,
+      cluster: cluster_client
+    )
+  end
+
+  describe '#health' do
+    subject(:method_call) { cluster.health }
+
+    let(:transport_response) do
+      {
+        'cluster_name' => 'xyz01_cluster',
+        'status' => 'green',
+        'timed_out' => false,
+        'number_of_nodes' => 7,
+        'number_of_data_nodes' => 4,
+        'discovered_master' => true,
+        'active_primary_shards' => 646,
+        'active_shards' => 2182,
+        'relocating_shards' => 0,
+        'initializing_shards' => 0,
+        'unassigned_shards' => 0,
+        'delayed_unassigned_shards' => 0,
+        'number_of_pending_tasks' => 0,
+        'number_of_in_flight_fetch' => 0,
+        'task_max_waiting_in_queue_millis' => 0,
+        'active_shards_percent_as_number' => 100.0
+      }
+    end
+
+    it 'gets the ClusterClient from the given TransportClient' do
+      expect(transport_client).to receive(:cluster)
+      method_call
+    end
+
+    it 'forwards the call to the Elasticsearch cluster client' do
+      expect(cluster_client).to receive(:health)
+      method_call
+    end
+
+    it 'directly returns the response' do
+      expect(method_call).to be(transport_response)
+    end
+  end
+end