- cross-posted to:
- [email protected]
0
- cross-posted to:
- [email protected]
So, you're captivated by the fediverse—the decentralized social web powered by protocols like ActivityPub. Maybe you're dreaming of building the next great federated app, a unique space connected to Mastodon, Lemmy, Pixelfed, and more. The temptation to dive deep and implement ActivityPub yourself, from the ground up, is strong. Total control, right? Understanding every byte? Sounds cool!
But hold on a sec. Before you embark on that epic quest, let's talk reality. Implementing ActivityPub correctly isn't just one task; it's like juggling several complex standards while riding a unicycle… blindfolded. It’s hard.
That's where Fedify comes in. It's a TypeScript framework designed to handle the gnarliest parts of ActivityPub development, letting you focus on what makes your app special, not reinventing the federation wheel.
This post will break down the common headaches of DIY ActivityPub implementation and show how Fedify acts as the super-powered pain reliever, starting with the very foundation of how data is represented.Challenge #1: Data Modeling—Speaking ActivityStreams & JSON-LD Fluently
At its core, ActivityPub relies on the ActivityStreams 2.0 vocabulary to describe actions and objects, and it uses JSON-LD as the syntax to encode this vocabulary. While powerful, this combination introduces significant complexity right from the start.
First, understanding and correctly using the vast ActivityStreams vocabulary itself is a hurdle. You need to model everything—posts (Note, Article), profiles (Person, Organization), actions (Create, Follow, Like, Announce)—using the precise terms and properties defined in the specification. Manual JSON construction is tedious and prone to errors.
Second, JSON-LD, the encoding layer, has specific rules that make direct JSON manipulation surprisingly tricky:Missing vs. Empty Array: In JSON-LD, a property being absent is often semantically identical to it being present with an empty array. Your application logic needs to treat these cases equally when checking for values. For example, these two Note objects mean the same thing regarding the name property:// No name property{ "@context": "https://www.w3.org/ns/activitystreams", "type": "Note", "content": "…"}// Equivalent to:{ "@context": "https://www.w3.org/ns/activitystreams", "type": "Note", "name": [], "content": "…"}Single Value vs. Array: Similarly, a property holding a single value directly is often equivalent to it holding a single-element array containing that value. Your code must anticipate both representations for the same meaning, like for the content property here:// Single value{ "@context": "https://www.w3.org/ns/activitystreams", "type": "Note", "content": "Hello"}// Equivalent to:{ "@context": "https://www.w3.org/ns/activitystreams", "type": "Note", "content": ["Hello"]}Object Reference vs. Embedded Object: Properties can contain either the full JSON-LD object embedded directly or just a URI string referencing that object. Your application needs to be prepared to fetch the object's data if only a URI is given (a process called dereferencing). These two Announce activities are semantically equivalent (assuming the URIs resolve correctly):{ "@context": "https://www.w3.org/ns/activitystreams", "type": "Announce", // Embedded objects: "actor": { "type": "Person", "id": "http://sally.example.org/", "name": "Sally" }, "object": { "type": "Arrive", "id": "https://sally.example.com/arrive", /* ... */ }}// Equivalent to:{ "@context": "https://www.w3.org/ns/activitystreams", "type": "Announce", // URI references: "actor": "http://sally.example.org/", "object": "https://sally.example.com/arrive"} { /* ... */ });// Now GET /.well-known/webfinger?resource=acct:[email protected] just works! { /* Handle follow */ }) .on(Undo, async (ctx, undo) => { /* Handle undo */ });// Define followers collection logicfederation.setFollowersDispatcher( "/users/{handle}/followers", async (ctx, handle, cursor) => { /* ... */ });.lhr.life/✔ Sent follow request to @@activitypub.academy.╭───────────────┬─────────────────────────────────────────╮│ Actor handle: │ [email protected] │├───────────────┼─────────────────────────────────────────┤│ Actor URI: │ https://.lhr.life/i │├───────────────┼─────────────────────────────────────────┤│ Actor inbox: │ https://.lhr.life/i/inbox │├───────────────┼─────────────────────────────────────────┤│ Shared inbox: │ https://.lhr.life/inbox │╰───────────────┴─────────────────────────────────────────╯Web interface available at: http://localhost:8000/.lhr.life/r/2 │╰────────────────┴─────────────────────────────────────╯
Imagine you want to write a competitor to PostgreSQL and you start out by importing SQLite into your project and building on top of that. To you it seems like a good idea because you’ve never written a DB app before and the only DB you’ve ever seen before is SQLite. You’ll get a prototype real fast but you’ll never build a PostgreSQL equivalent because you never learned the foundational knowledge of how a DB works and because SQLite forecloses all the pathways you need to get there.
Same thing.
Of course you wouldn’t use an existing database engine as the foundation of a new database engine. But you would use an existing database engine as the foundation of an ERP software, which is a vastly different use case even if the software does spend a lot of time dealing with data.
If I want to build an application I don’t want to reimplement everything. That’s what middleware is for. The use case of my application is most likely not to speak a certain protocol; the protocol is just the means to what I actually want to do. There’s no reason for me to roll my own implementation from scratch and keep up with current developments except if I’m unhappy with all current implementations of that protocol.
Of course one can overdo it with middleware (the JS world is rife with this) but implementing a communication protocol is one of the classic cases where it makes sense.