Proposal: flexible management of how posts gets transformed to ActivityPub objects

[Menrath]

This document outlines suggestions for the further development of the WordPress ActivityPub plugin regarding its interoperability with other WordPress plugins that could enhance ActivityPub functionality.

This work has been done within the course of a project aiming at better event-federation within WordPress: repository, website.

Note: Currently drafts for a pull request on this are already being worked on.

The main part of this proposal: Scroll down to Transformer Management.

Terms used

The following terms are used:

• post type: post types 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)
• publish/dispatch: Sending a Create, Update or Announce Activity.

Principals of the changes proposed changes:

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.

Goals

Goals of the WordPress Event Federation project

The aim of the event federations project is to enable seamless federation of events created within an event plugin as an ActivityPub object with Type Event and accompanying meta-data, as typically seen in common ActivityPub implementations like Mobilizon. This will guarantee optimal compatibility between various 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: CastoPod, 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 and not Product even though that one would be available in the official specification.

Transformer Management

Current situation

Frontend

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.

Backend

Currently, all this functionality is handled via one hard-coded transformer in includes/transformer/class post.php (Source) and the actual logic that assigns the type is somewhere else.

/**
 * 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() {
    ...

Proposal

All publicly accessible WordPress post types can become active for ActivityPub federation when selecting a transformer available for the relevant post type. It is up to the transformer to determine the target ActivityPub object type, which may vary depending on variables such as 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.

Frontend

	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	-	-	-

columns: Available transformers
rows: 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 clearly 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

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.
• Provide useful functions, documentation, and examples for automatic testing of transformers.
• Highly unlikely: The ActivityPub plugin provides an even more high 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.
• Highly unlikely: don't use an interface with implementations, (miss)use class extensions.

[pfefferle]

Thanks for writing that down!

I already started something in that direction https://github.com/Automattic/wordpress-activitypub/pull/550/files#diff-d2a03275a41bd73f49915a3cd42eb16d6f85a7e6bd128973ad8ffeaf57366af2

I would love to also add the interface!

[pfefferle]

I am also thinking about an outbox (custom post type), to have a more solid queue instead of a simple "One time schedule".

[Menrath]

@pfefferle I thought for consistency it might be a good idea, if each transformer, even the built-in one(s), get a dedicated settings page?

[Menrath]

The draft is aiming at using different transformers based on whether to transform a WP_Post or WP_Comment object. We mainly had transforming WP_Post objects in mind, but we will keep such things in mind as well. Thanks again for pointing that out.

[openforfuture]

I would suggest to add the Events Manager plugin in the examples: it uses event as "post type". I already wrote the code to interface it with @pfefferle plugin and federate events with Mobilizon, so we can reuse code and save time. Even if it is used by less people I found it more "dev friendly" and the basic version has no limitations, with also some advanced functions: in my use cases I never needed to upgrade to the Pro version.

[Menrath]

This plugin will be part of our first example implementations, for sure :) but I don't see a reason to add it to the original post as an example.

[pfefferle]

What settings do you have in mind?