Add tests; rename create to setup; cleanup

Author: mtdowling

aws/aws-config/src/fuzz/java/software/amazon/smithy/java/aws/config/AwsProfileFileParserFuzzTest.java

@@ -9,7 +9,7 @@
 import java.nio.charset.StandardCharsets;
 
 /**
- * Fuzz test for the AWS config file parser. Ensures no input can cause unexpected exceptions,
+ * Fuzz test for the AWS config file parser. Helps detect when an input causes unexpected exceptions,
  * OOM, or infinite loops. The only acceptable exception is {@link ConfigFileParseException}.
  */
 class AwsProfileFileParserFuzzTest {

aws/aws-config/src/test/java/software/amazon/smithy/java/aws/config/AwsProfileFileParserTest.java

@@ -9,6 +9,7 @@
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
@@ -237,7 +238,7 @@ void whitespaceOnlyLineWithinSubPropertiesIsBlank() {
     }
 
     private static Map<String, String> mapValues(Map<String, RawProperty> props) {
-        Map<String, String> out = new java.util.LinkedHashMap<>();
+        Map<String, String> out = new LinkedHashMap<>();
         for (var e : props.entrySet()) {
             out.put(e.getKey(), e.getValue().value);
         }

aws/aws-config/src/test/java/software/amazon/smithy/java/aws/config/SepParserConformanceTest.java

@@ -18,8 +18,10 @@
 import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Stream;
 import org.junit.jupiter.api.DynamicTest;
 import org.junit.jupiter.api.TestFactory;
@@ -209,8 +211,8 @@ private void assertSsoSessionsMatch(Map<String, Map<String, Object>> expected, A
         }
     }
 
-    private static java.util.Set<String> profileNameSet(AwsProfileFile file) {
-        java.util.Set<String> names = new java.util.LinkedHashSet<>();
+    private static Set<String> profileNameSet(AwsProfileFile file) {
+        Set<String> names = new LinkedHashSet<>();
         for (AwsProfile p : file.profiles()) {
             names.add(p.name());
         }

aws/aws-credential-chain/src/main/java/software/amazon/smithy/java/aws/credentials/chain/ChainIdentityProvider.java

@@ -12,7 +12,7 @@
  * SPI for registering an identity provider into a credential/token chain.
  *
  * <p>Implementations are discovered via the language's plugin mechanism (e.g., {@code ServiceLoader}
- * in Java) and sorted by {@link #ordering()} before {@link #create} is called. A provider
+ * in Java) and sorted by {@link #ordering()} before {@link #setup} is called. A provider
  * registers its resolver by calling {@link ChainSetup#addResolver} or
  * {@link ChainSetup#addTerminalResolver} from within {@code create()}.
  */
@@ -47,5 +47,5 @@ default Set<CredentialFeatureId> featureIds() {
      * @param identityType the identity class the chain is resolving.
      * @param setup        the chain setup context.
      */
-    void create(Class<? extends Identity> identityType, ChainSetup setup);
+    void setup(Class<? extends Identity> identityType, ChainSetup setup);
 }

aws/aws-credential-chain/src/main/java/software/amazon/smithy/java/aws/credentials/chain/ChainSetup.java

@@ -9,106 +9,256 @@
 import java.util.List;
 import java.util.Set;
 import java.util.concurrent.ScheduledExecutorService;
-import software.amazon.smithy.java.auth.api.identity.Identity;
+import java.util.function.Function;
 import software.amazon.smithy.java.auth.api.identity.IdentityResolver;
 import software.amazon.smithy.java.aws.config.AwsProfile;
 import software.amazon.smithy.java.aws.config.AwsProfileFile;
 import software.amazon.smithy.java.context.Context;
+import software.amazon.smithy.utils.SmithyInternalApi;
 
 /**
- * Mutable assembly context passed to each {@link ChainIdentityProvider#create} during chain
- * construction. Providers use this to read shared state and register resolvers.
+ * Mutable assembly context passed to each {@link ChainIdentityProvider#setup} during
+ * credential chain construction.
  *
- * <p>When {@link #addTerminalResolver} is called, assembly stops — no further providers are invoked.
+ * <p>Providers use this to:
+ * <ul>
+ *   <li>Read shared state ({@link #profile()}, {@link #profileFile()}, {@link #executor()})</li>
+ *   <li>Write shared state ({@link #setProfileFile(AwsProfileFile)}, {@link #setProfile(AwsProfile)})</li>
+ *   <li>Register resolvers ({@link #addResolver(IdentityResolver)}, {@link #addTerminalResolver(IdentityResolver)})</li>
+ *   <li>Read environment variables ({@link #getenv(String)})</li>
+ * </ul>
+ *
+ * <p>When {@link #addTerminalResolver(IdentityResolver)} is called, assembly stops immediately
+ * and no further providers are invoked.
+ *
+ * <p>This class is not thread-safe. It is used only during the single-threaded assembly phase.
+ * Resolvers MUST NOT retain a reference to this object.
  */
 public final class ChainSetup {
     private final ScheduledExecutorService executor;
     private final String profileNameOverride;
     private final Context properties;
     private final List<NamedResolver> resolvers = new ArrayList<>();
+    private final Function<String, String> envFn;
     private AwsProfileFile profileFile;
     private AwsProfile profile;
     private boolean terminal;
-
-    // Current provider being assembled (set by the chain before calling create())
     private ChainIdentityProvider currentProvider;
 
-    public ChainSetup(ScheduledExecutorService executor) {
-        this(executor, null);
+    private ChainSetup(Builder builder) {
+        this.executor = builder.executor;
+        this.profileNameOverride = builder.profileNameOverride;
+        this.properties = Context.create();
+        this.envFn = builder.envFn;
     }
 
-    public ChainSetup(ScheduledExecutorService executor, String profileNameOverride) {
-        this.executor = executor;
-        this.profileNameOverride = profileNameOverride;
-        this.properties = Context.create();
+    /**
+     * Creates a new builder for {@link ChainSetup}.
+     *
+     * @return a new builder.
+     */
+    public static Builder builder() {
+        return new Builder();
     }
 
-    /** Shared executor for background credential refresh. */
+    /**
+     * Returns the shared executor for scheduling background credential refresh tasks.
+     *
+     * @return the scheduled executor, or {@code null} if none was configured.
+     */
     public ScheduledExecutorService executor() {
         return executor;
     }
 
-    /** Client-specified profile name override, or {@code null} for default resolution. */
+    /**
+     * Returns the client-specified profile name override, or {@code null} to use the
+     * default resolution order ({@code AWS_PROFILE} env var, {@code aws.profile} system
+     * property, then {@code "default"}).
+     *
+     * @return the profile name override, or {@code null}.
+     */
     public String profileNameOverride() {
         return profileNameOverride;
     }
 
-    /** General-purpose property bag for sharing state between providers. */
+    /**
+     * Returns the value of the given environment variable, or {@code null} if not set.
+     *
+     * <p>In production this delegates to {@link System#getenv(String)}. In tests, a custom
+     * function can be provided via {@link Builder#env(Function)} for isolation.
+     *
+     * @param name the environment variable name.
+     * @return the value, or {@code null}.
+     */
+    public String getenv(String name) {
+        return envFn.apply(name);
+    }
+
+    /**
+     * Returns a general-purpose typed property bag for sharing additional state between
+     * providers during assembly.
+     *
+     * @return the shared context properties.
+     */
     public Context properties() {
         return properties;
     }
 
-    /** The parsed AWS config/credentials file, or {@code null} if not yet loaded. */
+    /**
+     * Returns the parsed AWS config/credentials file, or {@code null} if not yet loaded.
+     *
+     * <p>Populated by the {@code SHARED_CONFIG} provider during assembly.
+     *
+     * @return the parsed profile file, or {@code null}.
+     */
     public AwsProfileFile profileFile() {
         return profileFile;
     }
 
-    /** Sets the parsed profile file. Called by the SHARED_CONFIG provider. */
+    /**
+     * Sets the parsed AWS config/credentials file. Called by the {@code SHARED_CONFIG}
+     * provider during assembly.
+     *
+     * @param profileFile the parsed profile file.
+     */
     public void setProfileFile(AwsProfileFile profileFile) {
         this.profileFile = profileFile;
     }
 
-    /** The active profile, or {@code null} if not yet loaded. */
+    /**
+     * Returns the active AWS profile, or {@code null} if not yet loaded.
+     *
+     * <p>Populated by the {@code SHARED_CONFIG} provider during assembly.
+     *
+     * @return the active profile, or {@code null}.
+     */
     public AwsProfile profile() {
         return profile;
     }
 
-    /** Sets the active profile. Called by the SHARED_CONFIG provider. */
+    /**
+     * Sets the active AWS profile. Called by the {@code SHARED_CONFIG} provider during assembly.
+     *
+     * @param profile the active profile.
+     */
     public void setProfile(AwsProfile profile) {
         this.profile = profile;
     }
 
     /**
-     * Registers a resolver at the current provider's position. Assembly continues.
+     * Registers a resolver at the current provider's position. Assembly continues after
+     * this call. May be called multiple times to register multiple resolvers that stack
+     * at this position.
+     *
+     * @param resolver the identity resolver to register.
      */
     public void addResolver(IdentityResolver<?> resolver) {
         resolvers.add(new NamedResolver(currentProvider.name(), currentProvider.featureIds(), resolver));
     }
 
     /**
-     * Registers a resolver and stops assembly. No further providers will be called.
+     * Registers a resolver and stops assembly immediately. No further providers will be
+     * called. Use when the credential source is authoritative once detected (e.g.,
+     * environment variables contain a complete set of credentials, or a profile explicitly
+     * configures assume-role).
+     *
+     * @param resolver the identity resolver to register.
      */
     public void addTerminalResolver(IdentityResolver<?> resolver) {
         resolvers.add(new NamedResolver(currentProvider.name(), currentProvider.featureIds(), resolver));
         this.terminal = true;
     }
 
-    // --- Package-private, used by CredentialChain ---
-
+    /**
+     * Sets the current provider being assembled. Called by the chain before invoking
+     * each provider's {@link ChainIdentityProvider#setup} method so that
+     * {@link #addResolver} and {@link #addTerminalResolver} can associate the resolver
+     * with the correct provider name and feature IDs.
+     *
+     * <p>This method is public to support unit testing of individual providers in
+     * isolation. Production code should not call this directly.
+     *
+     * @param provider the provider currently being assembled.
+     */
+    @SmithyInternalApi
     public void setCurrentProvider(ChainIdentityProvider provider) {
         this.currentProvider = provider;
     }
 
+    /**
+     * Returns the list of resolvers registered during assembly, in the order they were added.
+     *
+     * @return the ordered list of named resolvers.
+     */
+    public List<NamedResolver> resolvers() {
+        return resolvers;
+    }
+
     boolean isTerminal() {
         return terminal;
     }
 
-    public List<NamedResolver> resolvers() {
-        return resolvers;
-    }
+    /**
+     * A resolver paired with the name and feature IDs of the provider that registered it.
+     *
+     * @param name       the canonical name of the provider that registered this resolver.
+     * @param featureIds the feature IDs to emit on successful resolution.
+     * @param resolver   the identity resolver.
+     */
+    public record NamedResolver(String name, Set<CredentialFeatureId> featureIds, IdentityResolver<?> resolver) {}
+
+    /**
+     * Builder for {@link ChainSetup}.
+     */
+    public static final class Builder {
+        private ScheduledExecutorService executor;
+        private String profileNameOverride;
+        private Function<String, String> envFn = System::getenv;
 
-    public record NamedResolver<I extends Identity>(
-            String name,
-            Set<CredentialFeatureId> featureIds,
-            IdentityResolver<I> resolver) {}
+        private Builder() {}
+
+        /**
+         * Sets the shared executor for background credential refresh.
+         *
+         * @param executor the scheduled executor.
+         * @return this builder.
+         */
+        public Builder executor(ScheduledExecutorService executor) {
+            this.executor = executor;
+            return this;
+        }
+
+        /**
+         * Sets the profile name override. When set, the {@code SHARED_CONFIG} provider
+         * uses this name instead of resolving from {@code AWS_PROFILE} or system properties.
+         *
+         * @param profileNameOverride the profile name to use.
+         * @return this builder.
+         */
+        public Builder profileNameOverride(String profileNameOverride) {
+            this.profileNameOverride = profileNameOverride;
+            return this;
+        }
+
+        /**
+         * Sets the function used to resolve environment variables. Defaults to
+         * {@link System#getenv(String)}. Override in tests for isolation.
+         *
+         * @param envFn the environment variable lookup function.
+         * @return this builder.
+         */
+        public Builder env(Function<String, String> envFn) {
+            this.envFn = envFn;
+            return this;
+        }
+
+        /**
+         * Builds the {@link ChainSetup}.
+         *
+         * @return the constructed setup.
+         */
+        public ChainSetup build() {
+            return new ChainSetup(this);
+        }
+    }
 }