atproto SDK: general-purpose API client (#900)

This is a more-protocol-complete replacement for `xrpc.Client`. I've
iterated on the overall design a couple times and feel pretty confident
about this implementation. Features:

- `APIClient` for use with XRPC HTTP requests
- pluggable `AuthMethod` abstraction, with basic implementations for
admin auth and password auth sessions (other auth methods, like OAuth
and inter-service auth, will be separate packages)
- reusable `APIError` and `APIRequest` types
- handle corner-cases like retryable request bodies when auth method
needs to re-send requests
- test coverage

Design notes for reviewers:

- should this package be named `atproto/atclient` instead of
`atproto/client`? "client" is such a generic term
- plan is to have `atproto/auth` with both server and client
implementations of service auth; and then `atproto/auth/oauth` with
OAuth stuff
- observability: open to adding `slog` logging if desired. I'd be
resistant to adding things like otel traces or prometheus metrics; i'd
like to keep this base type minimal in terms of dependencies. could hook
those in via `http.Client`, or a wrapper type.
- some initialization methods return just a pointer to a struct (no
error). those could be returning the struct directly; not sure what our
house style should be for that

A couple small known limitations:

- one not-frequently-used protocol feature is to return the "last
indexed" repo rev in AppView responses, to help with read-after-write
and debugging. the `Get()` and `Post()` helpers don't have an easy way
to access that; could be saved on the `APIClient` struct itself?
- with password auth, there isn't an easy to way directly call
`Logout()`. it isn't so bad to type-unpack the `APIClient.Auth` when
needed? but alternatively the `DoWithAuth` method could detect any
`deleteSession` call and use the refresh token for that (instead of
access token); then calling code would just call that method. feels a
bit "magic" though.
- some headers, like `User-Agent`, don't get passed through and included
on some special calls, like token refresh. not sure how big a deal this
is

atproto/client/admin_auth.go

···
+package client
+
+import (
+	"net/http"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+)
+
+// Simple [AuthMethod] implementation for atproto "admin auth".
+type AdminAuth struct {
+	Password string
+}
+
+func (a *AdminAuth) DoWithAuth(c *http.Client, req *http.Request, endpoint syntax.NSID) (*http.Response, error) {
+	req.SetBasicAuth("admin", a.Password)
+	return c.Do(req)
+}
+
+func NewAdminClient(host, password string) *APIClient {
+	c := NewAPIClient(host)
+	c.Auth = &AdminAuth{Password: password}
+	return c
+}

atproto/client/admin_auth_test.go

···
+package client
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func adminHandler(w http.ResponseWriter, r *http.Request) {
+	username, password, ok := r.BasicAuth()
+	if ok && username == "admin" && password == "secret" {
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprintln(w, "{\"status\":\"success\"}")
+		return
+	}
+	w.Header().Set("WWW-Authenticate", `Basic realm="admin", charset="UTF-8"`)
+	http.Error(w, "Unauthorized", http.StatusUnauthorized)
+}
+
+func TestAdminAuth(t *testing.T) {
+	assert := assert.New(t)
+	ctx := context.Background()
+	var apierr *APIError
+
+	srv := httptest.NewServer(http.HandlerFunc(adminHandler))
+	defer srv.Close()
+
+	{
+		c := NewAPIClient(srv.URL)
+		err := c.Get(ctx, syntax.NSID("com.example.get"), nil, nil)
+		assert.ErrorAs(err, &apierr)
+	}
+
+	{
+		c := NewAdminClient(srv.URL, "wrong")
+		err := c.Get(ctx, syntax.NSID("com.example.get"), nil, nil)
+		assert.ErrorAs(err, &apierr)
+	}
+
+	{
+		c := NewAdminClient(srv.URL, "secret")
+		err := c.Get(ctx, syntax.NSID("com.example.get"), nil, nil)
+		assert.NoError(err)
+	}
+}

atproto/client/apiclient.go

···
+package client
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+)
+
+// Interface for auth implementations which can be used with [APIClient].
+type AuthMethod interface {
+	// Endpoint parameter is included for auth methods which need to include the NSID in authorization tokens
+	DoWithAuth(c *http.Client, req *http.Request, endpoint syntax.NSID) (*http.Response, error)
+}
+
+// General purpose client for atproto "XRPC" API endpoints.
+type APIClient struct {
+	// Inner HTTP client. May be customized after the overall [APIClient] struct is created; for example to set a default request timeout.
+	Client *http.Client
+
+	// Host URL prefix: scheme, hostname, and port. This field is required.
+	Host string
+
+	// Optional auth client "middleware".
+	Auth AuthMethod
+
+	// Optional HTTP headers which will be included in all requests. Only a single value per key is included; request-level headers will override any client-level defaults.
+	Headers http.Header
+
+	// optional authenticated account DID for this client. Does not change client behavior; this field is included as a convenience for calling code, logging, etc.
+	AccountDID *syntax.DID
+}
+
+// Creates a simple APIClient for the provided host. This is appropriate for use with unauthenticated ("public") atproto API endpoints, or to use as a base client to add authentication.
+//
+// Uses [http.DefaultClient], and sets a default User-Agent.
+func NewAPIClient(host string) *APIClient {
+	return &APIClient{
+		Client: http.DefaultClient,
+		Host:   host,
+		Headers: map[string][]string{
+			"User-Agent": []string{"indigo-sdk"},
+		},
+	}
+}
+
+// High-level helper for simple JSON "Query" API calls.
+//
+// This method automatically parses non-successful responses to [APIError].
+//
+// For Query endpoints which return non-JSON data, or other situations needing complete configuration of the request and response, use the [APIClient.Do] method.
+func (c *APIClient) Get(ctx context.Context, endpoint syntax.NSID, params map[string]any, out any) error {
+
+	req := NewAPIRequest(http.MethodGet, endpoint, nil)
+	req.Headers.Set("Accept", "application/json")
+
+	if params != nil {
+		qp, err := ParseParams(params)
+		if err != nil {
+			return err
+		}
+		req.QueryParams = qp
+	}
+
+	resp, err := c.Do(ctx, req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if !(resp.StatusCode >= 200 && resp.StatusCode < 300) {
+		var eb ErrorBody
+		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
+			return &APIError{StatusCode: resp.StatusCode}
+		}
+		return eb.APIError(resp.StatusCode)
+	}
+
+	if out == nil {
+		// drain body before returning
+		io.ReadAll(resp.Body)
+		return nil
+	}
+
+	if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
+		return fmt.Errorf("failed decoding JSON response body: %w", err)
+	}
+	return nil
+}
+
+// High-level helper for simple JSON-to-JSON "Procedure" API calls, with no query params.
+//
+// This method automatically parses non-successful responses to [APIError].
+//
+// For Query endpoints which expect non-JSON request bodies; return non-JSON responses; direct use of [io.Reader] for the request body; or other situations needing complete configuration of the request and response, use the [APIClient.Do] method.
+func (c *APIClient) Post(ctx context.Context, endpoint syntax.NSID, body any, out any) error {
+	bodyJSON, err := json.Marshal(body)
+	if err != nil {
+		return err
+	}
+
+	req := NewAPIRequest(http.MethodPost, endpoint, bytes.NewReader(bodyJSON))
+	req.Headers.Set("Accept", "application/json")
+	req.Headers.Set("Content-Type", "application/json")
+
+	resp, err := c.Do(ctx, req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if !(resp.StatusCode >= 200 && resp.StatusCode < 300) {
+		var eb ErrorBody
+		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
+			return &APIError{StatusCode: resp.StatusCode}
+		}
+		return eb.APIError(resp.StatusCode)
+	}
+
+	if out == nil {
+		// drain body before returning
+		io.ReadAll(resp.Body)
+		return nil
+	}
+
+	if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
+		return fmt.Errorf("failed decoding JSON response body: %w", err)
+	}
+	return nil
+}
+
+// Full-featured method for atproto API requests.
+//
+// TODO: this does not currently parse API error response JSON body to [APIError], thought it might in the future.
+func (c *APIClient) Do(ctx context.Context, req *APIRequest) (*http.Response, error) {
+
+	if c.Client == nil {
+		c.Client = http.DefaultClient
+	}
+
+	httpReq, err := req.HTTPRequest(ctx, c.Host, c.Headers)
+	if err != nil {
+		return nil, err
+	}
+
+	var resp *http.Response
+	if c.Auth != nil {
+		resp, err = c.Auth.DoWithAuth(c.Client, httpReq, req.Endpoint)
+	} else {
+		resp, err = c.Client.Do(httpReq)
+	}
+	if err != nil {
+		return nil, err
+	}
+	return resp, nil
+}
+
+// Returns a shallow copy of the APIClient with the provided service ref configured as a proxy header.
+//
+// To configure service proxying without creating a copy, simply set the 'Atproto-Proxy' header.
+func (c *APIClient) WithService(ref string) *APIClient {
+	hdr := c.Headers.Clone()
+	hdr.Set("Atproto-Proxy", ref)
+	out := APIClient{
+		Client:     c.Client,
+		Host:       c.Host,
+		Auth:       c.Auth,
+		Headers:    hdr,
+		AccountDID: c.AccountDID,
+	}
+	return &out
+}
+
+// Configures labeler header ('Atproto-Accept-Labelers') with the indicated "redact" level labelers, and regular labelers.
+//
+// Overwrites any existing client-level header value.
+func (c *APIClient) SetLabelers(redact, other []syntax.DID) {
+	c.Headers.Set("Atproto-Accept-Labelers", encodeLabelerHeader(redact, other))
+}
+
+func encodeLabelerHeader(redact, other []syntax.DID) string {
+	val := ""
+	for _, did := range redact {
+		if val != "" {
+			val = val + ","
+		}
+		val = fmt.Sprintf("%s%s;redact", val, did.String())
+	}
+	for _, did := range other {
+		if val != "" {
+			val = val + ","
+		}
+		val = val + did.String()
+	}
+	return val
+}

