⚡️(yhub) cache authz verdicts to cut backend calls on connections

A connection to the collaboration server — websocket or http fallback —
can chain up to three calls to the backend: users/me, documents/{id} and
accesses/me. On the fallback poll path this repeats every few seconds per
client, and the calls bypass the backend throttling (X-Y-Provider-Key),
so a busy instance hammers the backend unthrottled.

Add an opt-in authz cache in yhub, three layers with different
invalidation physics:

- identity: users/me -> userid, in-process per replica, keyed on the
  SHA-256 of the Cookie header. Nothing can invalidate it and nothing
  needs to: a dead session fails closed at the abilities fetch. Kills
  the users/me call on every poll and REST request.
- abilities: the documents/{id} verdict, in the shared redis per
  (document, cookie hash). The one payload a stale entry would
  over-grant, so reset-connections deletes every entry of the document
  BEFORE triggering the recheck — the recheck then re-runs authorize
  against post-invalidation state and the revocation stays immediate.
  The TTL is only the backstop for a lost kick. Anonymous callers share
  one entry per document: what they may do is the link configuration,
  and nothing about them distinguishes one from another.
- access date: the accesses/me created_at bounding the history a user
  may read. Append-mostly by design, invalidated by user-scoped kicks.

All three TTLs default to 0: caching off, byte-identical behavior.
Backend refusals (403/404) are cached like any verdict, so a client
that lost access costs one call per TTL instead of one per poll. An
unanswered backend is never cached — an error is not a permission
decision. Keys carry only sha256 hashes, never session ids.

Warm-state connections and polls make zero backend calls. Watch
yhub_authz_cache_lookups_total{layer,result} against
yhub_backend_request_duration_seconds{route} before raising the TTLs.

Author: lunika

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to
 
 - ✨(backend) add a setting for the http fallback polling interval #2827
 - ✨(backend) add a setting to turn off awareness on the http fallback #2827
+- ⚡️(yhub) cache authz verdicts to cut backend calls on connections #2832
 
 ### Changed
 

documentation/env.md

@@ -202,6 +202,9 @@ documents what each of them changes.
 | YHUB_TASK_DEBOUNCE_MS         | How long an update waits on the redis stream before a worker persists it                                                                                 | 10000                  |
 | YHUB_MIN_MESSAGE_LIFETIME_MS  | How long persisted updates stay replayable from redis rather than read back from postgres                                                                | 60000                  |
 | YHUB_BACKEND_REQUEST_TIMEOUT_MS | How long a call to the backend (`users/me`, `documents/{id}`, `accesses/me`) may take before it is given up on and the caller told to retry, in ms   | 5000                   |
+| YHUB_IDENTITY_CACHE_TTL_MS     | How long a resolved identity is reused for the same session cookie, in ms. 0 disables this layer (default)                                                | 0                      |
+| YHUB_ABILITIES_CACHE_TTL_MS    | How long a document abilities verdict is served from cache, in ms, before it is re-read; deleted cluster-wide by the reset-connections kick. 0 disables it | 0                      |
+| YHUB_ACCESS_CACHE_TTL_MS       | How long an access date (the history bound) is served from cache, in ms. 0 disables it (default)                                                          | 0                      |
 | SENTRY_DSN                    | Sentry DSN, unset disables it: the SDK is then not even loaded. Can be read from a file with SENTRY_DSN_FILE                                             |                        |
 | SENTRY_ENVIRONMENT            | Environment the events are reported under                                                                                                                | production             |
 | SENTRY_RELEASE                | Release the events are reported under. Detected by the SDK when unset                                                                                    |                        |

src/helm/impress/values.yaml

@@ -1189,6 +1189,9 @@ yhub:
   ## @extra yhub.envVars.YHUB_TASK_DEBOUNCE_MS How long an update waits on the redis stream before a worker persists it, in ms (default: 10000)
   ## @extra yhub.envVars.YHUB_MIN_MESSAGE_LIFETIME_MS How long persisted updates stay replayable from redis, in ms (default: 60000)
   ## @extra yhub.envVars.YHUB_BACKEND_REQUEST_TIMEOUT_MS How long a call to the backend may take before yhub gives up on it and tells the caller to retry, in ms (default: 5000)
