Added constructors that include native utf-8 validation

The goal is to adopt this functionality into the standard constructors,
but backwards compatibility is tricky - this gives more room to
experiment first.

Reader::from_reader_validating()
Reader::from_file_validating()
NsReader::from_reader_validating()
NsReader::from_file_validating()

(when "encoding" feature is not enabled)

Author: dralley

Changelog.md

@@ -32,6 +32,13 @@
   - `Attribute::decode_and_unescape_value_with()`
 
   Deprecated functions now behaves the same as newly added.
+-[#947]: Add new constructors to `Reader` and `NsReader` that perform automatic streaming UTF-8
+  validation on the underlying input. Validation failures are raised as errors when the `Reader`
+  is used. These APIs are currently considered "experimental".
+  - `Reader::from_reader_validating()`
+  - `Reader::from_file_validating()`
+  - `NsReader::from_reader_validating()`
+  - `NsReader::from_file_validating()`
 
 ### Bug Fixes
 
@@ -48,6 +55,7 @@
   properly normalized EOLs. To get the previous behavior use `.read_text().decode()?`.
 - [#947]: Bumped MSRV from 1.59 (Feb 2022) to 1.79 (June 2024)
 
+[#947]: https://github.com/tafia/quick-xml/pull/947
 [#371]: https://github.com/tafia/quick-xml/issues/371
 [#914]: https://github.com/tafia/quick-xml/pull/914
 [#938]: https://github.com/tafia/quick-xml/pull/938

src/reader/buffered_reader.rs

@@ -5,7 +5,7 @@ use std::fs::File;
 use std::io::{self, BufRead, BufReader};
 use std::path::Path;
 
-use crate::encoding;
+use crate::encoding::{self, Utf8BytesReader};
 use crate::errors::{Error, Result};
 use crate::events::{BytesText, Event};
 use crate::name::QName;
@@ -578,6 +578,18 @@ impl Reader<BufReader<File>> {
     }
 }
 
+impl Reader<Utf8BytesReader<File>> {
+    /// Creates an XML reader from a file path.
+    ///
+    /// The reader will validate that all bytes read from the file are valid UTF-8.
+    /// If invalid UTF-8 is encountered, an error will be returned when reading events.
+    #[cfg(not(feature = "encoding"))]
+    pub fn from_file_validating<P: AsRef<Path>>(path: P) -> Result<Self> {
+        let file = File::open(path)?;
+        Ok(Self::from_reader_validating(file))
+    }
+}
+
 #[cfg(test)]
 mod test {
     use crate::reader::test::check;

src/reader/mod.rs

@@ -5,9 +5,9 @@ use encoding_rs::Encoding;
 use std::io;
 use std::ops::Range;
 
-use crate::encoding::Decoder;
 #[cfg(feature = "encoding")]
 use crate::encoding::DetectedEncoding;
+use crate::encoding::{Decoder, Utf8BytesReader};
 use crate::errors::{Error, IllFormedError, SyntaxError};
 use crate::events::{BytesRef, Event};
 use crate::parser::{DtdParser, ElementParser, Parser, PiParser};
@@ -778,7 +778,7 @@ impl<R> Reader<R> {
     /// Creates a `Reader` that reads from a given reader.
     pub fn from_reader(reader: R) -> Self {
         Self {
-            reader,
+            reader: reader,
             state: ReaderState::default(),
         }
     }
@@ -794,6 +794,35 @@ impl<R> Reader<R> {
     }
 }
 
+impl<R: std::io::Read> Reader<Utf8BytesReader<R>> {
+    /// Creates a `Reader` that reads from a given reader with UTF-8 validation.
+    ///
+    /// This constructor wraps the input reader in a [`Utf8BytesReader`], which validates
+    /// that all bytes read are valid UTF-8. If invalid UTF-8 is encountered, an error
+    /// will be returned when reading events.
+    ///
+    /// # Experimental
+    ///
+    /// **This API is experimental and may change (or disappear) in future versions.**
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use quick_xml::reader::Reader;
+    /// use std::io::Cursor;
+    ///
+    /// let data = Cursor::new(b"<tag>content</tag>".to_vec());
+    /// let reader = Reader::from_reader_validating(data);
+    /// // Reader will validate UTF-8 as it reads
+    /// ```
+    ///
+    /// [`Utf8BytesReader`]: crate::encoding::Utf8BytesReader
+    #[cfg(not(feature = "encoding"))]
+    pub fn from_reader_validating(reader: R) -> Self {
+        Self::from_reader(Utf8BytesReader::new(reader))
+    }
+}
+
 /// Getters
 impl<R> Reader<R> {
     /// Consumes `Reader` returning the underlying reader

src/reader/ns_reader.rs

@@ -9,6 +9,7 @@ use std::io::{BufRead, BufReader};
 use std::ops::Deref;
 use std::path::Path;
 
+use crate::encoding::Utf8BytesReader;
 use crate::errors::Result;
 use crate::events::{BytesText, Event};
 use crate::name::{NamespaceResolver, QName, ResolveResult};
@@ -50,6 +51,36 @@ impl<R> NsReader<R> {
     }
 }
 
+impl<R: std::io::Read> NsReader<Utf8BytesReader<R>> {
+    /// Creates an `NsReader` that reads from a given reader with UTF-8 validation.
+    ///
+    /// This constructor wraps the input reader in a [`Utf8BytesReader`], which validates
+    /// that all bytes read are valid UTF-8. If invalid UTF-8 is encountered, an error
+    /// will be returned when reading events.
+    ///
+    /// # Experimental
+    ///
+    /// **This API is experimental and may change (or disappear) in future versions.**
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use quick_xml::reader::NsReader;
+    /// use std::io::Cursor;
+    ///
+    /// let data = Cursor::new(b"<tag>content</tag>".to_vec());
+    /// let reader = NsReader::from_reader_validating(data);
+    /// // Reader will validate UTF-8 as it reads
+    /// ```
+    ///
+    /// [`Utf8BytesReader`]: crate::encoding::Utf8BytesReader
+    #[inline]
+    #[cfg(not(feature = "encoding"))]
+    pub fn from_reader_validating(reader: R) -> Self {
+        Self::new(Reader::from_reader_validating(reader))
+    }
+}
+
 /// Private methods
 impl<R> NsReader<R> {
     #[inline]
@@ -442,6 +473,18 @@ impl NsReader<BufReader<File>> {
     }
 }
 
+impl NsReader<Utf8BytesReader<File>> {
+    /// Creates an XML reader from a file path.
+    ///
+    /// If the [`encoding`] feature is *not* enabled, the reader will validate that all
+    /// bytes read from the file are valid UTF-8. If invalid UTF-8 is encountered, an
+    /// error will be returned when reading events.
+    #[cfg(not(feature = "encoding"))]
+    pub fn from_file_validating<P: AsRef<Path>>(path: P) -> Result<Self> {
+        Ok(Self::new(Reader::from_file_validating(path)?))
+    }
+}
+
 impl<'i> NsReader<&'i [u8]> {
     /// Creates an XML reader from a string slice.
     #[inline]