chore(config): properly enforce specifying docs::enum_tag_description for internally tagged enums (#15853)

Author: tobz

lib/codecs/src/encoding/mod.rs

@@ -55,6 +55,7 @@ impl From<std::io::Error> for Error {
 #[configurable_component]
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[serde(tag = "method", rename_all = "snake_case")]
+#[configurable(metadata(docs::enum_tag_description = "The framing method."))]
 pub enum FramingConfig {
     /// Event data is not delimited at all.
     Bytes,

scripts/generate-component-docs.rb

@@ -6,7 +6,7 @@
   require 'tempfile'
 rescue LoadError => e
   puts "Load error: #{e.message}"
-  exit
+  exit 1
 end
 
 DEBUG_LEVEL = 1
@@ -277,7 +277,7 @@ def get_docs_type_for_value(schema, value)
     @logger.error "Schema instance type and value type are a mismatch, which should not happen."
     @logger.error "Schema instance type: #{schema_instance_type}"
     @logger.error "Value: #{value} (type: #{value_type})"
-    exit
+    exit 1
   end
 
   # For any numeric type, extract the value of `docs::numeric_type`, which must always be present in
@@ -288,7 +288,7 @@ def get_docs_type_for_value(schema, value)
     numeric_type = get_schema_metadata(schema, 'docs::numeric_type')
     if numeric_type.nil?
       @logger.error "All fields with numeric types should have 'docs::numeric_type' metadata included."
-      exit
+      exit 1
     end
 
     return numeric_type
@@ -461,7 +461,7 @@ def get_schema_by_name(root_schema, schema_name)
   schema_def = root_schema.dig('definitions', schema_name)
   if schema_def.nil?
     @logger.error "Could not find schema definition '#{schema_name}' in given schema."
-    exit
+    exit 1
   end
 
   schema_def
@@ -713,7 +713,7 @@ def resolve_schema_by_name(root_schema, schema_name)
     cycles with `#[configurable(metadata(docs::cycle_entrypoint))]`. As such a field will have no type \
     information rendered, it is advised to supply a sufficiently detailed field description that \
     describes the allowable values, etc."
-    exit
+    exit 1
   end
 
   # It wasn't already cached, so we actually have to resolve it.
@@ -949,7 +949,7 @@ def resolve_bare_schema(root_schema, schema)
       grouped
     else
       @logger.error "Failed to resolve the schema. Schema: #{schema}"
-      exit
+      exit 1
     end
 
   { 'type' => resolved }
@@ -985,7 +985,7 @@ def resolve_enum_schema(root_schema, schema)
     @logger.error 'Enum schemas should never be missing the metadata for the enum tagging mode.'
     @logger.error "Schema: #{JSON.pretty_generate(schema)}"
     @logger.error "Filter subschemas: #{JSON.pretty_generate(subschemas)}"
-    exit
+    exit 1
   end
 
   enum_tag_field = get_schema_metadata(schema, 'docs::enum_tag_field')
@@ -1098,12 +1098,12 @@ def resolve_enum_schema(root_schema, schema)
         if tag_value.nil?
           @logger.error 'All enum subschemas representing an internally-tagged enum must have the tag field use a const value.'
           @logger.error "Tag subschema: #{tag_subschema}"
-          exit
+          exit 1
         end
 
         if unique_tag_values.key?(tag_value)
           @logger.error "Found duplicate tag value '#{tag_value}' when resolving enum subschemas."
-          exit
+          exit 1
         end
 
         unique_tag_values[tag_value] = tag_subschema
@@ -1122,7 +1122,7 @@ def resolve_enum_schema(root_schema, schema)
               @logger.error "Had overlapping property '#{property_name}' from resolved enum subschema, but schemas differed:"
               @logger.error "Existing property schema (reduced): #{to_pretty_json(reduced_existing_property)}"
               @logger.error "New property schema (reduced): #{to_pretty_json(reduced_new_property)}"
-              exit
+              exit 1
             end
 
             @logger.debug "Adding relevant tag to existing resolved property schema for '#{property_name}'."
@@ -1185,8 +1185,14 @@ def resolve_enum_schema(root_schema, schema)
           }
         }
       }
+
       tag_description = get_schema_metadata(schema, 'docs::enum_tag_description')
