Module Neodriver_eio.ConnSource

A minimal Bolt connection (connect, authenticate, RUN/PULL/DISCARD, transactions).

Minimal Bolt connection: TCP connect (+ optional TLS) + handshake + HELLO/auth + state machine.

See conn.ml for the implementation.

Sourcetype auth = {
  1. scheme : string;
  2. principal : string;
  3. credentials : string;
}

Authentication token sent in HELLO (Bolt <= 5.0) or LOGON (Bolt >= 5.1). Only the basic scheme is supported so far.

Sourcetype config = {
  1. host : string;
  2. port : int;
  3. scheme : Neodriver_core.Addressing.scheme;
  4. connection_timeout : float;
  5. user_agent : string;
  6. auth : auth;
}

Target connection settings. The scheme selects TLS: Bolt plain, Bolt_secure TLS with certificate validation, Bolt_self_signed TLS without validation. Routing schemes (Neo4j*) are rejected until routing is implemented.

Sourcetype t

An established, authenticated Bolt connection: the transport, the negotiated protocol version and the tracked server state.

Sourceval default_user_agent : string

Default user_agent header for HELLO.

Sourceval basic_auth : ?principal:string -> ?credentials:string -> unit -> auth

The basic authentication token (scheme = "basic"), with the given principal (default neo4j) and credentials (default empty).

