Jetrelay: A high-performance ATproto relay in 500 LOC

Summary

Let the kernel do the work!Tricks for implementing a pub/sub server This post explains the design of jetrelay, a pub/sub server compatible with Bluesky’s “jetstream” data feed. Using a few pertinent Linux kernel features, it avoids doing almost any work itself. As a result, it’s highly efficient: it can saturate a 10 Gbps network connection with just 8 CPU cores. May 2025 The challenge: Broadcasting at line rate Bluesky is built on ATproto, and a core part of ATproto is “the firehose”, a stream of events representing all changes to the state of the network. The firehose contains all the new posts, as you’d expect; but also people liking things, deleting/editing their old posts, following people, etc. It covers the whole of Bluesky, so it’s fairly active. This data comes in two flavours: the original full-fat firehose, and a new slimmed-down version called “jetstream”. Both feeds are websockets-based, but jetstream encodes its payloads as JSON (rather than CBOR) and omits the bits that are only needed for authentication. Also, I think jetstream only contains a subset of the events. The average message size on jetstream is around half a kilobyte. The event rate is variable (I guess it depends on which countries are awake), but it seems to be around 300–500 events per second. A relay is a server which follows an upstream feed provider and re-broadcasts the data to its own clients. Napkin estimate: running on a machine with a 10 gigabit NIC, your relay should be able serve 10Gbps / (0.5KiB * 400/s) = ~6000 clients simultaneously. OK, challenge accepted! I’ve written a simple jetstream relay which I’m calling “jetrelay”. It’s only ~500 LOC, the code lives here, and in this post I’m going to explain how it works. Very few of those 500 lines are actually specific to jetstream. The point of jetrelay is to demonstrate the techniques described below, which should be transferrable to implementations of other pub/sub protocols. Be aware, though, that jetrelay is a tech demo—mor...