crates-docs 0.9.0

# Crates Docs MCP Server Configuration Example
#
# =============================================================================
# Hot Reload Support Notes
# =============================================================================
#
# Marker explanation:
# - ✅ Supports hot reload: configuration changes take effect automatically without server restart
# - ❌ Does not support hot reload: configuration changes require server restart to take effect
#
# Configuration that supports hot reload:
# - logging section: all fields
# - auth/oauth/api_key section: all fields
# - cache section: TTL-related fields (default_ttl, crate_docs_ttl_secs, item_docs_ttl_secs, search_results_ttl_secs)
# - performance section: rate_limit_per_second, concurrent_request_limit, enable_metrics, enable_response_compression
#
# Configuration that does not support hot reload:
# - server section: all fields (involves listening socket and transport layer initialization)
# - cache section: cache_type, memory_size, redis_url, key_prefix (cache backend initialization parameters)
# - performance section: http_client_*, cache_max_size, cache_default_ttl_secs, metrics_port
#
# After modifying the configuration file, the system will automatically detect changes and apply hot-reloadable configuration items.

# =============================================================================
# [server] Server Configuration ❌ Does not support hot reload
# =============================================================================
# Warning: The following configuration changes require server restart to take effect
#
[server]
# Server name
name = "crates-docs"
# Server version (defaults to version in Cargo.toml)
# version = "0.5.3"
# Server description
description = "High-performance Rust crate documentation query MCP server"
# Listen host
# For container deployment, use 0.0.0.0 to expose service externally; for local use only, change back to 127.0.0.1
host = "0.0.0.0"
# Listen port
port = 8080
# Transport mode: stdio, http, sse, hybrid
transport_mode = "hybrid"
# Enable SSE support
enable_sse = true
# Enable OAuth authentication
enable_oauth = false
# Maximum concurrent connections
max_connections = 100
# Request timeout (seconds)
request_timeout_secs = 30
# Response timeout (seconds)
response_timeout_secs = 60

# Security configuration
# Allowed hosts list (Host header validation)
# For container/reverse proxy deployment, add actual domain names or service names as needed
allowed_hosts = ["localhost", "127.0.0.1", "0.0.0.0"]

# Allowed origins list (CORS)
# Development environment can use wildcard patterns; production environment should specify exact domain names
# Example: allowed_origins = ["https://your-domain.com"]
# Note: Using "*" will allow all origins, which poses security risks
allowed_origins = ["http://localhost:*"]

# =============================================================================
# [cache] Cache Configuration - Partial hot reload support
# =============================================================================
#
# ✅ Hot reload supported fields:
#    default_ttl, crate_docs_ttl_secs, item_docs_ttl_secs, search_results_ttl_secs
#
# ❌ Hot reload not supported fields (require restart):
#    cache_type, memory_size, redis_url, key_prefix
#
[cache]
# Cache type: memory, redis ❌ Does not support hot reload
cache_type = "memory"
# Memory cache size (number of entries) ❌ Does not support hot reload
memory_size = 1000
# Redis connection URL (used only when cache_type = "redis") ❌ Does not support hot reload
# redis_url = "redis://localhost:6379"
# Default cache TTL (seconds) ✅ Supports hot reload
default_ttl = 3600
# Crate docs cache TTL (seconds), default 1 hour ✅ Supports hot reload
crate_docs_ttl_secs = 3600
# Item docs cache TTL (seconds), default 30 minutes ✅ Supports hot reload
item_docs_ttl_secs = 1800
# Search results cache TTL (seconds), default 5 minutes ✅ Supports hot reload
search_results_ttl_secs = 300

# =============================================================================
# [oauth] OAuth Configuration ✅ Fully supports hot reload
# =============================================================================
#
# All fields support runtime hot reload, take effect immediately after modification (no restart needed)
#
[oauth]
# Enable OAuth ✅ Supports hot reload
enabled = false
# OAuth client ID ✅ Supports hot reload
# client_id = "your-client-id"
# OAuth client secret ✅ Supports hot reload
# client_secret = "your-client-secret"
# Redirect URI ✅ Supports hot reload
# redirect_uri = "http://localhost:8080/oauth/callback"
# Authorization endpoint ✅ Supports hot reload
# authorization_endpoint = "https://provider.com/oauth/authorize"
# Token endpoint ✅ Supports hot reload
# token_endpoint = "https://provider.com/oauth/token"
# Authorization scopes ✅ Supports hot reload
scopes = ["openid", "profile", "email"]
# OAuth provider: Custom, GitHub, Google, Keycloak ✅ Supports hot reload
provider = "Custom"

# GitHub OAuth example configuration
# [oauth]
# enabled = true
# client_id = "github-client-id"
# client_secret = "github-client-secret"
# redirect_uri = "http://localhost:8080/oauth/callback"
# authorization_endpoint = "https://github.com/login/oauth/authorize"
# token_endpoint = "https://github.com/login/oauth/access_token"
# scopes = ["read:user", "user:email"]
# provider = "GitHub"

# Google OAuth example configuration
# [oauth]
# enabled = true
# client_id = "google-client-id"
# client_secret = "google-client-secret"
# redirect_uri = "http://localhost:8080/oauth/callback"
# authorization_endpoint = "https://accounts.google.com/o/oauth2/v2/auth"
# token_endpoint = "https://oauth2.googleapis.com/token"
# scopes = ["openid", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/userinfo.email"]
# provider = "Google"

# Keycloak OAuth example configuration
# [oauth]
# enabled = true
# client_id = "keycloak-client-id"
# client_secret = "keycloak-client-secret"
# redirect_uri = "http://localhost:8080/oauth/callback"
# authorization_endpoint = "https://keycloak.example.com/realms/myrealm/protocol/openid-connect/auth"
# token_endpoint = "https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token"
# scopes = ["openid", "profile", "email"]
# provider = "Keycloak"

