nordisk/knut

crates/knut-graphdb/src/error.rs

//! The one error type every [`crate::GraphDb`] op returns.

use thiserror::Error;

/// A graph-backend failure.
///
/// The variants exist to keep **"reachable and empty" distinguishable from
/// "unreachable"** by TYPE rather than by prose — a consumer branches on the kind
/// and never greps a sentence. A backend that folds a connect failure into an empty
/// [`crate::SubGraph`] is wrong on this seam.
#[derive(Debug, Error)]
pub enum GraphError {
    /// Could not connect to / open the backend. **Unreachable**, never "empty".
    #[error("graph backend connect: {0}")]
    Connect(String),

    /// The native engine (FalkorDB / Cozo) returned an error running the op.
    #[error("graph backend query: {0}")]
    Backend(String),

    /// A response the parser could not read into a [`crate::SubGraph`].
    #[error("graph backend response: {0}")]
    Malformed(String),

    /// **The named graph is not on this endpoint.** Distinct from an empty graph:
    /// an empty graph opens and reads as zero rows, a missing one is this.
    #[error("graph '{graph}' does not exist on {endpoint}")]
    NotFound { graph: String, endpoint: String },

    /// **The op exceeded its time bound.** Never an unbounded wait, never a
    /// spinner that stays "queued" forever.
    #[error("graph read timed out after {ms}ms — {endpoint} did not respond")]
    Timeout { endpoint: String, ms: u128 },

    /// **This backend has no query language.** The honest refusal a caller gets when
    /// it offers a Cypher bar over an arbitrary [`crate::GraphDb`] that does not
    /// implement [`crate::Cypher`]. It is a value, not a panic and not an empty
    /// scene — the whole reason Cypher is an extension trait rather than a base
    /// method with a stub.
    #[error("this graph backend ({backend}) offers no Cypher — it serves graph_names/open/read only ({endpoint})")]
    NoQueryLanguage {
        backend: &'static str,
        endpoint: String,
    },

    /// This backend does not implement this op yet — a clear, non-panicking signal
    /// the caller can surface as a user-facing message.
    #[error("operation not supported by the {backend} backend yet: {op}")]
    Unsupported {
        backend: &'static str,
        op: &'static str,
    },
}