lint (pedantic)

Cargo.toml

···
 complexity = { level = "warn", priority = -1 }
 perf = { level = "warn", priority = -1 }
 style = { level = "warn", priority = -1 }
-# pedantic = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
 restriction = { level = "warn", priority = -1 }
 cargo = { level = "warn", priority = -1 }
 # Temporary Allows
-single_call_fn = "allow"
-multiple_crate_versions = "allow"
+multiple_crate_versions = "allow" # triggered by lib
 expect_used = "allow"
+missing_docs_in_private_items = "allow"
 # # Temporary Allows - Restriction
-min_ident_chars = "allow"
+min_ident_chars = "allow" # 50 instances
 # arbitrary_source_item_ordering = "allow"
-renamed_function_params = "allow"
+renamed_function_params = "allow" # possibly triggered by lib
 # pattern_type_mismatch = "allow"
 # Style Allows
 implicit_return = "allow"
···
 ref_patterns = "allow"
 question_mark_used = "allow"
 shadow_reuse = "allow"
+single_call_fn = "allow"
 # Warns
-missing_docs_in_private_items = "warn"
 use_self = "warn"
 str_to_string = "warn"
 print_stdout = "warn"

src/auth.rs

···
 /// If specified in an API endpoint, this will guarantee that the API can only be called
 /// by an authenticated user.
 pub(crate) struct AuthenticatedUser {
+    /// The DID of the authenticated user.
     did: String,
 }
 
···
                 auth.strip_prefix("Bearer ")
             });
 
-        let token = match token {
-            Some(tok) => tok,
-            None => {
-                return Err(Error::with_status(
-                    StatusCode::UNAUTHORIZED,
-                    anyhow!("no bearer token"),
-                ));
-            }
+        let Some(token) = token else {
+            return Err(Error::with_status(
+                StatusCode::UNAUTHORIZED,
+                anyhow!("no bearer token"),
+            ));
         };
 
         // N.B: We ignore all fields inside of the token up until this point because they can be
···
 pub(crate) fn sign(
     key: &Secp256k1Keypair,
     typ: &str,
-    claims: serde_json::Value,
+    claims: &serde_json::Value,
 ) -> anyhow::Result<String> {
     // RFC 9068
     let hdr = serde_json::json!({

src/config.rs

···
 //! Configuration structures for the PDS.
 /// The metrics configuration.
 pub(crate) mod metrics {
-    use super::*;
+    use super::{Deserialize, Url};
 
     #[derive(Deserialize, Debug, Clone)]
     /// The Prometheus configuration.

src/did.rs

···
                 bail!("forbidden URL {host}");
             }
 
-            format!("https://{}/.well-known/did.json", host)
+            format!("https://{host}/.well-known/did.json")
         }
         "did:plc" => {
             format!("https://plc.directory/{}", did.as_str())

src/endpoints/identity.rs

···
+//! Identity endpoints (/xrpc/com.atproto.identity.*)
 use std::collections::HashMap;
 
 use anyhow::{Context as _, anyhow};
···
     plc::{self, PlcOperation, PlcService},
 };
 
+/// (GET) Resolves an atproto handle (hostname) to a DID. Does not necessarily bi-directionally verify against the the DID document.
+/// ### Query Parameters
+/// - handle: The handle to resolve.
+/// ### Responses
+/// - 200 OK: {did: did}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `HandleNotFound`]}
+/// - 401 Unauthorized
 async fn resolve_handle(
     State(db): State<Db>,
     State(client): State<Client>,
···
 }
 
 #[expect(unused_variables, clippy::todo, reason = "Not yet implemented")]
+/// Request an email with a code to in order to request a signed PLC operation. Requires Auth.
+/// - POST /xrpc/com.atproto.identity.requestPlcOperationSignature
+/// ### Responses
+/// - 200 OK
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn request_plc_operation_signature(user: AuthenticatedUser) -> Result<()> {
     todo!()
 }
 
 #[expect(unused_variables, clippy::todo, reason = "Not yet implemented")]
+/// Signs a PLC operation to update some value(s) in the requesting DID's document.
+/// - POST /xrpc/com.atproto.identity.signPlcOperation
+/// ### Request Body
+/// - token: string // A token received through com.atproto.identity.requestPlcOperationSignature
+/// - rotationKeys: string[]
+/// - alsoKnownAs: string[]
+/// - verificationMethods: services
+/// ### Responses
+/// - 200 OK: {operation: string}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn sign_plc_operation(
     user: AuthenticatedUser,
     State(skey): State<SigningKey>,
···
     clippy::too_many_arguments,
     reason = "Many parameters are required for this endpoint"
 )]
+/// Updates the current account's handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.
+/// - POST /xrpc/com.atproto.identity.updateHandle
+/// ### Query Parameters
+/// - handle: handle // The new handle.
+/// ### Responses
+/// - 200 OK
+/// ## Errors
+/// - If the handle is already in use.
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
+/// ## Panics
+/// - If the handle is not valid.
 async fn update_handle(
     user: AuthenticatedUser,
     State(skey): State<SigningKey>,
···
             ),
         },
     )
-    .await
     .context("failed to sign plc op")?;
 
     if !config.test {
···
     let doc = tokio::fs::File::options()
         .read(true)
         .write(true)
-        .open(config.plc.path.join(format!("{}.car", did_hash)))
+        .open(config.plc.path.join(format!("{did_hash}.car")))
         .await
         .context("failed to open did doc")?;
 
···
 }
 
 #[rustfmt::skip]
+/// Identity endpoints (/xrpc/com.atproto.identity.*)
+/// ### Routes
+/// - AP /xrpc/com.atproto.identity.updateHandle                    -> [`update_handle`]
+/// - AP /xrpc/com.atproto.identity.requestPlcOperationSignature    -> [`request_plc_operation_signature`]
+/// - AP /xrpc/com.atproto.identity.signPlcOperation                -> [`sign_plc_operation`]
+/// - UG /xrpc/com.atproto.identity.resolveHandle                   -> [`resolve_handle`]
 pub(super) fn routes() -> Router<AppState> {
-    // AP /xrpc/com.atproto.identity.updateHandle
-    // AP /xrpc/com.atproto.identity.requestPlcOperationSignature
-    // AP /xrpc/com.atproto.identity.signPlcOperation
-    // UG /xrpc/com.atproto.identity.resolveHandle
     Router::new()
         .route(concat!("/", identity::update_handle::NSID),                   post(update_handle))
         .route(concat!("/", identity::request_plc_operation_signature::NSID), post(request_plc_operation_signature))

src/endpoints/repo.rs

···
+//! PDS repository endpoints /xrpc/com.atproto.repo.*)
 use std::{collections::HashSet, str::FromStr as _};
 
 use anyhow::{Context as _, anyhow};
···
 /// SHA2-256 mulithash
 const IPLD_MH_SHA2_256: u64 = 0x12;
 
+/// Used in [`scan_blobs`] to identify a blob.
 #[derive(Deserialize, Debug, Clone)]
 struct BlobRef {
+    /// `BlobRef` link. Include `$` when serializing to JSON, since `$` isn't allowed in struct names.
     #[serde(rename = "$link")]
     link: String,
 }
 
 #[derive(serde::Serialize, serde::Deserialize, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
+/// Parameters for [`list_records`].
 pub(super) struct ListRecordsParameters {
     ///The NSID of the record type.
     pub collection: Nsid,
+    /// The cursor to start from.
     #[serde(skip_serializing_if = "core::option::Option::is_none")]
     pub cursor: Option<String>,
     ///The number of records to return.
···
     }
 }
 
