atp #

AT Protocol boilerplate for Go, extracted from arabica.social. Covers OAuth flows, PDS client operations, real-time event consumption, session storage, and HTTP middleware.

For integration testing against an ephemeral in-process PDS, see chrysalis.

Installation #

go get tangled.org/pdewey.com/atp@latest

Packages #

Root (atp) #

Core types and clients for the AT Protocol.

• Client -- authenticated PDS client for CRUD operations on a user's repository (CreateRecord, GetRecord, ListRecords, PutRecord, DeleteRecord, UploadBlob, GetBlob).
• OAuthApp -- manages the OAuth flow: login (browser-based and CLI), callback handling, session resumption, and logout. Supports public and localhost (development) client modes.
• PublicClient -- unauthenticated access to public atproto APIs (handle resolution, profiles, record reads) with SSRF protection.
• Helpers for AT-URI parsing/building, scope construction, and error handling.

jetstream #

Consumers for both Jetstream protocols:

• New uses the legacy /subscribe protocol and keeps its timestamp cursor and options_update behavior.
• NewV2 wraps the official canonical v2 client. It supports live sequence cursors, archive replay, sync events, v2 dictionary compression, and filter changes by reconnecting.

V2 cursors are scoped to one host and one canonical filter set. A batch is checkpointed only after every event handler call succeeds; handler and cursor-store failures stop Run, so a restart replays the uncommitted batch.

consumer, err := jetstream.NewV2(&jetstream.V2Config{
	Host:              jetstream.DefaultV2Host,
	WantedCollections: []string{"app.bsky.feed.post"},
	WantedKinds:       []string{jetstream.KindCommit},
	CursorStore:       cursors,
	// ReplayArchive requires an API key on hosted public instances.
	ReplayArchive: true,
	APIKey:        os.Getenv("JETSTREAM_API_KEY"),
}, func(ctx context.Context, event *jetstream.Event) error {
	// Apply the event transactionally or idempotently. Decode known records
	// through Indigo with event.Commit.DecodeRecord().
	return apply(ctx, event)
})
if err != nil {
	return err
}
defer consumer.Close()

if err := consumer.Run(ctx); err != nil {
	return err
}

middleware #

Cookie-based AT Protocol auth middleware. Validates sessions against the OAuth store and injects the authenticated DID into the request context. Also serves the OAuth client metadata endpoint.

store/bolt and store/sqlite #

Two oauth.ClientAuthStore implementations for persisting OAuth sessions and auth request state:

• bolt: BoltDB-backed.
• sqlite: SQLite-backed with automatic schema migration and expired request cleanup.

tracing #

OpenTelemetry span helpers for AT Protocol operations (PDS calls, database operations, HTTP handlers). Sets up an OTLP HTTP exporter and returns no-op spans when there is no active trace context.