documentation/architecture design proposal.md

Table of Contents

• Terms used
• Content related
• Actor related
• General
• Principals of the changes proposed to the ActivityPub plugin
• Goals
• Goals of the WordPress Event Fedeartion project
• Tangential Objectives:
• Transformer Management
• User Interface
• Current situation
• Proposal
• Backend
• Mapping: Actors and Dispatching
• Current situation
• Possibilities
• What features does our event federation project need?
• Other features
• Proposed starting point for evaluating use cases
• Actor collisions
• Existing collisions
• New collisions
• Conclusion
• Appendix
• The approach of youtube-dl

This document describes proposals for the evolvment of the WordPress ActivityPub plugin in the field of the interaction with other WordPress plugins that may add additional ActivityPub features.

Terms used

The following terms are used:

Content related

• post type: Post type and custom post types within WordPress
• Object Type: ActivityPub object type
• Transformers: a piece of code that converts items of particular WordPress post types to an ActivityPub object. For example a transformer that can transform:
  • every post type to a Note
  • post or page to Note, Article, Image, Audio or Article depending on the post-format
  • tribe_events (Event post the of The Event Calendar) to Event
  • podcast (Podcast post of Podlove Podcast Publisher) to PodcastEpisode as (proposed and implemented by Castopod)

Actor related

• Actors: ActivityPub Actor Objects
• Actor Types: ActivityPub Actor Types
• WordPress actor types: Things on WordPress that can be mapped to actors:
  • WordPress users →Person
  • Whole Blog →Application or Group
  • post types → e.g. Organization
  • custom definitions → custom actor types
• Mapping: Which WordPress actor types are actually are mapped to any ActivityPub actors at all and to which one.

General

• publish/dispatch: Sending a Create, Update or Announce Activity.

Principals of the changes proposed to the ActivityPub plugin

The WordPress ActivityPub plugin

• should be aware (or even control) the whole chain from creating some content within WordPress to being published via ActivityPub. For sure, it should be the only plugin that directly sends and receives ActivityPub.
• should not get any more complex by default, the out-of-the box functionality/features and simplicity should be similar to version 1.0.0.
• offers other plugins the possibility to register custom transformers.
• (maybe) offers other plugins the possibility to register new WordPress actor types, e.g. the tribe_organizer post type of The Event Calendar.
• handles the controls collisions of actor names:
  • collisions that are already present during activation of a WordPress actor type on the settings page
  • collisions that happen afterwards (e.g. a new user registering with the same username as the blog-wide actor)
  • (maybe) show notifications/warnings when using an actor name which has been used and followed by in the past, as there may be issues due to caching of the old public key.
• maybe distinguishes between the default admin user interface and advanced sections which give the user more fine-grained control:
  • transformer management
  • actor management

Goals

Goals of the WordPress Event Fedeartion project

The event federations project goal is make it possible that events created within an event plugin can federate properly as an ActivityPub object with Type Event along with all the meta-data belonging to the event, as found in common ActivityPub implementations, e.g. of Mobilizon, in order to ensure maximum compatibly between those services.

Tangential Objectives:

Nevertheless, we see a lot of other cases that can benefit, if the primary goals of the event federation project are achieved this using a modularized approach as proposed below. The following list indicates examples what might be those other benefits:

• Other types of content get federated in a more feature rich way:
  • PodcastEpisode as proposed by CastoPod
  • Question
  • Product
  • ...
• ActivityPub offers features how to deal with multilingual content (contentMap - see Example 115) which could be implemented differently by multilingual and translation plugins (example search for the current use of ->set_content_map within the ActivityPub plugin).

Note: CastoPop, to give an example, has currently decided that podcast episodes will not be sent to followers as a Create activity directly containing the PodcastEpisode object, but will send a Note which is linking to the PodcastEpisode, because most Fediverse implementations currently ignore by default all object types they don't know. This is likely the same reason flohmarkt is currently also using the Note an not Product even though that one would be available in the offical specification.

