View Source Goth (Goth v1.4.2)

A Goth token server.

Summary

Functions

Returns a specification to start this module under a supervisor.

Fetches the token from the cache.

Fetches the token, erroring if it is missing.

Starts the server.

Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

fetch(name, timeout \\ 5000)

View Source (since 1.3.0)

Fetches the token from the cache.

If the token is not in the cache, this function blocks for timeout milliseconds (defaults to 5000) while it is attempted to fetch it in the background.

To fetch the token bypassing the cache, see Goth.Token.fetch/1.

Link to this function

fetch!(name, timeout \\ 5000)

View Source (since 1.3.0)

Fetches the token, erroring if it is missing.

See fetch/2 for more information.

Link to this function

start_link(opts)

View Source (since 1.3.0)

Starts the server.

When the server is started, we attempt to fetch the token and store it in internal cache. If we fail, we'll retry with backoff.

Options

  • :name - a unique name to register the server under. It can be any term.

  • :source - the source to retrieve the token from.

    Supported values include:

    • {:service_account, credentials} - fetch token using service account credentials

    • {:refresh_token, credentials} - fetch token using refresh token

    • :metadata - fetching token using Google internal metadata service

    If :source is not set, Goth will:

    • Check application environment. You can set it with: config :goth, json: File.read!("credentials.json").

    • Check GOOGLE_APPLICATION_CREDENTIALS env variable that contains path to credentials file.

    • Check GOOGLE_APPLICATION_CREDENTIALS_JSON env variable that contains credentials JSON.

    • Check ~/.config/gcloud/application_default_credentials.json file.

    • Check ~/.config/gcloud/configurations/config_default for project id and email address for SDK users.

    • Check Google internal metadata service

    • Otherwise, raise an error.

    See documentation of the "Source" section in Goth.Token.fetch/1 documentation for more information.

  • :refresh_before - Time in seconds before the token is about to expire that it is tried to be automatically refreshed. Defaults to 300 (5 minutes).

  • :http_client - a function that makes the HTTP request. Defaults to using built-in integration with Finch

    See documentation of the :http_client option in Goth.Token.fetch/1 for more information.

  • :prefetch - how to prefetch the token when the server starts. The possible options are :async to do it asynchronously or :sync to do it synchronously (that is, the server doesn't start until an attempt to fetch the token was made). Defaults to :async.

  • :max_retries - the maximum number of retries (default: 10)

  • :retry_delay - a function that receives the retry count (starting at 0) and returns the delay, the number of milliseconds to sleep before making another attempt. Defaults to a simple exponential backoff capped at 30s: 1s, 2s, 4s, 8s, 16s, 30s, 30s, ...

Examples

Generate a token using a service account credentials file:

iex> credentials = "credentials.json" |> File.read!() |> Jason.decode!()
iex> {:ok, _} = Goth.start_link(name: MyApp.Goth, source: {:service_account, credentials, []})
iex> Goth.fetch!(MyApp.Goth)
%Goth.Token{...}

Retrieve the token using a refresh token:

iex> credentials = "credentials.json" |> File.read!() |> Jason.decode!()
iex> {:ok, _} = Goth.start_link(name: MyApp.Goth, source: {:refresh_token, credentials, []})
iex> Goth.fetch!(MyApp.Goth)
%Goth.Token{...}

Retrieve the token using the Google metadata server:

iex> {:ok, _} = Goth.start_link(name: MyApp.Goth, source: {:metadata, []})
iex> Goth.fetch!(MyApp.Goth)
%Goth.Token{...}