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. 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..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 @@ -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 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) + .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..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 @@ -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; @@ -52,20 +53,22 @@ 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,12 +88,76 @@ private long maxCacheDurationMs(RealmConfig realmConfig) { } } + /** + * 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) { + 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(), + refreshBufferSeconds, + FeatureConfiguration.STORAGE_CREDENTIAL_DURATION_SECONDS.key(), + credentialDurationSeconds); + return 0L; + } + 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, 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) { - return cache.get(key).toAccessConfig(); + StorageCredentialCacheEntry entry = cache.get(key); + if (isUnderRefreshBuffer(entry)) { + cache.invalidate(key); + entry = cache.get(key); + if (isUnderRefreshBuffer(entry)) { + 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(); + } + + private static boolean isUnderRefreshBuffer(StorageCredentialCacheEntry entry) { + if (entry.refreshBufferMs() <= 0) { + return false; + } + long remainingMs = entry.getExpirationTime() - System.currentTimeMillis(); + return remainingMs < entry.refreshBufferMs(); } @VisibleForTesting 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..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 @@ -30,6 +30,7 @@ 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; @@ -39,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"; @@ -441,6 +444,221 @@ 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 + // 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() + .put(StorageAccessProperty.AWS_KEY_ID, "key") + .put(StorageAccessProperty.AWS_SECRET_KEY, "secret") + .put(StorageAccessProperty.AWS_SESSION_TOKEN_EXPIRES_AT_MS, String.valueOf(expiresAt)) + .build(); + AtomicInteger loadCount = new AtomicInteger(); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer(300), + () -> { + loadCount.incrementAndGet(); + return nearExpiryConfig; + }); + + 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(); + } + + @Test + 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. + 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 = + buildKey( + "bufferZeroConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + () -> config); + + storageCredentialCache.getOrLoad(key); + 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(); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferHappyPathConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer(300), + () -> 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(); + + StorageCredentialCacheKey key = + new TestKey( + realmContext.getRealmIdentifier(), + "bufferRetryConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer(300), + () -> configs.get(loadCount.getAndIncrement())); + + StorageAccessConfig result = storageCredentialCache.getOrLoad(key); + Assertions.assertThat(result).isEqualTo(freshConfig); + Assertions.assertThat(loadCount.get()).isEqualTo(2); + } + + @ParameterizedTest + // -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 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(), + "bufferOutOfRangeConfig-" + bufferSeconds, + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer(bufferSeconds), + () -> config); + + StorageAccessConfig result = storageCredentialCache.getOrLoad(key); + Assertions.assertThat(result).isEqualTo(config); + Assertions.assertThat(storageCredentialCache.getIfPresent(key)).isNotNull(); + } + + @Test + 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(), + "bufferNoExpiresAtConfig", + true, + Set.of("s3://bucket/path"), + Set.of(), + Optional.empty(), + realmConfigWithBuffer(300), + () -> { + loadCount.incrementAndGet(); + return noExpiryConfig; + }); + + 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() { return Arrays.asList("config1", "config2", "config3"); } 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; + } +} 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..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 @@ -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 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` + +--- + ##### `polaris.features."SUPPORTED_CATALOG_CONNECTION_TYPES"` The list of supported catalog connection types for federation