refactor: split handle resolution

src/config.rs

···
 /// use quickdid::config::{Args, Config};
 /// use clap::Parser;
 ///
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
 /// let args = Args::parse();
 /// let config = Config::from_args(args)?;
 /// config.validate()?;
 ///
 /// println!("Service running at: {}", config.http_external);
 /// println!("Service DID: {}", config.service_did);
+/// # Ok(())
+/// # }
 /// ```
 #[derive(Clone)]
 pub struct Config {
···
     /// use quickdid::config::{Args, Config};
     /// use clap::Parser;
     ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
     /// // Parse from environment and command-line
     /// let args = Args::parse();
     /// let config = Config::from_args(args)?;
     ///
     /// // The service DID is automatically generated from HTTP_EXTERNAL
     /// assert!(config.service_did.starts_with("did:web:"));
+    /// # Ok(())
+    /// # }
     /// ```
     ///
     /// ## Errors
···
     /// ## Example
     ///
     /// ```rust,no_run
+    /// # use quickdid::config::{Args, Config};
+    /// # use clap::Parser;
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let args = Args::parse();
     /// let config = Config::from_args(args)?;
     /// config.validate()?; // Ensures all values are valid
+    /// # Ok(())
+    /// # }
     /// ```
     ///
     /// ## Errors

src/handle_resolver.rs src/handle_resolver/redis.rs

···
+//! Redis-backed caching handle resolver.
+//!
+//! This module provides a handle resolver that caches resolution results in Redis
+//! with configurable expiration times. Redis caching provides persistence across
+//! service restarts and allows sharing of cached results across multiple instances.
+
+use super::errors::HandleResolverError;
+use super::traits::HandleResolver;
 use crate::handle_resolution_result::HandleResolutionResult;
 use async_trait::async_trait;
-use atproto_identity::resolve::{DnsResolver, resolve_subject};
-use chrono::Utc;
 use deadpool_redis::{Pool as RedisPool, redis::AsyncCommands};
 use metrohash::MetroHash64;
-use reqwest::Client;
-use std::collections::HashMap;
 use std::hash::Hasher as _;
 use std::sync::Arc;
-use thiserror::Error;
-use tokio::sync::RwLock;
-
-/// Errors that can occur during handle resolution
-#[derive(Error, Debug)]
-pub enum HandleResolverError {
-    #[error("error-quickdid-resolve-1 Failed to resolve subject: {0}")]
-    ResolutionFailed(String),
-
-    #[error("error-quickdid-resolve-2 Handle not found (cached): {0}")]
-    HandleNotFoundCached(String),
-
-    #[error("error-quickdid-resolve-3 Handle not found (cached)")]
-    HandleNotFound,
 
-    #[error("error-quickdid-resolve-4 Mock resolution failure")]
-    MockResolutionFailure,
-}
-
-#[async_trait]
-pub trait HandleResolver: Send + Sync {
-    async fn resolve(&self, s: &str) -> Result<String, HandleResolverError>;
-}
-
-pub struct BaseHandleResolver {
-    /// DNS resolver for handle-to-DID resolution via TXT records.
-    pub dns_resolver: Arc<dyn DnsResolver>,
-    /// HTTP client for DID document retrieval and well-known endpoint queries.
-    pub http_client: Client,
-    /// Hostname of the PLC directory server for `did:plc` resolution.
-    pub plc_hostname: String,
-}
-
-#[async_trait]
-impl HandleResolver for BaseHandleResolver {
-    async fn resolve(&self, s: &str) -> Result<String, HandleResolverError> {
-        resolve_subject(&self.http_client, &*self.dns_resolver, s)
-            .await
-            .map_err(|e| HandleResolverError::ResolutionFailed(e.to_string()))
-    }
-}
-
-#[derive(Clone, Debug)]
-pub enum ResolveHandleResult {
-    Found(u64, String),
-    NotFound(u64, String),
-}
-
-pub struct CachingHandleResolver {
-    inner: Arc<dyn HandleResolver>,
-    cache: Arc<RwLock<HashMap<String, ResolveHandleResult>>>,
-    ttl_seconds: u64,
-}
-
-impl CachingHandleResolver {
-    pub fn new(inner: Arc<dyn HandleResolver>, ttl_seconds: u64) -> Self {
-        Self {
-            inner,
-            cache: Arc::new(RwLock::new(HashMap::new())),
-            ttl_seconds,
-        }
-    }
-
-    fn current_timestamp() -> u64 {
-        Utc::now().timestamp() as u64
-    }
-
-    fn is_expired(&self, timestamp: u64) -> bool {
-        let current = Self::current_timestamp();
-        current > timestamp && (current - timestamp) > self.ttl_seconds
-    }
-}
-
-#[async_trait]
-impl HandleResolver for CachingHandleResolver {
-    async fn resolve(&self, s: &str) -> Result<String, HandleResolverError> {
-        let handle = s.to_string();
-
-        // Check cache first
-        {
-            let cache = self.cache.read().await;
-            if let Some(cached) = cache.get(&handle) {
-                match cached {
-                    ResolveHandleResult::Found(timestamp, did) => {
-                        if !self.is_expired(*timestamp) {
-                            tracing::debug!("Cache hit for handle {}: {}", handle, did);
-                            return Ok(did.clone());
-                        }
-                        tracing::debug!("Cache entry expired for handle {}", handle);
-                    }
-                    ResolveHandleResult::NotFound(timestamp, error) => {
-                        if !self.is_expired(*timestamp) {
-                            tracing::debug!(
-                                "Cache hit (not found) for handle {}: {}",
-                                handle,
-                                error
-                            );
-                            return Err(HandleResolverError::HandleNotFoundCached(error.clone()));
-                        }
-                        tracing::debug!("Cache entry expired for handle {}", handle);
-                    }
-                }
-            }
-        }
-
-        // Not in cache or expired, resolve through inner resolver
-        tracing::debug!("Cache miss for handle {}, resolving...", handle);
-        let result = self.inner.resolve(s).await;
-        let timestamp = Self::current_timestamp();
-
-        // Store in cache
-        {
-            let mut cache = self.cache.write().await;
-            match &result {
-                Ok(did) => {
-                    cache.insert(
-                        handle.clone(),
-                        ResolveHandleResult::Found(timestamp, did.clone()),
-                    );
-                    tracing::debug!(
-                        "Cached successful resolution for handle {}: {}",
-                        handle,
-                        did
-                    );
-                }
-                Err(e) => {
-                    cache.insert(
-                        handle.clone(),
-                        ResolveHandleResult::NotFound(timestamp, e.to_string()),
-                    );
-                    tracing::debug!("Cached failed resolution for handle {}: {}", handle, e);
-                }
-            }
-        }
-
-        result
-    }
-}
-
-/// Redis-backed caching handle resolver that caches resolution results in Redis
-/// with a configurable expiration time.
+/// Redis-backed caching handle resolver.
+///
+/// This resolver caches handle resolution results in Redis with a configurable TTL.
+/// Results are stored in a compact binary format using bincode serialization
+/// to minimize storage overhead.
+///
+/// # Features
+///
+/// - Persistent caching across service restarts
+/// - Shared cache across multiple service instances  
+/// - Configurable TTL (default: 90 days)
+/// - Compact binary storage format
+/// - Graceful fallback if Redis is unavailable
+///
+/// # Example
+///
+/// ```no_run
+/// use std::sync::Arc;
+/// use deadpool_redis::Pool;
+/// use quickdid::handle_resolver::{RedisHandleResolver, BaseHandleResolver};
+///
+/// # async fn example() {
+/// # let base_resolver: BaseHandleResolver = todo!();
+/// # let redis_pool: Pool = todo!();
+/// // Create with default 90-day TTL
+/// let resolver = RedisHandleResolver::new(
+///     Arc::new(base_resolver),
+///     redis_pool.clone()
+/// );
+///
+/// // Or with custom TTL
+/// let resolver_with_ttl = RedisHandleResolver::with_ttl(
+///     Arc::new(base_resolver),
+///     redis_pool,
+///     86400  // 1 day in seconds
+/// );
+/// # }
+/// ```
 pub struct RedisHandleResolver {
     /// Base handle resolver to perform actual resolution
     inner: Arc<dyn HandleResolver>,
···
 }
 
 impl RedisHandleResolver {
-    /// Create a new Redis-backed handle resolver with default 90-day TTL
+    /// Create a new Redis-backed handle resolver with default 90-day TTL.
     pub fn new(inner: Arc<dyn HandleResolver>, pool: RedisPool) -> Self {
         Self::with_ttl(inner, pool, 90 * 24 * 60 * 60) // 90 days default
     }
 
-    /// Create a new Redis-backed handle resolver with custom TTL
+    /// Create a new Redis-backed handle resolver with custom TTL.
     pub fn with_ttl(inner: Arc<dyn HandleResolver>, pool: RedisPool, ttl_seconds: u64) -> Self {
         Self::with_full_config(inner, pool, "handle:".to_string(), ttl_seconds)
     }
 
-    /// Create a new Redis-backed handle resolver with a custom key prefix
+    /// Create a new Redis-backed handle resolver with a custom key prefix.
     pub fn with_prefix(
         inner: Arc<dyn HandleResolver>,
         pool: RedisPool,
···
         Self::with_full_config(inner, pool, key_prefix, 90 * 24 * 60 * 60)
     }
 
-    /// Create a new Redis-backed handle resolver with full configuration
+    /// Create a new Redis-backed handle resolver with full configuration.
     pub fn with_full_config(
         inner: Arc<dyn HandleResolver>,
         pool: RedisPool,
···
         }
     }
 
-    /// Generate the Redis key for a handle
+    /// Generate the Redis key for a handle.
+    ///
+    /// Uses MetroHash64 to generate a consistent hash of the handle
+    /// for use as the Redis key. This provides better key distribution
+    /// and avoids issues with special characters in handles.
     fn make_key(&self, handle: &str) -> String {
         let mut h = MetroHash64::default();
         h.write(handle.as_bytes());
         format!("{}{}", self.key_prefix, h.finish())
     }
 
-    /// Get the TTL in seconds
+    /// Get the TTL in seconds.
     fn ttl_seconds(&self) -> u64 {
         self.ttl_seconds
     }
···
             let _: Result<(), _> = conn.del(key).await;
         }
     }
