From c06715852c2f9dedbb7830663eb4ae91620d84c0 Mon Sep 17 00:00:00 2001 From: Petitminion Date: Fri, 17 Nov 2023 23:13:59 +0100 Subject: [PATCH 1/3] add sporiff activitypub overview --- docs/specs/activitypub-overview/index.md | 151 +++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/specs/activitypub-overview/index.md diff --git a/docs/specs/activitypub-overview/index.md b/docs/specs/activitypub-overview/index.md new file mode 100644 index 000000000..fc0aaae74 --- /dev/null +++ b/docs/specs/activitypub-overview/index.md @@ -0,0 +1,151 @@ +Funkwhale ActivityPub overview +=== + +## Actors + +Funkwhale uses [ActivityPub actors](https://www.w3.org/TR/activitypub/#actor-objects) to hold and manage access to content. There are five main types of actor: + +Service actor + +: The **Service actor** is a special actor that represents a Funkwhale pod. ActivityPub actors can [follow this actor](https://www.w3.org/TR/activitypub/#follow-activity-outbox) to receive updates to public content stored on the pod. + +User + +: A **User** is an actor that represents **either** a person with a Funkwhale account **or** a *virtual* user that controls access to a **Channel**. *Regular* **Users** can own Funkwhale **Collection** actors to add content to their [ActivityPub Collection](https://www.w3.org/TR/activitypub/#collections). + +: *Regular* **Users** may follow other **Users** to receive updates about the **User's** *Favorites* ([likes collection](https://www.w3.org/TR/activitypub/#likes)) and *Listening activity*. + +: Multiple *regular* **Users** can own a *virtual* **User** to control access to a **Channel**. This is useful in the example of bands or groups who might share access to a joint account. A **User** may authenticate as the *virtual* user to add content to a **Channel's** + [ActivityPub Collection](https://www.w3.org/TR/activitypub/#collections). + +Collection + +: A **Collection** is an actor that represents a collection of content owned by a **User**. ActivityPub actors can [follow this actor](https://www.w3.org/TR/activitypub/#follow-activity-outbox) to be notified of changes to the collection's content. + +Channel + +: A **Channel** is an actor that represents a public stream of content owned by a *virtual* **User**. Funkwhale **Users** with access to the *virtual* **User** may manage content in the **Channel's** collection. ActivityPub actors can [follow this actor](https://www.w3.org/TR/activitypub/#follow-activity-outbox) to be notified of changes to the collection's content. + +Each actor must have a globally unique username that identifies them across federation. The `preferredUsername` field should be used to render the actor's name in all representations. Actor owners can change the `preferredUsername` of the actor at any time to update how it is represented. + + +```mermaid +erDiagram + Pod ||--|| ServiceActor : contains + Pod ||--|{ Users: contains + Users ||--|{ Collections : owns + Users }|--o{ VirtualUsers : accesses + VirtualUsers ||--|{ Channels : owns + Users }|--o{ Collections : follows + Users }|--o{ Channels : follows + Channels }|--|| ServiceActor : "public content" + Collections }|--|| ServiceActor : "public content" + ServiceActor ||--|| Outbox : publish +``` + +## Service actor outbox + +The **Service actor** publishes *public* Funkwhale content to its [outbox](https://www.w3.org/TR/activitypub/#outbox). When new content is added to a *public* **Collection** or to a **Channel**, this update is added to the **Service actor's** outbox. Actors in the [follower collection](https://www.w3.org/TR/activitypub/#followers) receive updates in their [inbox](https://www.w3.org/TR/activitypub/#inbox) and display the new content. + +Pods may follow one another's public content by having their **Service actor** follow the target pod's **Service actor**. If the target **Service actor** [accepts](https://www.w3.org/TR/activitypub/#accept-activity-inbox) the follow request, the requesting **Service actor** is added to the target **Service actor's** follower collection. + +```mermaid +sequenceDiagram + Pod A->>Pod B: Follow + Pod B-->>Pod A: Accept + loop New items are added to the outbox + Pod B->>Pod A: New items + end +``` + +**Service actors** publish the following to their outbox: + +* Addition of new public content (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against content objects) +* Deletion of public content (represented as [delete activities](https://www.w3.org/TR/activitypub/#delete-activity-inbox) against content objects) +* Changes to public content details (represented as [update activities](https://www.w3.org/TR/activitypub/#update-activity-inbox) against content objects) + +```mermaid +sequenceDiagram + User->>Service actor: Add new public content + Service actor->>Outbox: Create content object + Outbox->>Follower collection: Create content object + User->>Service actor: Delete public content + Service actor->>Outbox: Delete content object + Outbox->>Follower collection: Delete content object + User->>Service actor: Update public content + Service actor->>Outbox: Update content object + Outbox->>Follower collection: Update content object +``` + +## Regular user outbox + +**Regular** actors publish the following to their [outbox](https://www.w3.org/TR/activitypub/#outbox): + +* Their favorites (represented as liked objects in their [likes collection](https://www.w3.org/TR/activitypub/#likes) +* Their listens (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against listening objects) + +### Favorite action + +```mermaid +sequenceDiagram + par + User->>Funkwhale API: Favorite content + User->>Outbox: Like content object + end + Outbox->>Follower collection: Like content object +``` + +### Listen action + +```mermaid +sequenceDiagram + par + User->>Funkwhale API: Listen + User->>Outbox: Create listen object + end + Outbox->>Follower collection: Create listen object +``` + +## Collection outbox + +**Collection** actors publish the following to their [outbox](https://www.w3.org/TR/activitypub/#outbox): + +* Addition of new content (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against content objects) +* Deletion of content (represented as [delete activities](https://www.w3.org/TR/activitypub/#delete-activity-inbox) against content objects) +* Changes to content details (represented as [update activities](https://www.w3.org/TR/activitypub/#update-activity-inbox) against content objects) + +```mermaid +sequenceDiagram + User->>Collection: Add new content + Collection->>Outbox: Create content object + Outbox->>Follower collection: Create content object + User->>Collection: Delete content + Collection->>Outbox: Delete content object + Outbox->>Follower collection: Delete content object + User->>Collection: Update content + Collection->>Outbox: Update content object + Outbox->>Follower collection: Update content object +``` + +## Channel outbox + +**Channel** actors publish the following to their [outbox](https://www.w3.org/TR/activitypub/#outbox): + +* Addition of new content (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against content objects) +* Deletion of content (represented as [delete activities](https://www.w3.org/TR/activitypub/#delete-activity-inbox) against content objects) +* Changes to content details (represented as [update activities](https://www.w3.org/TR/activitypub/#update-activity-inbox) against content objects) + +```mermaid +sequenceDiagram + User->>Channel: Add new content + Channel->>Outbox: Create content object + Outbox->>Follower collection: Create content object + User->>Channel: Delete content + Channel->>Outbox: Delete content object + Outbox->>Follower collection: Delete content object + User->>Channel: Update content + Channel->>Outbox: Update content object + Outbox->>Follower collection: Update content object +``` + +###### tags: `specs` `in-progress` `activitypub` From 8b5772a7ce881db8fb55fa8560ce185712db5729 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Tue, 12 Dec 2023 18:17:27 +0000 Subject: [PATCH 2/3] Update formatting for Sphinx --- docs/index.md | 1 + docs/specs/activitypub-overview/index.md | 82 +++++++++++++----------- 2 files changed, 44 insertions(+), 39 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6566d65bf..2d41c6136 100644 --- a/docs/index.md +++ b/docs/index.md @@ -101,6 +101,7 @@ caption: Specifications hidden: true --- +specs/activitypub-overview/index specs/collections/index specs/nodeinfo21/index specs/offline-mode/index diff --git a/docs/specs/activitypub-overview/index.md b/docs/specs/activitypub-overview/index.md index fc0aaae74..7c80d1758 100644 --- a/docs/specs/activitypub-overview/index.md +++ b/docs/specs/activitypub-overview/index.md @@ -1,35 +1,29 @@ -Funkwhale ActivityPub overview -=== +# ActivityPub overview ## Actors -Funkwhale uses [ActivityPub actors](https://www.w3.org/TR/activitypub/#actor-objects) to hold and manage access to content. There are five main types of actor: +Funkwhale uses [ActivityPub actors][actor-object] to hold and manage access to content. There are five main types of actor: Service actor - -: The **Service actor** is a special actor that represents a Funkwhale pod. ActivityPub actors can [follow this actor](https://www.w3.org/TR/activitypub/#follow-activity-outbox) to receive updates to public content stored on the pod. +: The **Service actor** is a special actor that represents a Funkwhale pod. ActivityPub actors can [follow this actor][follow-activity] to receive updates to public content stored on the pod. User +: A **User** is an actor that represents **either** a person with a Funkwhale account **or** a _virtual_ user that controls access to a **Channel**. _Regular_ **Users** can own Funkwhale **Collection** actors to add content to their [ActivityPub Collection][collections]. -: A **User** is an actor that represents **either** a person with a Funkwhale account **or** a *virtual* user that controls access to a **Channel**. *Regular* **Users** can own Funkwhale **Collection** actors to add content to their [ActivityPub Collection](https://www.w3.org/TR/activitypub/#collections). +: _Regular_ **Users** may follow other **Users** to receive updates about the **User's** _Favorites_ ([likes collection](https://www.w3.org/TR/activitypub/#likes)) and _Listening activity_. -: *Regular* **Users** may follow other **Users** to receive updates about the **User's** *Favorites* ([likes collection](https://www.w3.org/TR/activitypub/#likes)) and *Listening activity*. - -: Multiple *regular* **Users** can own a *virtual* **User** to control access to a **Channel**. This is useful in the example of bands or groups who might share access to a joint account. A **User** may authenticate as the *virtual* user to add content to a **Channel's** - [ActivityPub Collection](https://www.w3.org/TR/activitypub/#collections). +: Multiple _regular_ **Users** can own a _virtual_ **User** to control access to a **Channel**. This is useful in the example of bands or groups who might share access to a joint account. A **User** may authenticate as the _virtual_ user to add content to a **Channel's** +[ActivityPub Collection][collections]. Collection - -: A **Collection** is an actor that represents a collection of content owned by a **User**. ActivityPub actors can [follow this actor](https://www.w3.org/TR/activitypub/#follow-activity-outbox) to be notified of changes to the collection's content. +: A **Collection** is an actor that represents a collection of content owned by a **User**. ActivityPub actors can [follow this actor][follow-activity] to be notified of changes to the collection's content. Channel - -: A **Channel** is an actor that represents a public stream of content owned by a *virtual* **User**. Funkwhale **Users** with access to the *virtual* **User** may manage content in the **Channel's** collection. ActivityPub actors can [follow this actor](https://www.w3.org/TR/activitypub/#follow-activity-outbox) to be notified of changes to the collection's content. +: A **Channel** is an actor that represents a public stream of content owned by a _virtual_ **User**. Funkwhale **Users** with access to the _virtual_ **User** may manage content in the **Channel's** collection. ActivityPub actors can [follow this actor][follow-activity] to be notified of changes to the collection's content. Each actor must have a globally unique username that identifies them across federation. The `preferredUsername` field should be used to render the actor's name in all representations. Actor owners can change the `preferredUsername` of the actor at any time to update how it is represented. - -```mermaid +```{mermaid} erDiagram Pod ||--|| ServiceActor : contains Pod ||--|{ Users: contains @@ -45,11 +39,11 @@ erDiagram ## Service actor outbox -The **Service actor** publishes *public* Funkwhale content to its [outbox](https://www.w3.org/TR/activitypub/#outbox). When new content is added to a *public* **Collection** or to a **Channel**, this update is added to the **Service actor's** outbox. Actors in the [follower collection](https://www.w3.org/TR/activitypub/#followers) receive updates in their [inbox](https://www.w3.org/TR/activitypub/#inbox) and display the new content. +The **Service actor** publishes _public_ Funkwhale content to its [outbox][outbox]. When new content is added to a _public_ **Collection** or to a **Channel**, this update is added to the **Service actor's** outbox. Actors in the [followers collection][followers-collection] receive updates in their [inbox][inbox] and display the new content. -Pods may follow one another's public content by having their **Service actor** follow the target pod's **Service actor**. If the target **Service actor** [accepts](https://www.w3.org/TR/activitypub/#accept-activity-inbox) the follow request, the requesting **Service actor** is added to the target **Service actor's** follower collection. +Pods may follow one another's public content by having their **Service actor** follow the target pod's **Service actor**. If the target **Service actor** [accepts][accept-activity] the follow request, the requesting **Service actor** is added to the target **Service actor's** follower collection. -```mermaid +```{mermaid} sequenceDiagram Pod A->>Pod B: Follow Pod B-->>Pod A: Accept @@ -60,11 +54,11 @@ sequenceDiagram **Service actors** publish the following to their outbox: -* Addition of new public content (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against content objects) -* Deletion of public content (represented as [delete activities](https://www.w3.org/TR/activitypub/#delete-activity-inbox) against content objects) -* Changes to public content details (represented as [update activities](https://www.w3.org/TR/activitypub/#update-activity-inbox) against content objects) +- Addition of new public content (represented as [created actvities][create-inbox] against content objects) +- Deletion of public content (represented as [delete activities][delete-activity] against content objects) +- Changes to public content details (represented as [update activities][update-activity] against content objects) -```mermaid +```{mermaid} sequenceDiagram User->>Service actor: Add new public content Service actor->>Outbox: Create content object @@ -79,14 +73,14 @@ sequenceDiagram ## Regular user outbox -**Regular** actors publish the following to their [outbox](https://www.w3.org/TR/activitypub/#outbox): +**Regular** actors publish the following to their [outbox][outbox]: -* Their favorites (represented as liked objects in their [likes collection](https://www.w3.org/TR/activitypub/#likes) -* Their listens (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against listening objects) +- Their favorites (represented as liked objects in their [likes collection][likes] +- Their listens (represented as [created activities][create-inbox] against listening objects) ### Favorite action -```mermaid +```{mermaid} sequenceDiagram par User->>Funkwhale API: Favorite content @@ -97,7 +91,7 @@ sequenceDiagram ### Listen action -```mermaid +```{mermaid} sequenceDiagram par User->>Funkwhale API: Listen @@ -108,13 +102,13 @@ sequenceDiagram ## Collection outbox -**Collection** actors publish the following to their [outbox](https://www.w3.org/TR/activitypub/#outbox): +**Collection** actors publish the following to their [outbox][outbox]: -* Addition of new content (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against content objects) -* Deletion of content (represented as [delete activities](https://www.w3.org/TR/activitypub/#delete-activity-inbox) against content objects) -* Changes to content details (represented as [update activities](https://www.w3.org/TR/activitypub/#update-activity-inbox) against content objects) +- Addition of new content (represented as [created activities][create-inbox] against content objects) +- Deletion of content (represented as [delete activities][delete-activity] against content objects) +- Changes to content details (represented as [update activities][update-activity] against content objects) -```mermaid +```{mermaid} sequenceDiagram User->>Collection: Add new content Collection->>Outbox: Create content object @@ -129,13 +123,13 @@ sequenceDiagram ## Channel outbox -**Channel** actors publish the following to their [outbox](https://www.w3.org/TR/activitypub/#outbox): +**Channel** actors publish the following to their [outbox][outbox]: -* Addition of new content (represented as [created actvities](https://www.w3.org/TR/activitypub/#create-activity-inbox) against content objects) -* Deletion of content (represented as [delete activities](https://www.w3.org/TR/activitypub/#delete-activity-inbox) against content objects) -* Changes to content details (represented as [update activities](https://www.w3.org/TR/activitypub/#update-activity-inbox) against content objects) +- Addition of new content (represented as [created actvities][create-inbox] against content objects) +- Deletion of content (represented as [delete activities][delete-activity] against content objects) +- Changes to content details (represented as [update activities][update-activity] against content objects) -```mermaid +```{mermaid} sequenceDiagram User->>Channel: Add new content Channel->>Outbox: Create content object @@ -148,4 +142,14 @@ sequenceDiagram Outbox->>Follower collection: Update content object ``` -###### tags: `specs` `in-progress` `activitypub` +[actor-object]: https://www.w3.org/TR/activitypub/#actor-objects +[inbox]: https://www.w3.org/TR/activitypub/#inbox +[outbox]: https://www.w3.org/TR/activitypub/#outbox +[collections]: https://www.w3.org/TR/activitypub/#collections +[followers-collection]: https://www.w3.org/TR/activitypub/#followers +[create-inbox]: https://www.w3.org/TR/activitypub/#create-activity-inbox +[likes]: https://www.w3.org/TR/activitypub/#likes +[delete-activity]: https://www.w3.org/TR/activitypub/#delete-activity-inbox +[update-activity]: https://www.w3.org/TR/activitypub/#update-activity-inbox +[accept-activity]: https://www.w3.org/TR/activitypub/#accept-activity-inbox +[follow-activity]: https://www.w3.org/TR/activitypub/#follow-activity-outbox From b4cae9c7b1eff53160dbbbab0f6d237007e7e331 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Tue, 12 Dec 2023 18:21:15 +0000 Subject: [PATCH 3/3] Add changelog fragment --- changes/changelog.d/ap-overview.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/changelog.d/ap-overview.doc diff --git a/changes/changelog.d/ap-overview.doc b/changes/changelog.d/ap-overview.doc new file mode 100644 index 000000000..a0d65561e --- /dev/null +++ b/changes/changelog.d/ap-overview.doc @@ -0,0 +1 @@ +Added basic ActivityPub overview