-      resolved_tag_property['description'] = tag_description unless tag_description.nil?
+      if tag_description.nil?
+        @logger.error "A unique tag description must be specified for enums which are internally tagged (i.e. `#[serde(tag = \"...\")/`). This can be specified via `#[configurable(metadata(docs::enum_tag_description = \"...\"))]`."
+        @logger.error "Schema being generated: #{JSON.pretty_generate(schema)}"
+        exit 1
+      end
+      resolved_tag_property['description'] = tag_description
       unique_resolved_properties[enum_tag_field] = resolved_tag_property
 
       @logger.debug "Resolved as 'internally-tagged with named fields' enum schema."
@@ -1366,7 +1372,7 @@ def apply_schema_default_value!(source_schema, resolved_schema)
       Source schema: #{to_pretty_json(source_schema)} \
       Default value: #{to_pretty_json(default_value)} (type: #{default_value_type}) \
       Resolved schema: #{to_pretty_json(resolved_schema)}"
-      exit
+      exit 1
     end
 
     case default_value_type
@@ -1487,7 +1493,7 @@ def apply_schema_metadata!(source_schema, resolved_schema)
   if !syntax_override.nil?
     if resolved_schema_type?(resolved_schema) != "string"
       @logger.error "Non-string schemas should not use the `syntax_override` metadata attribute."
-      exit
+      exit 1
     end
 
     resolved_schema['type']['string']['syntax'] = syntax_override.to_s
