codec_core/
error.rs

1//! Error handling for the codec library
2//!
3//! This module defines comprehensive error types that can occur during
4//! codec operations, providing detailed information for debugging and
5//! error recovery.
6
7#![allow(missing_docs)]
8
9use std::fmt;
10use thiserror::Error;
11
12/// Result type alias for codec operations
13pub type Result<T> = std::result::Result<T, CodecError>;
14
15/// Comprehensive error type for codec operations
16#[derive(Error, Debug)]
17pub enum CodecError {
18    /// Invalid codec configuration
19    #[error("Invalid codec configuration: {details}")]
20    InvalidConfig { details: String },
21
22    /// Unsupported codec type
23    #[error("Unsupported codec type: {codec_type}")]
24    UnsupportedCodec { codec_type: String },
25
26    /// Invalid audio format
27    #[error("Invalid audio format: {details}")]
28    InvalidFormat { details: String },
29
30    /// Invalid frame size
31    #[error("Invalid frame size: expected {expected}, got {actual}")]
32    InvalidFrameSize { expected: usize, actual: usize },
33
34    /// Invalid sample rate
35    #[error("Invalid sample rate: {rate}Hz (supported: {supported:?})")]
36    InvalidSampleRate { rate: u32, supported: Vec<u32> },
37
38    /// Invalid channel count
39    #[error("Invalid channel count: {channels} (supported: {supported:?})")]
40    InvalidChannelCount { channels: u8, supported: Vec<u8> },
41
42    /// Invalid bitrate
43    #[error("Invalid bitrate: {bitrate}bps (range: {min}-{max})")]
44    InvalidBitrate { bitrate: u32, min: u32, max: u32 },
45
46    /// Encoding operation failed
47    #[error("Encoding failed: {reason}")]
48    EncodingFailed { reason: String },
49
50    /// Decoding operation failed
51    #[error("Decoding failed: {reason}")]
52    DecodingFailed { reason: String },
53
54    /// Buffer too small for operation
55    #[error("Buffer too small: need {needed} bytes, got {actual}")]
56    BufferTooSmall { needed: usize, actual: usize },
57
58    /// Buffer overflow during operation
59    #[error("Buffer overflow: attempted to write {size} bytes to {capacity} byte buffer")]
60    BufferOverflow { size: usize, capacity: usize },
61
62    /// Codec initialization failed
63    #[error("Codec initialization failed: {reason}")]
64    InitializationFailed { reason: String },
65
66    /// Codec reset failed
67    #[error("Codec reset failed: {reason}")]
68    ResetFailed { reason: String },
69
70    /// Invalid payload data
71    #[error("Invalid payload data: {details}")]
72    InvalidPayload { details: String },
73
74    /// Codec not found
75    #[error("Codec not found: {name}")]
76    CodecNotFound { name: String },
77
78    /// Feature not enabled
79    #[error("Feature not enabled: {feature} (enable with --features {feature})")]
80    FeatureNotEnabled { feature: String },
81
82    /// SIMD operation failed
83    #[error("SIMD operation failed: {reason}")]
84    SimdFailed { reason: String },
85
86    /// Math operation failed (overflow, underflow, etc.)
87    #[error("Math operation failed: {operation} - {reason}")]
88    MathError { operation: String, reason: String },
89
90    /// I/O operation failed
91    #[error("I/O operation failed: {reason}")]
92    IoError { reason: String },
93
94    /// External library error
95    #[error("External library error: {library} - {error}")]
96    ExternalLibraryError { library: String, error: String },
97
98    /// Internal error (should not occur in normal operation)
99    #[error("Internal error: {message} (this is a bug, please report it)")]
100    InternalError { message: String },
101}
102
103impl CodecError {
104    /// Create a new invalid configuration error
105    pub fn invalid_config(details: impl Into<String>) -> Self {
106        Self::InvalidConfig {
107            details: details.into(),
108        }
109    }
110
111    /// Create a new unsupported codec error
112    pub fn unsupported_codec(codec_type: impl Into<String>) -> Self {
113        Self::UnsupportedCodec {
114            codec_type: codec_type.into(),
115        }
116    }
117
118    /// Create a new invalid format error
119    pub fn invalid_format(details: impl Into<String>) -> Self {
120        Self::InvalidFormat {
121            details: details.into(),
122        }
123    }
124
125    /// Create a new encoding failed error
126    pub fn encoding_failed(reason: impl Into<String>) -> Self {
127        Self::EncodingFailed {
128            reason: reason.into(),
129        }
130    }
131
132    /// Create a new decoding failed error
133    pub fn decoding_failed(reason: impl Into<String>) -> Self {
134        Self::DecodingFailed {
135            reason: reason.into(),
136        }
137    }
138
139    /// Create a new initialization failed error
140    pub fn initialization_failed(reason: impl Into<String>) -> Self {
141        Self::InitializationFailed {
142            reason: reason.into(),
143        }
144    }
145
146    /// Create a new feature not enabled error
147    pub fn feature_not_enabled(feature: impl Into<String>) -> Self {
148        Self::FeatureNotEnabled {
149            feature: feature.into(),
150        }
151    }
152
153    /// Create a new internal error
154    pub fn internal_error(message: impl Into<String>) -> Self {
155        Self::InternalError {
156            message: message.into(),
157        }
158    }
159
160    /// Check if this error is recoverable
161    pub fn is_recoverable(&self) -> bool {
162        match self {
163            // Configuration errors are not recoverable
164            Self::InvalidConfig { .. } 
165            | Self::UnsupportedCodec { .. }
166            | Self::InvalidFormat { .. }
167            | Self::InvalidSampleRate { .. }
168            | Self::InvalidChannelCount { .. }
169            | Self::InvalidBitrate { .. }
170            | Self::FeatureNotEnabled { .. }
171            | Self::CodecNotFound { .. }
172            | Self::InternalError { .. } => false,
173
174            // Operational errors may be recoverable
175            Self::InvalidFrameSize { .. }
176            | Self::EncodingFailed { .. }
177            | Self::DecodingFailed { .. }
178            | Self::BufferTooSmall { .. }
179            | Self::BufferOverflow { .. }
180            | Self::InvalidPayload { .. }
181            | Self::SimdFailed { .. }
182            | Self::MathError { .. }
183            | Self::IoError { .. }
184            | Self::ExternalLibraryError { .. } => true,
185
186            // Reset and initialization errors depend on the specific cause
187            Self::InitializationFailed { .. }
188            | Self::ResetFailed { .. } => false,
189        }
190    }
191
192    /// Get the error category
193    pub fn category(&self) -> ErrorCategory {
194        match self {
195            Self::InvalidConfig { .. }
196            | Self::UnsupportedCodec { .. }
197            | Self::InvalidFormat { .. }
198            | Self::InvalidSampleRate { .. }
199            | Self::InvalidChannelCount { .. }
200            | Self::InvalidBitrate { .. }
201            | Self::FeatureNotEnabled { .. }
202            | Self::CodecNotFound { .. } => ErrorCategory::Configuration,
203
204            Self::EncodingFailed { .. }
205            | Self::DecodingFailed { .. }
206            | Self::InvalidFrameSize { .. }
207            | Self::InvalidPayload { .. } => ErrorCategory::Processing,
208
209            Self::BufferTooSmall { .. }
210            | Self::BufferOverflow { .. } => ErrorCategory::Memory,
211
212            Self::InitializationFailed { .. }
213            | Self::ResetFailed { .. } => ErrorCategory::Initialization,
214
215            Self::SimdFailed { .. }
216            | Self::MathError { .. } => ErrorCategory::Computation,
217
218            Self::IoError { .. } => ErrorCategory::Io,
219
220            Self::ExternalLibraryError { .. } => ErrorCategory::External,
221
222            Self::InternalError { .. } => ErrorCategory::Internal,
223        }
224    }
225}
226
227/// Error category for grouping related errors
228#[derive(Debug, Clone, Copy, PartialEq, Eq)]
229pub enum ErrorCategory {
230    /// Configuration and parameter errors
231    Configuration,
232    /// Audio processing errors
233    Processing,
234    /// Memory management errors
235    Memory,
236    /// Initialization and setup errors
237    Initialization,
238    /// Computational errors (SIMD, math, etc.)
239    Computation,
240    /// I/O related errors
241    Io,
242    /// External library errors
243    External,
244    /// Internal library errors
245    Internal,
246}
247
248impl fmt::Display for ErrorCategory {
249    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
250        match self {
251            Self::Configuration => write!(f, "Configuration"),
252            Self::Processing => write!(f, "Processing"),
253            Self::Memory => write!(f, "Memory"),
254            Self::Initialization => write!(f, "Initialization"),
255            Self::Computation => write!(f, "Computation"),
256            Self::Io => write!(f, "I/O"),
257            Self::External => write!(f, "External"),
258            Self::Internal => write!(f, "Internal"),
259        }
260    }
261}
262
263/// Convert from I/O errors
264impl From<std::io::Error> for CodecError {
265    fn from(error: std::io::Error) -> Self {
266        Self::IoError {
267            reason: error.to_string(),
268        }
269    }
270}
271
272/// Convert from parsing errors
273impl From<std::num::ParseIntError> for CodecError {
274    fn from(error: std::num::ParseIntError) -> Self {
275        Self::MathError {
276            operation: "parse_int".to_string(),
277            reason: error.to_string(),
278        }
279    }
280}
281
282/// Convert from parsing errors
283impl From<std::num::ParseFloatError> for CodecError {
284    fn from(error: std::num::ParseFloatError) -> Self {
285        Self::MathError {
286            operation: "parse_float".to_string(),
287            reason: error.to_string(),
288        }
289    }
290}
291
292impl From<&str> for CodecError {
293    fn from(s: &str) -> Self {
294        Self::InvalidConfig {
295            details: s.to_string(),
296        }
297    }
298}
299
300impl From<String> for CodecError {
301    fn from(s: String) -> Self {
302        Self::InvalidConfig {
303            details: s,
304        }
305    }
306}
307
308#[cfg(test)]
309mod tests {
310    use super::*;
311
312    #[test]
313    fn test_error_creation() {
314        let err = CodecError::invalid_config("test message");
315        assert!(matches!(err, CodecError::InvalidConfig { .. }));
316        assert_eq!(err.category(), ErrorCategory::Configuration);
317    }
318
319    #[test]
320    fn test_error_recoverability() {
321        let recoverable = CodecError::EncodingFailed {
322            reason: "test".to_string(),
323        };
324        assert!(recoverable.is_recoverable());
325
326        let non_recoverable = CodecError::InvalidConfig {
327            details: "test".to_string(),
328        };
329        assert!(!non_recoverable.is_recoverable());
330    }
331
332    #[test]
333    fn test_error_categories() {
334        assert_eq!(
335            CodecError::invalid_config("test").category(),
336            ErrorCategory::Configuration
337        );
338        assert_eq!(
339            CodecError::encoding_failed("test").category(),
340            ErrorCategory::Processing
341        );
342        assert_eq!(
343            CodecError::BufferTooSmall { needed: 100, actual: 50 }.category(),
344            ErrorCategory::Memory
345        );
346    }
347
348    #[test]
349    fn test_error_display() {
350        let err = CodecError::InvalidFrameSize {
351            expected: 160,
352            actual: 80,
353        };
354        let display = format!("{}", err);
355        assert!(display.contains("expected 160"));
356        assert!(display.contains("got 80"));
357    }
358
359    #[test]
360    fn test_error_conversion() {
361        let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "file not found");
362        let codec_err: CodecError = io_err.into();
363        assert!(matches!(codec_err, CodecError::IoError { .. }));
364    }
365}
codec_core/error.rs

codec_core/
error.rs