-}
+}

src/handle_resolver/base.rs

···
+//! Base handle resolver implementation.
+//!
+//! This module provides the fundamental handle resolution implementation that
+//! performs actual DNS and HTTP lookups to resolve AT Protocol handles to DIDs.
+
+use super::errors::HandleResolverError;
+use super::traits::HandleResolver;
+use async_trait::async_trait;
+use atproto_identity::resolve::{DnsResolver, resolve_subject};
+use reqwest::Client;
+use std::sync::Arc;
+
+/// Base handle resolver that performs actual resolution via DNS and HTTP.
+///
+/// This resolver implements the core AT Protocol handle resolution logic:
+/// 1. DNS TXT record lookup for `_atproto.{handle}`
+/// 2. HTTP well-known endpoint query at `https://{handle}/.well-known/atproto-did`
+/// 3. DID document retrieval from PLC directory or web DIDs
+///
+/// # Example
+///
+/// ```no_run
+/// use std::sync::Arc;
+/// use reqwest::Client;
+/// use atproto_identity::resolve::HickoryDnsResolver;
+/// use quickdid::handle_resolver::{BaseHandleResolver, HandleResolver};
+///
+/// # async fn example() {
+/// let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
+/// let http_client = Client::new();
+/// 
+/// let resolver = BaseHandleResolver {
+///     dns_resolver,
+///     http_client,
+///     plc_hostname: "plc.directory".to_string(),
+/// };
+///
+/// let did = resolver.resolve("alice.bsky.social").await.unwrap();
+/// # }
+/// ```
+pub struct BaseHandleResolver {
+    /// DNS resolver for handle-to-DID resolution via TXT records.
+    pub dns_resolver: Arc<dyn DnsResolver>,
+    
+    /// HTTP client for DID document retrieval and well-known endpoint queries.
+    pub http_client: Client,
+    
+    /// Hostname of the PLC directory server for `did:plc` resolution.
+    pub plc_hostname: String,
+}
+
+#[async_trait]
+impl HandleResolver for BaseHandleResolver {
+    async fn resolve(&self, s: &str) -> Result<String, HandleResolverError> {
+        resolve_subject(&self.http_client, &*self.dns_resolver, s)
+            .await
+            .map_err(|e| HandleResolverError::ResolutionFailed(e.to_string()))
+    }
+}

