/proc/self/cwd/envoy/server/options.h

Source
#pragma once

#include <chrono>
#include <cstdint>
#include <string>

#include "envoy/admin/v3/server_info.pb.h"
#include "envoy/common/pure.h"
#include "envoy/config/bootstrap/v3/bootstrap.pb.h"
#include "envoy/network/address.h"
#include "envoy/stats/tag.h"

#include "absl/types/optional.h"
#include "spdlog/spdlog.h"

namespace Envoy {
namespace Server {

/**
 * Whether to run Envoy in serving mode, or in config validation mode at one of two levels (in which
 * case we'll verify the configuration file is valid, print any errors, and exit without serving.)
 */
enum class Mode {
  /**
   * Default mode: Regular Envoy serving process. Configs are validated in the normal course of
   * initialization, but if all is well we proceed to serve traffic.
   */
  Serve,

  /**
   * Validate as much as possible without opening network connections upstream or downstream.
   */
  Validate,

  /**
   * Completely load and initialize the config, and then exit without running the listener loop.
   */
  InitOnly,

  // TODO(rlazarus): Add a fourth option for "light validation": Mock out access to the filesystem.
  // Perform no validation of files referenced in the config, such as runtime configs, SSL certs,
  // etc. Validation will pass even if those files are malformed or don't exist, allowing the config
  // to be validated in a non-prod environment.
};

/**
 * During the drain sequence, different components ask the DrainManager
 * whether to drain via drainClose(). This enum dictates the behaviour of
 * drainClose() calls.
 */
enum class DrainStrategy {
  /**
   * The probability of drainClose() returning true increases from 0 to 100%
   * over the duration of the drain period.
   */
  Gradual,

  /**
   * drainClose() will return true as soon as the drain sequence is initiated.
   */
  Immediate,
};

using CommandLineOptionsPtr = std::unique_ptr<envoy::admin::v3::CommandLineOptions>;

/**
 * General options for the server.
 */
class Options {
public:
  virtual ~Options() = default;

  /**
   * @return uint64_t the base ID for the server. This is required for system-wide things like
   *         shared memory, domain sockets, etc. that are used during hot restart. Setting the
   *         base ID to a different value will allow the server to run multiple times on the same
   *         host if desired.
   */
  virtual uint64_t baseId() const PURE;

  /**
   * @return bool choose an unused base ID dynamically. The chosen base id can be written to a
   *         a file using the baseIdPath option.
   */
  virtual bool useDynamicBaseId() const PURE;

  /**
   * @return const std::string& the dynamic base id output file.
   */
  virtual const std::string& baseIdPath() const PURE;

  /**
   * @return the number of worker threads to run in the server.
   */
  virtual uint32_t concurrency() const PURE;

  /**
   * @return the duration of the drain period in seconds.
   */
  virtual std::chrono::seconds drainTime() const PURE;

  /**
   * @return the strategy that defines behaviour of DrainManager::drainClose();
   */
  virtual DrainStrategy drainStrategy() const PURE;

  /**
   * @return the delay before shutting down the parent envoy in a hot restart,
   *         generally longer than drainTime().
   */
  virtual std::chrono::seconds parentShutdownTime() const PURE;

  /**
   * @return const std::string& the path to the configuration file.
   */
  virtual const std::string& configPath() const PURE;

  /**
   * @return const std::string& an inline YAML bootstrap config that merges
   *                            into the config loaded in configPath().
   */
  virtual const std::string& configYaml() const PURE;

  /**
   * @return const envoy::config::bootstrap::v2::Bootstrap& a bootstrap proto object
   * that merges into the config last, after configYaml and configPath.
   */
  virtual const envoy::config::bootstrap::v3::Bootstrap& configProto() const PURE;

  /**
   * @return bool allow unknown fields in the static configuration?
   */
  virtual bool allowUnknownStaticFields() const PURE;

  /**
   * @return bool allow unknown fields in the dynamic configuration?
   */
  virtual bool rejectUnknownDynamicFields() const PURE;

  /**
   * @return bool ignore unknown fields in the dynamic configuration?
   **/
  virtual bool ignoreUnknownDynamicFields() const PURE;

