Exosphere.OAuth.Session (Exosphere v0.4.0)

Copy Markdown View Source

Process wrapper around an Exosphere.ATProto.OAuth.Session that keeps the session fresh and makes DPoP-signed XRPC calls.

The GenServer serializes access to the rotating refresh token (concurrent refresh attempts would burn it), refreshes eagerly when the access token nears expiry, and retries once through a refresh when the server rejects an expired token. Use Exosphere.ATProto.OAuth.Flow to produce the session, then park it here:

{:ok, session} = Exosphere.ATProto.OAuth.Flow.callback(ctx, params)
{:ok, pid} = Exosphere.OAuth.Session.start_link(session: session, name: {:via, Registry, ...})

{:ok, %{"did" => did}} = Exosphere.OAuth.Session.query(pid, "com.atproto.identity.resolveHandle",
  handle: "atproto.com")

For persistence beyond the process lifetime, serialize with Exosphere.ATProto.OAuth.Session.to_map/1 (e.g. into your database after handle_call returns, or via the :on_refresh callback) and restore with from_map/1.

  • :session - the %Exosphere.ATProto.OAuth.Session{} (required)
  • :on_refresh - {m, f, a} or a 1-arity fun invoked with each refreshed session, so callers can persist rotated tokens
  • :name - GenServer name

Summary

Types

server()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get(server)

The current session struct.

procedure(server, nsid, body \\ %{})

An XRPC procedure (POST) through the session's DPoP-bound client, with the same refresh handling as query/3.

query(server, nsid, params \\ [])

An XRPC query (GET) through the session's DPoP-bound client, refreshing first when the access token has expired and retrying once through a refresh when the server reports an expired token.

refresh(server)

Refresh now (rotates the refresh token).

start_link(opts)

Start a session process.

xrpc_client(session)

The XRPC client for the session — a plain data struct, useful for Exosphere.ATProto.Repo and other direct consumers.

Types

server()

@type server() :: GenServer.server()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get(server)

@spec get(server()) :: Exosphere.ATProto.OAuth.Session.t()

The current session struct.

procedure(server, nsid, body \\ %{})

@spec procedure(server(), String.t(), map()) :: {:ok, map()} | {:error, term()}

An XRPC procedure (POST) through the session's DPoP-bound client, with the same refresh handling as query/3.

query(server, nsid, params \\ [])

@spec query(server(), String.t(), keyword() | map()) ::
  {:ok, map()} | {:error, term()}

An XRPC query (GET) through the session's DPoP-bound client, refreshing first when the access token has expired and retrying once through a refresh when the server reports an expired token.

refresh(server)

@spec refresh(server()) ::
  {:ok, Exosphere.ATProto.OAuth.Session.t()} | {:error, term()}

Refresh now (rotates the refresh token).

start_link(opts)

@spec start_link(keyword() | Exosphere.ATProto.OAuth.Session.t()) ::
  GenServer.on_start()

Start a session process.

Accepts the options listed in the module documentation, or the session struct directly.

xrpc_client(session)

@spec xrpc_client(Exosphere.ATProto.OAuth.Session.t()) ::
  Exosphere.ATProto.XRPC.Client.t()

The XRPC client for the session — a plain data struct, useful for Exosphere.ATProto.Repo and other direct consumers.