From eee2948c1b328b108f5ae3bdac6e559e17c8b5b7 Mon Sep 17 00:00:00 2001 From: Your Name Date: Fri, 29 Nov 2024 17:10:12 -0500 Subject: [PATCH] add doc for federation --- docs/features.md | 1 + docs/internals/catalog.md | 1 + docs/internals/federation.md | 120 +++++++++++++++++++++++++++++++++++ docs/sites.md | 25 ++++++++ 4 files changed, 147 insertions(+) create mode 100644 docs/sites.md diff --git a/docs/features.md b/docs/features.md index a8c5b548..d054e7cc 100644 --- a/docs/features.md +++ b/docs/features.md @@ -21,6 +21,7 @@ NeoDB has [various features](features.md), and you may image it as a mix of Mast - Bangumi - Board Game Geek - any RSS link to a podcast + - ...[full list](sites.md) ## Personal collections diff --git a/docs/internals/catalog.md b/docs/internals/catalog.md index 1c10a354..5d25a6c4 100644 --- a/docs/internals/catalog.md +++ b/docs/internals/catalog.md @@ -111,3 +111,4 @@ Add a new site - Command: `neodb-manage python3 manage.py test [--keepdb]`. - See [this issue](https://github.com/neodb-social/neodb/issues/5) if `lxml.etree.ParserError` occurs on macOS. - add a site UI label style to `common/static/scss/_sitelabel.scss` + - update documentation in [sites.md](../sites.md) diff --git a/docs/internals/federation.md b/docs/internals/federation.md index e69de29b..dd3205cc 100644 --- a/docs/internals/federation.md +++ b/docs/internals/federation.md @@ -0,0 +1,120 @@ +# Federation + +## ActivityPub + +NeoDB's ActivityPub implementation is based on [Takahē](https://jointakahe.org), with some change to enable interchange of additional information between NeoDB instances. + +### NodeInfo + +NeoDB instances can be identified from user agent string (`NeoDB/x.x (+https://example.org)`) and its nodeinfo, e.g. https://neodb.social/nodeinfo/2.0/ : +```json +{ + "version": "2.0", + "software": { + "name": "neodb", + "version": "0.10.4.13", + "repository": "https://github.com/neodb-social/neodb", + "homepage": "https://neodb.net/" + }, + "protocols": ["activitypub", "neodb"], +} +``` + + +### Activity + +NeoDB add additional fields to `Note` activity: + + - `relatedWith` is a list of NeoDB specific activities which are associated with this `Note`. For each activity, `id` and `href` are both unique links to that activity, `withRegardTo` links to the catalog item, `attributedTo` links to the user, `type` is one of: + - `Status`, its `status` can be one of: `complete`, `progress`, `wishlist` and `dropped` + - `Rating`, its `value` is rating grade (int, 1-10), `worst` is always 1, `best` is always 10 + - `Comment`, its `content` is comment text + - `Review`, its `name` is review title, `content` is its body, `mediaType` is always `text/markdown` for now + - `Note`, its `content` is note text + - `tag` is used to store list of NeoDB catalog items, which are related with this activity. `type` of NeoDB catalog item can be one of `Edition`, `Movie`, `TVShow`, `TVSeason`, `TVEpisode`, `Album`, `Game`, `Podcast`, `PodcastEpisode`, `Performance`, `PerformanceProduction`; href will be the link to that item. + +Example: +```json +{ + "@context": ["https://www.w3.org/ns/activitystreams", { + "blurhash": "toot:blurhash", + "Emoji": "toot:Emoji", + "focalPoint": { + "@container": "@list", + "@id": "toot:focalPoint" + }, + "Hashtag": "as:Hashtag", + "manuallyApprovesFollowers": "as:manuallyApprovesFollowers", + "sensitive": "as:sensitive", + "toot": "http://joinmastodon.org/ns#", + "votersCount": "toot:votersCount", + "featured": { + "@id": "toot:featured", + "@type": "@id" + } + }, "https://w3id.org/security/v1"], + "id": "https://neodb.social/@april_long_face@neodb.social/posts/380919151408919488/", + "type": "Note", + "relatedWith": [{ + "id": "https://neodb.social/p/5oyF0qRx96mKKmVpFzHtMM", + "type": "Status", + "status": "complete", + "withRegardTo": "https://neodb.social/movie/7hfF7d0aFMaqHpFjUpq4zR", + "attributedTo": "https://neodb.social/@april_long_face@neodb.social/", + "href": "https://neodb.social/p/5oyF0qRx96mKKmVpFzHtMM", + "published": "2024-11-17T10:16:42.745240+00:00", + "updated": "2024-11-17T10:16:42.750917+00:00" + }, { + "id": "https://neodb.social/p/47cJnbQTkbSSN2izLwQMjo", + "type": "Comment", + "withRegardTo": "https://neodb.social/movie/7hfF7d0aFMaqHpFjUpq4zR", + "attributedTo": "https://neodb.social/@april_long_face@neodb.social/", + "content": "Broadway cin\u00e9math\u00e8que, at least I laughed hard.", + "href": "https://neodb.social/p/47cJnbQTkbSSN2izLwQMjo", + "published": "2024-11-17T10:16:42.745240+00:00", + "updated": "2024-11-17T10:16:42.777276+00:00" + }, { + "id": "https://neodb.social/p/3AyYu974qo6OU09AAsPweQ", + "type": "Rating", + "best": 10, + "value": 7, + "withRegardTo": "https://neodb.social/movie/7hfF7d0aFMaqHpFjUpq4zR", + "worst": 1, + "attributedTo": "https://neodb.social/@april_long_face@neodb.social/", + "href": "https://neodb.social/p/3AyYu974qo6OU09AAsPweQ", + "published": "2024-11-17T10:16:42.784220+00:00", + "updated": "2024-11-17T10:16:42.786458+00:00" + }], + "attributedTo": "https://neodb.social/@april_long_face@neodb.social/", + "content": "