atproto/client/apiclient_test.go

···
+package client
+
+import (
+	"testing"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestEncodeLabelerHeader(t *testing.T) {
+	assert := assert.New(t)
+
+	labelerA := syntax.DID("did:web:aaa.example.com")
+	labelerB := syntax.DID("did:web:bbb.example.com")
+
+	assert.Equal("", encodeLabelerHeader(nil, nil))
+	assert.Equal("did:web:aaa.example.com,did:web:bbb.example.com", encodeLabelerHeader(nil, []syntax.DID{labelerA, labelerB}))
+	assert.Equal("did:web:aaa.example.com;redact,did:web:bbb.example.com", encodeLabelerHeader([]syntax.DID{labelerA}, []syntax.DID{labelerB}))
+	assert.Equal("did:web:aaa.example.com;redact", encodeLabelerHeader([]syntax.DID{labelerA}, nil))
+}

atproto/client/apierror.go

···
+package client
+
+import (
+	"fmt"
+)
+
+type APIError struct {
+	StatusCode int
+	Name       string
+	Message    string
+}
+
+func (ae *APIError) Error() string {
+	if ae.StatusCode > 0 {
+		if ae.Name != "" && ae.Message != "" {
+			return fmt.Sprintf("API request failed (HTTP %d): %s: %s", ae.StatusCode, ae.Name, ae.Message)
+		} else if ae.Name != "" {
+			return fmt.Sprintf("API request failed (HTTP %d): %s", ae.StatusCode, ae.Name)
+		}
+		return fmt.Sprintf("API request failed (HTTP %d)", ae.StatusCode)
+	}
+	return "API request failed"
+}
+
+type ErrorBody struct {
+	Name    string `json:"error"`
+	Message string `json:"message,omitempty"`
+}
+
+func (eb *ErrorBody) APIError(statusCode int) error {
+	return &APIError{
+		StatusCode: statusCode,
+		Name:       eb.Name,
+		Message:    eb.Message,
+	}
+}

atproto/client/apirequest.go

···
+package client
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+)
+
+var (
+	// atproto API "Query" Lexicon method, which is HTTP GET. Not to be confused with the IETF draft "HTTP QUERY" method.
+	MethodQuery = http.MethodGet
+
+	// atproto API "Procedure" Lexicon method, which is HTTP POST.
+	MethodProcedure = http.MethodPost
+)
+
+type APIRequest struct {
+	// HTTP method as a string (eg "GET") (required)
+	Method string
+
+	// atproto API endpoint, as NSID (required)
+	Endpoint syntax.NSID
+
+	// Optional request body (may be nil). If this is provided, then 'Content-Type' header should be specified
+	Body io.Reader
+
+	// Optional function to return new reader for request body; used for retries. Strongly recommended if Body is defined. Body still needs to be defined, even if this function is provided.
+	GetBody func() (io.ReadCloser, error)
+
+	// Optional query parameters (field may be nil). These will be encoded as provided.
+	QueryParams url.Values
+
+	// Optional HTTP headers (field bay be nil). Only the first value will be included for each header key ("Set" behavior).
+	Headers http.Header
+}
+
+// Initializes a new request struct. Initializes Headers and QueryParams so they can be manipulated immediately.
+//
+// If body is provided (it can be nil), will try to turn it in to the most retry-able form (and wrap as [io.ReadCloser]).
+func NewAPIRequest(method string, endpoint syntax.NSID, body io.Reader) *APIRequest {
+	req := APIRequest{
+		Method:      method,
+		Endpoint:    endpoint,
+		Headers:     map[string][]string{},
+		QueryParams: map[string][]string{},
+	}
+
+	// logic to turn "whatever io.Reader we are handed" in to something relatively re-tryable (using GetBody)
+	if body != nil {
+		// NOTE: http.NewRequestWithContext already handles GetBody() as well as ContentLength for specific types like bytes.Buffer and strings.Reader. We just want to add io.Seeker here, for things like files-on-disk.
+		switch v := body.(type) {
+		case io.Seeker:
+			req.Body = io.NopCloser(body)
+			req.GetBody = func() (io.ReadCloser, error) {
+				v.Seek(0, 0)
+				return io.NopCloser(body), nil
+			}
+		default:
+			req.Body = body
+		}
+	}
+	return &req
+}
+
+// Creates an [http.Request] for this API request.
+//
+// `host` parameter should be a URL prefix: schema, hostname, port (required)
+//
+// `clientHeaders`, if provided, is treated as client-level defaults. Only a single value is allowed per key ("Set" behavior), and will be clobbered by any request-level header values. (optional; may be nil)
+func (r *APIRequest) HTTPRequest(ctx context.Context, host string, clientHeaders http.Header) (*http.Request, error) {
+	u, err := url.Parse(host)
+	if err != nil {
+		return nil, err
+	}
+	if u.Host == "" {
+		return nil, fmt.Errorf("empty hostname in host URL")
+	}
+	if u.Scheme == "" {
+		return nil, fmt.Errorf("empty scheme in host URL")
+	}
+	if r.Endpoint == "" {
+		return nil, fmt.Errorf("empty request endpoint")
+	}
+	u.Path = "/xrpc/" + r.Endpoint.String()
+	u.RawQuery = ""
+	if r.QueryParams != nil && len(r.QueryParams) > 0 {
+		u.RawQuery = r.QueryParams.Encode()
+	}
+	httpReq, err := http.NewRequestWithContext(ctx, r.Method, u.String(), r.Body)
+	if err != nil {
+		return nil, err
+	}
+
+	if r.GetBody != nil {
+		httpReq.GetBody = r.GetBody
+	}
+
+	// first set default headers...
+	if clientHeaders != nil {
+		for k := range clientHeaders {
+			httpReq.Header.Set(k, clientHeaders.Get(k))
+		}
+	}
+
+	// ... then request-specific take priority (overwrite)
+	if r.Headers != nil {
+		for k := range r.Headers {
+			httpReq.Header.Set(k, r.Headers.Get(k))
+		}
+	}
+
+	return httpReq, nil
+}