+/// Resolves DID to DID document. Does not bi-directionally verify handle.
+/// - GET /xrpc/com.atproto.repo.resolveDid
+/// ### Query Parameters
+/// - `did`: DID to resolve.
+/// ### Responses
+/// - 200 OK: {`did_doc`: `did_doc`}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `DidNotFound`, `DidDeactivated`]}
 async fn resolve_did(
     db: &Db,
     identifier: &AtIdentifier,
···
     Ok((did.to_owned(), handle.to_owned()))
 }
 
+/// Used in [`apply_writes`] to scan for blobs in the JSON object and return their CIDs.
 fn scan_blobs(unknown: &Unknown) -> anyhow::Result<Vec<Cid>> {
     // { "$type": "blob", "ref": { "$link": "bafyrei..." } }
 
···
     ];
     while let Some(value) = stack.pop() {
         match value {
-            serde_json::Value::Null => (),
-            serde_json::Value::Bool(_) => (),
-            serde_json::Value::Number(_) => (),
-            serde_json::Value::String(_) => (),
+            serde_json::Value::Bool(_)
+            | serde_json::Value::Null
+            | serde_json::Value::Number(_)
+            | serde_json::Value::String(_) => (),
             serde_json::Value::Array(values) => stack.extend(values.into_iter()),
             serde_json::Value::Object(map) => {
                 if let (Some(blob_type), Some(blob_ref)) = (map.get("$type"), map.get("ref")) {
···
         }
     });
 
-    let blob = scan_blobs(&json.try_into_unknown().unwrap()).unwrap();
+    let blob = scan_blobs(&json.try_into_unknown().expect("should be valid JSON"))
+        .expect("should be able to scan blobs");
     assert_eq!(
         blob,
-        vec![Cid::from_str("bafkreifzxf2wa6dyakzbdaxkz2wkvfrv3hiuafhxewbn5wahcw6eh3hzji").unwrap()]
+        vec![
+            Cid::from_str("bafkreifzxf2wa6dyakzbdaxkz2wkvfrv3hiuafhxewbn5wahcw6eh3hzji")
+                .expect("should be valid CID")
+        ]
     );
 }
 
-#[expect(clippy::large_stack_frames)]
+#[expect(clippy::too_many_lines)]
+/// Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.
+/// - POST /xrpc/com.atproto.repo.applyWrites
+/// ### Request Body
+/// - `repo`: `at-identifier` // The handle or DID of the repo (aka, current account).
+/// - `validate`: `boolean` // Can be set to 'false' to skip Lexicon schema validation of record data across all operations, 'true' to require it, or leave unset to validate only for known Lexicons.
+/// - `writes`: `object[]` // One of:
+/// - - com.atproto.repo.applyWrites.create
+/// - - com.atproto.repo.applyWrites.update
+/// - - com.atproto.repo.applyWrites.delete
+/// - `swap_commit`: `cid` // If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations.
 async fn apply_writes(
     user: AuthenticatedUser,
     State(skey): State<SigningKey>,
···
                     blobs.extend(
                         new_blobs
                             .into_iter()
-                            .map(|blob_cid| (key.to_owned(), blob_cid)),
+                            .map(|blob_cid| (key.clone(), blob_cid)),
                     );
                 }
 
···
                         blobs.extend(
                             new_blobs
                                 .into_iter()
-                                .map(|blod_cid| (key.to_owned(), blod_cid)),
+                                .map(|blod_cid| (key.clone(), blod_cid)),
                         );
                     }
                     ops.push(RepoOp::Create {
···
                         blobs.extend(
                             new_blobs
                                 .into_iter()
-                                .map(|blod_cid| (key.to_owned(), blod_cid)),
+                                .map(|blod_cid| (key.clone(), blod_cid)),
                         );
                     }
                     ops.push(RepoOp::Update {
···
                 .await
                 .context("failed to remove blob_ref")?;
             }
-            _ => {}
+            &RepoOp::Create { .. } => {}
         }
     }
 
-    // for (key, cid) in &blobs {
     for &mut (ref key, cid) in &mut blobs {
         let cid_str = cid.to_string();
 
···
     ))
 }
 
