Documenting federation behavior in a semi-standard way?

TL;DR, please check out FEDERATION.md and tell me what you think about it.

Context: I am in the process of federating an existing service for organizing events and meetups called gath.io. The federated currently version lives at events.tinysubversions.com, and the source code for my branch is available here.

Because I’m building a federated service, I felt like I should add the documentation that I wish other federated services had: namely, something that describes how the server responds to and generates ActivityPub activities!

As a first pass, I have created a FEDERATION.md file that lives in the root of the repo. It is divided into three main sections:

  • Federation philosophy
  • Inbox behavior
  • Activities triggered from the web application

You can read the full thing here.

I would like to see other implementations write up something similar to this. Maybe putting it in a FEDERATION.md file in the root could be a de facto standard.

Any thoughts on this? What’s missing that other ActivityPub implementors would like to know about the server? (I’m sure plenty is missing, as I just wrote this up in an hour.)

9 Likes

I very much agree that we need a solid place where we discuss the Codes and Codices of Interoperability.

For me this is the goal of the ActivityPub Events series itself.
If you read my 36c3 reflection there are some hints.
My personal opinion is to have it face to face or at least voice to voice.

My fear is about the balance of power :
History proved that when big players step in they try to set the Codices.

/me still suffering from a virus after a hackerconf but for sure I will write the same for
redaktor – thank You.

2 Likes

This looks really cool! One high-level thing I noticed is that it might make more sense to start with the activities triggered by the web application (after the short federation philosophy/intro section), and then move into Inbox behavior. This makes the document flow better from a user-centric perspective, I think, which has two main benefits: 1) gath.io implementors reading it who may not be entirely familiar with federation have concrete user actions to ground them, and 2) activitypub implementors who may not be familar with gath.io have a clearer idea of the scope/scale of expected user behaviors.

The second thing that strikes me about gath’s federation (and this may be in complete contradiction to my first paragraph) is that it’s almost a “server-to-client” model—that is, you’re using the limited vocabulary of some existing federated clientservers to take tangible actions as a user on another application. That is, you’re almost using federation as a pure “front end” for gathio. This is interesting, and it’s something I’ve thought about doing before, but it’s definitely something not considered by any of the specs we have and even kind of flies in contradiction to the idealized activitypub “specialized clients, generic servers” model. I don’t think this is a bad decision! it seems like a logical but awkward conclusion to the world of specialized servers we’ve found ourselves in, and it definitely has value in the world today. I just wanted to note it as a point of general discussion.

(this is in contradiction to what I said above because if activitypub is a “front end” client for the imagined gath user, then incoming and outgoing actions are both user behaviors, so it doesn’t make as much difference which one comes first)

On specifics, the only thing I noticed that seemed kind of weird is the usage of Create/Note to denote replies to the event—most people have been using an Announce activity to handle “posting to a group” or similar events. What are your thoughts there? Why not just boost the original reply instead of duplicating it?

1 Like

This is great and I think every federated service needs to do this. I will do this too. I have some questions however.

Is Event an actor after all? I’ve only ever seen it in the wild in Friendica, and there it’s used as an attachment to a post. I was going to have events myself so representing them in ActivityPub is still an open question. I personally was thinking about a Group with an Event in its attachments. Event isn’t an actor as per the spec, it’s an “object”.

How is this going to work with implementations that deliberately don’t support direct messages, like mine? As of yesterday’s update, I return 400 Bad Request to any Create{Note} that doesn’t contain as:Public in either to or cc.

Also since I was going to have events and the spec specifies the proper way of RSVPing to events (Invite{Event} and then Accept/Reject/TentativeAccept{Invite}), are there any plans to support that?

1 Like

You’re absolutely right, I should just be boost/Announce-ing those posts!! I just hadn’t thought of it.

2 Likes

An Event is not an actor in my implementation. I try to be careful in the document about capital-E Event per the spec, versus an “event”, which is the thing that gathio describes. So:

  • an Event is an Object that is attached to an Activity and conforms to the AP spec
  • an event-the-thing-that-people-attend is an Actor; in this case I am representing it the actor as a Person because I don’t see a better choice (though maybe Service? I’m not sure that most implementations know how to represent that right now)
    • at this juncture I choose to interpret Person as an individual agent, rather than as an “individual person” per the AS Vocab spec

Great question. I’ll have to think about that. Right now your actors could still follow my actor and get normal public updates. But some correspondence between the human-actor and the event-actor should be private. I think they would simply have to go to the page and manually RSVP rather than doing it via federation.

Yes, definitely.

I will add the Accept/Reject/TentativeAccept Invite as a TODO to my list, along with the boosting that nightpool mentioned above.

2 Likes

Btw, the above todo items are done, and have been documented in FEDERATION.md :slight_smile:

1 Like

WriteFreely just added federation.md to their repo after I started a question about the behavior of what happens when one changes ones username.

1 Like

just updating this thread because I came across Zot’s new FEDERATION.md they just added and thought this would be a good place to post it…

1 Like

I added one to tavern and plan on keeping it updated: FEDERATION.md

1 Like