ForgeFed

ForgeFed Behavior - draft - 2020-02-10 master 7f8f3b6

1 Abstract

This document provides instructions for using ActivityPub activities and properties to represent forge events, and describes the side-effects these activities should have.

2 Introduction

The ForgeFed behavior specification is a set of instructions for representing version control system and project management related transactions using ActivityPub activity objects, and it describes the side effects and expected results of sending and receiving these activities. The vocabulary for these activities includes standard ActivityPub terms, new terms defined by ForgeFed, and terms borrowed from other external vocabularies.

The ForgeFed vocabulary specification defines a dedicated vocabulary of forge-related terms, and the behavior specification uses these terms, along with terms that already exist in ActivityPub or elsewhere and can be reused for forge federation.

The ForgeFed modeling specification defines rules for representing forge related objects as ActivityPub JSON-LD objects, and these objects are used in the behavior specification, included in activities or mentioned in activities or modified due to activity side-effects.

3 Conformance

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted as described in RFC2119.

4 Objects

Objects are the core concept around which both ActivityPub and ForgeFed are built. Examples of Objects are Note, Ticket, Image, Create, Push. Some objects are resources, which are objects that contain or represent information and user made or program made content, and some objects are helpers that exist as implementation detail aren’t necessarily exposed to humans or are useful to humans. But everything is an Object, represented as compacted JSON-LD.

ForgeFed is an ActivityPub extension, and communication between ForgeFed implementations occurs using activity objects sent to actor inboxes and outboxes.

There are 4 kinds of objects in ForgeFed:

  1. Activities: These are objects that describe actions (actions that happened, or actions that are happening, or a request to perform an action), and their primary use is for S2S interaction between actors, by being sent to an actor’s inbox, and C2S interaction between a person or a program and actor they control, by being sent to the actor’s outbox. Activities can also appear or be linked inside other objects and activities and be listed in Collections.
  2. Actors: These are static persistent objects that have an [inbox] and can be directly interacted with by POSTing activities to it. Their primary use is to contain or represent information and output of user actions or program actions, and to manage access this information and to modification of it.
  3. Child objects: These are persistent objects which, like actors, contain or represent information and output of user actions or program actions, but they don’t have their own [inbox] and aren’t directly interacted with. A managed static object always has a parent object, which is an actor, and that actor’s inbox is the way to interact with the child object. The parent actor manages access and modification of the child object.
  4. Global helper objects: These are objects that don’t belong to any actor and don’t need any interaction through activities. As such, they don’t exactly fit into the actor model, but may be involved in implementation details and practical considerations.

Actors, children and globals are referred in ForgeFed as the static objects, while activities are the dynamic objects (the terms constant and variable are used for stating whether an object changes during its lifetime or not).

Static objects, in addition to being an actor or child or global, also have a resource/helper distinction:

This specification doesn’t mandate which types and objects should be actors, but it does provide guidelines that implementations SHOULD follow:

Here are some examples and their rationale:

The proposal here is that the following types typically be actors:

And other types such as these typically not be actors:

5 Actors

A ForgeFed implementation MUST provide an Actor of type Repository for every repository that should support federation.

A ForgeFed implementation SHOULD provide an Actor of type Person for every user of the platform.

6 Client to Server Interactions

ForgeFed uses Activities for client to server interactions, as described by ActivityPub. A client will send objects (eg. a Ticket) wrapped in a Activity (eg. Create) to an actor’s outbox, and in turn the server will take care of delivery.

6.1 Follow Activity

The Follow activity is used to subscribe to the activities of a Repository. The client MUST send a Follow activity to the Person’s outbox. The server in turn delivers the message to the destination inbox.

6.2 Push Activity

The Push activity is used to notify followers when somebody has pushed changes to a Repository. The client MUST send a Push activity to the Repository’s outbox. The server in turn delivers the message to the Repository followers.

7 Server to Server Interactions

7.1 Reporting Pushed Commits

The ForgeFed Push activity can be used for representing an action of pushing commits into a Repository. Two actors are involved in the process, the pusher (usually a person) and the repository, and they may be hosted on different instances. We therefore refer to 2 kinds of pushes:

  1. Local Push: The pusher and the repository are hosted on the same instance (that’s the only case in centralized non-federated forges)
  2. Federated Push: The pusher and the repository are hosted on different instances (that’s unique to federated forges)

At this time, the representation of Federated Push isn’t provided yet. Below we discuss Local Push.

