zzstoatzz.io
+85
docs/tools/tap.md
+85
docs/tools/tap.md
···
1
+
# tap
2
+
3
+
bluesky's ATProto sync utility for backfilling and streaming custom lexicons.
4
+
5
+
## install
6
+
7
+
```bash
8
+
go install github.com/bluesky-social/indigo/cmd/tap@latest
9
+
```
10
+
11
+
binary lands at `~/go/bin/tap`
12
+
13
+
## run locally
14
+
15
+
```bash
16
+
TAP_SIGNAL_COLLECTION=fm.plyr.track \
17
+
TAP_COLLECTION_FILTERS=fm.plyr.* \
18
+
TAP_LOG_LEVEL=info \
19
+
~/go/bin/tap run
20
+
```
21
+
22
+
this will:
23
+
1. enumerate all repos with `fm.plyr.track` via `com.atproto.sync.listReposByCollection`
24
+
2. backfill those repos, extracting any `fm.plyr.*` records
25
+
3. stream the firehose for new records
26
+
4. serve events via websocket at `ws://localhost:2480/channel`
27
+
28
+
## what we found
29
+
30
+
initial network scan (dec 2025):
31
+
- 35 repos with `fm.plyr.track` records
32
+
- 497 total records indexed
33
+
34
+
breakdown:
35
+
```
36
+
fm.plyr.track 273
37
+
fm.plyr.like 90
38
+
fm.plyr.list 41
39
+
fm.plyr.dev.track 18
40
+
fm.plyr.comment 15
41
+
fm.plyr.actor.profile 13
42
+
(plus staging/dev variants)
43
+
```
44
+
45
+
## consuming events
46
+
47
+
events come through `/channel` websocket as JSON:
48
+
49
+
```json
50
+
{
51
+
"id": 439,
52
+
"type": "record",
53
+
"record": {
54
+
"live": false,
55
+
"did": "did:plc:...",
56
+
"collection": "fm.plyr.track",
57
+
"rkey": "3m7m3wyasmi2l",
58
+
"action": "create",
59
+
"record": {
60
+
"title": "...",
61
+
"artist": "...",
62
+
"audioUrl": "https://..."
63
+
}
64
+
}
65
+
}
66
+
```
67
+
68
+
ack events to consume them: `{"ack": <id>}`
69
+
70
+
see `sandbox/tap/read_events.py` for example consumer.
71
+
72
+
## api endpoints
73
+
74
+
- `GET /health` - status check
75
+
- `POST /repos/add` - track a DID
76
+
- `POST /repos/remove` - stop tracking
77
+
- `GET /stats/repo-count` - tracked repos
78
+
- `GET /stats/record-count` - indexed records
79
+
- `WS /channel` - event stream
80
+
81
+
## resources
82
+
83
+
- [tap README](https://github.com/bluesky-social/indigo/blob/main/cmd/tap/README.md)
84
+
- [bailey's guide](https://marvins-guide.leaflet.pub/3m7ttuppfzc23)
85
+
- [@atproto/tap](https://www.npmjs.com/package/@atproto/tap) - typescript client