\u770b\u8fc7 \u963f\u8bfa\u62c9 \ud83c\udf15\ud83c\udf15\ud83c\udf15\ud83c\udf17\ud83c\udf11
Broadway cin\u00e9math\u00e8que, at least I laughed hard.

#\u6211\u770b\u6211\u542c\u6211\u8bfb

", + "published": "2024-11-17T10:16:42.745Z", + "sensitive": false, + "tag": [{ + "type": "Hashtag", + "href": "https://neodb.social/tags/\u6211\u770b\u6211\u542c\u6211\u8bfb/", + "name": "#\u6211\u770b\u6211\u542c\u6211\u8bfb" + }, { + "type": "Movie", + "href": "https://neodb.social/movie/7hfF7d0aFMaqHpFjUpq4zR", + "image": "https://neodb.social/m/item/doubanmovie/2024/09/13/a30bf2f3-4f79-43ef-b22f-58ebc3fd8aae.jpg", + "name": "Anora" + }], + "to": ["https://www.w3.org/ns/activitystreams#Public"], + "updated": "2024-11-17T10:16:42.750Z", + "url": "https://neodb.social/@april_long_face/posts/380919151408919488/" +} +``` + +This is not ideal but a practical manner to pass along additional information between NeoDB instances and other ActivityPub servers. We have some ideas for improvements, but are open to more suggestions. + + +### Relay + +NeoDB instances may share public rating and reviews with a default relay, which is currently `https://relay.neodb.net`. This relay is used to propagate public activities and catalog information between instances. + +Owner of instances may choose to turn this off in the admin settings. + + +## ATProto + +NeoDB is not a PDS itself currently, but can interact with PDS to import user's social graph, and send status updates. So technically NeoDB does not do full federation in ATProto, but NeoDB will handle some side effect from federation, e.g. when user logging in via ATProto handle, NeoDB will resolve user's DID and store it, and will attempt further operation with the DID, and update user's handle if that's changed. diff --git a/docs/sites.md b/docs/sites.md new file mode 100644 index 00000000..62517b0e --- /dev/null +++ b/docs/sites.md @@ -0,0 +1,25 @@ +# Supported Sites + +the following sites are supported + + +| | import link for media type | import archive | +| ----------------------| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| Apple Music | Music (Album) | | +| Bandcamp | Music (Album) | | +| Bangumi | Book (Edition)
Music (Album)
Movie
TV (Season)
Game | | +| Board Game Geek | Game | | +| BooksTW 博客來 | Book (Edition) | | +| Discogs | Music (Album) | | +| Douban 豆瓣 | Book (Edition, Work)
Music (Album)
Movie
TV (Show, Season, Episode)
Game
Performance (Performance, Production) | Yes, upload [doufen](https://doufen.org) archive | +| Goodreads | Book (Edition, Work) | Yes, submit shelf link | +| Google Books | Book (Edition) | | +| IGDB | Game | | +| IMDB | Movie
TV (Show, Episode) | | +| Letterboxd | not supported (link in archive is mapped to TMDB) | Yes, upload exported archive | +| Qidian 起点 | Book (Edition) | | +| Spotify | Music (Album) | | +| Steam | Game | | +| The Movie Database | Movie
TV (Show, Season, Episode) | | +| ypshuo 阅评说 | Book (Edition) | | +| RSS link to a podcast | Podcast | Yes, upload OPML |