feat(user-display): persistent DB cache + Keycloak resolver hook (Phase 1+2 wiring)

Closes "ток мой UUID отображается" pain reported on staging today: any reviewer / maker / publisher / actor whose JWT sub never landed in the JVM cache shows up as a short UUID in audit / reviews / changelog / events / history / record drawer / webhook detail / record version history. Restart the pod and even captured users disappear. Three-tier resolve, replacing the in-memory-only cache that was the "Альтернатива (на будущее)" TODO in the original UserDisplayService: 1. JVM ConcurrentHashMap hot cache (~µs, capped at 10k). 2. user_display_cache Postgres table (~ms, persistent across restart). New migration 0023 — sub PK + preferred_username + name + email + source enum + synced_at + updated_at, plus an index on synced_at for the scheduled bulk sync that lands later. 3. Keycloak Admin API on-demand (Phase 2) — dispatched to optional KeycloakUserResolver bean. When the bean isn't wired (no Keycloak admin creds yet), the third tier is a no-op and UserCell falls back to short UUID exactly like before. Source enum on every row — JWT_CAPTURE / KEYCLOAK_SYNC / KEYCLOAK_ON_DEMAND — so the eventual scheduled sync can prefer JWT- captured rows (richest claims as the user actually saw them) and the on-demand fallback can be distinguished from bulk sync in audits. JwtUserCaptureFilter and UserDisplayController are unchanged — they already used UserDisplayService.put / find with the same signatures. The behavior change is invisible at the API layer: same /admin/users/ {sub}/display endpoint, same 404 user_not_cached on miss; persistence just survives pod restart now. mergeFrom on UserDisplayCacheEntry deliberately keeps the existing non-blank field when an update brings null — Keycloak sync may have a richer email than JWT capture; don't blank it out. Phase 2 will land a KeycloakAdminUserResolver impl + vault secret plumbing on this same branch. Phase 3 (scheduled bulk sync via @Scheduled) is a separate sprint — it needs the Keycloak admin client already in place.
2026-05-14 14:45:14 +03:00
parent 455ca2ff26
commit ec0c74afdf
6 changed files with 374 additions and 39 deletions
@@ -0,0 +1,24 @@
+package cloud.nstart.terravault.ordinis.restapi.service;
+
+import java.util.Optional;
+
+/**
+ * Phase 2 contract: resolve sub → user info via Keycloak Admin API. The
+ * implementation (Phase 2) will be an HTTP client using a service-account
+ * client + role {@code view-users} on realm {@code nstart}.
+ *
+ * <p>{@link UserDisplayService} consumes this as an optional dependency —
+ * if no bean exists in the context, the third resolve tier is skipped and
+ * UserCell falls back to short UUID. This keeps the Phase 1 (DB cache only)
+ * deployment runnable without Keycloak admin creds.
+ *
+ * <p>Implementations must throw {@link RuntimeException} on transient errors
+ * (network, 5xx) so the caller can log and continue. Return {@link Optional#empty()}
+ * for definitive 404 — sub does not exist in the realm.
+ */
+public interface KeycloakUserResolver {
+
+  Optional<KeycloakUser> findById(String sub);
+
+  record KeycloakUser(String sub, String preferredUsername, String name, String email) {}
+}
@@ -1,69 +1,165 @@
 package cloud.nstart.terravault.ordinis.restapi.service;