Sourceval connect : ?resolver: (Neodriver_core.Addressing.t -> (Neodriver_core.Addressing.t list, Neodriver_core.Errors.t) result) -> [> `Network | `Platform of [> `Generic ] ] Eio.Resource.t -> Mtime.t Eio.Time.clock_ty Eio.Resource.t -> Eio.Switch.t -> config -> (t, Neodriver_core.Errors.t) result

Establish a connection (over TLS when the scheme requires it), negotiate the Bolt protocol version and authenticate. resolver replaces the address lookup: the address built from config is passed to it and each returned address is tried in turn (first success wins, errors are aggregated). Without resolver, the single configured address is used. An IPv6 literal in config.host is treated as such (the address is built with brackets around the host). For Bolt >= 5.1 the authentication is sent via LOGON after HELLO; for older versions it is inline in HELLO. clock bounds the whole attempt and subsequent reads/writes by config.connection_timeout.

  • returns

    Error _ for connection/handshake failures, for routing schemes (unsupported until routing is implemented), or for an authentication failure reported by the server.

The resolved address the connection is established with.

Sourceval version : t -> int * int

The negotiated protocol version (major, minor).

Sourceval server_state : t -> State.t

The tracked server protocol state.

Sourceval reset : t -> (unit, Neodriver_core.Errors.t) result

Send a RESET and wait for the response; the server returns to Ready.

Sourceval logon : t -> auth -> (unit, Neodriver_core.Errors.t) result

Re-authenticate with auth via LOGON (Bolt >= 5.1 only). A RESET is sent first if the server is in the Failed state.

  • returns

    Error _ for older protocol versions or on server failure.

Sourceval logoff : t -> (unit, Neodriver_core.Errors.t) result

De-authenticate via LOGOFF (Bolt >= 5.1 only). A RESET is sent first if the server is in the Failed state.

  • returns

    Error _ for older protocol versions or on server failure.

Sourceval close : t -> unit

Close the connection.

A fresh hydration scope for the connection's protocol version.

Sourcetype run_metadata = {
  1. fields : string list;
  2. qid : int option;
  3. bookmark : string option;
  4. t_first : int option;
}

Metadata of a RUN response: the result's field names, the query id (for multiple results), the bookmark reported for an auto-commit transaction (if any) and the t_first timing (result available-after, milliseconds).

Sourceval run : ?mode:Neodriver_core.Config.access_mode -> ?db:string -> ?bookmarks:string list -> ?timeout:float -> ?metadata:(string * Neodriver_core.Values.t) list -> t -> hydration:Neodriver_core.Hydration.t -> query:string -> parameters:(string * Neodriver_core.Values.t) list -> (run_metadata, Neodriver_core.Errors.t) result

Send a RUN message for query. parameters are dehydrated with hydration. The optional mode, db, bookmarks, timeout (seconds) and metadata (tx_metadata) go into the request's extra map.

  • returns

    Error _ if the server fails the request (the connection enters Failed and is RESET before the next request).

Sourceval begin_ : t -> extra:Neodriver_packstream.Packstream.value -> (unit, Neodriver_core.Errors.t) result

Send a BEGIN message (start a transaction) with the given extra map (see build_extra). A RESET is sent first if the server is in the Failed state.

Sourceval build_extra : ?mode:Neodriver_core.Config.access_mode -> ?db:string -> ?imp_user:string -> ?bookmarks:string list -> ?timeout:float -> ?metadata:(string * Neodriver_packstream.Packstream.value) list -> unit -> Neodriver_packstream.Packstream.value

The extra map for BEGIN (and auto-commit RUN): mode (Read -> "r"), db, imp_user, bookmarks, timeout (seconds, sent as tx_timeout milliseconds) and metadata (tx_metadata, already dehydrated).

Send a COMMIT message (end the transaction, applying its writes). Returns the full response metadata (its bookmark entry records the commit position).

Sourceval rollback : t -> (unit, Neodriver_core.Errors.t) result

Send a ROLLBACK message (end the transaction, discarding its writes). On a Failed connection the server already discarded the transaction implicitly, so a RESET is sent instead.

Send a PULL message, fetching up to n records (all by default) of the result qid. Records are hydrated with hydration. Returns the records delivered and the terminal outcome: Ok _ with the PULL summary metadata (its has_more flag, readable via Bolt.metadata_has_more, says whether more records remain) on SUCCESS, or Error _ for a server FAILURE (the records delivered before the failure are kept). A server failure leaves the connection in the Failed state.

Sourceval discard : ?n:int -> ?qid:int -> t -> (unit, Neodriver_core.Errors.t) result

Send a DISCARD message, discarding up to n remaining records (all by default) of the result qid. A server failure is surfaced as Error _.

Sourcetype stream

A lazily-streamed result on a connection: RUN is sent immediately, records are pulled in batches on demand. The terminal state is a summary (normal end) or an error (a server failure, surfaced after the buffered records are consumed).

Sourceval stream : ?on_complete:(Neodriver_packstream.Packstream.value -> unit) -> t -> hydration:Neodriver_core.Hydration.t -> run_metadata:run_metadata -> stream

A fresh stream for the given connection, hydration scope and RUN metadata. on_complete fires with the final summary once the stream ends normally.

Sourceval connection : stream -> t

The connection the stream is running on.

Sourceval buffered : stream -> Neodriver_core.Values.t list list

The records buffered so far, in order.

Sourceval has_more : stream -> bool

Whether the stream still has records to pull.

A server failure that interrupted the stream.

The final PULL summary metadata, once the stream has ended normally.

Sourceval run_metadata : stream -> run_metadata

The RUN metadata (field names, query id, timings, bookmark).

Sourceval pull_stream : ?n:int -> stream -> (Neodriver_core.Values.t list list, Neodriver_core.Errors.t) result

Pull up to n more records (all by default), buffering them, and return the newly fetched records. A server failure mid-stream is stored on the stream (error) and the records delivered before it are kept. Once the stream ends normally, its summary is stored.

  • returns

    Error _ for transport failures.

Sourceval server_agent : t -> string option

The server agent string reported in the HELLO response, if any.

The protocol capabilities of the connection's version.

Sourceval current_auth : t -> auth option

The authentication token the connection is currently logged on with, if any.

Sourceval re_auth : t -> auth -> (bool, Neodriver_core.Errors.t) result

Re-authenticate when auth differs from the current token (LOGOFF then LOGON, Bolt >= 5.1). Returns whether the token changed (false when it is the same as the current one).

  • returns

    Error _ for older protocol versions or on server failure.

Sourceval mark_unauthenticated : t -> unit

Forget the current token (the next re_auth will log on again).