ptr.pet
at protocol indexer with flexible filtering, xrpc queries, and a cursor-backed event stream, built on fjall
at-protocol
atproto
indexer
rust
fjall
[docs] move the vs tap section to the top of the readme
+16
-16
README.md
+16
-16
README.md
···
2
2
3
3
`hydrant` is an AT Protocol indexer built on the `fjall` database. it's meant to be a flexible indexer, supporting both full-network indexing and filtered indexing (e.g., by DID), also allowing querying with XRPCs and providing an ordered event stream with cursor support.
4
4
5
+
## vs `tap`
6
+
7
+
while [`tap`](https://github.com/bluesky-social/indigo/tree/main/cmd/tap) is designed primarily as a firehose consumer and relay, `hydrant` is flexible, it allows you to directly query the database for records, and it also provides an ordered view of events, allowing the use of a cursor to fetch events from a specific point in time.
8
+
9
+
### stream behavior
10
+
11
+
the `WS /stream` (hydrant) and `WS /channel` (tap) endpoints have different designs:
12
+
13
+
| aspect | `tap` (`/channel`) | `hydrant` (`/stream`) |
14
+
| :--- | :--- | :--- |
15
+
| distribution | sharded work queue: events are load-balanced across connected clients. If 5 clients connect, each receives ~20% of events. | broadcast: every connected client receives a full copy of the event stream. If 5 clients connect, all 5 receive 100% of events. |
16
+
| cursors | server-managed: clients ACK messages. The server tracks progress and redelivers unacked messages. | client-managed: client provides `?cursor=123`. The server streams from that point. |
17
+
| backfill | integrated queue: backfill events are mixed into the live queue and prioritized by the server. | unified log: backfill simply inserts "historical" events (`live: false`) into the global event log. streaming is just reading this log sequentially. |
18
+
| event types | `record`, `identity` (includes status) | `record`, `identity` (handle), `account` (status) |
19
+
| persistence | **full**: all events are stored and replayable. | **hybrid**: `record` events are persisted/replayable. `identity`/`account` are ephemeral/live-only. |
20
+
5
21
## configuration
6
22
7
23
`hydrant` is configured via environment variables. all variables are prefixed with `HYDRANT_`.
···
127
143
### stats
128
144
129
145
- `GET /stats`: get aggregate counts of repos, records, events, and errors.
130
-
131
-
## vs `tap`
132
-
133
-
while [`tap`](https://github.com/bluesky-social/indigo/tree/main/cmd/tap) is designed primarily as a firehose consumer and relay, `hydrant` is flexible, it allows you to directly query the database for records, and it also provides an ordered view of events, allowing the use of a cursor to fetch events from a specific point in time.
134
-
135
-
### stream behavior
136
-
137
-
the `WS /stream` (hydrant) and `WS /channel` (tap) endpoints have different designs:
138
-
139
-
| aspect | `tap` (`/channel`) | `hydrant` (`/stream`) |
140
-
| :--- | :--- | :--- |
141
-
| distribution | sharded work queue: events are load-balanced across connected clients. If 5 clients connect, each receives ~20% of events. | broadcast: every connected client receives a full copy of the event stream. If 5 clients connect, all 5 receive 100% of events. |
142
-
| cursors | server-managed: clients ACK messages. The server tracks progress and redelivers unacked messages. | client-managed: client provides `?cursor=123`. The server streams from that point. |
143
-
| backfill | integrated queue: backfill events are mixed into the live queue and prioritized by the server. | unified log: backfill simply inserts "historical" events (`live: false`) into the global event log. streaming is just reading this log sequentially. |
144
-
| event types | `record`, `identity` (includes status) | `record`, `identity` (handle), `account` (status) |
145
-
| persistence | **full**: all events are stored and replayable. | **hybrid**: `record` events are persisted/replayable. `identity`/`account` are ephemeral/live-only. |