Groups Extension

Groups are a way to organize users and notes into communities, for any purpose, such as forums, blogs or messaging.

This extension requires pub.versia:social@1, which defines Notes.

Definition

Group

Only the instance hosting a group may send or serve that Group.

{
    "type": "pub.versia:groups/Group",
    "id": "033j6qrwzt002",
    "created_at": "2021-01-01T00:00:00Z",
    "name": "The Woozy fan club",
    "description": "<p>A group for fans of the <strong>Woozy</strong> emoji.</p>",
    "open": false,
    "url": "https://example.com/groups/woozy"
}

Notes in a Group

A Note is posted to a group through the pub.versia:groups key of its extensions field.

Members of the group can see the Note, on top of the audience its visibility gives it, and their instances may fetch it. A Note with a visibility of mentions can be seen only by members and the rest of its mentions audience. An instance that does not support this extension shows it only to the mentioned users.

{
    "type": "pub.versia:social/Note",
    "visibility": "mentions",
    // ...
    "extensions": {
        "pub.versia:groups": {
            "group": "example.com:033j6qrwzt002"
        }
    }
}

GroupFederate

The GroupFederate entity tells an instance to fetch a Note posted to a group. MUST be sent by the instance hosting the group.

A receiver MUST ignore a GroupFederate that does not come from the instance hosting group, or whose fetched Note does not name that group in its pub.versia:groups extension.

{
    "type": "pub.versia:groups/Federate",
    "target": "versia.example:034e17jw54002",
    "group": "example.com:033j6qrwzt002",
    "created_at": "2021-01-01T00:00:00Z"
}

Behavior

Subscribing to Groups

Groups accept subscriptions. A User joins a group by sending a Subscribe whose target_type is pub.versia:groups/Group, and leaves it with an Unsubscribe. The group’s instance answers as for any subscription, including when the group is open, and a SubscribeReject also removes a member.

A Group’s subscribers are its members, listed in its members collection. They receive the Notes posted to it, as described under Federation.

Federation

The instance hosting a group cannot send the Notes posted to it, as an entity’s author must belong to the instance that signs it. A Note therefore reaches the group’s members in three steps:

1. The instance of the Note’s author MUST send the Note to the inbox of the group’s instance, on top of its usual delivery. It MUST do the same with any change to the Note, and with a Delete for it.
2. The group’s instance decides which Notes to federate. A Note it refuses is dropped silently. For the others, it MUST send a GroupFederate to every instance hosting a member of the group.
3. Each of those instances fetches the Note from the instance of its author.

The instance of the author MUST allow that fetch if the requesting instance hosts a user in the group’s members collection, unless it refuses to federate with that instance. It MAY cache that collection, and SHOULD fetch it again before refusing an instance it does not find there.

When a Note posted to a group changes or is deleted, the group’s instance MUST send a GroupFederate for it again, and receivers fetch it again. The instance of the author answers a request for the deleted Note as Delete describes. After a 404 Not Found, members keep their copy.

Delivery and Access

Any instance may fetch a Group and its members and moderators collections.

Versia Links

The Groups extension adds the following Versia Link action:

• groups/{instance}/{id}: Open a group.