mount jetstream as a userspace character device on linux
Rust 100.0%
3 1 0

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.

readme.txt
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