feat: sync policies with redisson

[caro3801]

⚠️ This description is stale it was made for choosing between plugin and inhouse solution. Since inhouse dev has be chosen, see new description and test plan in comments below

Adds a Redis pub/sub watcher (PolicyWatcher) that broadcasts Casbin policy changes across server instances in real time, replacing the previous polling-only approach. When a project grant or revoke mutates the policy, the watcher publishes a reload signal on a Redis topic so all instances apply the change immediately rather than waiting for the next poll cycle.

Also fixes several correctness issues in the session and project-admin layers surfaced during review.

What changed

• PolicyWatcher - new RTopic-backed Watcher that publishes instanceId:reload on mutations and subscribes to reload events; suppresses self-triggered reloads; logs WARN when publish fails so the operator knows other instances won't see the change until the next poll cycle
• Authorizer - new Watcher constructor; startAutoLoadPolicy(intervalMs) backstop for partition recovery; implements Closeable
• CommonMode - wires PolicyWatcher when busType=REDIS; registers both watcher and authorizer with addCloseable; calls startAutoLoadPolicy for failsafe reload
• ProjectAdminServiceImpl - findUser helper checks SQL then Redis (usersWritable.find) so OAuth2-only users (never in SQL) are found during grant/revoke; casbinWithRollback now rolls back both SQL and Redis on Casbin failure; actionable hint in UserNotFoundException when --authUsersProvider is not UsersInRedis
• UsersInRedis.saveOrUpdate - WATCH/MULTI/EXEC retry loop eliminates the TOCTOU race between ttl() and EXEC; extend-only TTL rule (never shorten an active session); bounded to 10 attempts
• DatashareCliOptions / GlobalOptions / StageRunCommand - --policyReloadInterval option (default 30 s fallback poll)

Tests added

• PolicyWatcherTest - unit tests for publish, self-suppress, listener registration
• AuthorizerRedisSyncIntTest - integration test: two Authorizer instances share a real Redis; a grant on instance A is visible on instance B within 500 ms
• UsersInRedisTest - WATCH retry loop, extend-only TTL, persistent key handling
• ProjectAdminServiceImplTest - CLI option parsing, OAuth2 user fallback, hint message
• AuthorizerTest - watcher notification, polling lifecycle (close() stops timer)

Important
When busType is not REDIS, it falls into the else path on line 320 of CommonMode.java:

• No PolicyWatcher — no Redis pub/sub, no cross-instance notifications
• Authorizer(adapter, interval) — creates an authorizer with only periodic polling via startAutoLoadPolicy(interval)
• If --policyReloadInterval is also unset (defaults to "0"), then interval=0 → startAutoLoadPolicy is a no-op → the authorizer is completely static: policy is loaded once at startup and never refreshed

So the behavior matrix:

busType	--policyReloadInterval	Result
REDIS	unset (0)	Event-driven only; no polling backstop
REDIS	e.g. 30000	Event-driven + polling backstop every 30 s
anything else	unset (0)	Static - loaded once, never refreshed
anything else	e.g. 30000	Polling-only every 30 s

In a single-server deploy without Redis (busType=MEMORY), the static case is fine - there's only one instance so there's nothing to sync. But if someone runs multiple servers without Redis, grants won't propagate to other instances unless --policyReloadInterval is set.

---

Differences between branches feat/casbin-redis-watcher and feat/casbin-redis-watcher-ex

	feat/casbin-redis-watcher	feat/casbin-redis-watcher-ex
