littlegraph-query-api 0.2.1

Neo4j-compatible HTTP Query API for the littlegraph database
Documentation
use std::path::PathBuf;

use axum::http::StatusCode;
use littlegraph_core::{
    CancellationToken, Error as CoreError, Graph, Params, QueryResult, TransactionErrorKind,
    TransactionOptions,
};

use crate::error::HttpError;
use crate::value::{encode, ValueView};

pub(crate) async fn auto_commit(
    database_path: PathBuf,
    statement: String,
    params: Params,
    mut options: TransactionOptions,
    cancellation: CancellationToken,
    max_result_rows: usize,
    max_result_bytes: usize,
) -> Result<QueryResult, HttpError> {
    options.cancellation_token = Some(cancellation);
    tokio::task::spawn_blocking(move || {
        let mut graph = Graph::open_neo4j_writable(database_path).map_err(map_core_error)?;
        let mut transaction = graph
            .transaction_with_options(options)
            .map_err(map_core_error)?;
        let result = transaction
            .query(&statement, params)
            .map_err(map_core_error)?;
        validate_result(&result, max_result_rows, max_result_bytes)?;
        transaction.commit().map_err(map_core_error)?;
        Ok(result)
    })
    .await
    .map_err(|error| {
        log::error!("Query API auto-commit worker failed: {error}");
        HttpError::new(
            StatusCode::INTERNAL_SERVER_ERROR,
            "Neo.DatabaseError.General.UnknownError",
            "The query worker failed.",
        )
    })?
}

pub(crate) fn validate_result(
    result: &QueryResult,
    max_result_rows: usize,
    max_result_bytes: usize,
) -> Result<(), HttpError> {
    if result.rows.len() > max_result_rows {
        return Err(HttpError::new(
            StatusCode::PAYLOAD_TOO_LARGE,
            "Neo.TransientError.General.MemoryPoolOutOfMemoryError",
            "query result exceeds the configured row limit",
        ));
    }
    let mut encoded_bytes = 1024usize;
    for column in &result.columns {
        encoded_bytes = encoded_bytes
            .checked_add(column.len().saturating_mul(6).saturating_add(4))
            .ok_or_else(result_too_large)?;
    }
    for record in &result.rows {
        // Keep the pre-commit estimate above JSONL's per-record event framing.
        encoded_bytes = encoded_bytes
            .checked_add(128)
            .ok_or_else(result_too_large)?;
        for value in &record.values {
            let value = encode(value, ValueView::Typed)?;
            let length = serde_json::to_vec(&value)
                .map_err(|error| HttpError::invalid(error.to_string()))?
                .len();
            encoded_bytes = encoded_bytes
                .checked_add(length.saturating_add(2))
                .ok_or_else(result_too_large)?;
        }
    }
    if encoded_bytes > max_result_bytes {
        return Err(result_too_large());
    }
    Ok(())
}

fn result_too_large() -> HttpError {
    HttpError::new(
        StatusCode::PAYLOAD_TOO_LARGE,
        "Neo.TransientError.General.MemoryPoolOutOfMemoryError",
        "query result exceeds the configured response limit",
    )
}

pub(crate) fn map_core_error(error: CoreError) -> HttpError {
    match error {
        CoreError::Parse(message) => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Statement.SyntaxError",
            message,
        ),
        CoreError::Validation(message)
        | CoreError::UnsupportedQueryFeature(message)
        | CoreError::UnsupportedWriteQuery(message) => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Statement.SemanticError",
            message,
        ),
        CoreError::AccessMode => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Statement.AccessMode",
            "Writing in read access mode not allowed. Attempted write to self",
        ),
        CoreError::DataLoad(message) | CoreError::InvalidGraphReference(message) => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Statement.ArgumentError",
            message,
        ),
        CoreError::UnknownProcedure { name } => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Procedure.ProcedureNotFound",
            format!("unknown procedure: {name}"),
        ),
        CoreError::InvalidProcedureCall { name, message } => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Procedure.ProcedureCallFailed",
            format!("invalid call to procedure `{name}`: {message}"),
        ),
        CoreError::Transaction(TransactionErrorKind::TimedOut) => HttpError::new(
            StatusCode::ACCEPTED,
            "Neo.TransientError.Transaction.TransactionTimedOut",
            "The transaction deadline was exceeded.",
        ),
        CoreError::Transaction(TransactionErrorKind::Cancelled) => HttpError::new(
            StatusCode::ACCEPTED,
            "Neo.TransientError.Transaction.Terminated",
            "The transaction was cancelled.",
        ),
        CoreError::Transaction(TransactionErrorKind::Conflict) => HttpError::new(
            StatusCode::ACCEPTED,
            "Neo.TransientError.Transaction.DeadlockDetected",
            "The transaction conflicted with a concurrent transaction.",
        ),
        CoreError::Transaction(TransactionErrorKind::ResourceLimit) => HttpError::new(
            StatusCode::ACCEPTED,
            "Neo.TransientError.General.MemoryPoolOutOfMemoryError",
            "The transaction exceeded a configured resource limit.",
        ),
        CoreError::Transaction(kind) => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Transaction.TransactionNotFound",
            kind.to_string(),
        ),
        CoreError::Execution(message) => HttpError::new(
            StatusCode::ACCEPTED,
            "Neo.ClientError.Statement.ExecutionFailed",
            message,
        ),
        CoreError::DeferredProcedure { name, reason } => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Procedure.ProcedureNotFound",
            format!("procedure `{name}` is deferred: {reason}"),
        ),
        CoreError::UnsupportedProcedureMode { name, mode } => HttpError::new(
            StatusCode::BAD_REQUEST,
            "Neo.ClientError.Procedure.ProcedureCallFailed",
            format!("procedure mode is not supported for `{name}`: {mode}"),
        ),
        CoreError::Neo4jStore(error) => {
            log::error!("Query API database storage error: {error}");
            database_unavailable()
        }
        CoreError::Io(error) => {
            log::error!("Query API database I/O error: {error}");
            database_unavailable()
        }
        CoreError::Json(error) => HttpError::invalid(error.to_string()),
        CoreError::Console(message) => {
            log::error!("Query API internal database error: {message}");
            unexpected_database_error()
        }
        error => {
            log::error!("Query API unexpected database error: {error}");
            unexpected_database_error()
        }
    }
}

fn database_unavailable() -> HttpError {
    HttpError::new(
        StatusCode::SERVICE_UNAVAILABLE,
        "Neo.TransientError.General.DatabaseUnavailable",
        "The database is unavailable.",
    )
}

fn unexpected_database_error() -> HttpError {
    HttpError::new(
        StatusCode::INTERNAL_SERVER_ERROR,
        "Neo.DatabaseError.General.UnknownError",
        "An unexpected database error occurred.",
    )
}

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

    #[test]
    fn storage_errors_do_not_expose_internal_details() {
        let error = map_core_error(CoreError::Io(std::io::Error::other(
            "private/path/database.store",
        )));
        assert_eq!(error.status, StatusCode::SERVICE_UNAVAILABLE);
        assert_eq!(error.message, "The database is unavailable.");
        assert!(!error.message.contains("private/path"));
    }
}