src/handle_resolver/errors.rs

···
+//! Error types for handle resolution operations.
+//!
+//! This module defines all error types used throughout the handle resolver components,
+//! following the QuickDID error format conventions.
+
+use thiserror::Error;
+
+/// Errors that can occur during handle resolution
+#[derive(Error, Debug)]
+pub enum HandleResolverError {
+    /// Failed to resolve subject through DNS or HTTP
+    #[error("error-quickdid-resolve-1 Failed to resolve subject: {0}")]
+    ResolutionFailed(String),
+
+    /// Handle not found in cache with specific error message
+    #[error("error-quickdid-resolve-2 Handle not found (cached): {0}")]
+    HandleNotFoundCached(String),
+
+    /// Handle not found in cache (generic)
+    #[error("error-quickdid-resolve-3 Handle not found (cached)")]
+    HandleNotFound,
+
+    /// Mock resolver failure for testing
+    #[error("error-quickdid-resolve-4 Mock resolution failure")]
+    MockResolutionFailure,
+}

src/handle_resolver/memory.rs

···
+//! In-memory caching handle resolver.
+//!
+//! This module provides a handle resolver that caches resolution results in memory
+//! with a configurable TTL. This is useful for reducing DNS/HTTP lookups and
+//! improving performance when Redis is not available.
+
+use super::errors::HandleResolverError;
+use super::traits::HandleResolver;
+use async_trait::async_trait;
+use chrono::Utc;
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+/// Result of a handle resolution cached in memory.
+#[derive(Clone, Debug)]
+pub enum ResolveHandleResult {
+    /// Handle was successfully resolved to a DID
+    Found(u64, String),
+    /// Handle resolution failed
+    NotFound(u64, String),
+}
+
+/// In-memory caching wrapper for handle resolvers.
+///
+/// This resolver wraps another resolver and caches results in memory with
+/// a configurable TTL. Both successful and failed resolutions are cached
+/// to avoid repeated lookups.
+///
+/// # Example
+///
+/// ```no_run
+/// use std::sync::Arc;
+/// use quickdid::handle_resolver::{CachingHandleResolver, BaseHandleResolver, HandleResolver};
+///
+/// # async fn example() {
+/// # let base_resolver: BaseHandleResolver = todo!();
+/// let caching_resolver = CachingHandleResolver::new(
+///     Arc::new(base_resolver),
+///     300  // 5 minute TTL
+/// );
+///
+/// // First call hits the underlying resolver
+/// let did1 = caching_resolver.resolve("alice.bsky.social").await.unwrap();
+///
+/// // Second call returns cached result
+/// let did2 = caching_resolver.resolve("alice.bsky.social").await.unwrap();
+/// # }
+/// ```
+pub struct CachingHandleResolver {
+    inner: Arc<dyn HandleResolver>,
+    cache: Arc<RwLock<HashMap<String, ResolveHandleResult>>>,
+    ttl_seconds: u64,
+}
+
+impl CachingHandleResolver {
+    /// Create a new caching handle resolver.
+    ///
+    /// # Arguments
+    ///
+    /// * `inner` - The underlying resolver to use for actual resolution
+    /// * `ttl_seconds` - How long to cache results in seconds
+    pub fn new(inner: Arc<dyn HandleResolver>, ttl_seconds: u64) -> Self {
+        Self {
+            inner,
+            cache: Arc::new(RwLock::new(HashMap::new())),
+            ttl_seconds,
+        }
+    }
+
+    fn current_timestamp() -> u64 {
+        Utc::now().timestamp() as u64
+    }
+
+    fn is_expired(&self, timestamp: u64) -> bool {
+        let current = Self::current_timestamp();
+        current > timestamp && (current - timestamp) > self.ttl_seconds
+    }
+}
+
+#[async_trait]
+impl HandleResolver for CachingHandleResolver {
+    async fn resolve(&self, s: &str) -> Result<String, HandleResolverError> {
+        let handle = s.to_string();
+
+        // Check cache first
+        {
+            let cache = self.cache.read().await;
+            if let Some(cached) = cache.get(&handle) {
+                match cached {
+                    ResolveHandleResult::Found(timestamp, did) => {
+                        if !self.is_expired(*timestamp) {
+                            tracing::debug!("Cache hit for handle {}: {}", handle, did);
+                            return Ok(did.clone());
+                        }
+                        tracing::debug!("Cache entry expired for handle {}", handle);
+                    }
+                    ResolveHandleResult::NotFound(timestamp, error) => {
+                        if !self.is_expired(*timestamp) {
+                            tracing::debug!(
+                                "Cache hit (not found) for handle {}: {}",
+                                handle,
+                                error
+                            );
+                            return Err(HandleResolverError::HandleNotFoundCached(error.clone()));
+                        }
+                        tracing::debug!("Cache entry expired for handle {}", handle);
+                    }
+                }
+            }
+        }
+
+        // Not in cache or expired, resolve through inner resolver
+        tracing::debug!("Cache miss for handle {}, resolving...", handle);
+        let result = self.inner.resolve(s).await;
+        let timestamp = Self::current_timestamp();
+
+        // Store in cache
+        {
+            let mut cache = self.cache.write().await;
+            match &result {
+                Ok(did) => {
+                    cache.insert(
+                        handle.clone(),
+                        ResolveHandleResult::Found(timestamp, did.clone()),
+                    );
+                    tracing::debug!(
+                        "Cached successful resolution for handle {}: {}",
+                        handle,
+                        did
+                    );
+                }
+                Err(e) => {
+                    cache.insert(
+                        handle.clone(),
+                        ResolveHandleResult::NotFound(timestamp, e.to_string()),
+                    );
+                    tracing::debug!("Cached failed resolution for handle {}: {}", handle, e);
+                }
+            }
+        }
+
+        result
+    }
+}

