docs: update caching docs by saad-h1 · Pull Request #3163 · openfga/openfga

saad-h1 · Jun 4, 2026

Description

What problem is being solved?

docs/caching.md had several gaps and inaccuracies: undocumented caches (auth model, typesystem), stale key format examples, missing explanation of how iterator invalidation keys work, no documentation of TTL jitter, an unanswered question about what happens when Check and List Objects iterator configs differ, and a staleness risk when all three of cache controller + iterator cache + query cache are enabled together.

How is it being solved?

By updating the doc to reflect current code behavior: correcting cache key formats to match the TLV-based scheme, explaining the field choices and invalidation key design, documenting the always-on model/typesystem caches, explaining the first-writer-wins interaction between Check and List Objects iterator configs, documenting TTL jitter, and adding a caveat describing the three-cache stale entry scenario and how to avoid it.

What changes are made to solve it?

Overview: Added a "Cache instances" note listing the three independent caches (shared check cache, model cache, typesystem cache) and their sizes/TTLs.
Cache key formats: Updated all key format descriptions from the old string-concatenation format (ic.r/, sp., etc.) to the current TLV-encoded field layout (IC + "READ" + ..., SP + ...), with a note that the actual stored key is opaque binary.
"Why these key fields?" subsection: Added explanation of why structural fields are in the clear vs. hashed, and why contextual tuples/context are excluded from iterator keys.
"How iterator invalidation keys map to iterator cache entries" subsection: Explains how a tuple write maps to IQ/OR (covers READ + RUT entries) and IQ/UOT (covers RSWU entries), and why relation is dropped from the UOT key.
List Objects iterator cache: Added a subsection on the first-writer-wins interaction between Check and List Objects iterator TTL/maxResults configs.
"Stale Query Cache Entry via Stale Iterator Cache" caveat: Documents the scenario where a stale iterator entry leads to a stale query cache entry that survives invalidation, and lists mitigations.
"Authorization Model & Typesystem Cache" section: New section covering what each caches, key format, TTL, immutability rationale, and size config flags.
"TTL Jitter" section: Documents OPENFGA_CACHE_TTL_JITTER_PERCENTAGE, the jitter formula, and why it prevents thundering herd.

References

Review Checklist

I have clicked on "allow edits by maintainers".
I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
The correct base branch is being used, if not main
I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

Documentation
- Expanded caching guide with comprehensive details on cache behavior, keying, and invalidation semantics.
- Added an explicit Authorization Model & Typesystem cache section and noted higher-consistency bypass rules.
- Clarified query and iterator cache key models and invalidation mapping, including staleness-window behavior.
- Documented TTL jitter configuration and fixed-TTL notes for model/typesystem caches.

Signed-off-by: Saad Hussain <saad.hussain@okta.com>

coderabbitai · Jun 4, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 015613ad-e43a-4355-9a22-5586afc60e10

📥 Commits

Reviewing files that changed from the base of the PR and between dbfd051 and 7572084.

📒 Files selected for processing (1)

docs/caching.md

✅ Files skipped from review due to trivial changes (1)

docs/caching.md

📝 Walkthrough

Walkthrough

Documentation update to docs/caching.md introducing an explicit Authorization Model & Typesystem Cache, revising Check Query and Check Iterator cache key models, overhauling Cache Controller invalidation semantics, and adding staleness and TTL jitter subsections.

Changes

Caching Documentation Expansion

Layer / File(s)	Summary
Cache Types and Query Cache Key Model `docs/caching.md`	Introduces always-on Authorization Model & Typesystem Cache with TTL/size configs, clarifies HIGHER_CONSISTENCY bypass, and revises Check Query Cache key model to `SP + storeID + object + relation + user + invariantHash` with updated invariantHash/storeID explanations.
Iterator Cache Key Structure and Examples `docs/caching.md`	Rewrites iterator cache from `ic.r/ic.rtwu/ic.rut` to `IC + "READ"/"RSWU"/"RUT"` taxonomy, clarifies which key components are stored clear vs. hashed, explicitly excludes request-time context from DB-derived keys, and documents Check/List Objects cache interaction where first-writer fixes TTL/maxResults.
Cache Controller and Invalidation Semantics `docs/caching.md`	Updates cache marker naming (`CC + storeID`, `IQ + ...`), expands query-vs-iterator invalidation logic into three explicit cases, maps iterator invalidation markers to iterator-cache entry shapes, and clarifies relation omission for user/objectType invalidation markers.
Cache Staleness Scenarios and TTL Configuration `docs/caching.md`	Adds "Stale Query Cache Entry via Stale Iterator Cache" scenario describing timestamp-based staleness windows, documents Authorization Model & Typesystem Cache keys/TTLs/sizes, and introduces TTL Jitter config and its effect on query/iterator TTLs (model/typesystem caches use fixed TTL).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

