PrincipalRoleBindingsChangedEvent

An internal event published to invalidate per-tenant role binding caches. This ensures role changes are reflected immediately, preventing stale

Overview

The PrincipalRoleBindingsChangedEvent is an internal system event used to signal that a principal's role bindings have been modified. Its primary purpose is to trigger the immediate invalidation of cached role binding information, ensuring that permission changes take effect without delay.

This event solves the problem of cache staleness. Without it, a principal whose administrative permissions have been revoked might retain access for the remaining Time-To-Live (TTL) of the cached entry. By publishing this event as part of the modification operation, the system forces the cache to drop the stale entry, guaranteeing that subsequent access checks fetch the most up-to-date bindings from the source of truth.

The event is published by the service responsible for managing role bindings and is consumed by the per-tenant bindings cache.

How It Works

When an API publisher initiates a change to a principal's role bindings, the system follows a specific sequence to ensure data consistency.

A request is made to add, revoke, or re-activate a role binding for a principal within a specific tenant.
The role management service processes the request and durably stores the change.
On the same thread that performed the write operation, the service constructs and publishes a PrincipalRoleBindingsChangedEvent. The event payload contains the tenantId corresponding to the modified bindings.
A listener, typically the per-tenant bindings cache, receives this event.
The listener uses the tenantId from the event to identify and evict the corresponding stale cache entry.
Any subsequent request for that principal's permissions will result in a cache miss, forcing the system to load the newly updated role bindings from the persistent data store.

NOTE

The event is published synchronously on the writer's thread before the originating operation completes. This design prevents race conditions by ensuring the cache is invalidated before any other process can read the stale, pre-modification data.

The following diagram illustrates this data flow:

sequenceDiagram
    participant API Publisher
    participant Role Management Service
    participant Event System
    participant Bindings Cache

    API Publisher->>Role Management Service: Request to modify role binding
    activate Role Management Service
    Role Management Service->>Role Management Service: Persist binding change
    Role Management Service->>Event System: Publish PrincipalRoleBindingsChangedEvent(tenantId)
    Event System->>Bindings Cache: Deliver event
    activate Bindings Cache
    Bindings Cache->>Bindings Cache: Evict cache entry for tenantId
    deactivate Bindings Cache
    deactivate Role Management Service
    Role Management Service-->>API Publisher: Acknowledge change

Event Definition

The event is defined as a Java record. Its structure is as follows:

public record PrincipalRoleBindingsChangedEvent(UUID tenantId) {
}

Payload Fields

The event payload contains a single field.

Name	Type	Default	Required	Description
`tenantId`	`UUID`	—	Yes	The unique identifier for the tenant whose principal role bindings changed.

Tagsreference

All SOAP-to-REST docs