excuse - mount jetstream as a character device on linux
CUSE is FUSE's little brother, and it allows mounting a
single character device file in /dev, with the device driver
being implemented in userspace.
unlike typical files, character devices like /dev/urandom
are not seekable. they only support a streaming interface:
λ cat /dev/urandom # random numbers
excuse simply mounts a websocket connection to an atproto
jetstream as a userspace character device:
λ sudo RUST_LOG=info excuse
[2025-09-21 INFO excuse] Initializing CUSE at /dev/jetstream
[2025-09-21 INFO excuse] /dev/jetstream is now 0644
in another terminal:
λ cat /dev/jetstream | jq
{
"did": "did:plc:s6zjj6aw652mmvsrs573j6ti",
"time_us": 1758442606746247,
"kind": "commit",
"commit": { ... }
}
.
.
.
you will notice a couple of optimizations:
- the websocket is only opened when the file has readers,
and is closed when all readers are closed
- the same connection is shared by all readers
- the data is buffered and not sent byte by byte
it is a bit of a gimmick however, you can do this easily
with websocat:
λ websocat wss://jetstream1.us-east.fire.hose.cam/subscribe
Rust
100.0%
code
Clone this repository
https://tangled.org/oppi.li/excuse
git@tangled.org:oppi.li/excuse
For self-hosted knots, clone URLs may differ based on your setup.
Signed-off-by: oppiliappan <me@oppi.li>
readme.txt