littlegraph-python 0.2.1

Python extension module for the littlegraph embedded graph database
Documentation
use std::path::PathBuf;
use std::sync::mpsc::{sync_channel, Receiver, SyncSender};
use std::thread::{self, JoinHandle};

use littlegraph_core::{Graph, Neo4jStorage, Params, QueryResult, TransactionOptions, Value};

use crate::error::BindingError;

pub(crate) enum Command {
    AutoExecute(Box<AutoExecute>),
    Shutdown,
}

pub(crate) struct AutoExecute {
    pub(crate) query: String,
    pub(crate) parameters: Params,
    pub(crate) options: TransactionOptions,
    pub(crate) max_result_rows: usize,
    pub(crate) max_result_bytes: usize,
    pub(crate) result: SyncSender<Result<QueryResult, BindingError>>,
    pub(crate) acknowledge: Receiver<bool>,
    pub(crate) finish: SyncSender<Result<(), BindingError>>,
}

pub(crate) struct WorkerHandle {
    pub(crate) commands: SyncSender<Command>,
    pub(crate) thread: JoinHandle<()>,
}

pub(crate) fn start(
    path: PathBuf,
    read_only: bool,
    create: bool,
    command_capacity: usize,
) -> Result<(WorkerHandle, Receiver<Result<(), BindingError>>), BindingError> {
    let (commands, receiver) = sync_channel(command_capacity);
    let (startup_tx, startup_rx) = sync_channel(1);
    let thread = thread::Builder::new()
        .name("littlegraph-python-database".to_owned())
        .spawn(move || {
            let opened = std::panic::catch_unwind(|| open_graph(&path, read_only, create));
            match opened {
                Ok(Ok(graph)) => {
                    if startup_tx.send(Ok(())).is_ok() {
                        worker_loop(graph, receiver);
                    }
                }
                Ok(Err(error)) => {
                    let _ = startup_tx.send(Err(error));
                }
                Err(_) => {
                    let _ = startup_tx.send(Err(BindingError::worker(
                        "database worker panicked during startup",
                    )));
                }
            }
        })
        .map_err(|error| {
            BindingError::worker(format!("failed to start database worker: {error}"))
        })?;
    Ok((WorkerHandle { commands, thread }, startup_rx))
}

fn open_graph(path: &PathBuf, read_only: bool, create: bool) -> Result<Graph, BindingError> {
    if create {
        Neo4jStorage::initialize_if_empty(path)?;
    }
    if read_only {
        Graph::open_neo4j(path).map_err(Into::into)
    } else {
        Graph::open_neo4j_writable(path).map_err(Into::into)
    }
}

fn worker_loop(mut graph: Graph, commands: Receiver<Command>) {
    while let Ok(command) = commands.recv() {
        match command {
            Command::AutoExecute(command) => {
                let AutoExecute {
                    query,
                    parameters,
                    options,
                    max_result_rows,
                    max_result_bytes,
                    result,
                    acknowledge,
                    finish,
                } = *command;
                execute_auto_commit(
                    &mut graph,
                    query,
                    parameters,
                    options,
                    max_result_rows,
                    max_result_bytes,
                    result,
                    acknowledge,
                    finish,
                );
            }
            Command::Shutdown => return,
        }
    }
}

#[allow(clippy::too_many_arguments)]
fn execute_auto_commit(
    graph: &mut Graph,
    query: String,
    parameters: Params,
    options: TransactionOptions,
    max_result_rows: usize,
    max_result_bytes: usize,
    result_reply: SyncSender<Result<QueryResult, BindingError>>,
    acknowledge: Receiver<bool>,
    finish: SyncSender<Result<(), BindingError>>,
) {
    let mut transaction = match graph.transaction_with_options(options) {
        Ok(transaction) => transaction,
        Err(error) => {
            let _ = result_reply.send(Err(BindingError::from(error)));
            return;
        }
    };
    let result = transaction
        .query(&query, parameters)
        .map_err(BindingError::from)
        .and_then(|result| {
            validate_result(&result, max_result_rows, max_result_bytes)?;
            Ok(result)
        });
    match result {
        Ok(result) => {
            if result_reply.send(Ok(result)).is_err() {
                return;
            }
            let commit = acknowledge.recv().unwrap_or(false);
            let completed = if commit {
                transaction.commit()
            } else {
                transaction.rollback()
            };
            let _ = finish.send(completed.map_err(BindingError::from));
        }
        Err(error) => {
            let _ = result_reply.send(Err(error));
        }
    }
}

