Go boilerplate library for building atproto apps
atproto
go
chore: remove readme artifact
-65
-65
temp.html
-65
temp.html
···
1
-
<h1 id="atp">atp</h1>
2
-
<p>AT Protocol boilerplate for Go, extracted from <a
3
-
href="https://tangled.org/arabica.social/arabica">arabica.social</a>.
4
-
Covers OAuth flows, PDS client operations, real-time event consumption,
5
-
session storage, HTTP middleware, and testing infrastructure.</p>
6
-
<blockquote>
7
-
<p>The <code>testpds</code> package pulls in <a
8
-
href="https://github.com/haileyok/cocoon">cocoon</a> to spin up
9
-
ephemeral PDS instances, which makes the dependency tree heavy. This is
10
-
a single module, so the transitive cost applies even if you only use the
11
-
client or OAuth packages.</p>
12
-
</blockquote>
13
-
<h2 id="packages">Packages</h2>
14
-
<h3 id="root-atp">Root (<code>atp</code>)</h3>
15
-
<p>Core types and clients for the AT Protocol.</p>
16
-
<ul>
17
-
<li><code>Client</code> – authenticated PDS client for CRUD operations
18
-
on a user’s repository (<code>CreateRecord</code>,
19
-
<code>GetRecord</code>, <code>ListRecords</code>,
20
-
<code>PutRecord</code>, <code>DeleteRecord</code>,
21
-
<code>UploadBlob</code>, <code>GetBlob</code>).</li>
22
-
<li><code>OAuthApp</code> – manages the OAuth flow: login (browser-based
23
-
and CLI), callback handling, session resumption, and logout. Supports
24
-
public and localhost (development) client modes.</li>
25
-
<li><code>PublicClient</code> – unauthenticated access to public atproto
26
-
APIs (handle resolution, profiles, record reads) with SSRF
27
-
protection.</li>
28
-
<li>Helpers for AT-URI parsing/building, scope construction, and error
29
-
handling.</li>
30
-
</ul>
31
-
<h3 id="jetstream"><code>jetstream</code></h3>
32
-
<p>WebSocket consumer for the <a
33
-
href="https://docs.bsky.app/blog/jetstream">Jetstream</a> relay.
34
-
Reconnects with exponential backoff, rotates endpoints, optionally
35
-
decompresses zstd, and persists cursors for resuming after restarts.</p>
36
-
<h3 id="middleware"><code>middleware</code></h3>
37
-
<p>Cookie-based AT Protocol auth middleware. Validates sessions against
38
-
the OAuth store and injects the authenticated DID into the request
39
-
context. Also serves the OAuth client metadata endpoint.</p>
40
-
<h3 id="storebolt-and-storesqlite"><code>store/bolt</code> and
41
-
<code>store/sqlite</code></h3>
42
-
<p>Two <code>oauth.ClientAuthStore</code> implementations for persisting
43
-
OAuth sessions and auth request state:</p>
44
-
<ul>
45
-
<li>bolt: BoltDB-backed.</li>
46
-
<li>sqlite: SQLite-backed with automatic schema migration and expired
47
-
request cleanup.</li>
48
-
</ul>
49
-
<h3 id="testpds"><code>testpds</code></h3>
50
-
<p>Ephemeral, in-process PDS for integration testing. Uses in-memory
51
-
SQLite and an optional <code>FakePLC</code> (from <code>plc</code>) so
52
-
tests need no external services. Includes helpers for creating test
53
-
accounts and subscribing to the firehose.</p>
54
-
<h3 id="plc"><code>plc</code></h3>
55
-
<p>Mock PLC directory that stores operations in memory instead of
56
-
posting to a real directory. Used by <code>testpds</code> for isolated
57
-
test environments.</p>
58
-
<h3 id="tracing"><code>tracing</code></h3>
59
-
<p>OpenTelemetry span helpers for AT Protocol operations (PDS calls,
60
-
database operations, HTTP handlers). Sets up an OTLP HTTP exporter and
61
-
returns no-op spans when there is no active trace context.</p>
62
-
<h2 id="installation">Installation</h2>
63
-
<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> get tangled.org/pdewey.com/atp</span></code></pre></div>
64
-
<h2 id="license">License</h2>
65
-
<p>See <a href="LICENSE">LICENSE</a> for details.</p>