atproto/client/cmd/atp-client-demo/main.go

···
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os"
+
+	comatproto "github.com/bluesky-social/indigo/api/agnostic"
+	"github.com/bluesky-social/indigo/atproto/client"
+	"github.com/bluesky-social/indigo/atproto/identity"
+	"github.com/bluesky-social/indigo/atproto/syntax"
+
+	"github.com/urfave/cli/v2"
+)
+
+func main() {
+	app := cli.App{
+		Name:  "atp-client-demo",
+		Usage: "dev helper for atproto/client SDK",
+		Commands: []*cli.Command{
+			&cli.Command{
+				Name:   "get-feed-public",
+				Usage:  "do a basic GET request (getAuthorFeed)",
+				Action: runGetFeedPublic,
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:  "host",
+						Value: "https://public.api.bsky.app",
+						Usage: "service host",
+					},
+				},
+			},
+			&cli.Command{
+				Name:   "list-records-public",
+				Usage:  "do a basic GET request (listRecords)",
+				Action: runListRecordsPublic,
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:  "host",
+						Value: "https://enoki.us-east.host.bsky.network",
+						Usage: "service host",
+					},
+				},
+			},
+			&cli.Command{
+				Name:   "login-auth",
+				Usage:  "do a basic login and GET session info",
+				Action: runLoginAuth,
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:     "username",
+						Required: true,
+						Aliases:  []string{"u"},
+						Usage:    "handle or DID (not email)",
+					},
+					&cli.StringFlag{
+						Name:     "password",
+						Required: true,
+						Aliases:  []string{"p"},
+						Usage:    "password (or app password)",
+					},
+				},
+			},
+			&cli.Command{
+				Name:   "get-feed-auth",
+				Usage:  "basic authenticated GET request",
+				Action: runGetFeedAuth,
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:     "username",
+						Required: true,
+						Aliases:  []string{"u"},
+						Usage:    "handle or DID (not email)",
+					},
+					&cli.StringFlag{
+						Name:     "password",
+						Required: true,
+						Aliases:  []string{"p"},
+						Usage:    "password (or app password)",
+					},
+					&cli.StringFlag{
+						Name: "labelers",
+					},
+					&cli.StringFlag{
+						Name:  "appview",
+						Value: "did:web:api.bsky.app#bsky_appview",
+						Usage: "bsky appview service DID ref",
+					},
+				},
+			},
+			&cli.Command{
+				Name:   "lookup-admin",
+				Usage:  "basic PDS admin auth request (getAccountInfo)",
+				Action: runLookupAdmin,
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:     "admin-password",
+						Required: true,
+						Aliases:  []string{"p"},
+						Usage:    "admin auth password",
+					},
+					&cli.StringFlag{
+						Name:     "host",
+						Required: true,
+						Usage:    "service host",
+					},
+					&cli.StringFlag{
+						Name:     "did",
+						Required: true,
+						Usage:    "account DID to lookup",
+					},
+				},
+			},
+		},
+	}
+	h := slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug})
+	slog.SetDefault(slog.New(h))
+	app.RunAndExitOnError()
+}
+
+func getFeed(ctx context.Context, c *client.APIClient) error {
+	params := map[string]any{
+		"actor":       "atproto.com",
+		"limit":       2,
+		"includePins": false,
+	}
+
+	var d json.RawMessage
+	err := c.Get(ctx, "app.bsky.feed.getAuthorFeed", params, &d)
+	if err != nil {
+		return err
+	}
+
+	out, err := json.MarshalIndent(d, "", "  ")
+	if err != nil {
+		return err
+	}
+	fmt.Println(string(out))
+	return nil
+}
+
+func listRecords(ctx context.Context, c *client.APIClient) error {
+
+	list, err := comatproto.RepoListRecords(ctx, c, "app.bsky.actor.profile", "", 10, "did:plc:ewvi7nxzyoun6zhxrhs64oiz", false)
+	if err != nil {
+		return err
+	}
+
+	out, err := json.MarshalIndent(list, "", "  ")
+	if err != nil {
+		return err
+	}
+	fmt.Println(string(out))
+	return nil
+}
+
+func runGetFeedPublic(cctx *cli.Context) error {
+	ctx := cctx.Context
+
+	c := client.APIClient{
+		Host: cctx.String("host"),
+	}
+
+	return getFeed(ctx, &c)
+}
+
+func runListRecordsPublic(cctx *cli.Context) error {
+	ctx := cctx.Context
+
+	c := client.APIClient{
+		Host: cctx.String("host"),
+	}
+
+	return listRecords(ctx, &c)
+}
+
+func runLoginAuth(cctx *cli.Context) error {
+	ctx := cctx.Context
+
+	atid, err := syntax.ParseAtIdentifier(cctx.String("username"))
+	if err != nil {
+		return err
+	}
+
+	dir := identity.DefaultDirectory()
+
+	c, err := client.LoginWithPassword(ctx, dir, *atid, cctx.String("password"), "", nil)
+	if err != nil {
+		return err
+	}
+
+	var d json.RawMessage
+	err = c.Get(ctx, "com.atproto.server.getSession", nil, &d)
+	if err != nil {
+		return err
+	}
+
+	out, err := json.MarshalIndent(d, "", "  ")
+	if err != nil {
+		return err
+	}
+	fmt.Println(string(out))
+	return nil
+}
+
+func runGetFeedAuth(cctx *cli.Context) error {
+	ctx := cctx.Context
+
+	atid, err := syntax.ParseAtIdentifier(cctx.String("username"))
+	if err != nil {
+		return err
+	}
+
+	dir := identity.DefaultDirectory()
+
+	c, err := client.LoginWithPassword(ctx, dir, *atid, cctx.String("password"), "", nil)
+	if err != nil {
+		return err
+	}
+	c = c.WithService(cctx.String("appview"))
+
+	return getFeed(ctx, c)
+}
+
+func runLookupAdmin(cctx *cli.Context) error {
+	ctx := cctx.Context
+
+	c := client.NewAdminClient(cctx.String("host"), cctx.String("admin-password"))
+
+	var d json.RawMessage
+	params := map[string]any{
+		"did": cctx.String("did"),
+	}
+	if err := c.Get(ctx, "com.atproto.admin.getAccountInfo", params, &d); err != nil {
+		return err
+	}
+
+	out, err := json.MarshalIndent(d, "", "  ")
+	if err != nil {
+		return err
+	}
+	fmt.Println(string(out))
+	return nil
+}

