// STRYKE-NEO4J — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

stryke-neo4j is an opt-in connector package in the stryke ecosystem — a Neo4j graph client exposing parametrized Cypher query and run, scalar/row helpers, and schema introspection as the Neo4j package, built on neo4rs, the pure-Rust Bolt driver.

neo4rs is async and pulls in tokio plus a TLS stack — a dependency tree that ships once, on demand, as an opt-in package. stryke core is never linked against it; the cdylib presents a blocking facade so every Neo4j::* call is an ordinary blocking call.

~ARCHITECTURE

A single in-process cdylib. The stryke side is a thin .stk library; the heavy driver code lives in libstryke_neo4j and is dlopened on first use Neo4j. No sidecar process, no fork per call.

~CAPABILITIES

The surface is scoped to "useful from a shell pipeline" — parametrized Cypher plus schema introspection, not full driver coverage.

Every one of the 44 functions is a thin .stk wrapper over a matching neo4j__* cdylib export — the wrapper count, the export list in stryke.toml, and the #[no_mangle] functions in src/lib.rs are kept in lockstep (44 / 44 / 44).

$WHY OPT-IN (NOT BUILTIN)

neo4rs pulls in tokio and a TLS stack. The core stryke binary stays slim precisely because each connector ships separately. Daily-driver work — one-liners, awk replacement, data scripting — doesn't need a Bolt driver or a graph client linked in.

&FFI PROTOCOL

JSON in, JSON out, over a C ABI. Each request is a JSON object of op-specific args; $name Cypher params are bound positionally, never interpolated into the query text. Each response is a JSON object; errors carry an error field. The C string returned by every export is freed through the shared stryke_free_cstring symbol.

neo4j__query('{"cypher":"MATCH (p:Person) WHERE p.id = $id RETURN p.name AS name",
              "params":{"id":1},"uri":"neo4j://localhost:7687","user":"neo4j"}')
  -> {"rows":[{"name":"Ada"}]}

# handler errors are surfaced, never thrown across the ABI
neo4j__query('{}')  ->  {"error":"missing cypher"}

/SCOPE

See the README's API reference and usage sections for the authoritative scope. The package is intentionally narrower than the underlying driver — the goal is "useful from a shell pipeline", not "complete API coverage". Live, credential-backed round-trips are exercised against a real Neo4j via the gated t/ tests.

+DEPENDENCIES

The crate is deliberately small: the Bolt driver plus a tokio runtime, JSON serialization for the FFI boundary, and the usual error / lazy-init helpers. Chosen for durability over fashion.

The release profile is tuned for a small, fast artifact: opt-level = 3, thin LTO, one codegen unit, symbols stripped, panic = "abort".

%TESTING

Two test tiers. The Rust unit tests in src/lib.rs cover the pure logic with no database — connection-key defaults, Bolt-URI parse / redact / build round-trips, identifier backtick-quoting (including injection attempts), string escaping, Cypher literal formatting, identifier validation, and the scalar-only property guard. The stryke t/ tests assert the full wrapper surface resolves via use Neo4j and exercise the pure URI helpers; the graph round-trips (write / query / point lookups / relationships / degree / counts / delete) are gated on $NEO4J_URL so CI without a server stays green.

CI runs cargo build, cargo fmt --check, cargo clippy -D warnings, cargo test on ubuntu + macos, a doc build, and a release build across targets. A set of documentation gates pins this site's HTML hygiene — valid structure, https-only links, no inline event handlers, no placeholder hrefs, rel="noopener" on every target="_blank", and a trailing newline.

#PROJECT METADATA