# =============================================================================
# [api_key] API Key Authentication Configuration ✅ Fully supports hot reload
# =============================================================================
#
# Note: Requires api-key feature to use this functionality
# All fields support runtime hot reload, take effect immediately after modification (no restart needed)
#
# [api_key]
# # Enable API Key authentication ✅ Supports hot reload
# enabled = true
# # List of valid API Key hashes (Argon2 PHC format) ✅ Supports hot reload
# # Do not store plaintext keys in configuration file; use `crates-docs generate-api-key`
# # to generate a one-time plaintext key, and save the output hash here
# keys = ["$argon2id$v=19$m=47104,t=1,p=1$replace$with_generated_hash"]
# # API Key header name ✅ Supports hot reload
# header_name = "X-API-Key"
# # API Key query parameter name (not recommended, lower security) ✅ Supports hot reload
# query_param_name = "api_key"
# # Allow API Key via query parameter (default false) ✅ Supports hot reload
# allow_query_param = false
# # API Key prefix (for generating and validating structured keys) ✅ Supports hot reload
# key_prefix = "sk"

# =============================================================================
# [logging] Logging Configuration ✅ Fully supports hot reload
# =============================================================================
#
# All fields support runtime hot reload, take effect immediately after modification (no restart needed)
#
[logging]
# Log level: trace, debug, info, warn, error ✅ Supports hot reload
level = "info"
# Log file path (effective when enable_file = true) ✅ Supports hot reload
file_path = "./logs/crates-docs.log"
# Enable console logging ✅ Supports hot reload
enable_console = true
# Enable file logging (default false, console output only) ✅ Supports hot reload
enable_file = false
# Maximum log file size (MB) ✅ Supports hot reload
max_file_size_mb = 100
# Number of log files to retain ✅ Supports hot reload
max_files = 10

# =============================================================================
# [performance] Performance Configuration - Partial hot reload support
# =============================================================================
#
# ✅ Hot reload supported fields:
#    rate_limit_per_second, concurrent_request_limit, enable_metrics, enable_response_compression
#
# ❌ Hot reload not supported fields (require restart):
#    http_client_*, cache_max_size, cache_default_ttl_secs, metrics_port
#
[performance]
# HTTP client connection pool size ❌ Does not support hot reload
http_client_pool_size = 10
# HTTP client pool idle timeout (seconds) ❌ Does not support hot reload
http_client_pool_idle_timeout_secs = 90
# HTTP client connection timeout (seconds) ❌ Does not support hot reload
http_client_connect_timeout_secs = 10
# HTTP client request timeout (seconds) ❌ Does not support hot reload
http_client_timeout_secs = 30
# HTTP client read timeout (seconds) ❌ Does not support hot reload
http_client_read_timeout_secs = 30
# HTTP client max retry attempts ❌ Does not support hot reload
http_client_max_retries = 3
# HTTP client retry initial delay (milliseconds) ❌ Does not support hot reload
http_client_retry_initial_delay_ms = 100
# HTTP client retry max delay (milliseconds) ❌ Does not support hot reload
http_client_retry_max_delay_ms = 10000
# Cache maximum size (number of entries) ❌ Does not support hot reload
cache_max_size = 1000
# Cache default TTL (seconds) ❌ Does not support hot reload
cache_default_ttl_secs = 3600
# Request rate limit (requests per second) ✅ Supports hot reload
rate_limit_per_second = 100
# Concurrent request limit ✅ Supports hot reload
concurrent_request_limit = 50
# Enable response compression ✅ Supports hot reload
enable_response_compression = true
# Enable Prometheus metrics collection ✅ Supports hot reload
enable_metrics = true
# Metrics server port (0 means use server port) ❌ Does not support hot reload
metrics_port = 0

# ============================================================================
# Environment Variable Configuration (for Docker deployment)
# ============================================================================
#
# The following environment variables can override settings in the configuration file.
# Priority: Environment variables > CLI configuration file > Default values
#
# API Key authentication environment variables:
#   CRATES_DOCS_API_KEY_ENABLED=true                    # Enable API Key authentication
#   CRATES_DOCS_API_KEYS=$argon2id$...,$argon2id$...   # API Key hash list (comma-separated)
#   CRATES_DOCS_API_KEY_HEADER=X-API-Key                # API Key header name
#   CRATES_DOCS_API_KEY_QUERY_PARAM_NAME=api_key        # API Key query parameter name
#   CRATES_DOCS_API_KEY_ALLOW_QUERY=false               # Allow query parameter passing
#   CRATES_DOCS_API_KEY_PREFIX=sk                       # API Key prefix
#
# First generate key:
#   crates-docs generate-api-key --prefix sk
#
# Docker deployment example:
#   docker run -d \
#     -p 8080:8080 \
#     -e CRATES_DOCS_API_KEY_ENABLED=true \
#     -e CRATES_DOCS_API_KEYS='$argon2id$...generated_hash...' \
#     crates-docs:latest
#
# Docker Compose example:
#   services:
#     crates-docs:
#       image: crates-docs:latest
#       ports:
#         - "8080:8080"
#       environment:
#         - CRATES_DOCS_API_KEY_ENABLED=true
#         - CRATES_DOCS_API_KEYS=$argon2id$...generated_hash...
#         - CRATES_DOCS_HOST=0.0.0.0
#         - CRATES_DOCS_PORT=8080
#
# CLI parameter example:
#   crates-docs serve \
#     --enable-api-key \
#     --api-keys '$argon2id$...generated_hash...' \
#     --api-key-header "X-API-Key"
#
# ============================================================================