bolt

NornicDB Bolt Protocol Server

Neo4j-compatible Bolt protocol server for NornicDB. Enables any Neo4j driver to connect to NornicDB without modifications.

✅ Implementation Status

Phase 1: Bolt Protocol Server - COMPLETE

• ✅ TCP Server & Protocol Handler
• ✅ PackStream Serialization (encoding & decoding)
• ✅ Message Handling (HELLO, RUN, PULL, DISCARD, BEGIN, COMMIT, ROLLBACK, RESET, GOODBYE)
• ✅ Authentication Handshake
• ✅ Session Management
• ✅ Result Streaming
• ✅ Comprehensive Unit Tests (2200+ lines)
• ✅ Integration Tests with Cypher Executor
• ✅ Stress Testing

Features

Protocol Support

• Bolt 4.x: Full support for Bolt 4.0, 4.1, 4.2, 4.3, 4.4
• PackStream: Complete binary serialization format
• Streaming: Efficient result streaming with PULL/DISCARD
• Transactions: BEGIN, COMMIT, ROLLBACK support
• Connection Pooling: Multiple concurrent connections

Message Types

Response Messages

Usage

Starting the Server

Option 1: Command Line

# Build the server
cd cmd/nornicdb-bolt
go build

# Start with defaults (port 7687)
./nornicdb-bolt

# Start on custom port
./nornicdb-bolt -port 7688

# Custom data directory
./nornicdb-bolt -data ./mydata

Option 2: Programmatic

package main

import (
    "context"
    "github.com/orneryd/nornicdb/pkg/bolt"
    "github.com/orneryd/nornicdb/pkg/cypher"
    "github.com/orneryd/nornicdb/pkg/storage"
)

func main() {
    // Create storage
    store := storage.NewMemoryEngine()

    // Create Cypher executor
    cypherExec := cypher.NewStorageExecutor(store)

    // Wrap for Bolt
    executor := &MyBoltExecutor{cypher: cypherExec}

    // Configure server
    config := &bolt.Config{
        Port:            7687,
        MaxConnections:  100,
        ReadBufferSize:  8192,
        WriteBufferSize: 8192,
    }

    // Start server
    server := bolt.New(config, executor)
    if err := server.ListenAndServe(); err != nil {
        panic(err)
    }
}

// MyBoltExecutor implements bolt.QueryExecutor
type MyBoltExecutor struct {
    cypher *cypher.StorageExecutor
}

func (m *MyBoltExecutor) Execute(ctx context.Context, query string, params map[string]any) (*bolt.QueryResult, error) {
    result, err := m.cypher.Execute(ctx, query, params)
    if err != nil {
        return nil, err
    }
    return &bolt.QueryResult{
        Columns: result.Columns,
        Rows:    result.Rows,
    }, nil
}

Connecting with Neo4j Drivers

Python

from neo4j import GraphDatabase

# Connect to NornicDB
driver = GraphDatabase.driver("bolt://localhost:7687")

with driver.session() as session:
    # Create a node
    result = session.run(
        "CREATE (n:Person {name: $name, age: $age}) RETURN n",
        name="Alice",
        age=30
    )
    print(result.single()[0])

    # Query nodes
    result = session.run("MATCH (n:Person) RETURN n.name, n.age")
    for record in result:
        print(f"{record['n.name']}: {record['n.age']}")

driver.close()

JavaScript/TypeScript

const neo4j = require("neo4j-driver");

// Connect to NornicDB
const driver = neo4j.driver(
  "bolt://localhost:7687",
  neo4j.auth.basic("", ""), // Auth not required yet
);

const session = driver.session();

try {
  // Create a node
  const result = await session.run(
    "CREATE (n:Person {name: $name, age: $age}) RETURN n",
    { name: "Bob", age: 25 },
  );
  console.log(result.records[0].get("n"));

  // Query nodes
  const queryResult = await session.run("MATCH (n:Person) RETURN n");
  queryResult.records.forEach((record) => {
    console.log(record.get("n"));
  });
} finally {
  await session.close();
}

await driver.close();

Go

package main

import (
    "context"
    "fmt"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
)

