Skip to content

FEP-136c: Comment Tracking Services

Summary

A comment tracking service adds the capability to comment on a site via the Fediverse. The site here is possibly static and usually hosted seperately from the comment tracking service.

This FEP describes

  • the mechanisms for linking the site to the comment tracking system
  • what is a comment
  • mechanisms to identify that an actor belongs to a comment tracking system
  • expectations on how the comment tracking system decimates information

Architecture

Retrieving a page

The page on the site will contain the URL for the API call to the comments server to retrieve the comments.

sequenceDiagram
actor User

User ->> Site: GET /page
Note over User: Retrieve URL for comments
User ->> Comments-Server: GET /comments/{pageId}
Note over User: Render comments in page

This can be for example using JavaScript and a CORS request.

Commenting

When commenting the user will talk with comments server with their Fediverse home server as an intermediary.

sequenceDiagram
actor User

User ->> Site: GET /page
Note over User: Retrieve URL for ActivityPub
User ->> Fediverse Home: GET /query?uri={activity_pub_url}
Fediverse Home ->> Comments-Server: GET /{activity_pub_url}
User ->> Fediverse Home: Reply to retrieved object
Fediverse Home ->> Comments-Server: POST /inbox with reply

Here the ActivityPub URL is retrieved using one of the two mechanisms below.

Creating an initial page object

So far the comment tracking system hasn't talked to the site yet. This is only necessary if the comment tracking system doesn't know about a page on the site yet. Then it retrieves the page and creates an object.

sequenceDiagram

Fediverse Home ->> Comments-Server: GET /{activity_pub_url}
Note over Comments-Server: Not found in database
Comments-Server ->> Site: GET /page

This also motivates one of our design choices! The ActivitPub url will need to contain the location of the page.

Linking between Comment Tracking System and the Site

We expect the site to be a collection of HTML files and possibly other assets. We do not assume control on the underlying hosting provider.

A HTML page can include information on alternative formats via a link element with rel="alternate". We will use this in the form of

<link rel="alternate"
    type="application/activity+json"
    href="https://comments.example/path/to/activity/pub/representation">

This mechanism is useful for programmatic retrievable. So when a Fediverse application looks up an object and retrieves an answer with content type text/html, it should check for such a link element. If it is found, the Fediverse application should follow the link.

Direct URL

This is done by providing a link inside the page, that is user visible, where the user can copy the ActivityPub URL from. This URL can then be pasted into their Fediverse application.

The URL format for ActivityPub objects

Note

One might want to make different choices here. Unfortunately, that would lead to different comment tracking systems not being interoperable.

As mentioned above, we will need to recover the URL of the original page from the ActivityPub object id. To do so, we use the format:

https://comments.server.domain/some/path/{base64-encoded-page-url}

for the URL of ActivityPub object. Here bas64 encoded means url safe with padding.

APIS

The ActivityPub endpoint

The ActivityPub endpoint should obey the following OpenAPI. This is not strictly necessary, as ActivityPub is quite flexible. However, by obeying it one reduces future interoperability headaches.

The comments API

Should obey the following OpenAPI.

Actors on the Comment Tracking System

It is recommended to use a different actor for each site supported by the comment tracking system.

Properties of each actor

  • The actor should be of type Service
  • The html url of the actor should be the root of the corresponding site
  • The actor should have a name and summary
  • Proper property values should be used to indicate this is a comment tracking system
  • The actor should automatically accept followers

Processing activities

Activities should be processed and made available in the appropriate collections as described in ActivityPub endpoint. Activities should be announced to all followers via the FEP-1b12: Group federation mechanism.

Implementing

Implementations are split into two parts

  • The Comment Tracking System
  • The generator for the site

If interoperability works, one should be able to mix and match these.

Comment Tracking System

Static Site Generators

What needs to be implemented:

  • Add the links as described here
  • Display replies, i.e. fetch from comments api and render

Examples

References

  • Christine Lemmer-Webber, Jessica Tallon, Erin Shepherd, Amy Guy, Evan Prodromou, ActivityPub, 2018

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.

Replies