Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include "envoy/common/optref.h"
       4             : #include "envoy/common/pure.h"
       5             : #include "envoy/config/endpoint/v3/endpoint.pb.h"
       6             : 
       7             : #include "absl/strings/string_view.h"
       8             : 
       9             : namespace Envoy {
      10             : namespace Config {
      11             : 
      12             : // An interface for cached resource removed callback.
      13             : class EdsResourceRemovalCallback {
      14             : public:
      15          28 :   virtual ~EdsResourceRemovalCallback() = default;
      16             : 
      17             :   // Invoked when a cached resource is removed from the cache.
      18             :   virtual void onCachedResourceRemoved(absl::string_view resource_name) PURE;
      19             : };
      20             : 
      21             : // Represents an xDS resources cache for EDS resources, and currently supports
      22             : // a single config-source (ADS). The motivation is that clusters that are
      23             : // updated (not added) during a CDS response will be able to use the current EDS
      24             : // configuration, thus avoiding the need of the xDS server to send an additional
      25             : // EDS response that is identical to what was already sent.
      26             : // However, using the cached EDS config is not always desired, for example when
      27             : // the cluster changes from non-TLS to TLS (see discussion in
      28             : // https://github.com/envoyproxy/envoy/issues/5168). Thus, this cache allows
      29             : // the EDS subscription to decide whether to use the cache or not.
      30             : //
      31             : // This cache will be instantiated once and owned by the ADS Mux, and passed to
      32             : // the EDS subscriptions.
      33             : //
      34             : // Resources lifetime in the cache is determined by the gRPC mux that adds/updates a
      35             : // resource when it receives its contents, and removes a resource when there is
      36             : // no longer interest in that resource.
      37             : // An EDS subscription may fetch a resource from the cache, and optionally
      38             : // install a callback to be triggered if the resource is removed from the cache.
      39             : // In addition, a resource in the cache may have an expiration timer if
      40             : // "endpoint_stale_after" (TTL) is set for that resource. Once the timer
      41             : // expires, the callbacks will be triggered to remove the resource.
      42             : class EdsResourcesCache {
      43             : public:
      44           0 :   virtual ~EdsResourcesCache() = default;
      45             : 
      46             :   /**
      47             :    * Adds or updates a given resource name with its resource.
      48             :    * Any callback that was previously assigned to the resource will be removed
      49             :    * without any notification.
      50             :    * @param resource_name the name of the resource to add/update.
      51             :    * @param resource the contents of the resource.
      52             :    */
      53             :   virtual void setResource(absl::string_view resource_name,
      54             :                            const envoy::config::endpoint::v3::ClusterLoadAssignment& resource) PURE;
      55             : 
      56             :   /**
      57             :    * Removes a resource from the resource cache given the resource name.
      58             :    * The callbacks for the resource will be invoked, notifying that the resource
      59             :    * is removed.
      60             :    * @param resource_name the name of the resource that will be removed from
      61             :    *        the cache.
      62             :    */
      63             :   virtual void removeResource(absl::string_view resource_name) PURE;
      64             : 
      65             :   /**
      66             :    * Retrieves a resource from the cache, and adds the given callback (if any)
      67             :    * to the resource's removal list. if the resource is removed, all callbacks
      68             :    * for that resource will be invoked.
      69             :    * @param resource_name the name of the resource to fetch.
      70             :    * @param removal_cb an optional callback that will be invoked if the resource is removed
      71             :    *        in the future. Note that updating the resource (`setResource()`) will also
      72             :    *        remove the callback. The caller of this function can also call
      73             :    *        `removeCallback()` to explicitly remove the callback. The callback
      74             :    *        is owned by the caller as it is part of the EDS subscription.
      75             :    * @return A reference to the cluster load assignment resource, or nullopt if the
      76             :    *         resource doesn't exist.
      77             :    */
      78             :   virtual OptRef<const envoy::config::endpoint::v3::ClusterLoadAssignment>
      79             :   getResource(absl::string_view resource_name, EdsResourceRemovalCallback* removal_cb) PURE;
      80             : 
      81             :   /**
      82             :    * Removes a callback for a given resource name (if it was previously added).
      83             :    * @param resource_name the name of the resource for which the callback should be removed.
      84             :    * @param removal_cb a pointer to the callback that needs to be removed.
      85             :    */
      86             :   virtual void removeCallback(absl::string_view resource_name,
      87             :                               EdsResourceRemovalCallback* removal_cb) PURE;
      88             : 
      89             :   /**
      90             :    * Sets an expiry timer for the given resource_name after the given ms milliseconds.
      91             :    * Once the timer expires, the callbacks for that resource (if any) will be
      92             :    * @param resource_name the name of the resource for which the timer should be added.
      93             :    * @param ms the number of milliseconds until expiration.
      94             :    */
      95             :   virtual void setExpiryTimer(absl::string_view resource_name, std::chrono::milliseconds ms) PURE;
      96             : 
      97             :   /**
      98             :    * Disables the expiration timer for the given resource_name.
      99             :    * @param resource_name the name of the resource for which the timer should be disabled.
     100             :    */
     101             :   virtual void disableExpiryTimer(absl::string_view resource_name) PURE;
     102             : 
     103             :   /**
     104             :    * Returns the number of items in the cache. Only used in tests.
     105             :    * @return the number of items in the cache.
     106             :    */
     107             :   virtual uint32_t cacheSizeForTest() const PURE;
     108             : };
     109             : 
     110             : using EdsResourcesCachePtr = std::unique_ptr<EdsResourcesCache>;
     111             : using EdsResourcesCacheOptRef = OptRef<EdsResourcesCache>;
     112             : 
     113             : } // namespace Config
     114             : } // namespace Envoy