atproto/client/doc.go

···
+/*
+General-purpose client for atproto "XRPC" HTTP API endpoints.
+
+[APIClient] wraps an [http.Client] and provides an ergonomic atproto-specific (but not Lexicon-specific) interface for "Query" (GET) and "Procedure" (POST) endpoints. It does not support "Event Stream" (WebSocket) endpoints. The client is expected to be used with a single host at a time, though it does have special support ([APIClient.WithService]) for proxied service requests when connected to a PDS host. The client does not authenticate requests by default, but supports pluggable authentication methods (see below). The [APIReponse] struct represents a generic API request, and helps with conversion to an [http.Request].
+
+The [APIError] struct can represent a generic API error response (eg, an HTTP response with a 4xx or 5xx response code), including the 'error' and 'message' JSON response fields expected with atproto. It is intended to be used with [errors.Is] in error handling, or to provide helpful error messages.
+
+The [AuthMethod] interface allows [APIClient] to work with multiple forms of authentication in atproto. It is expected that more complex auth systems (eg, those using signed JWTs) will be implemented in separate packages, but this package does include two simple auth methods:
+
+- [PasswordAuth] is the original PDS user auth method, using access and refresh tokens.
+- [AdminAuth] is simple HTTP Basic authentication for administrative requests, as implemented by many atproto services (Relay, Ozone, PDS, etc).
+
+## Design Notes
+
+Several [AuthMethod] implementations are expected to require retrying entire request at unexpected times. For example, unexpected OAuth DPoP nonce changes, or unexpected password session token refreshes. The auth method may also need to make requests to other servers as part of the refresh process (eg, OAuth when working with a PDS/entryway split). This means that requests should be "retryable" as often as possible. This is mostly a concern for Procedures (HTTP POST) with a non-empty body. The [http.Client] will attempt to "unclose" some common [io.ReadCloser] types (like [bytes.Buffer]), but others may need special handling, using the [APIRequest.GetBody] method. This package will try to make types implementing [io.Seeker] tryable; this helps with things like passing in a open file descriptor for file uploads.
+
+In theory, the [http.RoundTripper] interface could have been used instead of [AuthMethod]; or auth methods could have been injected in to [http.Client] instances directly. This package avoids this pattern for a few reasons. The first is that wrangling layered stacks of [http.RoundTripper] can become cumbersome. Calling code may want to use [http.Client] variants which add observability, retries, circuit-breaking, or other non-auth customization. Secondly, some atproto auth methods will require requests to other servers or endpoints, and having a common [http.Client] to re-use for these requests makes sense. Finally, several atproto auth methods need to know the target endpoint as an NSID; while this could be re-parsed from the request URL, it is simpler and more reliable to pass it as an argument.
+
+This package tries to use minimal dependencies beyond the Go standard library, to make it easy to reference as a dependency. It does require the [github.com/bluesky-social/indigo/atproto/syntax] and [github.com/bluesky-social/indigo/atproto/identity] sibling packages. In particular, this package does not include any auth methods requiring JWTs, to avoid adding any specific JWT implementation as a dependency.
+*/
+package client

atproto/client/examples_test.go