Transformer Management

User Interface

Current situation

The admin user interface in v1.0.0 lets one choose to which object type all post get transformed to. The options are:

• Note (default) - Should work with most platforms.
• Article - The presentation of the "Article" might change on different platforms.
• WordPress Post-Format - Maps the WordPress Post-Format to the ActivityPub Object Type.

Proposal

All publicly accessible WordPress post types can become active for ActivityPub federation when selecting a transformer available for the relevant post type. The transformer determines the target ActivityPub object type, which can vary depending on variables like the post type or post format. If there is no specific transformer available for a given post type, it cannot be assigned through the user interface.

	Note	Post-Format	The Events Calendar Transformer	Custom Event Transformer
post	X	O	-	-
page	O	O	-	-
tribe_events	O	-	X	O
custom_event	O	-	-	O
...	O	-	-	-

x: Available transformers
y: Public and non-password protected WordPress post types
Note: Only one or zero selections can be made in each row.

• For any custom post type, if there is a custom transformer registered, indicate that one should be selected as default (or select it right ahead?).
• Should not differ too much from the current view: Maybe completely hide the current activity object type part of the settings and only show the buttons for enable and disable and move the transformer table to an advanced settings page.
• Maybe make the tables more advanced and cleary show the origin of the transformer (built-in, etc.) and maybe a Pop-Up with a description, or even a link to a configuration page of the transformer.

Backend

Currently, only one hard-coded transformer exists in includes/transformer/class post.php (Source).

/**
 * WordPress Post Transformer
 *
 * The Post Transformer is responsible for transforming a WP_Post object into different othe
 * Object-Types.
 *
 * Currently supported are:
 *
 * - Activitypub\Activity\Base_Object
 */