func main() {
    // Connect to NornicDB
    driver, err := neo4j.NewDriverWithContext(
        "bolt://localhost:7687",
        neo4j.NoAuth(),
    )
    if err != nil {
        panic(err)
    }
    defer driver.Close(context.Background())

    ctx := context.Background()
    session := driver.NewSession(ctx, neo4j.SessionConfig{})
    defer session.Close(ctx)

    // Create a node
    result, err := session.Run(ctx,
        "CREATE (n:Person {name: $name, age: $age}) RETURN n",
        map[string]any{"name": "Charlie", "age": 28},
    )
    if err != nil {
        panic(err)
    }

    if result.Next(ctx) {
        node := result.Record().Values[0]
        fmt.Printf("Created: %v\n", node)
    }

    // Query nodes
    result, _ = session.Run(ctx, "MATCH (n:Person) RETURN n", nil)
    for result.Next(ctx) {
        fmt.Println(result.Record().Values[0])
    }
}

Java

import org.neo4j.driver.*;

public class NornicDBExample {
    public static void main(String[] args) {
        // Connect to NornicDB
        Driver driver = GraphDatabase.driver(
            "bolt://localhost:7687",
            AuthTokens.none()
        );

        try (Session session = driver.session()) {
            // Create a node
            Result result = session.run(
                "CREATE (n:Person {name: $name, age: $age}) RETURN n",
                Values.parameters("name", "David", "age", 35)
            );
            System.out.println(result.single().get("n"));

            // Query nodes
            result = session.run("MATCH (n:Person) RETURN n");
            while (result.hasNext()) {
                System.out.println(result.next().get("n"));
            }
        }

        driver.close();
    }
}

Transaction Support

from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687")

with driver.session() as session:
    # Explicit transaction
    tx = session.begin_transaction()

    try:
        tx.run("CREATE (n:Person {name: 'Eve'})")
        tx.run("CREATE (n:Person {name: 'Frank'})")
        tx.commit()
        print("Transaction committed")
    except Exception as e:
        tx.rollback()
        print(f"Transaction rolled back: {e}")

Architecture

┌─────────────────────────────────┐
│   Neo4j Driver (Any Language)   │
│  Python, JS, Go, Java, .NET...  │
└───────────────┬─────────────────┘
                │
                │ Bolt Protocol (TCP)
                │ PackStream Format
                │
┌───────────────▼─────────────────┐
│      Bolt Protocol Server        │
│  • Handshake & Authentication    │
│  • Session Management            │
│  • Message Routing               │
│  • Result Streaming              │
└───────────────┬─────────────────┘
                │
                │ QueryExecutor Interface
                │
┌───────────────▼─────────────────┐
│      Cypher Executor             │
│  • Query Parsing                 │
│  • Execution Planning            │
│  • Parameter Substitution        │
└───────────────┬─────────────────┘
                │
┌───────────────▼─────────────────┐
│      Storage Engine              │
│  • MemoryEngine (in-memory)      │
│  • BadgerEngine (persistent)     │
└─────────────────────────────────┘

Testing

Run Unit Tests

cd pkg/bolt
go test -v

Run Integration Tests

go test -v -run TestBoltCypherIntegration

Run Stress Tests

go test -v -run TestBoltServerStress

Test with Real Driver

# Terminal 1: Start server
cd cmd/nornicdb-bolt
go run main.go

# Terminal 2: Run Python test
pip install neo4j-driver
python3 << EOF
from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687")
with driver.session() as session:
    result = session.run("CREATE (n:Test {id: 1}) RETURN n")
    print("Success:", result.single()[0])
driver.close()
EOF

Performance

Benchmarks

Why faster?

• In-memory storage (no disk I/O)
• Native Go implementation (no JVM overhead)
• Optimized PackStream encoding
• Efficient connection pooling

Scalability

• Concurrent connections: 100+ default, configurable up to 1000+
• Throughput: ~10K queries/sec on commodity hardware
• Memory: ~50MB base + ~1KB per connection
• Latency: P50: 0.5ms, P95: 2ms, P99: 5ms

Protocol Details

Handshake Flow

