activity/pub

pub

Implements both the SocialAPI and FederateAPI in the ActivityPub specification.

Disclaimer

This library is designed with flexibility in mind. The cost of doing so is that writing an ActivityPub application requires a lot of careful considerations that are not trivial. ActivityPub is an Application transport layer that is also tied to a specific data model, making retrofits nontrivial as well.

How To Use

There are two ActivityPub APIs: the SocialAPI between a user and your ActivityPub server, and the FederateAPI between your ActivityPub server and another server peer. This library lets you choose one or both.

Lightning intro to ActivityPub: ActivityPub uses ActivityStreams as data. This lives in go-fed/activity/vocab. ActivityPub has a concept of actors who can send, receive, and read their messages. When sending and receiving messages from a client (such as on their phone) to an ActivityPub server, it is via the SocialAPI. When it is between two ActivityPub servers, it is via the FederateAPI.

Next, there are two kinds of ActivityPub requests to handle:

1. Requests that GET or POST to stuff owned by an actor like their inbox or outbox.
2. Requests that GET ActivityStream objects hosted on your server.

The first is the most complex, and requires the creation of a Pubber. It is created depending on which APIs are to be supported:

// Only support SocialAPI
s := pub.NewSocialPubber(...)
// Only support FederateAPI
f := pub.NewFederatingPubber(...)
// Support both APIs
sf := pub.NewPubber(...)

Note that only the creation of the Pubber is affected by the decision of which API to support. Once created, the Pubber should be used in the same manner regardless of the API it is supporting. This allows your application to easily adopt one API first and migrate to both later by simply changing how the Pubber is created.

To use the Pubber, call its methods in the HTTP handlers responsible for an actor's inbox and outbox:

// Given:
//     var myPubber pub.Pubber
var outboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
  c := context.Background()
  // Populate c with application specific information
  if handled, err := myPubber.PostOutbox(c, w, r); err != nil {
    // Write to w
  } else if handled {
    return
  }
  if handled, err := myPubber.GetOutbox(c, w, r); err != nil {
    // Write to w
  } else if handled {
    return
  }
  // Handle non-ActivityPub request, such as responding with an HTML
  // representation with correct view permissions.
}
var inboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
  c := context.Background()
  // Populate c with application specific information
  if handled, err := myPubber.PostInbox(c, w, r); err != nil {
    // Write to w
  } else if handled {
    return
  }
  if handled, err := myPubber.GetInbox(c, w, r); err != nil {
    // Write to w
  } else if handled {
    return
  }
  // Handle non-ActivityPub request, such as responding with an HTML
  // representation with correct view permissions.
}

Finally, to handle the second kind of request, use the HandlerFunc within HTTP handler functions in a similar way. There are two ways to create HandlerFunc, which depend on decisions we will address later:

asHandler := pub.ServeActivityPubObject(...)
var activityStreamHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
  c := context.Background()
  // Populate c with application specific information
  if handled, err := asHandler(c, w, r); err != nil {
    // Write to w
  } else if handled {
    return
  }
  // Handle non-ActivityPub request, such as responding with an HTML
  // representation with correct view permissions.
}

That's all that's required to support ActivityPub.

How To Create

You may have noticed that using the library is deceptively straightforward. This is because creating the Pubber and HandlerFunc types is not trivial and requires forethought.

There are a lot of interfaces that must be satisfied in order to have a complete working ActivityPub server.

Note that context.Context is passed everywhere possible, to allow your implementation to keep a request-specific context throughout the lifecycle of an ActivityPub request.

Application Interface

Regardless of which of the SocialAPI and FederateAPI chosen, the Application interface contains the set of core methods fundamental to the functionality of this library. It contains a lot of the storage fetching and writing, all of which is keyed by *url.URL. To protect against race conditions, this library will inform whether it is fetching data to read-only or fetching for read-or- write.

Note that under some conditions, ActivityPub verifies the peer's request. It does so using HTTP Signatures. However, this requires knowing the other party's public key, and fetching this remotely is do-able. However, this library assumes this server already has it locally; at this time it is up to implementations to remotely fetch it if needed.

SocialAPI and FederateAPI Interfaces

These interfaces capture additional behaviors required by the SocialAPI and the FederateAPI.

The SocialAPI can additionally provide a mechanism for client authentication and authorization using frameworks like Oauth 2.0. Such frameworks are not natively supported in this library and must be supplied.

Callbacker Interface

One of these is needed per ActivityPub API supported. For example, if both the SocialAPI and FederateAPI are supported, then two of these are needed.

Upon receiving one of these activities from a POST to the inbox or outbox, the correct callbacker will be called to handle either a SocialAPI activity or a FederateAPI activity.

This is where the bulk of implementation-specific logic is expected to reside.

Do note that for some of these activities, default actions will already occur. For example, if receiving an Accept in response to a sent Follow, this library automatically handles adding the correct actor into the correct following collection. This means a lot of the social and federate functionality is provided out of the box.

Deliverer Interface

This is an optional interface. Since this library needs to send HTTP requests, it would be unwise for it to provide no way of allowing implementations to rate limit, persist across downtime, back off, etc. This interface is satisfied by the go-fed/activity/deliverer package which has an implementation that can remember to send requests across downtime.

If an implementation does not care to have this level of control, a synchronous implementation is very straightforward to make.

Other Interfaces

Other interfaces such as Typer and PubObject are meant to limit modification scope or require minimal ActivityStream compatibility to be used by this library. As long as the go-fed/activity/vocab or go-fed/activity/streams_old packages are being used, these interfaces will be natively supported.

Other Considerations

Please see the README for go-fed/activity for the status of the latest official implementation report.

The go-fed.org website has a tutorial and documentation for this library.