atproto pds in zig
pds.zat.dev
pds
atproto
document pds ecosystem references
+157
-29
+157
-29
docs/references.md
+157
-29
docs/references.md
···
1
-
# references
1
+
# pds ecosystem references
2
+
3
+
ZDS is built with a small set of PDS implementations and adjacent projects in
4
+
mind. This file records what each one is useful for so future work can start
5
+
from known prior art instead of rediscovering it.
6
+
7
+
## primary references
8
+
9
+
### official Bluesky PDS
10
+
11
+
Links:
12
+
[legacy repo](https://github.com/bluesky-social/pds),
13
+
[atproto package](https://github.com/bluesky-social/atproto/tree/main/packages/pds)
14
+
15
+
Use it as the compatibility floor. If an endpoint, repo write, sync frame,
16
+
invite-code rule, app-password route, account status field, or OAuth behavior is
17
+
implemented by the official PDS, ZDS should usually match it unless there is a
18
+
documented reason not to.
19
+
20
+
Strengths:
21
+
22
+
- broad client compatibility with bsky.app and ecosystem OAuth clients
23
+
- SQLite-backed account, invite, token, repo, blob, and identity state
24
+
- record preparation behavior for known and unknown lexicons
25
+
- sync and firehose frame shape, including inductive Sync 1.1 fields
26
+
- operational conventions around crawlers, email, app passwords, and admin APIs
27
+
28
+
Use it especially for:
29
+
30
+
- XRPC response shape and error codes
31
+
- app-password and invite-code behavior
32
+
- DID/PLC migration and recommended credentials
33
+
- repo import/export and block storage expectations
34
+
- conformance tests and bug triage
35
+
36
+
### Tranquil
37
+
38
+
Link: [tranquil.farm/tranquil-pds](https://tangled.org/tranquil.farm/tranquil-pds)
39
+
40
+
Use it as the maturity reference. Tranquil is more ambitious than the official
41
+
PDS in places, but it tends to separate concerns cleanly and has already solved
42
+
many problems ZDS wants to grow into.
43
+
44
+
Strengths:
45
+
46
+
- clean store boundaries and storage-specific benchmark targets
47
+
- strong validation and conformance posture
48
+
- passkey/WebAuthn login support
49
+
- richer account security model: sessions, app passwords, token lifecycle, and
50
+
audit-friendly account state
51
+
- delegation-oriented subject/actor/controller distinctions
52
+
- good instinct for keeping appview behavior outside the PDS
2
53
3
-
## implementation references
54
+
Use it especially for:
4
55
5
-
- [Tranquil PDS](https://tangled.org/tranquil.farm/tranquil-pds): broad
6
-
community PDS reference, strong validation and storage separation.
7
-
- [Pegasus](https://tangled.org/futur.blue/pegasus): compact architectural
8
-
reference with clear protocol module
9
-
boundaries.
10
-
- [Bluesky PDS](https://github.com/bluesky-social/pds): compatibility oracle
11
-
for endpoint behavior, record preparation, sync shape, and operational
12
-
expectations.
13
-
- [Bluesky atproto PDS package](https://github.com/bluesky-social/atproto/tree/main/packages/pds):
14
-
implementation source for the published reference PDS package.
15
-
- [pds.js](https://tangled.org/chadtmiller.com/pds.js): compact endpoint and
16
-
architecture reference.
17
-
- [Cocoon](https://github.com/haileyok/cocoon): additional PDS implementation
18
-
context.
19
-
- [PDS Gatekeeper](https://tangled.org/pds.dad/pds-gatekeeper): operational
20
-
policy sidecar reference for captcha-gated account creation, 2FA, and
21
-
migration-only createAccount deployments.
56
+
- account-plane hardening
57
+
- passkey UX and credential storage semantics
58
+
- OAuth refresh/revocation edge cases
59
+
- benchmark design and metastore comparisons
60
+
- delegation groundwork
61
+
62
+
### Pegasus
63
+
64
+
Link: [futur.blue/pegasus](https://tangled.org/futur.blue/pegasus)
65
+
66
+
Use it as a compact architecture reference. Pegasus is useful when ZDS needs a
67
+
smaller codebase to compare module boundaries, protocol routing, and generic PDS
68
+
shape without inheriting the full complexity of the official implementation.
22
69
23
-
## test and app references
70
+
Strengths:
24
71
25
-
- [atproto-smoke](https://tangled.org/alice.mosphere.at/atproto-smoke):
26
-
browser-oriented compatibility testing.
27
-
- pollz: Zig + SvelteKit ATProto app using OAuth, SQLite, Jetstream, and PDS
72
+
- readable PDS organization
73
+
- clear protocol module boundaries
74
+
- useful contrast against both Tranquil's broader architecture and the official
75
+
PDS's production-oriented codebase
76
+
77
+
Use it especially for:
78
+
79
+
- sanity-checking whether a ZDS module boundary is understandable
80
+
- comparing minimal PDS surface area
81
+
- avoiding overfitting to bsky-specific client pressure
82
+
83
+
## secondary and adjacent references
84
+
85
+
### Cocoon
86
+
87
+
Link: [haileyok/cocoon](https://github.com/haileyok/cocoon)
88
+
89
+
Cocoon is useful additional PDS context, especially for seeing a different
90
+
implementation's tradeoffs around repo/account organization. Treat it as
91
+
informative rather than normative.
92
+
93
+
### distributed-pds
94
+
95
+
Link: [willdot.net/distributed-pds](https://tangled.org/willdot.net/distributed-pds)
96
+
97
+
This is useful for thinking about future account delegation and distributed PDS
98
+
shape. It should influence abstractions only after the official PDS and
99
+
Tranquil have been checked, because it is more experimental.
100
+
101
+
### pds.js
102
+
103
+
Link: [chadtmiller.com/pds.js](https://tangled.org/chadtmiller.com/pds.js)
104
+
105
+
Useful as a compact endpoint reference and a quick way to compare how a smaller
106
+
implementation handles basic routing and PDS behaviors.
107
+
108
+
### pds-message-poc
109
+
110
+
Link: [zzstoatzz.io/pds-message-poc](https://tangled.org/zzstoatzz.io/pds-message-poc)
111
+
112
+
Useful for custom records and PDS-to-PDS behavior. This is app-adjacent context,
113
+
not a substitute for PDS conformance.
114
+
115
+
### PDS Gatekeeper
116
+
117
+
Link: [pds.dad/pds-gatekeeper](https://tangled.org/pds.dad/pds-gatekeeper)
118
+
119
+
Useful operational policy prior art for captcha-gated account creation, 2FA, and
120
+
migration-only account creation. It can inform boundary policy, but it does not
121
+
replace invite-code accounting inside the PDS.
122
+
123
+
### PDS Moover
124
+
125
+
Link: [pds.dad/pds-moover](https://tangled.org/pds.dad/pds-moover)
126
+
127
+
Useful for migration behavior and PLC rotation-key handling as observed by real
128
+
PDS moves. When migration behavior is confusing, check this alongside the
129
+
official PDS before assuming what key material should be stored or exposed.
130
+
131
+
## test and workload references
132
+
133
+
- [alice.mosphere.at/atproto-smoke](https://tangled.org/alice.mosphere.at/atproto-smoke):
134
+
browser-oriented PDS compatibility tests.
135
+
- [zzstoatzz.io/atproto-bench](https://tangled.org/zzstoatzz.io/atproto-bench):
136
+
benchmark rigor and methodology reference.
137
+
- `pollz`: Zig + SvelteKit ATProto app using OAuth, SQLite, Jetstream, and PDS
28
138
writes.
29
-
- [pds-message-poc](https://tangled.org/zzstoatzz.io/pds-message-poc):
30
-
custom-record and PDS-to-PDS behavior reference.
31
-
- pds.js and atproto-smoke helped identify which endpoint failures are client
32
-
visible versus appview/proxy visible.
139
+
- `plyr.fm`, `streamplace`, `pds.ls`, and bsky.app are useful live client probes
140
+
because they exercise OAuth, scope handling, repo writes, blobs, appview proxy
141
+
routes, and client expectations differently.
142
+
143
+
## reference hierarchy
144
+
145
+
When references disagree, use this order:
146
+
147
+
1. atproto specs and lexicons
148
+
2. official Bluesky PDS behavior
149
+
3. Tranquil for richer mature behavior and implementation shape
150
+
4. Pegasus or other compact implementations for readability checks
151
+
5. experimental or app-adjacent references for ideas only
152
+
153
+
Any intentional ZDS divergence from the first three should be documented near
154
+
the code or in the relevant docs page.
33
155
34
156
## lessons kept in code
35
157
···
48
170
live at the PDS boundary or a reverse proxy boundary; pds-gatekeeper is useful
49
171
prior art for that layer, not a substitute for invite-code accounting.
50
172
- Passkeys are Tranquil-derived, not reference-PDS-derived: store credential
51
-
IDs, public keys, counters, names, and timestamps, and verify WebAuthn
173
+
IDs, public keys, counters, names, and timestamps, and verify WebAuthN
52
174
assertions before authorizing OAuth requests.
175
+
- Account-plane security should be storage-backed. Sessions, refresh rotation,
176
+
app passwords, OAuth grants, passkeys, and revocation are not merely JWT
177
+
formatting concerns.
178
+
- Delegation-ready code should keep subject, actor, and controller identities
179
+
distinct even before user-facing account delegation exists.
53
180
54
-
## Tranquil comparison
181
+
## active comparison work
55
182
56
183
ZDS should stay close to Tranquil's design where it has already solved a PDS
57
184
problem cleanly:
···
61
188
- keep appview behavior behind `atproto-proxy`
62
189
- validate known records before writes are accepted
63
190
- report latency percentiles for storage operations
191
+
- keep account security surfaces durable and inspectable
64
192
65
193
See [benchmarks](../bench/README.md) for the active performance comparison
66
194
work.