BoltR

A standalone, pure Rust implementation of the Bolt v5.x wire protocol - the binary protocol used by Neo4j and other graph databases for client-server communication.

Any Bolt-compatible database engine can plug in via the BoltBackend trait. BoltR handles TCP transport, PackStream encoding, session management, transactions, and the full Bolt type system over the wire.

Features

• Spec-faithful: Full Bolt v5.x protocol (5.1-5.4), all PackStream types, all message types
• Pure Rust: No C/C++ dependencies
• Lightweight: Minimal deps: tokio, bytes, thiserror, tracing
• Fast: Efficient PackStream encoding, chunked streaming
• Embeddable: Library-first design, usable by any Rust project
• TLS: Optional TLS via tls feature flag (tokio-rustls)
• Auth: Pluggable authentication via AuthValidator trait
• Observability: Structured tracing via tracing crate
• Graceful shutdown: Drain connections on signal

Quick Start

Add to your Cargo.toml:

[dependencies]
boltr = "0.1"

Implementing a Backend

Implement the BoltBackend trait to connect your database:

use boltr::server::{BoltBackend, SessionHandle, TransactionHandle, SessionConfig, ResultStream, BoltRecord};
use boltr::error::BoltError;

struct MyDatabase { /* ... */ }

#[async_trait::async_trait]
impl BoltBackend for MyDatabase {
    async fn create_session(&self, config: &SessionConfig) -> Result<SessionHandle, BoltError> {
        // Create a session in your database
        Ok(SessionHandle::new("session-1"))
    }

    async fn execute(
        &self,
        session: &SessionHandle,
        query: &str,
        parameters: &std::collections::HashMap<String, boltr::types::BoltValue>,
        transaction: Option<&TransactionHandle>,
    ) -> Result<Box<dyn ResultStream>, BoltError> {
        // Execute query and return a result stream
        todo!()
    }

    // ... other trait methods
}

Starting the Server

use boltr::server::BoltServer;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = MyDatabase::new();
    let addr = "127.0.0.1:7687".parse()?;

    BoltServer::builder(backend)
        .idle_timeout(Duration::from_secs(300))
        .max_sessions(1000)
        .shutdown(async { tokio::signal::ctrl_c().await.unwrap() })
        .serve(addr)
        .await?;

    Ok(())
}

Using the Client

Enable the client feature:

[dependencies]
boltr = { version = "0.1", features = ["client"] }

use boltr::client::BoltConnection;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut conn = BoltConnection::connect("127.0.0.1:7687").await?;
    let mut session = conn.create_session().await?;

    let records = session.run("MATCH (n:Person) RETURN n.name", HashMap::new()).await?;

    for record in records {
        println!("{record:?}");
    }

    session.close().await?;
    Ok(())
}

Architecture

Application (Cypher statements, parameters, results)
       |
       v
  Bolt Messages
  - Client: HELLO, LOGON, RUN, PULL, BEGIN, COMMIT, ROLLBACK, GOODBYE
  - Server: SUCCESS, RECORD, FAILURE, IGNORED
       |
       v
  PackStream Encoding
  - Full Bolt type system: scalars, graph elements, temporal, spatial
       |
       v
  Chunk Framing (2-byte length-prefixed)
       |
       v
  BoltBackend trait (your database plugs in here)

Bolt Type Support

Modules

Requirements

• Rust 1.85.0+ (edition 2024)

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.