Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <memory>
       4             : 
       5             : #include "envoy/common/exception.h"
       6             : #include "envoy/common/pure.h"
       7             : #include "envoy/config/eds_resources_cache.h"
       8             : #include "envoy/config/subscription.h"
       9             : #include "envoy/stats/stats_macros.h"
      10             : 
      11             : #include "source/common/common/cleanup.h"
      12             : #include "source/common/protobuf/protobuf.h"
      13             : 
      14             : namespace Envoy {
      15             : namespace Config {
      16             : 
      17             : using ScopedResume = std::unique_ptr<Cleanup>;
      18             : /**
      19             :  * All control plane related stats. @see stats_macros.h
      20             :  */
      21             : #define ALL_CONTROL_PLANE_STATS(COUNTER, GAUGE, TEXT_READOUT)                                      \
      22          29 :   COUNTER(rate_limit_enforced)                                                                     \
      23          29 :   GAUGE(connected_state, NeverImport)                                                              \
      24          29 :   GAUGE(pending_requests, Accumulate)                                                              \
      25          29 :   TEXT_READOUT(identifier)
      26             : 
      27             : /**
      28             :  * Struct definition for all control plane stats. @see stats_macros.h
      29             :  */
      30             : struct ControlPlaneStats {
      31             :   ALL_CONTROL_PLANE_STATS(GENERATE_COUNTER_STRUCT, GENERATE_GAUGE_STRUCT,
      32             :                           GENERATE_TEXT_READOUT_STRUCT)
      33             : };
      34             : 
      35             : /**
      36             :  * Handle on a muxed gRPC subscription. The subscription is canceled on destruction.
      37             :  */
      38             : class GrpcMuxWatch {
      39             : public:
      40         135 :   virtual ~GrpcMuxWatch() = default;
      41             : 
      42             :   /**
      43             :    * Updates the set of resources that the watch is interested in.
      44             :    * @param resources set of resource names to watch for
      45             :    */
      46             :   virtual void update(const absl::flat_hash_set<std::string>& resources) PURE;
      47             : };
      48             : 
      49             : using GrpcMuxWatchPtr = std::unique_ptr<GrpcMuxWatch>;
      50             : 
      51             : /**
      52             :  * Manage one or more gRPC subscriptions on a single stream to management server. This can be used
      53             :  * for a single xDS API, e.g. EDS, or to combined multiple xDS APIs for ADS.
      54             :  */
      55             : class GrpcMux {
      56             : public:
      57         129 :   virtual ~GrpcMux() = default;
      58             : 
      59             :   /**
      60             :    * Initiate stream with management server.
      61             :    */
      62             :   virtual void start() PURE;
      63             : 
      64             :   /**
      65             :    * Pause discovery requests for a given API type. This is useful when we're processing an update
      66             :    * for LDS or CDS and don't want a flood of updates for RDS or EDS respectively. Discovery
      67             :    * requests may later be resumed with resume().
      68             :    * @param type_url type URL corresponding to xDS API, e.g.
      69             :    * type.googleapis.com/envoy.api.v2.Cluster.
      70             :    *
      71             :    * @return a ScopedResume object, which when destructed, resumes the paused discovery requests.
      72             :    * A discovery request will be sent if one would have been sent during the pause.
      73             :    */
      74             :   ABSL_MUST_USE_RESULT virtual ScopedResume pause(const std::string& type_url) PURE;
      75             : 
      76             :   /**
      77             :    * Pause discovery requests for given API types. This is useful when we're processing an update
      78             :    * for LDS or CDS and don't want a flood of updates for RDS or EDS respectively. Discovery
      79             :    * requests may later be resumed with resume().
      80             :    * @param type_urls type URLs corresponding to xDS API, e.g.
      81             :    * type.googleapis.com/envoy.api.v2.Cluster.
      82             :    *
      83             :    * @return a ScopedResume object, which when destructed, resumes the paused discovery requests.
      84             :    * A discovery request will be sent if one would have been sent during the pause.
      85             :    */
      86             :   ABSL_MUST_USE_RESULT virtual ScopedResume pause(const std::vector<std::string> type_urls) PURE;
      87             : 
      88             :   /**
      89             :    * Start a configuration subscription asynchronously for some API type and resources.
      90             :    * @param type_url type URL corresponding to xDS API, e.g.
      91             :    * type.googleapis.com/envoy.api.v2.Cluster.
      92             :    * @param resources set of resource names to watch for. If this is empty, then all
      93             :    *                  resources for type_url will result in callbacks.
      94             :    * @param callbacks the callbacks to be notified of configuration updates. These must be valid
      95             :    *                  until GrpcMuxWatch is destroyed.
      96             :    * @param resource_decoder how incoming opaque resource objects are to be decoded.
      97             :    * @param options subscription options.
      98             :    * @return GrpcMuxWatchPtr a handle to cancel the subscription with. E.g. when a cluster goes
      99             :    * away, its EDS updates should be cancelled by destroying the GrpcMuxWatchPtr.
     100             :    */
     101             :   virtual GrpcMuxWatchPtr addWatch(const std::string& type_url,
     102             :                                    const absl::flat_hash_set<std::string>& resources,
     103             :                                    SubscriptionCallbacks& callbacks,
     104             :                                    OpaqueResourceDecoderSharedPtr resource_decoder,
     105             :                                    const SubscriptionOptions& options) PURE;
     106             : 
     107             :   virtual void requestOnDemandUpdate(const std::string& type_url,
     108             :                                      const absl::flat_hash_set<std::string>& for_update) PURE;
     109             : 
     110             :   /**
     111             :    * Returns an EdsResourcesCache for this GrpcMux if there is one.
     112             :    * @return EdsResourcesCacheOptRef optional eds resources cache for the gRPC-mux.
     113             :    */
     114             :   virtual EdsResourcesCacheOptRef edsResourcesCache() PURE;
     115             : };
     116             : 
     117             : using GrpcMuxPtr = std::unique_ptr<GrpcMux>;
     118             : using GrpcMuxSharedPtr = std::shared_ptr<GrpcMux>;
     119             : 
     120             : template <class ResponseProto> using ResponseProtoPtr = std::unique_ptr<ResponseProto>;
     121             : /**
     122             :  * A grouping of callbacks that a GrpcMux should provide to its GrpcStream.
     123             :  */
     124             : template <class ResponseProto> class GrpcStreamCallbacks {
     125             : public:
     126         129 :   virtual ~GrpcStreamCallbacks() = default;
     127             : 
     128             :   /**
     129             :    * For the GrpcStream to prompt the context to take appropriate action in response to the
     130             :    * gRPC stream having been successfully established.
     131             :    */
     132             :   virtual void onStreamEstablished() PURE;
     133             : 
     134             :   /**
     135             :    * For the GrpcStream to prompt the context to take appropriate action in response to
     136             :    * failure to establish the gRPC stream.
     137             :    */
     138             :   virtual void onEstablishmentFailure() PURE;
     139             : 
     140             :   /**
     141             :    * For the GrpcStream to pass received protos to the context.
     142             :    */
     143             :   virtual void onDiscoveryResponse(ResponseProtoPtr<ResponseProto>&& message,
     144             :                                    ControlPlaneStats& control_plane_stats) PURE;
     145             : 
     146             :   /**
     147             :    * For the GrpcStream to call when its rate limiting logic allows more requests to be sent.
     148             :    */
     149             :   virtual void onWriteable() PURE;
     150             : };
     151             : 
     152             : } // namespace Config
     153             : } // namespace Envoy