Make metrics and prometheus features optional

Introduce `metrics` and `prometheus` feature flags to allow users to
opt out of telemetry dependencies. Update the `Registry` and
`CacheManager` to conditionally compile metrics logic, and adjust
documentation and tests to reflect these changes.

Author: aurexav

Cargo.lock

@@ -9,7 +9,7 @@ license     = "GPL-3.0"
 name        = "jwks-cache"
 readme      = "README.md"
 repository  = "https://github.com/hack-ink/jwks-cache"
-version     = "0.1.5"
+version     = "0.2.0"
 
 [package.metadata.docs.rs]
 all-features = true
@@ -23,7 +23,14 @@ inherits = "release"
 lto      = true
 
 [features]
-default = []
+metrics = [
+	"dep:metrics",
+	"smallvec",
+]
+prometheus = [
+	"metrics",
+	"metrics-exporter-prometheus",
+]
 
 [dependencies]
 # crates.io
@@ -33,19 +40,19 @@ http                        = { version = "1.4" }
 http-cache-semantics        = { version = "2.1" }
 httpdate                    = { version = "1.0" }
 jsonwebtoken                = { version = "10.2", features = ["aws_lc_rs"] }
-metrics                     = { version = "0.24" }
-metrics-exporter-prometheus = { version = "0.18" }
+metrics                     = { version = "0.24", optional = true }
+metrics-exporter-prometheus = { version = "0.18", optional = true }
 rand                        = { version = "0.9", features = ["small_rng", "std"] }
 redis                       = { version = "0.32", optional = true, default-features = false, features = ["aio", "tokio-comp"] }
 reqwest                     = { version = "0.12", default-features = false, features = ["http2", "json", "rustls-tls", "stream"] }
 serde                       = { version = "1.0", features = ["derive"] }
 serde_json                  = { version = "1.0" }
 sha2                        = { version = "0.10" }
-smallvec                    = { version = "1.15" }
+smallvec                    = { version = "1.15", optional = true }
 thiserror                   = { version = "2.0" }
 tokio                       = { version = "1.48", features = ["macros", "rt-multi-thread", "sync", "time"] }
 tracing                     = { version = "0.1" }
-url                         = { version = "2.5" }
+url                         = { version = "2.5", features = ["serde"] }
 
 [dev-dependencies]
 # crates.io

Cargo.toml

@@ -1,22 +1,28 @@
 # Format
-# | task      | type    | cwd |
-# | ----      | ------- | --- |
-# | fmt       | command |     |
-# | fmt-check | command |     |
+# | task          | type      | cwd |
+# | ------------  | --------- | --- |
+# | fmt           | composite |     |
+# | fmt-check     | composite |     |
+# | fmt-rust      | script    |     |
+# | fmt-rust-check| extend    |     |
 
 [tasks.fmt]
 workspace = false
-command = "cargo"
-args = ["fmt"]
+dependencies = ["fmt-rust"]
 
 [tasks.fmt-check]
 workspace = false
-command = "cargo"
-args = [
-	"fmt",
-	"--",
-	"--check"
-]
+dependencies = ["fmt-rust-check"]
+
+[tasks.fmt-rust]
+workspace = false
+script = "cargo +nightly fmt ${FMT_RUST_ARGS}"
+env = { FMT_RUST_ARGS = "" }
+
+[tasks.fmt-rust-check]
+workspace = false
+extend = "fmt-rust"
+env = { FMT_RUST_ARGS = "-- --check" }
 
 
 # Lint

Makefile.toml

@@ -60,7 +60,7 @@ The crate is fully async and designed for the Tokio multi-threaded runtime.
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
 	tracing_subscriber::fmt::init();
-	// Optional Prometheus exporter (metrics are always sent via the `metrics` facade).
+	// Optional Prometheus exporter (requires the `prometheus` feature).
 	jwks_cache::install_default_exporter()?;
 
 	let registry = jwks_cache::Registry::builder()
@@ -144,7 +144,7 @@ The optional third argument to `Registry::resolve` lets you pass the `kid` up fr
 - `register` / `unregister` keep provider state scoped to each tenant.
 - `resolve` serves cached JWKS payloads with per-tenant metrics tagging.
 - `refresh` triggers an immediate background refresh without waiting for TTL expiry.
-- `provider_status` and `all_statuses` expose lifecycle state, expiry, error counters, hit rates, and the metrics that power `jwks-cache.openapi.yaml`.
+- `provider_status` and `all_statuses` expose lifecycle state, expiry, and error counters, plus hit rates and status metrics when the `metrics` feature is enabled.
 
 ### Security controls
 
@@ -154,12 +154,15 @@ The optional third argument to `Registry::resolve` lets you pass the `kid` up fr
 
 ### Feature flags
 
