Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include "envoy/common/pure.h"
       4             : #include "envoy/config/tap/v3/common.pb.h"
       5             : #include "envoy/data/tap/v3/wrapper.pb.h"
       6             : #include "envoy/extensions/filters/http/tap/v3/tap.pb.h"
       7             : #include "envoy/http/header_map.h"
       8             : 
       9             : #include "source/extensions/common/matcher/matcher.h"
      10             : 
      11             : #include "absl/strings/string_view.h"
      12             : 
      13             : namespace Envoy {
      14             : namespace Extensions {
      15             : namespace Common {
      16             : namespace Tap {
      17             : 
      18             : using Matcher = Envoy::Extensions::Common::Matcher::Matcher;
      19             : 
      20             : using TraceWrapperPtr = std::unique_ptr<envoy::data::tap::v3::TraceWrapper>;
      21           0 : inline TraceWrapperPtr makeTraceWrapper() {
      22           0 :   return std::make_unique<envoy::data::tap::v3::TraceWrapper>();
      23           0 : }
      24             : 
      25             : /**
      26             :  * A handle for a per-tap sink. This allows submitting either a single buffered trace, or a series
      27             :  * of trace segments that the sink can aggregate in whatever way it chooses.
      28             :  */
      29             : class PerTapSinkHandle {
      30             : public:
      31           0 :   virtual ~PerTapSinkHandle() = default;
      32             : 
      33             :   /**
      34             :    * Send a trace wrapper to the sink. This may be a fully buffered trace or a segment of a larger
      35             :    * trace depending on the contents of the wrapper.
      36             :    * @param trace supplies the trace to send.
      37             :    * @param format supplies the output format to use.
      38             :    */
      39             :   virtual void submitTrace(TraceWrapperPtr&& trace,
      40             :                            envoy::config::tap::v3::OutputSink::Format format) PURE;
      41             : };
      42             : 
      43             : using PerTapSinkHandlePtr = std::unique_ptr<PerTapSinkHandle>;
      44             : 
      45             : /**
      46             :  * Wraps potentially multiple PerTapSinkHandle instances and any common pre-submit functionality.
      47             :  * Each active tap will have a reference to one of these, which in turn may have references to
      48             :  * one or more PerTapSinkHandle.
      49             :  */
      50             : class PerTapSinkHandleManager {
      51             : public:
      52           0 :   virtual ~PerTapSinkHandleManager() = default;
      53             : 
      54             :   /**
      55             :    * Submit a buffered or streamed trace segment to all managed per-tap sink handles.
      56             :    */
      57             :   virtual void submitTrace(TraceWrapperPtr&& trace) PURE;
      58             : };
      59             : 
      60             : using PerTapSinkHandleManagerPtr = std::unique_ptr<PerTapSinkHandleManager>;
      61             : 
      62             : /**
      63             :  * Sink for sending tap messages.
      64             :  */
      65             : class Sink {
      66             : public:
      67           2 :   virtual ~Sink() = default;
      68             : 
      69             :   /**
      70             :    * Create a per tap sink handle for use in submitting either buffered traces or trace segments.
      71             :    * @param trace_id supplies a locally unique trace ID. Some sinks use this for output generation.
      72             :    * @param type     Indicates the type of Sink specified in request body
      73             :    */
      74             :   virtual PerTapSinkHandlePtr
      75             :   createPerTapSinkHandle(uint64_t trace_id,
      76             :                          envoy::config::tap::v3::OutputSink::OutputSinkTypeCase type) PURE;
      77             : };
      78             : 
      79             : using SinkPtr = std::unique_ptr<Sink>;
      80             : using SinkContext =
      81             :     absl::variant<std::reference_wrapper<Server::Configuration::FactoryContext>,
      82             :                   std::reference_wrapper<Server::Configuration::TransportSocketFactoryContext>>;
      83             : 
      84             : /**
      85             :  * Abstract tap sink factory. Produces a factory that can instantiate SinkPtr objects
      86             :  */
      87             : class TapSinkFactory : public Config::TypedFactory {
      88             : public:
      89             :   ~TapSinkFactory() override = default;
      90           0 :   std::string category() const override { return "envoy.tap.sinks"; }
      91             : 
      92             :   /**
      93             :    * Create a Sink that can be used for writing out data produced by the tap filter.
      94             :    * @param config supplies the protobuf configuration for the sink factory
      95             :    * @param cluster_manager is a ClusterManager from the HTTP/transport socket context
      96             :    */
      97             :   virtual SinkPtr createSinkPtr(const Protobuf::Message& config, SinkContext context) PURE;
      98             : };
      99             : 
     100             : using TapSinkFactoryPtr = std::unique_ptr<TapSinkFactory>;
     101             : 
     102             : /**
     103             :  * Generic configuration for a tap extension (filter, transport socket, etc.).
     104             :  */
     105             : class ExtensionConfig {
     106             : public:
     107           2 :   virtual ~ExtensionConfig() = default;
     108             : 
     109             :   /**
     110             :    * @return the ID to use for admin extension configuration tracking (if applicable).
     111             :    */
     112             :   virtual const absl::string_view adminId() PURE;
     113             : 
     114             :   /**
     115             :    * Clear any active tap configuration.
     116             :    */
     117             :   virtual void clearTapConfig() PURE;
     118             : 
     119             :   /**
     120             :    * Install a new tap configuration.
     121             :    * @param proto_config supplies the generic tap config to install. Not all configuration fields
     122             :    *        may be applicable to an extension (e.g. HTTP fields). The extension is free to fail
     123             :    *        the configuration load via exception if it wishes.
     124             :    * @param admin_streamer supplies the singleton admin sink to use for output if the configuration
     125             :    *        specifies that output type. May not be used if the configuration does not specify
     126             :    *        admin output. May be nullptr if admin is not used to supply the config.
     127             :    */
     128             :   virtual void newTapConfig(const envoy::config::tap::v3::TapConfig& proto_config,
     129             :                             Sink* admin_streamer) PURE;
     130             : };
     131             : 
     132             : /**
     133             :  * Abstract tap configuration base class.
     134             :  */
     135             : class TapConfig {
     136             : public:
     137           0 :   virtual ~TapConfig() = default;
     138             : 
     139             :   /**
     140             :    * Return a per-tap sink handle manager for use by a tap session.
     141             :    * @param trace_id supplies a locally unique trace ID. Some sinks use this for output generation.
     142             :    */
     143             :   virtual PerTapSinkHandleManagerPtr createPerTapSinkHandleManager(uint64_t trace_id) PURE;
     144             : 
     145             :   /**
     146             :    * Return the maximum received bytes that can be buffered in memory. Streaming taps are still
     147             :    * subject to this limit depending on match status.
     148             :    */
     149             :   virtual uint32_t maxBufferedRxBytes() const PURE;
     150             : 
     151             :   /**
     152             :    * Return the maximum transmitted bytes that can be buffered in memory. Streaming taps are still
     153             :    * subject to this limit depending on match status.
     154             :    */
     155             :   virtual uint32_t maxBufferedTxBytes() const PURE;
     156             : 
     157             :   /**
     158             :    * Return a new match status vector that is correctly sized for the number of matchers that are in
     159             :    * the configuration.
     160             :    */
     161             :   virtual Matcher::MatchStatusVector createMatchStatusVector() const PURE;
     162             : 
     163             :   /**
     164             :    * Return the root matcher for use in updating a match status vector.
     165             :    */
     166             :   virtual const Matcher& rootMatcher() const PURE;
     167             : 
     168             :   /**
     169             :    * Non-const version of rootMatcher method.
     170             :    */
     171           0 :   Matcher& rootMatcher() {
     172           0 :     return const_cast<Matcher&>(static_cast<const TapConfig&>(*this).rootMatcher());
     173           0 :   }
     174             : 
     175             :   /**
     176             :    * Return whether the tap session should run in streaming or buffering mode.
     177             :    */
     178             :   virtual bool streaming() const PURE;
     179             : };
     180             : 
     181             : using TapConfigSharedPtr = std::shared_ptr<TapConfig>;
     182             : 
     183             : /**
     184             :  * Abstract tap configuration factory. Given a new generic tap configuration, produces an
     185             :  * extension specific tap configuration.
     186             :  */
     187             : class TapConfigFactory {
     188             : public:
     189           2 :   virtual ~TapConfigFactory() = default;
     190             : 
     191             :   /**
     192             :    * @return a new configuration given a raw tap service config proto. See
     193             :    * ExtensionConfig::newTapConfig() for param info.
     194             :    */
     195             :   virtual TapConfigSharedPtr
     196             :   createConfigFromProto(const envoy::config::tap::v3::TapConfig& proto_config,
     197             :                         Sink* admin_streamer) PURE;
     198             : };
     199             : 
     200             : using TapConfigFactoryPtr = std::unique_ptr<TapConfigFactory>;
     201             : 
     202             : } // namespace Tap
     203             : } // namespace Common
     204             : } // namespace Extensions
     205             : } // namespace Envoy