+/// Create a single new repository record. Requires auth, implemented by PDS.
+/// - POST /xrpc/com.atproto.repo.createRecord
+/// ### Request Body
+/// - `repo`: `at-identifier` // The handle or DID of the repo (aka, current account).
+/// - `collection`: `nsid` // The NSID of the record collection.
+/// - `rkey`: `string` // The record key. <= 512 characters.
+/// - `validate`: `boolean` // Can be set to 'false' to skip Lexicon schema validation of record data, 'true' to require it, or leave unset to validate only for known Lexicons.
+/// - `record`
+/// - `swap_commit`: `cid` // Compare and swap with the previous commit by CID.
+/// ### Responses
+/// - 200 OK: {`cid`: `cid`, `uri`: `at-uri`, `commit`: {`cid`: `cid`, `rev`: `tid`}, `validation_status`: [`valid`, `unknown`]}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `InvalidSwap`]}
+/// - 401 Unauthorized
 async fn create_record(
     user: AuthenticatedUser,
     State(skey): State<SigningKey>,
···
         State(fhp),
         Json(
             repo::apply_writes::InputData {
-                repo: input.repo.to_owned(),
-                validate: input.validate.to_owned(),
-                swap_commit: input.swap_commit.to_owned(),
+                repo: input.repo.clone(),
+                validate: input.validate,
+                swap_commit: input.swap_commit.clone(),
                 writes: vec![repo::apply_writes::InputWritesItem::Create(Box::new(
                     repo::apply_writes::CreateData {
-                        collection: input.collection.to_owned(),
-                        rkey: input.rkey.to_owned(),
-                        value: input.record.to_owned(),
+                        collection: input.collection.clone(),
+                        rkey: input.rkey.clone(),
+                        value: input.record.clone(),
                     }
                     .into(),
                 ))],
···
     let create_result = if let repo::apply_writes::OutputResultsItem::CreateResult(create_result) =
         write_result
             .results
-            .to_owned()
+            .clone()
             .and_then(|result| result.first().cloned())
             .context("unexpected output from apply_writes")?
     {
···
 
     Ok(Json(
         repo::create_record::OutputData {
-            cid: create_result.cid.to_owned(),
-            commit: write_result.commit.to_owned(),
-            uri: create_result.uri.to_owned(),
+            cid: create_result.cid.clone(),
+            commit: write_result.commit.clone(),
+            uri: create_result.uri.clone(),
             validation_status: Some("unknown".to_owned()),
         }
         .into(),
     ))
 }
 
+/// Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.
+/// - POST /xrpc/com.atproto.repo.putRecord
+/// ### Request Body
+/// - `repo`: `at-identifier` // The handle or DID of the repo (aka, current account).
+/// - `collection`: `nsid` // The NSID of the record collection.
+/// - `rkey`: `string` // The record key. <= 512 characters.
+/// - `validate`: `boolean` // Can be set to 'false' to skip Lexicon schema validation of record data, 'true' to require it, or leave unset to validate only for known Lexicons.
+/// - `record`
+/// - `swap_record`: `boolean` // Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation
+/// - `swap_commit`: `cid` // Compare and swap with the previous commit by CID.
+/// ### Responses
+/// - 200 OK: {"uri": "string","cid": "string","commit": {"cid": "string","rev": "string"},"validationStatus": "valid | unknown"}
+/// - 400 Bad Request: {error:"`InvalidRequest` | `ExpiredToken` | `InvalidToken` | `InvalidSwap`"}
+/// - 401 Unauthorized
 async fn put_record(
     user: AuthenticatedUser,
     State(skey): State<SigningKey>,
···
         State(fhp),
         Json(
             repo::apply_writes::InputData {
-                repo: input.repo.to_owned(),
+                repo: input.repo.clone(),
                 validate: input.validate,
-                swap_commit: input.swap_commit.to_owned(),
+                swap_commit: input.swap_commit.clone(),
                 writes: vec![repo::apply_writes::InputWritesItem::Update(Box::new(
                     repo::apply_writes::UpdateData {
-                        collection: input.collection.to_owned(),
-                        rkey: input.rkey.to_owned(),
-                        value: input.record.to_owned(),
+                        collection: input.collection.clone(),
+                        rkey: input.rkey.clone(),
+                        value: input.record.clone(),
                     }
                     .into(),
                 ))],
···
 
     let update_result = write_result
         .results
-        .to_owned()
+        .clone()
         .and_then(|result| result.first().cloned())
         .context("unexpected output from apply_writes")?;
     let (cid, uri) = match update_result {
         repo::apply_writes::OutputResultsItem::CreateResult(create_result) => (
-            Some(create_result.cid.to_owned()),
-            Some(create_result.uri.to_owned()),
+            Some(create_result.cid.clone()),
+            Some(create_result.uri.clone()),
         ),
         repo::apply_writes::OutputResultsItem::UpdateResult(update_result) => (
-            Some(update_result.cid.to_owned()),
-            Some(update_result.uri.to_owned()),
+            Some(update_result.cid.clone()),
+            Some(update_result.uri.clone()),
         ),
-        _ => (None, None),
+        repo::apply_writes::OutputResultsItem::DeleteResult(_) => (None, None),
     };
     Ok(Json(
         repo::put_record::OutputData {
             cid: cid.context("missing cid")?,
-            commit: write_result.commit.to_owned(),
+            commit: write_result.commit.clone(),
             uri: uri.context("missing uri")?,
             validation_status: Some("unknown".to_owned()),
         }
···
     ))
 }
 
+/// Delete a repository record, or ensure it doesn't exist. Requires auth, implemented by PDS.
+/// - POST /xrpc/com.atproto.repo.deleteRecord
+/// ### Request Body
+/// - `repo`: `at-identifier` // The handle or DID of the repo (aka, current account).
+/// - `collection`: `nsid` // The NSID of the record collection.
+/// - `rkey`: `string` // The record key. <= 512 characters.
+/// - `swap_record`: `boolean` // Compare and swap with the previous record by CID.
+/// - `swap_commit`: `cid` // Compare and swap with the previous commit by CID.
+/// ### Responses
+/// - 200 OK: {"commit": {"cid": "string","rev": "string"}}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `InvalidSwap`]}
+/// - 401 Unauthorized
 async fn delete_record(
     user: AuthenticatedUser,
     State(skey): State<SigningKey>,
···
                 State(fhp),
                 Json(
                     repo::apply_writes::InputData {
-                        repo: input.repo.to_owned(),
-                        swap_commit: input.swap_commit.to_owned(),
+                        repo: input.repo.clone(),
+                        swap_commit: input.swap_commit.clone(),
                         validate: None,
                         writes: vec![repo::apply_writes::InputWritesItem::Delete(Box::new(
                             repo::apply_writes::DeleteData {
-                                collection: input.collection.to_owned(),
-                                rkey: input.rkey.to_owned(),
+                                collection: input.collection.clone(),
+                                rkey: input.rkey.clone(),
                             }
                             .into(),
                         ))],
···
             .await
             .context("failed to apply writes")?
             .commit
-            .to_owned(),
+            .clone(),
         }
         .into(),
     ))
 }
 
+/// Get information about an account and repository, including the list of collections. Does not require auth.
+/// - GET /xrpc/com.atproto.repo.describeRepo
+/// ### Query Parameters
+/// - `repo`: `at-identifier` // The handle or DID of the repo.
+/// ### Responses
+/// - 200 OK: {"handle": "string","did": "string","didDoc": {},"collections": [string],"handleIsCorrect": true} \
+///   handeIsCorrect - boolean - Indicates if handle is currently valid (resolves bi-directionally)
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn describe_repo(
     State(config): State<AppConfig>,
     State(db): State<Db>,
···
     ))
 }
 
+/// Get a single record from a repository. Does not require auth.
+/// - GET /xrpc/com.atproto.repo.getRecord
+/// ### Query Parameters
+/// - `repo`: `at-identifier` // The handle or DID of the repo.
+/// - `collection`: `nsid` // The NSID of the record collection.
+/// - `rkey`: `string` // The record key. <= 512 characters.
+/// - `cid`: `cid` // The CID of the version of the record. If not specified, then return the most recent version.
+/// ### Responses
+/// - 200 OK: {"uri": "string","cid": "string","value": {}}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `RecordNotFound`]}
+/// - 401 Unauthorized
 async fn get_record(
     State(config): State<AppConfig>,
     State(db): State<Db>,
···
             Err(Error::with_message(
                 StatusCode::BAD_REQUEST,
                 anyhow!("could not find the requested record at {}", uri),
-                ErrorMessage::new(
-                    "RecordNotFound",
-                    format!("Could not locate record: {}", uri),
-                ),
+                ErrorMessage::new("RecordNotFound", format!("Could not locate record: {uri}")),
             ))
         },
         |record_value| {
             Ok(Json(
                 repo::get_record::OutputData {
                     cid: cid.map(atrium_api::types::string::Cid::new),
-                    uri: uri.to_owned(),
+                    uri: uri.clone(),
                     value: record_value
                         .try_into_unknown()
                         .context("should be valid JSON")?,
···
     )
 }
 
+/// List a range of records in a repository, matching a specific collection. Does not require auth.
+/// - GET /xrpc/com.atproto.repo.listRecords
+/// ### Query Parameters
+/// - `repo`: `at-identifier` // The handle or DID of the repo.
+/// - `collection`: `nsid` // The NSID of the record type.
+/// - `limit`: `integer` // The maximum number of records to return. Default 50, >=1 and <=100.
+/// - `cursor`: `string`
+/// - `reverse`: `boolean` // Flag to reverse the order of the returned records.
+/// ### Responses
+/// - 200 OK: {"cursor": "string","records": [{"uri": "string","cid": "string","value": {}}]}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn list_records(
     State(config): State<AppConfig>,
     State(db): State<Db>,
···
                 value: value.try_into_unknown().context("should be valid JSON")?,
             }
             .into(),
-        )
+        );
     }
 
     #[expect(clippy::pattern_type_mismatch)]
···
     ))
 }
 
+/// Upload a new blob, to be referenced from a repository record. \
+/// The blob will be deleted if it is not referenced within a time window (eg, minutes). \
+/// Blob restrictions (mimetype, size, etc) are enforced when the reference is created. \
+/// Requires auth, implemented by PDS.
+/// - POST /xrpc/com.atproto.repo.uploadBlob
+/// ### Request Body
+/// ### Responses
+/// - 200 OK: {"blob": "binary"}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn upload_blob(
     user: AuthenticatedUser,
     State(config): State<AppConfig>,
···
 
     let cid_str = cid.to_string();
 
-    tokio::fs::rename(
-        &filename,
-        config.blob.path.join(format!("{}.blob", cid_str)),
-    )
-    .await
-    .context("failed to finalize blob")?;
+    tokio::fs::rename(&filename, config.blob.path.join(format!("{cid_str}.blob")))
+        .await
+        .context("failed to finalize blob")?;
 
     let did_str = user.did();
 
···
     ))
 }
 
