microcosm-rs

microcosm HTTP APIs + rust crates

Welcome! Documentation is under active development. If you like reading API docs, you'll probably hit the ground running!

Tutorials, how-to guides, and client SDK libraries are all in the works for gentler on-ramps, but are not quite ready yet. But don't let that stop you! Hop in the microcosm discord, or post questions and tag @bad-example.com on Bluesky if you get stuck anywhere.

[!tip] This repository's primary home is moving to tangled: @microcosm.blue/microcosm-rs. It will continue to be mirrored on github for the forseeable future, and it's fine to open issues or pulls in either place!

🌌 Constellation

A global atproto interactions backlink index as a simple JSON API. Works with every lexicon, runs on a raspberry pi, consumes less than 2GiB of disk per day. Handles record deletion, account de/re-activation, and account deletion, ensuring accurate link counts while respecting users' data choices.

• Source: ./constellation/
• Public instance/API docs
• Status: used in production. APIs will change but backwards compatibility will be maintained as long as needed.

🎇 Spacedust

A global atproto interactions firehose. Extracts all at-uris, DIDs, and URLs from every lexicon in the firehose, and exposes them over a websocket modelled after jetstream.

• Source: ./spacedust/
• Public instance/API docs
• Status: v0: the basics work and the APIs are in place! missing cursor replay, forward link storage, and delete event link hydration.

Demos:

• Spacedust notifications: web push notifications for every atproto app
• Zero-Bluesky real-time interaction-updating post embed

🛰️ Slingshot

A fast, eager, production-grade edge cache for atproto records and identities. Pre-caches all records from the firehose and maintains a longer-term cache of requested records on disk.

• Source: ./slingshot/
• Public instance/API docs
• Status: v0: most XRPC APIs are working. cache storage is being reworked.

🛸 UFOs API

Timeseries stats and sample records for every collection ever seen in the atproto firehose. Unique users are counted in hyperloglog sketches enabling arbitrary cardinality aggregation across time buckets and/or NSIDs.

• Source: ./ufos/
• Public instance/API docs
• Status: Used in production. It has APIs and they work! Needs improvement on indexing; needs more indexes and some more APIs to the data exposed.

[!tip] See also: UFOs atproto explorer built on UFOs API. (source)

💫 Links

Rust library for parsing and extracting links (at-uris, DIDs, and URLs) from atproto records.

• Source: ./links/
• Status: not yet published to crates.io; needs some rework

🛩️ Jetstream

A low-overhead jetstream client with cursor handling and automatic reconnect.

• Source: ./links/
• Status: used in multiple apps in production, but not yet published to crates.io; some rework planned

[!tip] See also: Rocketman, another excellent rust jetstream client which shares some lineage and is published on crates.io.

🔭 Deprecated: Who am I

An identity bridge for microcosm demos, that kinda worked. Fixing its problems is about equivalent to reinventing a lot of OIDC, so it's being retired.

• Source: ./who-am-i/
• Status: ready for retirement.

[!warning] who-am-i is still in use for the Spacedust Notifications demo, but that will hopefully be migrated to use atproto oauth directly instead.