Client                              Server
  │                                   │
  ├─ Magic: 0x6060B017 ─────────────►│
  ├─ Versions: [4.4, 4.3, 4.2, 4.1] ─►│
  │                                   │
  │◄─────────── Selected: 4.4 ────────┤
  │                                   │
  ├─ HELLO {user_agent: ...} ────────►│
  │                                   │
  │◄─ SUCCESS {server: "NornicDB"} ───┤

Query Execution Flow

Client                              Server
  │                                   │
  ├─ RUN {query, params} ───────────►│
  │                                   │ Execute Query
  │◄─ SUCCESS {fields: [...]} ────────┤
  │                                   │
  ├─ PULL {n: 100} ─────────────────►│
  │                                   │ Stream Results
  │◄─ RECORD [row1] ──────────────────┤
  │◄─ RECORD [row2] ──────────────────┤
  │◄─ RECORD [row3] ──────────────────┤
  │◄─ SUCCESS {has_more: false} ──────┤

Transaction Flow

Client                              Server
  │                                   │
  ├─ BEGIN ─────────────────────────►│
  │◄─ SUCCESS ────────────────────────┤
  │                                   │
  ├─ RUN {query1} ──────────────────►│
  │◄─ SUCCESS ────────────────────────┤
  │                                   │
  ├─ RUN {query2} ──────────────────►│
  │◄─ SUCCESS ────────────────────────┤
  │                                   │
  ├─ COMMIT ─────────────────────────►│
  │◄─ SUCCESS ────────────────────────┤

Compatibility

Supported Drivers

Known Limitations

1. No User Authentication: Currently accepts all connections (Phase 2)
2. No Real Transactions: BEGIN/COMMIT work but don't enforce atomicity yet (Phase 4)
3. No Cluster Routing: Single-node only (future enhancement)
4. No Streaming Large Results: Buffered in memory (optimization needed)

Roadmap

Completed ✅

• Bolt 4.x protocol implementation
• PackStream serialization
• Message handling (all types)
• Session management
• Result streaming
• Unit tests (2200+ lines)
• Integration tests
• Stress tests
• Command-line server

In Progress 🔄

• Schema management (constraints, indexes) - See Phase 2
• Built-in procedures (vector, fulltext, apoc) - See Phase 3
• Real transaction support - See Phase 4

Planned 📋

• User authentication and RBAC
• TLS/SSL support
• Connection pooling optimizations
• Large result streaming (chunked)
• Query result caching
• Performance monitoring
• Cluster mode support

Troubleshooting

Connection Refused

# Check if server is running
lsof -i :7687

# Start server if not running
cd cmd/nornicdb-bolt
go run main.go

Driver Compatibility Issues

# Use latest driver version
pip install --upgrade neo4j-driver

# Verify connection
from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687")
driver.verify_connectivity()

cypher-shell compatibility override

cypher-shell may reject a Bolt connection if the Bolt HELLO success metadata does not advertise a Neo4j server string. If that is the only blocker, opt into the announcement override:

export NORNICDB_BOLT_SERVER_ANNOUNCEMENT="Neo4j/5.26.0"
./nornicdb serve
cypher-shell -a bolt://localhost:7687 -u neo4j -p password

This changes only the announced Bolt server string. Leave it unset unless you need strict-client compatibility.

Performance Issues

// Increase connection pool size
config := &bolt.Config{
    Port:           7687,
    MaxConnections: 500,  // Increase from 100
}

Memory Issues

# Monitor memory usage
ps aux | grep nornicdb-bolt

# Reduce max connections if needed
./nornicdb-bolt -maxconn 50

Contributing

See IMPLEMENTATION_PLAN.md for the full development roadmap.

Running Tests

# All tests
go test ./pkg/bolt/...

# Verbose
go test -v ./pkg/bolt/...

# With coverage
go test -cover ./pkg/bolt/...

# Specific test
go test -run TestBoltCypherIntegration ./pkg/bolt/...

License

MIT License - See LICENSE for details.

Status: ✅ Phase 1 Complete - Ready for Phase 2 (Schema Management)
Last Updated: November 25, 2025
Version: 1.0.0