@@ -1656,7 +1662,7 @@ def render_and_import_schema(root_schema, schema_name, friendly_name, config_map
   unwrapped_resolved_schema = resolved_schema.dig('type', 'object', 'options')
   if unwrapped_resolved_schema.nil?
     @logger.error 'Configuration types must always resolve to an object schema.'
-    exit
+    exit 1
   end
 
   unwrapped_resolved_schema = sort_hash_nested(unwrapped_resolved_schema)
@@ -1689,7 +1695,7 @@ def render_and_import_schema(root_schema, schema_name, friendly_name, config_map
   cue_output_file = "website/cue/reference/components/#{cue_relative_path}"
   unless system(@cue_binary_path, 'import', '-f', '-o', cue_output_file, '-p', 'metadata', json_output_file)
     @logger.error "[!]   Failed to import #{friendly_name} schema as valid Cue."
-    exit
+    exit 1
   end
   @logger.info "[✓]   Imported #{friendly_name} schema to '#{cue_output_file}'."
 end
@@ -1716,13 +1722,13 @@ def render_and_import_component_schema(root_schema, schema_name, component_type,
 
 if ARGV.empty?
   puts 'usage: extract-component-schema.rb <configuration schema path>'
-  exit
+  exit 1
 end
 
 # Ensure that Cue is present since we need it to import our intermediate JSON representation.
 if @cue_binary_path.nil?
   puts 'Failed to find \'cue\' binary on the current path. Install \'cue\' (or make it available on the current path) and try again.'
-  exit
+  exit 1
 end
 
 schema_path = ARGV[0]

src/nats.rs

@@ -19,30 +19,35 @@ pub enum NatsConfigError {
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(rename_all = "snake_case", tag = "strategy")]
+#[configurable(metadata(
+    docs::enum_tag_description = "The strategy used to authenticate with the NATS server.
+
+More information on NATS authentication, and the various authentication strategies, can be found in the
+NATS [documentation][nats_auth_docs]. For TLS client certificate authentication specifically, see the
+`tls` settings.
+
+[nats_auth_docs]: https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro"
+))]
 pub(crate) enum NatsAuthConfig {
-    /// Username and password authentication.
-    /// ([documentation](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/username_password))
+    /// Username/password authentication.
     UserPassword {
         #[configurable(derived)]
         user_password: NatsAuthUserPassword,
     },
 
     /// Token authentication.
-    /// ([documentation](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/tokens))
     Token {
         #[configurable(derived)]
         token: NatsAuthToken,
     },
 
-    /// Credentials file authentication.
-    /// ([documentation](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt))
+    /// Credentials file authentication. (JWT-based)
     CredentialsFile {
         #[configurable(derived)]
         credentials_file: NatsAuthCredentialsFile,
     },
 
     /// NKey authentication.
-    /// ([documentation](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/nkey_auth))
     Nkey {
         #[configurable(derived)]
         nkey: NatsAuthNKey,

src/sinks/elasticsearch/mod.rs

@@ -35,6 +35,7 @@ use crate::{
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(deny_unknown_fields, rename_all = "snake_case", tag = "strategy")]
+#[configurable(metadata(docs::enum_tag_description = "The authentication strategy to use."))]
 pub enum ElasticsearchAuth {
     /// HTTP Basic Authentication.
     Basic {

src/sinks/prometheus/mod.rs

@@ -14,6 +14,7 @@ use crate::aws::AwsAuthentication;
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(deny_unknown_fields, rename_all = "snake_case", tag = "strategy")]
+#[configurable(metadata(docs::enum_tag_description = "The authentication strategy to use."))]
 pub enum PrometheusRemoteWriteAuth {
     /// HTTP Basic Authentication.
     Basic {

src/sinks/socket.rs

@@ -32,14 +32,15 @@ pub struct SocketSinkConfig {
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(tag = "mode", rename_all = "snake_case")]
+#[configurable(metadata(docs::enum_tag_description = "The type of socket to use."))]
 pub enum Mode {
-    /// TCP.
+    /// Send over TCP.
     Tcp(#[configurable(transparent)] TcpMode),
 
-    /// UDP.
+    /// Send over UDP.
     Udp(#[configurable(transparent)] UdpMode),
 
-    /// Unix Domain Socket.
+    /// Send over a Unix domain socket (UDS).
     #[cfg(unix)]
     Unix(#[configurable(transparent)] UnixMode),
 }

src/sinks/statsd.rs

@@ -62,14 +62,15 @@ pub struct StatsdSinkConfig {
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(tag = "mode", rename_all = "snake_case")]
+#[configurable(metadata(docs::enum_tag_description = "The type of socket to use."))]
 pub enum Mode {
-    /// TCP.
+    /// Send over TCP.
     Tcp(#[configurable(transparent)] TcpSinkConfig),
 
-    /// UDP.
+    /// Send over UDP.
     Udp(#[configurable(transparent)] StatsdUdpConfig),
 
-    /// Unix Domain Socket.
+    /// Send over a Unix domain socket (UDS).
     #[cfg(unix)]
     Unix(#[configurable(transparent)] UnixSinkConfig),
 }

src/sources/demo_logs.rs

@@ -81,6 +81,9 @@ pub enum DemoLogsConfigError {
 #[derive(Clone, Debug, Derivative)]
 #[derivative(Default)]
 #[serde(tag = "format", rename_all = "snake_case")]
+#[configurable(metadata(
+    docs::enum_tag_description = "The format of the randomly generated output."
+))]
 pub enum OutputFormat {
     /// Lines are chosen at random from the list specified using `lines`.
     Shuffle {

src/sources/file.rs

@@ -243,13 +243,15 @@ fn default_line_delimiter() -> String {
 #[configurable_component]
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[serde(tag = "strategy", rename_all = "snake_case")]
+#[configurable(metadata(
+    docs::enum_tag_description = "The strategy used to uniquely identify files.\n\nThis is important for checkpointing when file rotation is used."
+))]
 pub enum FingerprintConfig {
     /// Read lines from the beginning of the file and compute a checksum over them.
     Checksum {
         /// Maximum number of bytes to use, from the lines that are read, for generating the checksum.
-        ///
-        /// TODO: Should we properly expose this in the documentation? There could definitely be value in allowing more
-        /// bytes to be used for the checksum generation, but we should commit to exposing it rather than hiding it.
+        // TODO: Should we properly expose this in the documentation? There could definitely be value in allowing more
+        // bytes to be used for the checksum generation, but we should commit to exposing it rather than hiding it.
         #[serde(alias = "fingerprint_bytes")]
         bytes: Option<usize>,
 
@@ -267,7 +269,9 @@ pub enum FingerprintConfig {
         lines: usize,
     },
 
-    /// Use the [device and inode](https://en.wikipedia.org/wiki/Inode) as the identifier.
+    /// Use the [device and inode][inode] as the identifier.
+    ///
+    /// [inode]: https://en.wikipedia.org/wiki/Inode
     #[serde(rename = "device_and_inode")]
     DevInode,
 }

src/sources/socket/mod.rs

@@ -30,6 +30,7 @@ pub struct SocketConfig {
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(tag = "mode", rename_all = "snake_case")]
+#[configurable(metadata(docs::enum_tag_description = "The type of socket to use."))]
 #[allow(clippy::large_enum_variant)] // just used for configuration
 pub enum Mode {
     /// Listen on TCP.
@@ -38,11 +39,11 @@ pub enum Mode {
     /// Listen on UDP.
     Udp(#[configurable(derived)] udp::UdpConfig),
 
-    /// Listen on UDS, in datagram mode. (Unix domain socket)
+    /// Listen on a Unix domain socket (UDS), in datagram mode.
     #[cfg(unix)]
     UnixDatagram(#[configurable(derived)] unix::UnixConfig),
 
-    /// Listen on UDS, in stream mode. (Unix domain socket)
+    /// Listen on a Unix domain socket (UDS), in stream mode.
     #[cfg(unix)]
     #[serde(alias = "unix")]
     UnixStream(#[configurable(derived)] unix::UnixConfig),

src/sources/statsd/mod.rs

@@ -42,6 +42,7 @@ use vector_core::config::LogNamespace;
 #[configurable_component(source("statsd"))]
 #[derive(Clone, Debug)]
 #[serde(tag = "mode", rename_all = "snake_case")]
+#[configurable(metadata(docs::enum_tag_description = "The type of socket to use."))]
 pub enum StatsdConfig {
     /// Listen on TCP.
     Tcp(#[configurable(derived)] TcpConfig),

src/sources/syslog.rs

@@ -67,6 +67,7 @@ pub struct SyslogConfig {
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(tag = "mode", rename_all = "snake_case")]
+#[configurable(metadata(docs::enum_tag_description = "The type of socket to use."))]
 pub enum Mode {
     /// Listen on TCP.
     Tcp {

src/transforms/log_to_metric.rs

@@ -88,6 +88,7 @@ pub enum TagConfig {
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(tag = "type", rename_all = "snake_case")]
+#[configurable(metadata(docs::enum_tag_description = "The type of metric to create."))]
 pub enum MetricTypeConfig {
     /// A counter.
     Counter(#[configurable(derived)] CounterConfig),

src/transforms/tag_cardinality_limit/config.rs

@@ -25,6 +25,9 @@ pub struct TagCardinalityLimitConfig {
 #[configurable_component]
 #[derive(Clone, Debug)]
 #[serde(tag = "mode", rename_all = "snake_case", deny_unknown_fields)]
+#[configurable(metadata(
+    docs::enum_tag_description = "Controls the approach taken for tracking tag cardinality."
+))]
 pub enum Mode {
     /// Tracks cardinality exactly.
     ///

website/cue/reference/components/sinks/base/aws_s3.cue

@@ -429,7 +429,8 @@ base: components: sinks: aws_s3: configuration: {
 				}
 			}
 			method: {
-				required: true
+				description: "The framing method."
+				required:    true
 				type: string: enum: {
 					bytes:               "Event data is not delimited at all."
 					character_delimited: "Event data is delimited by a single ASCII (7-bit) character."

website/cue/reference/components/sinks/base/azure_blob.cue

@@ -272,7 +272,8 @@ base: components: sinks: azure_blob: configuration: {
 				}
 			}
 			method: {
-				required: true
+				description: "The framing method."
+				required:    true
 				type: string: enum: {
 					bytes:               "Event data is not delimited at all."
 					character_delimited: "Event data is delimited by a single ASCII (7-bit) character."

website/cue/reference/components/sinks/base/console.cue

@@ -158,7 +158,8 @@ base: components: sinks: console: configuration: {
 				}
 			}
 			method: {
-				required: true
+				description: "The framing method."
+				required:    true
 				type: string: enum: {
 					bytes:               "Event data is not delimited at all."
 					character_delimited: "Event data is delimited by a single ASCII (7-bit) character."

website/cue/reference/components/sinks/base/elasticsearch.cue

@@ -126,7 +126,8 @@ base: components: sinks: elasticsearch: configuration: {
 				type: string: {}
 			}
 			strategy: {
-				required: true
+				description: "The authentication strategy to use."
+				required:    true
 				type: string: enum: {
 					aws:   "Amazon OpenSearch Service-specific authentication."
 					basic: "HTTP Basic Authentication."