Struct JsonStreamReader 

pub struct JsonStreamReader<R>
where
    R: Read,
{ /* private fields */ }

A JSON reader implementation which consumes data from a Read

This reader internally buffers data so it is normally not necessary to wrap the provided reader in a std::io::BufReader. However, due to this buffering it should not be attempted to use the provided Read after this JSON reader was dropped (in case the Read was provided by reference only), unless JsonReader::consume_trailing_whitespace was called and therefore the end of the Read stream was reached. Otherwise due to the buffering it is unpredictable how much additional data this JSON reader has consumed from the Read.

The data provided by the underlying reader is expected to be valid UTF-8 data. The JSON reader methods will return a ReaderError::IoError if invalid UTF-8 data is detected. A leading byte order mark (BOM) is not allowed.

If the underlying reader returns an error of kind ErrorKind::Interrupted, this JSON reader will keep retrying to read data.

Security

Besides UTF-8 validation this JSON reader only implements the following basic security features:

• restriction on JSON numbers, see ReaderSettings::restrict_number_values
• nesting depth limit, see ReaderSettings::max_nesting_depth

But it does not implement any other security related measures. In particular it does not:

• Impose a limit on the length of the document

  Especially when the JSON data comes from a compressed data stream (such as gzip) large JSON documents could be used for denial of service attacks.

• Detect duplicate member names

  The JSON specification allows duplicate member names, but does not dictate how to handle them. Different JSON libraries might therefore handle them in inconsistent ways (for example one using the first occurrence, another one using the last), which could be exploited.

• Impose a limit on the length on member names and string values, or on arrays and objects

  Especially when the JSON data comes from a compressed data stream (such as gzip) large member names and string values or large arrays and objects could be used for denial of service attacks.

• Impose restrictions on content of member names and string values

  The only restriction is that member names and string values are valid UTF-8 strings, besides that they can contain any code point. They may contain control characters such as the NULL character (\0), code points which are not yet assigned a character or invalid graphemes.

When processing JSON data from an untrusted source, users of this JSON reader must implement protections against the above mentioned security issues themselves.

Implementations

impl<R> JsonStreamReader<R>

where R: Read,

pub fn new(reader: R) -> JsonStreamReader<R>

Creates a JSON reader with default settings

pub fn new_custom( reader: R, reader_settings: ReaderSettings, ) -> JsonStreamReader<R>

Creates a JSON reader with custom settings

The settings can be used to customize which JSON data the reader accepts and to allow JSON data which is considered invalid by the JSON specification.

pub fn reader_mut(&mut self) -> &mut R

Gets a mutable reference to the underlying reader

This should only be needed rarely, for advanced use cases only. The reader should not be used for determining the byte position of the JSON reader, since it might buffer not yet processed data internally. Instead the JsonReaderPosition::data_pos of the current_position should be used for that.

---

🔬 Experimental
This method is currently experimental, please provide feedback about how you are using it here.

Trait Implementations

impl<R> Debug for JsonStreamReader<R>

where R: Read + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<R> JsonReader for JsonStreamReader<R>

where R: Read,

fn peek(&mut self) -> Result<ValueType, ReaderError>

Peeks at the type of the next value, without consuming it

fn begin_array(&mut self) -> Result<(), ReaderError>

Begins consuming a JSON array

fn end_array(&mut self) -> Result<(), ReaderError>

Consumes the closing bracket ] of the current JSON array

fn begin_object(&mut self) -> Result<(), ReaderError>

Begins consuming a JSON object

fn next_name_owned(&mut self) -> Result<String, ReaderError>

Consumes and returns the name of the next JSON object member as String

fn next_name(&mut self) -> Result<&str, ReaderError>

Consumes and returns the name of the next JSON object member as str

fn end_object(&mut self) -> Result<(), ReaderError>

Consumes the closing bracket } of the current JSON object

fn next_bool(&mut self) -> Result<bool, ReaderError>

Consumes and returns a JSON boolean value

fn next_null(&mut self) -> Result<(), ReaderError>

Consumes a JSON null value

fn has_next(&mut self) -> Result<bool, ReaderError>

Checks if there is a next element in the current JSON array or object, without consuming it

fn skip_name(&mut self) -> Result<(), ReaderError>

Skips the name of the next JSON object member

fn skip_value(&mut self) -> Result<(), ReaderError>

Skips the next value

fn next_string(&mut self) -> Result<String, ReaderError>

Consumes and returns a JSON string value as String

fn next_str(&mut self) -> Result<&str, ReaderError>

Consumes and returns a JSON string value as str

fn next_string_reader(&mut self) -> Result<impl Read, ReaderError>

Provides a reader for lazily reading a JSON string value

fn next_number_as_string(&mut self) -> Result<String, ReaderError>

Consumes and returns the string representation of a JSON number value as String

fn next_number_as_str(&mut self) -> Result<&str, ReaderError>

Consumes and returns the string representation of a JSON number value as str

fn skip_to_top_level(&mut self) -> Result<(), ReaderError>

Skips the remaining elements of all currently enclosing JSON arrays and objects

fn transfer_to<W>(&mut self, json_writer: &mut W) -> Result<(), TransferError>

where W: JsonWriter,

Consumes the next value and writes it to the given JSON writer

fn consume_trailing_whitespace(self) -> Result<(), ReaderError>

Consumes trailing whitespace at the end of the top-level value

fn current_position(&self, include_path: bool) -> JsonReaderPosition

Gets the current position of this JSON reader within the JSON data

fn next_number<T>( &mut self, ) -> Result<Result<T, <T as FromStr>::Err>, ReaderError>

where T: FromStr,

Consumes and returns a JSON number value

fn seek_to( &mut self, rel_json_path: &[JsonPathPiece], ) -> Result<(), ReaderError>

Seeks to the specified location in the JSON document

fn seek_back( &mut self, rel_json_path: &[JsonPathPiece], ) -> Result<(), ReaderError>

Opposite of seek_to