Saltearse al contenido
NamiDB NamiDB

Bolt (drivers Neo4j)

NamiDB habla el protocolo Bolt a través de un listener TCP opcional en namidb-server. Cada driver oficial de Neo4j (Python, Java, JavaScript, .NET, Go, Rust) se conecta sin modificación a través de bolt://host:7687.

El diseño wire-level vive en RFC-022; el codec, el handshake y la state machine viven en el crate namidb-bolt.

Versiones negociadas

  • Bolt 4.4
  • Bolt 5.0
  • Bolt 5.4

El handshake (magic 0x6060B017 + cuatro version offers, con la forma range soportada) anuncia las tres; el driver elige la más alta que soporte.

Habilitar el listener

Ventana de terminal
namidb-server \
  --store memory://demo \
  --listen 0.0.0.0:8080 \
  --bolt-listen 0.0.0.0:7687 \
  --auth-token "$NAMIDB_AUTH_TOKEN"

--bolt-listen también está disponible como NAMIDB_BOLT_LISTEN. Tanto la API HTTP como el listener Bolt comparten un WriterSession por proceso y el mismo --auth-token.

Conectarse desde un driver Neo4j

El usuario es el string literal namidb; la contraseña es el mismo bearer token que la API HTTP. La superficie de credenciales coincide con lo que cada driver Neo4j espera.

from neo4j import GraphDatabase


driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    auth=("namidb", "$NAMIDB_AUTH_TOKEN"),
)


with driver.session() as s:
    s.run("CREATE (:Person {name: 'Alice'})")
    for record in s.run("MATCH (p:Person) RETURN p.name AS name"):
        print(record["name"])

La misma forma funciona con los demás drivers oficiales de Neo4j — el connection string y el tuple usuario / contraseña son lo único específico de NamiDB.

Vocabulario de mensajes soportado

namidb-bolt implementa el vocabulario completo de request y response de v4.4 / v5.0 / v5.4: HELLO, LOGON, LOGOFF, RUN, PULL, DISCARD, BEGIN, COMMIT, ROLLBACK, RESET, ROUTE, TELEMETRY, GOODBYE.

El mapeo de valores es una traducción total RuntimeValue ↔ Bolt Value, incluyendo:

  • Node, Relationship, UnboundRelationship, Path.
  • Date, LocalDateTime — datetime() / date() desde un driver round-trippean a los tipos nativos del driver (por ejemplo, neo4j.time.DateTime, neo4j.time.Date en Python). Este es el fix que aterrizó en [Unreleased] que cerró la pérdida de tipos del __overflow_json para properties Date / DateTime no declaradas.

Concurrencia

El listener Bolt comparte el WriterSession con la API HTTP. El invariante single-writer-per-namespace sigue válido: a lo sumo un statement de escritura en vuelo contra el namespace a la vez. Las lecturas comparten la misma snapshot cell que publica RFC-021.

Probarlo end-to-end

El repo incluye un script de smoke manual (tests/bolt_neo4j_driver_smoke.py) que maneja el driver oficial neo4j de PyPI contra un namidb-server corriendo y verifica un round-trip CREATE / MATCH.

El test de integración crates/namidb-server/tests/bolt_integration.rs ejecuta el mismo flujo contra un servidor in-process a través del handshake Bolt 5.4.

Siguientes pasos

  • Servidor HTTP — el daemon que hospeda el listener Bolt.
  • API HTTP — la superficie REST que comparte el mismo WriterSession y la misma autenticación.
  • Configuración — NAMIDB_BOLT_LISTEN y compañía.