parse-stack-next 5.6.0 → 5.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7ea05ce0688ca7c1df6a1077162478dfee52e33d9fac77c7480c5ca818c9eb8
-  data.tar.gz: 71e61f7e70da94793dae9d741a3e5d29ffc7f9cd45f2adee6c96cd98b5ac2d24
+  metadata.gz: 7cb6a2c813f0a1b2d624852680651ed289f7aac282fa24e246b28d0ed9e69383
+  data.tar.gz: a3984ae30555af28eadfdc19fa936103bb252bad332b0ddb8ead163277ae4bde
 SHA512:
-  metadata.gz: c723fbb9589ce57c7651fab142bed386f3a2070d39fc20887fc40b50f676ccb0041e9b758611e8b75d0a9202095de318ce2bbae35e41015be519209d9d2628dd
-  data.tar.gz: dbbc09ee718630415da1ab329168fc1c10d5d9cf20ad09e4129b2518087231206ca84d7d5ecd5e1a27f66e2fb75d3704b856592fcd43c6d2f7711fa20c0dba1b
+  metadata.gz: d19428000255676b8a5f10ee0087bf3b6d21216c499f56d895d1ee50a646985a4297b725807b2b19878a8576415c8e1551471d34fa236e9bf90170e6e13abed5
+  data.tar.gz: 5db3159d3da214300df9e21760ae871f070f6a79d961fe9e082b5160dd0bd2c07cba5d64656791b961ab2c347e9ebf5151eb607fcf0a3768587a3c382476000e

data/CHANGELOG.md

@@ -1,5 +1,494 @@
 ## parse-stack-next Changelog
 
