TypeDB.GRPC.Server (TypeDB.GRPC v0.1.0)

What the server is, and whether this driver was built for it.

Summary

Types

server()

One server in the cluster, in the shape TypeDB.Server.servers/2 returns.

Functions

check_protocol(conn, opts \\ [])

Checks the server against the protocol version this driver was generated from.

check_protocol!(conn, opts \\ [])

Checks the protocol version, raising on a mismatch.

health(conn, opts \\ [])

Whether the server is reachable and answering.

health!(conn, opts \\ [])

Server reachability, raising on failure.

server(conn, opts \\ [])

The one server this connection is talking to.

server!(conn, opts \\ [])

This server, raising on failure.

servers(conn, opts \\ [])

Lists the servers in the cluster.

servers!(conn, opts \\ [])

The servers in the cluster, raising on failure.

version(conn, opts \\ [])

The server's distribution and version, as it reports them.

version!(conn, opts \\ [])

The server's version, raising on failure.

Types

server()

@type server() :: %{optional(String.t()) => term()}

One server in the cluster, in the shape TypeDB.Server.servers/2 returns.

String keys rather than atoms, and "address" rather than :address, because the sibling hands back TypeDB's JSON decoded as-is and a caller that switches transports should not have to rewrite its pattern matches. A stock single-server CE deployment reports %{"address" => nil} on both.

"replication_status" is present only when the server sends one — the HTTP API has no such field at all, so inventing a nil for it would be a difference between the transports rather than a fact about the server.

Functions

check_protocol(conn, opts \\ [])

@spec check_protocol(
  TypeDB.GRPC.Connection.t(),
  keyword()
) :: :ok | {:error, TypeDB.Error.t()}

Checks the server against the protocol version this driver was generated from.

Returns :ok, or {:error, %TypeDB.Error{kind: :config}} naming both versions. Nothing calls this on the hot path: it is for a boot-time check and for the integration suite, which is where a mismatch should be found.

A mismatch is not proof of breakage — protobuf tolerates a client built from an older schema — but it is proof that nobody has checked.

Since connection_open carries the protocol version, the server now performs the authoritative version check itself and refuses a driver it cannot speak to. This one compares the two strings, which is a different and weaker question — it catches a generated protocol that has drifted from the server even when both ends still interoperate — and it is why the integration suite keeps calling it.

check_protocol!(conn, opts \\ [])

@spec check_protocol!(term(), term()) :: :ok

Checks the protocol version, raising on a mismatch.

health(conn, opts \\ [])

@spec health(
  TypeDB.GRPC.Connection.t(),
  keyword()
) :: :ok | {:error, TypeDB.Error.t()}

Whether the server is reachable and answering.

There is no dedicated health RPC in the protocol, so this asks for the version — the cheapest call that proves a round trip, and the same thing TypeDB's own drivers use for the purpose.

health!(conn, opts \\ [])

@spec health!(term(), term()) :: :ok

Server reachability, raising on failure.

server(conn, opts \\ [])

@spec server(
  TypeDB.GRPC.Connection.t(),
  keyword()
) :: {:ok, server()} | {:error, TypeDB.Error.t()}

The one server this connection is talking to.

servers/2 asks about the cluster; this asks about the node on the other end of this channel, which is the one whose replication role decides whether a write here is a write at all. The sibling has no counterpart — the HTTP API exposes only the list.

server!(conn, opts \\ [])

@spec server!(term(), term()) :: server()

This server, raising on failure.

servers(conn, opts \\ [])

@spec servers(
  TypeDB.GRPC.Connection.t(),
  keyword()
) :: {:ok, [server()]} | {:error, TypeDB.Error.t()}

Lists the servers in the cluster.

A single-server deployment reports one entry. The same caveat as the sibling's TypeDB.Server.servers/2: fields vary by distribution, so what the server said is what you get.

servers!(conn, opts \\ [])

@spec servers!(term(), term()) :: [server()]

The servers in the cluster, raising on failure.

version(conn, opts \\ [])

@spec version(
  TypeDB.GRPC.Connection.t(),
  keyword()
) ::
  {:ok, %{distribution: String.t(), version: String.t()}}
  | {:error, TypeDB.Error.t()}

The server's distribution and version, as it reports them.

{:ok, %{distribution: "TypeDB CE", version: "3.12.1"}}

version!(conn, opts \\ [])

@spec version!(term(), term()) :: %{distribution: String.t(), version: String.t()}

The server's version, raising on failure.