-#[rustfmt::skip]
+/// These endpoints are part of the atproto PDS repository management APIs. \
+/// Requests usually require authentication (unlike the com.atproto.sync.* endpoints), and are made directly to the user's own PDS instance.
+/// ### Routes
+/// - AP /xrpc/com.atproto.repo.applyWrites     -> [`apply_writes`]
+/// - AP /xrpc/com.atproto.repo.createRecord    -> [`create_record`]
+/// - AP /xrpc/com.atproto.repo.putRecord       -> [`put_record`]
+/// - AP /xrpc/com.atproto.repo.deleteRecord    -> [`delete_record`]
+/// - AP /xrpc/com.atproto.repo.uploadBlob      -> [`upload_blob`]
+/// - UG /xrpc/com.atproto.repo.describeRepo    -> [`describe_repo`]
+/// - UG /xrpc/com.atproto.repo.getRecord       -> [`get_record`]
+/// - UG /xrpc/com.atproto.repo.listRecords     -> [`list_records`]
 pub(super) fn routes() -> Router<AppState> {
-    // AP /xrpc/com.atproto.repo.applyWrites
-    // AP /xrpc/com.atproto.repo.createRecord
-    // AP /xrpc/com.atproto.repo.putRecord
-    // AP /xrpc/com.atproto.repo.deleteRecord
-    // AP /xrpc/com.atproto.repo.uploadBlob
-    // UG /xrpc/com.atproto.repo.describeRepo
-    // UG /xrpc/com.atproto.repo.getRecord
-    // UG /xrpc/com.atproto.repo.listRecords
     Router::new()
-        .route(concat!("/", repo::apply_writes::NSID),  post(apply_writes))
+        .route(concat!("/", repo::apply_writes::NSID), post(apply_writes))
         .route(concat!("/", repo::create_record::NSID), post(create_record))
-        .route(concat!("/", repo::put_record::NSID),    post(put_record))
+        .route(concat!("/", repo::put_record::NSID), post(put_record))
         .route(concat!("/", repo::delete_record::NSID), post(delete_record))
-        .route(concat!("/", repo::upload_blob::NSID),   post(upload_blob))
+        .route(concat!("/", repo::upload_blob::NSID), post(upload_blob))
         .route(concat!("/", repo::describe_repo::NSID), get(describe_repo))
-        .route(concat!("/", repo::get_record::NSID),    get(get_record))
-        .route(concat!("/", repo::list_records::NSID),  get(list_records))
+        .route(concat!("/", repo::get_record::NSID), get(get_record))
+        .route(concat!("/", repo::list_records::NSID), get(list_records))
 }

src/endpoints/server.rs

···
+//! Server endpoints. (/xrpc/com.atproto.server.*)
 use std::{collections::HashMap, str::FromStr as _};
 
 use anyhow::{Context as _, anyhow};
···
 /// This is a dummy password that can be used in absence of a real password.
 const DUMMY_PASSWORD: &str = "$argon2id$v=19$m=19456,t=2,p=1$En2LAfHjeO0SZD5IUU1Abg$RpS8nHhhqY4qco2uyd41p9Y/1C+Lvi214MAWukzKQMI";
 
+/// Create an invite code.
+/// - POST /xrpc/com.atproto.server.createInviteCode
+/// ### Request Body
+/// - `useCount`: integer
+/// - `forAccount`: string (optional)
+/// ### Responses
+/// - 200 OK: {code: string}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn create_invite_code(
     _user: AuthenticatedUser,
     State(db): State<Db>,
···
     ))
 }
 
+#[expect(clippy::too_many_lines, reason = "TODO: refactor")]
+/// Create an account. Implemented by PDS.
+/// - POST /xrpc/com.atproto.server.createAccount
+/// ### Request Body
+/// - `email`: string
+/// - `handle`: string (required)
+/// - `did`: string - Pre-existing atproto DID, being imported to a new account.
+/// - `inviteCode`: string
+/// - `verificationCode`: string
+/// - `verificationPhone`: string
+/// - `password`: string - Initial account password. May need to meet instance-specific password strength requirements.
+/// - `recoveryKey`: string - DID PLC rotation key (aka, recovery key) to be included in PLC creation operation.
+/// - `plcOp`: object
+/// ## Responses
+/// - 200 OK: {"accessJwt": "string","refreshJwt": "string","handle": "string","did": "string","didDoc": {}}
+/// - 400 Bad Request: {error: [`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `InvalidHandle`, `InvalidPassword`, \
+///   `InvalidInviteCode`, `HandleNotAvailable`, `UnsupportedDomain`, `UnresolvableDid`, `IncompatibleDidDoc`)}
+/// - 401 Unauthorized
 async fn create_account(
     State(db): State<Db>,
     State(skey): State<SigningKey>,
···
             prev: None,
         },
     )
-    .await
     .context("failed to sign genesis op")?;
     let op_bytes = serde_ipld_dagcbor::to_vec(&op).context("failed to encode genesis op")?;
 
···
         #[expect(clippy::string_slice, reason = "digest length confirmed")]
         digest[..24].to_owned()
     };
-    let did = format!("did:plc:{}", did_hash);
+    let did = format!("did:plc:{did_hash}");
 
-    let doc = tokio::fs::File::create(config.plc.path.join(format!("{}.car", did_hash)))
+    let doc = tokio::fs::File::create(config.plc.path.join(format!("{did_hash}.car")))
         .await
         .context("failed to create did doc")?;
 
