From 3d0addfc4917807507d42f9cf0c17d9347078d4a Mon Sep 17 00:00:00 2001 From: Pierre Lecerf Date: Thu, 19 Nov 2026 00:58:29 +0100 Subject: [PATCH] feat(w103): delayed secret resolving options --- .../illuin/wombat/core/secret/Secret.java | 67 +++++++++ .../wombat/core/secret/SecretResolver.java | 32 ++++ .../illuin/wombat/core/secret/SecretTest.java | 137 ++++++++++++++++++ 3 files changed, 236 insertions(+) create mode 100644 core/src/main/java/tech/illuin/wombat/core/secret/Secret.java create mode 100644 core/src/test/java/tech/illuin/wombat/core/secret/SecretTest.java diff --git a/core/src/main/java/tech/illuin/wombat/core/secret/Secret.java b/core/src/main/java/tech/illuin/wombat/core/secret/Secret.java new file mode 100644 index 0000000..133b712 --- /dev/null +++ b/core/src/main/java/tech/illuin/wombat/core/secret/Secret.java @@ -0,0 +1,67 @@ +package tech.illuin.wombat.core.secret; + +import java.util.Objects; +import java.util.Optional; + +/** + * A deferred reference to a secret: it carries the key and the {@link SecretResolver} it came from, never the value. + *

+ * The value is resolved on every {@link #fetch()} or {@link #tryFetch()}, so a rotated credential is picked up without + * rebuilding whatever holds the handle, and the value lives in memory only for as long as the caller keeps it. + * Caching, if needed, is the resolver implementation's concern: a handle fetches through whichever resolver produced it. + */ +public final class Secret +{ + private final String key; + private final SecretResolver resolver; + + Secret(String key, SecretResolver resolver) + { + this.key = Objects.requireNonNull(key, "key cannot be null"); + this.resolver = Objects.requireNonNull(resolver, "resolver cannot be null"); + } + + public String key() + { + return this.key; + } + + /** + * @return the current value of the secret + * @throws MissingSecretException when the secret is no longer bound + */ + public String fetch() + { + return this.resolver.require(this.key); + } + + /** + * @return the current value of the secret, empty when it is no longer bound + */ + public Optional tryFetch() + { + return this.resolver.find(this.key); + } + + @Override + public boolean equals(Object o) + { + if (this == o) + return true; + if (!(o instanceof Secret other)) + return false; + return this.key.equals(other.key) && this.resolver == other.resolver; + } + + @Override + public int hashCode() + { + return Objects.hash(this.key, System.identityHashCode(this.resolver)); + } + + @Override + public String toString() + { + return "Secret[" + this.key + "]"; + } +} diff --git a/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java b/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java index 85c3e3a..60be9ea 100644 --- a/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java +++ b/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java @@ -27,6 +27,38 @@ public interface SecretResolver */ Optional find(String key); + /** + * Checks that {@code key} is bound now, and returns a handle that resolves it again on each fetch. + * + * @return a {@link Secret} backed by this resolver + * @throws MissingSecretException when nothing is bound to {@code key} + */ + default Secret requireAsync(String key) + { + this.require(key); + return new Secret(key, this); + } + + /** + * Returns a handle that resolves {@code key} on each fetch, this does not check anything upfront. + * + * @return a {@link Secret} backed by this resolver + */ + default Secret async(String key) + { + return new Secret(key, this); + } + + /** + * Checks whether {@code key} is bound now, and if so returns a handle that resolves it again on each fetch. + * + * @return a {@link Secret} backed by this resolver, empty when nothing is bound to {@code key} + */ + default Optional findAsync(String key) + { + return this.find(key).map(value -> new Secret(key, this)); + } + static SecretResolver standard() { return new EnvironmentSecretResolver(); diff --git a/core/src/test/java/tech/illuin/wombat/core/secret/SecretTest.java b/core/src/test/java/tech/illuin/wombat/core/secret/SecretTest.java new file mode 100644 index 0000000..37f5d58 --- /dev/null +++ b/core/src/test/java/tech/illuin/wombat/core/secret/SecretTest.java @@ -0,0 +1,137 @@ +package tech.illuin.wombat.core.secret; + +import org.junit.jupiter.api.Test; + +import java.util.HashMap; +import java.util.Map; +import java.util.Optional; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class SecretTest +{ + @Test + void requireAsyncReturnsAHandleForABoundKey() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get); + + Secret secret = resolver.requireAsync("API_KEY"); + + assertEquals("API_KEY", secret.key()); + assertEquals("s3cret", secret.fetch()); + assertEquals("s3cret", secret.tryFetch().orElseThrow()); + } + + @Test + void requireAsyncFailsWhenTheKeyIsUnbound() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of()::get); + + MissingSecretException e = assertThrows(MissingSecretException.class, () -> resolver.requireAsync("API_KEY")); + assertEquals("API_KEY", e.key()); + } + + @Test + void findAsyncIsEmptyWhenTheKeyIsUnbound() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get); + + assertTrue(resolver.findAsync("API_KEY").isPresent()); + assertTrue(resolver.findAsync("OTHER").isEmpty()); + } + + @Test + void asyncReturnsAHandleForABoundKey() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get); + + Secret secret = resolver.async("API_KEY"); + + assertEquals("API_KEY", secret.key()); + assertEquals("s3cret", secret.fetch()); + assertEquals("s3cret", secret.tryFetch().orElseThrow()); + } + + @Test + void asyncDoesNotCheckTheKeyUpfront() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of()::get); + + Secret secret = resolver.async("API_KEY"); + + assertEquals("API_KEY", secret.key()); + assertEquals(Optional.empty(), secret.tryFetch()); + MissingSecretException e = assertThrows(MissingSecretException.class, secret::fetch); + assertEquals("API_KEY", e.key()); + } + + @Test + void asyncPicksUpAKeyBoundAfterTheHandleWasCreated() + { + Map env = new HashMap<>(); + SecretResolver resolver = new EnvironmentSecretResolver(env::get); + Secret secret = resolver.async("API_KEY"); + + env.put("API_KEY", "late"); + + assertEquals("late", secret.fetch()); + } + + @Test + void asyncHandleEqualsTheOneFromRequireAsync() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get); + + assertEquals(resolver.requireAsync("API_KEY"), resolver.async("API_KEY")); + } + + @Test + void asyncMethodsRejectNullAndBlankKeys() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of()::get); + + assertThrows(IllegalArgumentException.class, () -> resolver.requireAsync(null)); + assertThrows(IllegalArgumentException.class, () -> resolver.findAsync(" ")); + } + + @Test + void fetchResolvesTheCurrentValueOnEachCall() + { + // The handle carries no value: a rotation or removal after it was obtained shows on the next fetch. + Map env = new HashMap<>(Map.of("API_KEY", "v1")); + SecretResolver resolver = new EnvironmentSecretResolver(env::get); + Secret secret = resolver.requireAsync("API_KEY"); + + env.put("API_KEY", "v2"); + assertEquals("v2", secret.fetch()); + + env.remove("API_KEY"); + assertEquals(Optional.empty(), secret.tryFetch()); + assertThrows(MissingSecretException.class, secret::fetch); + } + + @Test + void toStringDoesNotLeakTheValue() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get); + + Secret secret = resolver.requireAsync("API_KEY"); + + assertFalse(secret.toString().contains("s3cret")); + } + + @Test + void handlesAreEqualForTheSameKeyAndResolver() + { + SecretResolver resolver = new EnvironmentSecretResolver(Map.of("A", "a", "B", "b")::get); + SecretResolver other = new EnvironmentSecretResolver(Map.of("A", "a")::get); + + assertEquals(resolver.requireAsync("A"), resolver.requireAsync("A")); + assertEquals(resolver.requireAsync("A").hashCode(), resolver.requireAsync("A").hashCode()); + assertFalse(resolver.requireAsync("A").equals(resolver.requireAsync("B"))); + assertFalse(resolver.requireAsync("A").equals(other.requireAsync("A"))); + } +}