+import cloud.nstart.terravault.ordinis.domain.userdisplay.UserDisplayCacheEntry;
+import cloud.nstart.terravault.ordinis.domain.userdisplay.UserDisplayCacheEntry.Source;
+import cloud.nstart.terravault.ordinis.domain.userdisplay.UserDisplayCacheRepository;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;

 import java.time.OffsetDateTime;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;

 /**
- * In-memory кэш user display info (sub → preferredUsername / name / email),
- * заполняемый из JWT claims на каждом authenticated запросе через
- * {@link cloud.nstart.terravault.ordinis.restapi.auth.JwtUserCaptureFilter}.
+ * Three-tier resolve sub → display info:
+ * <ol>
+ *   <li>JVM ConcurrentHashMap hot cache (~µs).</li>
+ *   <li>{@code user_display_cache} Postgres table (~ms, persistent across pod restart).</li>
+ *   <li>Keycloak Admin API on-demand fallback (~10-50ms, Phase 2 — wired
+ *       via optional {@link KeycloakUserResolver} bean).</li>
+ * </ol>
 *
- * <p><b>Зачем:</b> audit log + record drafts хранят actor как JWT
- * {@code sub} UUID. Frontend (UserCell в audit / reviews) показывает short
- * UUID + tooltip — плохой UX. Этот сервис позволяет резолвить sub →
- * читаемое имя для display, не запрашивая Keycloak Admin API на каждое
- * отображение.
+ * <p>JwtUserCaptureFilter calls {@link #put} on every authenticated request
+ * → updates both hot cache and DB (idempotent merge).
 *
- * <p><b>Trade-offs:</b>
- * <ul>
- *   <li>In-memory — пропадает на pod restart. Постепенно заполняется
- *       обратно по мере того как users делают запросы. Для display это OK.</li>
- *   <li>Без Keycloak Admin API — не видим users которые ни разу не
- *       логинились в Ordinis. Display fallback → short UUID.</li>
- *   <li>Stale: если user сменит preferred_username в Keycloak, кэш
- *       обновится только на следующий его login + request.</li>
- * </ul>
+ * <p>Phase 3 (TBD): scheduled bulk sync from Keycloak will call
+ * {@link #upsertFromKeycloak} for every realm user every 6h to refill
+ * stale entries.
 *
- * <p>Альтернатива (на будущее): миграция 0023 user_display_cache table
- * + periodic Keycloak sync. Сделать когда станет реально нужно
- * (пока display name никто не редактирует постоянно).
+ * <p>Hot cache reads from DB lazily on miss — no warm-up at startup
+ * (would block readiness probe + Keycloak might be cold). First request
+ * for each sub after restart pays a single DB hit.
 */