  /**
   * @return const std::string& the admin address output file.
   */
  virtual const std::string& adminAddressPath() const PURE;

  /**
   * @return Network::Address::IpVersion the local address IP version.
   */
  virtual Network::Address::IpVersion localAddressIpVersion() const PURE;

  /**
   * @return spdlog::level::level_enum the default log level for the server.
   */
  virtual spdlog::level::level_enum logLevel() const PURE;

  /**
   * @return const std::vector<std::pair<std::string, spdlog::level::level_enum>>& pair of
   * component,log level for all configured components.
   */
  virtual const std::vector<std::pair<std::string, spdlog::level::level_enum>>&
  componentLogLevels() const PURE;

  /**
   * @return const std::string& the log format string.
   */
  virtual const std::string& logFormat() const PURE;

  /**
   * @return whether or not a log format was set by CLI option.
   */
  virtual bool logFormatSet() const PURE;

  /**
   * @return const bool indicating whether to escape c-style escape sequences in logs.
   */
  virtual bool logFormatEscaped() const PURE;

  /**
   * @return const bool logger mode: whether to use Fine-Grain Logger.
   */
  virtual bool enableFineGrainLogging() const PURE;

  /**
   * @return const std::string& the log file path.
   */
  virtual const std::string& logPath() const PURE;

  /**
   * @return the restart epoch. 0 indicates the first server start, 1 the second, and so on.
   */
  virtual uint64_t restartEpoch() const PURE;

  /**
   * @return whether to verify the configuration file is valid, print any errors, and exit
   *         without serving.
   */
  virtual Mode mode() const PURE;

  /**
   * @return std::chrono::milliseconds the duration in msec between log flushes.
   */
  virtual std::chrono::milliseconds fileFlushIntervalMsec() const PURE;

  /**
   * @return const std::string& the server's cluster.
   */
  virtual const std::string& serviceClusterName() const PURE;

  /**
   * @return const std::string& the server's node identification.
   */
  virtual const std::string& serviceNodeName() const PURE;

  /**
   * @return const std::string& the server's zone.
   */
  virtual const std::string& serviceZone() const PURE;

  /**
   * @return bool indicating whether the hot restart functionality has been disabled via cli flags.
   */
  virtual bool hotRestartDisabled() const PURE;

  /**
   * @return bool indicating whether system signal listeners are enabled.
   */
  virtual bool signalHandlingEnabled() const PURE;

  /**
   * @return bool indicating whether mutex tracing functionality has been enabled.
   */
  virtual bool mutexTracingEnabled() const PURE;

  /**
   * @return bool indicating whether core dumps have been enabled.
   */
  virtual bool coreDumpEnabled() const PURE;

  /**
   * @return bool indicating whether cpuset size should determine the number of worker threads.
   */
  virtual bool cpusetThreadsEnabled() const PURE;

  /**
   * @return the names of extensions to disable.
   */
  virtual const std::vector<std::string>& disabledExtensions() const PURE;

  /**
   * Converts the Options in to CommandLineOptions proto message defined in server_info.proto.
   * @return CommandLineOptionsPtr the protobuf representation of the options.
   */
  virtual CommandLineOptionsPtr toCommandLineOptions() const PURE;

  /**
   * @return the path of socket file.
   */
  virtual const std::string& socketPath() const PURE;

  /**
   * @return the mode of socket file.
   */
  virtual mode_t socketMode() const PURE;

  /**
   * @return the stats tags provided by the cli. Tags may contain duplicates. It is the
   * responsibility of the caller to handle the duplicates.
   */
  virtual const Stats::TagVector& statsTags() const PURE;
};

} // namespace Server
} // namespace Envoy

Coverage Report

Created: 2023-11-12 09:30