class Post {
    ...
    	/**
         * Transforms the WP_Post object to an ActivityPub Object
         *
         * @see \Activitypub\Activity\Base_Object
         *
         * @return \Activitypub\Activity\Base_Object The ActivityPub Object
         */
        public function to_object() {
    ...

A solution could be to define a transformer interface and let the transformers be implementations.

interface Transformer {
    public function get_supported_post_types(): array;
    public function get_transformer_info(): array;
    public function to_object(WP_Post $post);
    ....
}

Use WordPress's hook system or a public API function to let other plugins register their custom transformer implementations to the ActivityPub plugin.

Problem: With the design above the transformer does a lot and leaves a lot of responsibility to the developer implementing it.

Possible alternatives and solutions:

• The ActivityPub plugin could provide reusable Traits for common tasks.
• Highly unlikely: The ActivityPub plugin provides an even more height level framework for adding transformers. For example for events the ActivityPub plugin could provide a built-in transformer to the object type Event which only needs a mapping (might make things harder, instead of making them easier). See Appendix.
• Don't use an interface with implementations, (miss)use class extensions.

Mapping: Actors and Dispatching

More comprehensive actor management would benefit our project aims and potentially meet the needs of others in the future. Nevertheless, its importance is considerably lower than that of Transformer management. In the future, the following factors may become more important when larger websites should be using the ActivityPub plugin.

Current situation

Currently, the admin user interface in v1.0.0 gives very limited options.

- [ ] Enable `blog`-actor
- [ ] Enable `author`-actors

Note that depending on which options are enabled, the method of federating via ActivityPub varies significantly:

• If the blog-actor is enabled, but the author-actors are not, posts are attributed and created by the blog actor.
• If both are enabled the blog-actor will announce (boosting) the posts of the author-actors.

Currently the whole logic controlling this is written within the Activity_Dispatcher class which is currently triggered only within the Scheduler class.

Possibilities

ActivityPub knows several actor types:

• Application
• Group
• Organization
• Person
• Service

The specifications allow for a lot of flexibility in their use. As WordPress websites serve a variety of tasks and goals, providing more detailed capabilities and options in this area may prove challenging to accomplish in a user-friendly manner.

What features does our event federation project need?

• For maximum Mobilizon compatibility we would love to have simply an actor of type Application, preferable called @relay@wordpress.site, that announces all events. Nonetheless, in theory, a Mobilizon instance should have the capability to follow any other actor as well. More or less this can already be achieved with the current blog-actor.

• Additionally, for example, organizers in The Event Calendar could also offer their own actor of type Organizer or Group to publicize events, or create events if the author-actors are not enabled.

• Optional: As events are sometimes published a long time before they start, adding the posibility that events get announced again at a scheduled time before the start, e.g. by sending an Announce activity.

Other features

Other WordPress actor types might have valid use cases, like actors for categories, or specific post types in general: "I only want to see the blog updates, but I do not want to spam my timeline with each product they post on their site, even if they choose to federate them."

Problems:

• Overall complexity may lead to programming and usage errors.
• Naming collisions become more likely. See below.
• Who is the actor, who is the attributedTo, who is just sending an Announce of a post?

Proposed starting point for evaluating use cases

We keep in mind that every post type shall only ever send as a Create Activity once by one single actor.

User Interface:

	users	tribe_organizers	custom	blog	category
post	C	O	O	A	A
page	C	O	O	A	O
tribe_events	O	C	-	A	0
product	O	-	C	0	0

x: WordPress actor-types
y: WordPress post types
C: Create - can only be assigned once per row A: Announce - can be assigned multiple times per row, but only if a Create has been assigned before user: the WordPress user publishing or updating something
all: blog-wide actor, everything that is published (like a relay)
custom: e.g. only a certain post_type that gets announced with this actor
tribe_organizers: only posts by one organizer

• Only allow setting something to Announce, when a Create is already set.
• Maybe forbid, that a user can automatically announce a post, because it's the "lowest level".

Actor collisions

Each ActivityPub actor must have a unique ID. In our case this is a HTTPS URI. But in reality webfinger is used: @actor-name@instance.tld. Actors like Persons and Groups and Applications have Public Keys attached to them, as well as their ID is probably cached by most software. So assigning some actor-name to something new also can cause unintended behavior.

If multiple plugins want to individually federate their content (like events, products and blog posts or even the built-in WordPress categories), they must be able to have something like an actor API, the ActivityPub plugin can register. The ActivityPub plugin being the main coordinator is necessary because actors are globally unique.

• For existing (collision was created before the installation/activation of the plugin)
• For new collisions (collision was/will be created after the installation/activation of the plugin)

It seems like it is the best if collisions are avoided in the first place by encouraging the use of prefixes, like category_<category>.

Anyway it seems the question has to be raised wheter activitypub should store a history of all past and currently mapped actors. Currently the ActivityPub plugin is still written with WordPress users being the default ActivityPub actors in mind. This also reflects in things like the class which is responsible for the actor lookup is still called Users and yet handles the Blog and the Application user too, see the Source.

Existing collisions

• Easy: Either we just tell the user to resolve all conflicts before a WordPress actor type can be activated at all
• Complex: We let him choose alternatives for conflicts.

New collisions

• Easy Forbid the saving of new users or posts that would conflict with an existing actor.
• Complex ...

Conclusion

• Anyway it seems the question has to be raised whether the ActivityPub plugin should store a history of all past and currently mapped actors.
• Additionally, shouldn't the user have a detailed overview in each case if the actor management should get more complex?

Appendix

The approach of youtube-dl

youtube-dl is solving a similar problem with "extractors" that return data to the processing-chain of youtube-dl. They provide a base class that includes useful functions for common issues e.g. automatic testing, geo-bypassing, login/cookie/header management. The most basic extractor is about 40 lines of code. They can also chain extractors recursivly, like a extractor for mastodon videos, that gets the video from the post and returns the source of the video, that could be youtube, vimeo or anything else youtube-dl supports.