TypeDB.GRPC.Config (TypeDB.GRPC v0.1.0)

A connection's settings, validated once at start-up.

Deliberately smaller than TypeDB.Config. That one carries a transport choice, a JSON codec, a retry policy and a status list, because the HTTP driver has three interchangeable adapters and retries requests itself. Here there is one transport, and a request lives on a transaction stream whose failure destroys the transaction — so there is nothing a per-request retry could correctly re-send.

Summary

Types

t()

Functions

new(opts)

Builds a config from start_link/1 options.

new!(opts)

Builds a config, raising on invalid options.

plaintext_to_remote?(config)

Whether this connection would send credentials in clear text to another machine.

ssl_options(config)

The options this config hands to :ssl.

Types

t()

@type t() :: %TypeDB.GRPC.Config{
  address: String.t(),
  call_timeout: timeout(),
  connect_retries: non_neg_integer(),
  connect_timeout: timeout(),
  name: atom(),
  password: String.t() | nil,
  static_token: String.t() | nil,
  timeout: timeout(),
  tls: boolean(),
  tls_opts: keyword(),
  tls_root_ca: Path.t() | nil,
  username: String.t() | nil
}

Functions

new(opts)

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

Builds a config from start_link/1 options.

Options

:name — the registered name, required; it is also the ETS table
:address — "host:port", TypeDB's gRPC port being 1729. :url is accepted as a synonym and parsed, so the same configuration that feeds the HTTP driver can feed this one
:username / :password — credentials to sign in with
:token — a pre-issued token, instead of credentials. Nothing renews it
:tls — TLS for the channel, defaulting to false — which is what TypeDB CE ships with — except when :url names an https:// one, where it defaults to true. A scheme is an instruction, and reading it as decor would hand a password to whoever answers the port. An explicit :tls wins over both. With nothing else set, the certificate is verified against this machine's trust store, which is what makes tls: true enough for a server whose certificate a public CA signed. The option exists because :ssl does not do that on its own: verify_peer with no cacerts refuses every certificate, including good ones
:tls_root_ca — a PEM file to verify against instead of the machine's store, for a private CA. The counterpart of Rust's DriverTlsConfig::enabled_with_root_ca/1; checked at start-up, so a path that is not there fails the connection rather than the handshake
:tls_opts — options passed straight to :ssl, and the last word: what it sets is never overwritten by the two above. The escape hatch for client certificates, a pinned cipher list, or verify: :verify_none
:timeout — per-call timeout in ms, default 60 s
:call_timeout — how long to wait on the connection process itself when it has to mint a token, default 30 s. Worth knowing because a per-call :timeout does not cover it: the first call on a connection signs in first, and that wait is bounded by this rather than by the option the caller passed
:connect_timeout — how long to wait for the channel to come up, default 10 s, matching TypeDB.Config. It bounds the case a retry count cannot: a plaintext client against a TLS port completes its TCP connection and then waits, because the server is waiting for a handshake that will never arrive. Without this the wait is minutes
:connect_retries — how many times the transport retries establishing the channel, default 0. The adapter's own default is 100, which turns a wrong CA or a wrong port into a wait of tens of seconds ending in :timeout — a failure that reads as "the server is slow" when it is really "this will never work". Raise it for a server that is expected to come up after the application does

new!(opts)

@spec new!(keyword()) :: t()

Builds a config, raising on invalid options.

plaintext_to_remote?(config)

@spec plaintext_to_remote?(t()) :: boolean()

Whether this connection would send credentials in clear text to another machine.

tls: false is the default and it is the right one for TypeDB CE, which ships with encryption off and is usually on the same host. It is the wrong one the moment the server is somewhere else, and nothing else in the driver is in a position to notice — Rust cannot have this problem because DriverOptions::new/1 takes the TLS configuration as a required argument.

So the default stays and TypeDB.GRPC.Connection says so once, at start-up, for an address that is not loopback.

ssl_options(config)

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

The options this config hands to :ssl.

Where :tls, :tls_root_ca and :tls_opts become one keyword list, and the place the machine's trust store is read. Separate from the struct on purpose: the store is a hundred and fifty certificates, and putting them in a struct that lives in ETS and gets inspected in error messages would be a poor trade for something :ssl wants once per connection.