GWP

A standalone, pure Rust gRPC wire protocol for GQL (ISO/IEC 39075) - the international standard query language for property graphs.

Any GQL-compatible database engine can plug in via the GqlBackend trait. GWP handles gRPC transport, session management, transactions, and the full GQL type system over the wire.

Features

• Spec-faithful: Full GQL type system, GQLSTATUS codes, session/transaction semantics
• Pure Rust: No C/C++ dependencies, #![forbid(unsafe_code)]
• Lightweight: Minimal deps: tonic, prost, tokio
• Fast: Streaming results via server-side gRPC streaming
• Embeddable: Library-first design, usable by any Rust project
• TLS: Optional TLS via tls feature flag (rustls)
• Auth: Pluggable authentication via AuthValidator trait
• Health checks: Standard grpc.health.v1.Health service
• Observability: Structured tracing on all gRPC methods via tracing crate
• Graceful shutdown: Drain connections on signal with .shutdown()

Quick Start

Add to your Cargo.toml:

[dependencies]
gwp = "0.1"

Implementing a Backend

Implement the GqlBackend trait to connect your database:

use gwp::server::{GqlBackend, SessionHandle, TransactionHandle, SessionConfig};
use gwp::error::GqlError;

struct MyDatabase { /* ... */ }

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

    async fn execute(
        &self,
        session: &SessionHandle,
        statement: &str,
        parameters: &std::collections::HashMap<String, gwp::types::Value>,
        transaction: Option<&TransactionHandle>,
    ) -> Result<std::pin::Pin<Box<dyn gwp::server::ResultStream>>, GqlError> {
        // Execute GQL and return a result stream
        todo!()
    }

    // ... other trait methods
}

Starting the Server

use gwp::server::GqlServer;
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:50051".parse()?;

    // Quick start with ctrl-c shutdown
    GqlServer::start(backend, addr).await?;

    Ok(())
}

Or use the builder for full control:

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

Using the Client

use gwp::client::GqlConnection;
use std::collections::HashMap;

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

    let mut cursor = session.execute("MATCH (n:Person) RETURN n.name", HashMap::new()).await?;

    while let Some(row) = cursor.next_row().await? {
        println!("{row:?}");
    }

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

Architecture

Application (GQL statements, parameters, results)
       |
       v
  gRPC Services
  - SessionService:  handshake, configure, reset, close, ping
  - GqlService:      execute, begin_transaction, commit, rollback
  - DatabaseService: list, create, delete, get_info
  - HealthService:   grpc.health.v1.Health (check, watch)
       |
       v
  Protocol Buffers (prost)
  - Full GQL type system: Value, Node, Edge, Path, Record
  - GQLSTATUS codes for structured error reporting
       |
       v
  GqlBackend trait (your database plugs in here)

GQL Type Support

Modules

Client Bindings

All bindings include GqlConnection, GqlSession, Transaction, ResultCursor, and DatabaseClient.

Requirements

• Rust 1.85.0+ (edition 2024)
• protoc (Protocol Buffers compiler) - required at build time

License

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