src/handle_resolver/mod.rs

···
+//! Handle resolution module for AT Protocol identity resolution.
+//!
+//! This module provides various implementations of handle-to-DID resolution
+//! with different caching strategies.
+//!
+//! # Architecture
+//!
+//! The module is structured around the [`HandleResolver`] trait with multiple
+//! implementations:
+//!
+//! - [`BaseHandleResolver`]: Core resolver that performs actual DNS/HTTP lookups
+//! - [`CachingHandleResolver`]: In-memory caching wrapper with configurable TTL
+//! - [`RedisHandleResolver`]: Redis-backed persistent caching with binary serialization
+//!
+//! # Example Usage
+//!
+//! ```no_run
+//! use std::sync::Arc;
+//! use quickdid::handle_resolver::{BaseHandleResolver, CachingHandleResolver, HandleResolver};
+//!
+//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+//! # use atproto_identity::resolve::HickoryDnsResolver;
+//! # use reqwest::Client;
+//! # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
+//! # let http_client = Client::new();
+//! // Create base resolver
+//! let base = Arc::new(BaseHandleResolver {
+//!     dns_resolver,
+//!     http_client,
+//!     plc_hostname: "plc.directory".to_string(),
+//! });
+//!
+//! // Wrap with in-memory caching
+//! let resolver = CachingHandleResolver::new(base, 300);
+//!
+//! // Resolve a handle
+//! let did = resolver.resolve("alice.bsky.social").await?;
+//! # Ok(())
+//! # }
+//! ```
+
+// Module structure
+mod errors;
+mod traits;
+mod base;
+mod memory;
+mod redis;
+
+// Re-export public API
+pub use errors::HandleResolverError;
+pub use traits::HandleResolver;
+pub use base::BaseHandleResolver;
+pub use memory::{CachingHandleResolver, ResolveHandleResult};
+pub use redis::RedisHandleResolver;

