A supervised connection to a TypeDB server.

A connection process owns exactly two things: the configuration and the current access token. It does not proxy requests — HTTP calls run in the caller's process, reading configuration from a :read_concurrency ETS table owned by this process. A slow query therefore never blocks anything else.

The process is consulted only when the token has to be minted or renewed, and it collapses concurrent renewals into a single sign-in.

Starting

Put it in your supervision tree:

children = [
  {TypeDB,
   url: "http://localhost:8000",
   username: "admin",
   password: System.fetch_env!("TYPEDB_PASSWORD")}
]

Or start several, each under its own name:

{TypeDB, name: :analytics, url: "http://analytics:8000", ...}
{TypeDB, name: :ingest,    url: "http://ingest:8000",    ...}

Every API function takes that name as its first argument.

Token lifecycle

TypeDB issues expiring JWTs. This driver:

• acquires one lazily, on the first request that needs it;
• reads the token's own lifetime from its JWT claims and renews it before it expires, so ordinary traffic never spends a round trip discovering a 401;
• still renews reactively when a 401 arrives anyway — a clock skew, a revoked token, a restarted server — and retries the failed request;
• collapses concurrent renewals: whoever reaches the connection first signs in, and everyone queued behind takes that token.

:max_auth_renewals bounds how many times a single request will go around the renew-and-retry loop before surfacing the error.

When a connection is configured with a pre-issued :token there is nothing to renew, and expiry surfaces as %TypeDB.Error{kind: :unauthenticated}.