Event-Federation/documentation
7
1
Fork 0
Code Issues 2 Pull requests Projects Releases Wiki Activity

Adding plenty of language improvements

Browse source
This commit is contained in:
André Menrath 2023-10-10 15:20:02 +02:00
parent 6c57a0b281
commit fc4dbfbcb9
1 changed files with 25 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
architecture design proposal.md
View file

@ -1,14 +1,13 @@
---
gitea: none
title: WordPress/ActivityPub
lang: en
authors:
- André Menrath
- ruru
- ruruLanguageTool Linter
include_toc: true
---
This document describes proposals for the evolvment of the [WordPress ActivityPub plugin](https://github.com/Automattic/WordPress-ActivityPub/) in the field of the interaction with other WordPress plugins that may add additional ActivityPub features.
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.
# Terms used
@ -30,9 +29,9 @@ The following terms are used:
- **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`
- 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.
- **Mapping:** Which WordPress actor types are mapped to any ActivityPub actors at all and to which ones.
## General
- **publish/dispatch:** Sending a `Create`, `Update` or `Announce` [Activity](https://www.w3.org/TR/activitypub/#create-activity-outbox).
@ -47,17 +46,17 @@ The WordPress ActivityPub plugin
- (maybe) offers other plugins the possibility to register new WordPress actor types, e.g. the `tribe_organizer` post type of [The Event Calendar](https://wordpress.org/plugins/the-events-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)
* 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:
- maybe distinguishes between the default 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.
## 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:
@ -65,10 +64,10 @@ Nevertheless, we see a lot of other cases that can benefit, if the primary goals
- `PodcastEpisode` [as proposed by CastoPod](https://code.castopod.org/adaures/castopod/-/blob/main/app/Libraries/PodcastEpisode.php)
- `Question`
- `Product`
- ...
- …
- ActivityPub offers features how to deal with multilingual content ([contentMap - see Example 115](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-contentmap)) 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](https://codeberg.org/grindhold/flohmarkt) is currently also using the `Note` and not `Product` even though that one would be available in the offical specification.
**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](https://codeberg.org/grindhold/flohmarkt) is currently also using the `Note` and not `Product` even though that one would be available in the official specification.
# Transformer Management
@ -77,9 +76,9 @@ Nevertheless, we see a lot of other cases that can benefit, if the primary goals
### 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:
* [x] 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.
* [x] 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.
@ -98,7 +97,7 @@ All publicly accessible WordPress post types can become active for ActivityPub f
- 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.
- 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
Currently, only one hard-coded transformer exists in `includes/transformer/class post.php` ([Source](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/transformer/class-post.php)).
@ -161,10 +160,9 @@ Currently, the admin user interface in v1.0.0 gives very limited options.
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.
- If both options are enabled the `blog`-actor will announce (boost) the posts of the `author`-actors.
Currently the whole logic controlling this is written within the `Activity_Dispatcher` [class](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/class-activity-dispatcher.php#L21) which is currently triggered only within the `Scheduler` [class](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/class-scheduler.php#L14-L15).
Currently, the whole logic controlling this is written within the `Activity_Dispatcher` [class](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/class-activity-dispatcher.php#L21) which is currently triggered only within the `Scheduler` [class](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/class-scheduler.php#L14-L15).
Furthermore, although a blog actor is available, the ActivityPub plugin is still written in such a way that WordPress users are the default ActivityPub actors. 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](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/collection/class-users.php).
## Possibilities
@ -175,7 +173,7 @@ ActivityPub knows several [actor types](https://www.w3.org/TR/activitystreams-co
- `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**.
The ActivityPub specification allows for immense flexibility in its application. As WordPress websites fulfill a variety of tasks and objectives, it is **challenging to implement control features and options for actor management that are more capable without sacrificing user-friendliness.**
## 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.
@ -183,7 +181,7 @@ The specifications allow for a lot of flexibility in their use. As WordPress web
- Optional: As events are sometimes published a long time before they start, adding the possibility 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."
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 website, even if they choose to federate them."
**Problems:**
- Overall complexity may lead to programming and usage errors.
@ -204,11 +202,11 @@ We keep in mind that every post type shall only ever send as a `Create` Activity
**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
**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
**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.
@ -216,23 +214,21 @@ We keep in mind that every post type shall only ever send as a `Create` Activity
## Actor collisions
Each ActivityPub actor must have a [unique ID](https://www.w3.org/TR/activitypub/#obj-id). In our case this is a HTTPS URI.
But in reality [webfinger](https://webfinger.net/) 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.
But in reality [webfinger](https://webfinger.net/) 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.
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.
### 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** ...
- **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.
@ -243,4 +239,4 @@ Anyway it seems the question has to be raised wheter activitypub should store a
## The approach of youtube-dl
[youtube-dl](https://github.com/ytdl-org/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](https://github.com/ytdl-org/youtube-dl#adding-support-for-a-new-site) 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.
They can also chain extractors recursively, 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.