/proc/self/cwd/source/extensions/common/tap/tap.h

Source (jump to first uncovered line)
#pragma once

#include "envoy/common/pure.h"
#include "envoy/config/tap/v3/common.pb.h"
#include "envoy/data/tap/v3/wrapper.pb.h"
#include "envoy/extensions/filters/http/tap/v3/tap.pb.h"
#include "envoy/http/header_map.h"

#include "source/extensions/common/matcher/matcher.h"

#include "absl/strings/string_view.h"

namespace Envoy {
namespace Extensions {
namespace Common {
namespace Tap {

using Matcher = Envoy::Extensions::Common::Matcher::Matcher;

using TraceWrapperPtr = std::unique_ptr<envoy::data::tap::v3::TraceWrapper>;
inline TraceWrapperPtr makeTraceWrapper() {
  return std::make_unique<envoy::data::tap::v3::TraceWrapper>();
}

/**
 * A handle for a per-tap sink. This allows submitting either a single buffered trace, or a series
 * of trace segments that the sink can aggregate in whatever way it chooses.
 */
class PerTapSinkHandle {
public:
  virtual ~PerTapSinkHandle() = default;

  /**
   * Send a trace wrapper to the sink. This may be a fully buffered trace or a segment of a larger
   * trace depending on the contents of the wrapper.
   * @param trace supplies the trace to send.
   * @param format supplies the output format to use.
   */
  virtual void submitTrace(TraceWrapperPtr&& trace,
                           envoy::config::tap::v3::OutputSink::Format format) PURE;
};

using PerTapSinkHandlePtr = std::unique_ptr<PerTapSinkHandle>;

/**
 * Wraps potentially multiple PerTapSinkHandle instances and any common pre-submit functionality.
 * Each active tap will have a reference to one of these, which in turn may have references to
 * one or more PerTapSinkHandle.
 */
class PerTapSinkHandleManager {
public:
  virtual ~PerTapSinkHandleManager() = default;

  /**
   * Submit a buffered or streamed trace segment to all managed per-tap sink handles.
   */
  virtual void submitTrace(TraceWrapperPtr&& trace) PURE;
};

using PerTapSinkHandleManagerPtr = std::unique_ptr<PerTapSinkHandleManager>;

/**
 * Sink for sending tap messages.
 */
class Sink {
public:
  virtual ~Sink() = default;

  /**
   * Create a per tap sink handle for use in submitting either buffered traces or trace segments.
   * @param trace_id supplies a locally unique trace ID. Some sinks use this for output generation.
   * @param type     Indicates the type of Sink specified in request body
   */
  virtual PerTapSinkHandlePtr
  createPerTapSinkHandle(uint64_t trace_id,
                         envoy::config::tap::v3::OutputSink::OutputSinkTypeCase type) PURE;
};

using SinkPtr = std::unique_ptr<Sink>;
using SinkContext =
    absl::variant<std::reference_wrapper<Server::Configuration::FactoryContext>,
                  std::reference_wrapper<Server::Configuration::TransportSocketFactoryContext>>;

/**
 * Abstract tap sink factory. Produces a factory that can instantiate SinkPtr objects
 */
class TapSinkFactory : public Config::TypedFactory {
public:
  ~TapSinkFactory() override = default;
  std::string category() const override { return "envoy.tap.sinks"; }

  /**
   * Create a Sink that can be used for writing out data produced by the tap filter.
   * @param config supplies the protobuf configuration for the sink factory
   * @param cluster_manager is a ClusterManager from the HTTP/transport socket context
   */
  virtual SinkPtr createSinkPtr(const Protobuf::Message& config, SinkContext context) PURE;
};

using TapSinkFactoryPtr = std::unique_ptr<TapSinkFactory>;

/**
 * Generic configuration for a tap extension (filter, transport socket, etc.).
 */
class ExtensionConfig {
public:
  virtual ~ExtensionConfig() = default;

  /**
   * @return the ID to use for admin extension configuration tracking (if applicable).
   */
  virtual const absl::string_view adminId() PURE;

  /**
   * Clear any active tap configuration.
   */
  virtual void clearTapConfig() PURE;

  /**
   * Install a new tap configuration.
   * @param proto_config supplies the generic tap config to install. Not all configuration fields
   *        may be applicable to an extension (e.g. HTTP fields). The extension is free to fail
   *        the configuration load via exception if it wishes.
   * @param admin_streamer supplies the singleton admin sink to use for output if the configuration
   *        specifies that output type. May not be used if the configuration does not specify
   *        admin output. May be nullptr if admin is not used to supply the config.
   */
  virtual void newTapConfig(const envoy::config::tap::v3::TapConfig& proto_config,
                            Sink* admin_streamer) PURE;
};

/**
 * Abstract tap configuration base class.
 */
class TapConfig {
public:
  virtual ~TapConfig() = default;

  /**
   * Return a per-tap sink handle manager for use by a tap session.
   * @param trace_id supplies a locally unique trace ID. Some sinks use this for output generation.
   */
  virtual PerTapSinkHandleManagerPtr createPerTapSinkHandleManager(uint64_t trace_id) PURE;

  /**
   * Return the maximum received bytes that can be buffered in memory. Streaming taps are still
   * subject to this limit depending on match status.
   */
  virtual uint32_t maxBufferedRxBytes() const PURE;

  /**
   * Return the maximum transmitted bytes that can be buffered in memory. Streaming taps are still
   * subject to this limit depending on match status.
   */
  virtual uint32_t maxBufferedTxBytes() const PURE;

  /**
   * Return a new match status vector that is correctly sized for the number of matchers that are in
   * the configuration.
   */
  virtual Matcher::MatchStatusVector createMatchStatusVector() const PURE;

  /**
   * Return the root matcher for use in updating a match status vector.
   */
  virtual const Matcher& rootMatcher() const PURE;

  /**
   * Non-const version of rootMatcher method.
   */
  Matcher& rootMatcher() {
    return const_cast<Matcher&>(static_cast<const TapConfig&>(*this).rootMatcher());
  }

  /**
   * Return whether the tap session should run in streaming or buffering mode.
   */
  virtual bool streaming() const PURE;
};

using TapConfigSharedPtr = std::shared_ptr<TapConfig>;

/**
 * Abstract tap configuration factory. Given a new generic tap configuration, produces an
 * extension specific tap configuration.
 */
class TapConfigFactory {
public:
  virtual ~TapConfigFactory() = default;

  /**
   * @return a new configuration given a raw tap service config proto. See
   * ExtensionConfig::newTapConfig() for param info.
   */
  virtual TapConfigSharedPtr
  createConfigFromProto(const envoy::config::tap::v3::TapConfig& proto_config,
                        Sink* admin_streamer) PURE;
};

using TapConfigFactoryPtr = std::unique_ptr<TapConfigFactory>;

} // namespace Tap
} // namespace Common
} // namespace Extensions
} // namespace Envoy

Coverage Report

Created: 2024-09-19 09:45

Line	Count	Source (jump to first uncovered line)
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	249	inline TraceWrapperPtr makeTraceWrapper() {
22	249	return std::make_unique<envoy::data::tap::v3::TraceWrapper>();
23	249	}
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	80	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	80	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	81	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	81	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	80	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	4.05k	Matcher& rootMatcher() {
172	4.05k	return const_cast<Matcher&>(static_cast<const TapConfig&>(*this).rootMatcher());
173	4.05k	}
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	81	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