···
     // Write out an initial commit for the user.
     // https://atproto.com/guides/account-lifecycle
     let (cid, rev, store) = async {
-        let file = tokio::fs::File::create_new(config.repo.path.join(format!("{}.car", did_hash)))
+        let file = tokio::fs::File::create_new(config.repo.path.join(format!("{did_hash}.car")))
             .await
             .context("failed to create repo file")?;
         let mut store = CarStore::create(file)
···
     let token = auth::sign(
         &skey,
         "at+jwt",
-        serde_json::json!({
+        &serde_json::json!({
             "scope": "com.atproto.access",
             "sub": did,
             "iat": chrono::Utc::now().timestamp(),
···
     let refresh_token = auth::sign(
         &skey,
         "refresh+jwt",
-        serde_json::json!({
+        &serde_json::json!({
             "scope": "com.atproto.refresh",
             "sub": did,
             "iat": chrono::Utc::now().timestamp(),
···
     ))
 }
 
+/// Create an authentication session.
+/// - POST /xrpc/com.atproto.server.createSession
+/// ### Request Body
+/// - `identifier`: string - Handle or other identifier supported by the server for the authenticating user.
+/// - `password`: string - Password for the authenticating user.
+/// - `authFactorToken` - string (optional)
+/// - `allowTakedown` - boolean (optional) - When true, instead of throwing error for takendown accounts, a valid response with a narrow scoped token will be returned
+/// ### Responses
+/// - 200 OK: {"accessJwt": "string","refreshJwt": "string","handle": "string","did": "string","didDoc": {},"email": "string","emailConfirmed": true,"emailAuthFactor": true,"active": true,"status": "takendown"}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `AccountTakedown`, `AuthFactorTokenRequired`]}
+/// - 401 Unauthorized
 async fn create_session(
     State(db): State<Db>,
     State(skey): State<SigningKey>,
···
     // TODO: `input.allow_takedown`
     // TODO: `input.auth_factor_token`
 
-    let account = if let Some(account) = sqlx::query!(
+    let Some(account) = sqlx::query!(
         r#"
-        WITH LatestHandles AS (
-            SELECT did, handle
-            FROM handles
-            WHERE (did, created_at) IN (
-                SELECT did, MAX(created_at) AS max_created_at
-                FROM handles
-                GROUP BY did
-            )
-        )
-        SELECT a.did, a.password, h.handle
-        FROM accounts a
-        LEFT JOIN LatestHandles h ON a.did = h.did
-        WHERE h.handle = ?
-        "#,
+         WITH LatestHandles AS (
+             SELECT did, handle
+             FROM handles
+             WHERE (did, created_at) IN (
+                 SELECT did, MAX(created_at) AS max_created_at
+                 FROM handles
+                 GROUP BY did
+             )
+         )
+         SELECT a.did, a.password, h.handle
+         FROM accounts a
+         LEFT JOIN LatestHandles h ON a.did = h.did
+         WHERE h.handle = ?
+         "#,
         handle
     )
     .fetch_optional(&db)
     .await
     .context("failed to authenticate")?
-    {
-        account
-    } else {
+    else {
         counter!(AUTH_FAILED).increment(1);
 
         // SEC: Call argon2's `verify_password` to simulate password verification and discard the result.
···
         password.as_bytes(),
         &PasswordHash::new(account.password.as_str()).context("invalid password hash in db")?,
     ) {
-        Ok(_) => {}
+        Ok(()) => {}
         Err(_e) => {
             counter!(AUTH_FAILED).increment(1);
 
···
     let token = auth::sign(
         &skey,
         "at+jwt",
-        serde_json::json!({
+        &serde_json::json!({
             "scope": "com.atproto.access",
             "sub": did,
             "iat": chrono::Utc::now().timestamp(),
···
     let refresh_token = auth::sign(
         &skey,
         "refresh+jwt",
-        serde_json::json!({
+        &serde_json::json!({
             "scope": "com.atproto.refresh",
             "sub": did,
             "iat": chrono::Utc::now().timestamp(),
···
     ))
 }
 
+/// Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt').
+/// - POST /xrpc/com.atproto.server.refreshSession
+/// ### Responses
+/// - 200 OK: {"accessJwt": "string","refreshJwt": "string","handle": "string","did": "string","didDoc": {},"active": true,"status": "takendown"}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `AccountTakedown`]}
+/// - 401 Unauthorized
 async fn refresh_session(
     State(db): State<Db>,
     State(skey): State<SigningKey>,
···
     }
     if claims
         .get("exp")
-        .and_then(|exp| exp.as_i64())
+        .and_then(serde_json::Value::as_i64)
         .context("failed to get `exp`")?
         < chrono::Utc::now().timestamp()
     {
···
     let token = auth::sign(
         &skey,
         "at+jwt",
-        serde_json::json!({
+        &serde_json::json!({
             "scope": "com.atproto.access",
             "sub": did,
             "iat": chrono::Utc::now().timestamp(),
···
     let refresh_token = auth::sign(
         &skey,
         "refresh+jwt",
-        serde_json::json!({
+        &serde_json::json!({
             "scope": "com.atproto.refresh",
             "sub": did,
             "iat": chrono::Utc::now().timestamp(),
···
     ))
 }
 
+/// Get a signed token on behalf of the requesting DID for the requested service.
+/// - GET /xrpc/com.atproto.server.getServiceAuth
+/// ### Request Query Parameters
+/// - `aud`: string - The DID of the service that the token will be used to authenticate with
+/// - `exp`: integer (optional) - The time in Unix Epoch seconds that the JWT expires. Defaults to 60 seconds in the future. The service may enforce certain time bounds on tokens depending on the requested scope.
+/// - `lxm`: string (optional) - Lexicon (XRPC) method to bind the requested token to
+/// ### Responses
+/// - 200 OK: {token: string}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `BadExpiration`]}
+/// - 401 Unauthorized
 async fn get_service_auth(
     user: AuthenticatedUser,
     State(skey): State<SigningKey>,
···
     }
 
     // Mint a bearer token by signing a JSON web token.
-    let token = auth::sign(&skey, "JWT", claims).context("failed to sign jwt")?;
+    let token = auth::sign(&skey, "JWT", &claims).context("failed to sign jwt")?;
 
     Ok(Json(server::get_service_auth::OutputData { token }.into()))
 }
 
+/// Get information about the current auth session. Requires auth.
+/// - GET /xrpc/com.atproto.server.getSession
+/// ### Responses
+/// - 200 OK: {"handle": "string","did": "string","email": "string","emailConfirmed": true,"emailAuthFactor": true,"didDoc": {},"active": true,"status": "takendown"}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn get_session(
     user: AuthenticatedUser,
     State(db): State<Db>,
···
     }
 }
 
+/// Describes the server's account creation requirements and capabilities. Implemented by PDS.
+/// - GET /xrpc/com.atproto.server.describeServer
+/// ### Responses
+/// - 200 OK: {"inviteCodeRequired": true,"phoneVerificationRequired": true,"availableUserDomains": [`string`],"links": {"privacyPolicy": "string","termsOfService": "string"},"contact": {"email": "string"},"did": "string"}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn describe_server(
     State(config): State<AppConfig>,
 ) -> Result<Json<server::describe_server::Output>> {
···
 }
 
 #[rustfmt::skip]
+/// These endpoints are part of the atproto PDS server and account management APIs. \
+/// Requests often require authentication and are made directly to the user's own PDS instance.
+/// ### Routes
+/// - `GET /xrpc/com.atproto.server.describeServer` -> [`describe_server`]
+/// - `POST /xrpc/com.atproto.server.createAccount` -> [`create_account`]
+/// - `POST /xrpc/com.atproto.server.createSession` -> [`create_session`]
+/// - `POST /xrpc/com.atproto.server.refreshSession` -> [`refresh_session`]
+/// - `GET /xrpc/com.atproto.server.getServiceAuth` -> [`get_service_auth`]
+/// - `GET /xrpc/com.atproto.server.getSession` -> [`get_session`]
+/// - `POST /xrpc/com.atproto.server.createInviteCode` -> [`create_invite_code`]
 pub(super) fn routes() -> Router<AppState> {
-    // UG /xrpc/com.atproto.server.describeServer
-    // UP /xrpc/com.atproto.server.createAccount
-    // UP /xrpc/com.atproto.server.createSession
-    // AP /xrpc/com.atproto.server.refreshSession
-    // AG /xrpc/com.atproto.server.getServiceAuth
-    // AG /xrpc/com.atproto.server.getSession
-    // AP /xrpc/com.atproto.server.createInviteCode
     Router::new()
         .route(concat!("/", server::describe_server::NSID),     get(describe_server))
         .route(concat!("/", server::create_account::NSID),     post(create_account))

src/endpoints/sync.rs

···
+//! Endpoints for the `ATProto` sync API. (/xrpc/com.atproto.sync.*)
 use std::str::FromStr as _;
 
 use anyhow::{Context as _, anyhow};
···
     storage::{open_repo_db, open_store},
 };
 
-// HACK: `limit` may be passed as a string, so we must treat it as one.
 #[derive(serde::Serialize, serde::Deserialize, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
+/// Parameters for `/xrpc/com.atproto.sync.listBlobs` \
+/// HACK: `limit` may be passed as a string, so we must treat it as one.
 pub(super) struct ListBlobsParameters {
     #[serde(skip_serializing_if = "core::option::Option::is_none")]
+    /// Optional cursor to paginate through blobs.
     pub cursor: Option<String>,
     ///The DID of the repo.
     pub did: Did,
     #[serde(skip_serializing_if = "core::option::Option::is_none")]
+    /// Optional limit of blobs to return.
     pub limit: Option<String>,
     ///Optional revision of the repo to list blobs since.
     #[serde(skip_serializing_if = "core::option::Option::is_none")]
     pub since: Option<String>,
 }
-// HACK: `limit` may be passed as a string, so we must treat it as one.
 #[derive(serde::Serialize, serde::Deserialize, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
+/// Parameters for `/xrpc/com.atproto.sync.listRepos` \
+/// HACK: `limit` may be passed as a string, so we must treat it as one.
 pub(super) struct ListReposParameters {
     #[serde(skip_serializing_if = "core::option::Option::is_none")]
+    /// Optional cursor to paginate through repos.
     pub cursor: Option<String>,
     #[serde(skip_serializing_if = "core::option::Option::is_none")]
+    /// Optional limit of repos to return.
     pub limit: Option<String>,
 }
-// HACK: `cursor` may be passed as a string, so we must treat it as one.
 #[derive(serde::Serialize, serde::Deserialize, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
+/// Parameters for `/xrpc/com.atproto.sync.subscribeRepos` \
+/// HACK: `cursor` may be passed as a string, so we must treat it as one.
 pub(super) struct SubscribeReposParametersData {
     ///The last known event seq number to backfill from.
     #[serde(skip_serializing_if = "core::option::Option::is_none")]
···
     let s = ReaderStream::new(f);
 
     Ok(Response::builder()
-        .header(http::header::CONTENT_LENGTH, format!("{}", len))
+        .header(http::header::CONTENT_LENGTH, format!("{len}"))
         .body(Body::from_stream(s))
         .context("failed to construct response")?)
 }
 
+/// Enumerates which accounts the requesting account is currently blocking. Requires auth.
+/// - GET /xrpc/com.atproto.sync.getBlocks
+/// ### Query Parameters
+/// - `limit`: integer, optional, default: 50, >=1 and <=100
+/// - `cursor`: string, optional
+/// ### Responses
+/// - 200 OK: ...
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
+/// - 401 Unauthorized
 async fn get_blocks(
     State(config): State<AppConfig>,
     Query(input): Query<sync::get_blocks::Parameters>,
···
         .context("failed to construct response")?)
 }
 
+/// Get the current commit CID & revision of the specified repo. Does not require auth.
+/// ### Query Parameters
+/// - `did`: The DID of the repo.
+/// ### Responses
+/// - 200 OK: {"cid": "string","rev": "string"}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `RepoTakendown`, `RepoSuspended`, `RepoDeactivated`]}
 async fn get_latest_commit(
     State(config): State<AppConfig>,
     State(db): State<Db>,
···
     ))
 }
 
+/// Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.
+/// ### Query Parameters
+/// - `did`: The DID of the repo.
+/// - `collection`: nsid
+/// - `rkey`: record-key
+/// ### Responses
+/// - 200 OK: ...
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `RecordNotFound`, `RepoNotFound`, `RepoTakendown`,
+///   `RepoSuspended`, `RepoDeactivated`]}
 async fn get_record(
     State(config): State<AppConfig>,
     State(db): State<Db>,
···
         .context("failed to construct response")?)
 }
 
+/// Get the hosting status for a repository, on this server. Expected to be implemented by PDS and Relay.
+/// ### Query Parameters
+/// - `did`: The DID of the repo.
+/// ### Responses
+/// - 200 OK: {"did": "string","active": true,"status": "takendown","rev": "string"}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `RepoNotFound`]}
 async fn get_repo_status(
     State(db): State<Db>,
     Query(input): Query<sync::get_repo::Parameters>,
···
         .await
         .context("failed to execute query")?;
 
-    let r = if let Some(r) = r {
-        r
-    } else {
+    let Some(r) = r else {
         return Err(Error::with_status(
             StatusCode::NOT_FOUND,
             anyhow!("account not found"),
···
     ))
 }
 
+/// Download a repository export as CAR file. Optionally only a 'diff' since a previous revision.
+/// Does not require auth; implemented by PDS.
+/// ### Query Parameters
+/// - `did`: The DID of the repo.
+/// - `since`: The revision ('rev') of the repo to create a diff from.
+/// ### Responses
+/// - 200 OK: ...
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `RepoNotFound`,
+///   `RepoTakendown`, `RepoSuspended`, `RepoDeactivated`]}
 async fn get_repo(
     State(config): State<AppConfig>,
     State(db): State<Db>,
···
         .context("failed to construct response")?)
 }
 
+/// List blob CIDs for an account, since some repo revision. Does not require auth; implemented by PDS.
+/// ### Query Parameters
+/// - `did`: The DID of the repo. Required.
+/// - `since`: Optional revision of the repo to list blobs since.
+/// - `limit`: >= 1 and <= 1000, default 500
+/// - `cursor`: string
+/// ### Responses
+/// - 200 OK: {"cursor": "string","cids": [string]}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`, `RepoNotFound`, `RepoTakendown`,
+///   `RepoSuspended`, `RepoDeactivated`]}
 async fn list_blobs(
     State(db): State<Db>,
     Query(input): Query<ListBlobsParameters>,
···
     ))
 }
 
+/// Enumerates all the DID, rev, and commit CID for all repos hosted by this service.
+/// Does not require auth; implemented by PDS and Relay.
+/// ### Query Parameters
+/// - `limit`: >= 1 and <= 1000, default 500
+/// - `cursor`: string
+/// ### Responses
+/// - 200 OK: {"cursor": "string","repos": [{"did": "string","head": "string","rev": "string","active": true,"status": "takendown"}]}
+/// - 400 Bad Request: {error:[`InvalidRequest`, `ExpiredToken`, `InvalidToken`]}
 async fn list_repos(
     State(db): State<Db>,
     Query(input): Query<ListReposParameters>,
 ) -> Result<Json<sync::list_repos::Output>> {
     struct Record {
+        /// The DID of the repo.
         did: String,
+        /// The commit CID of the repo.
         rev: String,
+        /// The root CID of the repo.
         root: String,
     }
 
···
     Ok(Json(sync::list_repos::OutputData { cursor, repos }.into()))
 }
 
+/// Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events,
+///  for all repositories on the current server. See the atproto specifications for details around stream sequencing,
+///  repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.
+/// ### Query Parameters
+/// - `cursor`: The last known event seq number to backfill from.
+/// ### Responses
+/// - 200 OK: ...
 async fn subscribe_repos(
     ws_up: WebSocketUpgrade,
     State(fh): State<FirehoseProducer>,
···
 }
 
 #[rustfmt::skip]
+/// These endpoints are part of the atproto repository synchronization APIs. Requests usually do not require authentication, 
+///  and can be made to PDS intances or Relay instances.
+/// ### Routes
+/// - `GET /xrpc/com.atproto.sync.getBlob` -> [`get_blob`]
+/// - `GET /xrpc/com.atproto.sync.getBlocks` -> [`get_blocks`]
+/// - `GET /xrpc/com.atproto.sync.getLatestCommit` -> [`get_latest_commit`]
+/// - `GET /xrpc/com.atproto.sync.getRecord` -> [`get_record`]
+/// - `GET /xrpc/com.atproto.sync.getRepoStatus` -> [`get_repo_status`]
+/// - `GET /xrpc/com.atproto.sync.getRepo` -> [`get_repo`]
+/// - `GET /xrpc/com.atproto.sync.listBlobs` -> [`list_blobs`]
+/// - `GET /xrpc/com.atproto.sync.listRepos` -> [`list_repos`]
+/// - `GET /xrpc/com.atproto.sync.subscribeRepos` -> [`subscribe_repos`]
 pub(super) fn routes() -> Router<AppState> {
-    // UG /xrpc/com.atproto.sync.getBlob
-    // UG /xrpc/com.atproto.sync.getBlocks
-    // UG /xrpc/com.atproto.sync.getLatestCommit
-    // UG /xrpc/com.atproto.sync.getRecord
-    // UG /xrpc/com.atproto.sync.getRepoStatus
-    // UG /xrpc/com.atproto.sync.getRepo
-    // UG /xrpc/com.atproto.sync.listBlobs
-    // UG /xrpc/com.atproto.sync.listRepos
-    // UG /xrpc/com.atproto.sync.subscribeRepos
     Router::new()
         .route(concat!("/", sync::get_blob::NSID),          get(get_blob))
         .route(concat!("/", sync::get_blocks::NSID),        get(get_blocks))

src/error.rs

···
 #[derive(Error)]
 #[expect(clippy::error_impl_error, reason = "just one")]
 pub struct Error {
+    /// The actual error that occurred.
     err: anyhow::Error,
+    /// The error message to be returned as JSON body.
     message: Option<ErrorMessage>,
+    /// The HTTP status code to be returned.
     status: StatusCode,
 }
 
 #[derive(Default, serde::Serialize)]
 /// A JSON error message.
 pub(crate) struct ErrorMessage {
+    /// The error type.
+    /// This is used to identify the error in the client.
+    /// E.g. `InvalidRequest`, `ExpiredToken`, `InvalidToken`, `HandleNotFound`.
     error: String,
+    /// The error message.
     message: String,
 }
 impl std::fmt::Display for ErrorMessage {
···
 }
 
 impl IntoResponse for Error {
-    #[expect(clippy::cognitive_complexity)]
     fn into_response(self) -> Response {
         error!("{:?}", self.err);
 

src/firehose.rs

···
 /// A firehose producer. This is used to transmit messages to the firehose for broadcast.
 #[derive(Clone, Debug)]
 pub(crate) struct FirehoseProducer {
+    /// The channel to send messages to the firehose.
     tx: tokio::sync::mpsc::Sender<FirehoseMessage>,
 }
 
···
     }
 }
 
-#[expect(clippy::as_conversions)]
+#[expect(
+    clippy::as_conversions,
+    clippy::cast_possible_truncation,
+    clippy::cast_sign_loss,
+    clippy::cast_precision_loss,
+    clippy::arithmetic_side_effects
+)]
+/// Convert a `usize` to a `f64`.
 const fn convert_usize_f64(x: usize) -> Result<f64, &'static str> {
     let result = x as f64;
-    if result as usize != x {
+    if result as usize - x > 0 {
         return Err("cannot convert");
     }
     Ok(result)
 }
 
 /// Serialize a message.
-async fn serialize_message(
-    seq: u64,
-    mut msg: sync::subscribe_repos::Message,
-) -> (&'static str, Vec<u8>) {
+fn serialize_message(seq: u64, mut msg: sync::subscribe_repos::Message) -> (&'static str, Vec<u8>) {
     let mut dummy_seq = 0_i64;
     #[expect(clippy::pattern_type_mismatch)]
     let (ty, nseq) = match &mut msg {
···
         sync::subscribe_repos::Message::Migrate(m) => ("#migrate", &mut m.seq),
         sync::subscribe_repos::Message::Tombstone(m) => ("#tombstone", &mut m.seq),
     };
-
-    #[expect(clippy::as_conversions)]
-    const fn convert_u64_i64(x: u64) -> Result<i64, &'static str> {
-        let result = x as i64;
-        if result as u64 != x {
-            return Err("cannot convert");
-        }
-        Ok(result)
-    }
     // Set the sequence number.
-    *nseq = convert_u64_i64(seq).expect("should find seq");
+    *nseq = i64::try_from(seq).expect("should find seq");
 
     let hdr = FrameHeader::Message(ty.to_owned());
 
···
 ) -> Result<WebSocket> {
     if let Some(cursor) = cursor {
         let mut frame = Vec::new();
-        #[expect(clippy::as_conversions)]
-        const fn convert_i64_u64(x: i64) -> Result<u64, &'static str> {
-            let result = x as u64;
-            if result as i64 != x {
-                return Err("cannot convert");
-            }
-            Ok(result)
+        let cursor = u64::try_from(cursor);
+        if cursor.is_err() {
+            tracing::warn!("cursor is not a valid u64");
+            return Ok(ws);
         }
-        let cursor = convert_i64_u64(cursor).expect("should find cursor");
-
+        let cursor = cursor.expect("should be valid u64");
         // Cursor specified; attempt to backfill the consumer.
         if cursor > seq {
             let hdr = FrameHeader::Error;
···
             );
         }
 
-        for &(historical_seq, ty, ref msg) in history.iter() {
+        for &(historical_seq, ty, ref msg) in history {
             if cursor > historical_seq {
                 continue;
             }
···
 
     info!("attempting to reconnect to upstream relays");
     for relay in &config.firehose.relays {
-        let host = match relay.host_str() {
-            Some(host) => host,
-            None => {
-                warn!("relay {} has no host specified", relay);
-                continue;
-            }
+        let Some(host) = relay.host_str() else {
+            warn!("relay {} has no host specified", relay);
+            continue;
         };
 
         let r = client
···
 ///
 /// This will broadcast all updates in this PDS out to anyone who is listening.
 ///
-/// Reference: https://atproto.com/specs/sync
-pub(crate) async fn spawn(
+/// Reference: <https://atproto.com/specs/sync>
+pub(crate) fn spawn(
     client: Client,
     config: AppConfig,
 ) -> (tokio::task::JoinHandle<()>, FirehoseProducer) {
     let (tx, mut rx) = tokio::sync::mpsc::channel(1000);
     let handle = tokio::spawn(async move {
-        let mut clients: Vec<WebSocket> = Vec::new();
-        let mut history = VecDeque::with_capacity(1000);
         fn time_since_inception() -> u64 {
             chrono::Utc::now()
                 .timestamp_micros()
···
                 .expect("should not wrap")
                 .unsigned_abs()
         }
+        let mut clients: Vec<WebSocket> = Vec::new();
+        let mut history = VecDeque::with_capacity(1000);
         let mut seq = time_since_inception();
 
         // TODO: We should use `com.atproto.sync.notifyOfUpdate` to reach out to relays
         // that may have disconnected from us due to timeout.
 
         loop {
-            match tokio::time::timeout(Duration::from_secs(30), rx.recv()).await {
-                Ok(msg) => match msg {
+            if let Ok(msg) = tokio::time::timeout(Duration::from_secs(30), rx.recv()).await {
+                match msg {
                     Some(FirehoseMessage::Broadcast(msg)) => {
-                        let (ty, by) = serialize_message(seq, msg.clone()).await;
+                        let (ty, by) = serialize_message(seq, msg.clone());
 
                         history.push_back((seq, ty, msg));
                         gauge!(FIREHOSE_HISTORY).set(
···
                     }
                     // All producers have been destroyed.
                     None => break,
-                },
-                Err(_) => {
-                    if clients.is_empty() {
-                        reconnect_relays(&client, &config).await;
-                    }
+                }
+            } else {
+                if clients.is_empty() {
+                    reconnect_relays(&client, &config).await;
+                }
 
-                    let contents = rand::thread_rng()
-                        .sample_iter(rand::distributions::Alphanumeric)
-                        .take(15)
-                        .map(char::from)
-                        .collect::<String>();
+                let contents = rand::thread_rng()
+                    .sample_iter(rand::distributions::Alphanumeric)
+                    .take(15)
+                    .map(char::from)
+                    .collect::<String>();
 
-                    // Send a websocket ping message.
-                    // Reference: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#pings_and_pongs_the_heartbeat_of_websockets
-                    let message = Message::Ping(axum::body::Bytes::from_owner(contents));
-                    drop(broadcast_message(&mut clients, message).await);
-                }
+                // Send a websocket ping message.
+                // Reference: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#pings_and_pongs_the_heartbeat_of_websockets
+                let message = Message::Ping(axum::body::Bytes::from_owner(contents));
+                drop(broadcast_message(&mut clients, message).await);
             }
         }
     });

src/main.rs

···
         }
     }
 
-    #[rustfmt::skip]
     /// Register all actor endpoints.
     pub(crate) fn routes() -> Router<AppState> {
         // AP /xrpc/app.bsky.actor.putPreferences
         // AG /xrpc/app.bsky.actor.getPreferences
         Router::new()
-            .route(concat!("/", actor::put_preferences::NSID), post(put_preferences))
-            .route(concat!("/", actor::get_preferences::NSID),  get(get_preferences))
+            .route(
+                concat!("/", actor::put_preferences::NSID),
+                post(put_preferences),
+            )
+            .route(
+                concat!("/", actor::get_preferences::NSID),
+                get(get_preferences),
+            )
     }
 }
 
···
 
 /// The index (/) route.
 async fn index() -> impl IntoResponse {
-    r#"
+    r"
          __                         __
         /\ \__                     /\ \__
     __  \ \ ,_\  _____   _ __   ___\ \ ,_\   ___
···
 
       Code: https://github.com/DrChat/bluepds
   Protocol: https://atproto.com
-    "#
+    "
 }
 
 /// Service proxy.
 ///
-/// Reference: https://atproto.com/specs/xrpc#service-proxying
+/// Reference: <https://atproto.com/specs/xrpc#service-proxying>
 async fn service_proxy(
     uri: Uri,
     user: AuthenticatedUser,
···
         .await
         .with_context(|| format!("failed to resolve did document {}", did.as_str()))?;
 
-    let service = match did_doc.service.iter().find(|s| s.id == id) {
-        Some(service) => service,
-        None => {
-            return Err(Error::with_status(
-                StatusCode::BAD_REQUEST,
-                anyhow!("could not find resolve service #{id}"),
-            ));
-        }
+    let Some(service) = did_doc.service.iter().find(|s| s.id == id) else {
+        return Err(Error::with_status(
+            StatusCode::BAD_REQUEST,
+            anyhow!("could not find resolve service #{id}"),
+        ));
     };
 
-    let url = service
+    let target_url: url::Url = service
         .service_endpoint
-        .join(&format!("/xrpc{}", url_path))
+        .join(&format!("/xrpc{url_path}"))
         .context("failed to construct target url")?;
 
     let exp = (chrono::Utc::now().checked_add_signed(chrono::Duration::minutes(1)))
···
     let token = auth::sign(
         &skey,
         "JWT",
-        serde_json::json!({
+        &serde_json::json!({
             "iss": user_did.as_str(),
             "aud": did.as_str(),
             "lxm": lxm,
···
     }
 
     let r = client
-        .request(request.method().clone(), url)
+        .request(request.method().clone(), target_url)
         .headers(h)
         .header(http::header::AUTHORIZATION, format!("Bearer {token}"))
         .body(reqwest::Body::wrap_stream(
···
 /// The main application entry point.
 #[expect(
     clippy::cognitive_complexity,
+    clippy::too_many_lines,
     reason = "main function has high complexity"
 )]
 async fn run() -> anyhow::Result<()> {
···
     // Set up trace logging to console and account for the user-provided verbosity flag.
     if args.verbosity.log_level_filter() != LevelFilter::Off {
         let lvl = match args.verbosity.log_level_filter() {
-            LevelFilter::Off => tracing::Level::INFO,
             LevelFilter::Error => tracing::Level::ERROR,
             LevelFilter::Warn => tracing::Level::WARN,
-            LevelFilter::Info => tracing::Level::INFO,
+            LevelFilter::Info | LevelFilter::Off => tracing::Level::INFO,
             LevelFilter::Debug => tracing::Level::DEBUG,
             LevelFilter::Trace => tracing::Level::TRACE,
         };
···
     }
 
     // Initialize metrics reporting.
-    metrics::setup(&config.metrics).context("failed to set up metrics exporter")?;
+    metrics::setup(config.metrics.as_ref()).context("failed to set up metrics exporter")?;
 
     // Create a reqwest client that will be used for all outbound requests.
     let simple_client = reqwest::Client::builder()
···
         .context("failed to create key directory")?;
 
     // Check if crypto keys exist. If not, create new ones.
-    let (skey, rkey) = match std::fs::File::open(&config.key) {
-        Ok(f) => {
-            let keys: KeyData = serde_ipld_dagcbor::from_reader(std::io::BufReader::new(f))
-                .context("failed to deserialize crypto keys")?;
+    let (skey, rkey) = if let Ok(f) = std::fs::File::open(&config.key) {
+        let keys: KeyData = serde_ipld_dagcbor::from_reader(std::io::BufReader::new(f))
+            .context("failed to deserialize crypto keys")?;
 
-            let skey =
-                Secp256k1Keypair::import(&keys.skey).context("failed to import signing key")?;
-            let rkey =
-                Secp256k1Keypair::import(&keys.rkey).context("failed to import rotation key")?;
+        let skey = Secp256k1Keypair::import(&keys.skey).context("failed to import signing key")?;
+        let rkey = Secp256k1Keypair::import(&keys.rkey).context("failed to import rotation key")?;
 
-            (SigningKey(Arc::new(skey)), RotationKey(Arc::new(rkey)))
-        }
-        _ => {
-            info!("signing keys not found, generating new ones");
+        (SigningKey(Arc::new(skey)), RotationKey(Arc::new(rkey)))
+    } else {
+        info!("signing keys not found, generating new ones");
 
-            let skey = Secp256k1Keypair::create(&mut rand::thread_rng());
-            let rkey = Secp256k1Keypair::create(&mut rand::thread_rng());
+        let skey = Secp256k1Keypair::create(&mut rand::thread_rng());
+        let rkey = Secp256k1Keypair::create(&mut rand::thread_rng());
 
-            let keys = KeyData {
-                skey: skey.export(),
-                rkey: rkey.export(),
-            };
+        let keys = KeyData {
+            skey: skey.export(),
+            rkey: rkey.export(),
+        };
 
-            let mut f = std::fs::File::create(&config.key).context("failed to create key file")?;
-            serde_ipld_dagcbor::to_writer(&mut f, &keys)
-                .context("failed to serialize crypto keys")?;
+        let mut f = std::fs::File::create(&config.key).context("failed to create key file")?;
+        serde_ipld_dagcbor::to_writer(&mut f, &keys).context("failed to serialize crypto keys")?;
 
-            (SigningKey(Arc::new(skey)), RotationKey(Arc::new(rkey)))
-        }
+        (SigningKey(Arc::new(skey)), RotationKey(Arc::new(rkey)))
     };
 
     tokio::fs::create_dir_all(&config.repo.path).await?;
···
         .await
         .context("failed to apply migrations")?;
 
-    let (_fh, fhp) = firehose::spawn(client.clone(), config.clone()).await;
+    let (_fh, fhp) = firehose::spawn(client.clone(), config.clone());
 
     let addr = config
         .listen_address
···
 
     serve
         .await
-        .map_err(|e| e.into())
+        .map_err(Into::into)
         .and_then(|r| r)
         .context("failed to serve app")
 }

src/metrics.rs

···
 pub(crate) const REPO_OP_DELETE: &str = "bluepds.repo.op.delete";
 
 /// Must be ran exactly once on startup. This will declare all of the instruments for `metrics`.
-pub(crate) fn setup(config: &Option<config::MetricConfig>) -> anyhow::Result<()> {
+pub(crate) fn setup(config: Option<&config::MetricConfig>) -> anyhow::Result<()> {
     describe_counter!(AUTH_FAILED, "The number of failed authentication attempts.");
 
     describe_gauge!(FIREHOSE_HISTORY, "The size of the firehose history buffer.");
···
     describe_counter!(REPO_OP_UPDATE, "The count of updated records.");
     describe_counter!(REPO_OP_DELETE, "The count of deleted records.");
 
-    if let Some(ref config) = *config {
+    if let Some(config) = config {
         match *config {
             config::MetricConfig::PrometheusPush(ref prometheus_config) => {
                 PrometheusBuilder::new()

src/plc.rs

···
     pub sig: String,
 }
 
-pub(crate) async fn sign_op(
-    rkey: &RotationKey,
-    op: PlcOperation,
-) -> anyhow::Result<SignedPlcOperation> {
+pub(crate) fn sign_op(rkey: &RotationKey, op: PlcOperation) -> anyhow::Result<SignedPlcOperation> {
     let bytes = serde_ipld_dagcbor::to_vec(&op).context("failed to encode op")?;
     let bytes = rkey.sign(&bytes).context("failed to sign op")?;
 

src/storage.rs

···
-//! ATProto user repository datastore functionality.
+//! `ATProto` user repository datastore functionality.
 
 use std::str::FromStr as _;