Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include "envoy/config/typed_config.h"
       4             : #include "envoy/singleton/manager.h"
       5             : #include "envoy/upstream/types.h"
       6             : #include "envoy/upstream/upstream.h"
       7             : 
       8             : namespace Envoy {
       9             : namespace Upstream {
      10             : 
      11             : /**
      12             :  * Used to optionally modify the PriorityLoad when selecting a priority for
      13             :  * a retry attempt.
      14             :  *
      15             :  * Each RetryPriority will live throughout the lifetime of a request and updated
      16             :  * with attempted hosts through onHostAttempted.
      17             :  */
      18             : class RetryPriority {
      19             : public:
      20           0 :   virtual ~RetryPriority() = default;
      21             : 
      22             :   /**
      23             :    * Function that maps a HostDescription to it's effective priority level in a cluster.
      24             :    * For most cluster types, the mapping is simply `return host.priority()`, but some
      25             :    * cluster types require more complex mapping.
      26             :    * @return either the effective priority, or absl::nullopt if the mapping cannot be determined,
      27             :    *         which can happen if the host has been removed from the configurations since it was
      28             :    *         used.
      29             :    */
      30             :   using PriorityMappingFunc =
      31             :       std::function<absl::optional<uint32_t>(const Upstream::HostDescription&)>;
      32             : 
      33           0 :   static absl::optional<uint32_t> defaultPriorityMapping(const Upstream::HostDescription& host) {
      34           0 :     return host.priority();
      35           0 :   }
      36             : 
      37             :   /**
      38             :    * Determines what PriorityLoad to use.
      39             :    *
      40             :    * @param priority_set current priority set of cluster.
      41             :    * @param original_priority_load the unmodified HealthAndDegradedLoad.
      42             :    * @param priority_mapping_func a callback to get the priority of a host that has
      43             :    *        been attempted. This function may only be called on hosts that were
      44             :    *        passed to calls to `onHostAttempted()` on this object.
      45             :    * @return HealthAndDegradedLoad load that should be used for the next retry. Return
      46             :    * original_priority_load if the original load should be used. a pointer to original_priority,
      47             :    * original_degraded_priority if no changes should be made.
      48             :    */
      49             :   virtual const HealthyAndDegradedLoad&
      50             :   determinePriorityLoad(const PrioritySet& priority_set,
      51             :                         const HealthyAndDegradedLoad& original_priority_load,
      52             :                         const PriorityMappingFunc& priority_mapping_func) PURE;
      53             : 
      54             :   /**
      55             :    * Called after a host has been attempted but before host selection for the next attempt has
      56             :    * begun.
      57             :    *
      58             :    * @param attempted_host the host that was previously attempted.
      59             :    */
      60             :   virtual void onHostAttempted(HostDescriptionConstSharedPtr attempted_host) PURE;
      61             : };
      62             : 
      63             : using RetryPrioritySharedPtr = std::shared_ptr<RetryPriority>;
      64             : 
      65             : /**
      66             :  * Used to decide whether a selected host should be rejected during retries. Host selection will be
      67             :  * reattempted until either the host predicate accepts the host or a configured max number of
      68             :  * attempts is reached.
      69             :  *
      70             :  * Each RetryHostPredicate will live throughout the lifetime of a request and updated
      71             :  * with attempted hosts through onHostAttempted.
      72             :  */
      73             : class RetryHostPredicate {
      74             : public:
      75           0 :   virtual ~RetryHostPredicate() = default;
      76             : 
      77             :   /**
      78             :    * Determines whether a host should be rejected during host selection.
      79             :    *
      80             :    * @param candidate_host the host to either reject or accept.
      81             :    * @return whether the host should be rejected and host selection reattempted.
      82             :    */
      83             :   virtual bool shouldSelectAnotherHost(const Host& candidate_host) PURE;
      84             : 
      85             :   /**
      86             :    * Called after a host has been attempted but before host selection for the next attempt has
      87             :    * begun.
      88             :    *
      89             :    * @param attempted_host the host that was previously attempted.
      90             :    */
      91             :   virtual void onHostAttempted(HostDescriptionConstSharedPtr attempted_host) PURE;
      92             : };
      93             : 
      94             : using RetryHostPredicateSharedPtr = std::shared_ptr<RetryHostPredicate>;
      95             : 
      96             : /**
      97             :  * A predicate that is applied prior to retrying a request. Each predicate can customize request
      98             :  * behavior prior to the request being retried.
      99             :  */
     100             : class RetryOptionsPredicate {
     101             : public:
     102             :   struct UpdateOptionsParameters {
     103             :     // Stream info for the previous request attempt that is about to be retried.
     104             :     StreamInfo::StreamInfo& retriable_request_stream_info_;
     105             :     // The current upstream socket options that were used for connection pool selection on the
     106             :     // previous attempt, or the result of an updated set of options from a previously run
     107             :     // retry options predicate.
     108             :     Network::Socket::OptionsSharedPtr current_upstream_socket_options_;
     109             :   };
     110             : 
     111             :   struct UpdateOptionsReturn {
     112             :     // New upstream socket options to apply to the next request attempt. If changed, will affect
     113             :     // connection pool selection similar to that which was done for the initial request.
     114             :     absl::optional<Network::Socket::OptionsSharedPtr> new_upstream_socket_options_;
     115             :   };
     116             : 
     117             :   virtual ~RetryOptionsPredicate() = default;
     118             : 
     119             :   /**
     120             :    * Update request options.
     121             :    * @param parameters supplies the update parameters.
     122             :    * @return the new options to apply. Each option is wrapped in an optional and is only applied
     123             :    *         if valid.
     124             :    */
     125             :   virtual UpdateOptionsReturn updateOptions(const UpdateOptionsParameters& parameters) const PURE;
     126             : };
     127             : 
     128             : using RetryOptionsPredicateConstSharedPtr = std::shared_ptr<const RetryOptionsPredicate>;
     129             : 
     130             : /**
     131             :  * Context for all retry extensions.
     132             :  */
     133             : class RetryExtensionFactoryContext {
     134             : public:
     135        1684 :   virtual ~RetryExtensionFactoryContext() = default;
     136             : 
     137             :   /**
     138             :    * @return Singleton::Manager& the server-wide singleton manager.
     139             :    */
     140             :   virtual Singleton::Manager& singletonManager() PURE;
     141             : };
     142             : 
     143             : /**
     144             :  * Factory for RetryPriority.
     145             :  */
     146             : class RetryPriorityFactory : public Config::TypedFactory {
     147             : public:
     148             :   virtual RetryPrioritySharedPtr
     149             :   createRetryPriority(const Protobuf::Message& config,
     150             :                       ProtobufMessage::ValidationVisitor& validation_visitor,
     151             :                       uint32_t retry_count) PURE;
     152             : 
     153           4 :   std::string category() const override { return "envoy.retry_priorities"; }
     154             : };
     155             : 
     156             : /**
     157             :  * Factory for RetryHostPredicate.
     158             :  */
     159             : class RetryHostPredicateFactory : public Config::TypedFactory {
     160             : public:
     161             :   virtual RetryHostPredicateSharedPtr createHostPredicate(const Protobuf::Message& config,
     162             :                                                           uint32_t retry_count) PURE;
     163             : 
     164           8 :   std::string category() const override { return "envoy.retry_host_predicates"; }
     165             : };
     166             : 
     167             : /**
     168             :  * Factory for RetryOptionsPredicate.
     169             :  */
     170             : class RetryOptionsPredicateFactory : public Config::TypedFactory {
     171             : public:
     172             :   virtual RetryOptionsPredicateConstSharedPtr
     173             :   createOptionsPredicate(const Protobuf::Message& config,
     174             :                          RetryExtensionFactoryContext& context) PURE;
     175             : 
     176           0 :   std::string category() const override { return "envoy.retry_options_predicates"; }
     177             : };
     178             : 
     179             : } // namespace Upstream
     180             : } // namespace Envoy