openfga/openfga#2664: Earlier documentation-only update to docs/caching.md that introduced initial caching keying and invalidation semantics which this PR expands and refactors.

Suggested reviewers

cikasfm
adriantam

Poem

🐰 I dug through keys and TTLs bright,
Around cache markers day and night,
Models steady, iterators sing,
Invalidation keeps the ring—
Hop, patch, and docs: caching feels just right!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'docs: update caching docs' is vague and generic, using non-descriptive language that does not convey the specific nature or scope of the documentation updates.	Use a more specific title that reflects the key updates, such as 'docs: update caching documentation with key formats, invalidation logic, and TTL jitter' or similar.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/caching-2026-06

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/caching.md`:
- Line 34: Update the documentation sentence to reference modelID rather than
storeID: change the phrase that currently says "cache correctness does not
depend on store IDs being globally unique across database restores or
environment imports" so it instead reads "cache correctness does not depend on
model IDs being globally unique across database restores or environment
imports", keeping the surrounding mention of the key and invariantHash for
defense-in-depth (symbols: storeID, modelID, invariantHash).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4327e671-0963-4ea5-832a-4881288a4647

📥 Commits

Reviewing files that changed from the base of the PR and between 709b9bd and dbfd051.

📒 Files selected for processing (1)

docs/caching.md

codecov · Jun 4, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.08%. Comparing base (4f00251) to head (7572084).

❌ Your project check has failed because the head coverage (81.08%) is below the target coverage (85.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3163      +/-   ##
==========================================
+ Coverage   80.98%   81.08%   +0.11%     
==========================================
  Files         196      201       +5     
  Lines       21051    22119    +1068     
==========================================
+ Hits        17046    17934     +888     
- Misses       3273     3406     +133     
- Partials      732      779      +47

Flag	Coverage Δ
matrix	`84.93% <ø> (?)`
storage	`86.23% <ø> (ø)`
unit	`80.03% <ø> (-0.10%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

senojj

Excellent! Just need one correction as suggested by coderabbitai.

Signed-off-by: Saad Hussain <saad.hussain@okta.com>

Add support for exporting logs via OTLP, allowing integration with any OpenTelemetry-compatible backend (Grafana Loki, Datadog, GCP Cloud Logging, etc.). When log.otlp.enabled is set, logs are exported via OTLP in addition to stdout. The otelzap bridge attaches span context (trace ID, span ID) to each log record, enabling log-trace correlation in backends that support it. Configuration mirrors the trace configuration shape: the standard OTel env vars (OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_ENDPOINT) only answer where logs are sent, while the explicit OpenFGA flag (log.otlp.enabled / --log-otlp-enabled / OPENFGA_LOG_OTLP_ENABLED) answers whether to export at all — so a cluster that injects the generic endpoint variable for tracing does not silently start exporting logs on upgrade. zap's production sampling is applied outside the tee, so the keep/drop decision is made once, before fan-out: stdout and OTLP receive the same deterministically sampled stream and collector egress stays bounded during log storms. Changes: - Add otelzap bridge core backed by an OTLP log provider (internal/telemetry/logging.go) - Add WithOTELCore logger option that tees log entries to the bridge. The bridge core is capped to the configured log level, the stdout core strips the bridge-only context field via contextFilterCore, and the sampler wraps the tee (pkg/logger/logger.go) - Attach the context field in the *WithContext logging methods only when an OTEL core is configured, and use those methods in the gRPC logging interceptor so the bridge can extract span context (pkg/middleware/logging/logging.go) - Add config: log.otlp.enabled, log.otlp.endpoint, log.otlp.tls.enabled with OPENFGA_LOG_OTLP_* env vars and OTEL_EXPORTER_OTLP_* endpoint fallbacks (pkg/server/config/config.go, cmd/run/, .config-schema.json) feat: add potential v2 breaking change logs for Expand and ListUsers (openfga#3182) release: update changelog for release 1.18.1 (openfga#3188) release: Update changelog to prep for 1.18.1 release (openfga#3186) test: fix flaky TestV2CheckWithIteratorCache_HigherConsistencyBypassesCache (openfga#3061) Co-authored-by: Joshua Jones <joshua.jones.software@gmail.com> Merge commit from fork * test reproducing ListUsers report * implement fix * additional test with 3 operands fix: match IPv4-mapped IPv6 addresses in the in_cidr condition (openfga#3181) Signed-off-by: kanywst <niwatakuma@icloud.com> fix: use deterministic proto marshaling for stored authorization models (openfga#3171) chore: create draft release and publish after provenance succeeds for immutable tags/releases (openfga#3178) docs: fix changelog entry (openfga#3177) Signed-off-by: Saad Hussain <saad.hussain@okta.com> feat: add v2Check logs for resolution breaking change (openfga#3149) feat: BatchCheck uses v2Check when ExperimentalWeightedGraphCheck is enabled (openfga#3154) Signed-off-by: Saad Hussain <saad.hussain@okta.com> chore: update changelog to add CVE identifiers for recent fixes (openfga#3176) chore: update todo comment string in migration guide (openfga#3175) release: update changelog for release `v1.18.0` (openfga#3174) Co-authored-by: adriantam <adrian.tam@okta.com> Merge commit from fork * fix(authn): require issuer and audience when OIDC authn is enabled Enforce configuration authn.oidc.audience and authn.oidc.issuer when `authn.method` is set to `oidc`. * fixed based on code review feedback * fix: adding comments + test case on empty space for audience * update based on code review feedback * Update CHANGELOG.md Co-authored-by: Joshua Jones <joshua.jones.software@gmail.com> * update changelog * Update CHANGELOG.md --------- Co-authored-by: Joshua Jones <joshua.jones.software@gmail.com> Merge commit from fork * fix(mysql): collate identifier columns as utf8mb4_bin * fix: add operator note to changelog * fix: move tests to shared storage * fix: separate migrations for each table * fix: add runbook for migrations * fix: set lock_wait_timeout * fix: add docker instructions * fix: add docker instructions * fix: combine the migrations back into one, fix documentation for this * fix: include details about table copy and * Update CHANGELOG.md Co-authored-by: Adrian Tam <adrian.tam@okta.com> --------- Co-authored-by: Adrian Tam <adrian.tam@okta.com> fix: use constant-time comparison for preshared key authentication (openfga#3168) chore(deps): bump the dependencies group with 2 updates (openfga#3166) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Justin Cohen <justincoh@gmail.com> chore(deps): bump the dependencies group with 2 updates (openfga#3167) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> release: update changelog for release `v1.17.1` (openfga#3165) Signed-off-by: Saad Hussain <saad.hussain@okta.com> chore: bump grpc-health-probe to v0.4.52 (openfga#3164) Co-authored-by: Saad Hussain <saad.hussain@okta.com> docs: update caching docs (openfga#3163) Signed-off-by: Saad Hussain <saad.hussain@okta.com> fix: continuation token deserializer - handle `|` in type names (openfga#3152) chore(deps): bump the dependencies group across 1 directory with 13 updates (openfga#3162) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Justin Cohen <justincoh@gmail.com> chore(deps): bump the dependencies group across 1 directory with 10 updates (openfga#3156) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Justin Cohen <justincoh@gmail.com> fix: use query start time as iterator cache entry LastModified to prevent stale-read survival (openfga#3155) chore(deps): bump grpc-ecosystem/grpc-health-probe from v0.4.50 to v0.4.51 in the dependencies group (openfga#3157) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Saad Hussain <saad.hussain@okta.com> Co-authored-by: Justin Cohen <justincoh@gmail.com> chore: Bump go toolchain to 1.26.4 (openfga#3159) fix: prevent v2Check from falling back for throttling and validation (openfga#3150) ci: make pr benchmark comparisons less fragile (openfga#3153) Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> release: update changelog for release `v1.17.0` (openfga#3151) Co-authored-by: Vic-Dev <vmichellej@gmail.com> refactor: redesign cache key generation, making it more secure and consistent (openfga#3148) feat: add configurable trace sampler with ParentBased support (openfga#3072) release: update changelog for release `v1.16.1` (openfga#3147) chore: update grpc-health-probe to latest to addres std lib CVEs (openfga#3146) fix: skip v2Check weight2 pruning if iterator is unordered (openfga#3145) Signed-off-by: Saad Hussain <saad.hussain@okta.com> chore: add concurrency-group to PR-related CI steps (openfga#3140) docs: move OIDC JWKS refresh entry from v1.15.1 to v1.16.0 (openfga#3142) fix: when v2Check is primary algorithm, fix fallback condition and emit metrics (openfga#3141) release: update changelog for release `v1.16.0` (openfga#3139) Merge commit from fork * fix: Standardize cache key generation everywhere * Revert "fix: Standardize cache key generation everywhere" This reverts commit ce60c6f9ae48a310a4dea2b824b5993520c8ba1c. * length-encoded approach * Revert "length-encoded approach" This reverts commit b94637c187c57a2d3f3904247267bbc8ad21a41a. * implement Hexer() and use in some cache keys * appendConditionsHash -> generateConditionsHash * mv Hexer -> BuildKey * BuildKey -> BuildCacheKey refactor to BuildCacheKey on each individual prefix component to remove collision risk * make v2 cacheKey functions the standard * make cache key prefixes consistent * generateConditionsHash -> generateConditionsString * delimit condition name string * remove extra empty check * relocate and reuse existing userTypeRestrictions function * replace hashing of conditions for brevity * fix tests * cleanup, add test file * remove unused slice capacity * make prefix treatments consistent * add nil-byte separator in object ids * hash user type restrictions for brevity * update comment string, use nil-byte separator for future-proofing * remove call to xxhash.new * adjustments for performance, consistency, and interface ergonomics. * make condition hash generation more efficient. * add clarifying comments for size caluculations * fix builder growth calculations to match original intentions * update outdated comment * don't hash potentially zero values * Revert "don't hash potentially zero values" This reverts commit 2ad6c5b796bc20a82c1414c5146c3c708330eefa. * add condition key separator unconditionally * patch test expectations for new key structure * export V2IteratorCachePrefix, use in tests --------- Co-authored-by: justin <justin.cohen@okta.com> Co-authored-by: Joshua Jones <joshua.jones@okta.com> fix: unintentional zeroing of slice values by setting slice to nil (openfga#3135) increase the check v2 trace information fidelity (openfga#3134) feat: add datastore ping and ping retry configurations (openfga#3113) fix: prevent v2Check strategies returning spurious false on context cancellation (openfga#3128) Signed-off-by: Saad Hussain <saad.hussain@okta.com> fix(authn/oidc): refresh JWKS on unknown kid to handle key rotation (openfga#3101) fix: v2Check falls back to v1 on errors (openfga#3126) fix: don't cache false results from cancelled-context goroutines in v2Check (openfga#3125) Signed-off-by: Saad Hussain <saad.hussain@okta.com> make union cache key unique by including the node input's label (openfga#3117) Signed-off-by: Saad Hussain <saad.hussain@okta.com> Co-authored-by: Saad Hussain <saad.hussain@okta.com> fix: shadow v2check and check use the same trace (openfga#3118) fix: bump go toolchain version to 1.26.3 (openfga#3115) chore: add more spans/attributes to v1 and v2 Check (openfga#3116) Signed-off-by: Saad Hussain <saad.hussain@okta.com> fix: add matches attribute to shadowv2Check and Check spans (openfga#3114) fix: use the same `request_id` for shadow traces in v2Check (openfga#3110) release: update changelog for release `v1.15.1` (openfga#3112) feat: reuse MySQL container across tests (openfga#3042) fix: close all channels opened thus far, before return on error (openfga#3111) chore: Add more spans/attributes to v2Check (openfga#3102) Signed-off-by: Saad Hussain <saad.hussain@okta.com> fix: ensure acquired limiter token is released on throttle context cancelation (openfga#3106) fix: cancel context before waiting on worker pool in ResolveUnionEdges (openfga#3105) fix: replace golang.org/x/exp/maps with stdlib maps to resolve govet inline errors (openfga#3104) fix: v2Check EdgeCacheKey collisions (openfga#3097) Signed-off-by: Saad Hussain <saad.hussain@okta.com> fix: expose context errors when they can be the potential cause of an underlying datastore error (openfga#3096) chore(deps): bump the dependencies group across 1 directory with 2 updates (openfga#3093) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> fix: move subproblem cache lookup from ResolveUnionEdges into ResolveUnion (openfga#3095) chore(deps): bump the dependencies group with 4 updates (openfga#3092) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> fix: error handler panic (openfga#3091) release: update changelog for release `v1.15.0` (openfga#3090) chore(deps): bump the dependencies group across 1 directory with 4 updates (openfga#3087) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> fix: v2Check correctly uses query cache even when cache controller is disabled (openfga#3086) Signed-off-by: Saad Hussain <saad.hussain@okta.com> chore(deps): bump the dependencies group across 1 directory with 7 updates (openfga#3081) Signed-off-by: dependabot[bot] <support@github.com> chore(deps): bump github.com/jackc/pgx/v5 from 5.9.1 to 5.9.2 (openfga#3085) Signed-off-by: dependabot[bot] <support@github.com> chore(deps): bump grpc-ecosystem/grpc-health-probe from v0.4.47 to v0.4.48 in the dependencies group across 1 directory (openfga#3065) Signed-off-by: dependabot[bot] <support@github.com> feat: try to use UDS internally between HTTP server and gRPC server (openfga#2937) feat: add jitter to internal cache TTLs to prevent thundering herd effects (openfga#3033) Signed-off-by: Asish Kumar <officialasishkumar@gmail.com> list objects pipeline edge pruning (openfga#3075) update toolchain go to 1.26.2 to address stdlib CVEs (openfga#3084) chore: add store ID and datastore query/item count to shadowV2Check log (openfga#3073) Signed-off-by: Saad Hussain <saad.hussain@okta.com> CI speed up (openfga#3062) Co-authored-by: Joshua Jones <joshua.jones.software@gmail.com> Co-authored-by: Joshua Jones <joshua.jones@okta.com> Add tracing to v2 Check planner strategy selection (openfga#3077) fix: v2Check honours `check-query-cache-enabled` flag (openfga#3070) Signed-off-by: Saad Hussain <saad.hussain@okta.com> feat: reuse PostgreSQL container across tests (openfga#3018) chore: fix reporter links in changelog (openfga#3069) release: update changelog for release `v1.14.2` (openfga#3068) fix: add null byte delimiter in contextual tuple cache keys and validation in v2Check (openfga#3064) release: update changelog for release `v1.14.1` (openfga#3060) chore(deps): bump the dependencies group across 1 directory with 7 updates (openfga#3056) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> fix: use a baseURL for AuthZEN configuration endpoint (openfga#3057) chore: replace docker with moby (openfga#3047) Iterator Cache V2: Storage Wrapper Pattern with Lock-Free Design (openfga#3016) Signed-off-by: Saad Hussain <saad.hussain@okta.com> Co-authored-by: Saad Hussain <saad.hussain@okta.com> Co-authored-by: Joshua Jones <joshua.jones.software@gmail.com> test: fix flaky condition test (openfga#3058) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> chore(deps): bump the dependencies group across 1 directory with 6 updates (openfga#3045) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> chore(deps): bump go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp from 1.41.0 to 1.43.0 (openfga#3054) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> feat: add graceful shutdown timeout configuration (openfga#2976) chore: update changelog to reflect playground off-by-default behavior (openfga#3053) chore: decouple Error() and Unwrap() (openfga#3051) perf: remove `fmt` from cache key generation (openfga#3006) perf: enhancements for list objects (openfga#3043) chore: remove stale notice file (openfga#3050) docs: update 1.14.0 for CVE fix (openfga#3046) feat: Add datastore throttling & concurrency limiting to v2Check (openfga#3035) Signed-off-by: Saad Hussain <saad.hussain@okta.com> release: update changelog for release `v1.14.0` (openfga#3040) batch check cache (openfga#3025) Merge commit from fork Also prevent enabling playground when the server requires authentication feat: add stats on tuple iterator query (openfga#3030) fix: remove unnecessary non-deterministic test (openfga#3038) remove unnecessary import (openfga#3032) perf: improve the intersection algorithm, reducing latency and memory use (openfga#3031) fix: ListObjects pipeline algorithm enhancements and fix for potential deadlock (openfga#3028) chore: Also update openfga/helm-charts in release script (openfga#3010) chore: update CICD to enforce GRPC healthprobe changes (openfga#2990) fix: SQL `TupleOperation` serialization and `pgx.ErrNoRows` error handling (openfga#3014) docs: update changelog for CVE-2026-33729 (openfga#3017) chore: output the diff after running keep-a-changelog (openfga#3015) chore(deps): bump the dependencies group across 1 directory with 11 updates (openfga#2998) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> chore(deps): bump the dependencies group across 1 directory with 10 updates (openfga#2999) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> release: update changelog for release `v1.13.1` (openfga#3002) Merge commit from fork * strip unicode control characters, encode context key length in cache key * add cache_key tests to ensure we escape control characters and encode context key length * run linter * docs: update changelog * Apply suggestion from @adriantam Co-authored-by: Adrian Tam <adrian.tam@okta.com> * Apply suggestion from @adriantam Co-authored-by: Adrian Tam <adrian.tam@okta.com> --------- Co-authored-by: Saad Hussain <saad.hussain@okta.com> Co-authored-by: Saad Hussain <saad.h@outlook.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> release: update changelog for release `v1.13.0` (openfga#2997) refactor: Separate caches for v1 and v2 Check (openfga#2968) Co-authored-by: Justin Cohen <justincoh@gmail.com> docs: fix typos in comments (openfga#2972) Signed-off-by: Artem Muterko <artem@sopho.tech> Co-authored-by: Adrian Tam <adrian.tam@okta.com> observability: aggregate message statistics for each list-objects sender into a single span (openfga#2993) Co-authored-by: Justin Cohen <justincoh@gmail.com> fix: capture panics in pipeline's base resolver, and return as errors. (openfga#2994) docs: fix typos in RELEASES.md and Makefile (openfga#2980) Co-authored-by: Adrian Tam <adrian.tam@okta.com> AuthZen v1.0 Implementation (openfga#2875) Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: Rokibul Hasan <mdrokibulhasan@appscode.com> Signed-off-by: Vihang Mehta <vihang@gimletlabs.ai> Co-authored-by: Karl Persson <kalle.persson92@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Maria Ines Parnisari <maria.inesparnisari@okta.com> Co-authored-by: Rokibul Hasan <mdrokibulhasan18@gmail.com> Co-authored-by: José Padilla <jose.padilla@okta.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> Co-authored-by: Vihang Mehta <vihang@gimletlabs.ai> Co-authored-by: Joshua Jones <joshua.jones.software@gmail.com> Co-authored-by: Justin Cohen <justincoh@gmail.com> release: update changelog for release `v1.12.1` (openfga#2992) chore(deps): bump google.golang.org/grpc from 1.79.1 to 1.79.3 (openfga#2988) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> chore: enforce minor version upgrade rule (openfga#2978) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> perf: tuple validation performance tweaks (openfga#2984) fix: support URI schemes in OTLP endpoint configuration (openfga#2981) refactor: remove custom pipes and replace with channels (openfga#2977) chore(docs): added caching docs (openfga#2664) Co-authored-by: Saad Hussain <saad.hussain@okta.com> release: update changelog for release `v1.12.0` (openfga#2974) chore: update toolchain go to 1.26.1 (openfga#2975) fix: update toolchain go to 1.25.8 to address stdlib CVEs (openfga#2971) fix: correct swapped format args in DecodeParameterType error message (openfga#2961) Signed-off-by: Artem Muterko <artem@sopho.tech> Co-authored-by: Adrian Tam <adrian.tam@okta.com> perf: small tweaks to tuple validation functions (openfga#2963) Co-authored-by: Vic-Dev <vmichellej@gmail.com> test: add tests for condition parameter type any with complex context structures (openfga#2959) Signed-off-by: Artem Muterko <artem@sopho.tech> test: add functional test for ReadAssertions API endpoint (openfga#2960) Signed-off-by: Artem Muterko <artem@sopho.tech> Co-authored-by: Adrian Tam <adrian.tam@okta.com> make configurable the maximum received grpc message size (openfga#2952) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> fix: set ExperimentalPipelineListObjects in experimentals by default (openfga#2957) fix: `cache_item_count` metric overcounting (openfga#2950) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> chore(deps): bump the dependencies group across 1 directory with 7 updates (openfga#2953) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> refactor: Make shadowV2Check final log clearer (openfga#2946) Move telemetry package to internal/telemetry (openfga#2938) Signed-off-by: Oleksandr Shestopal <ar.shestopal-oshegithub@gmail.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> chore(deps): bump the dependencies group across 1 directory with 3 updates (openfga#2956) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> fix: Resolve race condition in check reducers (openfga#2947) Co-authored-by: Adrian Tam <adrian.tam@okta.com> fix: gateway grpc client tls cert rotation (openfga#2951) Signed-off-by: Shashank Goel <goelshashank13@gmail.com> fix: disable LO pipeline if ff has it set for a store (openfga#2945) chore(deps): bump the dependencies group across 1 directory with 4 updates (openfga#2949) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> fix: various random fixes (openfga#2942) refactor: check using weighted graph (openfga#2816) Co-authored-by: Yissell Garma <yissell.garma@okta.com> release: update changelog for release `v1.11.6` (openfga#2939) feat: enable pipeline algorithm by default (openfga#2921) add tests to exercise reported bug (openfga#2934) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Adrian Tam <adrian.tam@okta.com> refine AGENTS.md to make it more concise with higher value. (openfga#2936) Co-authored-by: Justin Cohen <justincoh@gmail.com> migrate grpc dial context to NewClient (openfga#2714) Co-authored-by: Adrian Tam <adrian.tam@okta.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> chore(deps): bump filippo.io/edwards25519 from 1.1.0 to 1.1.1 (openfga#2935) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

docs: update caching docs

dbfd051

Signed-off-by: Saad Hussain <saad.hussain@okta.com>

saad-h1 requested a review from a team as a code owner June 4, 2026 18:04

Copilot AI review requested due to automatic review settings June 4, 2026 18:04

saad-h1 added the Skip-Changelog Indicates that a PR does not need a changelog entry label Jun 4, 2026

Copilot started reviewing on behalf of saad-h1 June 4, 2026 18:04 View session

Copilot AI reviewed Jun 4, 2026

coderabbitai Bot reviewed Jun 4, 2026

View reviewed changes

Comment thread docs/caching.md Outdated

senojj reviewed Jun 4, 2026

View reviewed changes

saad-h1 added 2 commits June 4, 2026 20:53

Merge branch 'main' into docs/caching-2026-06

55e6493

docs: fix statement about storeID in invariantHash

7572084

Signed-off-by: Saad Hussain <saad.hussain@okta.com>

senojj approved these changes Jun 5, 2026

View reviewed changes

saad-h1 merged commit c452374 into main Jun 5, 2026
39 of 44 checks passed

saad-h1 deleted the docs/caching-2026-06 branch June 5, 2026 16:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: update caching docs#3163

docs: update caching docs#3163
saad-h1 merged 3 commits into
mainopenfga/openfga:mainfrom
docs/caching-2026-06openfga/openfga:docs/caching-2026-06Copy head branch name to clipboard

saad-h1 commented Jun 4, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 4, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 inconclusive)

Uh oh!

Copilot AI left a comment

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

codecov Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

senojj left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Search code, repositories, users, issues, pull requests...

Uh oh!

Conversation

saad-h1 commented Jun 4, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What problem is being solved?

How is it being solved?

What changes are made to solve it?

References

Review Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 inconclusive)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

senojj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

saad-h1 commented Jun 4, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 4, 2026 •

edited

Loading

codecov Bot commented Jun 4, 2026 •

edited

Loading