Atex.XRPC.OAuthClient (atex v0.7.1)

View Source

OAuth client for making authenticated XRPC requests to AT Protocol servers.

The client contains a user's DID and talks to Atex.OAuth.SessionStore to retrieve sessions internally to make requests. As a result, it will only work for users that have gone through an OAuth flow; see Atex.OAuth.Plug for an existing method of doing that.

The entire OAuth session lifecycle is handled transparently, with the access token being refreshed automatically as required.

Usage

# Create from an existing OAuth session
{:ok, client} = Atex.XRPC.OAuthClient.new("did:plc:abc123")

# Or extract from a Plug.Conn after OAuth flow
{:ok, client} = Atex.XRPC.OAuthClient.from_conn(conn)

# Make XRPC requests
{:ok, response, client} = Atex.XRPC.get(client, "com.atproto.repo.listRecords")

Summary

Types

t()

Functions

from_conn(conn)

Create an OAuthClient from a Plug.Conn.

get(client, resource, opts \\ [])

Make a GET request to an XRPC endpoint.

new(did)

Create a new OAuthClient from a DID.

post(client, resource, opts \\ [])

Make a POST request to an XRPC endpoint.

refresh(client)

Ask the client's OAuth server for a new set of auth tokens.

Types

t()

@type t() :: %Atex.XRPC.OAuthClient{did: String.t()}

Functions

from_conn(conn)

@spec from_conn(Plug.Conn.t()) :: {:ok, t()} | :error | {:error, atom()}

Create an OAuthClient from a Plug.Conn.

Extracts the DID from the session (stored under :atex_session key) and validates that the OAuth session is still valid. If the token is expired or expiring soon, it attempts to refresh it.

Requires the conn to have passed through Plug.Session and Plug.Conn.fetch_session/2.

Returns

  • {:ok, client} - Successfully created client
  • {:error, :reauth} - Session exists but refresh failed, user needs to re-authenticate
  • :error - No session found in conn

Examples

# After OAuth flow completes
conn = Plug.Conn.put_session(conn, :atex_session, "did:plc:abc123")
{:ok, client} = Atex.XRPC.OAuthClient.from_conn(conn)

get(client, resource, opts \\ [])

Make a GET request to an XRPC endpoint.

See Atex.XRPC.get/3 for details.

new(did)

@spec new(String.t()) :: {:ok, t()} | {:error, atom()}

Create a new OAuthClient from a DID.

Validates that an OAuth session exists for the given DID in the session store before returning the client struct.

Examples

iex> Atex.XRPC.OAuthClient.new("did:plc:abc123")
{:ok, %Atex.XRPC.OAuthClient{did: "did:plc:abc123"}}

iex> Atex.XRPC.OAuthClient.new("did:plc:nosession")
{:error, :not_found}

post(client, resource, opts \\ [])

Make a POST request to an XRPC endpoint.

See Atex.XRPC.post/3 for details.

refresh(client)

@spec refresh(client :: t()) :: {:ok, Atex.OAuth.Session.t()} | {:error, any()}

Ask the client's OAuth server for a new set of auth tokens.

Fetches the session, refreshes the tokens, creates a new session with the updated tokens, stores it, and returns the new session.

You shouldn't need to call this manually for the most part, the client does its best to refresh automatically when it needs to.

This function acquires a lock on the session to prevent concurrent refresh attempts.