Skip to content

Commit

Permalink
update ActvitityPub docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Floppy
Floppy committed Oct 21, 2024
1 parent 2653fbd commit 765fab8
Showing 1 changed file with 31 additions and 28 deletions.
59 changes: 31 additions & 28 deletions technology/activitypub.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,17 @@ 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!
{:.note}
Manyfold's ActivityPub implementation is still evolving, and this document may be inaccurate compared to the latest code, or may include sections that are not yet implemented.


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/).
Manyfold instances 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.
On top of the ActivityPub standard object types, we define an extension specifically for 3D content, and provide alternatives for use when communicating to instances that don't support it.

## NodeInfo

Manyfold will support the [NodeInfo](https://nodeinfo.diaspora.software/) standard for exposing server capabilities.
Manyfold supports 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.

Expand Down Expand Up @@ -44,50 +45,52 @@ Platforms such as Pixelfed and Bookwyrm use the `software` field to determine su

## Objects

### 3dModel
### 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).
`3DModel` is a custom ActivityStreams object type, parallel to the similar `Audio` and `Video` types, and consistent with the schema.org [3DModel](https://schema.org/3DModel) type.

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.
This object type corresponds 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).

#### Downgrading
The standard ActivityStreams activity types will be used in direct correspondence to events in Manyfold. A new `Model` will results in a `Create` activity, changes will result in `Update` activities, and so on.

Servers that do not support the `3dModel` object type (as determined using NodeInfo, above) will be sent a `Link` instead, containing the canonical URL of the model's web page, and the 3D preview will not be included.
If available, the `preview` property of the object includes 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.

### Actor
### Note

Our `Actor` objects are just as defined in the ActivityPub standard; they correspond to our signed-up users, and will use the `Person` type.
`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.

{:.note}
Note that Manyfold's internal`Creator` class is not the same thing; Manyfold can store creator metadata even when the creators do not have an 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.
Servers such as Mastodon that do not support the `3DModel` object type (potentially determined using NodeInfo, above) are sent a `Note` instead, containing a textual description of the event and the canonical URL of the model's web page; the 3D preview will not be included. A new `Note` is created for each event, whether creation, update, etc.

### Collection
## Actors

We will use the ActivityPub standard `Collection` object to share activities where users add `3dModel`s and `Actor`s to collections, if made public. This will operate using all the standard semantics.
Manyfold provides individual ActivityPub actors for the following:

### Note
|Manyfold class|ActvityPub actor type|Notes|
|-|-|-|
|User|`Person`||
|Creator|`Person`||
|Collection|`Group`||
|Model|`Service`|used instead of the more accurate `Document` for wider compatibility|

`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.
Any of these can be followed via ActivityPub *if they are publicly visible to logged-out users*.

## Activities

The following activities are supported on the object types shown in the table. In summary:

* Following is supported for users, individual models, and collections;
* Following is supported for users, creators, individual models, and collections;
* Standard microblog-interaction-type activities (create, like, boost) are supported for models and comments;
* Collection-oriented activities are supported for users, models, and other collections.

|Activity|Description|object|target|origin|
|-|-|-|-|-|
|`Create`|Actor has published a new model or comment|`3dModel`, `Note`|||
|`Update`|Actor has updated the object (including individual files, in the case of a model)|`3dModel`, `Note`|||
|`Delete`|Actor has deleted the object|`3dModel`, `Note`||
|`Announce`|Actor "boosts" the object into their own timeline|`3dModel`, `Note`|||
|`Like`|Actor has liked the object|`3dModel`, `Note`|||
|`Flag`|Actor has flagged the object for moderator attention|`3dModel`, `Note`|
|`Follow`|Actor has followed the object to get updates|`Actor`, `3dModel`, `Collection`|||
|`Add`|Actor has added the object to the target collection|`Actor`, `3dModel`, `Collection`|`Collection`||
|`Remove`|Actor has removed the object from the target collection|`Actor`, `3dModel`, `Collection`||`Collection`|
|`Create`|Actor has published a new model or comment|`3DModel`, `Note`|||
|`Update`|Actor has updated the object (including individual files, in the case of a model)|`3DModel`|||
|`Delete`|Actor has deleted the object|`3DModel`||
|`Flag`|Actor has flagged the object for moderator attention|`3DModel`, `Note`|
|`Follow`|Actor has followed the object to get updates|`Person`, `Group`, `Service`|||
|`Add`|Actor has added the object to the target collection|`3DModel`, `Group`|`Group`||
|`Remove`|Actor has removed the object from the target collection|`3DModel`, `Group`||`Group`|

## Technical implementation

Expand Down

0 comments on commit 765fab8

Please sign in to comment.