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

fix typos and make formatting consistent

Browse source
This commit is contained in:
André Menrath 2023-10-10 12:53:57 +02:00
parent 7f44c1cff5
commit 597111d650
1 changed files with 5 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
architecture design proposal.md
View file

@ -10,12 +10,13 @@ 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 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.
# Terms used # Terms used
The following terms are used: The following terms are used:
## Content related ## Content related
- **post type:** post types 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)
- **Transformers:** a piece of code that converts items of particular WordPress post types to an ActivityPub object. For example a transformer that can transform: - **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` - every post type to a `Note`
@ -24,7 +25,6 @@ The following terms are used:
- `podcast` (Podcast post of [Podlove Podcast Publisher](https://github.com/podlove/podlove-publisher)) to `PodcastEpisode` as ([proposed and implemented by Castopod](https://code.castopod.org/adaures/castopod/-/blob/main/app/Libraries/PodcastEpisode.php)) - `podcast` (Podcast post of [Podlove Podcast Publisher](https://github.com/podlove/podlove-publisher)) to `PodcastEpisode` as ([proposed and implemented by Castopod](https://code.castopod.org/adaures/castopod/-/blob/main/app/Libraries/PodcastEpisode.php))
## Actor related ## Actor related
- **Actors:** ActivityPub [Actor Objects](https://www.w3.org/TR/activitypub/#actor-objects) - **Actors:** ActivityPub [Actor Objects](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)
- **WordPress actor types:** Things on WordPress that can be mapped to actors: - **WordPress actor types:** Things on WordPress that can be mapped to actors:
@ -35,11 +35,11 @@ The following terms are used:
- **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.
## General ## General
- **publish/dispatch:** Sending a `Create`, `Update` or `Announce` [Activity](https://www.w3.org/TR/activitypub/#create-activity-outbox). - **publish/dispatch:** Sending a `Create`, `Update` 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.
@ -70,19 +70,18 @@ Nevertheless, we see a lot of other cases that can benefit, if the primary goals
**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:** 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.
# 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
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. 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 | | | Note | Post-Format | The Events Calendar Transformer | Custom Event Transformer |
@ -101,9 +100,7 @@ All publicly accessible WordPress post types can become active for ActivityPub f
- 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.
- 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 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 ## 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)). 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)).
```php ```php
@ -180,15 +177,11 @@ 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. More or less this can already be achieved with the current blog-actor. - 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](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.
- 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. - 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 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:**
@ -197,7 +190,6 @@ Other WordPress actor types might have valid use cases, like actors for categori
- 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:**
@ -222,7 +214,6 @@ We keep in mind that every post type shall only ever send as a `Create` Activity
- 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.
@ -250,6 +241,5 @@ Anyway it seems the question has to be raised wheter activitypub should store a
# 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. The most [basic extractor](https://github.com/ytdl-org/youtube-dl#adding-support-for-a-new-site) is about 40 lines of code. [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 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.