From 7eac3d1e007e790692ab6f1ab463530c395eaf82 Mon Sep 17 00:00:00 2001 From: James Smith Date: Mon, 11 Mar 2024 14:37:24 +0000 Subject: [PATCH] add initial description of activitypub federation --- technology/activitypub.md | 86 +++++++++++++++++++++++++++++++++++++++ technology/index.md | 8 ++++ 2 files changed, 94 insertions(+) create mode 100644 technology/activitypub.md create mode 100644 technology/index.md diff --git a/technology/activitypub.md b/technology/activitypub.md new file mode 100644 index 0000000..80f950a --- /dev/null +++ b/technology/activitypub.md @@ -0,0 +1,86 @@ +--- +title: ActivityPub +parent: Technology +layout: page +nav_order: 1 +--- + +{:.important} +Manyfold does not yet include ActivityPub federation, or even multiuser support. This document is a proposal for comment, which explores how Manyfold instances _might_ interact with the Fediverse in future. Feedback is welcome; please comment on the [GitHub issue](https://github.com/manyfold3d/manyfold/issues/1389) with your thoughts! + +Manyfold instances should use the [ActivityPub](http://activitypub.rocks/) protocol to exchange user activity with other instances, and other ActivityPub services, such as [Mastodon](https://joinmastodon.org/). + +On top of the ActivityPub standard object types, we define an extension specifically for 3D content, and provide a mapping back to the standard for use when communicating to instances that don't support them. + +## NodeInfo + +Manyfold will support the [NodeInfo](https://nodeinfo.diaspora.software/) standard for exposing server capabilities. + +Support for extension types will be indicated in the `metadata` field of the nodeinfo response. Several metadata fields are [known](https://codeberg.org/thefederationinfo/nodeinfo_metadata_survey), but we define a new one specifically to indicate 3d model support. + +``` +{ + "version": "2.1", + "software": { + "name": "manyfold", + "version": "x.y.z" + }, + "protocols": [ + "activitypub" + ], + "usage": {...}, + "openRegistrations": true|false, + metadata: { + "ActivityPub:ObjectType:3dModel": "1.0" + } +} +``` + +Platforms such as Pixelfed and Bookwyrm use the `software` field to determine support for their custom types, but as we explicitly want to encourage other implementations, using `metadata` seems more sensible. We make this a version field rather than boolean, in case of future changes. + +## Objects + +### 3dModel + +`3dModel` is a custom ActivityStreams object type, corresponding to Manyfold's internal `Model` class. It extends the `Document` core object type, in the same way as `Audio` [in the core spec](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-audio). + +If available, the `preview` property of the object will include a URL for both an image and a 3d model file for direct loading by the client, with the appropriate MIME types. Of course, it's up to the client whether it chooses to display these. + +#### Supported activities + +|Activity|Description|Actor| +|-|-|-| +|Create|A new model has been published|model creator| +|Update|The model or its files have been changed|model creator| +|Delete|The model has been removed|model creator| +|Announce|A user "boosts" the model into their own timeline|other user| +|Follow|A user has followed the model to get updates|other user| +|Like|A user has liked the model|other user| + +Future expansion may include `Add` and `Remove` activities for collections. + +#### Downgrading + +Servers that do not support the `3dModel` object type will reject the `Activity`; in this case, the `3dModel` will be sent as a `Link` instead, containing the canonical URL of the model's web page, and the 3D preview will not be included. + +### Actor + +Our `Actor` objects are just as defined in the ActivityPub standard; they are mapped to our instance `User`s. + +{:.note} +Note that Manyfold's `Creator` class is not the same thing; Manyfold can store creator metadata even when the creators do not have a `User` account on the instance. Only activities from actual real users of an instance are federated; creators that are purely made for metadata purposes will not be exposed. + +### Collection + +We anticipate using the standard's `Collection` feature to support activities around users adding models to collections. This will operate using all the standard semantics. + +### Note + +`Note` is used to represent comments on a model; these could either be local to Manyfold, or remote on a different system such as Mastodon. A Manyfold `Note` will always be in reply to something, either a `3dModel` or another `Note`. They operate in accordance with the standard. + +## Technical implementation + +Manyfold's ActivityPub support will be built using the [federails](https://gitlab.com/experimentslabs/federails) Ruby gem. + +{:.info} +Many thanks to [Bookwyrm](https://docs.joinbookwyrm.com/activitypub.html) and [Pixelfed](https://docs.pixelfed.org/spec/ActivityPub.html) for their excellent ActivityPub implementation docs, which this page is heavily based on. diff --git a/technology/index.md b/technology/index.md new file mode 100644 index 0000000..d06a8df --- /dev/null +++ b/technology/index.md @@ -0,0 +1,8 @@ +--- +title: Technology +layout: page +nav_order: 3 +has_children: true +--- + +Technical documentation for developers