From 705a7fc6770733362b334986d915fb77005993cc Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Thu, 23 Jul 2026 10:59:13 -0400 Subject: [PATCH 01/12] fix(cache): add configurable refresh buffer to StorageCredentialCache Adds STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS (default 0, preserving existing half-lifetime behavior). When non-zero, credentials are evicted before their remaining validity drops below the threshold. Closes #2046 --- .../core/config/FeatureConfiguration.java | 16 +++++ .../storage/cache/StorageCredentialCache.java | 32 ++++++--- .../cache/StorageCredentialCacheEntry.java | 3 +- .../cache/StorageCredentialCacheTest.java | 69 +++++++++++++++++++ 4 files changed, 108 insertions(+), 12 deletions(-) diff --git a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java index 38162c8719c..b8f995c3b88 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java @@ -517,6 +517,22 @@ public static void enforceFeatureEnabledOrThrow( .defaultValue(30 * 60) // 30 minutes .buildFeatureConfiguration(); + public static final FeatureConfiguration + STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS = + PolarisConfiguration.builder() + .key("STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS") + .description( + "Minimum remaining validity (in seconds) that a cached storage credential must " + + "have before it is considered stale and evicted. When non-zero, credentials " + + "are removed from the cache this many seconds before they expire, ensuring " + + "clients always receive credentials with at least this much validity left. " + + "When zero (the default), credentials are kept for half of their remaining " + + "lifetime, which is the legacy behavior. Must be less than " + + STORAGE_CREDENTIAL_DURATION_SECONDS.key() + + ".") + .defaultValue(0) + .buildFeatureConfiguration(); + public static final FeatureConfiguration MAX_METADATA_REFRESH_RETRIES = PolarisConfiguration.builder() .key("MAX_METADATA_REFRESH_RETRIES") diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java index ee3e147dad8..1167ca72c07 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java @@ -52,20 +52,24 @@ public StorageCredentialCache(StorageCredentialCacheConfig cacheConfig) { .expireAfter( Expiry.creating( (StorageCredentialCacheKey key, StorageCredentialCacheEntry entry) -> { + long remainingMs = + entry.getExpirationTime() - System.currentTimeMillis(); + long bufferMs = entry.refreshBufferMs(); + long effectiveTtl = + bufferMs > 0 ? remainingMs - bufferMs : remainingMs / 2; long expireAfterMillis = - Math.max( - 0, - Math.min( - (entry.getExpirationTime() - System.currentTimeMillis()) / 2, - entry.maxCacheDurationMs())); + Math.max(0, Math.min(effectiveTtl, entry.maxCacheDurationMs())); return Duration.ofMillis(expireAfterMillis); })) - .build(key -> { - LOGGER.atDebug().log("StorageCredentialCache::load"); - StorageAccessConfig accessConfig = key.load(); - return new StorageCredentialCacheEntry( - accessConfig, maxCacheDurationMs(key.realmConfig())); - }); + .build( + key -> { + LOGGER.atDebug().log("StorageCredentialCache::load"); + StorageAccessConfig accessConfig = key.load(); + return new StorageCredentialCacheEntry( + accessConfig, + maxCacheDurationMs(key.realmConfig()), + refreshBufferMs(key.realmConfig())); + }); } /** How long credentials should remain in the cache. */ @@ -85,6 +89,12 @@ private long maxCacheDurationMs(RealmConfig realmConfig) { } } + /** Minimum buffer to keep between credential expiry and cache eviction. */ + private long refreshBufferMs(RealmConfig realmConfig) { + return realmConfig.getConfig(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS) + * 1000L; + } + /** * Return the cached {@link StorageAccessConfig} for {@code key}, loading it via {@link * StorageCredentialCacheKey#load()} on miss. diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheEntry.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheEntry.java index f26d8125348..2771c5917f1 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheEntry.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheEntry.java @@ -25,9 +25,10 @@ * A storage credential cached entry. * * @param storageAccessConfig The scoped creds map that is fetched from a creds vending service + * @param refreshBufferMs Milliseconds before expiry at which the entry is considered stale */ public record StorageCredentialCacheEntry( - StorageAccessConfig storageAccessConfig, long maxCacheDurationMs) { + StorageAccessConfig storageAccessConfig, long maxCacheDurationMs, long refreshBufferMs) { /** Get the expiration time in millisecond for the cached entry */ public long getExpirationTime() { diff --git a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java index 8e6b553e9d5..cf439f2e7e0 100644 --- a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java +++ b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java @@ -36,6 +36,7 @@ import org.apache.polaris.core.storage.StorageAccessConfig; import org.apache.polaris.core.storage.StorageAccessProperty; import org.assertj.core.api.Assertions; +import org.apache.polaris.core.config.FeatureConfiguration; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.RepeatedTest; import org.junit.jupiter.api.Test; @@ -441,6 +442,74 @@ private static List getFakeAccessConfigs(int number, boolea return res; } + @Test + public void testRefreshBufferEvictsNearExpiryCredentials() { + // Credentials expire in 120 seconds from now. + // With a 300-second refresh buffer, effective TTL = 120s - 300s = -180s → clamped to 0. + // The entry must be absent immediately after load. + long expiresAt = System.currentTimeMillis() + 120_000; + StorageAccessConfig nearExpiryConfig = + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .put( + StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, + String.valueOf(expiresAt)) + .put(StorageAccessProperty.EXPIRATION_TIME, String.valueOf(expiresAt)) + .build(); + + // RealmConfig with STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS = 300 + RealmConfig realmConfigWithBuffer = + new RealmConfigImpl( + (rc, name) -> + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) + ? 300 + : null, + realmContext); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer, + () -> nearExpiryConfig); + + storageCredentialCache.getOrLoad(key); + Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNull(); + } + + @Test + public void testRefreshBufferZeroPreservesHalfLifetimeBehavior() { + // Credentials expire in 120 seconds from now. + // With buffer = 0 (default), effective TTL = 120s / 2 = 60s > 0 → entry is kept in cache. + long expiresAt = System.currentTimeMillis() + 120_000; + StorageAccessConfig config = + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .put( + StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, + String.valueOf(expiresAt)) + .put(StorageAccessProperty.EXPIRATION_TIME, String.valueOf(expiresAt)) + .build(); + + StorageCredentialCacheKey key = + buildKey( + "bufferZeroConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + () -> config); + + storageCredentialCache.getOrLoad(key); + Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNotNull(); + } + private static List getStorageConfigStrings() { return Arrays.asList("config1", "config2", "config3"); } From d41dcbf6137c0d09e9a84e59f7a9576e78bfb8ee Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Sat, 25 Jul 2026 09:50:42 -0400 Subject: [PATCH 02/12] style: apply spotless formatting --- .../core/config/FeatureConfiguration.java | 29 +++++++++---------- .../storage/cache/StorageCredentialCache.java | 6 ++-- .../cache/StorageCredentialCacheTest.java | 10 ++----- 3 files changed, 19 insertions(+), 26 deletions(-) diff --git a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java index b8f995c3b88..102987b6bfd 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java @@ -517,21 +517,20 @@ public static void enforceFeatureEnabledOrThrow( .defaultValue(30 * 60) // 30 minutes .buildFeatureConfiguration(); - public static final FeatureConfiguration - STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS = - PolarisConfiguration.builder() - .key("STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS") - .description( - "Minimum remaining validity (in seconds) that a cached storage credential must " - + "have before it is considered stale and evicted. When non-zero, credentials " - + "are removed from the cache this many seconds before they expire, ensuring " - + "clients always receive credentials with at least this much validity left. " - + "When zero (the default), credentials are kept for half of their remaining " - + "lifetime, which is the legacy behavior. Must be less than " - + STORAGE_CREDENTIAL_DURATION_SECONDS.key() - + ".") - .defaultValue(0) - .buildFeatureConfiguration(); + public static final FeatureConfiguration STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS = + PolarisConfiguration.builder() + .key("STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS") + .description( + "Minimum remaining validity (in seconds) that a cached storage credential must " + + "have before it is considered stale and evicted. When non-zero, credentials " + + "are removed from the cache this many seconds before they expire, ensuring " + + "clients always receive credentials with at least this much validity left. " + + "When zero (the default), credentials are kept for half of their remaining " + + "lifetime, which is the legacy behavior. Must be less than " + + STORAGE_CREDENTIAL_DURATION_SECONDS.key() + + ".") + .defaultValue(0) + .buildFeatureConfiguration(); public static final FeatureConfiguration MAX_METADATA_REFRESH_RETRIES = PolarisConfiguration.builder() diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java index 1167ca72c07..22b8eb3a729 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java @@ -52,11 +52,9 @@ public StorageCredentialCache(StorageCredentialCacheConfig cacheConfig) { .expireAfter( Expiry.creating( (StorageCredentialCacheKey key, StorageCredentialCacheEntry entry) -> { - long remainingMs = - entry.getExpirationTime() - System.currentTimeMillis(); + long remainingMs = entry.getExpirationTime() - System.currentTimeMillis(); long bufferMs = entry.refreshBufferMs(); - long effectiveTtl = - bufferMs > 0 ? remainingMs - bufferMs : remainingMs / 2; + long effectiveTtl = bufferMs > 0 ? remainingMs - bufferMs : remainingMs / 2; long expireAfterMillis = Math.max(0, Math.min(effectiveTtl, entry.maxCacheDurationMs())); return Duration.ofMillis(expireAfterMillis); diff --git a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java index cf439f2e7e0..d3d005fa445 100644 --- a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java +++ b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java @@ -30,13 +30,13 @@ import java.util.concurrent.atomic.AtomicInteger; import java.util.function.Supplier; import org.apache.iceberg.exceptions.UnprocessableEntityException; +import org.apache.polaris.core.config.FeatureConfiguration; import org.apache.polaris.core.config.RealmConfig; import org.apache.polaris.core.config.RealmConfigImpl; import org.apache.polaris.core.context.RealmContext; import org.apache.polaris.core.storage.StorageAccessConfig; import org.apache.polaris.core.storage.StorageAccessProperty; import org.assertj.core.api.Assertions; -import org.apache.polaris.core.config.FeatureConfiguration; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.RepeatedTest; import org.junit.jupiter.api.Test; @@ -452,9 +452,7 @@ public void testRefreshBufferEvictsNearExpiryCredentials() { StorageAccessConfig.builder() .put(StorageAccessProperty.AWS_KEY_ID, "key") .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") - .put( - StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, - String.valueOf(expiresAt)) + .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) .put(StorageAccessProperty.EXPIRATION_TIME, String.valueOf(expiresAt)) .build(); @@ -491,9 +489,7 @@ public void testRefreshBufferZeroPreservesHalfLifetimeBehavior() { StorageAccessConfig.builder() .put(StorageAccessProperty.AWS_KEY_ID, "key") .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") - .put( - StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, - String.valueOf(expiresAt)) + .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) .put(StorageAccessProperty.EXPIRATION_TIME, String.valueOf(expiresAt)) .build(); From 814c1bad01ce16e1a66250d1e5ee80caa0228f14 Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Sat, 1 Aug 2026 17:07:40 -0400 Subject: [PATCH 03/12] test: address dimas-b review on StorageCredentialCacheTest - Remove EXPIRATION_TIME usage (removed in #5070) - Rename testRefreshBufferZeroPreservesHalfLifetimeBehavior to testRefreshBufferZeroKeepsEntryInCache (assert only proves entry is cached, not the specific TTL formula) --- .../core/storage/cache/StorageCredentialCacheTest.java | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java index d3d005fa445..3a671e042d9 100644 --- a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java +++ b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java @@ -445,7 +445,7 @@ private static List getFakeAccessConfigs(int number, boolea @Test public void testRefreshBufferEvictsNearExpiryCredentials() { // Credentials expire in 120 seconds from now. - // With a 300-second refresh buffer, effective TTL = 120s - 300s = -180s → clamped to 0. + // With a 300-second refresh buffer, effective TTL = 120s - 300s = -180s -> clamped to 0. // The entry must be absent immediately after load. long expiresAt = System.currentTimeMillis() + 120_000; StorageAccessConfig nearExpiryConfig = @@ -453,7 +453,6 @@ public void testRefreshBufferEvictsNearExpiryCredentials() { .put(StorageAccessProperty.AWS_KEY_ID, "key") .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) - .put(StorageAccessProperty.EXPIRATION_TIME, String.valueOf(expiresAt)) .build(); // RealmConfig with STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS = 300 @@ -481,16 +480,15 @@ public void testRefreshBufferEvictsNearExpiryCredentials() { } @Test - public void testRefreshBufferZeroPreservesHalfLifetimeBehavior() { + public void testRefreshBufferZeroKeepsEntryInCache() { // Credentials expire in 120 seconds from now. - // With buffer = 0 (default), effective TTL = 120s / 2 = 60s > 0 → entry is kept in cache. + // With buffer = 0 (default), effective TTL = 120s / 2 = 60s > 0 -> entry is kept in cache. long expiresAt = System.currentTimeMillis() + 120_000; StorageAccessConfig config = StorageAccessConfig.builder() .put(StorageAccessProperty.AWS_KEY_ID, "key") .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) - .put(StorageAccessProperty.EXPIRATION_TIME, String.valueOf(expiresAt)) .build(); StorageCredentialCacheKey key = From c56c4bd935eef8df587365130f02cbe99d2a13cf Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Sat, 1 Aug 2026 18:34:13 -0400 Subject: [PATCH 04/12] docs: regenerate config reference for STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS --- .../config-sections/flags-polaris_features.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md b/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md index 516cde1a6f1..de587cb1523 100644 --- a/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md +++ b/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md @@ -578,6 +578,15 @@ The duration of time that vended storage credentials are valid for. Support for --- +##### `polaris.features."STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS"` + +Minimum remaining validity (in seconds) that a cached storage credential must have before it is considered stale and evicted. When non-zero, credentials are removed from the cache this many seconds before they expire, ensuring clients always receive credentials with at least this much validity left. When zero (the default), credentials are kept for half of their remaining lifetime, which is the legacy behavior. Must be less than STORAGE_CREDENTIAL_DURATION_SECONDS. + +- **Type:** `Integer` +- **Default:** `0` + +--- + ##### `polaris.features."SUPPORTED_CATALOG_CONNECTION_TYPES"` The list of supported catalog connection types for federation From 5b3cf60fc1fc6982c8ec207d9d7bd1ed57dc5ef5 Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Mon, 14 Sep 2026 22:21:07 -0400 Subject: [PATCH 05/12] fix(cache): enforce refresh buffer on first load, validate buffer range getOrLoad() previously returned a freshly-loaded credential as-is even when it was already within the configured refresh buffer of expiring, because Caffeine's expireAfter only governs how long an entry is kept -- not what a synchronous get() returns on the load that populates it. This violated the documented guarantee that clients always receive credentials with at least STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS of validity left. getOrLoad() now checks the loaded entry against the buffer and, if under it, invalidates and reloads once before returning -- bypassing the stale copy without retrying indefinitely against a misconfigured or short-lived credential source. Also validates STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS is >= 0 and less than STORAGE_CREDENTIAL_DURATION_SECONDS, matching the existing validation pattern for STORAGE_CREDENTIAL_CACHE_DURATION_SECONDS. Addresses review from flyingImer and ayushtkn. --- .../storage/cache/StorageCredentialCache.java | 49 +++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java index 22b8eb3a729..ef1478ea019 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java @@ -89,16 +89,59 @@ private long maxCacheDurationMs(RealmConfig realmConfig) { /** Minimum buffer to keep between credential expiry and cache eviction. */ private long refreshBufferMs(RealmConfig realmConfig) { - return realmConfig.getConfig(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS) - * 1000L; + var refreshBufferSeconds = + realmConfig.getConfig(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS); + var credentialDurationSeconds = + realmConfig.getConfig(FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS); + if (refreshBufferSeconds < 0 || refreshBufferSeconds >= credentialDurationSeconds) { + throw new IllegalArgumentException( + String.format( + "%s must be >= 0 and less than %s", + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key(), + FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS.key())); + } + return refreshBufferSeconds * 1000L; } /** * Return the cached {@link StorageAccessConfig} for {@code key}, loading it via {@link * StorageCredentialCacheKey#load()} on miss. + * + *

