# Architecture

Purpose: Define system architecture, key decisions, and repository boundaries for jwks-cache.

Audience: Engineers and LLMs reading the canonical system specification.

Scope: JWKS caching behavior, registry lifecycle, HTTP semantics, persistence, metrics, security, and repository layout.

## Platform targets

- Rust library crate designed for async runtimes.
- No OS-specific code; consumers decide runtime integration.
- Optional Redis persistence is gated by the `redis` feature.

## Runtime and dependencies

- Async runtime: Tokio multi-thread runtime.
- HTTP client: Reqwest with Rustls TLS.
- Caching semantics: `http-cache-semantics` for `Cache-Control`, `ETag`, and `Last-Modified`.
- JWKS parsing: `jsonwebtoken::jwk::JwkSet`.

## Registry and cache lifecycle

- `Registry` owns tenant/provider registrations and per-provider cache managers.
- Each tenant/provider pair has a `CacheManager` that enforces single-flight refreshes.
- Cache states: `Empty`, `Loading`, `Ready`, `Refreshing`.
- Refresh cadence is driven by:
	- `refresh_early` lead time before expiry.
	- `stale_while_error` window when refresh fails.
	- `min_ttl` / `max_ttl` clamps on upstream cache directives.
	- `retry_policy` backoff strategy for refresh attempts.

## Persistence (optional)

- Enable the `redis` feature to persist snapshots between deploys.
- `Registry::restore_from_persistence` restores cache state on startup.
- `Registry::persist_all` captures JWKS payloads, validators, and expiry metadata on shutdown.

## Metrics and tracing

- 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

- HTTPS is required by default (`require_https = true`).
- Redirect allowlist via `allowed_domains`.
- Redirect depth is capped by `max_redirects`.
- Payload size guard via `max_response_bytes`.
- Optional TLS pinning via `pinned_spki` fingerprints.

## Repository layout (current)

```
.
├── docs/
│   ├── guide/                        # Operational guidance and development rules.
│   └── spec/                         # Normative system specifications.
├── src/                              # Library implementation.
├── tests/                            # Integration tests (wiremock).
├── Cargo.toml                        # Crate metadata and dependencies.
├── Makefile.toml                     # Use `cargo make fmt`, `cargo make lint`, `cargo make test`, `cargo make test-redis`.
├── README.md                         # Public-facing overview and usage.
└── rust-toolchain.toml               # Pinned Rust toolchain.
```

## Key boundaries

### `registry`

Owns registrations, validation, and coordinates cache managers.

### `cache`

Implements cache state, refresh scheduling, and single-flight behavior.

### `http`

Handles JWKS fetches, retry policies, and HTTP caching semantics.

### `metrics`

Captures per-provider metrics and exposes Prometheus-compatible exporters when enabled.

### `security`

Validates HTTPS requirements, allowed domains, and TLS pinning settings.