Line	Count	Source
1		#pragma once
2
3		#include <chrono>
4		#include <cstdint>
5		#include <string>
6
7		#include "envoy/admin/v3/server_info.pb.h"
8		#include "envoy/common/pure.h"
9		#include "envoy/config/bootstrap/v3/bootstrap.pb.h"
10		#include "envoy/network/address.h"
11		#include "envoy/stats/tag.h"
12
13		#include "absl/types/optional.h"
14		#include "spdlog/spdlog.h"
15
16		namespace Envoy {
17		namespace Server {
18
19		/**
20		* Whether to run Envoy in serving mode, or in config validation mode at one of two levels (in which
21		* case we'll verify the configuration file is valid, print any errors, and exit without serving.)
22		*/
23		enum class Mode {
24		/**
25		* Default mode: Regular Envoy serving process. Configs are validated in the normal course of
26		* initialization, but if all is well we proceed to serve traffic.
27		*/
28		Serve,
29
30		/**
31		* Validate as much as possible without opening network connections upstream or downstream.
32		*/
33		Validate,
34
35		/**
36		* Completely load and initialize the config, and then exit without running the listener loop.
37		*/
38		InitOnly,
39
40		// TODO(rlazarus): Add a fourth option for "light validation": Mock out access to the filesystem.
41		// Perform no validation of files referenced in the config, such as runtime configs, SSL certs,
42		// etc. Validation will pass even if those files are malformed or don't exist, allowing the config
43		// to be validated in a non-prod environment.
44		};
45
46		/**
47		* During the drain sequence, different components ask the DrainManager
48		* whether to drain via drainClose(). This enum dictates the behaviour of
49		* drainClose() calls.
50		*/
51		enum class DrainStrategy {
52		/**
53		* The probability of drainClose() returning true increases from 0 to 100%
54		* over the duration of the drain period.
55		*/
56		Gradual,
57
58		/**
59		* drainClose() will return true as soon as the drain sequence is initiated.
60		*/
61		Immediate,
62		};
63
64		using CommandLineOptionsPtr = std::unique_ptr<envoy::admin::v3::CommandLineOptions>;
65
66		/**
67		* General options for the server.
68		*/
69		class Options {
70		public:
71	39.4k	virtual ~Options() = default;
72
73		/**
74		* @return uint64_t the base ID for the server. This is required for system-wide things like
75		* shared memory, domain sockets, etc. that are used during hot restart. Setting the
76		* base ID to a different value will allow the server to run multiple times on the same
77		* host if desired.
78		*/
79		virtual uint64_t baseId() const PURE;
80
81		/**
82		* @return bool choose an unused base ID dynamically. The chosen base id can be written to a
83		* a file using the baseIdPath option.
84		*/
85		virtual bool useDynamicBaseId() const PURE;
86
87		/**
88		* @return const std::string& the dynamic base id output file.
89		*/
90		virtual const std::string& baseIdPath() const PURE;
91
92		/**
93		* @return the number of worker threads to run in the server.
94		*/
95		virtual uint32_t concurrency() const PURE;
96
97		/**
98		* @return the duration of the drain period in seconds.
99		*/
100		virtual std::chrono::seconds drainTime() const PURE;
101
102		/**
103		* @return the strategy that defines behaviour of DrainManager::drainClose();
104		*/
105		virtual DrainStrategy drainStrategy() const PURE;
106
107		/**
108		* @return the delay before shutting down the parent envoy in a hot restart,
109		* generally longer than drainTime().
110		*/
111		virtual std::chrono::seconds parentShutdownTime() const PURE;
112
113		/**
114		* @return const std::string& the path to the configuration file.
115		*/
116		virtual const std::string& configPath() const PURE;
117
118		/**
119		* @return const std::string& an inline YAML bootstrap config that merges
120		* into the config loaded in configPath().
121		*/
122		virtual const std::string& configYaml() const PURE;
123
124		/**
125		* @return const envoy::config::bootstrap::v2::Bootstrap& a bootstrap proto object
126		* that merges into the config last, after configYaml and configPath.
127		*/
128		virtual const envoy::config::bootstrap::v3::Bootstrap& configProto() const PURE;
129
130		/**
131		* @return bool allow unknown fields in the static configuration?
132		*/
133		virtual bool allowUnknownStaticFields() const PURE;
134
135		/**
136		* @return bool allow unknown fields in the dynamic configuration?
137		*/
138		virtual bool rejectUnknownDynamicFields() const PURE;
139
140		/**
141		* @return bool ignore unknown fields in the dynamic configuration?
142		**/
143		virtual bool ignoreUnknownDynamicFields() const PURE;
144
145		/**
146		* @return const std::string& the admin address output file.
147		*/
148		virtual const std::string& adminAddressPath() const PURE;
149
150		/**
151		* @return Network::Address::IpVersion the local address IP version.
152		*/
153		virtual Network::Address::IpVersion localAddressIpVersion() const PURE;
154
155		/**
156		* @return spdlog::level::level_enum the default log level for the server.
157		*/
158		virtual spdlog::level::level_enum logLevel() const PURE;
159
160		/**
161		* @return const std::vector<std::pair<std::string, spdlog::level::level_enum>>& pair of
162		* component,log level for all configured components.
163		*/
164		virtual const std::vector<std::pair<std::string, spdlog::level::level_enum>>&
165		componentLogLevels() const PURE;
166
167		/**
168		* @return const std::string& the log format string.
169		*/
170		virtual const std::string& logFormat() const PURE;
171
172		/**
173		* @return whether or not a log format was set by CLI option.
174		*/
175		virtual bool logFormatSet() const PURE;
176
177		/**
178		* @return const bool indicating whether to escape c-style escape sequences in logs.
179		*/
180		virtual bool logFormatEscaped() const PURE;
181
182		/**
183		* @return const bool logger mode: whether to use Fine-Grain Logger.
184		*/
185		virtual bool enableFineGrainLogging() const PURE;
186
187		/**
188		* @return const std::string& the log file path.
189		*/
190		virtual const std::string& logPath() const PURE;
191
192		/**
193		* @return the restart epoch. 0 indicates the first server start, 1 the second, and so on.
194		*/
195		virtual uint64_t restartEpoch() const PURE;
196
197		/**
198		* @return whether to verify the configuration file is valid, print any errors, and exit
199		* without serving.
200		*/
201		virtual Mode mode() const PURE;
202
203		/**
204		* @return std::chrono::milliseconds the duration in msec between log flushes.
205		*/
206		virtual std::chrono::milliseconds fileFlushIntervalMsec() const PURE;
207
208		/**
209		* @return const std::string& the server's cluster.
210		*/
211		virtual const std::string& serviceClusterName() const PURE;
212
213		/**
214		* @return const std::string& the server's node identification.
215		*/
216		virtual const std::string& serviceNodeName() const PURE;
217
218		/**
219		* @return const std::string& the server's zone.
220		*/
221		virtual const std::string& serviceZone() const PURE;
222
223		/**
224		* @return bool indicating whether the hot restart functionality has been disabled via cli flags.
225		*/
226		virtual bool hotRestartDisabled() const PURE;
227
228		/**
229		* @return bool indicating whether system signal listeners are enabled.
230		*/
231		virtual bool signalHandlingEnabled() const PURE;
232
233		/**
234		* @return bool indicating whether mutex tracing functionality has been enabled.
235		*/
236		virtual bool mutexTracingEnabled() const PURE;
237
238		/**
239		* @return bool indicating whether core dumps have been enabled.
240		*/
241		virtual bool coreDumpEnabled() const PURE;
242
243		/**
244		* @return bool indicating whether cpuset size should determine the number of worker threads.
245		*/
246		virtual bool cpusetThreadsEnabled() const PURE;
247
248		/**
249		* @return the names of extensions to disable.
250		*/
251		virtual const std::vector<std::string>& disabledExtensions() const PURE;
252
253		/**
254		* Converts the Options in to CommandLineOptions proto message defined in server_info.proto.
255		* @return CommandLineOptionsPtr the protobuf representation of the options.
256		*/
257		virtual CommandLineOptionsPtr toCommandLineOptions() const PURE;
258
259		/**
260		* @return the path of socket file.
261		*/
262		virtual const std::string& socketPath() const PURE;
263
264		/**
265		* @return the mode of socket file.
266		*/
267		virtual mode_t socketMode() const PURE;
268
269		/**
270		* @return the stats tags provided by the cli. Tags may contain duplicates. It is the
271		* responsibility of the caller to handle the duplicates.
272		*/
273		virtual const Stats::TagVector& statsTags() const PURE;
274		};
275
276		} // namespace Server
277		} // namespace Envoy