The Allure of the Fediverse and the Challenges of ActivityPub Implementation

The fediverse—a decentralized social web powered by protocols like ActivityPub—is an exciting space to explore. If you’re considering building the next great federated app, connected to platforms like Mastodon, Lemmy, Pixelfed, and more, you might be tempted to implement ActivityPub from scratch. While this approach offers total control, it’s a daunting task due to the complexity of the standards involved.

The Challenge: Data Modeling with ActivityStreams & JSON-LD

At its core, ActivityPub relies on ActivityStreams 2.0 vocabulary and JSON-LD syntax. This combination introduces significant complexity:

1. Understanding ActivityStreams Vocabulary:
   You need to model actions and objects (e.g., posts as Note or Article, profiles as Person or Organization, and actions like Create, Follow, Like, Announce) using the precise terms defined in the specification.

2. JSON-LD Specifics:
   JSON-LD has unique rules that complicate direct JSON manipulation:

   • Missing vs. Empty Arrays: A property being absent is often semantically identical to it being present with an empty array.

     // 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: A property can hold a single value or an array.

     // 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 References vs. Embedded Objects: Properties can contain either embedded objects or URI references.

     // Embedded object
     {
       "@context": "https://www.w3.org/ns/activitystreams",
       "type": "Announce",
       "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",
       "actor": "http://sally.example.org/",
       "object": "https://sally.example.com/arrive"
     }
     

---

Fedify: Simplifying ActivityPub Development

Fedify, a TypeScript framework, abstracts the complexity of ActivityPub development. It handles the heavy lifting, allowing you to focus on what makes your app unique.

Example Code with Fedify

Fedify simplifies federation logic:

// Handle follow
federation.on(Follow, async (ctx, follow) => {
  // Implement follow logic
});

// Handle post activity
federation.on(Create, async (ctx, activity) => {
  // Implement post activity logic
});

Web Interface and Logs

When running your app:

Web interface available at: http://localhost:8000/

Logs example:

.lhr.life/r/2 | ╰─────────────────┴───────────────────────────────────────╯

---

Conclusion

Building a federated app with ActivityPub is challenging, but tools like Fedify make the process manageable. By abstracting away the complexity of JSON-LD and ActivityStreams, Fedify allows developers to focus on creating innovative applications for the fediverse.

---