gluex_ccdb/
lib.rs

1//! `GlueX` CCDB access library with optional Python bindings.
2//!
3//! This crate provides a read-only interface to the Jefferson Lab Calibration
4//! and Conditions Database (CCDB).
5use thiserror::Error;
6
7/// Context handling for run-, variation-, and timestamp-aware requests.
8pub mod context;
9/// Column-oriented data structures returned from CCDB queries.
10pub mod data;
11/// High-level database entry points and handles to CCDB objects.
12pub mod database;
13/// Lightweight structs that mirror CCDB tables.
14pub mod models;
15
16/// Convenience alias for functions that can return a [`CCDBError`].
17pub type CCDBResult<T> = Result<T, CCDBError>;
18
19/// Errors that can occur while interacting with CCDB metadata or payloads.
20#[derive(Error, Debug)]
21pub enum CCDBError {
22    /// Wrapper around [`rusqlite::Error`].
23    #[error(transparent)]
24    SqliteError(#[from] rusqlite::Error),
25    /// Requested directory path could not be resolved.
26    #[error("directory not found: {0}")]
27    DirectoryNotFoundError(String),
28    /// Requested table path could not be resolved.
29    #[error("table not found: {0}")]
30    TableNotFoundError(String),
31    /// Failed to resolve or canonicalize a filesystem path.
32    #[error(transparent)]
33    PathResolutionError(#[from] std::io::Error),
34    /// Path was malformed or missing a required component.
35    #[error("invalid path: {0}")]
36    InvalidPathError(String),
37    /// Variation name does not exist in the database.
38    #[error("variation not found: {0}")]
39    VariationNotFoundError(String),
40    /// Path did not begin with a forward slash.
41    #[error("path \"{0}\" is not absolute (must start with '/')")]
42    NotAbsolutePath(String),
43    /// Path contained a character outside the allowed set.
44    #[error("illegal character encountered in path \"{0}\"")]
45    IllegalCharacter(String),
46    /// Run number was not a valid integer.
47    #[error("invalid run number: {0}")]
48    InvalidRunNumberError(String),
49    /// Failed to parse data because the number of cells was not divisible by the number of columns.
50    #[error("column count mismatch (expected {expected}, found {found})")]
51    ColumnCountMismatch {
52        /// The total expected number of cells.
53        expected: usize,
54        /// The number of cells found while parsing.
55        found: usize,
56    },
57    /// Failed to parse a cell to the given type.
58    #[error("parse error at row {row}, column {column} ({column_type}): {text:?}")]
59    ParseError {
60        /// The column index of the cell.
61        column: usize,
62        /// The row index of the cell.
63        row: usize,
64        /// The expected column type for the cell.
65        column_type: crate::models::ColumnType,
66        /// The unparsed contents of the cell.
67        text: String,
68    },
69    /// Failed to retrieve a row due to an out-of-bounds index.
70    #[error("row index {requested} out of bounds (n_rows={n_rows})")]
71    RowOutOfBounds {
72        /// The requested index.
73        requested: usize,
74        /// The available number of rows.
75        n_rows: usize,
76    },
77    /// Timestamp string failed to parse.
78    #[error(transparent)]
79    GlueXCoreError(#[from] gluex_core::GlueXCoreError),
80    /// Required environment variable is not set.
81    #[error("missing {0} environment variable for CCDB connection")]
82    MissingConnectionEnv(String),
83}
84
85pub use crate::context::{CCDBContext, NamePath, Request};
86pub use crate::data::{Column, ColumnDef, ColumnLayout, Data, RowView, Value};
87pub use crate::database::CCDB;
88pub use crate::models::{
89    AssignmentMeta, AssignmentMetaLite, ColumnMeta, ColumnType, ConstantSetMeta, DirectoryMeta,
90    EventRangeMeta, RunRangeMeta, TypeTableMeta, VariationMeta,
91};
92pub use gluex_core::{run_periods::RunPeriod, GlueXCoreError, RESTVersion, RunNumber};
gluex_ccdb/lib.rs

gluex_ccdb/
lib.rs
