feat: add opt-in opportunistic pre-fetch cache for clients and client grants

[emsearcy]

🔧 Changes

Add an opt-in opportunistic pre-fetch cache for auth0_client and auth0_client_grant resource reads.

Large Auth0 deployments (100+ clients, 100+ grants) incur excessive latency and rate-limit exhaustion (especially non-production tenants!) during terraform plan CI runs because the provider fetches each resource individually. When pre-fetch is enabled, any individual resource read:

1. Checks an in-memory cache (by resource type + ID).
2. On a cache miss (while pages remain): fetches the next page of resources (50/page), stores all results, advances the page cursor.
3. Re-checks the cache — returns the entry if now found.
4. Falls back to a single-resource fetch if still not found.

This balances latency (never waits for all pages) with opportunistic bulk loading.

Opt-in:

provider "auth0" {
  prefetch = true  # or AUTH0_PREFETCH=true
}

The feature is off by default — existing users are unaffected.

Files changed:

File	Change
internal/prefetch/cache.go	Thread-safe sync.RWMutex-backed cache; page-cursor tracking; per-type fetch mutex (prevents TOCTOU races across parallel goroutines); atomic hit/miss/page counters
internal/prefetch/prefetch.go	GetClient and GetClientGrant — opportunistic heuristic + fallback
internal/config/config.go	prefetchCache field, GetPrefetchCache() accessor, wired in ConfigureProvider
internal/provider/provider.go	prefetch bool schema attribute + AUTH0_PREFETCH env var
internal/auth0/client/resource.go	Use prefetch path in readClient when cache non-nil
internal/auth0/client/resource_grant.go	Use prefetch path in readClientGrant when cache non-nil
internal/auth0/client/resource_credentials.go	Use prefetch path in readClientCredentials when cache non-nil
docs/guides/opportunistic_prefetch.md	Usage guide
internal/prefetch/cache_test.go	Unit tests

Known limitations:

• Per-process cache only. OpenTofu/Terraform spawns multiple provider processes for parallelism. Each process has its own independent in-memory cache.
• Cache is not invalidated. Populated once per provider process lifetime — correct for terraform plan but pre-fetch should not be used if Auth0 state changes mid-run.
• Page size is fixed at 50, matching the SDK default.

Observability: At TF_LOG=DEBUG, a summary line is emitted when each resource type's page list is exhausted:

prefetch: client_grant cache exhausted  pages_fetched=3 cached=114 hits=68 misses=4 hit_rate_pct=94.4

📚 References

• Auth0 rate limits being hit when applying terraform with a large number of Applications/Clients #1488 — rate limits with large client counts (the core problem this addresses)
• fix: Add opt-in parameters to eliminate over-fetching in data sources #1521 — community PR with similar motivation for data sources

🔬 Testing

Unit tests in internal/prefetch/cache_test.go cover concurrent access, TOCTOU safety, pagination exhaustion, and fallback behavior.

Manual timing against a non-production Auth0 tenant with ~270 clients and ~165 grants:

Run	Wall time
Upstream (no prefetch)	4 min 20 sec
AUTH0_PREFETCH=true	49 sec
Speedup	~5.3×

Cache stats from the prefetch run:

• auth0_client: hit_rate=95.8% (264 cached, 6 pages fetched)
• auth0_client_grant: hit_rate=100.0% (114 cached, 3 pages fetched)

📝 Checklist

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

[duedares-rvj]

List results may not be equivalent to read results. readClient and readClientCredentials now flatten objects returned from Client.List, not Client.Read. Auth0 documents special field/scope behavior for client fields like client_authentication_methods, client_secret,encryption_key, and signing keys; using list responses as read substitutes risks missing fields or producing diffs.

[duedares-rvj]

The cache used seems to be currently process-wide and never invalidated.
updateClient, updateClientGrant, and updateClientCredentials all call read afterward; if the object was cached before the write, state can be flattened from stale data. Clean call out that “Cache is not invalidated”, but the provider option affects apply too.

[duedares-rvj]

These tests are essential, but are mostly cache-unit tests and not provider behaviour tests. They focus on cache state/concurrency and does not validate read-vs-list equivalence, stale-cache-after-update, or integration behaviour.