Add tests; rename create to setup; cleanup

Author: mtdowling

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);
+        }
+    }
 }

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

@@ -105,17 +105,17 @@ static <I extends Identity> CredentialChain<I> assemble(
         List<ChainIdentityProvider> sorted = sortByOrdering(registrations);
 
         // Call create() on each provider in sorted order.
-        ChainSetup setup = new ChainSetup(executor);
+        ChainSetup setup = ChainSetup.builder().executor(executor).build();
 
         for (ChainIdentityProvider provider : sorted) {
             setup.setCurrentProvider(provider);
-            provider.create(identityType, setup);
+            provider.setup(identityType, setup);
             if (setup.isTerminal()) {
                 break;
             }
         }
 
-        List<ChainSetup.NamedResolver> ordered = setup.resolvers();
+        var ordered = setup.resolvers();
 
         if (LOGGER.isDebugEnabled()) {
             LOGGER.debug("Assembled credential chain: {}",
@@ -207,6 +207,7 @@ private static void warnDetectedButUnclaimed(Set<StandardProvider> claimed) {
     }
 
     @Override
+    @SuppressWarnings("unchecked")
     public IdentityResult<I> resolveIdentity(Context requestProperties) {
         if (resolvers.isEmpty()) {
             return IdentityResult.ofError(getClass(),
@@ -218,16 +219,15 @@ public IdentityResult<I> resolveIdentity(Context requestProperties) {
         List<Object> errors = new ArrayList<>();
 
         for (var nr : resolvers) {
-            @SuppressWarnings("unchecked")
-            var result = (IdentityResult<I>) nr.resolver().resolveIdentity(requestProperties);
+            var result = nr.resolver().resolveIdentity(requestProperties);
             if (result.identity() != null) {
                 if (!nr.featureIds().isEmpty()) {
                     var ids = requestProperties.get(CallContext.FEATURE_IDS);
                     if (ids != null) {
                         ids.addAll(nr.featureIds());
                     }
                 }
-                return result;
+                return (IdentityResult<I>) result;
             }
             errors.add(nr.name());
             errors.add(result.error());

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

@@ -58,11 +58,11 @@ public boolean isDetected() {
 
     /**
      * Parses AWS shared config/credentials files and stores the result on the
-     * {@link ProviderContext} for downstream providers.
+     * {@link ChainSetup} for downstream providers.
      *
      * <p>This provider does not itself resolve credentials — it returns {@code null} from
      * {@code create()}. Its purpose is to make the parsed profile available via
-     * {@link ProviderContext#profile()} for all subsequent profile-based slots.
+     * {@link ChainSetup#profile()} for all subsequent profile-based slots.
      */
     SHARED_CONFIG(null) {
         @Override
@@ -76,11 +76,6 @@ public boolean isDetected() {
         }
     },
 
-    /**
-     * Profile-based web identity token ({@code web_identity_token_file} + {@code role_arn}).
-     *
-     * <p>Requires the STS module. Reads the active profile from {@link ProviderContext#profile()}.
-     */
     /**
      * Profile-based static keys ({@code aws_access_key_id} + {@code aws_secret_access_key}).
      *

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

@@ -64,7 +64,7 @@ public Set<CredentialFeatureId> featureIds() {
     }
 
     @Override
-    public void create(Class<? extends Identity> identityType, ChainSetup setup) {
+    public void setup(Class<? extends Identity> identityType, ChainSetup setup) {
         if (identityType != AwsCredentialsIdentity.class) {
             return;
         }

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

@@ -48,7 +48,7 @@ public Set<CredentialFeatureId> featureIds() {
     }
 
     @Override
-    public void create(Class<? extends Identity> identityType, ChainSetup setup) {
+    public void setup(Class<? extends Identity> identityType, ChainSetup setup) {
         if (identityType != AwsCredentialsIdentity.class) {
             return;
         }