XRPC HTTP Surface

XRPC is the public HTTP RPC layer used by AT Protocol clients and services. Tempest exposes XRPC methods under /xrpc/<method-nsid>.

Concepts

A Lexicon method has an NSID such as com.atproto.repo.createRecord. Methods are queries, procedures, or subscriptions:

• queries usually use GET and URL query parameters
• procedures use POST and a JSON or byte body
• subscriptions upgrade to a streaming protocol such as WebSocket

Errors are protocol-shaped JSON with an error string and optional message.

Implementation

TempestWeb.Router sends protocol methods through the XRPC pipeline. Tempest.Xrpc.Registry is the method table. _health is public, and _admin/status is protected by admin-token auth outside normal account bearer credentials. Each registry entry declares:

• NSID
• kind (query, procedure, subscription)
• auth requirement
• input/output content type
• handler module/function
• known errors

TempestWeb.XrpcController performs registry lookup, method checks, content handling, auth assignment, and error rendering before calling the handler.

Handlers live under Tempest.Xrpc.* and should remain thin. Long-running or stateful work belongs in contexts such as Tempest.Accounts, Tempest.Records, Tempest.Sync, or Tempest.Blobs.

Error behavior

Unknown methods return JSON, not Phoenix HTML errors. Verb mismatches and content mismatches fail before handler execution.

Common status mappings:

• 400: invalid params/body
• 401: missing or invalid auth
• 403: authenticated but forbidden
• 404: unknown method or missing resource
• 409: compare-and-swap conflict
• 500: unexpected internal error
• 502: upstream failure

Verification

hurl --test --variable base_url=http://localhost:4000 test/smoke/xrpc.hurl

The smoke test covers health, method dispatch, unknown methods, and verb/error shape behavior.