diff --git a/src/components/validation/mod.rs b/src/components/validation/mod.rs index c98af05f3d115..6db16961358a4 100644 --- a/src/components/validation/mod.rs +++ b/src/components/validation/mod.rs @@ -441,9 +441,14 @@ fn get_validation_configuration_from_test_case_path( )) } +/// Runs component validation for the test case data file at the given path. +/// +/// # Panics +/// +/// Panics if the path does not exist, if the path does not map to a validatable component (it +/// must end in `/.yaml`), if the Tokio runtime cannot be +/// built, if the validation run returns an error, or if any validator reports a failure. #[cfg(feature = "component-validation-runner")] -// https://github.com/vectordotdev/vector/issues/23659 -#[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")] pub fn validate_component(test_case_data_path: std::path::PathBuf) { assert!( test_case_data_path.exists(), diff --git a/src/components/validation/resources/event.rs b/src/components/validation/resources/event.rs index f35fde6ff5fc0..3181533ad35f8 100644 --- a/src/components/validation/resources/event.rs +++ b/src/components/validation/resources/event.rs @@ -161,8 +161,11 @@ impl From for TestEvent { } } -// https://github.com/vectordotdev/vector/issues/23659 -#[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")] +/// Encodes a test event into `buf`, using an alternate encoder for events meant to fail decoding. +/// +/// # Panics +/// +/// Panics if the event cannot be encoded with the selected encoder. pub fn encode_test_event( encoder: &mut Encoder, buf: &mut BytesMut, diff --git a/src/components/validation/resources/http.rs b/src/components/validation/resources/http.rs index cebe210e56dd7..d4d2c89c0e1ac 100644 --- a/src/components/validation/resources/http.rs +++ b/src/components/validation/resources/http.rs @@ -87,8 +87,18 @@ impl HttpResourceConfig { } } + /// Spawns this resource as the output for a sink. + /// + /// # Errors + /// + /// Returns an error if the decoder for the resource codec cannot be built. + /// + /// # Panics + /// + /// Panics if the resource direction is `Pull`, which is not implemented, or if the URI host is + /// missing or not an IP address. Panics if the codec uses a serializer that has no matching + /// deserializer for validation. // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] #[allow( clippy::needless_pass_by_value, reason = "Preserve ownership and drop timing" diff --git a/src/components/validation/resources/mod.rs b/src/components/validation/resources/mod.rs index a4411a7cc7831..2715ee5ebb867 100644 --- a/src/components/validation/resources/mod.rs +++ b/src/components/validation/resources/mod.rs @@ -75,9 +75,13 @@ impl ResourceCodec { /// /// The encoder is generated as an inverse to the input codec: if a decoding configuration was /// given, we generate an encoder that satisfies that decoding configuration, and vice versa. + /// + /// # Panics + /// + /// Panics if the serializer fails to build, or if the decoding configuration uses a + /// deserializer (`influxdb`, `vrl`) or framing (`octet_counting`, `chunked_gelf`) that has no + /// encoding equivalent. #[must_use] - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")] pub fn into_encoder(&self) -> Encoder { let (framer, serializer) = match self { Self::Encoding(config) => ( @@ -109,8 +113,16 @@ impl ResourceCodec { /// /// The decoder is generated as an inverse to the input codec: if an encoding configuration was /// given, we generate a decoder that satisfies that encoding configuration, and vice versa. - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// + /// # Errors + /// + /// Returns an error if the deserializer cannot be built, such as when a Protobuf descriptor + /// file cannot be loaded. + /// + /// # Panics + /// + /// Panics if the encoding configuration uses a serializer that has no decoding equivalent + /// (`avro`, `cef`, `csv`, `logfmt`, `otlp`, or `syslog`). pub fn into_decoder(&self, log_namespace: LogNamespace) -> vector_lib::Result { let (framer, deserializer) = match self { Self::Decoding(config) => return config.build(), @@ -397,8 +409,16 @@ impl ExternalResource { } /// Spawns this resource for use as an output for a sink. - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// + /// # Errors + /// + /// Returns an error if the decoder for the resource codec cannot be built. + /// + /// # Panics + /// + /// Panics if an HTTP resource uses the `Pull` direction, which is not implemented, or if its + /// URI host is missing or not an IP address. Panics if the codec uses a serializer that has no + /// matching deserializer for validation. pub fn spawn_as_output( self, output_tx: mpsc::Sender>, diff --git a/src/components/validation/runner/config.rs b/src/components/validation/runner/config.rs index 484c0edc1cd8d..88f04031262e8 100644 --- a/src/components/validation/runner/config.rs +++ b/src/components/validation/runner/config.rs @@ -28,8 +28,10 @@ pub struct TopologyBuilder { impl TopologyBuilder { /// Creates a component topology for the given component configuration. - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// + /// # Errors + /// + /// Returns an error if the configuration has no component configuration for `config_name`. pub fn from_configuration( configuration: &ValidationConfiguration, config_name: Option<&String>, diff --git a/src/components/validation/runner/mod.rs b/src/components/validation/runner/mod.rs index 7bf6f379febe1..89b7138ee1ee6 100644 --- a/src/components/validation/runner/mod.rs +++ b/src/components/validation/runner/mod.rs @@ -208,10 +208,22 @@ impl Runner { } } + /// Runs every test case for the configured component and collects the validator results. + /// + /// # Errors + /// + /// Returns an error if the test case file cannot be opened or deserialized, if a test case + /// names a component configuration that does not exist, or if a sink's external resource + /// fails to spawn (for example, because its decoder cannot be built). + /// + /// # Panics + /// + /// Panics if a source or sink has no external resource, if the input or output driver task + /// panics, or if the generated topology configuration fails to build. Spawning external + /// resources and drivers can also panic on unsupported codecs, framings, or resource + /// directions, and on invalid resource URIs. #[allow(clippy::print_stdout)] // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] - #[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")] #[allow(clippy::too_many_lines, reason = "Preserve existing control flow")] pub async fn run_validation(self) -> Result, vector_lib::Error> { // Initialize our test environment. diff --git a/src/components/validation/util.rs b/src/components/validation/util.rs index fb58dca97d53e..0ca18e07d7310 100644 --- a/src/components/validation/util.rs +++ b/src/components/validation/util.rs @@ -25,9 +25,12 @@ impl GrpcAddress { /// Gets the fully-qualified endpoint address. /// /// This is a URI in the form of `http:///`. The scheme and path are hard-coded. + /// + /// # Panics + /// + /// Panics if the socket address does not form a valid URI authority, which should not happen + /// for any `SocketAddr`. #[must_use] - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")] pub fn as_uri(&self) -> Uri { let addr_str = self.addr.to_string(); Uri::builder() diff --git a/src/components/validation/validators/mod.rs b/src/components/validation/validators/mod.rs index d8cc9c7f4e269..240c1689ff546 100644 --- a/src/components/validation/validators/mod.rs +++ b/src/components/validation/validators/mod.rs @@ -19,8 +19,12 @@ pub trait Validator { /// /// Additionally, all telemetry events received for the component for the validation run are /// provided as well. - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// + /// # Errors + /// + /// Implementations return an error containing the failure messages if the inputs, outputs, + /// telemetry events, or runner metrics do not satisfy the validator's requirements for the + /// given component type and test case expectation. fn check_validation( &self, component_type: ComponentType, diff --git a/src/conditions/datadog_search.rs b/src/conditions/datadog_search.rs index c4461aed0eb84..f6ff67a9abaac 100644 --- a/src/conditions/datadog_search.rs +++ b/src/conditions/datadog_search.rs @@ -33,8 +33,11 @@ impl Default for DatadogSearchConfig { } impl DatadogSearchConfig { - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// Builds a log event matcher from the configured query. + /// + /// # Errors + /// + /// Currently never returns an error. pub fn build_matcher(&self) -> crate::Result>> { Ok(build_matcher(&self.source, &EventFilter)?) } diff --git a/src/conditions/mod.rs b/src/conditions/mod.rs index 4625d045e705e..5567f90b5ecaf 100644 --- a/src/conditions/mod.rs +++ b/src/conditions/mod.rs @@ -120,8 +120,11 @@ pub enum ConditionConfig { } impl ConditionConfig { - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// Builds the configured condition. + /// + /// # Errors + /// + /// Returns an error if a VRL condition fails to compile or does not return a boolean. pub fn build( &self, enrichment_tables: &vector_lib::enrichment::TableRegistry, @@ -158,8 +161,12 @@ pub trait Conditional: std::fmt::Debug { } pub trait ConditionalConfig: std::fmt::Debug + Send + Sync + dyn_clone::DynClone { - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// Builds the condition described by this configuration. + /// + /// # Errors + /// + /// Implementations return an error if the configuration cannot be turned into a usable + /// condition, such as a source that fails to compile or parse. fn build( &self, enrichment_tables: &vector_lib::enrichment::TableRegistry, @@ -200,12 +207,16 @@ pub enum AnyCondition { } impl AnyCondition { + /// Builds the condition, treating a plain string as a VRL boolean expression. + /// + /// # Errors + /// + /// Returns an error if a VRL condition fails to compile or does not return a boolean. // https://github.com/vectordotdev/vector/issues/23659 #[allow( clippy::default_trait_access, reason = "Preserve inferred default types" )] - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] pub fn build( &self, enrichment_tables: &vector_lib::enrichment::TableRegistry, @@ -223,8 +234,11 @@ impl AnyCondition { } } - // https://github.com/vectordotdev/vector/issues/23659 - #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")] + /// Checks that the condition can be built, discarding the result. + /// + /// # Errors + /// + /// Returns an error if a VRL condition fails to compile or does not return a boolean. pub fn validate( &self, enrichment_tables: &vector_lib::enrichment::TableRegistry,