@Service
 public class UserDisplayService {

-  /** Cap чтобы не держать миллионы entries в RAM при abuse. ~100 байт per
-   *  entry → 10k = 1MB. Eviction policy — LRU не нужен, hash без bound — fine. */
-  private static final int SOFT_CAP = 10_000;
-
-  private final ConcurrentHashMap<String, UserDisplayInfo> cache = new ConcurrentHashMap<>();
+  private static final Logger log = LoggerFactory.getLogger(UserDisplayService.class);

  /**
-   * Обновляет / создаёт запись для {@code sub}. Idempotent. Вызывается
-   * из {@code JwtUserCaptureFilter} на каждом authenticated request —
-   * стоимость ~O(1) hash put.
+   * Cap чтобы не держать миллионы entries в RAM при abuse. ~100 байт per
+   * entry → 10k = 1MB. Eviction policy — LRU не нужен, hash без bound — fine.
+   * DB table сама разрастается без cap (см. migration 0023 design notes).
   */
+  private static final int HOT_CACHE_CAP = 10_000;
+
+  private final ConcurrentHashMap<String, UserDisplayInfo> hotCache = new ConcurrentHashMap<>();
+  private final UserDisplayCacheRepository repository;
+  private final KeycloakUserResolver keycloakResolver;
+
+  public UserDisplayService(UserDisplayCacheRepository repository,
+                            @Autowired(required = false) KeycloakUserResolver keycloakResolver) {
+    this.repository = repository;
+    this.keycloakResolver = keycloakResolver;
+    if (keycloakResolver == null) {
+      log.info("UserDisplayService: KeycloakUserResolver not wired — three-tier resolve "
+          + "will fall back to short-UUID for users that never made an authenticated "
+          + "request to ordinis.");
+    }
+  }
+
+  /**
+   * Capture from JWT (called per-request by JwtUserCaptureFilter). Cheap and
+   * idempotent. Writes to hot cache + DB. Source is always JWT_CAPTURE here —
+   * KEYCLOAK_SYNC / KEYCLOAK_ON_DEMAND have their own write paths.
+   */
+  @Transactional
  public void put(String sub, String preferredUsername, String name, String email) {
    if (sub == null || sub.isBlank()) return;
-    if (cache.size() >= SOFT_CAP) return; // soft cap, don't grow unbounded
-    cache.put(sub, new UserDisplayInfo(
-        sub,
-        nullIfBlank(preferredUsername),
-        nullIfBlank(name),
-        nullIfBlank(email),
-        OffsetDateTime.now()));
+    upsert(sub, preferredUsername, name, email, Source.JWT_CAPTURE);
  }

+  /**
+   * Three-tier lookup. Returns empty only if sub absent in all three tiers
+   * AND Keycloak is unreachable (transient — caller's UserCell will fall
+   * back to short UUID, retry next time it renders).
+   */
+  @Transactional
  public Optional<UserDisplayInfo> find(String sub) {
    if (sub == null || sub.isBlank()) return Optional.empty();
-    return Optional.ofNullable(cache.get(sub));
+
+    // Tier 1: hot cache
+    UserDisplayInfo hot = hotCache.get(sub);
+    if (hot != null) return Optional.of(hot);
+
+    // Tier 2: DB
+    Optional<UserDisplayCacheEntry> dbHit = repository.findById(sub);
+    if (dbHit.isPresent()) {
+      UserDisplayInfo info = toInfo(dbHit.get());
+      cacheHot(sub, info);
+      return Optional.of(info);
+    }
+
+    // Tier 3: Keycloak Admin on-demand (Phase 2)
+    if (keycloakResolver != null) {
+      try {
+        Optional<KeycloakUserResolver.KeycloakUser> kc = keycloakResolver.findById(sub);
+        if (kc.isPresent()) {
+          KeycloakUserResolver.KeycloakUser u = kc.get();
+          UserDisplayInfo info = upsert(sub, u.preferredUsername(), u.name(), u.email(),
+              Source.KEYCLOAK_ON_DEMAND);
+          return Optional.of(info);
+        }
+      } catch (RuntimeException e) {
+        log.warn("Keycloak on-demand lookup failed for sub={}: {}", sub, e.getMessage());
+      }
+    }
+
+    return Optional.empty();
  }

-  /** Stats для observability — сколько users закэшировано. */
-  public int size() {
-    return cache.size();
+  /**
+   * Phase 3 entry point — scheduled sync writes every realm user with
+   * Source.KEYCLOAK_SYNC. Same idempotent merge as {@link #put}.
+   */
+  @Transactional
+  public void upsertFromKeycloak(String sub, String preferredUsername, String name, String email) {
+    if (sub == null || sub.isBlank()) return;
+    upsert(sub, preferredUsername, name, email, Source.KEYCLOAK_SYNC);
+  }
+
+  /** Stats для observability. */
+  public int hotCacheSize() {
+    return hotCache.size();
+  }
+
+  // --- internals ---
+
+  private UserDisplayInfo upsert(String sub, String preferredUsername, String name,
+                                 String email, Source source) {
+    OffsetDateTime now = OffsetDateTime.now();
+    UserDisplayCacheEntry entry = repository.findById(sub).orElse(null);
+    if (entry == null) {
+      entry = new UserDisplayCacheEntry(sub,
+          nullIfBlank(preferredUsername),
+          nullIfBlank(name),
+          nullIfBlank(email),
+          source,
+          now);
+    } else {
+      entry.mergeFrom(preferredUsername, name, email, source, now);
+    }
+    repository.save(entry);
+    UserDisplayInfo info = toInfo(entry);
+    cacheHot(sub, info);
+    return info;
+  }
+
+  private void cacheHot(String sub, UserDisplayInfo info) {
+    if (hotCache.size() < HOT_CACHE_CAP) {
+      hotCache.put(sub, info);
+    }
+  }
+
+  private static UserDisplayInfo toInfo(UserDisplayCacheEntry e) {
+    return new UserDisplayInfo(
+        e.getSub(),
+        e.getPreferredUsername(),
+        e.getName(),
+        e.getEmail(),
+        e.getUpdatedAt());
  }

  private static String nullIfBlank(String s) {