RUBY-3628 Deprecate hedged reads option

Hedged reads are deprecated in MongoDB Server 8.0 and will be removed
in a future version. Per the server-selection spec, drivers without
static deprecation annotations must emit a runtime warning when the
hedge parameter is specified.

- Mark the :hedge option, the hedge attr_reader, hedge_allowed? methods,
  and the NO_HEDGE_SUPPORT error message as @deprecated in YARD docs.
- Emit a one-time Mongo::Deprecations warning when a server selector is
  constructed with a non-nil :hedge option.

Author: comandeo-mongo

lib/mongo/error/invalid_server_preference.rb

@@ -33,6 +33,9 @@ class InvalidServerPreference < Error
       # Error message when hedge is specified for a read preference that does not support it.
       #
       # @api private
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       NO_HEDGE_SUPPORT = 'The hedge option cannot be set for this read preference'
 
       # Error message for when the max staleness is not at least twice the heartbeat frequency.

lib/mongo/server_selector/base.rb

@@ -37,6 +37,8 @@ class Base
       #   reads on the server. Hedged reads are not enabled by default. When
       #   specifying this option, it must be in the format: { enabled: true },
       #   where the value of the :enabled key is a boolean value.
+      #   @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #     be removed in a future version.
       #
       # @raise [ Error::InvalidServerPreference ] If tag sets are specified
       #   but not allowed.
@@ -51,6 +53,14 @@ def initialize(options = nil)
         @hedge = options[:hedge]
 
         validate!
+
+        return if @hedge.nil?
+
+        Mongo::Deprecations.warn(
+          :hedge_read_preference,
+          'The hedge read preference option is deprecated. Hedged reads are ' \
+          'deprecated in MongoDB Server 8.0 and will be removed in a future version.'
+        )
       end
 
       # @return [ Hash ] options The options.
@@ -67,6 +77,9 @@ def initialize(options = nil)
 
       # @return [ Hash | nil ] hedge The document specifying whether to enable
       #   hedged reads.
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       attr_reader :hedge
 
       # Get the timeout for server selection.

lib/mongo/server_selector/nearest.rb

@@ -59,6 +59,9 @@ def tags_allowed?
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end

lib/mongo/server_selector/primary.rb

@@ -59,6 +59,9 @@ def tags_allowed?
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ false ] false
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         false
       end

lib/mongo/server_selector/primary_preferred.rb

@@ -59,6 +59,9 @@ def tags_allowed?
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end

lib/mongo/server_selector/secondary.rb

@@ -59,6 +59,9 @@ def tags_allowed?
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end

lib/mongo/server_selector/secondary_preferred.rb

@@ -59,6 +59,9 @@ def tags_allowed?
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end