From b59b6b8ebbfd79c9cff297769fb605c4a4529bc8 Mon Sep 17 00:00:00 2001 From: Jesse Wierzbinski Date: Sun, 3 Nov 2024 12:19:21 +0100 Subject: [PATCH] refactor: :recycle: Add URI Collections and change all appropriate Collections to use them --- app/changelog/page.mdx | 2 + app/entities/group/page.mdx | 4 +- app/entities/user/page.mdx | 10 ++-- app/extensions/interaction-controls/page.mdx | 2 +- app/extensions/likes/page.mdx | 4 +- app/extensions/reactions/page.mdx | 2 +- app/federation/page.mdx | 2 +- app/structures/collection/page.mdx | 57 ++++++++++++++++++++ 8 files changed, 71 insertions(+), 12 deletions(-) diff --git a/app/changelog/page.mdx b/app/changelog/page.mdx index dde3e1e..746644d 100644 --- a/app/changelog/page.mdx +++ b/app/changelog/page.mdx @@ -22,6 +22,8 @@ This page lists changes since Working Draft 3. {{ className: 'lead' }} - In most cases, the two are interchangeable, but RFC 3339 is more strict. Most implementations should not need to change anything. - Add optional `$schema` field to [Entities](/entities). - Added [Interaction Controls Extensions](/extensions/interaction-controls) +- Added [URI Collections](/structures/collection#uri-collection) + - Changed all Collections that can contain remote entities to use URI Collections (eg. [User](/entities/user) `collections.followers`). ## Since WD 3 diff --git a/app/entities/group/page.mdx b/app/entities/group/page.mdx index ec9e4cc..7d19d25 100644 --- a/app/entities/group/page.mdx +++ b/app/entities/group/page.mdx @@ -25,10 +25,10 @@ Refer to [Note](/entities/note#entity-definition)'s `group` property for how not Text only (`text/plain`, `text/html`, etc). - URI of the group's members list. [Collection](/structures/collection) of [Users](/entities/user). + URI of the group's members list. [URI Collection](/structures/collection#uri-collection) of [Users](/entities/user). - URI of the group's associated notes. [Collection](/structures/collection) of [Notes](/entities/note). + URI of the group's associated notes. [URI Collection](/structures/collection#uri-collection) of [Notes](/entities/note). diff --git a/app/entities/user/page.mdx b/app/entities/user/page.mdx index f7a6ab8..bb4773d 100644 --- a/app/entities/user/page.mdx +++ b/app/entities/user/page.mdx @@ -114,19 +114,19 @@ Instance **must** be the host of the instance the user is on (hostname with opti } ``` - All URIs must resolve to a [Collection](/structures/collection) of the appropriate entities. Extensions may add additional collections. + All URIs must resolve to either a [Collection](/structures/collection) or a [URI Collection](/structures/collection#uri-collection) of the appropriate entities. Extensions may add additional collections. ### Outbox - The user's federation outbox. Refer to the [federation documentation](/federation). + The user's federation outbox. Refer to the [federation documentation](/federation). [Collection](/structures/collection) of [Note](/entities/note) entities. ### Followers - User's followers. [Collection](/structures/collection) of [User](/entities/user) entities. + User's followers. [URI Collection](/structures/collection#uri-collection) of [User](/entities/user) entities. ### Following - Users that the user follows. [Collection](/structures/collection) of [User](/entities/user) entities. + Users that the user follows. [URI Collection](/structures/collection#uri-collection) of [User](/entities/user) entities. ### Featured - [Notes](/entities/note) that the user wants to feature (also known as "pin") on their profile. [Collection](/structures/collection) of [Note](/entities/note) entities. + [Notes](/entities/note) that the user wants to feature (also known as "pin") on their profile. [Collection](/structures/collection) of [Note](/entities/note) entities. Only notes authored by the user can be featured. diff --git a/app/extensions/interaction-controls/page.mdx b/app/extensions/interaction-controls/page.mdx index 9ea730e..682a9c1 100644 --- a/app/extensions/interaction-controls/page.mdx +++ b/app/extensions/interaction-controls/page.mdx @@ -102,7 +102,7 @@ Extensions **may** choose to register their own interaction types (such as `pub. Implementations that find a user attempting to create an interaction they are not allowed to **MUST** return a `403 Forbidden` HTTP status code when processing the Note during federation. The Note **must** also be discarded. -It is important for implementations to backfill any related [Collections](/structures/collection) (e.g. user followers) in order to not incorrectly reject Notes based off of outdated data. +It is important for implementations to backfill any related [Collections](/structures/collection)/[URI Collections](/structures/collection#uri-collection) (e.g. user followers) in order to not incorrectly reject Notes based off of outdated data. To avoid server load from constant Collection refreshing, implementations **could** only refetch associated Collections when forbidden interactions are detected, then recalculate permissions again. diff --git a/app/extensions/likes/page.mdx b/app/extensions/likes/page.mdx index 6682831..20a36ff 100644 --- a/app/extensions/likes/page.mdx +++ b/app/extensions/likes/page.mdx @@ -92,8 +92,8 @@ To undo a like or dislike, a [Delete](/entities/delete) entity should be used. T The Likes extension adds the following collections to the [User](/entities/user) entity: -- `likes`: A [Collection](/structures/collection) of all the notes the user has liked. -- `dislikes`: A [Collection](/structures/collection) of all the notes the user has disliked. +- `likes`: A [URI Collection](/structures/collection#uri-collection) of all the notes the user has liked. +- `dislikes`: A [URI Collection](/structures/collection#uri-collection) of all the notes the user has disliked. ```jsonc { diff --git a/app/extensions/reactions/page.mdx b/app/extensions/reactions/page.mdx index 9d7b856..687c861 100644 --- a/app/extensions/reactions/page.mdx +++ b/app/extensions/reactions/page.mdx @@ -58,7 +58,7 @@ The Reactions Extension extends the [Note](/entities/note) entity with the follo - URI to a [Collection](/structures/collection) of the [Reactions](#entity-definition) attached to the note. + URI to a [URI Collection](/structures/collection#uri-collection) of the [Reactions](#entity-definition) attached to the note. diff --git a/app/federation/page.mdx b/app/federation/page.mdx index 6378dc7..9364a26 100644 --- a/app/federation/page.mdx +++ b/app/federation/page.mdx @@ -39,6 +39,6 @@ Shared inboxes are defined in the [Instance Metadata](/entities/instance-metadat ## Outboxes -In addition to inboxes, every user has an outbox (e.g., `/users/3/outbox`). The outbox is simply a collection of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox. +In addition to inboxes, every user has an outbox (e.g., `/users/3/outbox`). The outbox is simply a [Collection](/structures/collection) of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox. Outboxes are very useful for "backfilling" data when a new instance joins the network. By resolving the outboxes of all new users it encounters, a new instance can quickly catch up on all old messages. \ No newline at end of file diff --git a/app/structures/collection/page.mdx b/app/structures/collection/page.mdx index 12ee97f..9140a24 100644 --- a/app/structures/collection/page.mdx +++ b/app/structures/collection/page.mdx @@ -75,5 +75,62 @@ Pages should be limited to a reasonable number of entities, such as 20 or 80. } ``` + + + +## URI Collection + +URI Collections are identical to regular collections, but they contain only URIs instead of full entities. They are useful for cases when remote entities need to be included in a collection, as those are typically not stored in implementation databases. {{ className: 'lead' }} + + + + + + Author of the collection. Usually the user who owns the collection. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author). + + + URI to the first page of the collection. Query parameters are allowed. + + + URI to the last page of the collection. Query parameters are allowed. + + If the collection only has one page, this should be the same as `first`. + + + Total number of entities in the collection, across all pages. + + + URI to the next page of the collection. Query parameters are allowed. + + If there is no next page, this should be `null`. + + + URI to the previous page of the collection. Query parameters are allowed. + + If there is no previous page, this should be `null`. + + + Collection contents. Must be an array of URIs. + + + + + + + ```jsonc {{ 'title': 'Example URI Collection' }} + { + "author": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771", + "first": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=1", + "last": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=3", + "total": 46, + "next": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=2", + "previous": null, + "items": [ + "https://versia.social/users/f8b0d4b4-d354-4798-bbc5-c2ba8acabfe3", + "https://social.bob.com/u/2B27E62snga763" + ] + } + ``` + \ No newline at end of file