From d2c7173309d8e781914f6653e689fbdb1bff010c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Tue, 14 Nov 2023 13:59:55 +0000 Subject: [PATCH] feat(docs): add initial AP overview documentation --- changes/changelog.d/activitypub-overview.doc | 1 + docs/developer/ap-overview.md | 147 +++++++++++++++++++ docs/index.md | 1 + 3 files changed, 149 insertions(+) create mode 100644 changes/changelog.d/activitypub-overview.doc create mode 100644 docs/developer/ap-overview.md diff --git a/changes/changelog.d/activitypub-overview.doc b/changes/changelog.d/activitypub-overview.doc new file mode 100644 index 000000000..b53eb279a --- /dev/null +++ b/changes/changelog.d/activitypub-overview.doc @@ -0,0 +1 @@ +Add basic ActivityPub overview for Funkwhale. diff --git a/docs/developer/ap-overview.md b/docs/developer/ap-overview.md new file mode 100644 index 000000000..bac212a3f --- /dev/null +++ b/docs/developer/ap-overview.md @@ -0,0 +1,147 @@ +# 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 +``` diff --git a/docs/index.md b/docs/index.md index 1c1224a86..2ccc6cd98 100644 --- a/docs/index.md +++ b/docs/index.md @@ -72,6 +72,7 @@ hidden: true developer/index developer/architecture +developer/ap-overview developer/setup/index developer/contribute/index developer/workflows/index