From 51634cf6d405d4136a41c9d1ff0da07fe83da29a Mon Sep 17 00:00:00 2001 From: "kacaii.dev" Date: Thu, 16 Jul 2026 13:51:46 -0300 Subject: [PATCH] possum: steal diagrams from hayleigh >:) --- src/possum.gleam | 23 ++++++++++++++--------- src/possum/at_uri.gleam | 22 ++++++++++++---------- src/possum/did.gleam | 38 ++++++++++---------------------------- src/possum/nsid.gleam | 30 +++++++++++++----------------- 4 files changed, 49 insertions(+), 64 deletions(-) diff --git a/src/possum.gleam b/src/possum.gleam index d832ed4..e249dc5 100644 --- a/src/possum.gleam +++ b/src/possum.gleam @@ -8,6 +8,12 @@ //// general account management interfaces such as the OAuth login screen. //// PDSes actively sync their data repos with Relays. //// +//// ## Lexicon +//// +//// Lexicon is a schema language. It's used in the Atmosphere to describe data +//// records and HTTP APIs. It's very similar to JSON-Schema and OpenAPI. +//// Lexicon's sole purpose is to help developers build compatible software. +//// //// ## Record Keys //// //// A record key (sometimes shortened to "rkey") is used to name and reference an individual @@ -45,9 +51,9 @@ const com_atproto_server = "xrpc/com.atproto.server" /// Documentation: [xrpc/com.atproto.sync](https://endpoints.bsky.app/#bluesky-app/tag/comatprotosync) const com_atproto_sync = "xrpc/com.atproto.sync" -/// Get current PLC Data for the indicated DID, +/// Get current [PLC](https://web.plc.directory/) Data for the indicated DID, /// this returns information about a Decentralized Identifier (DID), -/// including their handle and service endpoint. +/// including their **handle** and **PDS endpoint**. /// /// PLC is a persistent global identifier system, stands for /// "Public Ledger of Credentials". @@ -55,7 +61,6 @@ const com_atproto_sync = "xrpc/com.atproto.sync" /// ## Examples /// /// ```gleam -/// import gleam/http/request /// import possum/did /// import possum /// @@ -63,7 +68,11 @@ const com_atproto_sync = "xrpc/com.atproto.sync" /// let request = possum.get_plc_data(did) /// /// // You can use this decoder to extract the server endpoint -/// let decoder = decode.at(["services", "atproto_pds", "endpoint"], decode.string) +/// let decoder = +/// decode.at( +/// ["services", "atproto_pds", "endpoint"], +/// decode.string +/// ) /// ``` /// /// ## Response @@ -88,10 +97,6 @@ const com_atproto_sync = "xrpc/com.atproto.sync" /// } /// } /// ``` -/// -/// Documentation: [DID PLC Directory](https://web.plc.directory/) -/// -/// See also: [did](possum/did.html), [did.parse](possum/did.html#parse) pub fn get_plc_data(did: did.Did) -> request.Request(String) { request.Request( method: http.Get, @@ -162,7 +167,7 @@ pub fn resolve_well_known_did(host host: String) -> request.Request(String) { /// /// Endpoint Docs: [/xrpc/com.atproto.identity.resolveHandle](https://endpoints.bsky.app/#bluesky-app/tag/comatprotoidentity/GET/xrpc/com.atproto.identity.resolveHandle) /// -/// See also: [did](possum/did.html), [did.parse](possum/did.html#parse) +/// See also: [Did](possum/did.html#Did), [handle.parse](possum/handle.html#parse) pub fn resolve_handle( handle: handle.Handle, pds host: String, diff --git a/src/possum/at_uri.gleam b/src/possum/at_uri.gleam index 52a43e3..604bedf 100644 --- a/src/possum/at_uri.gleam +++ b/src/possum/at_uri.gleam @@ -1,11 +1,3 @@ -//// The AT URI scheme (at://) makes it easy to reference individual records in -//// a specific repository, identified by either DID or handle. -//// -//// AT URIs are not content-addressed, so the contents of the record they -//// refer to may also change over time. -//// -//// Documentation: [AT URI Scheme](https://atproto.com/specs/at-uri-scheme) - import gleam/result import gleam/string import possum/did @@ -39,9 +31,19 @@ pub type Authority { Did(value: did.Did) } -/// A URI scheme for addressing atproto repository data. +/// The AT URI scheme (at://) makes it easy to reference individual records in +/// a specific repository, identified by either DID or handle. +/// +/// ``` +/// at://did:plc:vwzwgnygau7ed7b7wt5ux7y2/app.bsky.feed.post/3k5nobkf2w72g +/// └──────────────────────────────┘ └────────────────┘ └───────────┘ +/// authority colection rkey +/// ``` +/// +/// AT URIs are not content-addressed, so the contents of the record they +/// refer to may also change over time. /// -/// See also: [parse](#parse) +/// Documentation: [AT URI Scheme](https://atproto.com/specs/at-uri-scheme) pub opaque type AtUri { AtUri( /// Identifier, can be a DID or a Handle diff --git a/src/possum/did.gleam b/src/possum/did.gleam index dc29ee9..10eec96 100644 --- a/src/possum/did.gleam +++ b/src/possum/did.gleam @@ -1,14 +1,3 @@ -//// ## DID (Decentralized ID) -//// -//// DIDs, or Decentralized IDentifiers, are universally-unique identifiers which -//// represent data repos. They are permanent and non-human-readable. -//// DIDs are a W3C specification. The AT Protocol currently supports -//// did:web and did:plc, two different DID methods. -//// -//// DIDs resolve to documents which contain metadata about a repo, -//// including the address of the repo's PDS, the repo's handles, -//// and the public signing keys. - import gleam/dynamic/decode import gleam/regexp import gleam/result @@ -26,8 +15,14 @@ pub type ParseError { InvalidDidMethod(value: String) } -/// AT Protocol uses Decentralized Identifiers (DIDs) as persistent account -/// identifiers. An example DID is `did:plc:ewvi7nxzyoun6zhxrhs64oiz`. +/// AT Protocol uses Decentralized Identifiers (DIDs) universally-unique +/// identifiers which represent data repos. For example: +/// +/// ``` +/// did:plc:k5vecqzf4d5mdvkcu3mx6l5g +/// └─┘ └──────────────────────┘ +/// method identifier +/// ``` /// /// Documentation: [Decentralized Identifiers](https://atproto.com/specs/did) /// @@ -48,8 +43,6 @@ pub opaque type Did { /// /// assert method == did.Plc /// ``` -/// -/// See also: [Did](#Did) pub fn method(self: Did) -> Method { self.method } @@ -57,7 +50,7 @@ pub fn method(self: Did) -> Method { /// Return the DID identifier. /// /// This function **does not** convert the value into a valid DID format, -/// for that use `to_string`. +/// for that use [to_string](#to_string). /// /// ## Examples /// @@ -69,8 +62,6 @@ pub fn method(self: Did) -> Method { /// /// assert identifier == "k5vecqzf4d5mdvkcu3mx6l5g" /// ``` -/// -/// See also: [Did](#Did) pub fn indentifer(self: Did) -> String { self.identifier } @@ -112,18 +103,9 @@ pub fn decoder() -> decode.Decoder(Did) { /// Documentation: [Blessed DID Methods](https://atproto.com/specs/did#blessed-did-methods) pub type Method { /// Self-authenticating DID method developed specifically for use with atproto. - /// See the DID PLC [website](https://web.plc.directory/) for more details. Plc /// [W3C community](https://w3c-ccg.github.io/did-method-web/) draft based - /// on HTTPS (and DNS). The identifier section is a hostname. - /// This method is supported in atproto to provide an independent - /// alternative to `did:plc`. - /// - /// The special localhost hostname is allowed, but only in testing and development - /// environments. Port numbers (with separating colon hex-encoded) are only - /// allowed for localhost, and only in testing and development. - /// - /// Documentation: [did:web](https://atproto.com/specs/did#did-web-in-at-protocol) + /// on HTTPS (and DNS). The identifier section is a _hostname_. Web } diff --git a/src/possum/nsid.gleam b/src/possum/nsid.gleam index d4c53d2..e00a229 100644 --- a/src/possum/nsid.gleam +++ b/src/possum/nsid.gleam @@ -1,18 +1,3 @@ -//// Namespaced Identifiers (NSIDs) are used to reference Lexicon schemas for -//// records, XRPC endpoints, and more. For example, `com.atproto.sync.getRecord`. -//// -//// The basic structure and semantics of an NSID are a fully-qualified hostname -//// in reverse domain-name order, followed by an additional name segment. -//// The hostname part is the **domain authority**, and the final segment is the **name**. -//// -//// ## Lexicon -//// -//// Lexicon is a schema language. It's used in the Atmosphere to describe data -//// records and HTTP APIs. Functionally it's very similar to JSON-Schema and OpenAPI. -//// Lexicon's sole purpose is to help developers build compatible software. -//// -//// Documentation: [Namespaced Identifiers](https://atproto.com/specs/nsid) - import gleam/regexp import gleam/result @@ -26,9 +11,20 @@ pub type ParseError { InvalidSyntax(value: String) } -/// A specification for global semantic IDs. +/// Namespaced Identifiers (NSIDs) are used to reference Lexicon schemas for +/// records, endpoints, and more. For example: +/// +/// ``` +/// sh.tangled.repo.pull +/// └─────────────┘ └──┘ +/// authority name +/// ```` +/// +/// The basic structure of an NSID are a hostname in reverse domain-name order, +/// followed by an additional name segment. The hostname part is called the +/// **domain authority**, and the final segment is the **name**. /// -/// See also: [parse](#parse) +/// Documentation: [Namespaced Identifiers](https://atproto.com/specs/nsid) pub opaque type Nsid { Nsid(value: String) } -- 2.51.2