Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include "envoy/api/api.h"
       4             : #include "envoy/common/exception.h"
       5             : #include "envoy/common/optref.h"
       6             : #include "envoy/common/pure.h"
       7             : #include "envoy/config/subscription.h"
       8             : #include "envoy/config/typed_config.h"
       9             : #include "envoy/protobuf/message_validator.h"
      10             : #include "envoy/service/discovery/v3/discovery.pb.h"
      11             : 
      12             : #include "absl/container/flat_hash_set.h"
      13             : #include "absl/types/optional.h"
      14             : 
      15             : namespace Envoy {
      16             : namespace Config {
      17             : 
      18             : /*
      19             :  * An abstract class that represents an xDS source. The toKey() function provides a unique
      20             :  * identifier for the source for a group of xDS resources in a DiscoveryResponse.
      21             :  */
      22             : class XdsSourceId {
      23             : public:
      24           0 :   virtual ~XdsSourceId() = default;
      25             : 
      26             :   /**
      27             :    * Returns a unique string representation of the source. The string can be used as an identifier
      28             :    * for the source (e.g. as a key in a hash map).
      29             :    * @return string representation of the source.
      30             :    */
      31             :   virtual std::string toKey() const PURE;
      32             : };
      33             : 
      34             : /**
      35             :  * An interface for hooking into xDS resource fetch and update events.
      36             :  * Currently, this interface only supports the SotW (state-of-the-world) xDS protocol.
      37             :  *
      38             :  * Instances of this interface get invoked on the main Envoy thread. Thus, it is important for
      39             :  * implementations of this interface to not execute any blocking operations on the same thread.
      40             :  * Any blocking operations (e.g. flushing config to disk) should be handed off to a separate thread
      41             :  * so we don't block the main thread.
      42             :  */
      43             : class XdsResourcesDelegate {
      44             : public:
      45             :   virtual ~XdsResourcesDelegate() = default;
      46             : 
      47             :   /**
      48             :    * Returns a list of xDS resources for the given source and names. The implementation is not
      49             :    * required to return all (or any) of the requested resources, but the resources it does return
      50             :    * are required to be in the set of requested resources. An empty resource name set will return
      51             :    * all known resources from the given xDS source (i.e. the "wildcard").
      52             :    *
      53             :    * This function is intended to only be called on xDS fetch startup, and allows the
      54             :    * implementation to return a set of resources to be loaded and used by the Envoy instance
      55             :    * (e.g. persisted resources in local storage).
      56             :    *
      57             :    * @param source_id The xDS source for the requested resources.
      58             :    * @param resource_names The names of the requested resources.
      59             :    * @return A list of xDS resources for the given source.
      60             :    */
      61             :   virtual std::vector<envoy::service::discovery::v3::Resource>
      62             :   getResources(const XdsSourceId& source_id,
      63             :                const absl::flat_hash_set<std::string>& resource_names) const PURE;
      64             : 
      65             :   /**
      66             :    * Invoked when SotW xDS configuration updates have been received from an xDS authority, have been
      67             :    * applied on the Envoy instance, and are about to be ACK'ed.
      68             :    *
      69             :    * @param source_id The xDS source for the requested resources.
      70             :    * @param resources The resources for the given source received on the DiscoveryResponse.
      71             :    */
      72             :   virtual void onConfigUpdated(const XdsSourceId& source_id,
      73             :                                const std::vector<DecodedResourceRef>& resources) PURE;
      74             : 
      75             :   /**
      76             :    * Invoked when loading a resource obtained from the getResources() call resulted in a failure.
      77             :    * This would typically happen when there is a parsing or validation error on the xDS resource
      78             :    * protocol buffer.
      79             :    *
      80             :    * @param source_id The xDS source for the requested resource.
      81             :    * @param resource_name The name of the resource.
      82             :    * @param exception The exception that occurred, if any.
      83             :    */
      84             :   virtual void onResourceLoadFailed(const XdsSourceId& source_id, const std::string& resource_name,
      85             :                                     const absl::optional<EnvoyException>& exception) PURE;
      86             : };
      87             : 
      88             : using XdsResourcesDelegatePtr = std::unique_ptr<XdsResourcesDelegate>;
      89             : using XdsResourcesDelegateOptRef = OptRef<XdsResourcesDelegate>;
      90             : 
      91             : /**
      92             :  * A factory abstract class for creating instances of XdsResourcesDelegate.
      93             :  */
      94             : class XdsResourcesDelegateFactory : public Config::TypedFactory {
      95             : public:
      96             :   ~XdsResourcesDelegateFactory() override = default;
      97             : 
      98             :   /**
      99             :    * Creates a XdsResourcesDelegate using the given configuration.
     100             :    * @param config Configuration of the XdsResourcesDelegate to create.
     101             :    * @param validation_visitor Validates the configuration.
     102             :    * @param api The APIs that can be used by the delegate.
     103             :    * @param dispatcher The dispatcher for the thread.
     104             :    * @return The created XdsResourcesDelegate instance
     105             :    */
     106             :   virtual XdsResourcesDelegatePtr
     107             :   createXdsResourcesDelegate(const ProtobufWkt::Any& config,
     108             :                              ProtobufMessage::ValidationVisitor& validation_visitor, Api::Api& api,
     109             :                              Event::Dispatcher& dispatcher) PURE;
     110             : 
     111           0 :   std::string category() const override { return "envoy.xds_delegates"; }
     112             : };
     113             : 
     114             : } // namespace Config
     115             : } // namespace Envoy