···
+package client
+
+import (
+	"context"
+	"fmt"
+
+	appbsky "github.com/bluesky-social/indigo/api/bsky"
+	"github.com/bluesky-social/indigo/atproto/syntax"
+)
+
+func ExampleGet() {
+
+	ctx := context.Background()
+
+	c := APIClient{
+		Host: "https://public.api.bsky.app",
+	}
+
+	endpoint := syntax.NSID("app.bsky.actor.getProfile")
+	params := map[string]any{
+		"actor": "atproto.com",
+	}
+	var profile appbsky.ActorDefs_ProfileViewDetailed
+	if err := c.Get(ctx, endpoint, params, &profile); err != nil {
+		panic(err)
+	}
+
+	fmt.Println(profile.Handle)
+	// Output: atproto.com
+}

atproto/client/lexclient.go

···
+package client
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+)
+
+// Implements the [github.com/bluesky-social/indigo/lex/util.LexClient] interface, for use with code-generated API helpers.
+func (c *APIClient) LexDo(ctx context.Context, method string, inputEncoding string, endpoint string, params map[string]any, bodyData any, out any) error {
+	// some of the code here is copied from indigo:xrpc/xrpc.go
+
+	nsid, err := syntax.ParseNSID(endpoint)
+	if err != nil {
+		return err
+	}
+
+	var body io.Reader
+	if bodyData != nil {
+		if rr, ok := bodyData.(io.Reader); ok {
+			body = rr
+		} else {
+			b, err := json.Marshal(bodyData)
+			if err != nil {
+				return err
+			}
+
+			body = bytes.NewReader(b)
+			if inputEncoding == "" {
+				inputEncoding = "application/json"
+			}
+		}
+	}
+
+	req := NewAPIRequest(method, nsid, body)
+
+	if inputEncoding != "" {
+		req.Headers.Set("Content-Type", inputEncoding)
+	}
+
+	if params != nil {
+		qp, err := ParseParams(params)
+		if err != nil {
+			return err
+		}
+		req.QueryParams = qp
+	}
+
+	resp, err := c.Do(ctx, req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if !(resp.StatusCode >= 200 && resp.StatusCode < 300) {
+		var eb ErrorBody
+		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
+			return &APIError{StatusCode: resp.StatusCode}
+		}
+		return eb.APIError(resp.StatusCode)
+	}
+
+	if out == nil {
+		// drain body before returning
+		io.ReadAll(resp.Body)
+		return nil
+	}
+
+	if buf, ok := out.(*bytes.Buffer); ok {
+		if resp.ContentLength < 0 {
+			_, err := io.Copy(buf, resp.Body)
+			if err != nil {
+				return fmt.Errorf("reading response body: %w", err)
+			}
+		} else {
+			n, err := io.CopyN(buf, resp.Body, resp.ContentLength)
+			if err != nil {
+				return fmt.Errorf("reading length delimited response body (%d < %d): %w", n, resp.ContentLength, err)
+			}
+		}
+	} else {
+		if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
+			return fmt.Errorf("failed decoding JSON response body: %w", err)
+		}
+	}
+
+	return nil
+}

atproto/client/params.go

···
+package client
+
+import (
+	"encoding"
+	"fmt"
+	"net/url"
+	"reflect"
+)
+
+// Flexibly parses an input map to URL query params (strings)
+func ParseParams(raw map[string]any) (url.Values, error) {
+	out := make(url.Values)
+	for k := range raw {
+		switch v := raw[k].(type) {
+		case nil:
+			out.Set(k, "")
+		case bool, string, int, uint, int8, int16, int32, int64, uint8, uint16, uint32, uint64, uintptr:
+			out.Set(k, fmt.Sprint(v))
+		case encoding.TextMarshaler:
+			out.Set(k, fmt.Sprint(v))
+		default:
+			ref := reflect.ValueOf(v)
+			if ref.Kind() == reflect.Slice {
+				for i := 0; i < ref.Len(); i++ {
+					switch elem := ref.Index(i).Interface().(type) {
+					case nil:
+						out.Add(k, "")
+					case bool, string, int, uint, int8, int16, int32, int64, uint8, uint16, uint32, uint64, uintptr:
+						out.Add(k, fmt.Sprint(elem))
+					case encoding.TextMarshaler:
+						out.Add(k, fmt.Sprint(elem))
+					default:
+						return nil, fmt.Errorf("can't marshal query param '%s' with type: %T", k, v)
+					}
+				}
+			} else {
+				return nil, fmt.Errorf("can't marshal query param '%s' with type: %T", k, v)
+			}
+		}
+	}
+	return out, nil
+}

atproto/client/params_test.go

