From 5068d0478ffc7c653e42cc2ab9cd60ce0ad6f2c0 Mon Sep 17 00:00:00 2001
From: Jesse Wierzbinski <contact@cpluspatch.com>
Date: Wed, 14 Aug 2024 15:43:36 +0200
Subject: [PATCH] feat: :memo: Document User and Server discovery

---
 app/federation/discovery/page.mdx | 78 +++++++++++++++++++++++++++++++
 app/page.tsx                      |  2 +-
 components/Navigation.tsx         |  1 +
 3 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 app/federation/discovery/page.mdx

diff --git a/app/federation/discovery/page.mdx b/app/federation/discovery/page.mdx
new file mode 100644
index 0000000..051278f
--- /dev/null
+++ b/app/federation/discovery/page.mdx
@@ -0,0 +1,78 @@
+export const metadata = {
+    title: 'Discovery',
+    description: "How Versia instances can discover users, capabilities, and endpoints.",
+}
+
+# Discovery
+
+A lot of the time, Versia instances may need to lookup information about other instances, such as their users, capabilities, and endpoints. This is done through a process called **discovery**.
+
+## User Discovery
+
+To discover a user, an instance must know [the user's address](/entities/user#addresses). Knowing this, the [WebFinger](https://tools.ietf.org/html/rfc7033) protocol can be used to find the user's profile.
+
+### Example
+
+To discover the profile of the user `@george@versia.social`, an instance would make a `GET` request to `https://versia.social/.well-known/webfinger?resource=acct:george@versia.social`.
+
+```http {{ 'title': 'Example Request' }}
+GET /.well-known/webfinger?resource=acct:george@versia.social HTTP/1.1
+Accept: application/jrd+json
+```
+
+```jsonc {{ 'title': 'Example Response' }}
+{
+    "subject": "acct:george@versia.social", // [!code focus:6]
+    "aliases": [
+        "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771",
+        "https://versia.social/@george"
+    ],
+    "links": [
+        {
+            "rel": "http://webfinger.net/rel/profile-page",
+            "type": "text/html",
+            "href": "https://versia.social/@george"
+        },
+        { // [!code focus:5]
+            "rel": "self",
+            "type": "application/json",
+            "href": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771"
+        },
+        {
+            "rel": "http://webfinger.net/rel/avatar",
+            "type": "image/png",
+            "href": "https://cdn.versia.social/uploads/banana.png"
+        }
+    ] // [!code focus]
+}
+```
+
+## Server Discovery
+
+Server metadata can be accessed by making a `GET` request to the server's Versia metadata endpoint, which is located at `/.well-known/versia`.
+
+### Example
+
+To discover the metadata of the server `versia.social`, an instance would make a `GET` request to `https://versia.social/.well-known/versia`.
+
+This endpoint will return a [ServerMetadata](/entities/server-metadata) entity.
+
+```http {{ 'title': 'Example Request' }}
+GET /.well-known/versia HTTP/1.1
+Accept: application/json
+```
+    
+```jsonc {{ 'title': 'Example Response' }}
+{
+    "type": "ServerMetadata",
+    "name": "Versia Social",
+    "uri": "https://versia.social",
+    "version": "3.2.0",
+    "supported_extensions": [
+        "org.lysand:reactions",
+        "org.lysand:polls",
+        "org.lysand:custom_emojis",
+        "org.lysand:is_cat"
+    ]
+}
+```
\ No newline at end of file
diff --git a/app/page.tsx b/app/page.tsx
index 4865d06..30061fb 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -72,7 +72,7 @@ const Page: FC = () => {
                     </h1>
                     <p className="mt-6 text-lg">
                         A simple, extensible federated protocol for building
-                        useful applications.
+                        useful applications. Formerly known as Lysand.
                     </p>
                 </div>
 
diff --git a/components/Navigation.tsx b/components/Navigation.tsx
index 046629b..f095e88 100644
--- a/components/Navigation.tsx
+++ b/components/Navigation.tsx
@@ -258,6 +258,7 @@ export const navigation: NavGroup[] = [
         links: [
             { title: "HTTP", href: "/federation/http" },
             { title: "Validation", href: "/federation/validation" },
+            { title: "Discovery", href: "/federation/discovery" },
         ],
     },
     {