Upon a successful push, a ForgeFed implementation that publishes a Push activity MUST provide the type, actor, context and target properties as described in the modeling specification. If the Push activity’s recipient fields list collections that belong to the repository, such as its followers and team, the repository MUST verify the authenticity and correctness of the Push activity’s fields before it performs inbox forwarding (i.e. delivery to the members of those collections), and MUST NOT perform inbox delivery if the correctness check doesn’t pass.

In a Local Push, if the Push activity is generated on the server, that obviates the need to perform correctness checking. Implementations MAY forbid clients from publishing Push activities (via the ActivityPub C2S API or any other mechanism), in order to guarantee the authenticity of Push activities.

See example in the modeling specification.

7.2 Opening a Ticket

The first step for opening a ticket is to determine to which actor to send the ticket. We’ll refer to this actor as the ticket tracker. Given an object obj against which you’d like to open a ticket (e.g. some application’s source code repository), look at the ticketsTrackedBy property of obj.

Now that we’ve determined the ticket tracker, i.e. the actor to whom we’ll send the Ticket, there are two mechanisms for opening a new Ticket under the ticket tracker:

  1. The creation flow: The ticket author will be hosting the ticket. They provide the ticket tracker with the ticket’s id URI, and the ticket tracker lists that URI under its list of tickets.
  2. The offer flow: The ticket tracker will be hosting the ticket. The author sends the tracker a ticket object, and the tracker assigns it an id URI and manages the object from now on.

It is recommended to use the creation flow as a default, and resort to the offer flow only when really necessary (if you’re unsure, it’s not necessary).

The creation flow begins with the ticket being published using a Create activity, in which object is a Ticket with fields as described in the modeling specification. The ticket MUST specify at least id, attributedTo, [summary][], content and context. The context property specifies the ticket tracker to which the actor is reporting the Ticket (e.g. a repository or project etc. under which the ticket will be listed if accepted). context MUST be either an actor or a child object. If it’s a child object, the actor to whom the child object belongs MUST be listed as a recipient in the Create’s to field. If it’s an actor, then that actor MUST be listed in the to field.

Among the recipients listed in the Create’s recipient fields, exactly one recipient is the actor who’s responsible for processing the ticket and possibly sending back an Accept or a Reject. We’ll refer to this actor as the target actor.

When an actor A receives the Create activity, they can determine whether they’re the target actor as follows: If the object ticket’s context is A or a child object of A, then A is the target actor. Otherwise, A isn’t the target actor.

In the following example, Luke wants to open a ticket under Aviva’s Game Of Life simulation app:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://forge.example/luke/outbox/02Ljp",
          "type": "Create",
          "actor": "https://forge.example/luke",
          "to": [
              "https://forge.example/luke/followers",
              "https://dev.example/aviva/game-of-life",
              "https://dev.example/aviva/game-of-life/team",
              "https://dev.example/aviva/game-of-life/followers"
          ],
          "object": {
              "id": "https://forge.example/luke/issues/k49fn",
              "type": "Ticket",
              "attributedTo": "https://forge.example/luke",
              "summary": "Test test test",
              "content": "<p>Just testing</p>",
              "mediaType": "text/html",
              "source": {
                  "mediaType": "text/markdown; variant=Commonmark",
                  "content": "Just testing"
              },
              "context": "https://dev.example/aviva/game-of-life"
          }
      }

The target actor SHOULD send an Accept or a Reject activity to the Create’s author in response. In the creation flow, to accept means to list the ticket’s id URI under the ticket tracker’s list of open tickets. If the target actor sends an Accept, it MUST either add the ticket’s id to its list, or host its own copy as in the offer flow described below. It SHOULD just list the ticket id, and that is the recommended behavior.

If the target actor sends a Reject, it MUST NOT list the ticket and MUST NOT host a copy. However if the target actor doesn’t make any use of the ticket, it MAY choose not to send a Reject, e.g. to protect user privacy. The Accept or Reject may also be delayed, e.g. until review by a human user; that is implementation dependent, and implementations should not rely on a response being sent instantly.

In the Accept activity:

In the following example, Luke’s ticket is listed automatically and Aviva’s Game Of Life repository, which is an actor, automatically sends Luke an Accept activity:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://dev.example/aviva/game-of-life/outbox/096al",
          "type": "Accept",
          "actor": "https://dev.example/aviva/game-of-life",
          "to": [
              "https://forge.example/luke",
              "https://dev.example/aviva/game-of-life/team",
              "https://dev.example/aviva/game-of-life/followers"
          ],
          "object": "https://forge.example/luke/outbox/02Ljp"
      }

