Discussing onboarding for developers

ActivityPub
1

Many have been overwhelmed by the amount of information in the spec, to the point some have written guides on how to read it that begin with stating what you can safely ignore. That is only the tip of the iceberg, as the whole introduction to ActivityPub could be potentially rethought - this forum being a prime improvement at organizing the information.

I suggest splitting the discussion in work packages centered around the learning steps involved:

  • understanding what problems ActivityPub solves/doesn’t solve
  • understanding what technologies ActivityPub uses
  • understanding the untold:
    • what is generally not implemented and why
    • what are the common deviations to the spec (a.k.a. dialects) and how to be compatible with them
    • what other technologies play a major role in most implementations (Webfinger, Signatures, etc.)
  • implementing:
    • what is a minimal implementation for each functional block of the spec
    • what are the tools that could help in that development, if any
    • libraries? good examples in major projects?
  • having feedback:
    • where to ask questions
    • where to check for compatibility (reports? test suite? forum?)
  • giving feedback:
    • where to declare deviations to the spec and explain how to be compatible with them

This is a rough list. Maybe we want to put our focus on some key points, but we should also pay extra care on how we cary the developer along that process, beginning with where that information is first given: probably http://activitypub.rocks/. What part of the explaining/dispatching belongs to the landing page, and what belongs to the forum is up for debate.

2 Likes
2

[2019-09-22 18:27:40+0000] Rigel Kent:

Many have been overwhelmed by the amount of information in the spec, to the point some have written guides on how to read it that begin with stating what you can safely ignore. That is only the tip of the iceberg, as the whole introduction to ActivityPub could be potentially rethought - this forum being a prime improvement at organizing the information.

I suggest splitting the discussion in work packages centered around the learning steps involved:

  • understanding what problems ActivityPub solves/doesn’t solve
  • understanding what technologies ActivityPub uses
  • understanding the untold:

Going to just give it a try on answering some of your list points as I’ve been for 2+ years in AP development, pretty much all my questions have been answered or become moot.

It was suggested at ApConf that maybe implementations of the fediverse should have some form of a wiki to describe this.

But quite quickly, here is for Pleroma:

  • Doesn’t use JSON-LD as there is/was no library in Elxir for it, but we are still compatible with it
  • No support for all the activities in the spec but rather the ones we find in the wild and then sanitize to a unified format in our database
  • Probably the only widely deployed implementation of AP which has support for the Client-to-Server API
  • Stuff we also have outside of pure ActivityPub:
  • implementing:
    • what is a minimal implementation for each functional block of the spec