src/handle_resolver/traits.rs

···
+//! Core traits for handle resolution.
+//!
+//! This module defines the fundamental `HandleResolver` trait that all resolver
+//! implementations must satisfy.
+
+use super::errors::HandleResolverError;
+use async_trait::async_trait;
+
+/// Core trait for handle-to-DID resolution.
+///
+/// Implementations of this trait provide different strategies for resolving
+/// AT Protocol handles (like `alice.bsky.social`) to their corresponding
+/// DID identifiers (like `did:plc:xyz123`).
+///
+/// # Examples
+///
+/// ```no_run
+/// use async_trait::async_trait;
+/// use quickdid::handle_resolver::{HandleResolver, HandleResolverError};
+///
+/// struct MyResolver;
+///
+/// #[async_trait]
+/// impl HandleResolver for MyResolver {
+///     async fn resolve(&self, s: &str) -> Result<String, HandleResolverError> {
+///         // Custom resolution logic
+///         Ok(format!("did:plc:{}", s.replace('.', "")))
+///     }
+/// }
+/// ```
+#[async_trait]
+pub trait HandleResolver: Send + Sync {
+    /// Resolve a handle to its DID.
+    ///
+    /// # Arguments
+    ///
+    /// * `s` - The handle to resolve (e.g., "alice.bsky.social")
+    ///
+    /// # Returns
+    ///
+    /// The resolved DID on success, or an error if resolution fails.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`HandleResolverError`] if:
+    /// - The handle cannot be resolved
+    /// - Network errors occur during resolution
+    /// - The handle is invalid or doesn't exist
+    async fn resolve(&self, s: &str) -> Result<String, HandleResolverError>;
+}