···
+package client
+
+import (
+	"net/url"
+	"testing"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseParams(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+
+	{
+		input := map[string]any{
+			"int":       int(-1),
+			"uint32":    uint32(32),
+			"str":       "hello",
+			"bool":      true,
+			"did":       syntax.DID("did:web:example.com"),
+			"multiBool": []bool{true, false},
+			"multiDID":  []syntax.DID{syntax.DID("did:web:example.com"), syntax.DID("did:web:other.com")},
+		}
+		expect := url.Values(map[string][]string{
+			"int":       []string{"-1"},
+			"uint32":    []string{"32"},
+			"str":       []string{"hello"},
+			"bool":      []string{"true"},
+			"did":       []string{"did:web:example.com"},
+			"multiBool": []string{"true", "false"},
+			"multiDID":  []string{"did:web:example.com", "did:web:other.com"},
+		})
+		output, err := ParseParams(input)
+		require.NoError(err)
+		assert.Equal(expect, output)
+	}
+
+	{
+		// unsupported type
+		input := map[string]any{
+			"map": map[string]int{"a": 123},
+		}
+		_, err := ParseParams(input)
+		assert.Error(err)
+	}
+
+}

atproto/client/password_auth.go

···
+package client
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+
+	"github.com/bluesky-social/indigo/atproto/identity"
+	"github.com/bluesky-social/indigo/atproto/syntax"
+)
+
+type RefreshCallback = func(ctx context.Context, data PasswordSessionData)
+
+// Implementation of [AuthMethod] for password-based auth sessions with atproto PDS hosts. Automatically refreshes "access token" using a "refresh token" when needed.
+//
+// It is safe to use this auth method concurrently from multiple goroutines.
+type PasswordAuth struct {
+	Session PasswordSessionData
+
+	// Optional callback function which gets called with updated session data whenever a successful token refresh happens.
+	//
+	// Note that this function is called while a lock is being held on the overall client, and with a context usually tied to a regular API request call. The callback should either return quickly, or spawn a goroutine. Because of the lock, this callback will never be called concurrently for a single client, but may be called currently across clients.
+	RefreshCallback RefreshCallback
+
+	// Lock which protects concurrent access to AccessToken and RefreshToken in session data. Note that this only applies to this particular instance of PasswordAuth.
+	lk sync.RWMutex
+}
+
+// Data about a PDS password auth session which can be persisted and then used to resume the session later.
+type PasswordSessionData struct {
+	AccessToken  string     `json:"access_token"`
+	RefreshToken string     `json:"refresh_token"`
+	AccountDID   syntax.DID `json:"account_did"`
+	Host         string     `json:"host"`
+}
+
+// Creates a deep copy of the session data.
+func (sd *PasswordSessionData) Clone() PasswordSessionData {
+	return PasswordSessionData{
+		AccessToken:  sd.AccessToken,
+		RefreshToken: sd.RefreshToken,
+		AccountDID:   sd.AccountDID,
+		Host:         sd.Host,
+	}
+}
+
+type createSessionRequest struct {
+	//AllowTakendown  *bool   `json:"allowTakendown,omitempty" cborgen:"allowTakendown,omitempty"`
+	AuthFactorToken *string `json:"authFactorToken,omitempty" cborgen:"authFactorToken,omitempty"`
+	// identifier: Handle or other identifier supported by the server for the authenticating user.
+	Identifier string `json:"identifier" cborgen:"identifier"`
+	Password   string `json:"password" cborgen:"password"`
+}
+
+type createSessionResponse struct {
+	AccessJwt string `json:"accessJwt" cborgen:"accessJwt"`
+	Active    *bool  `json:"active,omitempty" cborgen:"active,omitempty"`
+	Did       string `json:"did" cborgen:"did"`
+	//Email           *string      `json:"email,omitempty" cborgen:"email,omitempty"`
+	//EmailAuthFactor *bool        `json:"emailAuthFactor,omitempty" cborgen:"emailAuthFactor,omitempty"`
+	//EmailConfirmed  *bool        `json:"emailConfirmed,omitempty" cborgen:"emailConfirmed,omitempty"`
+	//Handle          string       `json:"handle" cborgen:"handle"`
+	RefreshJwt string  `json:"refreshJwt" cborgen:"refreshJwt"`
+	Status     *string `json:"status,omitempty" cborgen:"status,omitempty"`
+}
+
+type refreshSessionResponse struct {
+	AccessJwt string `json:"accessJwt" cborgen:"accessJwt"`
+	Active    *bool  `json:"active,omitempty" cborgen:"active,omitempty"`
+	Did       string `json:"did" cborgen:"did"`
+	//Handle     string       `json:"handle" cborgen:"handle"`
+	RefreshJwt string  `json:"refreshJwt" cborgen:"refreshJwt"`
+	Status     *string `json:"status,omitempty" cborgen:"status,omitempty"`
+}
+
+func (a *PasswordAuth) DoWithAuth(c *http.Client, req *http.Request, endpoint syntax.NSID) (*http.Response, error) {
+	accessToken, refreshToken := a.GetTokens()
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+	resp, err := c.Do(req)
+	if err != nil {
+		return nil, err
+	}
+
+	// on success, or most errors, just return HTTP response
+	if resp.StatusCode != http.StatusBadRequest || !strings.HasPrefix(resp.Header.Get("Content-Type"), "application/json") {
+		return resp, nil
+	}
+
+	// parse the error response body (JSON) and check the error name
+	defer resp.Body.Close()
+	var eb ErrorBody
+	if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
+		return nil, &APIError{StatusCode: resp.StatusCode}
+	}
+	if eb.Name != "ExpiredToken" {
+		return nil, eb.APIError(resp.StatusCode)
+	}
+
+	// ok, we had an expired token, try a refresh
+	if err := a.Refresh(req.Context(), c, refreshToken); err != nil {
+		return nil, err
+	}
+
+	retry := req.Clone(req.Context())
+	if req.GetBody != nil {
+		retry.Body, err = req.GetBody()
+		if err != nil {
+			return nil, fmt.Errorf("API request retry GetBody failed: %w", err)
+		}
+	}
+
+	accessToken, _ = a.GetTokens()
+
+	retry.Header.Set("Authorization", "Bearer "+accessToken)
+	retryResp, err := c.Do(retry)
+	if err != nil {
+		return nil, err
+	}
+	// NOTE: could handle auth failure as special error type here
+	return retryResp, err
+}
+
+// Returns current access and refresh tokens (take a read-lock on session data)
+func (a *PasswordAuth) GetTokens() (string, string) {
+	a.lk.RLock()
+	defer a.lk.RUnlock()
+	return a.Session.AccessToken, a.Session.RefreshToken
+}
+
+// Refreshes auth tokens (takes a write-lock on session data).
+//
+// `priorRefreshToken` argument is used to check if a concurrent refresh already took place.
+func (a *PasswordAuth) Refresh(ctx context.Context, c *http.Client, priorRefreshToken string) error {
+
+	a.lk.Lock()
+	defer a.lk.Unlock()
+
+	// basic concurrency check: if refresh token already changed, can bail here (releasing lock)
+	if priorRefreshToken != "" && priorRefreshToken != a.Session.RefreshToken {
+		return nil
+	}
+
+	u := a.Session.Host + "/xrpc/com.atproto.server.refreshSession"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return err
+	}
+	// NOTE: could try to pull User-Agent from a request and pass that through to here
+	req.Header.Set("User-Agent", "indigo-sdk")
+
+	// NOTE: using refresh token here, not access token
+	req.Header.Set("Authorization", "Bearer "+a.Session.RefreshToken)
+
+	resp, err := c.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if !(resp.StatusCode >= 200 && resp.StatusCode < 300) {
+		var eb ErrorBody
+		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
+			return &APIError{StatusCode: resp.StatusCode}
+		}
+		// TODO: indicate in the error that it was from refresh process, not original request?
+		return eb.APIError(resp.StatusCode)
+	}
+
+	var out refreshSessionResponse
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		return err
+	}
+
+	a.Session.AccessToken = out.AccessJwt
+	a.Session.RefreshToken = out.RefreshJwt
+
+	if a.RefreshCallback != nil {
+		snapshot := a.Session.Clone()
+		a.RefreshCallback(ctx, snapshot)
+	}
+
+	return nil
+}
+
+func (a *PasswordAuth) Logout(ctx context.Context, c *http.Client) error {
+	_, refreshToken := a.GetTokens()
+
+	u := a.Session.Host + "/xrpc/com.atproto.server.deleteSession"
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, u, nil)
+	if err != nil {
+		return err
+	}
+	// NOTE: could try to pull User-Agent from a request and pass that through to here
+	req.Header.Set("User-Agent", "indigo-sdk")
+
+	// NOTE: using refresh token here, not access token
+	req.Header.Set("Authorization", "Bearer "+refreshToken)
+
+	resp, err := c.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if !(resp.StatusCode >= 200 && resp.StatusCode < 300) {
+		var eb ErrorBody
+		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
+			return &APIError{StatusCode: resp.StatusCode}
+		}
+		return eb.APIError(resp.StatusCode)
+	}
+	return nil
+}
+
+// Creates a new [APIClient] with [PasswordAuth] for the provided user. The provided identity directory is used to resolve the PDS host for the account.
+//
+// `authToken` is optional; is used when multi-factor authentication is enabled for the account.
+//
+// `cb` is an optional callback which will be called with updated session data after any token refresh.
+func LoginWithPassword(ctx context.Context, dir identity.Directory, username syntax.AtIdentifier, password, authToken string, cb RefreshCallback) (*APIClient, error) {
+
+	ident, err := dir.Lookup(ctx, username)
+	if err != nil {
+		return nil, err
+	}
+
+	host := ident.PDSEndpoint()
+	if host == "" {
+		return nil, fmt.Errorf("account does not have PDS registered")
+	}
+
+	c, err := LoginWithPasswordHost(ctx, host, ident.DID.String(), password, authToken, cb)
+	if err != nil {
+		return nil, err
+	}
+
+	if c.AccountDID == nil || *c.AccountDID != ident.DID {
+		return nil, fmt.Errorf("returned session DID not requested account: %s", c.AccountDID)
+	}
+
+	return c, nil
+}
+
+// Creates a new [APIClient] with [PasswordAuth], based on a login to the provided host. Note that with some PDS implementations, 'username' could be an email address. This login method also works in situations where an account's network identity does not resolve to this specific host.
+//
+// `authToken` is optional; is used when multi-factor authentication is enabled for the account.
+//
+// `cb` is an optional callback which will be called with updated session data after any token refresh.
+func LoginWithPasswordHost(ctx context.Context, host, username, password, authToken string, cb RefreshCallback) (*APIClient, error) {
+
+	c := NewAPIClient(host)
+	reqBody := createSessionRequest{
+		Identifier: username,
+		Password:   password,
+	}
+	if authToken != "" {
+		reqBody.AuthFactorToken = &authToken
+	}
+
+	var out createSessionResponse
+	if err := c.Post(ctx, syntax.NSID("com.atproto.server.createSession"), &reqBody, &out); err != nil {
+		return nil, err
+	}
+
+	if out.Active != nil && *out.Active == false {
+		return nil, fmt.Errorf("account is disabled: %v", out.Status)
+	}
+
+	did, err := syntax.ParseDID(out.Did)
+	if err != nil {
+		return nil, err
+	}
+
+	ra := PasswordAuth{
+		Session: PasswordSessionData{
+			AccessToken:  out.AccessJwt,
+			RefreshToken: out.RefreshJwt,
+			AccountDID:   did,
+			Host:         c.Host,
+		},
+		RefreshCallback: cb,
+	}
+	c.Auth = &ra
+	c.AccountDID = &did
+	return c, nil
+}
+
+// Creates an [APIClient] using [PasswordAuth], based on existing session data.
+//
+// `cb` is an optional callback which will be called with updated session data after any token refresh.
+func ResumePasswordSession(data PasswordSessionData, cb RefreshCallback) *APIClient {
+	c := NewAPIClient(data.Host)
+	ra := PasswordAuth{
+		Session:         data,
+		RefreshCallback: cb,
+	}
+	c.Auth = &ra
+	c.AccountDID = &data.AccountDID
+	return c
+}