I’m not exactly sure on this one as there could be extra ones but basically with pleroma an activity MUST have:

  • a type (Note, Create, …)
  • an id which is a proper IRI (for now only http(s)://)
  • an actor/attributedTo field which is on the same host as the activity (so alice.social can’t federate as:Delete of posts from bob.social)
  • what are the tools that could help in that development, if any

Basic web development tools like curl, being able to dump full HTTP requests while debugging can be quite useful.

  • libraries? good examples in major projects?
  • having feedback:
    • where to ask questions

I think pleroma is pretty good on this one as we use IRC channels which are also reachable via Matrix, but yeah for now it’s going implementation per implementation.

  • where to check for compatibility (reports? test suite? forum?)

There is http://activitypub.rocks/implementation-report/ which I think can be used as a base, I think it should have the posibility of having extra fields for the non-strictly ActivityPub stuff. (Note: it’s slightly outdated for pleroma)

  • giving feedback:
    • where to declare deviations to the spec and explain how to be compatible with them

I think this is where nodeinfo could help for federation, for example the required headers to be signed via HTTP Signatures and accepted Activities.

3 Likes
3

Thanks for your feedback. I’ll take on your examples for my own feedback.

Note that the report itself cannot be updated anymore, since https://test.activitypub.rocks is down (and has been for almost a year). It cannot be used for checking compatibility automatically anymore - one has to resort to manual checking against the grid of requirements. Putting it back online would be a good improvement.

Then there is https://git.feneas.org/feneas/federation/testsuite - it’s far from testing the spec, but it lays down the basis for compatibility testing.

I like your idea of adding fields to pubstrate (the soft behind https://test.activitypub.rocks) - now if there was a formal way of specifying the added fields to the protocol, that would be nice to generate the code required to check it. Maybe something like https://github.com/gobengo/activitystreams2-spec-scraped?

Agreed. Simple tools, but we should showcase some examples.

I concur with that. Your quick description of the minimal implementation, with the list of supported types and required HTTP signatures should already give a good idea to developers of what to do to achieve minimum compatibility (which is what I meant by “functional block”: “I want to have my Note object visible from Pleroma” -> here is the least/ideal to todo so).

I guess that’s where the dedicated section of the forum is going to be useful.

@lanodan Could you expand on that with an example? Is there an issue on the NodeInfo tracker with that suggestion?

4

[2019-09-22 20:08:40+0000] Rigel Kent:

Note that the report itself cannot be updated anymore, since https://test.activitypub.rocks is down (and has been for almost a year). It cannot be used for checking compatibility automatically anymore - one has to resort to manual checking against the grid of requirements. Putting it back online would be a good improvement.

It needs to be submitted via GitHub anyway. https://github.com/w3c/activitypub/issues/307 Not really sure where it goes though.

Then there is https://git.feneas.org/feneas/federation/testsuite - it’s far from testing the spec, but it lays down the basis for compatibility testing.

I like your idea of adding fields to pubstrate (the soft behind https://test.activitypub.rocks) - now if there was a formal way of specifying the added fields to the protocol, that would be nice to generate the code required to check it. Maybe something like https://github.com/gobengo/activitystreams2-spec-scraped?

No idea on this one, specially as I haven’t used either of the software that you mentionned.

Agreed. Simple tools, but we should showcase some examples.

I guess this could call for a (joined?) blog post or something to be put into a wiki.

@lanodan Could you expand on that with an example? Is there an issue on the NodeInfo tracker with that suggestion?

As far as I know, there is not ticket to add that in nodeinfo.

For example right now the nodeinfo of my own instance (with metadata collapsed because it’s implementation-defined and useless here) looks like this:

{
  "metadata": {…},
  "openRegistrations": false,
  "protocols": [
    "activitypub",
    "ostatus"
  ],
  "services": {
    "inbound": [],
    "outbound": []
  },
  "software": {
    "name": "pleroma",
    "repository": "https://hacktivis.me/git/pleroma",
    "version": "1.0.0-5137-g1cdf3cee-dev-lanodan2"
  },
  "usage": {
    "localPosts": 36190,
    "users": {
      "total": 20
    }
  },
  "version": "2.1"
}

So basically we know that the instance federates via ActivityPub and OStatus(which can be forgotten as a piece of the past) and there is some information about where to find the repository (here, my own as I have modifications).

What I think can be added could be something like this to be added into the root and so with a metadata field for the extra stuff, or directly into the root’s "metadata" field but it would mean loosely parseable, why not either way.

{
  "activitypub": {
    "activity": ["Accept", "Announce", "Block", "Create", "Delete", "Flag", …], // https://www.w3.org/TR/activitystreams-vocabulary/#activity-types
    "actor": ["Person", "Application", "Service"], // https://www.w3.org/TR/activitystreams-vocabulary/#actor-types
    "object": ["Note", "Document", "Video", "Image", "Page", "Article", …], // https://www.w3.org/TR/activitystreams-vocabulary/#object-types
    "metadata": {
      // Here goes non-standard ActivityPub
      "http-signature-required-headers": ["date", …],
      "webfinger": "optionnal"
    }
  }
}
1 Like
5

On the topic of using NodeInfo for capability discovery, I’m actually not in favor of it.

I think it makes more sense to have a special /.well-known URL that describes the server capabilities itself. Most likely this URL could also double for the instance actor itself.

In the JSON generated there, we could describe the vocabulary accepted by the instance.

6

/.well-known/activitypub ?

1 Like
7

I would suggest something like

/.well-known/activitypub/role/instance

but this is mostly because Pleroma has different actors with different security contexts: fetch and relay so far.

8

However you maintain the /.well-known/activitypub namespace it must be registered with IANA at some point. From RFC8615:

3.1. Registering Well-Known URIs

The “Well-Known URIs” registry is located at https://www.iana.org/assignments/well-known-uris/.
Registration requests can be made by following the instructions located there or by sending an email to the wellknown-uri-review@ietf.org mailing list.

Registration requests consist of at least the following information:

  • URI suffix: The name requested for the well-known URI, relative to “/.well-known/”; e.g., “example”.
  • Change controller: For Standards Track RFCs, state “IETF”. For others, give the name of the responsible party. Other details (e.g., email address, home page URI) may also be included.
  • Specification document(s): Reference to the document that specifies the field, preferably including a URI that can be used to retrieve a copy of the document. An indication of the relevant sections may also be included, but is not required.
  • Status: One of “permanent” or “provisional”. See guidance below.
  • Related information: Optionally, citations to additional documents containing further relevant information.

General requirements for registered values are described in Section 3.

For ActivityPub that would look like:

@kaniini do you have work in progress on an RFC, or would like to specify one?

9

I can do the standards work to get that registered at IETF if wanted. I am doing other standards work at IETF adjacent to ActivityPub already (namely, bearer capability URIs).

1 Like
10

Well, if we are to use something other than nodeinfo, I think we should also try to use something else than /.well-known because of the hardcoded path which may not work for everyone (for example the AP implementation being in a subdirectory like /~user/).

Not exactly sure what solution could there be on this one, but I think we should at least be aware of this issue.

EDIT: If it’s going to be more or less a per-actor thing it could be added to the actor endpoints and note that implementation should cache the response (to avoid doubling the requests on actor refresh).

11

We could probably use a DNS SRV and in general DNS SD entry to specify the well-known URI, if different from /.well-known.

1 Like
12

I think in general I’d want to be careful for onboarding to distinguish between “things the ActivityPub spec requires” and “things that you (probably) want to implement for maximum compatibility with instances of a certain type that can be found in the wild” - things like HTTP Signatures, Linked Data Signatures, and WebFinger should get a mention somewhere, but I also wouldn’t want to see the spec itself start requiring them, or a specific orientation towards dealing with authorization (as a for-instance) because my understanding is that ActivityPub is meant to be more general than the microblog-alike stuff that’s dominating what is floating around out there right now.

Something like a “guide to related specifications” on activitypub.rocks would go a long way towards making sure people understand what all these different things do, why they may (or may not) want to implement them, and what they can or can’t ignore, without running the risk of undermining innovation into “weirder” ways to use the spec, applications that don’t bear a particularly close resemblance to twitter, and explore new solutions to problems the fediverse is facing.

1 Like
13

(Sorry for the detour into capability negotiation earlier, we should open a separate discussion thread for that.)

I think the answer is to have a basic document that defines the current “profile” of ActivityPub – that it is composed with HTTP Signatures and WebFinger (some implementations do sign objects with LDSigs, but whether or not this is actually a good idea is debatable). That keeps core ActivityPub isolated, so it can remain strictly a “theory” document, while different “profiles” show how it is composed in practice. This was, originally, one of the things Litepub was meant to do, but it’s not really interesting work, and so it has yet to get done.

14

Note that the current status of ap.rocks makes it easier to organize the guide(s) as wikis on the forum, and link to it from ap.rocks.

1 Like
15

Note that the current status of ap.rocks makes it easier to organize the guide(s) as wikis on the forum, and link to it from ap.rocks

Lots of good ideas here. As part of getting up to speed on ActivityPub, I’ve started to pull together material for new implementers (like me!) that covers at least some of what’s been suggested. I’d be happy to post it as a first draft towards a wiki page or pages. Suggestions for where best to post?

1 Like
16

I’ve posted a draft here Draft: Guide for new ActivityPub implementers. Ideas and feedback very much appreciated.