voauth

OAuth2 access-token vault for Gleam. Proactive refresh, bounded retry, typed errors.

What's voauth?

When you call an OAuth2 API you have to renew the access token before it expires. Done well, that needs a long-lived process holding the current token, a timer to refresh before expiry, retry on transient failures, and a way to tell the UI "the user has to reconnect" when the refresh token gets revoked.

voauth is that process. You write the bit that talks to your provider's /oauth2/token endpoint; voauth handles the rest.

Installation

gleam add voauth

Quickstart

import gleam/option.{Some}
import voauth

pub fn main() {
  // 1. Build a config with sane defaults; override what you need.
  let config =
    voauth.config(refresh: my_refresh_function)
    |> voauth.with_on_refresh(my_persist_callback)

  // 2. Start the vault.
  let assert Ok(vault) = voauth.start(config)

  // 3. After OAuth (or rehydrating from your DB), install a token.
  voauth.set_token(vault, voauth.Token(
    access_token: "...",
    expires_in: 1800,
    refresh_token: Some("..."),
    scope: "...",
    token_type: "Bearer",
  ))

  // 4. Use the vault. Blocks until a valid access token is available
  //    (refreshes automatically if the cached one has expired).
  case voauth.get_token(vault) {
    Ok(token) -> // call your provider's API with `token`
    Error(voauth.RefreshFailed(voauth.RefreshUnauthorized(_))) ->
      // refresh token revoked — show "please reconnect" UI
    Error(voauth.RefreshFailed(voauth.RefreshRetryable(_))) ->
      // transient outage — caller may retry
    Error(voauth.NoRefreshToken) ->
      // no token installed yet — user hasn't authorised
    Error(voauth.StartError(_)) -> // vault start error
  }
}

The refresh callback

Provider-specific. Performs the OAuth2 refresh-token grant and returns either a RefreshResponse or a typed error:

fn my_refresh_function(
  refresh_token: String,
) -> Result(voauth.RefreshResponse, voauth.RefreshError) {
  // ... HTTP call to your provider's /oauth2/token endpoint ...
  case status, body {
    200, body -> decode_refresh_response(body)

    // OAuth2 invalid_grant / invalid_token: refresh token is dead.
    400, body | 401, body if has_invalid_grant(body) ->
      Error(voauth.RefreshUnauthorized(body))

    // Everything else: treat as transient; voauth will retry with backoff.
    _, body -> Error(voauth.RefreshRetryable(body))
  }
}

Use voauth.refresh_response_decoder() for the JSON. voauth handles the case where a provider omits fields like scope or refresh_token on a refresh — merge_response carries the previous values forward.

The on_refresh callback (optional)

Fired after every successful refresh. Use it to persist the new token to durable storage (DB, file, secrets manager) so a process restart can rehydrate from the latest state.

fn my_persist_callback(token: voauth.Token) -> Result(Nil, String) {
  save_to_db(token)
}

The callback runs inside the vault's mailbox, so keep it fast. Errors are logged at Error level via logging and otherwise ignored; the vault keeps running.

Configuration

config(refresh:) returns a Config with the defaults below. Override with the with_* setters.

Field	Default	Description
on_refresh	None	Persistence hook.
call_timeout_ms	30_000	Caller-side timeout for get_token / refresh_now / set_token. Must exceed worst-case refresh HTTP latency.
init_timeout_ms	1_000	Actor initialisation timeout.
refresh_at_percent	80	Proactive refresh fires at this percent of expires_in.
min_refresh_delay_ms	60_000	Floor on the proactive delay.
retry_backoff_ms	[30_000, 60_000, 120_000]	Backoff schedule for failed scheduled refreshes. [] disables retries.

Crash recovery

The vault actor can be supervised by your application's gleam_otp supervisor. voauth.supervised(config) returns a child specification. On restart the supervisor calls start(config) with the same config.

To survive a full BEAM restart, persist tokens via on_refresh and re-install via set_token from your durable store on application startup. voauth doesn't own a persistence backend.

Errors

• RefreshFailed(RefreshRetryable(_)) — transient; voauth retries with backoff.
• RefreshFailed(RefreshUnauthorized(_)) — refresh token rejected; user must reauthorise.
• NoRefreshToken — no token installed yet, or the installed token has no refresh_token.
• StartError(_) — vault failed to start.

Development

gleam test