Watcher implementation	Hand-rolled PolicyWatcher using Redisson RTopic	SafeWatcherEx wrapping jcasbin-redis-watcher-ex library's RedisWatcherEx
Watcher interface	Watcher (basic — one update() method)	WatcherEx (fine-grained — separate callbacks per operation: updateForAddPolicy, updateForRemovePolicy, etc.)
Self-suppress	Yes — each message is prefixed with instanceId; the publisher ignores its own messages	Handled internally by the library
New dependency	None — reuses Redisson already in the project	Adds jcasbin-redis-watcher-ex 1.1.0 + 3 Netty exclusions to avoid classpath conflicts
Redis client	Redisson (already a project dependency)	Lettuce (bundled inside jcasbin-redis-watcher-ex)
Failure visibility	PolicyWatcher.update() catches and logs WARN	SafeWatcherEx catches all updateFor*() and logs WARN (necessary because jcasbin swallows them silently)
Close/cleanup	PolicyWatcher implements Closeable — removes the RTopic listener	Library handles cleanup internally; no Closeable needed on the watcher
Polling backstop	startAutoLoadPolicy(interval)	Same
Code owned	~60 lines, fully in-repo	~70 lines of shim wrapping a third-party class

Key trade-off: the -watcher branch adds zero dependencies and keeps full control; the -watcher-ex branch delegates to the library but requires managing Netty exclusions and adds a shim layer purely to recover the error visibility that jcasbin strips away. The WatcherEx granularity (per-operation callbacks) is the only functional advantage of the library, and Datashare doesn't currently use those callbacks for anything beyond triggering a reload.

[caro3801]

feat(casbin): Redis RTopic watcher for event-driven policy sync

Summary

Replaces polling-only Casbin policy reload with a Redis pub/sub watcher, so all Datashare nodes pick up permission changes in near-real time when running in Redis mode. Includes a refactor of the user session layer to cleanly separate read-only user lookup from mutable session management.

Changes

Core feature: Redis policy watcher

• Add PolicyWatcher that subscribes to a Redis RTopic and triggers Casbin policy reloads on publication; falls back to 30s polling when busType is not REDIS
• Suppress self-triggered reloads (the node that wrote the policy change skips its own notification)
• Expose --policyReloadInterval on the CLI; fall back to DEFAULT_POLICY_RELOAD_INTERVAL when unset
• Disable Casbin's verbose built-in logging by default (SyncedEnforcer enables it implicitly)
• Roll back Redis state on Casbin failure during project grant/revoke

Session layer refactor

• Extract UsersIdProviderCache interface + UsersIdProviderRedisCache implementation — session-based auth filters now use this focused interface instead of the broader UsersWritable
• Make UsersInRedis and UsersInDb read-only; mutable session writes go through UsersIdProviderCache only
• UserStore replaces Repository as the user management abstraction in session and admin code
• Fix saveOrUpdate TTL handling: preserve persistent/long-lived entries, drop the WATCH/retry complexity, always reset TTL on update
• Scope the Redis session cache to OAuth2 mode only

Mode wiring

• CommonMode now provides Users and UsersIdProviderCache as separate bindings (activated when busType=REDIS)
• Remove UsersWritable binding from CommonMode; ProjectAdminServiceImpl and UserAdminServiceImpl updated accordingly
• Close resources in LIFO order

CLI

• Remove duplicate options from ServerOptions that were already declared in GlobalOptions
• Surface an actionable hint when UserNotFoundException is thrown during first OAuth2 grant

Tests

• PolicyWatcherTest — unit tests for watcher lifecycle and self-reload suppression
• AuthorizerRedisSyncIntTest — integration test verifying cross-node policy sync via Redis
• UsersIdProviderRedisCacheTest — covers session cache read/write/TTL behaviour (replaces UsersInRedisTest)
• Extended ProjectCommandTest and DatashareCommandTest for CLI option handling

[caro3801]

Casbin sync manual test scenarios

Context

The feat/casbin-redis-watcher branch adds cross-instance Casbin policy sync via a Redis RTopic.
When one instance grants or revokes a project, all other instances receive a pub/sub notification
and reload their policy from the database. The writing instance suppresses its own notification.

This file is a manual test guide covering three auth/user-provider combinations to confirm the
sync works end-to-end in each configuration.

