1//! When serializing or deserializing JSON goes wrong.
2
3use crate::io;
4use alloc::boxed::Box;
5use alloc::string::{String, ToString};
6use core::fmt::{self, Debug, Display};
7use core::result;
8use core::str::FromStr;
9use serde::{de, ser};
10#[cfg(feature = "std")]
11use std::error;
12#[cfg(feature = "std")]
13use std::io::ErrorKind;
14
15/// This type represents all possible errors that can occur when serializing or
16/// deserializing JSON data.
17pub struct Error {
18 /// This `Box` allows us to keep the size of `Error` as small as possible. A
19 /// larger `Error` type was substantially slower due to all the functions
20 /// that pass around `Result<T, Error>`.
21 err: Box<ErrorImpl>,
22}
23
24/// Alias for a `Result` with the error type `serde_json::Error`.
25pub type Result<T> = result::Result<T, Error>;
26
27impl Error {
28 /// One-based line number at which the error was detected.
29 ///
30 /// Characters in the first line of the input (before the first newline
31 /// character) are in line 1.
32 pub fn line(&self) -> usize {
33 self.err.line
34 }
35
36 /// One-based column number at which the error was detected.
37 ///
38 /// The first character in the input and any characters immediately
39 /// following a newline character are in column 1.
40 ///
41 /// Note that errors may occur in column 0, for example if a read from an
42 /// I/O stream fails immediately following a previously read newline
43 /// character.
44 pub fn column(&self) -> usize {
45 self.err.column
46 }
47
48 /// Categorizes the cause of this error.
49 ///
50 /// - `Category::Io` - failure to read or write bytes on an I/O stream
51 /// - `Category::Syntax` - input that is not syntactically valid JSON
52 /// - `Category::Data` - input data that is semantically incorrect
53 /// - `Category::Eof` - unexpected end of the input data
54 pub fn classify(&self) -> Category {
55 match self.err.code {
56 ErrorCode::Message(_) => Category::Data,
57 ErrorCode::Io(_) => Category::Io,
58 ErrorCode::EofWhileParsingList
59 | ErrorCode::EofWhileParsingObject
60 | ErrorCode::EofWhileParsingString
61 | ErrorCode::EofWhileParsingValue => Category::Eof,
62 ErrorCode::ExpectedColon
63 | ErrorCode::ExpectedListCommaOrEnd
64 | ErrorCode::ExpectedObjectCommaOrEnd
65 | ErrorCode::ExpectedSomeIdent
66 | ErrorCode::ExpectedSomeValue
67 | ErrorCode::ExpectedDoubleQuote
68 | ErrorCode::InvalidEscape
69 | ErrorCode::InvalidNumber
70 | ErrorCode::NumberOutOfRange
71 | ErrorCode::InvalidUnicodeCodePoint
72 | ErrorCode::ControlCharacterWhileParsingString
73 | ErrorCode::KeyMustBeAString
74 | ErrorCode::ExpectedNumericKey
75 | ErrorCode::FloatKeyMustBeFinite
76 | ErrorCode::LoneLeadingSurrogateInHexEscape
77 | ErrorCode::TrailingComma
78 | ErrorCode::TrailingCharacters
79 | ErrorCode::UnexpectedEndOfHexEscape
80 | ErrorCode::RecursionLimitExceeded => Category::Syntax,
81 }
82 }
83
84 /// Returns true if this error was caused by a failure to read or write
85 /// bytes on an I/O stream.
86 pub fn is_io(&self) -> bool {
87 self.classify() == Category::Io
88 }
89
90 /// Returns true if this error was caused by input that was not
91 /// syntactically valid JSON.
92 pub fn is_syntax(&self) -> bool {
93 self.classify() == Category::Syntax
94 }
95
96 /// Returns true if this error was caused by input data that was
97 /// semantically incorrect.
98 ///
99 /// For example, JSON containing a number is semantically incorrect when the
100 /// type being deserialized into holds a String.
101 pub fn is_data(&self) -> bool {
102 self.classify() == Category::Data
103 }
104
105 /// Returns true if this error was caused by prematurely reaching the end of
106 /// the input data.
107 ///
108 /// Callers that process streaming input may be interested in retrying the
109 /// deserialization once more data is available.
110 pub fn is_eof(&self) -> bool {
111 self.classify() == Category::Eof
112 }
113
114 /// The kind reported by the underlying standard library I/O error, if this
115 /// error was caused by a failure to read or write bytes on an I/O stream.
116 ///
117 /// # Example
118 ///
119 /// ```
120 /// use serde_json::Value;
121 /// use std::io::{self, ErrorKind, Read};
122 /// use std::process;
123 ///
124 /// struct ReaderThatWillTimeOut<'a>(&'a [u8]);
125 ///
126 /// impl<'a> Read for ReaderThatWillTimeOut<'a> {
127 /// fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
128 /// if self.0.is_empty() {
129 /// Err(io::Error::new(ErrorKind::TimedOut, "timed out"))
130 /// } else {
131 /// self.0.read(buf)
132 /// }
133 /// }
134 /// }
135 ///
136 /// fn main() {
137 /// let reader = ReaderThatWillTimeOut(br#" {"k": "#);
138 ///
139 /// let _: Value = match serde_json::from_reader(reader) {
140 /// Ok(value) => value,
141 /// Err(error) => {
142 /// if error.io_error_kind() == Some(ErrorKind::TimedOut) {
143 /// // Maybe this application needs to retry certain kinds of errors.
144 ///
145 /// # return;
146 /// } else {
147 /// eprintln!("error: {}", error);
148 /// process::exit(1);
149 /// }
150 /// }
151 /// };
152 /// }
153 /// ```
154 #[cfg(feature = "std")]
155 pub fn io_error_kind(&self) -> Option<ErrorKind> {
156 if let ErrorCode::Io(io_error) = &self.err.code {
157 Some(io_error.kind())
158 } else {
159 None
160 }
161 }
162}
163
164/// Categorizes the cause of a `serde_json::Error`.
165#[derive(Copy, Clone, PartialEq, Eq, Debug)]
166pub enum Category {
167 /// The error was caused by a failure to read or write bytes on an I/O
168 /// stream.
169 Io,
170
171 /// The error was caused by input that was not syntactically valid JSON.
172 Syntax,
173
174 /// The error was caused by input data that was semantically incorrect.
175 ///
176 /// For example, JSON containing a number is semantically incorrect when the
177 /// type being deserialized into holds a String.
178 Data,
179
180 /// The error was caused by prematurely reaching the end of the input data.
181 ///
182 /// Callers that process streaming input may be interested in retrying the
183 /// deserialization once more data is available.
184 Eof,
185}
186
187#[cfg(feature = "std")]
188#[allow(clippy::fallible_impl_from)]
189impl From<Error> for io::Error {
190 /// Convert a `serde_json::Error` into an `io::Error`.
191 ///
192 /// JSON syntax and data errors are turned into `InvalidData` I/O errors.
193 /// EOF errors are turned into `UnexpectedEof` I/O errors.
194 ///
195 /// ```
196 /// use std::io;
197 ///
198 /// enum MyError {
199 /// Io(io::Error),
200 /// Json(serde_json::Error),
201 /// }
202 ///
203 /// impl From<serde_json::Error> for MyError {
204 /// fn from(err: serde_json::Error) -> MyError {
205 /// use serde_json::error::Category;
206 /// match err.classify() {
207 /// Category::Io => {
208 /// MyError::Io(err.into())
209 /// }
210 /// Category::Syntax | Category::Data | Category::Eof => {
211 /// MyError::Json(err)
212 /// }
213 /// }
214 /// }
215 /// }
216 /// ```
217 fn from(j: Error) -> Self {
218 if let ErrorCode::Io(err) = j.err.code {
219 err
220 } else {
221 match j.classify() {
222 Category::Io => unreachable!(),
223 Category::Syntax | Category::Data => io::Error::new(ErrorKind::InvalidData, j),
224 Category::Eof => io::Error::new(ErrorKind::UnexpectedEof, j),
225 }
226 }
227 }
228}
229
230struct ErrorImpl {
231 code: ErrorCode,
232 line: usize,
233 column: usize,
234}
235
236pub(crate) enum ErrorCode {
237 /// Catchall for syntax error messages
238 Message(Box<str>),
239
240 /// Some I/O error occurred while serializing or deserializing.
241 Io(io::Error),
242
243 /// EOF while parsing a list.
244 EofWhileParsingList,
245
246 /// EOF while parsing an object.
247 EofWhileParsingObject,
248
249 /// EOF while parsing a string.
250 EofWhileParsingString,
251
252 /// EOF while parsing a JSON value.
253 EofWhileParsingValue,
254
255 /// Expected this character to be a `':'`.
256 ExpectedColon,
257
258 /// Expected this character to be either a `','` or a `']'`.
259 ExpectedListCommaOrEnd,
260
261 /// Expected this character to be either a `','` or a `'}'`.
262 ExpectedObjectCommaOrEnd,
263
264 /// Expected to parse either a `true`, `false`, or a `null`.
265 ExpectedSomeIdent,
266
267 /// Expected this character to start a JSON value.
268 ExpectedSomeValue,
269
270 /// Expected this character to be a `"`.
271 ExpectedDoubleQuote,
272
273 /// Invalid hex escape code.
274 InvalidEscape,
275
276 /// Invalid number.
277 InvalidNumber,
278
279 /// Number is bigger than the maximum value of its type.
280 NumberOutOfRange,
281
282 /// Invalid unicode code point.
283 InvalidUnicodeCodePoint,
284
285 /// Control character found while parsing a string.
286 ControlCharacterWhileParsingString,
287
288 /// Object key is not a string.
289 KeyMustBeAString,
290
291 /// Contents of key were supposed to be a number.
292 ExpectedNumericKey,
293
294 /// Object key is a non-finite float value.
295 FloatKeyMustBeFinite,
296
297 /// Lone leading surrogate in hex escape.
298 LoneLeadingSurrogateInHexEscape,
299
300 /// JSON has a comma after the last value in an array or map.
301 TrailingComma,
302
303 /// JSON has non-whitespace trailing characters after the value.
304 TrailingCharacters,
305
306 /// Unexpected end of hex escape.
307 UnexpectedEndOfHexEscape,
308
309 /// Encountered nesting of JSON maps and arrays more than 128 layers deep.
310 RecursionLimitExceeded,
311}
312
313impl Error {
314 #[cold]
315 pub(crate) fn syntax(code: ErrorCode, line: usize, column: usize) -> Self {
316 Error {
317 err: Box::new(ErrorImpl { code, line, column }),
318 }
319 }
320
321 // Not public API. Should be pub(crate).
322 //
323 // Update `eager_json` crate when this function changes.
324 #[doc(hidden)]
325 #[cold]
326 pub fn io(error: io::Error) -> Self {
327 Error {
328 err: Box::new(ErrorImpl {
329 code: ErrorCode::Io(error),
330 line: 0,
331 column: 0,
332 }),
333 }
334 }
335
336 #[cold]
337 pub(crate) fn fix_position<F>(self, f: F) -> Self
338 where
339 F: FnOnce(ErrorCode) -> Error,
340 {
341 if self.err.line == 0 {
342 f(self.err.code)
343 } else {
344 self
345 }
346 }
347}
348
349impl Display for ErrorCode {
350 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
351 match self {
352 ErrorCode::Message(msg) => f.write_str(msg),
353 ErrorCode::Io(err) => Display::fmt(err, f),
354 ErrorCode::EofWhileParsingList => f.write_str("EOF while parsing a list"),
355 ErrorCode::EofWhileParsingObject => f.write_str("EOF while parsing an object"),
356 ErrorCode::EofWhileParsingString => f.write_str("EOF while parsing a string"),
357 ErrorCode::EofWhileParsingValue => f.write_str("EOF while parsing a value"),
358 ErrorCode::ExpectedColon => f.write_str("expected `:`"),
359 ErrorCode::ExpectedListCommaOrEnd => f.write_str("expected `,` or `]`"),
360 ErrorCode::ExpectedObjectCommaOrEnd => f.write_str("expected `,` or `}`"),
361 ErrorCode::ExpectedSomeIdent => f.write_str("expected ident"),
362 ErrorCode::ExpectedSomeValue => f.write_str("expected value"),
363 ErrorCode::ExpectedDoubleQuote => f.write_str("expected `\"`"),
364 ErrorCode::InvalidEscape => f.write_str("invalid escape"),
365 ErrorCode::InvalidNumber => f.write_str("invalid number"),
366 ErrorCode::NumberOutOfRange => f.write_str("number out of range"),
367 ErrorCode::InvalidUnicodeCodePoint => f.write_str("invalid unicode code point"),
368 ErrorCode::ControlCharacterWhileParsingString => {
369 f.write_str("control character (\\u0000-\\u001F) found while parsing a string")
370 }
371 ErrorCode::KeyMustBeAString => f.write_str("key must be a string"),
372 ErrorCode::ExpectedNumericKey => {
373 f.write_str("invalid value: expected key to be a number in quotes")
374 }
375 ErrorCode::FloatKeyMustBeFinite => {
376 f.write_str("float key must be finite (got NaN or +/-inf)")
377 }
378 ErrorCode::LoneLeadingSurrogateInHexEscape => {
379 f.write_str("lone leading surrogate in hex escape")
380 }
381 ErrorCode::TrailingComma => f.write_str("trailing comma"),
382 ErrorCode::TrailingCharacters => f.write_str("trailing characters"),
383 ErrorCode::UnexpectedEndOfHexEscape => f.write_str("unexpected end of hex escape"),
384 ErrorCode::RecursionLimitExceeded => f.write_str("recursion limit exceeded"),
385 }
386 }
387}
388
389impl serde::de::StdError for Error {
390 #[cfg(feature = "std")]
391 fn source(&self) -> Option<&(dyn error::Error + 'static)> {
392 match &self.err.code {
393 ErrorCode::Io(err: &Error) => err.source(),
394 _ => None,
395 }
396 }
397}
398
399impl Display for Error {
400 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
401 Display::fmt(&*self.err, f)
402 }
403}
404
405impl Display for ErrorImpl {
406 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
407 if self.line == 0 {
408 Display::fmt(&self.code, f)
409 } else {
410 write!(
411 f,
412 "{} at line {} column {}",
413 self.code, self.line, self.column
414 )
415 }
416 }
417}
418
419// Remove two layers of verbosity from the debug representation. Humans often
420// end up seeing this representation because it is what unwrap() shows.
421impl Debug for Error {
422 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
423 write!(
424 f,
425 "Error({:?}, line: {}, column: {})",
426 self.err.code.to_string(),
427 self.err.line,
428 self.err.column
429 )
430 }
431}
432
433impl de::Error for Error {
434 #[cold]
435 fn custom<T: Display>(msg: T) -> Error {
436 make_error(msg.to_string())
437 }
438
439 #[cold]
440 fn invalid_type(unexp: de::Unexpected, exp: &dyn de::Expected) -> Self {
441 Error::custom(msg:format_args!(
442 "invalid type: {}, expected {}",
443 JsonUnexpected(unexp),
444 exp,
445 ))
446 }
447
448 #[cold]
449 fn invalid_value(unexp: de::Unexpected, exp: &dyn de::Expected) -> Self {
450 Error::custom(msg:format_args!(
451 "invalid value: {}, expected {}",
452 JsonUnexpected(unexp),
453 exp,
454 ))
455 }
456}
457
458impl ser::Error for Error {
459 #[cold]
460 fn custom<T: Display>(msg: T) -> Error {
461 make_error(msg.to_string())
462 }
463}
464
465struct JsonUnexpected<'a>(de::Unexpected<'a>);
466
467impl<'a> Display for JsonUnexpected<'a> {
468 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
469 match self.0 {
470 de::Unexpected::Unit => formatter.write_str(data:"null"),
471 de::Unexpected::Float(value: f64) => write!(
472 formatter,
473 "floating point `{}`",
474 ryu::Buffer::new().format(value),
475 ),
476 unexp: Unexpected<'a> => Display::fmt(&unexp, f:formatter),
477 }
478 }
479}
480
481// Parse our own error message that looks like "{} at line {} column {}" to work
482// around erased-serde round-tripping the error through de::Error::custom.
483fn make_error(mut msg: String) -> Error {
484 let (line: usize, column: usize) = parse_line_col(&mut msg).unwrap_or((0, 0));
485 Error {
486 err: Box::new(ErrorImpl {
487 code: ErrorCode::Message(msg.into_boxed_str()),
488 line,
489 column,
490 }),
491 }
492}
493
494fn parse_line_col(msg: &mut String) -> Option<(usize, usize)> {
495 let start_of_suffix = match msg.rfind(" at line ") {
496 Some(index) => index,
497 None => return None,
498 };
499
500 // Find start and end of line number.
501 let start_of_line = start_of_suffix + " at line ".len();
502 let mut end_of_line = start_of_line;
503 while starts_with_digit(&msg[end_of_line..]) {
504 end_of_line += 1;
505 }
506
507 if !msg[end_of_line..].starts_with(" column ") {
508 return None;
509 }
510
511 // Find start and end of column number.
512 let start_of_column = end_of_line + " column ".len();
513 let mut end_of_column = start_of_column;
514 while starts_with_digit(&msg[end_of_column..]) {
515 end_of_column += 1;
516 }
517
518 if end_of_column < msg.len() {
519 return None;
520 }
521
522 // Parse numbers.
523 let line = match usize::from_str(&msg[start_of_line..end_of_line]) {
524 Ok(line) => line,
525 Err(_) => return None,
526 };
527 let column = match usize::from_str(&msg[start_of_column..end_of_column]) {
528 Ok(column) => column,
529 Err(_) => return None,
530 };
531
532 msg.truncate(start_of_suffix);
533 Some((line, column))
534}
535
536fn starts_with_digit(slice: &str) -> bool {
537 match slice.as_bytes().first() {
538 None => false,
539 Some(&byte: u8) => byte >= b'0' && byte <= b'9',
540 }
541}
542