feature: rate limited handle resolver

CLAUDE.md

···
 
 1. **Handle Resolution** (`src/handle_resolver.rs`)
    - `BaseHandleResolver`: Core resolution using DNS and HTTP
+   - `RateLimitedHandleResolver`: Semaphore-based rate limiting for concurrent resolutions
    - `CachingHandleResolver`: In-memory caching layer
    - `RedisHandleResolver`: Redis-backed persistent caching with 90-day TTL
+   - `SqliteHandleResolver`: SQLite-backed persistent caching
    - Uses binary serialization via `HandleResolutionResult` for space efficiency
 
 2. **Binary Serialization** (`src/handle_resolution_result.rs`)
···
 - **Key Prefixes**: Configurable via `QUEUE_REDIS_PREFIX` environment variable
 
 ### Handle Resolution Flow
-1. Check Redis cache (if configured)
-2. Fall back to in-memory cache
+1. Check cache (Redis/SQLite/in-memory based on configuration)
+2. If not cached, acquire rate limit permit (if rate limiting enabled)
 3. Perform DNS TXT lookup or HTTP well-known query
 4. Cache result with appropriate TTL
 5. Return DID or error
···
 - `HTTP_PORT`: Server port (default: 8080)
 - `PLC_HOSTNAME`: PLC directory hostname (default: plc.directory)
 - `REDIS_URL`: Redis connection URL for caching
-- `QUEUE_ADAPTER`: Queue type - 'mpsc' or 'redis' (default: mpsc)
+- `QUEUE_ADAPTER`: Queue type - 'mpsc', 'redis', 'sqlite', or 'noop' (default: mpsc)
 - `QUEUE_REDIS_PREFIX`: Redis key prefix for queues (default: queue:handleresolver:)
-- `QUEUE_WORKER_ID`: Worker ID for Redis queue (auto-generated if not set)
+- `QUEUE_WORKER_ID`: Worker ID for Redis queue (default: worker1)
+- `RESOLVER_MAX_CONCURRENT`: Maximum concurrent handle resolutions (default: 0 = disabled)
 - `RUST_LOG`: Logging level (e.g., debug, info)
 
 ## Error Handling
···
 - MetroHash64 for fast key generation
 - Connection pooling for Redis
 - Configurable TTLs for cache entries
+- Rate limiting via semaphore-based concurrency control
 
 ### Code Style
 - Follow existing Rust idioms and patterns

docs/configuration-reference.md