---

Common setup

Prerequisites: Redis, PostgreSQL, and (for scenario 1) the OAuth2 provider are running.

Both instances share the same Redis and PostgreSQL. Instance 1 runs on port 8080, instance 2 on
port 8081. Both must have --busType REDIS so the RTopic watcher is active.

Common flags used in all scenarios:

-d ~/Datashare/Data/
--redisAddress redis://redis:6379
--dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin"
--messageBusAddress redis://redis:6379
--busType REDIS
--mode SERVER

To confirm sync happened on instance 2, watch its logs for a line like:
INFO Authorizer - policy reloaded

Or make an API call to instance 2 after the grant and verify the project appears in the user's
project list.

---

Scenario 1 — OAuth2 auth

Users authenticate via the IdP. Their session is cached in Redis by the OAuth2 filter.
In OAuth2 mode --authUsersProvider is not needed: grant/revoke automatically looks up the user
from the session cache. The user must have logged in at least once before being granted.

Start instance 1 (port 8080)

./run.sh app start \
  --auth oauth \
  -d ~/Datashare/Data/ \
  --redisAddress redis://redis:6379 \
  --messageBusAddress redis://redis:6379 \
  --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
  --busType REDIS \
  --mode SERVER \
  --oauthClientId datashareuidforseed \
  --oauthClientSecret datasharesecretforseed \
  --oauthAuthorizeUrl http://<OAuth>:3001/oauth/authorize \
  --oauthTokenUrl http://<OAuth>:3001/oauth/token \
  --oauthApiUrl http://<OAuth>:3001/api/v1/me.json \
  --oauthCallbackPath /auth/callback

Start instance 2 (port 8081)

./run.sh app start \
--auth oauth \
-d ~/Datashare/Data/ \
--redisAddress redis://redis:6379 \
--messageBusAddress redis://redis:6379 \
--dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
--busType REDIS \
--mode SERVER \
--oauthClientId datashareuidforseed \
--oauthClientSecret datasharesecretforseed \
--oauthAuthorizeUrl http://<OAuth>:3001/oauth/authorize \
--oauthTokenUrl http://<OAuth>:3001/oauth/token \
--oauthApiUrl http://<OAuth>:3001/api/v1/me.json \
--oauthCallbackPath /auth/callback \
--port 8081

Same flags, add --port 8081.

Test steps

1. Log in to instance 1 at http://localhost:8080 via OAuth2. This creates the Redis session key.
2. Note the login (e.g. jdoe) from the user list.
3. Grant the project from CLI:

   ./run.sh project grant --project local-datashare --user jdoe \
     --redisAddress redis://redis:6379 \
     --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
     --busType REDIS

4. Check instance 2 logs for policy reloaded.
5. Check instance 1 logs — it should NOT show policy reloaded (self-suppression).
6. Call GET http://localhost:8081/api/project with jdoe's session cookie and confirm
   local-datashare appears.
7. Revoke and repeat verification.

---

Scenario 2 — Form auth, database user provider

Users are stored in PostgreSQL. Authentication uses the form login filter.

Create the test user

./run.sh user create \
  --login jdoe \
  --email jdoe@example.org \
  --name "Jane Doe" \
  --password secret \
  --provider local \
  --authUsersProvider database \
  --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin"

Start instance 1 (port 8080)

./run.sh app start \
  --auth form \
  --authUsersProvider database \
  -d ~/Datashare/Data/ \
  --redisAddress redis://redis:6379 \
  --messageBusAddress redis://redis:6379 \
  --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
  --busType REDIS \
  --mode SERVER

Start instance 2 (port 8081)

./run.sh app start \
--auth form \
--authUsersProvider database \
-d ~/Datashare/Data/ \
--redisAddress redis://redis:6379 \
--messageBusAddress redis://redis:6379 \
--dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
--busType REDIS \
--mode SERVER \
--port 8081