-- `redis`: enable Redis-backed snapshots for `persist_all` and `restore_from_persistence`. When disabled, these methods are cheap no-ops so lifecycle code can stay shared.
+- The `redis` feature enables Redis-backed snapshots for `persist_all` and `restore_from_persistence`. When disabled, these methods are cheap no-ops so lifecycle code can stay shared.
+- The `metrics` feature enables metrics emission through the `metrics` facade.
+- The `prometheus` feature enables `install_default_exporter` to install the bundled Prometheus recorder (implies `metrics`).
+- The default features include `prometheus` and `metrics`; disable them with `default-features = false`.
 
 ## Observability
 
-- Metrics emitted via the `metrics` facade include `jwks_cache_requests_total`, `jwks_cache_hits_total`, `jwks_cache_misses_total`, `jwks_cache_stale_total`, `jwks_cache_refresh_total`, `jwks_cache_refresh_errors_total`, and the `jwks_cache_refresh_duration_seconds` histogram.
-- `install_default_exporter` installs the bundled Prometheus recorder (`metrics-exporter-prometheus`) and exposes a `PrometheusHandle` for HTTP servers to serve `/metrics`.
+- Metrics emitted via the `metrics` facade (requires the `metrics` feature) include `jwks_cache_requests_total`, `jwks_cache_hits_total`, `jwks_cache_misses_total`, `jwks_cache_stale_total`, `jwks_cache_refresh_total`, `jwks_cache_refresh_errors_total`, and the `jwks_cache_refresh_duration_seconds` histogram.
+- The `install_default_exporter` function installs the bundled Prometheus recorder (`metrics-exporter-prometheus`) and exposes a `PrometheusHandle` for HTTP servers to serve `/metrics` (requires the `prometheus` feature).
 - Every cache operation is instrumented with `tracing` spans keyed by tenant and provider identifiers, making it easy to correlate logs, traces, and metrics.
 
 ## Persistence & Warm Starts

README.md

@@ -38,8 +38,8 @@ Scope: JWKS caching behavior, registry lifecycle, HTTP semantics, persistence, m
 
 ## Metrics and tracing
 
-- Metrics flow through the `metrics` facade.
-- `install_default_exporter` installs the bundled Prometheus recorder.
+- Metrics flow through the `metrics` facade when the `metrics` feature is enabled.
+- The `install_default_exporter` function installs the bundled Prometheus recorder when the `prometheus` feature is enabled.
 - Cache operations emit structured `tracing` spans keyed by tenant and provider identifiers.
 
 ## Security and validation
@@ -81,7 +81,7 @@ Handles JWKS fetches, retry policies, and HTTP caching semantics.
 
 ### `metrics`
 
-Captures per-provider metrics and exposes Prometheus-compatible exporters.
+Captures per-provider metrics and exposes Prometheus-compatible exporters when enabled.
 
 ### `security`
 

docs/spec/architecture.md

@@ -15,6 +15,7 @@ use tokio::{
 	time,
 };
 // self
+#[cfg(feature = "metrics")] use crate::metrics::{self, ProviderMetrics};
 #[cfg(feature = "redis")] use crate::registry::PersistentSnapshot;
 use crate::{
 	_prelude::*,
@@ -27,7 +28,6 @@ use crate::{
 		retry::{AttemptBudget, RetryExecutor},
 		semantics::{Freshness, base_request, evaluate_freshness, evaluate_revalidation},
 	},
-	metrics::{self, ProviderMetrics},
 	registry::IdentityProviderRegistration,
 };
 
