Introduction

The [[[!ActivityPub]]] API is a RESTful interface for social networking servers. It provides a readable interface for locally-hosted objects via HTTP GET to their id property URL, and for remotely-hosted objects via the proxyUrl endpoint. A writeable interface is provided with an HTTP POST to the user's outbox collection.

To get updated versions of an object or collection, the client application has to repeatedly fetch the object -- "polling" for updates at a given interval. This has three disadvantages:

If changes are made between polls, the representation in the client application is out of synch until the next poll.
If the object is unchanged between polling requests, resources on the client and server are wasted for no user benefit.
A client representation, like a mobile app screen or a Web page, may reference dozens or even hundreds of different objects, each of which needs to be polled separately.

One alternative to the polling model is server push. In this architecture, the client establishes a long-running connection to the server. The server then sends update notifications to the client, as close to the actual modification time as possible, so that the client can modify its local representation of the object.

Several server push technologies exist in the Web ecosystem. This document describes an application of [[[!eventsource]]] to the ActivityPub API. Server-Sent Events have the advantage of being well-supported in many browser environments, and easy to support in other contexts. Their downside, compared to some other technologies such as [[[websockets]]], is that they are one-way and read-only; the server can send updates to the client, but the client cannot use the same channel to send updates to the server. The POST interface through the user's outbox should suffice for most applications.

This specification uses a constrained subset of the [[[!activitystreams-vocabulary]]] to represent changes to ActivityPub objects. This has the advantage of not requiring a separate vocabulary or format for changes, which are already well represented in AS2. On the downside, it blurs the line between the data to be represented, and the changes to that data.

Events

Events from the server are in the form of [[[!activitystreams-core]]] Activity objects, in [[[!json-ld]]] format.

Activity objects MAY include an actor property, and MAY include an id property.

Add

An Add event is sent when a new item is added to a collection.

In this example, the client has requested an event stream for the inbox collection https://ideas.example/user/18/inbox. A new Like activity has been received from a remote server.

            data: {
            data:   "@context": "https://www.w3.org/ns/activitystreams",
            data:   "type": "Add",
            data:   "summary": "Igor's like activity was added to the inbox",
            data:   "object": {
            data:     "id": "https://social.example/like/11802",
            data:     "type": "Like",
            data:     "summary": "Igor liked a note",
            data:     "actor": {
            data:        "id": "https://social.example/user/27127",
            data:        "icon": {
            data:           "type": "Link",
            data:           "href": "https://files.social.example/335.jpg"
            data:        },
            data:        "name": "Igor Q. Actyr"
            data      }
            data:     "to": ["as:Public", "https://ideas.example/user/18"],
            data:     "object": "https://third.example/note/4881"
            data:   },
            data:   "target": "https://ideas.example/user/18/inbox"
            data: }

In this example, the client has requested an event stream for the object https://ideas.example/note/339. A new reply has been received by the server for this object; an Add event is generated for adding the reply to the replies collection.

            data: {
            data:   "@context": "https://www.w3.org/ns/activitystreams",
            data:   "type": "Add",
            data:   "summary": "A note was added to the replies",
            data:   "object": {
            data:     "id": "https://social.example/note/138",
            data:     "type": "Note",
            data:     "content": "I disagree!",
            data:     "to": ["as:Public", "https://ideas.example/user/18"],
            data:     "inReplyTo": "https://ideas.example/note/339"
            data:   },
            data:   "target": "https://ideas.example/note/339/replies"
            data: }

Remove

A Remove event is sent when an existing item is removed from a collection.

In this example, the client has requested an event stream for the collection https://photos.example/album/31939. The album's owner has removed a photo from the collection.

            data: {
            data:   "@context": "https://www.w3.org/ns/activitystreams",
            data:   "id": "https://photos.example/remove/2102",
            data:   "actor": "https://photos.example/user/25863",
            data:   "to": "https://photos.example/user/25863/followers",
            data:   "type": "Remove",
            data:   "object": "https://photos.example/photo/5821",
            data:   "target": "https://photos.example/album/31939",
            data:   "summary": "The owner removed this photo from the album"
            data: }

In this example, the client has requested an event stream for the collection https://other.example/user/20550/followers, the followers collection of an actor. One of the followers in the collection has unfollowed the main actor using an Undo activity. Note that the Undo activity is not directly represented in this event.

            data: {
            data:   "@context": "https://www.w3.org/ns/activitystreams",
            data:   "type": "Remove",
            data:   "summary": "A follower unfollowed the actor",
            data:   "object": "https://third.example/user/24176",
            data:   "target": "https://other.example/user/20550/followers"
            data: }

Update

An Update event is sent when an object has been changed. The object property of the event should contain a full representation of the changed object.

In this example, the client has requested an event stream for the Note object https://social.example/note/9891. The note's author has updated the content of the note.

            data: {
            data:   "@context": "https://www.w3.org/ns/activitystreams",
            data:   "id": "https://social.example/update/10224",
            data:   "type": "Update",
            data:   "actor": "https://social.example/person/4806",
            data:   "to": ["as:Public"],
            data:   "summary": "The author updated their note",
            data:   "object": {
            data:      "id": "https://social.example/note/9891",
            data:      "type": "Note",
            data:      "content": "Hello World, actually!",
            data:      "attributedTo": "https://social.example/person/4806",
            data:      "to": ["as:Public"]
            data:   }
            data: }

