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

view fixes

Browse source
This commit is contained in:
André Menrath 2023-10-03 15:45:21 +02:00
parent 908b4a669b
commit bf26766fa2
1 changed files with 28 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
architecture design proposal.md
View file

@ -8,14 +8,12 @@ authors:
include_toc: true include_toc: true
--- ---
# A proposal for the evolvment of the WordPress ActivityPub plugin 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 describes proposals for future development in the area of interaction between a WordPress plugin that add additional ActivityPub features via the [WordPress-ActivityPub plugin](https://github.com/Automattic/WordPress-ActivityPub/). # Terms used
## Terms used
The following terms are used: The following terms are used:
### Actor related ## Actor related
- **Actors:** ActivityPub actors (https://www.w3.org/TR/activitypub/#actor-objects) - **Actors:** ActivityPub actors (https://www.w3.org/TR/activitypub/#actor-objects)
- **Actor Types:** ActivityPub [Actor Types](https://www.w3.org/TR/activitystreams-vocabulary/#actor types) - **Actor Types:** ActivityPub [Actor Types](https://www.w3.org/TR/activitystreams-vocabulary/#actor types)
@ -25,7 +23,7 @@ The following terms are used:
- (custom) post-types - (custom) post-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 actually are mapped to any ActivityPub actors at all and to which one.
### Content related ## Content related
- **post-type:** Post type and custom post types within WordPress - **post-type:** Post type and custom post types within WordPress
- **Object Type:** ActivityPub [Object-Type](https://www.w3.org/TR/activitystreams-vocabulary/#object-types) - **Object Type:** ActivityPub [Object-Type](https://www.w3.org/TR/activitystreams-vocabulary/#object-types)
@ -35,12 +33,12 @@ The following terms are used:
- `post` to `Note`, `Article`, `Image`, `Audio` or `Article` depending on the [post-format](https://wordpress.org/documentation/article/post-formats/) - `post` to `Note`, `Article`, `Image`, `Audio` or `Article` depending on the [post-format](https://wordpress.org/documentation/article/post-formats/)
- `tribe_events` (Event post the of [The Event Calendar](https://wordpress.org/plugins/the-events-calendar/)) to `Event` - `tribe_events` (Event post the of [The Event Calendar](https://wordpress.org/plugins/the-events-calendar/)) to `Event`
### General ## General
- **publish:** Sending a `Create` or `Announce` [Activity](https://www.w3.org/TR/activitypub/#create-activity-outbox). - **publish:** Sending a `Create` or `Announce` [Activity](https://www.w3.org/TR/activitypub/#create-activity-outbox).
## Principals of the changes proposed to the ActivityPub plugin # Principals of the changes proposed to the ActivityPub plugin
The WordPress 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 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. - 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.
@ -54,7 +52,7 @@ The WordPress ActivityPub plugin
* actor management * actor management
## Goals # Goals
Our primary goal is to 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. Our primary goal is to 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.
@ -67,18 +65,18 @@ Nevertheless, we see a lot of other cases that can benefit, if we achieve this u
- 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). - 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).
## Transformer Management # Transformer Management
### User Interface ## User Interface
#### Current situation ### 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: 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. * [x] Note (default) - Should work with most platforms.
* [ ] Article - The presentation of the "Article" might change on different 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. * [ ] WordPress Post-Format - Maps the WordPress Post-Format to the ActivityPub Object Type.
#### Proposal ### Proposal
Every public WordPress post type may be transformed (have different transformers available) to a different ActivityPub object types. Transformations that are not Every public WordPress post type may be transformed (have different transformers available) to a different ActivityPub object types. Transformations that are not
available for a given post-type are greyed out. available for a given post-type are greyed out.
@ -95,7 +93,7 @@ x: ActivityPub object-types, y: WordPress post-types
- 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?). - 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. - 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.
#### Problems ### Problems
- If two transformers with the same source and target are installed, then we have two possibilities: - If two transformers with the same source and target are installed, then we have two possibilities:
1. A dropdown menu is displayed to select one of the transformers. 1. A dropdown menu is displayed to select one of the transformers.
@ -105,7 +103,7 @@ x: ActivityPub object-types, y: WordPress post-types
- Do we really want to manage which transformers apply to what directly or do users prefer a setting like "let a certain plugin take care of this post type"? Then further configuration would have to be managed by the other plugins. - Do we really want to manage which transformers apply to what directly or do users prefer a setting like "let a certain plugin take care of this post type"? Then further configuration would have to be managed by the other plugins.
### Backend ## Backend
Currently, only one hard-coded transformer exists in [`includes/transformer/class-post.php`](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/transformer/class-post.php). Currently, only one hard-coded transformer exists in [`includes/transformer/class-post.php`](https://github.com/Automattic/wordpress-activitypub/blob/master/includes/transformer/class-post.php).
```php ```php
@ -144,7 +142,7 @@ interface Transformer {
Use WordPress's hook system or a public API function to let other plugins register their custom transformer implementations to the ActivityPub plugin. Use WordPress's hook system or a public API function to let other plugins register their custom transformer implementations to the ActivityPub plugin.
#### Problem ### Problem
With the design above the transformer does a lot and leaves a lot of responsibility to the developer implementing it. With the design above the transformer does a lot and leaves a lot of responsibility to the developer implementing it.
@ -154,7 +152,7 @@ Possible alternatives and solutions:
- Don't use an interface with implementations, (miss)use class extensions. - Don't use an interface with implementations, (miss)use class extensions.
## Actor Mapping Management # Actor Mapping Management
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. 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.
@ -169,7 +167,7 @@ Note that depending on which options are enabled, the method of federating via A
- If both are enabled the `blog`-actor will announce (boosting) the posts of the - If both are enabled the `blog`-actor will announce (boosting) the posts of the
`author`-actors. `author`-actors.
### Possibilities ## Possibilities
ActivityPub knows several [actor types](https://www.w3.org/TR/activitystreams-core/#actors): ActivityPub knows several [actor types](https://www.w3.org/TR/activitystreams-core/#actors):
- Application - Application
- Group - Group
@ -179,27 +177,27 @@ ActivityPub knows several [actor types](https://www.w3.org/TR/activitystreams-co
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 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? ## 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. - 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.
- Additionally, for example, organizers in [The Event Calendar](https://wordpress.org/plugins/the-events-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. - Additionally, for example, organizers in [The Event Calendar](https://wordpress.org/plugins/the-events-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.
### Other features ## 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 site, even if they choose to federate them."
#### Problems ### Problems
- Overall complexity may lead to programming and usage errors. - Overall complexity may lead to programming and usage errors.
- Naming collisions become more likely. - Naming collisions become more likely.
- Who is the `actor`, who is the `attributedTo`, who is just sending an `Announce` of a post? - Who is the `actor`, who is the `attributedTo`, who is just sending an `Announce` of a post?
### Proposed starting point for evaluating use cases ## 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. We keep in mind that every post type shall only ever send as a `Create` Activity once by one single actor.
#### User Interface ### User Interface
| | users | tribe_organizers | custom | blog | category | | | users | tribe_organizers | custom | blog | category |
| -----------------|:-----:|:----------------:|:------:|:-----:|:--------:| | -----------------|:-----:|:----------------:|:------:|:-----:|:--------:|
| **post** | C | O | O | A | A | | **post** | C | O | O | A | A |
@ -219,7 +217,7 @@ We keep in mind that every post type shall only ever send as a `Create` Activity
- Only allow setting something to `Announce`, when a `Create` is already set. - 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". - Maybe forbid, that a user can automatically announce a post, because it's the "lowest level".
### Actor collisions ## 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. 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.
@ -231,21 +229,21 @@ It seems like it is the best if collisions are avoided in the first place by enc
Anyway it seems the question has to be raised wheter activitypub should store a history of all past and currently mapped actors. Anyway it seems the question has to be raised wheter activitypub should store a history of all past and currently mapped actors.
#### Existing collisions ### Existing collisions
- **Easy:** Either we just tell the user to resolve all conflicts before a WordPress actor type can be activated at all - **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. - **Complex:** We let him choose alternatives for conflicts.
#### New collisions ### New collisions
- **Easy** Forbid the saving of new users or posts that would conflict with an existing actor. - **Easy** Forbid the saving of new users or posts that would conflict with an existing actor.
- **Complex** ... - **Complex** ...
### Conclusion ## 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. - 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? - Additionally, shouldn't the user have a detailed overview in each case if the actor management should get more complex?
#### Proposal of how plugins register WordPress-actor types ### Proposal of how plugins register WordPress-actor types
```php ```php
interface ActorType { interface ActorType {
@ -258,9 +256,9 @@ interface ActorType {
The registration of an actor type also registers every actor that is currently in the `listActorsOfThisType()`-list. The registration of an actor type also registers every actor that is currently in the `listActorsOfThisType()`-list.
## Appendix # Appendix
### The approach of youtube-dl ## 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. [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.
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 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.