wfdisc 0.1.0

Reader for CSS 3.0 / NNSA KB Core wfdisc seismological waveform descriptor files. Cross-validated against ObsPy.
Documentation
//! Crate-level [`Error`] type and [`Result`] alias.

use std::io;
use std::path::PathBuf;

use thiserror::Error;

/// Convenience [`Result`](std::result::Result) alias parameterised over [`enum@Error`].
pub type Result<T> = std::result::Result<T, Error>;

/// All errors produced by this crate.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum Error {
    /// Underlying I/O failure (open, read, seek, decompress).
    #[error("I/O error: {0}")]
    Io(#[from] io::Error),

    /// A wfdisc line did not match either CSS 3.0 (283 chars) or NNSA KB
    /// Core (287 chars) length.
    #[error("invalid wfdisc line length: got {got} chars, expected 283 (CSS 3.0) or 287 (NNSA KB Core)")]
    InvalidLineLength {
        /// Observed line length.
        got: usize,
    },

    /// A numeric field could not be parsed.
    #[error("failed to parse field `{field}` (value `{value}`): {source}")]
    ParseField {
        /// Schema field name (e.g. `nsamp`, `samprate`).
        field: &'static str,
        /// Raw substring that failed to parse.
        value: String,
        /// Underlying parse error from `f64::from_str` / `i64::from_str`.
        #[source]
        source: Box<dyn std::error::Error + Send + Sync + 'static>,
    },

    /// The two-character `datatype` code was not recognised at all.
    #[error("unknown datatype code `{code}` (expected one of s4, s2, s3, i4, i2, t4, t8, f4, f8, a0, a#, b0, b#, c0, c#, e1, g2, cd, sc)")]
    UnknownDatatype {
        /// The unrecognised two-character code as it appeared in the line.
        code: String,
    },

    /// A datatype code is recognised but sample decoding is not implemented
    /// (currently: ASCII and CSS compressed variants).
    #[error("datatype `{0}` is recognised but sample decoding is not yet supported")]
    UnsupportedDatatype(crate::DataType),

    /// The referenced `.w` data file did not contain enough bytes at the
    /// requested offset.
    #[error("waveform file {path:?} truncated: needed {needed} bytes at offset {offset}, got {got}")]
    TruncatedWaveform {
        /// Path to the `.w` file.
        path: PathBuf,
        /// Byte offset (`foff`) we seeked to.
        offset: u64,
        /// Total bytes the request needed.
        needed: usize,
        /// Bytes actually read.
        got: usize,
    },

    /// The waveform file referenced from a wfdisc row could not be located.
    #[error("waveform file not found: tried {tried:?}")]
    WaveformNotFound {
        /// All paths that were attempted (typically `<dfile>` and `<dfile>.gz`).
        tried: Vec<PathBuf>,
    },

    /// Decoding would allocate more sample bytes than the configured cap.
    #[error("sample payload size {requested} bytes exceeds limit of {max} bytes")]
    SampleSizeExceeded {
        /// Bytes requested (`bytes_per_sample * nsamp`, or gzip skip offset).
        requested: usize,
        /// Configured maximum (see [`crate::DEFAULT_MAX_SAMPLE_BYTES`]).
        max: usize,
    },

    /// A numeric or path field failed semantic validation after parse.
    #[error("invalid value for field `{field}`: {reason}")]
    InvalidFieldValue {
        /// Schema field name (e.g. `nsamp`, `foff`, `dir`).
        field: &'static str,
        /// Human-readable rejection reason.
        reason: &'static str,
    },

    /// A fixed-width column slice is not valid UTF-8 at the column boundary.
    #[error("invalid UTF-8 in field `{field}` at column bytes {start}..{end}")]
    InvalidUtf8 {
        /// Schema field name.
        field: &'static str,
        /// Inclusive start byte index in the line.
        start: usize,
        /// Exclusive end byte index in the line.
        end: usize,
    },

    /// A wfdisc line does not match the reader's locked fixed-width schema.
    #[error(
        "line length {got} does not match locked schema {schema:?} (expected {expected})"
    )]
    MixedSchemaInLockedMode {
        /// Observed line length.
        got: usize,
        /// Schema the reader locked onto.
        schema: crate::Schema,
        /// Expected length for that schema.
        expected: usize,
    },

    /// Sandboxed sample read rejected an unsafe path component.
    #[error("path escapes sandbox base {base:?}: {reason}")]
    PathTraversal {
        /// Caller-supplied base directory.
        base: PathBuf,
        /// Why the resolved path was rejected.
        reason: &'static str,
    },
}