···
 - [Network Configuration](#network-configuration)
 - [Caching Configuration](#caching-configuration)
 - [Queue Configuration](#queue-configuration)
-- [Security Configuration](#security-configuration)
-- [Advanced Configuration](#advanced-configuration)
+- [Rate Limiting Configuration](#rate-limiting-configuration)
 - [Configuration Examples](#configuration-examples)
 - [Validation Rules](#validation-rules)
 
···
 - **Disk space concerns**: Lower values (1000-5000)
 - **High ingestion rate**: Higher values (50000-1000000)
 
+## Rate Limiting Configuration
+
+### `RESOLVER_MAX_CONCURRENT`
+
+**Required**: No  
+**Type**: Integer  
+**Default**: `0` (disabled)  
+**Range**: 0-10000  
+**Constraints**: Must be between 0 and 10000  
+
+Maximum concurrent handle resolutions allowed. When set to a value greater than 0, enables semaphore-based rate limiting to protect upstream DNS and HTTP services from being overwhelmed.
+
+**How it works**:
+- Uses a semaphore to limit concurrent resolutions
+- Applied between the base resolver and caching layers
+- Requests wait for an available permit before resolution
+- Helps prevent overwhelming upstream services
+
+**Examples**:
+```bash
+# Disabled (default)
+RESOLVER_MAX_CONCURRENT=0
+
+# Light rate limiting
+RESOLVER_MAX_CONCURRENT=10
+
+# Moderate rate limiting
+RESOLVER_MAX_CONCURRENT=50
+
+# Heavy traffic with rate limiting
+RESOLVER_MAX_CONCURRENT=100
+
+# Maximum allowed
+RESOLVER_MAX_CONCURRENT=10000
+```
+
+**Recommendations**:
+- **Development**: 0 (disabled) or 10-50 for testing
+- **Production (low traffic)**: 50-100
+- **Production (high traffic)**: 100-500
+- **Production (very high traffic)**: 500-1000
+- **Testing rate limiting**: 1-5 to observe behavior
+
+**Placement in resolver stack**:
+```
+Request → Cache → RateLimited → Base → DNS/HTTP
+```
+
+### `RESOLVER_MAX_CONCURRENT_TIMEOUT_MS`
+
+**Required**: No  
+**Type**: Integer (milliseconds)  
+**Default**: `0` (no timeout)  
+**Range**: 0-60000  
+**Constraints**: Must be between 0 and 60000 (60 seconds max)  
+
+Timeout for acquiring a rate limit permit in milliseconds. When set to a value greater than 0, requests will timeout if they cannot acquire a permit within the specified time, preventing them from waiting indefinitely when the rate limiter is at capacity.
+
+**How it works**:
+- Applied when `RESOLVER_MAX_CONCURRENT` is enabled (> 0)
+- Uses `tokio::time::timeout` to limit permit acquisition time
+- Returns an error if timeout expires before permit is acquired
+- Prevents request queue buildup during high load
+
+**Examples**:
+```bash
+# No timeout (default)
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=0
+
+# Quick timeout for responsive failures (100ms)
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=100
+
+# Moderate timeout (1 second)
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=1000
+
+# Longer timeout for production (5 seconds)
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=5000
+
+# Maximum allowed (60 seconds)
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=60000
+```
+
+**Recommendations**:
+- **Development**: 100-1000ms for quick feedback
+- **Production (low latency)**: 1000-5000ms
+- **Production (high latency tolerance)**: 5000-30000ms
+- **Testing**: 100ms to quickly identify bottlenecks
+- **0**: Use when you want requests to wait indefinitely
+
+**Error behavior**:
+When a timeout occurs, the request fails with:
+```
+Rate limit permit acquisition timed out after {timeout}ms
+```
+
 ## Configuration Examples
 
 ### Minimal Development Configuration
···
 QUEUE_REDIS_TIMEOUT=5
 QUEUE_BUFFER_SIZE=5000
 
+# Rate Limiting (optional, recommended for production)
+RESOLVER_MAX_CONCURRENT=100
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=5000  # 5 second timeout
+
 # Logging
 RUST_LOG=info
 ```
···
 QUEUE_ADAPTER=sqlite
 QUEUE_BUFFER_SIZE=5000
 QUEUE_SQLITE_MAX_SIZE=10000
+
+# Rate Limiting (optional, recommended for production)
+RESOLVER_MAX_CONCURRENT=100
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=5000  # 5 second timeout
 
 # Logging
 RUST_LOG=info
···
 # Performance
 QUEUE_BUFFER_SIZE=10000
 
+# Rate Limiting (important for HA deployments)
+RESOLVER_MAX_CONCURRENT=500
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=10000  # 10 second timeout for HA
+
 # Logging
 RUST_LOG=warn
 ```
···
    - Must be one of: `mpsc`, `redis`, `sqlite`, `noop`, `none`
    - Case-sensitive
 
-4. **Port** (`HTTP_PORT`):
+4. **Rate Limiting** (`RESOLVER_MAX_CONCURRENT`):
+   - Must be between 0 and 10000
+   - 0 = disabled (default)
+   - Values > 10000 will fail validation
+
+5. **Rate Limiting Timeout** (`RESOLVER_MAX_CONCURRENT_TIMEOUT_MS`):
+   - Must be between 0 and 60000 (milliseconds)
+   - 0 = no timeout (default)
+   - Values > 60000 will fail validation
+
+6. **Port** (`HTTP_PORT`):
    - Must be valid port number (1-65535)
    - Ports < 1024 require elevated privileges
 

docs/production-deployment.md

···
 # RUST_LOG_FORMAT=json
 
 # ----------------------------------------------------------------------------
+# RATE LIMITING CONFIGURATION
+# ----------------------------------------------------------------------------
+
+# Maximum concurrent handle resolutions (default: 0 = disabled)
+# When > 0, enables semaphore-based rate limiting
+# Range: 0-10000 (0 = disabled)
+# Protects upstream DNS/HTTP services from being overwhelmed
+RESOLVER_MAX_CONCURRENT=0
+
+# Timeout for acquiring rate limit permit in milliseconds (default: 0 = no timeout)
+# When > 0, requests will timeout if they can't acquire a permit within this time
+# Range: 0-60000 (max 60 seconds)
+# Prevents requests from waiting indefinitely when rate limiter is at capacity
+RESOLVER_MAX_CONCURRENT_TIMEOUT_MS=0
+
+# ----------------------------------------------------------------------------
 # PERFORMANCE TUNING
 # ----------------------------------------------------------------------------
 
···
 3. **Queue Adapter** (`QUEUE_ADAPTER`):
    - Must be one of: `mpsc`, `redis`, `sqlite`, `noop`, `none`
    - Case-sensitive
+
+4. **Rate Limiting** (`RESOLVER_MAX_CONCURRENT`):
+   - Must be between 0 and 10000
+   - 0 = disabled (default)
+   - When > 0, limits concurrent handle resolutions
+
+5. **Rate Limiting Timeout** (`RESOLVER_MAX_CONCURRENT_TIMEOUT_MS`):
+   - Must be between 0 and 60000 (milliseconds)
+   - 0 = no timeout (default)
+   - Maximum: 60000ms (60 seconds)
 
 ### Validation Errors
 

src/bin/quickdid.rs

···
     cache::create_redis_pool,
     config::Config,
     handle_resolver::{
-        create_base_resolver, create_caching_resolver, create_redis_resolver_with_ttl,
-        create_sqlite_resolver_with_ttl,
+        create_base_resolver, create_caching_resolver, create_rate_limited_resolver_with_timeout,
+        create_redis_resolver_with_ttl, create_sqlite_resolver_with_ttl,
     },
     sqlite_schema::create_sqlite_pool,
     handle_resolver_task::{HandleResolverTaskConfig, create_handle_resolver_task_with_config},
···
                 println!("    QUEUE_WORKER_ID     Worker ID for Redis queue (default: worker1)");
                 println!("    QUEUE_BUFFER_SIZE   Buffer size for MPSC queue (default: 1000)");
                 println!("    QUEUE_SQLITE_MAX_SIZE Maximum SQLite queue size (default: 10000)");
+                println!();
+                println!("    RATE LIMITING:");
+                println!("    RESOLVER_MAX_CONCURRENT Maximum concurrent resolutions (default: 0 = disabled)");
+                println!("    RESOLVER_MAX_CONCURRENT_TIMEOUT_MS Timeout for acquiring permits in ms (default: 0 = no timeout)");
                 println!();
                 println!("For more information, visit: https://github.com/smokesignal.events/quickdid");
                 return true;
···
     let dns_resolver_arc = Arc::new(dns_resolver);
 
     // Create base handle resolver using factory function
-    let base_handle_resolver = create_base_resolver(dns_resolver_arc.clone(), http_client.clone());
+    let mut base_handle_resolver = create_base_resolver(dns_resolver_arc.clone(), http_client.clone());
+
+    // Apply rate limiting if configured
+    if config.resolver_max_concurrent > 0 {
+        let timeout_info = if config.resolver_max_concurrent_timeout_ms > 0 {
+            format!(", {}ms timeout", config.resolver_max_concurrent_timeout_ms)
+        } else {
+            String::new()
+        };
+        tracing::info!(
+            "Applying rate limiting to handle resolver (max {} concurrent resolutions{})",
+            config.resolver_max_concurrent,
+            timeout_info
+        );
+        base_handle_resolver = create_rate_limited_resolver_with_timeout(
+            base_handle_resolver, 
+            config.resolver_max_concurrent,
+            config.resolver_max_concurrent_timeout_ms
+        );
+    }
 
     // Create Redis pool if configured
     let redis_pool = config

src/cache.rs

···
 //! Redis cache utilities for QuickDID
 
-use anyhow::Result;
 use deadpool_redis::{Config, Pool, Runtime};
+use thiserror::Error;
+
+/// Cache-specific errors
+#[derive(Debug, Error)]
+pub enum CacheError {
+    /// Redis pool creation failed
+    #[error("error-quickdid-cache-1 Redis pool creation failed: {0}")]
+    RedisPoolCreationFailed(String),
+}
 
 /// Create a Redis connection pool from a Redis URL.
 ///
···
 /// Returns an error if:
 /// - The Redis URL is invalid
 /// - Pool creation fails
-pub fn create_redis_pool(redis_url: &str) -> Result<Pool> {
+pub fn create_redis_pool(redis_url: &str) -> Result<Pool, CacheError> {
     let config = Config::from_url(redis_url);
     let pool = config
         .create_pool(Some(Runtime::Tokio1))
-        .map_err(|e| anyhow::anyhow!("error-quickdid-cache-1 Redis pool creation failed: {}", e))?;
+        .map_err(|e| CacheError::RedisPoolCreationFailed(e.to_string()))?;
     Ok(pool)
 }

src/config.rs

···
 
     /// Invalid configuration value that doesn't meet expected format or constraints
     ///
-    /// Example: Invalid QUEUE_ADAPTER value (must be 'mpsc', 'redis', or 'noop')
+    /// Example: Invalid QUEUE_ADAPTER value (must be 'mpsc', 'redis', 'sqlite', 'noop', or 'none')
     #[error("error-quickdid-config-2 Invalid configuration value: {0}")]
     InvalidValue(String),
 
···
 /// Validated configuration for QuickDID service
 ///
 /// This struct contains all configuration after validation and processing.
-/// Use `Config::from_args()` to create from command-line arguments and environment variables.
+/// Use `Config::from_env()` to create from environment variables.
 ///
 /// ## Example
 ///
···
     /// When exceeded, oldest entries are deleted to maintain this limit.
     /// Set to 0 to disable work shedding (unlimited queue size).
     pub queue_sqlite_max_size: u64,
+
+    /// Maximum concurrent handle resolutions allowed (rate limiting).
+    /// When set to > 0, enables rate limiting using a semaphore.
+    /// Default: 0 (disabled)
+    pub resolver_max_concurrent: usize,
+
+    /// Timeout for acquiring rate limit permit in milliseconds.
+    /// When set to > 0, requests will timeout if they can't acquire a permit within this time.
+    /// Default: 0 (no timeout)
+    pub resolver_max_concurrent_timeout_ms: u64,
 }
 
 impl Config {
···
             cache_ttl_sqlite: parse_env("CACHE_TTL_SQLITE", 7776000)?,
             queue_redis_timeout: parse_env("QUEUE_REDIS_TIMEOUT", 5)?,
             queue_sqlite_max_size: parse_env("QUEUE_SQLITE_MAX_SIZE", 10000)?,
+            resolver_max_concurrent: parse_env("RESOLVER_MAX_CONCURRENT", 0)?,
+            resolver_max_concurrent_timeout_ms: parse_env("RESOLVER_MAX_CONCURRENT_TIMEOUT_MS", 0)?,
         })
     }
 
···
     /// Checks:
     /// - Cache TTL values are positive (> 0)
     /// - Queue timeout is positive (> 0)
-    /// - Queue adapter is a valid value ('mpsc', 'redis', 'noop', 'none')
+    /// - Queue adapter is a valid value ('mpsc', 'redis', 'sqlite', 'noop', 'none')
     ///
     /// ## Example
     ///
···
             "mpsc" | "redis" | "sqlite" | "noop" | "none" => {}
             _ => {
                 return Err(ConfigError::InvalidValue(format!(
-                    "Invalid QUEUE_ADAPTER '{}', must be 'mpsc', 'redis', 'sqlite', or 'noop'",
+                    "Invalid QUEUE_ADAPTER '{}', must be 'mpsc', 'redis', 'sqlite', 'noop', or 'none'",
                     self.queue_adapter
                 )));
             }
+        }
+        if self.resolver_max_concurrent > 10000 {
+            return Err(ConfigError::InvalidValue(
+                "RESOLVER_MAX_CONCURRENT must be between 0 and 10000".to_string(),
+            ));
+        }
+        if self.resolver_max_concurrent_timeout_ms > 60000 {
+            return Err(ConfigError::InvalidTimeout(
+                "RESOLVER_MAX_CONCURRENT_TIMEOUT_MS must be <= 60000 (60 seconds)".to_string(),
+            ));
         }
         Ok(())
     }

src/handle_resolution_result.rs

···
 /// Errors that can occur during handle resolution result operations
 #[derive(Debug, Error)]
 pub enum HandleResolutionError {
-    #[error("error-quickdid-resolution-1 System time error: {0}")]
+    /// System time error when getting timestamp
+    #[error("error-quickdid-result-1 System time error: {0}")]
     SystemTime(String),
 
-    #[error("error-quickdid-serialization-1 Failed to serialize resolution result: {0}")]
+    /// Failed to serialize resolution result to binary format
+    #[error("error-quickdid-result-2 Failed to serialize resolution result: {0}")]
     Serialization(String),
 
-    #[error("error-quickdid-serialization-2 Failed to deserialize resolution result: {0}")]
+    /// Failed to deserialize resolution result from binary format
+    #[error("error-quickdid-result-3 Failed to deserialize resolution result: {0}")]
     Deserialization(String),
 }
 

src/handle_resolver/mod.rs

···
 //! implementations:
 //!
 //! - [`BaseHandleResolver`]: Core resolver that performs actual DNS/HTTP lookups
+//! - [`RateLimitedHandleResolver`]: Rate limiting wrapper using semaphore-based concurrency control
 //! - [`CachingHandleResolver`]: In-memory caching wrapper with configurable TTL
 //! - [`RedisHandleResolver`]: Redis-backed persistent caching with binary serialization
 //! - [`SqliteHandleResolver`]: SQLite-backed persistent caching for single-instance deployments
···
 mod base;
 mod errors;
 mod memory;
+mod rate_limited;
 mod redis;
 mod sqlite;
 mod traits;
···
 // Factory functions for creating resolvers
 pub use base::create_base_resolver;
 pub use memory::create_caching_resolver;
+pub use rate_limited::{create_rate_limited_resolver, create_rate_limited_resolver_with_timeout};
 pub use redis::{create_redis_resolver, create_redis_resolver_with_ttl};
 pub use sqlite::{create_sqlite_resolver, create_sqlite_resolver_with_ttl};

src/handle_resolver/rate_limited.rs

···
+//! Rate-limited handle resolver implementation.
+//!
+//! This module provides a handle resolver wrapper that limits concurrent
+//! resolution requests using a semaphore to implement basic rate limiting.
+
+use super::errors::HandleResolverError;
+use super::traits::HandleResolver;
+use async_trait::async_trait;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::sync::Semaphore;
+use tokio::time::timeout;
+
+/// Rate-limited handle resolver that constrains concurrent resolutions.
+///
+/// This resolver wraps an inner resolver and uses a semaphore to limit
+/// the number of concurrent resolution requests. This provides basic
+/// rate limiting and protects upstream services from being overwhelmed.
+///
+/// # Architecture
+///
+/// The rate limiter should be placed between the base resolver and any
+/// caching layers:
+/// ```text
+/// Request -> Cache -> RateLimited -> Base -> DNS/HTTP
+/// ```
+///
+/// # Example
+///
+/// ```no_run
+/// use std::sync::Arc;
+/// use quickdid::handle_resolver::{
+///     create_base_resolver,
+///     create_rate_limited_resolver,
+///     HandleResolver,
+/// };
+///
+/// # async fn example() {
+/// # 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 = create_base_resolver(dns_resolver, http_client);
+///
+/// // Wrap with rate limiting (max 10 concurrent resolutions)
+/// let rate_limited = create_rate_limited_resolver(base, 10);
+///
+/// // Use the rate-limited resolver
+/// let did = rate_limited.resolve("alice.bsky.social").await.unwrap();
+/// # }
+/// ```
+pub(super) struct RateLimitedHandleResolver {
+    /// Inner resolver that performs actual resolution.
+    inner: Arc<dyn HandleResolver>,
+    
+    /// Semaphore for limiting concurrent resolutions.
+    semaphore: Arc<Semaphore>,
+    
+    /// Optional timeout for acquiring permits (in milliseconds).
+    /// When None or 0, no timeout is applied.
+    timeout_ms: Option<u64>,
+}
+
+impl RateLimitedHandleResolver {
+    /// Create a new rate-limited resolver.
+    ///
+    /// # Arguments
+    ///
+    /// * `inner` - The inner resolver to wrap
+    /// * `max_concurrent` - Maximum number of concurrent resolutions allowed
+    pub fn new(inner: Arc<dyn HandleResolver>, max_concurrent: usize) -> Self {
+        Self {
+            inner,
+            semaphore: Arc::new(Semaphore::new(max_concurrent)),
+            timeout_ms: None,
+        }
+    }
+    
+    /// Create a new rate-limited resolver with timeout.
+    ///
+    /// # Arguments
+    ///
+    /// * `inner` - The inner resolver to wrap
+    /// * `max_concurrent` - Maximum number of concurrent resolutions allowed
+    /// * `timeout_ms` - Timeout in milliseconds for acquiring permits (0 = no timeout)
+    pub fn new_with_timeout(inner: Arc<dyn HandleResolver>, max_concurrent: usize, timeout_ms: u64) -> Self {
+        Self {
+            inner,
+            semaphore: Arc::new(Semaphore::new(max_concurrent)),
+            timeout_ms: if timeout_ms > 0 { Some(timeout_ms) } else { None },
+        }
+    }
+}
+
+#[async_trait]
+impl HandleResolver for RateLimitedHandleResolver {
+    async fn resolve(&self, s: &str) -> Result<String, HandleResolverError> {
+        // Acquire a permit from the semaphore, with optional timeout
+        let _permit = match self.timeout_ms {
+            Some(timeout_ms) if timeout_ms > 0 => {
+                // Apply timeout when acquiring permit
+                let duration = Duration::from_millis(timeout_ms);
+                match timeout(duration, self.semaphore.acquire()).await {
+                    Ok(Ok(permit)) => permit,
+                    Ok(Err(e)) => {
+                        // Semaphore error (e.g., closed)
+                        return Err(HandleResolverError::ResolutionFailed(
+                            format!("Failed to acquire rate limit permit: {}", e)
+                        ));
+                    }
+                    Err(_) => {
+                        // Timeout occurred
+                        return Err(HandleResolverError::ResolutionFailed(
+                            format!("Rate limit permit acquisition timed out after {}ms", timeout_ms)
+                        ));
+                    }
+                }
+            }
+            _ => {
+                // No timeout configured, wait indefinitely
+                self.semaphore.acquire().await
+                    .map_err(|e| HandleResolverError::ResolutionFailed(
+                        format!("Failed to acquire rate limit permit: {}", e)
+                    ))?
+            }
+        };
+        
+        // With permit acquired, forward to inner resolver
+        self.inner.resolve(s).await
+    }
+}
+
+/// Create a rate-limited handle resolver.
+///
+/// This factory function creates a new [`RateLimitedHandleResolver`] that wraps
+/// the provided inner resolver with concurrency limiting.
+///
+/// # Arguments
+///
+/// * `inner` - The resolver to wrap with rate limiting
+/// * `max_concurrent` - Maximum number of concurrent resolutions allowed
+///
+/// # Returns
+///
+/// An `Arc<dyn HandleResolver>` that can be used wherever a handle resolver is needed.
+///
+/// # Example
+///
+/// ```no_run
+/// use std::sync::Arc;
+/// use quickdid::handle_resolver::{
+///     create_base_resolver,
+///     create_rate_limited_resolver,
+/// };
+///
+/// # async fn example() {
+/// # use atproto_identity::resolve::HickoryDnsResolver;
+/// # use reqwest::Client;
+/// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
+/// # let http_client = Client::new();
+/// let base = create_base_resolver(dns_resolver, http_client);
+/// let rate_limited = create_rate_limited_resolver(base, 10);
+/// # }
+/// ```
+pub fn create_rate_limited_resolver(
+    inner: Arc<dyn HandleResolver>,
+    max_concurrent: usize,
+) -> Arc<dyn HandleResolver> {
+    Arc::new(RateLimitedHandleResolver::new(inner, max_concurrent))
+}
+
+/// Create a rate-limited handle resolver with timeout.
+///
+/// This factory function creates a new [`RateLimitedHandleResolver`] that wraps
+/// the provided inner resolver with concurrency limiting and timeout for permit acquisition.
+///
+/// # Arguments
+///
+/// * `inner` - The resolver to wrap with rate limiting
+/// * `max_concurrent` - Maximum number of concurrent resolutions allowed
+/// * `timeout_ms` - Timeout in milliseconds for acquiring permits (0 = no timeout)
+///
+/// # Returns
+///
+/// An `Arc<dyn HandleResolver>` that can be used wherever a handle resolver is needed.
+///
+/// # Example
+///
+/// ```no_run
+/// use std::sync::Arc;
+/// use quickdid::handle_resolver::{
+///     create_base_resolver,
+///     create_rate_limited_resolver_with_timeout,
+/// };
+///
+/// # async fn example() {
+/// # use atproto_identity::resolve::HickoryDnsResolver;
+/// # use reqwest::Client;
+/// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
+/// # let http_client = Client::new();
+/// let base = create_base_resolver(dns_resolver, http_client);
+/// // Rate limit with 10 concurrent resolutions and 5 second timeout
+/// let rate_limited = create_rate_limited_resolver_with_timeout(base, 10, 5000);
+/// # }
+/// ```
+pub fn create_rate_limited_resolver_with_timeout(
+    inner: Arc<dyn HandleResolver>,
+    max_concurrent: usize,
+    timeout_ms: u64,
+) -> Arc<dyn HandleResolver> {
+    Arc::new(RateLimitedHandleResolver::new_with_timeout(inner, max_concurrent, timeout_ms))
+}

src/handle_resolver_task.rs

···
 /// Handle resolver task errors
 #[derive(Error, Debug)]
 pub(crate) enum HandleResolverError {
-    #[error("Queue adapter health check failed: adapter is not healthy")]
+    /// Queue adapter health check failed
+    #[error("error-quickdid-task-1 Queue adapter health check failed: adapter is not healthy")]
     QueueAdapterUnhealthy,
 }