Exosphere.Lexicon.Resolver (Exosphere v0.4.0)

Copy Markdown View Source

Fetching lexicons published as com.atproto.lexicon.schema records.

Two resolution paths:

  • Direct: fetch/3 against a known PDS and DID — the record key is the lexicon NSID, so a single com.atproto.repo.getRecord call retrieves the document.
  • Authority: resolve/2 follows the lexicon resolution spec: the NSID's authority domain is looked up as a DNS TXT record (_lexicon.<reversed-domain> → did=<DID>), the DID is resolved to its PDS, and the schema record fetched from there. Resolution is deliberately non-recursive: if the TXT lookup fails, resolution fails (per spec, resolvers must not probe up or down the DNS tree).

Both paths validate the fetched document (Lexicon.Schema.new/1) and can register it in Lexicon.Registry with register: true.

Examples

# From a known repo
{:ok, schema} =
  Exosphere.Lexicon.Resolver.fetch("https://pds.example.com",
    "did:plc:abc123", "com.example.post", register: true)

# Via NSID authority
{:ok, schema} = Exosphere.Lexicon.Resolver.resolve("com.example.post")

# Every lexicon a repo publishes
{:ok, schemas} = Exosphere.Lexicon.Resolver.list("https://pds.example.com", "did:plc:abc123")

Summary

Types

fetch_opt()

Functions

fetch(pds_url, did, nsid, opts \\ [])

Fetch a lexicon by NSID from a specific repository.

list(pds_url, did, opts \\ [])

List every lexicon published by a repository, paginating through com.atproto.repo.listRecords.

resolve(nsid, opts \\ [])

Resolve a lexicon by NSID authority: DNS TXT _lexicon.<domain> → DID → PDS → schema record.

Types

fetch_opt()

@type fetch_opt() :: {:register, boolean()} | {:http, module()}

Functions

fetch(pds_url, did, nsid, opts \\ [])

@spec fetch(String.t(), Exosphere.ATProto.Identity.DID.did(), String.t(), [
  fetch_opt()
]) ::
  {:ok, Exosphere.Lexicon.Schema.t()} | {:error, term()}

Fetch a lexicon by NSID from a specific repository.

Options:

  • :register — register the fetched lexicon in Lexicon.Registry (default false)
  • :http — HTTP client module implementing HTTP.Behaviour

list(pds_url, did, opts \\ [])

@spec list(String.t(), Exosphere.ATProto.Identity.DID.did(), [fetch_opt()]) ::
  {:ok, %{schemas: [Exosphere.Lexicon.Schema.t()], invalid: [String.t()]}}
  | {:error, term()}

List every lexicon published by a repository, paginating through com.atproto.repo.listRecords.

Returns {:ok, %{schemas: [Schema.t()], invalid: [nsid]}} — records that fail Lexicon.Schema validation are skipped, with their NSIDs reported under :invalid.

resolve(nsid, opts \\ [])

@spec resolve(String.t(), [fetch_opt()]) ::
  {:ok, Exosphere.Lexicon.Schema.t()} | {:error, term()}

Resolve a lexicon by NSID authority: DNS TXT _lexicon.<domain> → DID → PDS → schema record.

Options: fetch/4 options plus :http (used for both DNS-adjacent DID resolution and the PDS fetch).