From bcdf0ec25113e78f0b942a58832c34f46acfcced Mon Sep 17 00:00:00 2001 From: Jesse Wierzbinski Date: Mon, 5 May 2025 14:33:22 +0200 Subject: [PATCH] refactor: :memo: Use References nomenclature instead of URI --- app/entities/delete/page.mdx | 8 ++--- app/entities/follow-accept/page.mdx | 8 ++--- app/entities/follow-reject/page.mdx | 8 ++--- app/entities/follow/page.mdx | 8 ++--- app/entities/note/page.mdx | 20 ++++++------ app/entities/unfollow/page.mdx | 8 ++--- app/extensions/groups/page.mdx | 40 ++++++++++++------------ app/extensions/likes/page.mdx | 16 +++++----- app/extensions/migration/page.mdx | 16 +++++----- app/extensions/polls/page.mdx | 8 ++--- app/extensions/reactions/page.mdx | 8 ++--- app/extensions/reports/page.mdx | 8 ++--- app/extensions/share/page.mdx | 8 ++--- app/extensions/vanity/page.mdx | 4 +-- app/structures/collection/page.mdx | 12 ++++---- app/types/page.mdx | 47 +++++++++++++++++++++++++++++ 16 files changed, 137 insertions(+), 90 deletions(-) diff --git a/app/entities/delete/page.mdx b/app/entities/delete/page.mdx index 773058b..0c69ef8 100644 --- a/app/entities/delete/page.mdx +++ b/app/entities/delete/page.mdx @@ -24,14 +24,14 @@ Having the authorization is defined as: - - URI of the `User` who is deleting the entity. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author). + + [Reference](/types#reference) to the `User` who is deleting the entity. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author). Type of the entity being deleted. - - URI of the entity being deleted. + + [Reference](/types#reference) to the entity being deleted. diff --git a/app/entities/follow-accept/page.mdx b/app/entities/follow-accept/page.mdx index a9d404b..1d0957d 100644 --- a/app/entities/follow-accept/page.mdx +++ b/app/entities/follow-accept/page.mdx @@ -18,11 +18,11 @@ export const metadata = { - - URI of the `User` considered the 'followee', i.e. the user who is being followed. + + [Reference](/types#reference) to the `User` considered the 'followee', i.e. the user who is being followed. - - URI of the `User` considered the 'follower', i.e. the user who is trying to follow the author. + + [Reference](/types#reference) to the `User` considered the 'follower', i.e. the user who is trying to follow the author. diff --git a/app/entities/follow-reject/page.mdx b/app/entities/follow-reject/page.mdx index db8d6df..5a0091d 100644 --- a/app/entities/follow-reject/page.mdx +++ b/app/entities/follow-reject/page.mdx @@ -28,11 +28,11 @@ But it can also be used when Bob is already following Alice, in the case that: - - URI of the `User` considered the 'followee', i.e. the user who is being followed. + + [Reference](/types#reference) to the `User` considered the 'followee', i.e. the user who is being followed. - - URI of the `User` considered the 'follower', i.e. the user who is trying to follow the author. + + [Reference](/types#reference) to the `User` considered the 'follower', i.e. the user who is trying to follow the author. diff --git a/app/entities/follow/page.mdx b/app/entities/follow/page.mdx index 6a188bb..0ddee2d 100644 --- a/app/entities/follow/page.mdx +++ b/app/entities/follow/page.mdx @@ -60,11 +60,11 @@ Once a follow relationship is established, the **followee**'s instance should se - - URI of the `User` considered the 'follower'. + + [Reference](/types#reference) to the `User` considered the 'follower'. - - URI of the `User` that is being followed. + + [Reference](/types#reference) to the `User` that is being followed. diff --git a/app/entities/note/page.mdx b/app/entities/note/page.mdx index 2a2e060..af7098a 100644 --- a/app/entities/note/page.mdx +++ b/app/entities/note/page.mdx @@ -19,8 +19,8 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ Media attachments to the note. May be any format. **Must** be remote. - - URI of the `User` considered the author of the note. + + [Reference](/types#reference) to the `User` considered the author of the note. Category of the note. Useful for clients to render notes differently depending on their intended purpose. @@ -50,8 +50,8 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ } ``` - - URI of a [Group](/extensions/groups) that the note is only visible in, or one of the following strings: + + [Reference](/types#reference) to a [Group](/extensions/groups) that the note is only visible in, or one of the following strings: - `public`: The note is visible to anyone. - `followers`: The note is visible only to the author's followers. @@ -64,8 +64,8 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ Whether the note contains "sensitive content". This can be used with `subject` as a "content warning" feature. - - URIs of [Users](/entities/user) that should be notified of the note. Similar to Twitter's `@` mentions. The note may also contain mentions in the content, however only the mentions in this field should trigger notifications. + + [References](/types#reference) to [Users](/entities/user) that should be notified of the note. Similar to Twitter's `@` mentions. The note may also contain mentions in the content, however only the mentions in this field should trigger notifications. Previews for any links in the publication. This is to avoid the [stampeding mastodon problem](https://github.com/mastodon/mastodon/issues/23662) where a link preview is fetched by every instance that sees the publication, creating an accidental DDOS attack. @@ -84,11 +84,11 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ Implementations should make sure not to trust the previews, as they could be faked by malicious remote instances. This is not a very good attack vector, but it is still possible to redirect users to malicious links. - - URI of the note that this note is quoting, if any. Quoting is similar to replying, but does not notify the author of the quoted note. Inspired by Twitter's "quote tweet" feature. + + [Reference](/types#reference) to the note that this note is quoting, if any. Quoting is similar to replying, but does not notify the author of the quoted note. Inspired by Twitter's "quote tweet" feature. - - URI of the note that this note is a reply to, if any. + + [Reference](/types#reference) to the note that this note is a reply to, if any. A subject for the note. Useful for clients to display a "content warning" or "spoiler" feature, such as on Mastodon. Must be a plaintext string (`text/plain`). diff --git a/app/entities/unfollow/page.mdx b/app/entities/unfollow/page.mdx index 3e1be6b..d033348 100644 --- a/app/entities/unfollow/page.mdx +++ b/app/entities/unfollow/page.mdx @@ -33,11 +33,11 @@ Sometimes, [Users](/entities/user) want to unsubscribe from each other to stop s - - URI of the `User` considered the 'follower', i.e. the user who is unsubscribing from the followee. + + [Reference](/types#reference) to the `User` considered the 'follower', i.e. the user who is unsubscribing from the followee. - - URI of the `User` considered the 'followee', i.e. the user who is being unsubscribed from. + + [Reference](/types#reference) to the `User` considered the 'followee', i.e. the user who is being unsubscribed from. diff --git a/app/extensions/groups/page.mdx b/app/extensions/groups/page.mdx index 4cf9e5b..54c710b 100644 --- a/app/extensions/groups/page.mdx +++ b/app/extensions/groups/page.mdx @@ -93,11 +93,11 @@ Indicates that a [User](/entities/user) wishes to subscribe to a group. Must be `pub.versia:groups/Subscribe`. - - URI of the [User](/entities/user) subscribing to the group. + + [Reference](/types#reference) to the [User](/entities/user) subscribing to the group. - - URI of the group to subscribe to. + + [Reference](/types#reference) to the group to subscribe to. @@ -131,11 +131,11 @@ Indicates that a [User](/entities/user) wishes to unsubscribe from a group. Must be `pub.versia:groups/Unsubscribe`. - - URI of the [User](/entities/user) unsubscribing from the group. + + [Reference](/types#reference) to the [User](/entities/user) unsubscribing from the group. - - URI of the group to unsubscribe from. + + [Reference](/types#reference) to the group to unsubscribe from. @@ -169,11 +169,11 @@ Indicates that a [Group](#entity-definition) has accepted a [User](/entities/use Must be `pub.versia:groups/SubscribeAccept`. - - URI of the [User](/entities/user) subscribing to the group. + + [Reference](/types#reference) to the [User](/entities/user) subscribing to the group. - - URI of the group that accepted the subscription. + + [Reference](/types#reference) to the group that accepted the subscription. @@ -207,11 +207,11 @@ Indicates that a [Group](#entity-definition) has rejected a [User](/entities/use Must be `pub.versia:groups/SubscribeReject`. - - URI of the [User](/entities/user) subscribing to the group. + + [Reference](/types#reference) to the [User](/entities/user) subscribing to the group. - - URI of the group that rejected the subscription. + + [Reference](/types#reference) to the group that rejected the subscription. @@ -253,11 +253,11 @@ The `GroupFederate` entity allows a group to federate a note to all of its membe Must be `pub.versia:groups/Federate`. - - URI of the note to federate. + + [Reference](/types#reference) to the note to federate. - - URI of the group federating the note. + + [Reference](/types#reference) to the group federating the note. diff --git a/app/extensions/likes/page.mdx b/app/extensions/likes/page.mdx index 4614aac..546aa30 100644 --- a/app/extensions/likes/page.mdx +++ b/app/extensions/likes/page.mdx @@ -22,11 +22,11 @@ Likes are a way for users to show appreciation for a note, like Twitter's "heart Must be `pub.versia:likes/Like`. - - Creator of the Like. + + [Reference](/types#reference) to the creator of the Like. - - URI of the note being liked. Must link to a [Note](/entities/note). + + [Reference](/types#reference) to the note being liked. @@ -58,11 +58,11 @@ Dislikes are a way for users to show disapproval for a note, like YouTube's "dis Must be `pub.versia:likes/Dislike`. - - Creator of the Dislike. + + [Reference](/types#reference) to the creator of the Dislike. - - URI of the note being disliked. Must link to a [Note](/entities/note). + + [Reference](/types#reference) to the note being disliked. diff --git a/app/extensions/migration/page.mdx b/app/extensions/migration/page.mdx index 47f6d5b..50cc11b 100644 --- a/app/extensions/migration/page.mdx +++ b/app/extensions/migration/page.mdx @@ -40,11 +40,11 @@ Migration happens in three steps: Must be `pub.versia:migration/Migration`. - - URI of the [User](/entities/user) who is migrating. + + [Reference](/types#reference) to the [User](/entities/user) who is migrating. - - URI of the destination [User](/entities/user) on the new instance. + + [Reference](/types#reference) to the destination [User](/entities/user) on the new instance. @@ -71,11 +71,11 @@ The following extensions to [User](/entities/user) are used by the migration ext - - If this user has migrated from another instance, this property **MUST** be set to the URI of the user on the previous instance. + + If this user has migrated from another instance, this property **MUST** be a [Reference](/types#reference) to the user on the previous instance. - - If this user has migrated to another instance, this property **MUST** be set to the URI of the user on the new instance. + + If this user has migrated to another instance, this property **MUST** be a [Reference](/types#reference) to the URI of the user on the new instance. diff --git a/app/extensions/polls/page.mdx b/app/extensions/polls/page.mdx index ae91bdf..f9e30dc 100644 --- a/app/extensions/polls/page.mdx +++ b/app/extensions/polls/page.mdx @@ -97,11 +97,11 @@ If a vote is cast to a poll that is closed, the vote should be rejected with a ` Must be `pub.versia:polls/Vote`. - - URI to the user who cast the vote. + + [Reference](/types#reference) of the user who cast the vote. - - URI to the poll that the user voted on. Must link to a [Note](/entities/note) with a valid poll. + + [Reference](/types#reference) to the note with poll that the user voted on. Index of the option that the user voted for. This should be a valid index into the `options` array of the poll. diff --git a/app/extensions/reactions/page.mdx b/app/extensions/reactions/page.mdx index 8691324..311a8ee 100644 --- a/app/extensions/reactions/page.mdx +++ b/app/extensions/reactions/page.mdx @@ -19,11 +19,11 @@ User reactions are (like every other entity) federated to all followers, and can Must be `pub.versia:reactions/Reaction`. - - URI of the [User](/entities/user) that is reacting. + + [Reference](/types#reference) to the [User](/entities/user) that is reacting. - - URI of the [Note](/entities/note) attached to the reaction. + + [Reference](/types#reference) to the [Note](/entities/note) attached to the reaction. Emoji content of reaction. May also be arbitrary text, or [Custom Emoji](/extensions/custom-emojis) if supported. diff --git a/app/extensions/reports/page.mdx b/app/extensions/reports/page.mdx index 6465730..ac4ed8c 100644 --- a/app/extensions/reports/page.mdx +++ b/app/extensions/reports/page.mdx @@ -21,11 +21,11 @@ When an instance receives a report, it *should* be reviewed by a moderator or ad Must be `pub.versia:reports/Report`. - - URI of the reporting [User](/entities/user). Optional if the report is anonymous. + + [Reference](/types#reference) to the reporting [User](/entities/user). Optional if the report is anonymous. - - URIs of the content being reported. + + [References](/types#reference) to the content being reported. Report tags. Should be concise and clear, such as `spam`, `harassment`, `misinformation`, etc. Used for categorization. diff --git a/app/extensions/share/page.mdx b/app/extensions/share/page.mdx index 9c80fad..02b862b 100644 --- a/app/extensions/share/page.mdx +++ b/app/extensions/share/page.mdx @@ -21,11 +21,11 @@ When a user shares a note, the note's original author **must** receive the entit Must be `pub.versia:share/Share`. - - Creator of the Share. + + [Reference](/types#reference) to the creator of the Share. - - URI of the note being shared. Must link to a [Note](/entities/note). + + [Reference](/types#reference) to the note being shared. diff --git a/app/extensions/vanity/page.mdx b/app/extensions/vanity/page.mdx index de6e6a9..626e3f1 100644 --- a/app/extensions/vanity/page.mdx +++ b/app/extensions/vanity/page.mdx @@ -72,8 +72,8 @@ All properties are optional. User's timezone. Should be a valid [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string. - - Versia profiles that should be considered aliases of this profile. + + [References](/types#reference) to Versia profiles that should be considered aliases (or "alt accounts") of this profile. diff --git a/app/structures/collection/page.mdx b/app/structures/collection/page.mdx index 6a8ac54..391c668 100644 --- a/app/structures/collection/page.mdx +++ b/app/structures/collection/page.mdx @@ -16,8 +16,8 @@ Collections are a way to represent paginated groups of entities. They are used e - - 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). + + [Reference](/types#reference) to the 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). Total number of entities in the collection, across all pages. @@ -64,14 +64,14 @@ URI Collections are identical to regular collections, but they contain only URIs - - 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). + + [Reference](/types#reference) to the 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). Total number of entities in the collection, across all pages. - - Collection contents. Must be an array of URIs. + + Collection contents. Must be an array of [References](/types#reference). diff --git a/app/types/page.mdx b/app/types/page.mdx index d35e6fa..ffe1230 100644 --- a/app/types/page.mdx +++ b/app/types/page.mdx @@ -1,3 +1,50 @@ +## Reference + +```typescript +type Hostname = string; +type Id = Entity["id"]; + +type Reference = `${Hostname}:${Id}` | `${Id}`; +``` + +A **reference** is a way to refer to any entity within the Versia network. It is a string composed of the following parts: + +- The entity's instance's hostname. Optional if that same instance is the creator of the entity. + - Punycode encoding is used for internationalized domain names (IDNs). + - Example: `example.com`, `example.com:3000`, `xn--ls8h.xn--ls8h`. +- A colon (`:`) separator, if the hostname is present. +- The entity's unique identifier. This is the `id` property of the entity. + + + If the hostname is an IPv6 address, it must be enclosed in square brackets. + + For example: `[2001:db8::1]:3000`. + + + +### Examples + +These two examples are equivalent if the instance is `example.com`: + +```jsonc +{ + "type": "Follow", + "id": "3e7e4750-afd4-4d99-a256-02f0710a0520", + "author": "6e0204a2-746c-4972-8602-c4f37fc63bbe", // [!code focus] + "created_at": "2021-01-01T00:00:00.000Z", + "followee": "test.org:02e1e3b2-cb1f-4e4a-b82e-98866bee5de7" +} +``` + +```jsonc +{ + "type": "Follow", + "id": "3e7e4750-afd4-4d99-a256-02f0710a0520", + "author": "example.com:6e0204a2-746c-4972-8602-c4f37fc63bbe", // [!code focus] + "created_at": "2021-01-01T00:00:00.000Z", + "followee": "test.org:02e1e3b2-cb1f-4e4a-b82e-98866bee5de7" +} +``` ## RFC3339