1
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:username@your.domain 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: â i@.lhr.life ââââââââââââââââââžââââââââââââââââââââââââââââââââââââââââââĪâ 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 ââ°âââââââââââââââââīââââââââââââââââââââââââââââââââââââââŊ
Iâm not sure about that. Sometimes itâs more about properly applying libraries. Thinking of database handling or cryptography
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.