Same flags, add --port 8081.

Test steps

1. Log in to instance 1 at http://localhost:8080 with jdoe / secret.
2. Grant from CLI:

   ./run.sh project grant --project local-datashare --user jdoe \
     --authUsersProvider database \
     --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
     --busType REDIS \
     --redisAddress redis://redis:6379

3. Check instance 2 logs for policy reloaded.
4. Check instance 1 logs — no reload (self-suppression).
5. Log in to instance 2 at http://localhost:8081 and confirm local-datashare is accessible.
6. Revoke and repeat verification.

./run.sh project revoke --project local-datashare --user jdoe \
  --authUsersProvider database \
  --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
  --busType REDIS \
  --redisAddress redis://redis:6379

---

Scenario 3 — Form auth, Redis user provider

Users are stored in Redis. Authentication uses the form login filter with password hashed in Redis.

Create the test user

./run.sh user create \
  --login jdoe \
  --email jdoe@example.org \
  --name "Jane Doe" \
  --password secret \
  --provider local \
  --authUsersProvider redis \
  --redisAddress redis://redis:6379 \
  --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin"

Confirm: redis-cli -h redis GET jdoe should return a JSON blob with uid, email, and password.

Start instance 1 (port 8080)

./run.sh app start \
  --auth form \
  --authUsersProvider redis \
  -d ~/Datashare/Data/ \
  --redisAddress redis://redis:6379 \
  --messageBusAddress redis://redis:6379 \
  --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
  --busType REDIS \
  --mode SERVER

Start instance 2 (port 8081)

./run.sh app start \
--auth form \
--authUsersProvider redis \
-d ~/Datashare/Data/ \
--redisAddress redis://redis:6379 \
--messageBusAddress redis://redis:6379 \
--dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
--busType REDIS \
--mode SERVER \
--port 8081

Same flags, add --port 8081.

Test steps

1. Log in to instance 1 at http://localhost:8080 with jdoe / secret.
2. Grant from CLI:

   ./run.sh project grant --project local-datashare --user jdoe \
     --authUsersProvider redis \
     --redisAddress redis://redis:6379 \
     --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
     --busType REDIS

3. Check instance 2 logs for policy reloaded.
4. Check instance 1 logs — no reload (self-suppression).
5. Log in to instance 2 at http://localhost:8081 and confirm local-datashare is accessible.
6. Revoke and repeat verification.

   ./run.sh project revoke --project local-datashare --user jdoe \
     --authUsersProvider redis \
     --redisAddress redis://redis:6379 \
     --dataSourceUrl "jdbc:postgresql://postgres/datashare?user=admin&password=admin" \
     --busType REDIS

---

Expected log output on instance 2 after grant

INFO  PolicyWatcher - Received policy-update notification from remote instance, reloading

Expected log output on instance 1 after grant (self-suppression)

Nothing — own notifications are suppressed at DEBUG level only. No INFO line appears.

[pirhoo]

Great work!

I've made only two non-blocking suggestions :)

[pirhoo]

suggestion: remove the prior listener before registering a new one, e.g. guard with if (listenerId != -1) topic.removeListener(listenerId); at the top of each overload, or track a List<Integer> and remove all on close().

[pirhoo]

suggestion: this creates a discreptencies with the default values in the legacy joptsimple parser, we could change it to:

long interval = parseInt(propertiesProvider.get(POLICY_RELOAD_INTERVAL_OPT)
        .orElse(String.valueOf(DEFAULT_POLICY_RELOAD_INTERVAL)));

Where DEFAULT_POLICY_RELOAD_INTERVAL is 30_000. This is important to change so default value is the same both with joptsimple and picocli.

[caro3801]

This is a particular case, in event driven, we don't want backstop polling policy reload by default (0), unless specified.
Howere joptsimple and picocli should behave the same, I'm fixing the initial value in joptsimple

[lschim]

Great work !!