smokesignal.events
+17
src/errors.rs
+17
src/errors.rs
···
1
+
//! # Structured Error Types
2
+
//!
3
+
//! Comprehensive error handling for AT Protocol identity operations using structured error types
4
+
//! with the `thiserror` library. All errors follow the project convention of prefixed error codes
5
+
//! with descriptive messages.
6
+
//!
7
+
//! ## Error Categories
8
+
//!
9
+
//! - **`WebDIDError`**: Errors specific to `did:web` operations including URL conversion and document fetching
10
+
//! - **`ConfigError`**: Configuration and environment variable related errors
11
+
//! - **`ResolveError`**: Handle and DID resolution errors including DNS/HTTP failures and conflicts
12
+
//! - **`PLCDIDError`**: PLC directory communication and document parsing errors
13
+
//!
14
+
//! ## Error Format
15
+
//!
16
+
//! All errors use the standardized format: `error-{domain}-{number} {message}: {details}`
17
+
1
18
use thiserror::Error;
2
19
3
20
/// Error types that can occur when working with Web DIDs
+24
src/lib.rs
+24
src/lib.rs
···
1
+
//! # atproto-identity
2
+
//!
3
+
//! A comprehensive Rust library for AT Protocol identity management providing DID resolution,
4
+
//! handle resolution, and identity document management across multiple DID methods.
5
+
//!
6
+
//! ## Core Modules
7
+
//!
8
+
//! - [`resolve`] - Core resolution logic for handles and DIDs with DNS/HTTP resolution
9
+
//! - [`plc`] - PLC directory client for `did:plc` resolution
10
+
//! - [`web`] - Web DID client for `did:web` resolution and URL conversion
11
+
//! - [`model`] - Data structures for DID documents and AT Protocol entities
12
+
//! - [`validation`] - Input validation for handles and DIDs
13
+
//! - [`config`] - Configuration management and environment variable handling
14
+
//! - [`errors`] - Structured error types following project conventions
15
+
//!
16
+
//! ## Usage
17
+
//!
18
+
//! This library supports both programmatic usage and CLI tooling for identity resolution
19
+
//! across the AT Protocol ecosystem.
20
+
//!
21
+
22
+
#![warn(missing_docs)]
23
+
#![warn(missing_doc_code_examples)]
24
+
1
25
pub mod config;
2
26
pub mod errors;
3
27
pub mod model;
+11
src/plc.rs
+11
src/plc.rs
···
1
+
//! # PLC Directory Client
2
+
//!
3
+
//! Simple HTTP client for querying PLC (Public Ledger of Credentials) directories to retrieve
4
+
//! DID documents for `did:plc` identifiers. The PLC system serves as a centralized registry
5
+
//! for AT Protocol DIDs.
6
+
//!
7
+
//! ## Usage
8
+
//!
9
+
//! The primary function `query()` fetches complete DID documents from PLC directory servers
10
+
//! using HTTPS requests to the standard PLC API endpoint format.
11
+
1
12
use anyhow::Result;
2
13
3
14
use super::errors::PLCDIDError;
+20
src/resolve.rs
+20
src/resolve.rs
···
1
+
//! # Core Resolution Logic
2
+
//!
3
+
//! Provides comprehensive resolution capabilities for AT Protocol identities including handle-to-DID
4
+
//! resolution via DNS TXT records and HTTPS well-known endpoints, input parsing for multiple
5
+
//! identifier formats, and DNS resolver configuration.
6
+
//!
7
+
//! ## Key Features
8
+
//!
9
+
//! - **Multi-method resolution**: Uses both DNS and HTTP methods for handle resolution
10
+
//! - **Input parsing**: Automatically detects and parses handles, `did:plc`, and `did:web` identifiers
11
+
//! - **Validation**: Ensures DNS and HTTP resolution methods agree on the resolved DID
12
+
//! - **Custom DNS**: Supports custom DNS nameservers for resolution
13
+
//!
14
+
//! ## Resolution Flow
15
+
//!
16
+
//! 1. Parse input to determine identifier type (handle vs DID)
17
+
//! 2. For handles: perform parallel DNS and HTTP resolution
18
+
//! 3. Validate that both methods return the same DID
19
+
//! 4. For DIDs: return the identifier directly
20
+
1
21
use anyhow::Result;
2
22
use futures_util::future::join;
3
23
use hickory_resolver::{
+17
src/web.rs
+17
src/web.rs
···
1
+
//! # Web DID Client
2
+
//!
3
+
//! HTTP client for resolving `did:web` identifiers by converting DID formats to HTTPS URLs
4
+
//! and fetching DID documents from well-known locations. Supports both standard did:web
5
+
//! resolution and direct hostname-based document retrieval.
6
+
//!
7
+
//! ## Key Functions
8
+
//!
9
+
//! - **`did_web_to_url()`**: Converts `did:web:example.com` format to HTTPS well-known URLs
10
+
//! - **`query()`**: Fetches DID documents for did:web identifiers
11
+
//! - **`query_hostname()`**: Direct document retrieval from hostname well-known endpoints
12
+
//!
13
+
//! ## URL Conversion
14
+
//!
15
+
//! Transforms DIDs like `did:web:example.com:path:subpath` into HTTPS URLs following
16
+
//! the did:web specification for well-known document locations.
17
+
1
18
use anyhow::Result;
2
19
3
20
use super::errors::WebDIDError;