fn validate_result(
    result: &QueryResult,
    max_rows: usize,
    max_bytes: usize,
) -> Result<(), BindingError> {
    if result.rows.len() > max_rows {
        return Err(BindingError::resource_limit(
            "query result exceeds the retained row limit",
        ));
    }
    let mut bytes = result
        .columns
        .iter()
        .try_fold(0_usize, |bytes, column| bytes.checked_add(column.len()))
        .ok_or_else(result_too_large)?;
    for row in &result.rows {
        if row.values.len() != result.columns.len() {
            return Err(BindingError::unsupported_value(
                "query result row width does not match its columns",
            ));
        }
        for value in &row.values {
            bytes = bytes
                .checked_add(estimated_value_bytes(value).ok_or_else(result_too_large)?)
                .ok_or_else(result_too_large)?;
            if bytes > max_bytes {
                return Err(result_too_large());
            }
        }
    }
    Ok(())
}

fn estimated_value_bytes(value: &Value) -> Option<usize> {
    match value {
        Value::Null | Value::Boolean(_) => Some(1),
        Value::Integer(_) | Value::Float(_) => Some(9),
        Value::String(value) => value.len().checked_add(5),
        Value::List(values) => estimated_values(values.iter()),
        Value::Map(values) => {
            let mut bytes = 5_usize;
            for (key, value) in values {
                bytes = bytes.checked_add(key.len().checked_add(5)?)?;
                bytes = bytes.checked_add(estimated_value_bytes(value)?)?;
            }
            Some(bytes)
        }
        Value::Node(node) => estimated_node_bytes(node),
        Value::Relationship(relationship) => estimated_relationship_bytes(relationship),
        Value::Path(path) => {
            let mut bytes = 5_usize;
            for node in &path.nodes {
                bytes = bytes.checked_add(estimated_node_bytes(node)?)?;
            }
            for relationship in &path.relationships {
                bytes = bytes.checked_add(estimated_relationship_bytes(relationship)?)?;
            }
            Some(bytes)
        }
        _ => None,
    }
}

fn estimated_node_bytes(node: &littlegraph_core::NodeValue) -> Option<usize> {
    let mut bytes = node.id.len().checked_add(16)?;
    for label in &node.labels {
        bytes = bytes.checked_add(label.len().checked_add(5)?)?;
    }
    for (key, value) in &node.properties {
        bytes = bytes.checked_add(key.len().checked_add(5)?)?;
        bytes = bytes.checked_add(estimated_value_bytes(value)?)?;
    }
    Some(bytes)
}

fn estimated_relationship_bytes(
    relationship: &littlegraph_core::RelationshipValue,
) -> Option<usize> {
    let mut bytes = relationship
        .id
        .len()
        .checked_add(relationship.start.len())?
        .checked_add(relationship.end.len())?
        .checked_add(relationship.r#type.len())?
        .checked_add(32)?;
    for (key, value) in &relationship.properties {
        bytes = bytes.checked_add(key.len().checked_add(5)?)?;
        bytes = bytes.checked_add(estimated_value_bytes(value)?)?;
    }
    Some(bytes)
}

fn estimated_values<'a>(values: impl IntoIterator<Item = &'a Value>) -> Option<usize> {
    values.into_iter().try_fold(5_usize, |bytes, value| {
        bytes.checked_add(estimated_value_bytes(value)?)
    })
}

fn result_too_large() -> BindingError {
    BindingError::resource_limit("query result exceeds the retained byte limit")
}