@@ -41,6 +41,7 @@ pub struct CacheManager {
 	client: Arc<Client>,
 	entry: Arc<RwLock<CacheEntry>>,
 	single_flight: Arc<Mutex<()>>,
+	#[cfg(feature = "metrics")]
 	metrics: Arc<ProviderMetrics>,
 }
 impl CacheManager {
@@ -54,14 +55,25 @@ impl CacheManager {
 			.connect_timeout(Duration::from_secs(5))
 			.build()?;
 
-		Ok(Self::with_parts(registration, client, ProviderMetrics::new()))
+		#[cfg(feature = "metrics")]
+		let manager = Self::with_parts(registration, client, ProviderMetrics::new());
+		#[cfg(not(feature = "metrics"))]
+		let manager = Self::with_parts(registration, client);
+
+		Ok(manager)
 	}
 
 	/// Build a cache manager using the supplied HTTP client (primarily for tests).
 	pub fn with_client(registration: IdentityProviderRegistration, client: Client) -> Self {
-		Self::with_parts(registration, client, ProviderMetrics::new())
+		#[cfg(feature = "metrics")]
+		let manager = Self::with_parts(registration, client, ProviderMetrics::new());
+		#[cfg(not(feature = "metrics"))]
+		let manager = Self::with_parts(registration, client);
+
+		manager
 	}
 
+	#[cfg(feature = "metrics")]
 	fn with_parts(
 		registration: IdentityProviderRegistration,
 		client: Client,
@@ -79,7 +91,21 @@ impl CacheManager {
 		}
 	}
 
+	#[cfg(not(feature = "metrics"))]
+	fn with_parts(registration: IdentityProviderRegistration, client: Client) -> Self {
+		let tenant = registration.tenant_id.clone();
+		let provider = registration.provider_id.clone();
+
+		Self {
+			registration: Arc::new(registration),
+			client: Arc::new(client),
+			entry: Arc::new(RwLock::new(CacheEntry::new(tenant, provider))),
+			single_flight: Arc::new(Mutex::new(())),
+		}
+	}
+
 	/// Access the per-provider metrics accumulator.
+	#[cfg(feature = "metrics")]
 	pub fn metrics(&self) -> Arc<ProviderMetrics> {
 		self.metrics.clone()
 	}
@@ -201,14 +227,17 @@ impl CacheManager {
 					match self.refresh_blocking(true).await? {
 						RefreshOutcome::Updated { jwks, from_cache } => {
 							if from_cache {
+								#[cfg(feature = "metrics")]
 								self.observe_hit(false);
 							} else {
+								#[cfg(feature = "metrics")]
 								self.observe_miss();
 							}
 
 							return Ok(jwks);
 						},
 						RefreshOutcome::Stale(jwks) => {
+							#[cfg(feature = "metrics")]
 							self.observe_hit(true);
 
 							return Ok(jwks);
@@ -219,6 +248,7 @@ impl CacheManager {
 					if !payload.is_expired(now) {
 						let jwks = payload.jwks.clone();
 
+						#[cfg(feature = "metrics")]
 						self.observe_hit(false);
 
 						if now >= payload.next_refresh_at {
@@ -234,14 +264,17 @@ impl CacheManager {
 						match self.refresh_blocking(false).await {
 							Ok(RefreshOutcome::Updated { jwks, from_cache }) => {
 								if from_cache {
+									#[cfg(feature = "metrics")]
 									self.observe_hit(false);
 								} else {
+									#[cfg(feature = "metrics")]
 									self.observe_miss();
 								}
 
 								return Ok(jwks);
 							},
 							Ok(RefreshOutcome::Stale(jwks)) => {
+								#[cfg(feature = "metrics")]
 								self.observe_hit(true);
 
 								return Ok(jwks);
@@ -250,6 +283,7 @@ impl CacheManager {
 								if payload.can_serve_stale(Instant::now()) {
 									tracing::warn!(error = %err, "refresh failed, serving stale data");
 
+									#[cfg(feature = "metrics")]
 									self.observe_hit(true);
 
 									return Ok(payload.jwks.clone());
@@ -261,8 +295,10 @@ impl CacheManager {
 						self.refresh_blocking(true).await?
 					{
 						if from_cache {
+							#[cfg(feature = "metrics")]
 							self.observe_hit(false);
 						} else {
+							#[cfg(feature = "metrics")]
 							self.observe_miss();
 						}
 						return Ok(jwks);
@@ -413,6 +449,7 @@ impl CacheManager {
 		let request = request;
 
 		while let AttemptBudget::Granted { timeout } = executor.attempt_budget() {
+			#[cfg(feature = "metrics")]
 			let attempt_started = Instant::now();
 			let fetch = fetch_jwks(&self.client, &self.registration, &request, timeout).await;
 
@@ -463,6 +500,7 @@ impl CacheManager {
 					let jwks = payload.jwks.clone();
 
 					self.commit_success(mode, payload).await;
+					#[cfg(feature = "metrics")]
 					self.observe_refresh_success(attempt_started.elapsed());
 
 					return Ok(RefreshOutcome::Updated { jwks, from_cache: false });
@@ -503,6 +541,7 @@ impl CacheManager {
 			},
 		}
 
+		#[cfg(feature = "metrics")]
 		self.observe_refresh_error();
 
 		if !force_revalidation
@@ -569,6 +608,7 @@ impl CacheManager {
 		}
 	}
 
+	#[cfg(feature = "metrics")]
 	fn observe_hit(&self, stale: bool) {
 		let tenant = &self.registration.tenant_id;
 		let provider = &self.registration.provider_id;
@@ -578,6 +618,7 @@ impl CacheManager {
 		self.metrics.record_hit(stale);
 	}
 
+	#[cfg(feature = "metrics")]
 	fn observe_miss(&self) {
 		let tenant = &self.registration.tenant_id;
 		let provider = &self.registration.provider_id;
@@ -587,6 +628,7 @@ impl CacheManager {
 		self.metrics.record_miss();
 	}
 
+	#[cfg(feature = "metrics")]
 	fn observe_refresh_success(&self, duration: Duration) {
 		let tenant = &self.registration.tenant_id;
 		let provider = &self.registration.provider_id;
@@ -596,6 +638,7 @@ impl CacheManager {
 		self.metrics.record_refresh_success(duration);
 	}
 
+	#[cfg(feature = "metrics")]
 	fn observe_refresh_error(&self) {
 		let tenant = &self.registration.tenant_id;
 		let provider = &self.registration.provider_id;

src/cache/manager.rs

@@ -40,6 +40,7 @@ pub enum Error {
 	#[error("Validation failed for {field}: {reason}")]
 	Validation { field: &'static str, reason: String },
 }
+#[cfg(feature = "metrics")]
 impl<T> From<metrics::SetRecorderError<T>> for Error
 where
 	T: std::fmt::Display,