siderust 0.9.1

High-precision astronomy and satellite mechanics in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 Vallés Puig, Ramon

//! Unified error type for SPICE kernel operations.

use thiserror::Error;

/// Errors produced by SPK kernel operations.
///
/// All public APIs in this module return `Result<_, SpiceError>`. The
/// variants are kept small and structured so adapters can branch on the
/// concrete failure mode (out-of-coverage vs. format error vs. missing
/// chain) without string matching.
///
/// # Examples
///
/// ```rust
/// use siderust::formats::spice::SpiceError;
///
/// let coverage = SpiceError::OutOfCoverage {
///     target: 399,
///     center: 0,
///     epoch_tdb_seconds: 0.0,
///     start_tdb_seconds: 1.0,
///     end_tdb_seconds: 2.0,
/// };
/// assert!(format!("{coverage}").contains("out of coverage"));
///
/// let unsupported = SpiceError::UnsupportedKernelQuery {
///     message: "DSK surface queries are not implemented".to_string(),
/// };
/// assert!(format!("{unsupported}").contains("unsupported kernel query"));
/// ```
#[derive(Debug, Error)]
pub enum SpiceError {
    /// I/O error reading a kernel file from disk.
    #[error("SPICE kernel I/O error: {0}")]
    Io(#[from] std::io::Error),

    /// The underlying DAF/SPK parser rejected the file.
    #[error("SPICE kernel parse error: {message}")]
    Parse {
        /// Human-readable description from the upstream parser.
        message: String,
    },

    /// No segment in the kernel covers `target → center` at `epoch`.
    #[error(
        "SPICE kernel: state for target={target} center={center} is out of coverage \
         at et={epoch_tdb_seconds} TDB-s; available segment range is \
         [{start_tdb_seconds}, {end_tdb_seconds}] TDB-s"
    )]
    OutOfCoverage {
        /// NAIF body ID of the requested target.
        target: i32,
        /// NAIF body ID of the requested center.
        center: i32,
        /// Epoch in TDB seconds past J2000.
        epoch_tdb_seconds: f64,
        /// Start of the closest segment's coverage window (TDB seconds).
        start_tdb_seconds: f64,
        /// End of the closest segment's coverage window (TDB seconds).
        end_tdb_seconds: f64,
    },

    /// Kernel contains no segment chain from `target` to `center`.
    #[error(
        "SPICE kernel: no chain from target={target} to center={center} \
         (kernel has no segment with this body pair, even via transitive \
         centers)"
    )]
    NoChain {
        /// NAIF body ID of the requested target.
        target: i32,
        /// NAIF body ID of the requested center.
        center: i32,
    },

    /// SPK data type is not implemented.
    ///
    /// This crate ships SPK Type 2 (Chebyshev position), Type 3 (Chebyshev
    /// position+velocity), Type 9 (unequally-spaced Lagrange state
    /// interpolation), and Type 13 (unequally-spaced Hermite state
    /// interpolation). Higher Types are indexed but not evaluated.
    #[error("SPICE kernel: SPK Type {data_type} is not implemented")]
    UnsupportedDataType {
        /// NAIF SPK data type code.
        data_type: i32,
    },

    /// Internal invariant violated while decoding a segment.
    ///
    /// Returned when a record's metadata (e.g. `radius`) is non-finite or
    /// non-positive, which would indicate kernel corruption.
    #[error("SPICE kernel: segment record corrupted: {message}")]
    Corrupted {
        /// Human-readable description.
        message: String,
    },

    /// A high-level kernel query is not implemented for this kernel type.
    #[error("SPICE kernel: unsupported kernel query: {message}")]
    UnsupportedKernelQuery {
        /// Human-readable explanation.
        message: String,
    },

    /// The requested frame ID or name is not registered in the current context.
    #[error("SPICE context: unknown frame: {description}")]
    UnknownFrame {
        /// Description of the unrecognised frame.
        description: String,
    },

    /// A time conversion failed.
    #[error("SPICE context: time conversion error: {message}")]
    TimeConversion {
        /// Human-readable reason.
        message: String,
    },

    /// A low-level DAF/SPK format parse error.
    #[error("SPICE format parse error: {0}")]
    FormatParse(String),
}

impl From<crate::archive::ArchiveError> for SpiceError {
    fn from(err: crate::archive::ArchiveError) -> Self {
        match err {
            crate::archive::ArchiveError::Io(e) => SpiceError::Io(e),
            other => SpiceError::FormatParse(format!("{other}")),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::archive::ArchiveError;

    #[test]
    fn archive_io_error_converts_to_spice_io() {
        let err = SpiceError::from(ArchiveError::Io(std::io::Error::new(
            std::io::ErrorKind::NotFound,
            "missing kernel",
        )));
        assert!(matches!(err, SpiceError::Io(_)));
    }

    #[test]
    fn archive_integrity_error_converts_to_format_parse() {
        let err = SpiceError::from(ArchiveError::Integrity("checksum mismatch".into()));
        assert!(matches!(err, SpiceError::FormatParse(message) if message.contains("checksum")));
    }
}