Gleanex.Config (Gleanex v0.1.0)

Copy Markdown View Source

Connection settings for a Glean deployment.

A config carries the backend domain, an API token and the transport knobs used for every request made with it.

Tokens are scoped

Glean issues separate tokens for the Client and Indexing APIs, and they are not interchangeable. Build one config per scope:

client = Gleanex.new(domain: "mycompany", token: client_token)
indexing = Gleanex.new(domain: "mycompany", token: indexing_token, scope: :indexing)

Using the wrong scope fails before the request is sent, with a clear message rather than an opaque 401.

Where settings come from

Highest precedence first:

  1. options passed to new/1

  2. application environment under :gleanex

  3. the GLEAN_API_TOKEN and GLEAN_INSTANCE environment variables

    config :gleanex, domain: "mycompany", token: {:system, "GLEAN_API_TOKEN"}

Domain and base URL

Glean serves each customer from https://{domain}-be.glean.com, where domain is usually the email domain without the TLD. The four APIs then live under different path prefixes, which this module appends for you.

:base_url overrides the host root only — always give it scheme and host with no path, for example https://mycompany-be.glean.com. The per-API prefix is still appended.

Summary

Types

api()

One of the four Glean APIs.

scope()

Which family of token this config holds.

t()

Functions

apis()

The list of known APIs.

base_url(config, api)

The full base URL for one of the four APIs, including its path prefix.

check_scope(config, api)

Check that this config's token scope can be used against api.

default()

Build a config from the application environment and system environment alone.

new(opts \\ [])

Build a config.

prefix(api)

The path prefix for an API, without the host.

Types

api()

@type api() :: :client | :indexing | :platform | :admin

One of the four Glean APIs.

scope()

@type scope() :: :client | :indexing

Which family of token this config holds.

t()

@type t() :: %Gleanex.Config{
  base_url: String.t() | nil,
  domain: String.t() | nil,
  receive_timeout: timeout(),
  req_options: keyword(),
  retry: Gleanex.Retry.t(),
  scope: scope(),
  token: String.t()
}

Functions

apis()

@spec apis() :: [api()]

The list of known APIs.

base_url(config, api)

@spec base_url(t(), api()) :: String.t()

The full base URL for one of the four APIs, including its path prefix.

iex> config = Gleanex.new(domain: "mycompany", token: "t")
iex> Gleanex.Config.base_url(config, :client)
"https://mycompany-be.glean.com/rest/api/v1"
iex> Gleanex.Config.base_url(config, :indexing)
"https://mycompany-be.glean.com/api/index/v1"

check_scope(config, api)

@spec check_scope(t(), api()) :: :ok | {:error, Gleanex.Error.t()}

Check that this config's token scope can be used against api.

Only the documented hard rule is enforced: Indexing tokens work against the Indexing API and nothing else, and Client tokens work everywhere except the Indexing API.

default()

@spec default() :: t()

Build a config from the application environment and system environment alone.

Used when an operation is called without an explicit :config option.

new(opts \\ [])

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

Build a config.

Raises Gleanex.Error when the token is missing, or when neither :domain nor :base_url can be resolved.

Options

  • :domain - backend subdomain, for example "mycompany". :instance is accepted as an alias, matching the Go SDK's WithInstance.
  • :base_url - host root override, skipping domain templating.
  • :token - API token. Defaults to GLEAN_API_TOKEN.
  • :scope - :client (default) or :indexing.
  • :retry - a Gleanex.Retry policy.
  • :receive_timeout - milliseconds to wait for a response, default 30_000.
  • :req_options - options passed straight through to Req.

prefix(api)

@spec prefix(api()) :: String.t()

The path prefix for an API, without the host.