+### 5.7.1
+
+#### Cache-invalidation webhooks no longer break every application hook for the same trigger
+
+- **FIXED**: `Parse::Cache::Invalidation` raised `NoMethodError: undefined
+  method 'guard'` on every `_User`, `_Role`, and `_Session` trigger it
+  registered, and the failure was not contained. A webhook handler block is
+  bound to the payload before it runs, so the bare `guard` / `bump_subject` /
+  `subject_id` calls in the handler bodies resolved against
+  `Parse::Webhooks::Payload`, which defines none of them. `guard`'s own
+  `rescue` never ran, because it lives inside the body that was never entered,
+  so the error escaped into the route dispatcher. The dispatcher folds a
+  trigger's handlers with `Array#map`, which abandons the collection on the
+  first raise, and these triggers install during `Parse.setup` and therefore
+  sit ahead of every application handler for the same trigger. One
+  unresolvable method name silently prevented an application's own
+  `after_save "_User"` hook from running at all, so any work downstream of it
+  stopped without a visible cause. The handlers now call the module on an
+  explicit receiver captured in a local, which is independent of whatever
+  `self` the dispatcher binds. Applications that set
+  `cache_invalidation_hooks: false` to work around this can remove it.
+- **FIXED**: The invalidation tests dispatched handlers with a plain
+  `Proc#call`, which leaves `self` bound to the module the block closed over,
+  so every one of them passed against handlers that could not run in
+  production. They now dispatch through the real handler invocation and fail
+  against the broken code.
+
+#### Whether one failing `after_*` handler stops the rest is now a setting
+
+- **NEW**: `Parse::Webhooks.abort_after_callbacks_on_error` decides whether an
+  exception raised by one `after_*` handler prevents the remaining handlers for
+  that trigger from running. It defaults to `true`, which is the existing
+  behavior, so nothing changes on upgrade. Set it to `false` to isolate
+  handlers from each other: each one runs regardless of what an earlier one
+  raised, and the failure is reported with a warning and a
+  `parse.webhooks.handler_error` notification instead of being swallowed
+  silently. This was previously not a decision at all but a side effect of
+  folding handlers with `Array#map`, which abandons the collection on the
+  first raise. Registration order is not fully under an application's control,
+  since the SDK's own cache-invalidation triggers install during `Parse.setup`
+  and therefore sit ahead of handlers registered by application files loaded
+  later, so a single raising handler could silently prevent an application's
+  own hooks from running with nothing logged to say they had been skipped.
+- **BEHAVIOR**: The setting governs only whether later handlers still run.
+  Neither mode reverts anything: an `after_*` trigger fires once the write has
+  already committed, so there is no version of this setting that can undo a
+  save. `before_*` dispatch is untouched, and only the accumulating,
+  non-rejectable triggers (`after_save`, `after_delete`, `after_logout`) can
+  hold more than one handler in the first place. A rejectable `before_*`
+  trigger must deny if any handler denies, so its raise must continue to
+  abort.
+
+#### Failed transactions restore the object they rolled back
+
+- **FIXED**: A failed `Parse::Object.transaction` left the in-memory object
+  holding its modified values. The rollback snapshotted `Parse::Object#attributes`
+  and restored it, but that method returns a schema map of field name to type
+  symbol rather than values, so nothing was ever restored. Property values
+  live in `@<field>` instance variables; those are now what the rollback
+  captures and restores, including values nested inside arrays and hashes,
+  relation operation queues, and properties whose ivar did not exist before
+  the transaction. State is captured when the object first enters the
+  transaction rather than at `batch.add`, so the documented pattern of
+  mutating an object and adding it afterwards rolls back correctly.
+- **FIXED**: A failed transaction also left the object with broken change
+  tracking. Restoring the schema map defined `@attributes`, which is the
+  instance variable `ActiveModel::Dirty` keys its behavior on: once defined it
+  builds an `AttributeMutationTracker` over that hash instead of the
+  `ForcedMutationTracker` a `Parse::Object` needs, and `clear_changes!` then
+  called `forgetting_assignment` on the `[key, value]` pairs `Hash#map`
+  yields. Both call sites rescue and warn, so every rollback quietly
+  downgraded the object rather than failing. The rollback no longer defines
+  `@attributes`.
+- **FIXED**: The mongo-direct role-graph integration test gated on
+  `ANALYTICS_DATABASE_URI`, a production variable name the test stack never
+  sets, so both of its traversal assertions skipped on every run while the
+  per-file reporter still reported the file as passing. It now reads
+  `PARSE_TEST_MONGO_URI` like every other mongo-direct integration file and
+  still honors `ANALYTICS_DATABASE_URI` as an override.
+
+### 5.7.0
+
+#### Cache keys move into a reserved, app-scoped keyspace
+
+- **NEW**: `Parse::Cache::Keyspace` owns the physical layout of the response,
+  identity, and role-cache keys the SDK writes to a shared cache backend along
+  with the glob patterns that clear them again, so key generation and eviction
+  can no longer drift apart. Keys are laid out as
+  `parse-stack:v1:<app_scope>[:<namespace>]:<family>[:T:<tenant>]:<rest>`, with
+  `cache`, `idn`, and `role` as the families. `app_scope` is a digest of the
+  application id and the server URL rather than the raw values, so two apps
+  sharing one Redis no longer collide when neither sets a `cache_namespace:`,
+  and an application id carrying a glob metacharacter cannot silently widen a
+  SCAN pattern. Enable it with `cache_keyspace: true` on `Parse.setup`. Without
+  that option the previous key shape and behavior are preserved exactly, so the
+  upgrade is inert until an operator opts in.
+- **FIXED**: `Parse::Client#clear_cache!` no longer reaches `FLUSHDB` **when a
+  keyspace is configured**. The wrapper fell through to a full flush whenever no
+  namespace was set on it, which is the default, and the caching middleware
+  could hold a `cache_namespace:` the wrapper knew nothing about. On a shared
+  Redis that destroyed co-tenant data, and it deleted the SDK's own
+  `parse-stack:foc:v1:*` create-locks, removing `first_or_create!` mutual
+  exclusion for any lock held at the time with no error anywhere. With
+  `cache_keyspace: true`, every clear is a scoped SCAN inside the client's own
+  keys and can only ever delete a subset of them, and `scope:` narrows within
+  that keyspace rather than widening past it. `flush_db!` remains the explicit
+  opt-in for a full flush.
+
+  **Without `cache_keyspace: true` the old behavior is unchanged**, including
+  the `FLUSHDB` fallback when no namespace is set, and a plain Moneta store
+  passed as `cache:` is still cleared in full because it has no notion of key
+  scoping. Opting in is what fixes it. This is stated plainly because a reader
+  who upgrades and changes nothing else is still exposed.
+- **NEW**: The keyspace-bound `Parse::Cache::ScopedView` exposed as
+  `client.sdk_cache` accepts `family:` and `tenant:` on `#clear`, and
+  `#delete_matching(pattern)` evicts by glob. A pattern outside the view's own
+  keyspace is a no-op rather than an unscoped scan, so the narrower API cannot
+  become a back door to the blast radius the keyspace exists to close.
+- **CHANGED**: Scoped eviction issues `UNLINK` rather than `DEL` when the
+  client exposes it, so reclaiming a large eviction runs on a Redis background
+  thread instead of stalling the server, falling back to `DEL` on older
+  clients. Each eviction emits a `parse.cache.evict`
+  `ActiveSupport::Notifications` event carrying `pattern_digest`, `deleted`,
+  and `duration_ms`, so an operator can see how much a clear actually removed
+  and how long it took. The pattern is digested rather than logged because it
+  embeds a URL digest and a cache tenant.
+- **CHANGED**: `Parse::Cache::Redis` refuses a Moneta `prefix:` option. It
+  rewrites the physical key layout underneath the wrapper, which would break
+  every SCAN pattern the class builds and quietly restore the unscoped clearing
+  the keyspace exists to prevent. Use `cache_namespace:` instead.
+
+#### The response cache's auth separation is now enforced by construction
+
+- **IMPROVED**: The auth discriminator on a response-cache key is now
+  structural rather than incidental. A master-key request bypasses ACL, CLP, and
+  `protectedFields`, so for the same URL it returns a strictly fuller body than a
+  session-token request, and two session-token requests can differ from each
+  other through `protectedFields` entity rules and row ACLs. Previous versions
+  already separated these, prefixing the key with `mk:` or a token digest, so
+  this is not a fix for a cache that crossed those boundaries. What changes is
+  that the separation can no longer be lost by accident:
+  `Parse::Cache::Keyspace#cache_key` has no default for `auth:` and raises
+  rather than building a key without one, and the generic key builder refuses
+  the response-cache family outright. A raw session token is still never
+  accepted as a key segment, only a truncated digest.
+- **FIXED**: A non-GET write now invalidates the resource for every caller. The
+  previous invalidation could name only the anonymous variant, the master-key
+  variant, and the caller's own, and had no way to enumerate the entries of
+  sessions the process had never seen, so a write by one user left every other
+  user reading a stale copy until the TTL expired. Every auth variant of one
+  resource now shares a key prefix, so a scan-capable store evicts all of them
+  with a single pattern. A GET miss still clears only the siblings it can name,
+  since evicting resource-wide there would destroy other sessions' valid
+  entries on every cache miss.
+- **CHANGED**: Invalidation also deletes the pre-keyspace form of a key, so a
+  rolling deploy does not leave old workers serving entries that a new worker's
+  write should have killed. Pass `cache_delete_legacy_variants: false` to stop
+  once every old worker is drained.
+
+#### Identity and role caching share one backend across processes
+
+- **NEW**: `Parse::Cache::ScopedView#identity` and `#roles` return
+  `Parse::Cache::SubCache` planes shaped for a client's
+  `Parse::Authorization::Context#identity_cache` and `#role_cache` slots. The
+  keyspace-bound view is exposed as `client.sdk_cache`; installing its planes
+  replaces the default per-process memory caches with a shared backend, so
+  every Puma worker and every dyno resolves a session token or a role closure
+  against the same view instead of each holding its own. Each plane writes
+  inside its own keyspace family, so clearing one can reach neither the other
+  nor the response cache.
+- **NEW**: Each plane carries a per-subject generation counter and a plane-wide
+  epoch, both for invalidating entries that cannot be named. Identity entries
+  are keyed by session token and no reverse map from user id exists, so a
+  `_User` write cannot enumerate them. Bumping that user's generation
+  invalidates all of them in constant time, including tokens the process has
+  never resolved, and without a master-key `_Session` query. The epoch answers
+  the different question of whether an entry written before a given moment is
+  stale, which is what judging a foreign cache entry requires. It never moves
+  backwards, so clock skew between workers cannot re-admit an entry a previous
+  invalidation had rejected.
+
+#### Role and session invalidation no longer depends on application discipline
+
+- **NEW**: `Parse::Cache::Invalidation` registers the webhook triggers that
+  keep the identity and role planes honest: `after_save` and `after_delete` on
+  `_Role`, `after_save` and `after_delete` on `_User`, and `after_logout` on
+  `_Session`. It installs alongside the keyspace and is disabled with
+  `cache_invalidation_hooks: false`. The previous contract asked applications
+  to call `Parse::AtlasSearch::Session.invalidate` and `invalidate_user_roles`
+  from their own logout and role-mutation paths. That depended on every
+  application remembering, and it missed role changes made by any other client,
+  including a mobile SDK, the dashboard, and Node cloud code. The triggers
+  cover writes from every source Parse Server sees. TTL remains the backstop,
+  since the triggers require a webhook endpoint Parse Server can reach and
+  hooks registered against it: this is TTL and hooks, not TTL or hooks.
+- **FIXED**: Registering a webhook handler replaced any handler already
+  registered for the same trigger instead of composing with it, for every
+  trigger except `after_save` and `after_delete`. A second `after_logout`
+  registration silently discarded the first, with file load order deciding the
+  winner and nothing warning about it. Non-rejectable `after_*` triggers now
+  accumulate handlers the way `after_save` always has. Rejectable `before_*`
+  triggers deliberately keep replacing: a composite of those must deny if any
+  handler denies, and folding the results with `.last` would discard an earlier
+  rejection.
+
+#### Optional read of Parse Server's own role cache
+
+- **NEW**: `Parse::Cache::UpstreamRoles` reads the `<appId>:role:<userId>`
+  closure Parse Server writes for itself, so a caller holding a trusted user
+  id, most usefully from a webhook payload, can skip the role-graph walk by
+  calling `client.sdk_cache.upstream_roles.roles_for`. Attach it by passing
+  `parse_cache_url:` to `Parse::Cache::Redis`. Without that option nothing
+  upstream is read.
+- **NEW**: Role resolution itself does not consume the upstream value in this
+  release. `Parse::AtlasSearch::Session` always computes its own closure, and
+  the only built-in integration is `compare_upstream_roles`, which reads the
+  upstream entry purely to emit a `parse.cache.role_compare` event carrying
+  the size of each set and their symmetric difference. Nothing about the ACL
+  decision changes. This is deliberate: the upstream value becomes an
+  authorization input the moment it is consumed, so it stays observable-only
+  until the two closures have been reconciled against real traffic. The
+  comparison is inert unless both the switch and a reader are set.
+- **NEW**: The attachment is strictly read-only. The SDK never writes that
+  keyspace, because its own closure is depth-capped while Parse Server's is
+  not, so injecting a strict subset into a cache the server reads back as
+  authoritative would under-permission users in windows that are close to
+  undiagnosable.
+- **NEW**: Every failure mode degrades to a miss so the caller recomputes the
+  closure, and none of them fails open. The decoded value must be a JSON array
+  of `role:`-prefixed names within the configured count and length caps. An
+  entry whose remaining PTTL cannot be read, is negative, or exceeds the
+  configured ceiling is rejected, because an entry whose age cannot be derived
+  is not one to trust as an authorization input. An entry written before the
+  SDK's last role invalidation is rejected by the plane epoch, because Parse
+  Server does not clear its own role cache on a `_Role` delete. The reader
+  needs only `+get` and `+pttl`, so the credential can be restricted to the
+  role keyspace.
+- **NEW**: `Parse::Cache::Redis#verify_upstream_isolation!` probes whether the
+  two endpoints resolve to the same Redis database, first by scanning the
+  SDK's own database for a key shaped like one Parse Server would have
+  written, then, if that finds nothing, by writing a random sentinel to the
+  SDK's database and asking the upstream connection to read it back. The scan
+  alone can only ever prove sharing: an empty result is equally consistent
+  with a separate database and with a shared one on which Parse Server has
+  not yet cached a role closure, which is the state of every freshly deployed
+  stack. Only the sentinel establishes the negative. The method returns
+  `true` for established isolation, `false` for established sharing, and
+  `:unknown` when neither could be shown, which is what a credential
+  restricted to `~<appId>:role:*` produces: the sentinel read is denied, and
+  a denial says nothing about which database denied it. `:unknown` is truthy,
+  so callers branching on truthiness are unaffected. Comparing URLs would be
+  defeated by `localhost` against `127.0.0.1`, by CNAMEs, by Sentinel and
+  Cluster topologies, and by a database selected outside the URL. A shared
+  database is a real hazard: on Parse Server 9.10.0 and earlier a `_Role` write
+  clears the cache with `FLUSHDB`, which takes the SDK's cached responses and
+  its `first_or_create!` create-locks with it. See
+  https://github.com/parse-community/parse-server/issues/10617. The probe warns
+  rather than refusing to boot, since the hazard disappears entirely on a
+  server carrying the scoped-clear fix.
+
+#### Role graph queries now accept the public API's default depth
+
+- **CHANGED**: Raised the MongoDB role-graph query default and hard cap from 6
+  to 10, matching the existing `Parse::Role.all_for_user` default. A ceiling
+  below that default made the opt-in MongoDB fast path raise `ArgumentError`
+  for any caller who did not pass an explicit `max_depth:`. The existing
+  query-time budget continues to bound traversal work.
+
+#### Users and roles can inspect effective object access
+
+- **NEW**: `Parse::User` and `Parse::Role` expose `can_read?`, `can_write?`,
+  and `can_delete?` predicates backed by the new `Parse::Access.check` policy
+  preflight. Each check combines the target ACL with its class's `get`,
+  `update`, or `delete` CLP; delete uses the ACL write grant. Direct and
+  inherited user/role grants are supported, as are Parse Server's
+  `pointerFields`, `readUserFields`, and `writeUserFields` branch semantics.
+  `Parse::Access::Decision` and the instance `access_decision` /
+  `access_decisions` helpers expose `allowed`, `denied`, or `unknown` results;
+  the boolean predicates accept only a definite allow and otherwise fail
+  closed. Full rows with no ACL retain Parse Server's public default, while
+  pointers, partial rows, unresolved schema/role evidence, and unsupported
+  system-class rules remain unknown. `_User` reads and mutations honor Parse
+  Server's self-access rules, and role-only checks cannot claim a concrete
+  member's pointer or `_User` self permission. CLP cache entries are isolated
+  by Parse application so identically named classes cannot leak policy across
+  clients. These helpers are advisory: the eventual Parse Server request is
+  still authoritative.
+
+#### Test infrastructure
+
+- **CHANGED**: The integration test stack pins Parse Server 9.10.0, up from
+  9.9.0.
+- **CHANGED**: The integration stack now backs Parse Server's own session,
+  user, and role caches with Redis instead of its in-process adapter, so the
+  `<appId>:role:<userId>` entries the upstream reader consumes are observable
+  from outside the container. It occupies database 1 while the SDK's cache and
+  create-locks stay on database 0, and the adapter refuses to start on database
+  0. Leaving the URL unset keeps the in-process adapter and the previous
+  behavior.
+
+#### Session-token and role resolution move off Atlas Search and onto the client
+
+- **NEW**: `Parse::Authorization` is the new owner of session-token resolution
+  and role-closure expansion. `client.authorization` returns a
+  `Parse::Authorization::Context`, one per `Parse::Client` and never shared.
+  Session-token resolution and role-closure expansion were originally written
+  inside `Parse::AtlasSearch::Session`, because `$search` was the first
+  feature to run aggregations straight against MongoDB and therefore the
+  first to enforce ACLs itself. Everything since reached back through it:
+  `Parse::ACLScope` called into the Atlas Search namespace, and
+  `Parse::MongoDB.aggregate` calls `Parse::ACLScope`, so
+  `Parse::Query#results_direct` on a plain query with no `$search` anywhere
+  in it depended on Atlas Search to decide who the caller was.
+  `Parse::Authorization` is now the sole owner; Atlas Search is one consumer
+  of it alongside every other mongo-direct path.
+- **FIXED**: Two `Parse::Client` instances addressing two different Parse
+  applications no longer share one identity cache and one role cache. The
+  previous caches, TTLs, and resolver were module-level globals reachable
+  only through `Parse.client`, so a session token minted by a secondary
+  application's Parse Server could be validated against the default
+  application's `/users/me` call and its cached role closures. Each
+  `Parse::Authorization::Context` now holds a back-reference to the one
+  client it authorizes for and resolves exclusively through it.
+- **NEW**: `Parse::Authorization.configure(identity_cache:, role_cache:,
+  identity_cache_ttl:, role_cache_ttl:, upstream_role_reader:,
+  compare_upstream_roles:)` configures the default client's context, as a
+  boundary convenience matching the existing single-application shorthand
+  `Parse::AtlasSearch.search(..., client: Parse.client)`. It is not the
+  source of truth: configure a secondary application with
+  `other_client.authorization.configure(...)` directly.
+  `Parse::Authorization.resolve(session_token, client:)` requires `client:`
+  with no default, because below the API boundary there is no such thing as
+  "the" client, and defaulting it there is exactly the bug this release
+  closes.
+- **CHANGED**: The identity plane is renamed `identity_cache` (was
+  `session_cache`) and its TTL setting `identity_cache_ttl` (was
+  `session_cache_ttl`), because it stores one user id per session token and
+  never any `_Session` row or session object, and the old name led readers to
+  reason about `_Session` semantics that were never involved.
+  `Parse::Authorization::Resolved`, `::MemoryCache`, and `::InvalidSession`
+  replace `Parse::AtlasSearch::Session::Resolved`, `::MemoryCache`, and
+  `::InvalidSession`.
+- **DEPRECATED**: `Parse::AtlasSearch.session_cache=`, `.role_cache=`,
+  `.session_cache_ttl`, `.role_cache_ttl`, `.upstream_role_reader`,
+  `.compare_upstream_roles`, and `Parse::AtlasSearch::Session.resolve` /
+  `.invalidate` / `.invalidate_user_roles` / `.reset_caches!` all still work
+  and delegate to the default client's context, so existing code keeps
+  running unchanged. Being module-level, they can only ever address
+  `Parse.client`; code running against a secondary application must call
+  `other_client.authorization` directly. Slated for removal in 6.0.
+  `Parse::AtlasSearch.require_session_token` is not part of this move: it
+  decides whether `$search` may run anonymously, which is Atlas Search's own
+  policy, not an identity concern.
+
+#### Cache clears can no longer widen past what was asked
+
+- **FIXED**: `Parse::Cache::Redis#clear` accepted `family:` and `tenant:` and
+  silently ignored them, falling through to the unnamespaced branch and
+  issuing `FLUSHDB`. A request to clear one family therefore wiped the whole
+  database, including other applications' entries and the
+  `parse-stack:foc:v1:*` create-locks, whose loss silently removes
+  `first_or_create!` mutual exclusion. `clear` now raises `ArgumentError` for
+  that combination and points callers at
+  `backend.scoped(keyspace).clear(family:)`, so a request to narrow a clear
+  can no longer widen it.
+- **FIXED**: `cache_keyspace: true` on a store that cannot produce a scoped
+  view, such as a plain `Moneta.new(:Redis)`, left the store installed bare.
+  Key composition still worked, so the deployment looked correctly
+  keyspaced, but `Parse::Client#clear_cache!` called the store's own
+  unrestricted `clear`, which on Redis is `FLUSHDB`. Such stores are now
+  wrapped in `Parse::Cache::KeyspacedStore`, which clears by enumerating
+  keys under the keyspace where the store supports `each_key`, and raises
+  `Parse::Cache::UnscopedClearRefused` where it cannot, rather than widening
+  the clear to compensate.
+
+#### The upstream-isolation probe stops mistaking silence for isolation
+
+- **FIXED**: `Parse::Cache::Redis#verify_upstream_isolation!` reported an
+  empty shared database as isolated. The SCAN probe can only ever prove
+  sharing: an empty result is equally consistent with a genuinely separate
+  database and with a shared one on which Parse Server has not yet cached a
+  role closure, which is the state of every freshly deployed stack and
+  exactly when an operator runs the check. The method now falls back to
+  writing a random sentinel into the SDK's own database and asking the
+  upstream connection to read it back, and returns `true` for established
+  isolation, `false` for established sharing, or `:unknown` when neither
+  could be shown, which is what a credential restricted to
+  `~<appId>:role:*` produces since the sentinel read is denied and a denial
+  says nothing about which database denied it. `:unknown` is truthy, so
+  callers branching on truthiness are unaffected.
+
+#### Generation keys stop growing without bound
+
+- **FIXED**: Generation keys in `Parse::Cache::SubCache` never expired. One
+  key is written per user id on every `_User` webhook, which is unbounded
+  Redis growth on a public signup flow. Generation keys now expire at twice
+  the plane's entry TTL: expiry resets a counter to 0, which is also the
+  value for a subject never bumped, so a counter that outlived its entries
+  would let an entry written at generation 0 compare current again and
+  reappear after having been invalidated. `set` clamps any longer per-call
+  TTL to keep that invariant true.
+
+### Behavior Notes
+
+- Authorization is client-owned as of this release: `client.authorization`
+  owns session-token resolution and role-closure expansion for that client
+  alone. `Parse::MongoDB` (the URI, the driver connection, and collection
+  selection) stays process-global in this release; the Mongo connection
+  itself becomes client-owned in 6.0.
+- **NEW**: Because those two now have different owners, `Parse::MongoDB`
+  records the Parse application it was configured for and
+  `Parse::MongoDB.verify_client!` refuses a mongo-direct query authorized by
+  a client belonging to a different one, raising
+  `Parse::MongoDB::ClientMismatch`. Per-client authorization and a
+  process-global connection are each safe alone and dangerous together: a
+  secondary client would resolve its token correctly against its own
+  application, build a correct `_rperm` allow-set for one of its users, then
+  run the pipeline against the other application's database, where those user
+  ids and role names match rows they have nothing to do with. Nothing about
+  that looks like a failure, which is why it fails closed instead. A
+  connection with no recorded binding, and a caller that cannot be
+  identified, both proceed, so single-application deployments and master-mode
+  calls made before `Parse.setup` are unaffected. The guard becomes
+  unnecessary in 6.0.
+- **NEW**: `Parse::Query#results_direct`, `#count_direct`, `#distinct_direct`,
+  `#distinct_direct_pointers`, and `Parse::MongoDB.aggregate` accept `client:`
+  alongside the existing auth keywords. It names the authorization context
+  that resolves the call, and it is carried onto the `Parse::ACLScope`
+  resolution so the binding check above has something to compare. Without it
+  every direct read resolved through `Parse.client`, which left the check
+  unable to see a second client at all and therefore unable to catch the case
+  it was written for. Omitting the keyword resolves through `Parse.client` as
+  before.
+- `cache_keyspace: true` is the switch for the new cache layout, scoped
+  clearing, invalidation hooks, and shared identity and role planes. Left
+  unset, those cache behaviors are exactly as they were. `parse_cache_url:` is
+  separately opt-in, and without it no upstream endpoint is contacted.
+- `parse_cache_url:` must address a different Redis database from `url:`. The
+  two are read and written by different processes with different clearing
+  semantics, and until the scoped-clear fix lands upstream a single `_Role`
+  write on the shared database destroys the SDK's cache and its create-locks.
+- Create-locks deliberately keep their historical `parse-stack:foc:v1:` prefix
+  and are not relocated into the keyspace. Moving them would have two workers
+  compute different lock keys during a rolling deploy, so they would stop
+  contending on the same key and lose mutual exclusion for the length of the
+  deploy.
+- The built-in upstream-role integration is compare-only and never changes
+  `permission_strings` or an ACL decision. A caller that directly consumes
+  `roles_for` as authorization input makes that database part of its trust
+  base, so restrict the credential to `+get +pttl` on `<appId>:role:*`.
+- Webhook-driven invalidation requires the application to expose a webhook
+  endpoint Parse Server can reach and to have registered the hooks. Where it is
+  unregistered or unreachable, the TTL is the only bound on staleness.
+
+### Code Example
+
+```ruby
+# The SDK's own cache on database 0, Parse Server's cache read-only on 1.
+store = Parse::Cache::Redis.new(
+  url: "redis://localhost:6379/0",
+  parse_cache_url: "redis://localhost:6379/1",
+)
+
+Parse.setup(
+  server_url: ENV.fetch("PARSE_SERVER_URL"),
+  application_id: ENV.fetch("PARSE_APP_ID"),
+  master_key: ENV.fetch("PARSE_MASTER_KEY"),
+  cache: store,
+  expires: 10,
+  cache_keyspace: true,   # reserved keyspace, scoped clearing, hook install
+)
+
+# Warns when both URLs resolve to the same Redis database.
+store.verify_upstream_isolation!
+
+# Share identity and role resolution across every process. Each client owns
+# its own Parse::Authorization::Context, so a second client pointed at a
+# second application configures its own view the same way.
+view = Parse.client.sdk_cache   # the scoped view derived at setup
+Parse::Authorization.configure(
+  identity_cache: view.identity(ttl: 3600),
+  role_cache: view.roles(ttl: 30),
+)
+
+Parse.client.clear_cache!        # scoped SCAN, because a keyspace is configured
+view.clear(family: :role)        # one plane
+view.clear(family: :cache, tenant: "acme")
+```
+
 ### 5.6.0
 
 #### Voyage embeddings reach the Atlas endpoint, video, and streamed media