The refresh buffer (when non-zero) is enforced on every call, not just on cache hits: a + * freshly loaded credential can itself already be within the buffer of expiring (e.g. a + * credential provider issuing a short-lived token), in which case Caffeine's {@code expireAfter} + * would give it a zero TTL but still hand it back on this same call. To honor the "clients always + * receive credentials with at least this much validity left" contract, such an entry is discarded + * and reloaded once, bypassing the stale copy. If the reload is still under the buffer, it's + * returned anyway (with a warning) rather than retried indefinitely -- a provider that can't + * clear its own configured buffer is a configuration problem, not something to hot-loop against. */ public StorageAccessConfig getOrLoad(StorageCredentialCacheKey key) { - return cache.get(key).toAccessConfig(); + StorageCredentialCacheEntry entry = cache.get(key); + if (isUnderRefreshBuffer(entry)) { + cache.invalidate(key); + entry = cache.get(key); + if (isUnderRefreshBuffer(entry)) { + LOGGER + .atWarn() + .log( + "Reloaded storage credential is still within its configured refresh buffer " + + "({} ms remaining, buffer {} ms) -- returning it anyway. The underlying " + + "credential provider may be issuing credentials shorter than the " + + "configured buffer.", + entry.getExpirationTime() - System.currentTimeMillis(), + entry.refreshBufferMs()); + } + } + return entry.toAccessConfig(); + } + + private static boolean isUnderRefreshBuffer(StorageCredentialCacheEntry entry) { + if (entry.refreshBufferMs() <= 0) { + return false; + } + long remainingMs = entry.getExpirationTime() - System.currentTimeMillis(); + return remainingMs < entry.refreshBufferMs(); } @VisibleForTesting From 348bec8c5f68f7af6758e89f9bebe09e445e8ff3 Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Mon, 14 Sep 2026 22:21:27 -0400 Subject: [PATCH 06/12] test: cover refresh-buffer happy path, first-load retry, and boundary validation Addresses ayushtkn's coverage gaps and flyingImer's ask to assert getOrLoad() never returns an under-buffer credential: - testRefreshBufferHappyPathCachesWithEffectiveTtl: buffer=300s, credential expires in 3600s -- stays cached with a comfortably positive effective TTL. - testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer: first load is near-expiry, second (retried) load is fresh -- getOrLoad() must return the fresh one, proving the buffer is enforced on the initial load, not just on cache hits. - testRefreshBufferRejectsNegativeValue / testRefreshBufferRejectsValueAtOrAboveCredentialDuration: boundary validation on the new range check. Also clarifies the existing testRefreshBufferEvictsNearExpiryCredentials comment to note why its fixed-value loader can't exercise the new retry path (see testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer for that). --- .../cache/StorageCredentialCacheTest.java | 152 +++++++++++++++++- 1 file changed, 151 insertions(+), 1 deletion(-) diff --git a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java index 3a671e042d9..5b5cd2c95ba 100644 --- a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java +++ b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java @@ -446,7 +446,11 @@ private static List getFakeAccessConfigs(int number, boolea public void testRefreshBufferEvictsNearExpiryCredentials() { // Credentials expire in 120 seconds from now. // With a 300-second refresh buffer, effective TTL = 120s - 300s = -180s -> clamped to 0. - // The entry must be absent immediately after load. + // The entry must be absent immediately after load. getOrLoad() will also retry the load + // once internally (see isUnderRefreshBuffer in StorageCredentialCache), but this loader + // always returns the same near-expiry value, so the retry can't produce a better result -- + // it's still correctly evicted. testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer below covers + // the case where a retry DOES have a fresher credential available. long expiresAt = System.currentTimeMillis() + 120_000; StorageAccessConfig nearExpiryConfig = StorageAccessConfig.builder() @@ -504,6 +508,152 @@ public void testRefreshBufferZeroKeepsEntryInCache() { Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNotNull(); } + @Test + public void testRefreshBufferHappyPathCachesWithEffectiveTtl() { + // Credentials expire in 3600 seconds. With a 300-second buffer, effective TTL is ~3300s -- + // comfortably positive, so the entry is loaded and stays cached (unlike the near-expiry case + // above, where the buffer consumes the entire remaining lifetime). + long expiresAt = System.currentTimeMillis() + 3600_000; + StorageAccessConfig config = + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) + .build(); + + RealmConfig realmConfigWithBuffer = + new RealmConfigImpl( + (rc, name) -> + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) + ? 300 + : null, + realmContext); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferHappyPathConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer, + () -> config); + + StorageAccessConfig result = storageCredentialCache.getOrLoad(key); + Assertions.assertThat(result).isEqualTo(config); + Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNotNull(); + } + + @Test + public void testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer() { + // First load is near-expiry (violates the 300s buffer); second load (from the internal + // retry) is comfortably fresh. getOrLoad() must return the SECOND value, not the first -- + // proving the buffer guarantee is enforced on the initial load, not just on cache hits. + long nearExpiryAt = System.currentTimeMillis() + 120_000; + long freshAt = System.currentTimeMillis() + 3600_000; + StorageAccessConfig nearExpiryConfig = + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key-stale") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret-stale") + .put( + StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(nearExpiryAt)) + .build(); + StorageAccessConfig freshConfig = + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key-fresh") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret-fresh") + .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(freshAt)) + .build(); + List configs = List.of(nearExpiryConfig, freshConfig); + AtomicInteger loadCount = new AtomicInteger(); + + RealmConfig realmConfigWithBuffer = + new RealmConfigImpl( + (rc, name) -> + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) + ? 300 + : null, + realmContext); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferRetryConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer, + () -> configs.get(loadCount.getAndIncrement())); + + StorageAccessConfig result = storageCredentialCache.getOrLoad(key); + Assertions.assertThat(result).isEqualTo(freshConfig); + Assertions.assertThat(loadCount.get()).isEqualTo(2); + } + + @Test + public void testRefreshBufferRejectsNegativeValue() { + RealmConfig realmConfigWithNegativeBuffer = + new RealmConfigImpl( + (rc, name) -> + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) + ? -1 + : null, + realmContext); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferNegativeConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithNegativeBuffer, + () -> + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .build()); + + Assertions.assertThatThrownBy(() -> storageCredentialCache.getOrLoad(key)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key()); + } + + @Test + public void testRefreshBufferRejectsValueAtOrAboveCredentialDuration() { + // Default STORAGE_CREDENTIAL_DURATION_SECONDS is 3600 (1 hour); a buffer equal to it must + // be rejected the same way a buffer greater than it would be. + RealmConfig realmConfigWithTooLargeBuffer = + new RealmConfigImpl( + (rc, name) -> + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) + ? 3600 + : null, + realmContext); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferTooLargeConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithTooLargeBuffer, + () -> + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .build()); + + Assertions.assertThatThrownBy(() -> storageCredentialCache.getOrLoad(key)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key()); + } + private static List getStorageConfigStrings() { return Arrays.asList("config1", "config2", "config3"); } From a2d3ab0eed52b1d89170c6896440c16aa2280d0d Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Mon, 14 Sep 2026 22:21:44 -0400 Subject: [PATCH 07/12] docs: add CHANGELOG entry for STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS Addresses ayushtkn's ask for a CHANGELOG line -- this is a user-facing configuration flag. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f1b2938673c..bf6e02746ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -688,6 +688,7 @@ see [changelog.d/README.md](changelog.d/README.md). Fragments are merged into th - Python CLI: added `--scheme` to specify URL scheme - Added opt-in idempotency for `createTable` and `updateTable` in the Iceberg REST catalog. When enabled via `polaris.idempotency.enabled=true` (default `false`), a client-supplied `Idempotency-Key` header is embedded into the table entity and committed in the same transaction as the operation; a retry carrying the same key within the TTL window (`polaris.idempotency.ttl`, default `PT5M`) replays the original success instead of failing — with `AlreadyExists` for `createTable`, or with `CommitFailedException` for `updateTable` when the request's requirements no longer match the already-advanced table. When idempotency is enabled, the reuse window is advertised to clients through the `idempotency-key-lifetime` field of the `GET /v1/config` response. - Python CLI: Added views and generic-tables support. +- Added the `STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS` feature flag (default `0`). When non-zero, a cached storage credential is evicted this many seconds before it actually expires, guaranteeing callers always receive credentials with at least this much validity left; a freshly loaded credential that is already within the buffer is reloaded once rather than handed back as-is. Must be `>= 0` and less than `STORAGE_CREDENTIAL_DURATION_SECONDS`. When `0` (the default), behavior is unchanged: credentials are kept for half of their remaining lifetime. ### Changes From edd371588b04ed05d70ef7ad82634c22f8cd1f9b Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Wed, 28 Oct 2026 22:03:07 -0400 Subject: [PATCH 08/12] fix(cache): throw when a reloaded credential still violates the refresh buffer getOrLoad's retry (added for the first-load gap) could still return a credential under the configured buffer if the provider issues another near-expiry one, silently violating the documented guarantee. Throw UnprocessableEntityException instead, per flyingImer's review. Test asserts the exact caller-visible outcome and exactly two loads. --- CHANGELOG.md | 2 +- .../storage/cache/StorageCredentialCache.java | 27 +++++++++-------- .../cache/StorageCredentialCacheTest.java | 29 ++++++++++++------- 3 files changed, 35 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bf6e02746ff..88f34a92b57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -688,7 +688,7 @@ see [changelog.d/README.md](changelog.d/README.md). Fragments are merged into th - Python CLI: added `--scheme` to specify URL scheme - Added opt-in idempotency for `createTable` and `updateTable` in the Iceberg REST catalog. When enabled via `polaris.idempotency.enabled=true` (default `false`), a client-supplied `Idempotency-Key` header is embedded into the table entity and committed in the same transaction as the operation; a retry carrying the same key within the TTL window (`polaris.idempotency.ttl`, default `PT5M`) replays the original success instead of failing — with `AlreadyExists` for `createTable`, or with `CommitFailedException` for `updateTable` when the request's requirements no longer match the already-advanced table. When idempotency is enabled, the reuse window is advertised to clients through the `idempotency-key-lifetime` field of the `GET /v1/config` response. - Python CLI: Added views and generic-tables support. -- Added the `STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS` feature flag (default `0`). When non-zero, a cached storage credential is evicted this many seconds before it actually expires, guaranteeing callers always receive credentials with at least this much validity left; a freshly loaded credential that is already within the buffer is reloaded once rather than handed back as-is. Must be `>= 0` and less than `STORAGE_CREDENTIAL_DURATION_SECONDS`. When `0` (the default), behavior is unchanged: credentials are kept for half of their remaining lifetime. +- Added the `STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS` feature flag (default `0`). When non-zero, a cached storage credential is evicted this many seconds before it actually expires, guaranteeing callers always receive credentials with at least this much validity left; a freshly loaded credential that is already within the buffer is reloaded once rather than handed back as-is, and if the reload is still under the buffer, an `UnprocessableEntityException` is thrown rather than returning a credential that violates the guarantee. Must be `>= 0` and less than `STORAGE_CREDENTIAL_DURATION_SECONDS`. When `0` (the default), behavior is unchanged: credentials are kept for half of their remaining lifetime. ### Changes diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java index ef1478ea019..8794a485d57 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java @@ -25,6 +25,7 @@ import java.time.Duration; import java.util.Map; import java.util.Optional; +import org.apache.iceberg.exceptions.UnprocessableEntityException; import org.apache.polaris.core.config.FeatureConfiguration; import org.apache.polaris.core.config.RealmConfig; import org.apache.polaris.core.storage.StorageAccessConfig; @@ -112,9 +113,14 @@ private long refreshBufferMs(RealmConfig realmConfig) { * credential provider issuing a short-lived token), in which case Caffeine's {@code expireAfter} * would give it a zero TTL but still hand it back on this same call. To honor the "clients always * receive credentials with at least this much validity left" contract, such an entry is discarded - * and reloaded once, bypassing the stale copy. If the reload is still under the buffer, it's - * returned anyway (with a warning) rather than retried indefinitely -- a provider that can't - * clear its own configured buffer is a configuration problem, not something to hot-loop against. + * and reloaded once, bypassing the stale copy. + * + *

If the reload is still under the buffer, the contract cannot be honored at all, so + * this throws rather than silently handing back an under-buffer credential -- a provider that + * can't clear its own configured buffer after a fresh fetch is a configuration problem the caller + * needs to see, not something to mask with a log line. It is not retried a third time: a provider + * issuing credentials shorter than the configured buffer will keep doing so, and hot-looping + * against it doesn't help. */ public StorageAccessConfig getOrLoad(StorageCredentialCacheKey key) { StorageCredentialCacheEntry entry = cache.get(key); @@ -122,15 +128,12 @@ public StorageAccessConfig getOrLoad(StorageCredentialCacheKey key) { cache.invalidate(key); entry = cache.get(key); if (isUnderRefreshBuffer(entry)) { - LOGGER - .atWarn() - .log( - "Reloaded storage credential is still within its configured refresh buffer " - + "({} ms remaining, buffer {} ms) -- returning it anyway. The underlying " - + "credential provider may be issuing credentials shorter than the " - + "configured buffer.", - entry.getExpirationTime() - System.currentTimeMillis(), - entry.refreshBufferMs()); + throw new UnprocessableEntityException( + "Storage credential provider returned a credential with only %d ms of validity left, " + + "which is still under the configured refresh buffer of %d ms, even after a " + + "reload. The credential provider may be issuing credentials shorter than " + + "STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.", + entry.getExpirationTime() - System.currentTimeMillis(), entry.refreshBufferMs()); } } return entry.toAccessConfig(); diff --git a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java index 5b5cd2c95ba..b157d1c8338 100644 --- a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java +++ b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java @@ -443,14 +443,14 @@ private static List getFakeAccessConfigs(int number, boolea } @Test - public void testRefreshBufferEvictsNearExpiryCredentials() { - // Credentials expire in 120 seconds from now. - // With a 300-second refresh buffer, effective TTL = 120s - 300s = -180s -> clamped to 0. - // The entry must be absent immediately after load. getOrLoad() will also retry the load - // once internally (see isUnderRefreshBuffer in StorageCredentialCache), but this loader - // always returns the same near-expiry value, so the retry can't produce a better result -- - // it's still correctly evicted. testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer below covers - // the case where a retry DOES have a fresher credential available. + public void testGetOrLoadThrowsWhenPersistentlyUnderBuffer() { + // Credentials expire in 120 seconds from now. With a 300-second refresh buffer, that's + // under the buffer on every load. getOrLoad() retries once internally (see + // isUnderRefreshBuffer in StorageCredentialCache), but this loader always returns the same + // near-expiry value, so the retry can't produce a better result -- the buffer can never be + // satisfied, and getOrLoad() must say so rather than silently handing back a credential that + // violates its own documented contract. See testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer + // below for the case where the retry DOES have a fresher credential available. long expiresAt = System.currentTimeMillis() + 120_000; StorageAccessConfig nearExpiryConfig = StorageAccessConfig.builder() @@ -458,6 +458,7 @@ public void testRefreshBufferEvictsNearExpiryCredentials() { .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) .build(); + AtomicInteger loadCount = new AtomicInteger(); // RealmConfig with STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS = 300 RealmConfig realmConfigWithBuffer = @@ -477,9 +478,17 @@ public void testRefreshBufferEvictsNearExpiryCredentials() { Set.of(), Optional.empty(), realmConfigWithBuffer, - () -> nearExpiryConfig); + () -> { + loadCount.incrementAndGet(); + return nearExpiryConfig; + }); - storageCredentialCache.getOrLoad(key); + Assertions.assertThatThrownBy(() -> storageCredentialCache.getOrLoad(key)) + .isInstanceOf(UnprocessableEntityException.class) + .hasMessageContaining("refresh buffer"); + // Exactly the initial load plus one retry -- no hot-looping against a provider that can't + // clear its own configured buffer. + Assertions.assertThat(loadCount.get()).isEqualTo(2); Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNull(); } From b4d0ec445693cb0b14612fcda4dbeb6046aa2958 Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Thu, 29 Oct 2026 22:05:41 -0400 Subject: [PATCH 09/12] test: apply orca-review-bot's test-quality suggestions Extract a realmConfigWithBuffer(int) helper used by all the buffer tests instead of repeating the RealmConfigImpl construction inline. Fold the negative and at-the-duration-limit rejection tests into one @ParameterizedTest. Add a case verifying a credential with no expiry at all is never considered under the buffer (getExpirationTime() falls back to Long.MAX_VALUE). --- .../cache/StorageCredentialCacheTest.java | 105 ++++++++---------- 1 file changed, 45 insertions(+), 60 deletions(-) diff --git a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java index b157d1c8338..6d9e18ee0ec 100644 --- a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java +++ b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java @@ -40,6 +40,8 @@ import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.RepeatedTest; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; public class StorageCredentialCacheTest { private final RealmContext realmContext = () -> "testRealm"; @@ -442,6 +444,18 @@ private static List getFakeAccessConfigs(int number, boolea return res; } + /** + * A RealmConfig reporting {@code bufferSeconds} for STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS. + */ + private RealmConfig realmConfigWithBuffer(int bufferSeconds) { + return new RealmConfigImpl( + (rc, name) -> + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) + ? bufferSeconds + : null, + realmContext); + } + @Test public void testGetOrLoadThrowsWhenPersistentlyUnderBuffer() { // Credentials expire in 120 seconds from now. With a 300-second refresh buffer, that's @@ -460,15 +474,6 @@ public void testGetOrLoadThrowsWhenPersistentlyUnderBuffer() { .build(); AtomicInteger loadCount = new AtomicInteger(); - // RealmConfig with STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS = 300 - RealmConfig realmConfigWithBuffer = - new RealmConfigImpl( - (rc, name) -> - FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) - ? 300 - : null, - realmContext); - StorageCredentialCacheKey key = new TestKey( realmContext.getRealmIdentifier(), @@ -477,7 +482,7 @@ public void testGetOrLoadThrowsWhenPersistentlyUnderBuffer() { Set.of("s3://bucket/path"), Set.of(), Optional.empty(), - realmConfigWithBuffer, + realmConfigWithBuffer(300), () -> { loadCount.incrementAndGet(); return nearExpiryConfig; @@ -530,14 +535,6 @@ public void testRefreshBufferHappyPathCachesWithEffectiveTtl() { .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) .build(); - RealmConfig realmConfigWithBuffer = - new RealmConfigImpl( - (rc, name) -> - FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) - ? 300 - : null, - realmContext); - StorageCredentialCacheKey key = new TestKey( realmContext.getRealmIdentifier(), @@ -546,7 +543,7 @@ public void testRefreshBufferHappyPathCachesWithEffectiveTtl() { Set.of("s3://bucket/path"), Set.of(), Optional.empty(), - realmConfigWithBuffer, + realmConfigWithBuffer(300), () -> config); StorageAccessConfig result = storageCredentialCache.getOrLoad(key); @@ -577,14 +574,6 @@ public void testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer() { List configs = List.of(nearExpiryConfig, freshConfig); AtomicInteger loadCount = new AtomicInteger(); - RealmConfig realmConfigWithBuffer = - new RealmConfigImpl( - (rc, name) -> - FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) - ? 300 - : null, - realmContext); - StorageCredentialCacheKey key = new TestKey( realmContext.getRealmIdentifier(), @@ -593,7 +582,7 @@ public void testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer() { Set.of("s3://bucket/path"), Set.of(), Optional.empty(), - realmConfigWithBuffer, + realmConfigWithBuffer(300), () -> configs.get(loadCount.getAndIncrement())); StorageAccessConfig result = storageCredentialCache.getOrLoad(key); @@ -601,25 +590,21 @@ public void testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer() { Assertions.assertThat(loadCount.get()).isEqualTo(2); } - @Test - public void testRefreshBufferRejectsNegativeValue() { - RealmConfig realmConfigWithNegativeBuffer = - new RealmConfigImpl( - (rc, name) -> - FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) - ? -1 - : null, - realmContext); - + @ParameterizedTest + // -1 is rejected as negative; 3600 is rejected because it's not less than the default + // STORAGE_CREDENTIAL_DURATION_SECONDS of 3600 (1 hour) -- same rejection path as a buffer + // greater than the credential duration. + @ValueSource(ints = {-1, 3600}) + public void testRefreshBufferRejectsOutOfRangeValue(int bufferSeconds) { StorageCredentialCacheKey key = new TestKey( realmContext.getRealmIdentifier(), - "bufferNegativeConfig", + "bufferOutOfRangeConfig-" + bufferSeconds, true, Set.of("s3://bucket/path"), Set.of(), Optional.empty(), - realmConfigWithNegativeBuffer, + realmConfigWithBuffer(bufferSeconds), () -> StorageAccessConfig.builder() .put(StorageAccessProperty.AWS_KEY_ID, "key") @@ -632,35 +617,35 @@ public void testRefreshBufferRejectsNegativeValue() { } @Test - public void testRefreshBufferRejectsValueAtOrAboveCredentialDuration() { - // Default STORAGE_CREDENTIAL_DURATION_SECONDS is 3600 (1 hour); a buffer equal to it must - // be rejected the same way a buffer greater than it would be. - RealmConfig realmConfigWithTooLargeBuffer = - new RealmConfigImpl( - (rc, name) -> - FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key().equals(name) - ? 3600 - : null, - realmContext); + public void testRefreshBufferWithNoExpiresAtIsNeverUnderBuffer() { + // No expiresAt set at all (StorageCredentialCacheEntry.getExpirationTime() falls back to + // Long.MAX_VALUE) -- a positive buffer must not misfire against a credential that doesn't + // expire. The entry should load normally, without retrying or throwing, and stay cached. + StorageAccessConfig noExpiryConfig = + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .build(); + AtomicInteger loadCount = new AtomicInteger(); StorageCredentialCacheKey key = new TestKey( realmContext.getRealmIdentifier(), - "bufferTooLargeConfig", + "bufferNoExpiresAtConfig", true, Set.of("s3://bucket/path"), Set.of(), Optional.empty(), - realmConfigWithTooLargeBuffer, - () -> - StorageAccessConfig.builder() - .put(StorageAccessProperty.AWS_KEY_ID, "key") - .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") - .build()); + realmConfigWithBuffer(300), + () -> { + loadCount.incrementAndGet(); + return noExpiryConfig; + }); - Assertions.assertThatThrownBy(() -> storageCredentialCache.getOrLoad(key)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key()); + StorageAccessConfig result = storageCredentialCache.getOrLoad(key); + Assertions.assertThat(result).isEqualTo(noExpiryConfig); + Assertions.assertThat(loadCount.get()).isEqualTo(1); + Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNotNull(); } private static List getStorageConfigStrings() { From 429f2d08e016d16a8c6870a4cba7c9ea1bf4ddcd Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Wed, 18 Nov 2026 22:51:29 -0500 Subject: [PATCH 10/12] docs: migrate CHANGELOG entry to a changelog.d fragment apache/polaris#5967 replaced direct CHANGELOG.md edits with fragment files under changelog.d/, to avoid merge conflicts between unrelated PRs editing the same section. Moves our entry there unchanged. Per adutra's note on this PR. --- CHANGELOG.md | 1 - changelog.d/storage-credential-refresh-buffer.md | 11 +++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 changelog.d/storage-credential-refresh-buffer.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 88f34a92b57..f1b2938673c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -688,7 +688,6 @@ see [changelog.d/README.md](changelog.d/README.md). Fragments are merged into th - Python CLI: added `--scheme` to specify URL scheme - Added opt-in idempotency for `createTable` and `updateTable` in the Iceberg REST catalog. When enabled via `polaris.idempotency.enabled=true` (default `false`), a client-supplied `Idempotency-Key` header is embedded into the table entity and committed in the same transaction as the operation; a retry carrying the same key within the TTL window (`polaris.idempotency.ttl`, default `PT5M`) replays the original success instead of failing — with `AlreadyExists` for `createTable`, or with `CommitFailedException` for `updateTable` when the request's requirements no longer match the already-advanced table. When idempotency is enabled, the reuse window is advertised to clients through the `idempotency-key-lifetime` field of the `GET /v1/config` response. - Python CLI: Added views and generic-tables support. -- Added the `STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS` feature flag (default `0`). When non-zero, a cached storage credential is evicted this many seconds before it actually expires, guaranteeing callers always receive credentials with at least this much validity left; a freshly loaded credential that is already within the buffer is reloaded once rather than handed back as-is, and if the reload is still under the buffer, an `UnprocessableEntityException` is thrown rather than returning a credential that violates the guarantee. Must be `>= 0` and less than `STORAGE_CREDENTIAL_DURATION_SECONDS`. When `0` (the default), behavior is unchanged: credentials are kept for half of their remaining lifetime. ### Changes diff --git a/changelog.d/storage-credential-refresh-buffer.md b/changelog.d/storage-credential-refresh-buffer.md new file mode 100644 index 00000000000..51f7390b9ca --- /dev/null +++ b/changelog.d/storage-credential-refresh-buffer.md @@ -0,0 +1,11 @@ +### New Features + +- Added the `STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS` feature flag (default `0`). When + non-zero, a cached storage credential is evicted this many seconds before it actually + expires, guaranteeing callers always receive credentials with at least this much validity + left; a freshly loaded credential that is already within the buffer is reloaded once rather + than handed back as-is, and if the reload is still under the buffer, an + `UnprocessableEntityException` is thrown rather than returning a credential that violates + the guarantee. Must be `>= 0` and less than `STORAGE_CREDENTIAL_DURATION_SECONDS`. When `0` + (the default), behavior is unchanged: credentials are kept for half of their remaining + lifetime. From 3542f25933329d72d88470714809661d0d8319ce Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Wed, 18 Nov 2026 23:16:52 -0500 Subject: [PATCH 11/12] fix(cache): validate refresh buffer at startup, fall back instead of throwing Addresses dimas-b's review: - Reworded the buffer=0 (half-lifetime) description to not call it "legacy" -- it's a reasonable choice on its own, not just a fallback being phased out. - Moved range validation for STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS out of the cache's request path and into a new ProductionReadinessChecks.checkStorageCredentialRefreshBuffer, modeled on the existing checkCatalogConfigAuthorization pattern (checks both the global default and every realm override). An out-of-range value is now surfaced loudly at server startup instead of failing a live credential request the first time a realm happens to need one. - StorageCredentialCache.refreshBufferMs() no longer throws on a bad value; it logs a warning and falls back to the default half-lifetime behavior (buffer=0). Failing a request over a config typo was worse than a safe fallback, now that the real signal lives at startup. Updated StorageCredentialCacheTest's out-of-range test to assert the fallback behavior instead of an exception, and added ProductionReadinessChecksStorageCredentialRefreshBufferTest covering unset/valid/negative/at-duration defaults plus realm-override cases. --- .../core/config/FeatureConfiguration.java | 5 +- .../storage/cache/StorageCredentialCache.java | 23 ++- .../cache/StorageCredentialCacheTest.java | 33 ++-- .../config/ProductionReadinessChecks.java | 58 +++++++ ...cksStorageCredentialRefreshBufferTest.java | 155 ++++++++++++++++++ 5 files changed, 256 insertions(+), 18 deletions(-) create mode 100644 runtime/service/src/test/java/org/apache/polaris/service/config/ProductionReadinessChecksStorageCredentialRefreshBufferTest.java diff --git a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java index 102987b6bfd..4ea1851a9c8 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java @@ -525,8 +525,9 @@ public static void enforceFeatureEnabledOrThrow( + "have before it is considered stale and evicted. When non-zero, credentials " + "are removed from the cache this many seconds before they expire, ensuring " + "clients always receive credentials with at least this much validity left. " - + "When zero (the default), credentials are kept for half of their remaining " - + "lifetime, which is the legacy behavior. Must be less than " + + "When zero (the default), credentials are instead kept for half of their " + + "remaining lifetime -- a reasonable choice on its own when the actual expiry " + + "timeout can't be estimated upfront. Must be less than " + STORAGE_CREDENTIAL_DURATION_SECONDS.key() + ".") .defaultValue(0) diff --git a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java index 8794a485d57..9ad728ca285 100644 --- a/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java +++ b/polaris-core/src/main/java/org/apache/polaris/core/storage/cache/StorageCredentialCache.java @@ -88,18 +88,31 @@ private long maxCacheDurationMs(RealmConfig realmConfig) { } } - /** Minimum buffer to keep between credential expiry and cache eviction. */ + /** + * Minimum buffer to keep between credential expiry and cache eviction. + * + *

An out-of-range value is a misconfiguration, not something to fail a live credential + * request over: {@link org.apache.polaris.service.config.ProductionReadinessChecks} validates + * this same flag at server startup, where a bad value is surfaced loudly before any request can + * be affected. Here, at request time, it's too late for that -- so an invalid value is logged + * and ignored, falling back to the default half-lifetime behavior instead. + */ private long refreshBufferMs(RealmConfig realmConfig) { var refreshBufferSeconds = realmConfig.getConfig(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS); var credentialDurationSeconds = realmConfig.getConfig(FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS); if (refreshBufferSeconds < 0 || refreshBufferSeconds >= credentialDurationSeconds) { - throw new IllegalArgumentException( - String.format( - "%s must be >= 0 and less than %s", + LOGGER + .atWarn() + .log( + "{} is {}, which is not >= 0 and less than {}={}. Falling back to the default " + + "half-lifetime behavior for this realm; fix the configured value.", FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key(), - FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS.key())); + refreshBufferSeconds, + FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS.key(), + credentialDurationSeconds); + return 0L; } return refreshBufferSeconds * 1000L; } diff --git a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java index 6d9e18ee0ec..4f420a5aded 100644 --- a/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java +++ b/polaris-core/src/test/java/org/apache/polaris/core/storage/cache/StorageCredentialCacheTest.java @@ -591,11 +591,26 @@ public void testGetOrLoadRetriesWhenFreshLoadIsUnderBuffer() { } @ParameterizedTest - // -1 is rejected as negative; 3600 is rejected because it's not less than the default - // STORAGE_CREDENTIAL_DURATION_SECONDS of 3600 (1 hour) -- same rejection path as a buffer + // -1 is out of range as negative; 3600 is out of range because it's not less than the default + // STORAGE_CREDENTIAL_DURATION_SECONDS of 3600 (1 hour) -- same out-of-range path as a buffer // greater than the credential duration. + // + // Catching this at request time is too late to fail the request over -- see + // ProductionReadinessChecks.checkStorageCredentialRefreshBuffer for the startup-time check + // that surfaces the same misconfiguration loudly, before any request is affected. Here, the + // cache instead falls back to the default half-lifetime behavior, same as an explicit 0. @ValueSource(ints = {-1, 3600}) - public void testRefreshBufferRejectsOutOfRangeValue(int bufferSeconds) { + public void testRefreshBufferOutOfRangeValueFallsBackToDefault(int bufferSeconds) { + // Credentials expire in 120 seconds from now. With the fallback (buffer=0) behavior, + // effective TTL = 120s / 2 = 60s > 0 -> entry is kept in cache, same as + // testRefreshBufferZeroKeepsEntryInCache. + long expiresAt = System.currentTimeMillis() + 120_000; + StorageAccessConfig config = + StorageAccessConfig.builder() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) + .build(); StorageCredentialCacheKey key = new TestKey( realmContext.getRealmIdentifier(), @@ -605,15 +620,11 @@ public void testRefreshBufferRejectsOutOfRangeValue(int bufferSeconds) { Set.of(), Optional.empty(), realmConfigWithBuffer(bufferSeconds), - () -> - StorageAccessConfig.builder() - .put(StorageAccessProperty.AWS_KEY_ID, "key") - .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") - .build()); + () -> config); - Assertions.assertThatThrownBy(() -> storageCredentialCache.getOrLoad(key)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining(FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key()); + StorageAccessConfig result = storageCredentialCache.getOrLoad(key); + Assertions.assertThat(result).isEqualTo(config); + Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNotNull(); } @Test diff --git a/runtime/service/src/main/java/org/apache/polaris/service/config/ProductionReadinessChecks.java b/runtime/service/src/main/java/org/apache/polaris/service/config/ProductionReadinessChecks.java index c6a1b8ccd01..ccebc22af07 100644 --- a/runtime/service/src/main/java/org/apache/polaris/service/config/ProductionReadinessChecks.java +++ b/runtime/service/src/main/java/org/apache/polaris/service/config/ProductionReadinessChecks.java @@ -569,6 +569,64 @@ public ProductionReadinessCheck checkSkipCredentialSubscopingIndirection( : ProductionReadinessCheck.of(errors.toArray(new Error[0])); } + /** + * {@link org.apache.polaris.core.storage.cache.StorageCredentialCache} treats an + * out-of-range {@code STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS} as a non-fatal + * misconfiguration: it logs a warning and falls back to the default half-lifetime behavior + * rather than failing a live credential request over an operator's typo. This check instead + * surfaces the same problem at startup, loudly, before any request is affected. + */ + @Produces + public ProductionReadinessCheck checkStorageCredentialRefreshBuffer( + FeaturesConfiguration featureConfiguration) { + var bufferFlag = FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS; + var durationFlag = FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS; + var message = + format( + "%s must be >= 0 and less than %s. The invalid value is ignored at runtime and the " + + "default half-lifetime behavior is used instead.", + bufferFlag.key(), durationFlag.key()); + var errors = new ArrayList(); + + int defaultDuration = + parseIntOrDefault( + featureConfiguration.defaults().get(durationFlag.key()), durationFlag.defaultValue()); + int defaultBuffer = + parseIntOrDefault( + featureConfiguration.defaults().get(bufferFlag.key()), bufferFlag.defaultValue()); + if (defaultBuffer < 0 || defaultBuffer >= defaultDuration) { + errors.add(Error.of(message, format("polaris.features.\"%s\"", bufferFlag.key()))); + } + + featureConfiguration + .realmOverrides() + .forEach((realmId, overrides) -> { + String bufferOverride = overrides.overrides().get(bufferFlag.key()); + if (bufferOverride == null) { + return; + } + int buffer = Integer.parseInt(bufferOverride); + int duration = + parseIntOrDefault(overrides.overrides().get(durationFlag.key()), defaultDuration); + if (buffer < 0 || buffer >= duration) { + errors.add( + Error.of( + message, + format( + "polaris.features.realm-overrides.\"%s\".overrides.\"%s\"", + realmId, bufferFlag.key()))); + } + }); + + return errors.isEmpty() + ? ProductionReadinessCheck.OK + : ProductionReadinessCheck.of(errors.toArray(new Error[0])); + } + + private static int parseIntOrDefault(String value, int defaultValue) { + return value == null ? defaultValue : Integer.parseInt(value); + } + @Produces public ProductionReadinessCheck checkOverlappingSiblingCheckSettings( FeaturesConfiguration featureConfiguration) { diff --git a/runtime/service/src/test/java/org/apache/polaris/service/config/ProductionReadinessChecksStorageCredentialRefreshBufferTest.java b/runtime/service/src/test/java/org/apache/polaris/service/config/ProductionReadinessChecksStorageCredentialRefreshBufferTest.java new file mode 100644 index 00000000000..832970370a6 --- /dev/null +++ b/runtime/service/src/test/java/org/apache/polaris/service/config/ProductionReadinessChecksStorageCredentialRefreshBufferTest.java @@ -0,0 +1,155 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.polaris.service.config; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.Map; +import org.apache.polaris.core.config.FeatureConfiguration; +import org.apache.polaris.core.config.ProductionReadinessCheck; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.junit.jupiter.MockitoExtension; +import org.mockito.Mockito; + +@ExtendWith(MockitoExtension.class) +class ProductionReadinessChecksStorageCredentialRefreshBufferTest { + + private static final String BUFFER_KEY = + FeatureConfiguration.STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS.key(); + private static final String DURATION_KEY = + FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS.key(); + + private ProductionReadinessChecks checks; + + @BeforeEach + void setUp() { + checks = new ProductionReadinessChecks(); + } + + @Test + void unsetDefaultsReturnOk() { + // Neither flag configured: falls back to the flags' own built-in defaults + // (buffer=0, duration=3600), which are mutually valid. + FeaturesConfiguration config = mockConfig(Map.of(), Map.of()); + + ProductionReadinessCheck result = checks.checkStorageCredentialRefreshBuffer(config); + + assertThat(result.ready()).isTrue(); + } + + @Test + void validDefaultsReturnOk() { + FeaturesConfiguration config = + mockConfig(Map.of(BUFFER_KEY, "300", DURATION_KEY, "3600"), Map.of()); + + ProductionReadinessCheck result = checks.checkStorageCredentialRefreshBuffer(config); + + assertThat(result.ready()).isTrue(); + } + + @Test + void negativeDefaultReturnsWarning() { + FeaturesConfiguration config = + mockConfig(Map.of(BUFFER_KEY, "-1", DURATION_KEY, "3600"), Map.of()); + + ProductionReadinessCheck result = checks.checkStorageCredentialRefreshBuffer(config); + + assertThat(result.ready()).isFalse(); + assertThat(result.getErrors()) + .singleElement() + .satisfies(error -> { + assertThat(error.offendingProperty()).contains(BUFFER_KEY); + assertThat(error.severe()).isFalse(); + }); + } + + @Test + void defaultAtOrAboveDurationReturnsWarning() { + FeaturesConfiguration config = + mockConfig(Map.of(BUFFER_KEY, "3600", DURATION_KEY, "3600"), Map.of()); + + ProductionReadinessCheck result = checks.checkStorageCredentialRefreshBuffer(config); + + assertThat(result.ready()).isFalse(); + assertThat(result.getErrors()).hasSize(1); + } + + @Test + void realmOverrideOutOfRangeReturnsWarning() { + FeaturesConfiguration config = + mockConfig( + Map.of(BUFFER_KEY, "300", DURATION_KEY, "3600"), + Map.of("test-realm", mockRealmOverrides(Map.of(BUFFER_KEY, "-1")))); + + ProductionReadinessCheck result = checks.checkStorageCredentialRefreshBuffer(config); + + assertThat(result.ready()).isFalse(); + assertThat(result.getErrors()) + .singleElement() + .satisfies(error -> + assertThat(error.offendingProperty()).contains("test-realm").contains(BUFFER_KEY)); + } + + @Test + void realmOverrideWithOwnDurationIsCheckedAgainstItsOwnDuration() { + // The realm overrides both: buffer=1800 is fine against the realm's own duration=7200, + // even though it would be invalid against the global default duration of 3600. + FeaturesConfiguration config = + mockConfig( + Map.of(BUFFER_KEY, "300", DURATION_KEY, "3600"), + Map.of( + "test-realm", + mockRealmOverrides(Map.of(BUFFER_KEY, "1800", DURATION_KEY, "7200")))); + + ProductionReadinessCheck result = checks.checkStorageCredentialRefreshBuffer(config); + + assertThat(result.ready()).isTrue(); + } + + @Test + void realmNotOverridingBufferIsNotChecked() { + // Default buffer/duration are valid; the realm only overrides an unrelated flag, so it + // shouldn't be re-evaluated against the buffer check at all. + FeaturesConfiguration config = + mockConfig( + Map.of(BUFFER_KEY, "300", DURATION_KEY, "3600"), + Map.of("test-realm", mockRealmOverrides(Map.of()))); + + ProductionReadinessCheck result = checks.checkStorageCredentialRefreshBuffer(config); + + assertThat(result.ready()).isTrue(); + } + + private static FeaturesConfiguration mockConfig( + Map defaults, Map realmOverrides) { + FeaturesConfiguration config = Mockito.mock(FeaturesConfiguration.class); + Mockito.when(config.defaults()).thenReturn(defaults); + Mockito.when(config.realmOverrides()).thenReturn(realmOverrides); + return config; + } + + private static RealmOverridable.RealmOverrides mockRealmOverrides(Map overrides) { + RealmOverridable.RealmOverrides realmOverrides = + Mockito.mock(RealmOverridable.RealmOverrides.class); + Mockito.when(realmOverrides.overrides()).thenReturn(overrides); + return realmOverrides; + } +} From e414238e7d3b68996cf71b36be3752ea0e22ddec Mon Sep 17 00:00:00 2001 From: Rahul Joshi Date: Wed, 18 Nov 2026 23:28:34 -0500 Subject: [PATCH 12/12] docs: sync config reference page with the reworded flag description Missed this mirrored doc page when rewording the 'legacy' framing in FeatureConfiguration.java's description string earlier -- same text, kept in sync. --- .../configuration/config-sections/flags-polaris_features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md b/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md index de587cb1523..f13d34360f4 100644 --- a/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md +++ b/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md @@ -580,7 +580,7 @@ The duration of time that vended storage credentials are valid for. Support for ##### `polaris.features."STORAGE_CREDENTIAL_REFRESH_BUFFER_SECONDS"` -Minimum remaining validity (in seconds) that a cached storage credential must have before it is considered stale and evicted. When non-zero, credentials are removed from the cache this many seconds before they expire, ensuring clients always receive credentials with at least this much validity left. When zero (the default), credentials are kept for half of their remaining lifetime, which is the legacy behavior. Must be less than STORAGE_CREDENTIAL_DURATION_SECONDS. +Minimum remaining validity (in seconds) that a cached storage credential must have before it is considered stale and evicted. When non-zero, credentials are removed from the cache this many seconds before they expire, ensuring clients always receive credentials with at least this much validity left. When zero (the default), credentials are instead kept for half of their remaining lifetime -- a reasonable choice on its own when the actual expiry timeout can't be estimated upfront. Must be less than STORAGE_CREDENTIAL_DURATION_SECONDS. - **Type:** `Integer` - **Default:** `0`