The offer flow begins with the ticket being sent to the ticket tracker using an Offer activity, in which:

Among the recipients listed in the Offer’s recipient fields, exactly one recipient is the actor who’s responsible for processing the offer and possibly sending back an Accept or a Reject. We’ll refer to this actor as the target actor.

When an actor A receives the Offer activity, they can determine whether they’re the target actor as follows: If the Offer’s target is A or a child object of A, then A is the target actor. Otherwise, A isn’t the target actor.

In the following example, Luke wants to open a ticket under Aviva’s Game Of Life simulation app:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://forge.example/luke/outbox/02Ljp",
          "type": "Offer",
          "actor": "https://forge.example/luke",
          "to": [
              "https://dev.example/aviva/game-of-life",
              "https://dev.example/aviva/game-of-life/team",
              "https://dev.example/aviva/game-of-life/followers"
          ],
          "object": {
              "type": "Ticket",
              "attributedTo": "https://forge.example/luke",
              "summary": "Test test test",
              "content": "<p>Just testing</p>",
              "mediaType": "text/html",
              "source": {
                  "mediaType": "text/markdown; variant=Commonmark",
                  "content": "Just testing"
              }
          },
          "target": "https://dev.example/aviva/game-of-life"
      }

The target actor SHOULD send an Accept or a Reject activity to the Offer’s author in response. In the offer flow, to accept means to create and host a copy of the ticket on the target’s side, and to list the id of this newly published copy under the ticket tracker’s list of open tickets. If the target actor sends an Accept, it MUST host a copy and add its id to the list of open tickets.

If the target actor sends a Reject, it MUST NOT list the ticket and MUST NOT host a copy. However if the target actor doesn’t make any use of the ticket, it MAY choose not to send a Reject, e.g. to protect user privacy. The Accept or Reject may also be delayed, e.g. until review by a human user; that is implementation dependent, and implementations should not rely on a response being sent instantly.

In the Accept activity:

In the following example, Luke’s ticket is opened automatically and Aviva’s Game Of Life repository, which is an actor, automatically sends Luke an Accept activity:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://dev.example/aviva/game-of-life/outbox/096al",
          "type": "Accept",
          "actor": "https://dev.example/aviva/game-of-life",
          "to": [
              "https://forge.example/luke",
              "https://dev.example/aviva/game-of-life/team",
              "https://dev.example/aviva/game-of-life/followers"
          ],
          "object": "https://forge.example/luke/outbox/02Ljp",
          "result": "https://dev.example/aviva/game-of-life/issues/113"
      }

The action that has been taken by the target actor is indicated to the ticket author as follows:

7.3 Commenting

A comment on a ForgeFed resource object (such as tickets, merge requests) MUST be published as a Create activity, in which object is a Note with fields as described in the modeling specification.

In the following example, Luke replies to Aviva’s comment under a merge request he submitted earlier against her Game Of Life simulation app repository:

{
          "@context": "https://www.w3.org/ns/activitystreams",
          "id": "https://forge.example/luke/outbox/rLaYo",
          "type": "Create",
          "actor": "https://forge.example/luke",
          "to": [
              "https://forge.example/luke/followers",
              "https://dev.example/aviva/game-of-life",
              "https://dev.example/aviva/game-of-life/followers",
              "https://dev.example/aviva/game-of-life/team",
              "https://dev.example/aviva/game-of-life/merge-requests/19/followers",
              "https://dev.example/aviva/game-of-life/merge-requests/19/team"
          ],
          "object": {
              "id": "https://forge.example/luke/comments/rD05r",
              "type": "Note",
              "attributedTo": "https://forge.example/luke",
              "to": [
                  "https://forge.example/luke/followers",
                  "https://dev.example/aviva/game-of-life",
                  "https://dev.example/aviva/game-of-life/followers",
                  "https://dev.example/aviva/game-of-life/team",
                  "https://dev.example/aviva/game-of-life/merge-requests/19/followers",
                  "https://dev.example/aviva/game-of-life/merge-requests/19/team"
              ],
              "context": "https://dev.example/aviva/game-of-life/merge-requests/19",
              "inReplyTo": "https://dev.example/aviva/comments/E9AGE",
              "mediaType": "text/html",
              "content": "<p>Thank you for the review! I'll submit a correction ASAP</p>",
              "source": {
                  "mediaType": "text/markdown; variant=Commonmark",
                  "content": "Thank you for the review! I'll submit a correction ASAP"
              },
              "published": "2019-11-06T20:49:05.604488Z"
          }
      }

8 Acknowledgements