Go boilerplate library for building atproto apps
atproto
go
chore: license and readme
+135
+21
LICENSE
+21
LICENSE
···
1
+
MIT License
2
+
3
+
Copyright (c) 2026 Patrick Dewey
4
+
5
+
Permission is hereby granted, free of charge, to any person obtaining a copy
6
+
of this software and associated documentation files (the "Software"), to deal
7
+
in the Software without restriction, including without limitation the rights
8
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+
copies of the Software, and to permit persons to whom the Software is
10
+
furnished to do so, subject to the following conditions:
11
+
12
+
The above copyright notice and this permission notice shall be included in all
13
+
copies or substantial portions of the Software.
14
+
15
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+
SOFTWARE.
+49
README.md
+49
README.md
···
1
+
# atp
2
+
3
+
AT Protocol boilerplate for Go, extracted from [arabica.social](https://tangled.org/arabica.social/arabica). Covers OAuth flows, PDS client operations, real-time event consumption, session storage, HTTP middleware, and testing infrastructure.
4
+
5
+
> Note: The `testpds` package pulls in [cocoon](https://github.com/haileyok/cocoon) to spin up ephemeral PDS instances, which makes the dependency tree heavy (indigo, aws-sdk, etc.).
6
+
7
+
## Installation
8
+
9
+
```sh
10
+
go get tangled.org/pdewey.com/atp@latest
11
+
```
12
+
13
+
## Packages
14
+
15
+
### Root (`atp`)
16
+
17
+
Core types and clients for the AT Protocol.
18
+
19
+
- `Client` -- authenticated PDS client for CRUD operations on a user's repository (`CreateRecord`, `GetRecord`, `ListRecords`, `PutRecord`, `DeleteRecord`, `UploadBlob`, `GetBlob`).
20
+
- `OAuthApp` -- manages the OAuth flow: login (browser-based and CLI), callback handling, session resumption, and logout. Supports public and localhost (development) client modes.
21
+
- `PublicClient` -- unauthenticated access to public atproto APIs (handle resolution, profiles, record reads) with SSRF protection.
22
+
- Helpers for AT-URI parsing/building, scope construction, and error handling.
23
+
24
+
### `jetstream`
25
+
26
+
WebSocket consumer for the [Jetstream](https://docs.bsky.app/blog/jetstream) relay. Reconnects with exponential backoff, rotates endpoints, optionally decompresses zstd, and persists cursors for resuming after restarts.
27
+
28
+
### `middleware`
29
+
30
+
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.
31
+
32
+
### `store/bolt` and `store/sqlite`
33
+
34
+
Two `oauth.ClientAuthStore` implementations for persisting OAuth sessions and auth request state:
35
+
36
+
- bolt: BoltDB-backed.
37
+
- sqlite: SQLite-backed with automatic schema migration and expired request cleanup.
38
+
39
+
### `testpds`
40
+
41
+
Ephemeral, in-process PDS for integration testing. Uses in-memory SQLite and an optional `FakePLC` (from `plc`) so tests need no external services. Includes helpers for creating test accounts and subscribing to the firehose.
42
+
43
+
### `plc`
44
+
45
+
Mock PLC directory that stores operations in memory instead of posting to a real directory. Used by `testpds` for isolated test environments.
46
+
47
+
### `tracing`
48
+
49
+
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.
+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>