In this example, the client has requested an event stream for the Note object https://social.example/note/9891. One of the actors that has replied to the note has changed their avatar image.

            data: {
            data:   "@context": "https://www.w3.org/ns/activitystreams",
            data:   "id": "https://other.example/update/14092",
            data:   "type": "Update",
            data:   "actor": "https://other.example/person/4607",
            data:   "summary": "The actor updated their avatar",
            data:   "object": {
            data:      "id": "https://other.example/person/4607",
            data:      "type": "Person",
            data:      "summary": "An example person",
            data:      "icon": "https://other.example/files/4607-b.jpg"
            data:   }
            data: }

Delete

The Delete activity is sent when an object has been deleted.

In this example, the client has requested an event stream for the Note object https://social.example/note/4023. The note's author has deleted the note.

            data: {
            data:   "@context": "https://www.w3.org/ns/activitystreams",
            data:   "id": "https://social.example/delete/23978",
            data:   "type": "Delete",
            data:   "summary": "The note has been deleted",
            data:   "object": "https://social.example/note/4023"
            data: }

Proxy Event Stream

The client may want to be notified of changes to remote objects; that is, objects hosted on remote servers. Similar to the proxyUrl endpoint, a publisher can share a proxyEventStream property in the endpoints property of an actor to indicate a local proxy URL that can be used to be notified of events about remote objects.

In this example, an ActivityPub actor includes a proxyEventStream property.

{ "@context": [ "https://www.w3.org/ns/activitystreams", "https://purl.archive.org/socialweb/sse" ], "id": "https://social.example/person/29504", "name": "A. Person", "inbox": "https://social.example/person/29504/inbox", "outbox": "https://social.example/person/29504/outbox", "followers": "https://social.example/person/29504/followers", "following": "https://social.example/person/29504/following", "liked": "https://social.example/person/29504/liked", "endpoints": { "proxyUrl": "https://social.example/proxy", "proxyEventStream": "https://social.example/events" } }

The proxy event stream URL takes two arguments (in addition to any arguments defined in the URL):

id: The id of the object to get events for
access_token: An OAuth 2.0 access token for authentication

This example shows how to follow events for a remote object in a Web application.

          const myActorId = "https://social.example/person/32015"
          const remoteCollectionId = "https://other.example/person/734/outbox"
          const myAccessToken = "some_token_here"

          const res = await fetch(myActorId)
          const actor = await res.json()
          const proxyEventStream = new URL(actor.endpoints.proxyEventStream)
          proxyEventStream.searchParams.set('id', remoteCollectionId)
          proxyEventStream.searchParams.set('access_token', myAccessToken)
          const es = new EventSource(proxyEventStream)

Implementation Notes

Client

Real-time server updates are easier to process with a model-view-controller or similar architecture. The event handler, for server events, can look up models by id and call the appropriate methods to change the models and, consequently, change all the views that depend on that model.

In this (optimistic) example code, a web page maintains a map of models by id, and updates them based on the data in the events.


            const accessToken = "some_token_here"
            const id = "https://social.example/note/1"

            const models = new Map()

            const res = await fetch(id)
            const json = await res.json()

            const model = new Model(json)
            models.set(id, model)

            const eventStream = new URL(json.eventStream)
            eventStream.searchParams.set('access_token', accessToken)
            const source = new EventSource(eventStream)

            source.onmessage = (event) => {
              const activity = JSON.parse(event.data)
              switch (activity.type) {
                case "Add":
                  const id = toId(activity.target)
                  const collection = models.get(id)
                  const item = new Model(activity.object)
                  models.set(item.id, item)
                  // mutate model, possibly triggering view updates
                  collection.add(item)
                  break
                case "Remove":
                  const id = toId(activity.target)
                  const collection = models.get(id)
                  const item = new Model(activity.object)
                  // mutate model, possibly triggering view updates
                  collection.remove(item.id)
                  break
                case "Update":
                  const id = toId(activity.object)
                  const model = models.get(id)
                  // mutate model, possibly triggering view updates
                  model.update(activity.object)
                  break
                case "Delete":
                  const id = toId(activity.object)
                  const model = models.get(id)
                  // mutate model, possibly triggering view updates
                  model.destroy()
                  models.delete(id)
                  break
              }
            }

Server

This specification shifts complexity from the client to the server; responsibility for tracking which objects are related to which client is primarily on the side of the server.

One option for making this work is to keep a map of objects currently being observed with an event stream to the streams that are observing them. When a change is made to one of the objects, look up the relevant event streams, and send out an event on those streams. A reverse mapping (from streams to objects) can help with cleanup when the stream is torn down.

Server software that spans multiple processes will need to have a way to coordinate triggering event updates between processes. For example, if an activity is received from a remote server on a sharedInbox endpoint, the effects of that change should propagate to open connections, even if they're being handled by another process.

Server-Sent Events For the ActivityPub API

Introduction

User Stories

Discovery

Authentication