AvroError enum for arrow-avro crate

arrow-avro/src/errors.rs

@@ -0,0 +1,151 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Common Avro errors and macros.
+
+use arrow_schema::ArrowError;
+use core::num::TryFromIntError;
+use std::error::Error;
+use std::string::FromUtf8Error;
+use std::{io, result, str};
+
+/// Avro error enumeration
+
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum AvroError {
+    /// General Avro error.
+    /// Returned when code violates normal workflow of working with Avro data.
+    General(String),
+    /// "Not yet implemented" Avro error.
+    /// Returned when functionality is not yet available.
+    NYI(String),
+    /// "End of file" Avro error.
+    /// Returned when IO related failures occur, e.g. when there are not enough bytes to
+    /// decode.
+    EOF(String),
+    /// Arrow error.
+    /// Returned when reading into arrow or writing from arrow.
+    ArrowError(Box<ArrowError>),
+    /// Error when the requested index is more than the
+    /// number of items expected
+    IndexOutOfBound(usize, usize),
+    /// Error indicating that an unexpected or bad argument was passed to a function.
+    InvalidArgument(String),
+    /// Error indicating that a value could not be parsed.
+    ParseError(String),
+    /// Error indicating that a schema is invalid.
+    SchemaError(String),
+    /// An external error variant
+    External(Box<dyn Error + Send + Sync>),
+    /// Error during IO operations
+    IoError(String, io::Error),
+    /// Returned when a function needs more data to complete properly. The `usize` field indicates
+    /// the total number of bytes required, not the number of additional bytes.
+    NeedMoreData(usize),
+    /// Returned when a function needs more data to complete properly.
+    /// The `Range<u64>` indicates the range of bytes that are needed.
+    NeedMoreDataRange(std::ops::Range<u64>),
+}
+
+impl std::fmt::Display for AvroError {
+    fn fmt(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
+        match &self {
+            AvroError::General(message) => {
+                write!(fmt, "Avro error: {message}")
+            }
+            AvroError::NYI(message) => write!(fmt, "NYI: {message}"),
+            AvroError::EOF(message) => write!(fmt, "EOF: {message}"),
+            AvroError::ArrowError(message) => write!(fmt, "Arrow: {message}"),
+            AvroError::IndexOutOfBound(index, bound) => {
+                write!(fmt, "Index {index} out of bound: {bound}")
+            }
+            AvroError::InvalidArgument(message) => {
+                write!(fmt, "Invalid argument: {message}")
+            }
+            AvroError::ParseError(message) => write!(fmt, "Parse error: {message}"),
+            AvroError::SchemaError(message) => write!(fmt, "Schema error: {message}"),
+            AvroError::External(e) => write!(fmt, "External: {e}"),
+            AvroError::IoError(message, e) => write!(fmt, "I/O Error: {message}: {e}"),
+            AvroError::NeedMoreData(needed) => write!(fmt, "NeedMoreData: {needed}"),
+            AvroError::NeedMoreDataRange(range) => {
+                write!(fmt, "NeedMoreDataRange: {}..{}", range.start, range.end)
+            }
+        }
+    }
+}
+
+impl Error for AvroError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            AvroError::External(e) => Some(e.as_ref()),
+            AvroError::ArrowError(e) => Some(e.as_ref()),
+            AvroError::IoError(_, e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+impl From<TryFromIntError> for AvroError {
+    fn from(e: TryFromIntError) -> AvroError {
+        AvroError::General(format!("Integer overflow: {e}"))
+    }
+}
+
+impl From<io::Error> for AvroError {
+    fn from(e: io::Error) -> AvroError {
+        AvroError::External(Box::new(e))
+    }
+}
+
+impl From<str::Utf8Error> for AvroError {
+    fn from(e: str::Utf8Error) -> AvroError {
+        AvroError::External(Box::new(e))
+    }
+}
+
+impl From<FromUtf8Error> for AvroError {
+    fn from(e: FromUtf8Error) -> AvroError {
+        AvroError::External(Box::new(e))
+    }
+}
+
+impl From<ArrowError> for AvroError {
+    fn from(e: ArrowError) -> Self {
+        AvroError::ArrowError(Box::new(e))
+    }
+}
+
+/// A specialized `Result` for Avro errors.
+pub type Result<T, E = AvroError> = result::Result<T, E>;
+
+impl From<AvroError> for io::Error {
+    fn from(e: AvroError) -> Self {
+        io::Error::other(e)
+    }
+}
+
+impl From<AvroError> for ArrowError {
+    fn from(e: AvroError) -> Self {
+        match e {
+            AvroError::External(inner) => ArrowError::from_external_error(inner),
+            AvroError::IoError(msg, err) => ArrowError::IoError(msg, err),
+            AvroError::ArrowError(inner) => *inner,
+            other => ArrowError::AvroError(other.to_string()),
+        }
+    }
+}

arrow-avro/src/lib.rs

@@ -195,6 +195,9 @@ pub mod compression;
 /// Avro data types and Arrow data types.
 pub mod codec;
 
+/// AvroError variants
+pub mod errors;
+
 /// Extension trait for AvroField to add Utf8View support
 ///
 /// This trait adds methods for working with Utf8View support to the AvroField struct.

arrow-avro/src/reader/block.rs

@@ -17,8 +17,8 @@
 
 //! Decoder for [`Block`]
 
+use crate::errors::{AvroError, Result};
 use crate::reader::vlq::VLQDecoder;
-use arrow_schema::ArrowError;
 
 /// A file data block
 ///
@@ -75,14 +75,14 @@ impl BlockDecoder {
     /// can then be used again to read the next block, if any
     ///
     /// [`BufRead::fill_buf`]: std::io::BufRead::fill_buf
-    pub fn decode(&mut self, mut buf: &[u8]) -> Result<usize, ArrowError> {
+    pub fn decode(&mut self, mut buf: &[u8]) -> Result<usize> {
         let max_read = buf.len();
         while !buf.is_empty() {
             match self.state {
                 BlockDecoderState::Count => {
                     if let Some(c) = self.vlq_decoder.long(&mut buf) {
                         self.in_progress.count = c.try_into().map_err(|_| {
-                            ArrowError::ParseError(format!(
+                            AvroError::ParseError(format!(
                                 "Block count cannot be negative, got {c}"
                             ))
                         })?;
@@ -93,9 +93,7 @@ impl BlockDecoder {
                 BlockDecoderState::Size => {
                     if let Some(c) = self.vlq_decoder.long(&mut buf) {
                         self.bytes_remaining = c.try_into().map_err(|_| {
-                            ArrowError::ParseError(format!(
-                                "Block size cannot be negative, got {c}"
-                            ))
+                            AvroError::ParseError(format!("Block size cannot be negative, got {c}"))
                         })?;
 
                         self.in_progress.data.reserve(self.bytes_remaining);

arrow-avro/src/reader/cursor.rs

@@ -15,8 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
+use crate::errors::{AvroError, Result};
 use crate::reader::vlq::read_varint;
-use arrow_schema::ArrowError;
 
 /// A wrapper around a byte slice, providing low-level decoding for Avro
 ///
@@ -43,88 +43,81 @@ impl<'a> AvroCursor<'a> {
 
     /// Read a single `u8`
     #[inline]
-    pub(crate) fn get_u8(&mut self) -> Result<u8, ArrowError> {
+    pub(crate) fn get_u8(&mut self) -> Result<u8> {
         match self.buf.first().copied() {
             Some(x) => {
                 self.buf = &self.buf[1..];
                 Ok(x)
             }
-            None => Err(ArrowError::ParseError("Unexpected EOF".to_string())),
+            None => Err(AvroError::EOF("Unexpected EOF".to_string())),
         }
     }
 
     #[inline]
-    pub(crate) fn get_bool(&mut self) -> Result<bool, ArrowError> {
+    pub(crate) fn get_bool(&mut self) -> Result<bool> {
         Ok(self.get_u8()? != 0)
     }
 
-    pub(crate) fn read_vlq(&mut self) -> Result<u64, ArrowError> {
-        let (val, offset) = read_varint(self.buf)
-            .ok_or_else(|| ArrowError::ParseError("bad varint".to_string()))?;
+    pub(crate) fn read_vlq(&mut self) -> Result<u64> {
+        let (val, offset) =
+            read_varint(self.buf).ok_or_else(|| AvroError::ParseError("bad varint".to_string()))?;
         self.buf = &self.buf[offset..];
         Ok(val)
     }
 
     #[inline]
-    pub(crate) fn get_int(&mut self) -> Result<i32, ArrowError> {
+    pub(crate) fn get_int(&mut self) -> Result<i32> {
         let varint = self.read_vlq()?;
         let val: u32 = varint
             .try_into()
-            .map_err(|_| ArrowError::ParseError("varint overflow".to_string()))?;
+            .map_err(|_| AvroError::ParseError("varint overflow".to_string()))?;
         Ok((val >> 1) as i32 ^ -((val & 1) as i32))
     }
 
     #[inline]
-    pub(crate) fn get_long(&mut self) -> Result<i64, ArrowError> {
+    pub(crate) fn get_long(&mut self) -> Result<i64> {
         let val = self.read_vlq()?;
         Ok((val >> 1) as i64 ^ -((val & 1) as i64))
     }
 
-    pub(crate) fn get_bytes(&mut self) -> Result<&'a [u8], ArrowError> {
-        let len: usize = self.get_long()?.try_into().map_err(|_| {
-            ArrowError::ParseError("offset overflow reading avro bytes".to_string())
-        })?;
+    pub(crate) fn get_bytes(&mut self) -> Result<&'a [u8]> {
+        let len: usize = self
+            .get_long()?
+            .try_into()
+            .map_err(|_| AvroError::ParseError("offset overflow reading avro bytes".to_string()))?;
 
         if self.buf.len() < len {
-            return Err(ArrowError::ParseError(
-                "Unexpected EOF reading bytes".to_string(),
-            ));
+            return Err(AvroError::EOF("Unexpected EOF reading bytes".to_string()));
         }
         let ret = &self.buf[..len];
         self.buf = &self.buf[len..];
         Ok(ret)
     }
 
     #[inline]
-    pub(crate) fn get_float(&mut self) -> Result<f32, ArrowError> {
+    pub(crate) fn get_float(&mut self) -> Result<f32> {
         if self.buf.len() < 4 {
-            return Err(ArrowError::ParseError(
-                "Unexpected EOF reading float".to_string(),
-            ));
+            return Err(AvroError::EOF("Unexpected EOF reading float".to_string()));
         }
         let ret = f32::from_le_bytes(self.buf[..4].try_into().unwrap());
         self.buf = &self.buf[4..];
         Ok(ret)
     }
 
     #[inline]
-    pub(crate) fn get_double(&mut self) -> Result<f64, ArrowError> {
+    pub(crate) fn get_double(&mut self) -> Result<f64> {
         if self.buf.len() < 8 {
-            return Err(ArrowError::ParseError(
-                "Unexpected EOF reading float".to_string(),
-            ));
+            return Err(AvroError::EOF("Unexpected EOF reading float".to_string()));
         }
         let ret = f64::from_le_bytes(self.buf[..8].try_into().unwrap());
         self.buf = &self.buf[8..];
         Ok(ret)
     }
 
     /// Read exactly `n` bytes from the buffer (e.g. for Avro `fixed`).
-    pub(crate) fn get_fixed(&mut self, n: usize) -> Result<&'a [u8], ArrowError> {
+    pub(crate) fn get_fixed(&mut self, n: usize) -> Result<&'a [u8]> {
         if self.buf.len() < n {
-            return Err(ArrowError::ParseError(
-                "Unexpected EOF reading fixed".to_string(),
-            ));
+            return Err(AvroError::EOF("Unexpected EOF reading fixed".to_string()));
         }
         let ret = &self.buf[..n];
         self.buf = &self.buf[n..];