atproto/client/password_auth_test.go

···
+package client
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/bluesky-social/indigo/atproto/identity"
+	"github.com/bluesky-social/indigo/atproto/syntax"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func pwHandler(w http.ResponseWriter, r *http.Request) {
+	switch r.URL.Path {
+	case "/xrpc/com.atproto.server.refreshSession":
+		//fmt.Println("refreshSession handler...")
+		hdr := r.Header.Get("Authorization")
+		if hdr != "Bearer refresh1" {
+			fmt.Printf("refreshSession header: %s\n", hdr)
+			w.Header().Set("WWW-Authenticate", `Bearer`)
+			http.Error(w, "Unauthorized", http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{
+			"did":        "did:web:account.example.com",
+			"accessJwt":  "access2",
+			"refreshJwt": "refresh2",
+		})
+		return
+	case "/xrpc/com.atproto.server.deleteSession":
+		//fmt.Println("deleteSession handler...")
+		hdr := r.Header.Get("Authorization")
+		if hdr != "Bearer refresh1" {
+			fmt.Printf("refreshSession header: %s\n", hdr)
+			w.Header().Set("WWW-Authenticate", `Bearer`)
+			http.Error(w, "Unauthorized", http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		return
+	case "/xrpc/com.atproto.server.createSession":
+		if !strings.HasPrefix(r.Header.Get("Content-Type"), "application/json") {
+			fmt.Println("createSession Content-Type")
+			http.Error(w, "Bad Request", http.StatusBadRequest)
+			return
+		}
+		var body map[string]string
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			fmt.Println("createSession JSON")
+			http.Error(w, "Bad Request", http.StatusBadRequest)
+			return
+		}
+		if body["identifier"] != "did:web:account.example.com" || body["password"] != "password1" {
+			fmt.Println("createSession wrong password")
+			http.Error(w, "Bad Request", http.StatusUnauthorized)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{
+			"did":        body["identifier"],
+			"accessJwt":  "access1",
+			"refreshJwt": "refresh1",
+		})
+		return
+	case "/xrpc/com.example.get", "/xrpc/com.example.post":
+		hdr := r.Header.Get("Authorization")
+		if hdr == "Bearer access1" || hdr == "Bearer access2" {
+			w.Header().Set("Content-Type", "application/json")
+			fmt.Fprintln(w, "{\"status\":\"success\"}")
+			return
+		} else {
+			fmt.Printf("get header: %s\n", hdr)
+			w.Header().Set("WWW-Authenticate", `Bearer`)
+			http.Error(w, "Unauthorized", http.StatusUnauthorized)
+			return
+		}
+	case "/xrpc/com.example.expire":
+		hdr := r.Header.Get("Authorization")
+		if hdr == "Bearer access1" {
+			//fmt.Println("forcing refresh...")
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(400)
+			fmt.Fprintln(w, "{\"error\":\"ExpiredToken\"}")
+			return
+		} else if hdr == "Bearer access2" {
+			w.Header().Set("Content-Type", "application/json")
+			fmt.Fprintln(w, "{\"status\":\"success\"}")
+			return
+		} else {
+			fmt.Printf("expire header: %s\n", hdr)
+			w.Header().Set("WWW-Authenticate", `Bearer`)
+			http.Error(w, "Unauthorized", http.StatusUnauthorized)
+			return
+		}
+	default:
+		http.NotFound(w, r)
+		return
+	}
+}
+
+func TestPasswordAuth(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+	ctx := context.Background()
+
+	srv := httptest.NewServer(http.HandlerFunc(pwHandler))
+	defer srv.Close()
+
+	dir := identity.NewMockDirectory()
+	dir.Insert(identity.Identity{
+		DID:    "did:web:account.example.com",
+		Handle: "user1.example.com",
+		Services: map[string]identity.Service{
+			"atproto_pds": {
+				Type: "AtprotoPersonalDataServer",
+				URL:  srv.URL,
+			},
+		},
+	})
+
+	{
+		// simple GET requests, with token expire/retry
+		c, err := LoginWithPassword(ctx, &dir, syntax.Handle("user1.example.com").AtIdentifier(), "password1", "", nil)
+		require.NoError(err)
+		err = c.Get(ctx, syntax.NSID("com.example.get"), nil, nil)
+		assert.NoError(err)
+		err = c.Get(ctx, syntax.NSID("com.example.expire"), nil, nil)
+		assert.NoError(err)
+	}
+
+	{
+		// test resume session, and session data callback mechanism
+		ch := make(chan string, 10)
+		cb := func(ctx context.Context, data PasswordSessionData) {
+			assert.Equal("refresh2", data.RefreshToken)
+			ch <- "refreshed"
+		}
+		c := ResumePasswordSession(PasswordSessionData{
+			AccessToken:  "access1",
+			RefreshToken: "refresh1",
+			AccountDID:   syntax.DID("did:web:account.example.com"),
+			Host:         srv.URL,
+		}, cb)
+
+		err := c.Get(ctx, syntax.NSID("com.example.get"), nil, nil)
+		assert.NoError(err)
+		err = c.Get(ctx, syntax.NSID("com.example.expire"), nil, nil)
+		assert.NoError(err)
+
+		select {
+		case msg := <-ch:
+			assert.Equal("refreshed", msg)
+		}
+	}
+
+	{
+		// logout
+		c, err := LoginWithPassword(ctx, &dir, syntax.Handle("user1.example.com").AtIdentifier(), "password1", "", nil)
+		require.NoError(err)
+
+		passAuth, ok := c.Auth.(*PasswordAuth)
+		require.True(ok)
+		err = passAuth.Logout(ctx, c.Client)
+		assert.NoError(err)
+	}
+
+	{
+		// simple POST request, with token expire/retry
+		c, err := LoginWithPassword(ctx, &dir, syntax.Handle("user1.example.com").AtIdentifier(), "password1", "", nil)
+		require.NoError(err)
+		body := map[string]any{
+			"a": 123,
+			"b": "hello",
+		}
+		var out json.RawMessage
+		err = c.Post(ctx, syntax.NSID("com.example.post"), body, &out)
+		assert.NoError(err)
+		err = c.Post(ctx, syntax.NSID("com.example.expire"), body, &out)
+		assert.NoError(err)
+	}
+
+	{
+		// POST with bytes.Buffer body
+		c, err := LoginWithPassword(ctx, &dir, syntax.Handle("user1.example.com").AtIdentifier(), "password1", "", nil)
+		require.NoError(err)
+		body := bytes.NewBufferString("some text")
+		req := NewAPIRequest(MethodProcedure, syntax.NSID("com.example.expire"), body)
+		req.Headers.Set("Content-Type", "text/plain")
+		resp, err := c.Do(ctx, req)
+		require.NoError(err)
+		assert.Equal(200, resp.StatusCode)
+	}
+
+	{
+		// POST with file on disk (can seek and retry)
+		c, err := LoginWithPassword(ctx, &dir, syntax.Handle("user1.example.com").AtIdentifier(), "password1", "", nil)
+		require.NoError(err)
+		f, err := os.Open("testdata/body.json")
+		require.NoError(err)
+		req := NewAPIRequest(MethodProcedure, syntax.NSID("com.example.expire"), f)
+		req.Headers.Set("Content-Type", "application/json")
+		resp, err := c.Do(ctx, req)
+		require.NoError(err)
+		assert.Equal(200, resp.StatusCode)
+	}
+
+	{
+		// POST with pipe reader (can *not* retry)
+		c, err := LoginWithPassword(ctx, &dir, syntax.Handle("user1.example.com").AtIdentifier(), "password1", "", nil)
+		require.NoError(err)
+		r1, w1 := io.Pipe()
+		go func() {
+			fmt.Fprintf(w1, "some data")
+			w1.Close()
+		}()
+		req1 := NewAPIRequest(MethodProcedure, syntax.NSID("com.example.post"), r1)
+		req1.Headers.Set("Content-Type", "text/plain")
+		resp, err := c.Do(ctx, req1)
+		require.NoError(err)
+		assert.Equal(200, resp.StatusCode)
+
+		// expect this to fail (can't re-read from Pipe)
+		r2, w2 := io.Pipe()
+		go func() {
+			fmt.Fprintf(w2, "some data")
+			w2.Close()
+		}()
+		req2 := NewAPIRequest(MethodProcedure, syntax.NSID("com.example.expire"), r2)
+		req2.Headers.Set("Content-Type", "text/plain")
+		_, err = c.Do(ctx, req2)
+		assert.Error(err)
+	}
+}

atproto/client/testdata/body.json

···
+{
+	"a": 123,
+	"b": "hello"
+}