Add endpoint rules engine

Author: mtdowling

build.gradle.kts

@@ -7,6 +7,11 @@ plugins {
     alias(libs.plugins.jreleaser)
 }
 
+repositories {
+    mavenLocal()
+    mavenCentral()
+}
+
 task("addGitHooks") {
     onlyIf("unix") {
         !Os.isFamily(Os.FAMILY_WINDOWS)

buildSrc/src/main/kotlin/smithy-java.module-conventions.gradle.kts

@@ -49,7 +49,6 @@ afterEvaluate {
         manifest {
             attributes(mapOf("Automatic-Module-Name" to moduleName))
         }
-        duplicatesStrategy = DuplicatesStrategy.FAIL
     }
 }
 

client/client-core/src/main/java/software/amazon/smithy/java/client/core/CallContext.java

@@ -5,7 +5,6 @@
 
 package software.amazon.smithy.java.client.core;
 
-import java.time.Duration;
 import java.util.HashSet;
 import java.util.Set;
 import software.amazon.smithy.java.auth.api.identity.Identity;
@@ -15,30 +14,26 @@
 
 /**
  * Context parameters made available to underlying transports like HTTP clients.
+ *
+ * <p>Settings that can be applied client-wide can be found in {@link ClientContext}.
  */
 public final class CallContext {
     /**
-     * The total amount of time to wait for an API call to complete, including retries, and serialization.
+     * The read-only endpoint for the request.
      */
-    public static final Context.Key<Duration> API_CALL_TIMEOUT = Context.key("API call timeout");
-
-    /**
-     * The amount of time to wait for a single, underlying network request to complete before giving up and timing out.
-     */
-    public static final Context.Key<Duration> API_CALL_ATTEMPT_TIMEOUT = Context.key("API call attempt timeout");
+    public static final Context.Key<Endpoint> ENDPOINT = Context.key("Endpoint of the request");
 
     /**
      * The endpoint resolver used to resolve the destination endpoint for a request.
+     *
+     * <p>This is a read-only value; modifying this value has no effect on a request.
      */
     public static final Context.Key<EndpointResolver> ENDPOINT_RESOLVER = Context.key("EndpointResolver");
 
     /**
-     * The read-only resolved endpoint for the request.
-     */
-    public static final Context.Key<Endpoint> ENDPOINT = Context.key("Endpoint of the request");
-
-    /**
-     * The identity resolved for the request.
+     * The read-only identity resolved for the request.
+     *
+     * <p>This is a read-only value; modifying this value has no effect on a request.
      */
     public static final Context.Key<Identity> IDENTITY = Context.key("Identity of the caller");
 
@@ -74,16 +69,5 @@ public final class CallContext {
             "Feature IDs used with a request",
             HashSet::new);
 
-    /**
-     * The name of the application, used in things like user-agent headers.
-     *
-     * <p>This value is used by AWS SDKs, but can be used generically for any client.
-     * See <a href="https://docs.aws.amazon.com/sdkref/latest/guide/feature-appid.html">Application ID</a> for more
-     * information.
-     *
-     * <p>This value should be less than 50 characters.
-     */
-    public static final Context.Key<String> APPLICATION_ID = Context.key("Application ID");
-
     private CallContext() {}
 }

client/client-core/src/main/java/software/amazon/smithy/java/client/core/Client.java

@@ -13,6 +13,7 @@
 import software.amazon.smithy.java.auth.api.identity.IdentityResolvers;
 import software.amazon.smithy.java.client.core.auth.scheme.AuthScheme;
 import software.amazon.smithy.java.client.core.auth.scheme.AuthSchemeResolver;
+import software.amazon.smithy.java.client.core.endpoint.Endpoint;
 import software.amazon.smithy.java.client.core.endpoint.EndpointResolver;
 import software.amazon.smithy.java.client.core.interceptors.CallHook;
 import software.amazon.smithy.java.client.core.interceptors.ClientInterceptor;
@@ -224,6 +225,34 @@ public B endpointResolver(EndpointResolver endpointResolver) {
             return (B) this;
         }
 
+        /**
+         * Set a custom endpoint for the client to use.
+         *
+         * <p>Note that things like "hostLabel" traits may still cause the endpoint to change. For a completely
+         * static endpoint that never changes, use {@link EndpointResolver#staticHost}.
+         *
+         * @param customEndpoint Endpoint to use with the client.
+         * @return the builder.
+         */
+        @SuppressWarnings("unchecked")
+        public B endpoint(Endpoint customEndpoint) {
+            putConfig(ClientContext.CUSTOM_ENDPOINT, customEndpoint);
+            return (B) this;
+        }
+
+        /**
+         * Set a custom endpoint for the client to use.
+         *
+         * @param customEndpoint Endpoint to use with the client.
+         * @return the builder.
+         * @see #endpoint(Endpoint)
+         */
+        @SuppressWarnings("unchecked")
+        public B endpoint(String customEndpoint) {
+            putConfig(ClientContext.CUSTOM_ENDPOINT, Endpoint.builder().uri(customEndpoint).build());
+            return (B) this;
+        }
+
         /**
          * Add an interceptor to the client.
          *

client/client-core/src/main/java/software/amazon/smithy/java/client/core/ClientCall.java

@@ -64,6 +64,8 @@ private ClientCall(Builder<I, O> builder) {
         supportedAuthSchemes = builder.supportedAuthSchemes.stream()
                 .collect(Collectors.toMap(AuthScheme::schemeId, Function.identity(), (key1, key2) -> key1));
 
+        context.put(CallContext.ENDPOINT_RESOLVER, endpointResolver);
+
         // Retries
         retryStrategy = Objects.requireNonNull(builder.retryStrategy, "retryStrategy is null");
         retryScope = Objects.requireNonNullElse(builder.retryScope, "");

client/client-core/src/main/java/software/amazon/smithy/java/client/core/ClientConfig.java

@@ -70,7 +70,19 @@ private ClientConfig(Builder builder) {
         this.transport = builder.transport;
         ClientPipeline.validateProtocolAndTransport(protocol, transport);
 
-        this.endpointResolver = Objects.requireNonNull(builder.endpointResolver, "endpointResolver is null");
+        // Use an explicitly given resolver if one was set.
+        if (builder.endpointResolver != null) {
+            this.endpointResolver = builder.endpointResolver;
+        } else {
+            // Use a custom endpoint and static endpoint resolver if a custom endpoint was given.
+            // Things like the Smithy rules engine based resolver look for this property to know if a custom endpoint
+            // was provided in this manner.
+            var customEndpoint = builder.context.get(ClientContext.CUSTOM_ENDPOINT);
+            if (customEndpoint == null) {
+                throw new NullPointerException("Both endpointResolver and ClientContext.CUSTOM_ENDPOINT are not set");
+            }
+            this.endpointResolver = EndpointResolver.staticEndpoint(customEndpoint);
+        }
 
         this.interceptors = List.copyOf(builder.interceptors);
 

client/client-core/src/main/java/software/amazon/smithy/java/client/core/ClientContext.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.java.client.core;
+
+import java.time.Duration;
+import software.amazon.smithy.java.client.core.endpoint.Endpoint;
+import software.amazon.smithy.java.client.core.endpoint.EndpointResolver;
+import software.amazon.smithy.java.context.Context;
+
+/**
+ * Context parameters that can be provided on a client config and take effect on each request.
+ *
+ * <p>Other per/call settings can be found in {@link CallContext}.
+ */
+public final class ClientContext {
+    /**
+     * A custom endpoint used in each request.
+     *
+     * <p>This can be used in lieu of setting something like {@link EndpointResolver#staticEndpoint}, allowing
+     * endpoint resolvers like the Smithy Rules Engine resolver to still process and validate endpoints even when a
+     * custom endpoint is provided.
+     */
+    public static final Context.Key<Endpoint> CUSTOM_ENDPOINT = Context.key("Custom endpoint to use with requests");
+
+    /**
+     * The name of the application, used in things like user-agent headers.
+     *
+     * <p>This value is used by AWS SDKs, but can be used generically for any client.
+     * See <a href="https://docs.aws.amazon.com/sdkref/latest/guide/feature-appid.html">Application ID</a> for more
+     * information.
+     *
+     * <p>This value should be less than 50 characters.
+     */
+    public static final Context.Key<String> APPLICATION_ID = Context.key("Application ID");
+
+    /**
+     * The total amount of time to wait for an API call to complete, including retries, and serialization.
+     *
+     * <p>This can be overridden per/call too.
+     */
+    public static final Context.Key<Duration> API_CALL_TIMEOUT = Context.key("API call timeout");
+
+    /**
+     * The amount of time to wait for a single, underlying network request to complete before giving up and timing out.
+     *
+     * <p>This can be overridden per/call too.
+     */
+    public static final Context.Key<Duration> API_CALL_ATTEMPT_TIMEOUT = Context.key("API call attempt timeout");
+
+    private ClientContext() {}
+}

client/client-core/src/main/java/software/amazon/smithy/java/client/core/endpoint/Endpoint.java

@@ -51,10 +51,13 @@ public interface Endpoint {
      *
      * @return the builder.
      */
+    @SuppressWarnings("unchecked")
     default Builder toBuilder() {
         var builder = new EndpointImpl.Builder();
         builder.uri(uri());
-        properties().forEach(k -> builder.properties.put(k, property(k)));
+        for (var e : properties()) {
+            builder.putProperty((Context.Key<Object>) e, property(e));
+        }
         for (EndpointAuthScheme authScheme : authSchemes()) {
             builder.addAuthScheme(authScheme);
         }

client/client-core/src/main/java/software/amazon/smithy/java/client/core/endpoint/EndpointContext.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.java.client.core.endpoint;
+
+import java.util.List;
+import java.util.Map;
+import software.amazon.smithy.java.context.Context;
+
+/**
+ * Context parameters specifically relevant to a resolved {@link Endpoint} property.
+ */
+public final class EndpointContext {
+
+    private EndpointContext() {}
+
+    /**
+     * Assigns headers to an endpoint. These are typically HTTP headers.
+     */
+    public static final Context.Key<Map<String, List<String>>> HEADERS = Context.key("Endpoint headers");
+}

client/client-core/src/main/java/software/amazon/smithy/java/client/core/endpoint/EndpointImpl.java

@@ -23,8 +23,11 @@ final class EndpointImpl implements Endpoint {
 
     private EndpointImpl(Builder builder) {
         this.uri = Objects.requireNonNull(builder.uri);
-        this.authSchemes = List.copyOf(builder.authSchemes);
-        this.properties = Map.copyOf(builder.properties);
+        this.authSchemes = builder.authSchemes == null ? List.of() : builder.authSchemes;
+        this.properties = builder.properties == null ? Map.of() : builder.properties;
+        // Clear out the builder, making this class immutable and the builder still reusable.
+        builder.authSchemes = null;
+        builder.properties = null;
     }
 
     @Override
@@ -66,11 +69,16 @@ public int hashCode() {
         return Objects.hash(uri, authSchemes, properties);
     }
 
+    @Override
+    public String toString() {
+        return "Endpoint{uri=" + uri + ", authSchemes=" + authSchemes + ", properties=" + properties + '}';
+    }
+
     static final class Builder implements Endpoint.Builder {
 
         private URI uri;
-        private final List<EndpointAuthScheme> authSchemes = new ArrayList<>();
-        final Map<Context.Key<?>, Object> properties = new HashMap<>();
+        private List<EndpointAuthScheme> authSchemes;
+        private Map<Context.Key<?>, Object> properties;
 
         @Override
         public Builder uri(URI uri) {
@@ -89,12 +97,18 @@ public Builder uri(String uri) {
 
         @Override
         public Builder addAuthScheme(EndpointAuthScheme authScheme) {
+            if (this.authSchemes == null) {
+                this.authSchemes = new ArrayList<>();
+            }
             this.authSchemes.add(authScheme);
             return this;
         }
 
         @Override
         public <T> Builder putProperty(Context.Key<T> property, T value) {
+            if (this.properties == null) {
+                this.properties = new HashMap<>();
+            }
             properties.put(property, value);
             return this;
         }

client/client-core/src/main/java/software/amazon/smithy/java/client/core/endpoint/EndpointResolver.java

@@ -72,7 +72,7 @@ static EndpointResolver staticEndpoint(URI endpoint) {
      */
     static EndpointResolver staticHost(Endpoint endpoint) {
         Objects.requireNonNull(endpoint);
-        return params -> CompletableFuture.completedFuture(endpoint);
+        return new StaticHostResolver(endpoint);
     }
 
     /**
@@ -83,8 +83,7 @@ static EndpointResolver staticHost(Endpoint endpoint) {
      */
     static EndpointResolver staticHost(String endpoint) {
         Objects.requireNonNull(endpoint);
-        var ep = Endpoint.builder().uri(endpoint).build();
-        return params -> CompletableFuture.completedFuture(ep);
+        return staticHost(Endpoint.builder().uri(endpoint).build());
     }
 
     /**
@@ -95,7 +94,6 @@ static EndpointResolver staticHost(String endpoint) {
      */
     static EndpointResolver staticHost(URI endpoint) {
         Objects.requireNonNull(endpoint);
-        var ep = Endpoint.builder().uri(endpoint).build();
-        return params -> CompletableFuture.completedFuture(ep);
+        return staticHost(Endpoint.builder().uri(endpoint).build());
     }
 }

client/client-core/src/main/java/software/amazon/smithy/java/client/core/endpoint/StaticHostResolver.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.java.client.core.endpoint;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * An endpoint resolver that always returns the same endpoint.
+ *
+ * @param endpoint Endpoint to return exactly.
+ */
+record StaticHostResolver(Endpoint endpoint) implements EndpointResolver {
+    @Override
+    public CompletableFuture<Endpoint> resolveEndpoint(EndpointResolverParams params) {
+        return CompletableFuture.completedFuture(endpoint);
+    }
+}