+  ## @extra yhub.envVars.YHUB_IDENTITY_CACHE_TTL_MS How long a resolved identity is reused for the same session cookie, in ms; 0 disables this layer (default)
+  ## @extra yhub.envVars.YHUB_ABILITIES_CACHE_TTL_MS How long a document abilities verdict is served from cache, in ms, before it is re-read; deleted cluster-wide by the reset-connections kick; 0 disables it
+  ## @extra yhub.envVars.YHUB_ACCESS_CACHE_TTL_MS How long an access date (the history bound) is served from cache, in ms; 0 disables it (default)
   ## @extra yhub.envVars.SOFT_MIGRATION Set to "true" to seed rooms from the legacy Django/S3 document store on first access
   ## @extra yhub.envVars.LEGACY_S3_ENDPOINT_URL Required by SOFT_MIGRATION, endpoint of the legacy Django media bucket, without a path (e.g. https://s3.example.com)
   ## @extra yhub.envVars.LEGACY_S3_ACCESS_KEY_ID Required by SOFT_MIGRATION, read access to the legacy bucket (or LEGACY_S3_ACCESS_KEY_ID_FILE)

src/yhub-server/README.md

@@ -274,6 +274,58 @@ were configurable:
 | `YHUB_TASK_DEBOUNCE_MS` | `10000` | How long an update waits on the stream before a worker persists it |
 | `YHUB_MIN_MESSAGE_LIFETIME_MS` | `60000` | How long persisted updates stay replayable from redis |
 | `YHUB_BACKEND_REQUEST_TIMEOUT_MS` | `5000` | How long a call to the Docs backend may take before it is given up on |
+| `YHUB_IDENTITY_CACHE_TTL_MS` | `0` | How long a resolved `users/me` identity is reused for the same Cookie header (authz cache, off by default) |
+| `YHUB_ABILITIES_CACHE_TTL_MS` | `0` | How long a `documents/{id}` verdict is served from cache before it is re-read (deleted by `reset-connections`, see the authz-cache section) |
+| `YHUB_ACCESS_CACHE_TTL_MS` | `0` | How long an `accesses/me` date is served from cache before it is re-read |
+
+### The authz cache
+
+Off by default, the three TTLs above turn on a cache that keeps the
+connection path from calling the backend on every request. The three payloads
+it holds go stale differently, so each has its own layer:
+
+- **identity** (`users/me` → userid, keyed on the SHA-256 of the whole
+  `Cookie` header): kept in-process, per replica, no invalidation. Nothing on
+  the backend side can name the key, and nothing needs to — a logged-out
+  caller is at most one TTL stale, and the stale userid then fails closed at
+  the abilities fetch, which answers 401 and denies. One nuance of that
+  staleness: a caller editing a *public* document keeps their userid for up
+  to one TTL after a server-side logout, so those edits stay attributed to
+  the logged-out user instead of `anonymous` — access is unaffected.
+- **abilities** (`documents/{id}` → the verdict): the one payload a stale
+  entry would over-grant, so it lives in yhub's own redis — the one already
+  carrying the document streams, shared between the replicas and never
+  touched by the backend — under
+  `{prefix}:authz:abilities:{org}:{docid}:{sha256(cookie)}`, and the
+  shortest TTL bounds what any lost invalidation can leave behind. Anonymous
+  callers share one entry per document (`…:anon`): what they may do is the
+  document's link configuration, and nothing about them distinguishes one
+  from another.
+- **access** (`accesses/me` → the stored `created_at` bounding history
+  reads): append-mostly, keyed per user, invalidated by user-scoped kicks.
+
+**Revocation stays immediate.** The backend's `reset-connections` kick — a
+plain HTTP POST, it reads nothing of yhub's stores — reaches one replica,
+which — before triggering the recheck — deletes every `authz` entry of that
+document from yhub's redis (see `invalidateDocumentAuthz`); the recheck
+itself is distributed to all replicas through the same redis stream, and
+every recheck re-runs `authorize`, which then reads post-invalidation
+state. The abilities TTL is therefore only the backstop for a lost kick,
+not the mechanism. One bounded window remains: an
+`authorize` in flight on another replica when the DEL runs can SET its
+pre-revocation verdict back after the deletion, admitting a connection opened
+in exactly that instant for at most one abilities TTL — the kick's recheck
+then re-checks it, and a fetch the backend answered *after* the revocation
+commits caches the fresh denial, not the grant.
+
+A backend refusal (403/404) is cached like any other verdict: a client that
+lost access costs one call per TTL, not one per poll. A backend that did not
+answer is never cached — an error is not a permission decision.
+
+Watch `yhub_authz_cache_lookups_total{layer,result}` alongside
+`yhub_backend_request_duration_seconds{route}`: the hit rate tells you what
+the cache is saving, and the remaining `users_me` / `document` /
+`accesses_me` rates tell you what is left.
 
 **Concurrency** multiplies with the number of processes running a worker, since
 redis hands each task to exactly one of them: the two are interchangeable up to