api: Add ServerCredentials

grpc · ejona86 · Nov 13, 2020 · Nov 7, 2020 · Nov 7, 2020 · Nov 7, 2020
commit 72f402780339754503c7d30d3cce05bb5a07cd0b
diff --git a/api/src/main/java/io/grpc/ChoiceServerCredentials.java b/api/src/main/java/io/grpc/ChoiceServerCredentials.java
@@ -0,0 +1,57 @@
+/*
+ * Copyright 2020 The gRPC Authors
+ *
+ * Licensed 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 io.grpc;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Provides a list of {@link ServerCredentials}, where any one may be used. The credentials are in
+ * preference order.
+ */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/7621")
+public final class ChoiceServerCredentials extends ServerCredentials {
+  /**
+   * Constructs with the provided {@code creds} as options, with preferred credentials first.
+   *
+   * @throws IllegalArgumentException if no creds are provided
+   */
+  public static ServerCredentials create(ServerCredentials... creds) {
+    if (creds.length == 0) {
+      throw new IllegalArgumentException("At least one credential is required");
+    }
+    return new ChoiceServerCredentials(creds);
+  }
+
+  private final List<ServerCredentials> creds;
+
+  private ChoiceServerCredentials(ServerCredentials... creds) {
+    for (ServerCredentials cred : creds) {
+      if (cred == null) {
+        throw new NullPointerException();
+      }
+    }
+    this.creds = Collections.unmodifiableList(new ArrayList<>(Arrays.asList(creds)));
+  }
+
+  /** Non-empty list of credentials, in preference order. */
+  public List<ServerCredentials> getCredentialsList() {
+    return creds;
+  }
+}
diff --git a/api/src/main/java/io/grpc/Grpc.java b/api/src/main/java/io/grpc/Grpc.java
@@ -124,4 +124,15 @@ private static String authorityFromHostAndPort(String host, int port) {
       throw new IllegalArgumentException("Invalid host or port: " + host + " " + port, ex);
     }
   }
+
+  /**
+   * Static factory for creating a new ServerBuilder.
+   *
+   * @param port the port to listen on
+   * @param creds the server identity
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/7621")
+  public static ServerBuilder<?> newServerBuilderForPort(int port, ServerCredentials creds) {
+    return ServerRegistry.getDefaultRegistry().newServerBuilderForPort(port, creds);
+  }
 }
diff --git a/api/src/main/java/io/grpc/InsecureServerCredentials.java b/api/src/main/java/io/grpc/InsecureServerCredentials.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2020 The gRPC Authors
+ *
+ * Licensed 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 io.grpc;
+
+/** No server identity or encryption is to be used. */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/7621")
+public final class InsecureServerCredentials extends ServerCredentials {
+  public static ServerCredentials create() {
+    return new InsecureServerCredentials();
+  }
+
+  private InsecureServerCredentials() {}
+}
diff --git a/api/src/main/java/io/grpc/ServerCredentials.java b/api/src/main/java/io/grpc/ServerCredentials.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2020 The gRPC Authors
+ *
+ * Licensed 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 io.grpc;
+
+/**
+ * Represents a security configuration to be used for servers. There is no generic mechanism for
+ * processing arbitrary {@code ServerCredentials}; the consumer of the credential (the server)
+ * must support each implementation explicitly and separately. Consumers are not required to support
+ * all types or even all possible configurations for types that are partially supported, but they
+ * <em>must</em> at least fully support {@link ChoiceServerCredentials}.
+ *
+ * <p>A {@code ServerCredential} provides server identity. They can also influence types of
+ * encryption used and similar security configuration.
+ *
+ * <p>The concrete credential type should not be relevant to most users of the API and may be an
+ * implementation decision. Users should generally use the {@code ServerCredentials} type for
+ * variables instead of the concrete type. Freshly-constructed credentials should be returned as
+ * {@code ServerCredentials} instead of a concrete type to encourage this pattern. Concrete types
+ * would only be used after {@code instanceof} checks (which must consider
+ * {@code ChoiceServerCredentials}!).
+ */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/7621")
+public abstract class ServerCredentials {}
diff --git a/api/src/main/java/io/grpc/ServerProvider.java b/api/src/main/java/io/grpc/ServerProvider.java
@@ -16,9 +16,8 @@
 
 package io.grpc;
 
+import com.google.common.base.Preconditions;
 import io.grpc.ManagedChannelProvider.ProviderNotFoundException;
-import io.grpc.ServiceProviders.PriorityAccessor;
-import java.util.Collections;
 
 /**
  * Provider of servers for transport agnostic consumption.
@@ -34,28 +33,13 @@
  */
 @Internal
 public abstract class ServerProvider {
-  private static final ServerProvider provider = ServiceProviders.load(
-      ServerProvider.class,
-      Collections.<Class<?>>emptyList(),
-      ServerProvider.class.getClassLoader(),
-      new PriorityAccessor<ServerProvider>() {
-        @Override
-        public boolean isAvailable(ServerProvider provider) {
-          return provider.isAvailable();
-        }
-
-        @Override
-        public int getPriority(ServerProvider provider) {
-          return provider.priority();
-        }
-      });
-
   /**
    * Returns the ClassLoader-wide default server.
    *
    * @throws ProviderNotFoundException if no provider is available
    */
   public static ServerProvider provider() {
+    ServerProvider provider = ServerRegistry.getDefaultRegistry().provider();
     if (provider == null) {
       throw new ProviderNotFoundException("No functional server found. "
           + "Try adding a dependency on the grpc-netty or grpc-netty-shaded artifact");
@@ -81,4 +65,38 @@ public static ServerProvider provider() {
    * Creates a new builder with the given port.
    */
   protected abstract ServerBuilder<?> builderForPort(int port);
+
+  /**
+   * Creates a new builder with the given port and credentials. Returns an error-string result if
+   * unable to understand the credentials.
+   */
+  protected NewServerBuilderResult newServerBuilderForPort(int port, ServerCredentials creds) {
+    return NewServerBuilderResult.error("ServerCredentials are unsupported");
+  }
+
+  public static final class NewServerBuilderResult {
+    private final ServerBuilder<?> serverBuilder;
+    private final String error;
+
+    private NewServerBuilderResult(ServerBuilder<?> serverBuilder, String error) {
+      this.serverBuilder = serverBuilder;
+      this.error = error;
+    }
+
+    public static NewServerBuilderResult serverBuilder(ServerBuilder<?> builder) {
+      return new NewServerBuilderResult(Preconditions.checkNotNull(builder), null);
+    }
+
+    public static NewServerBuilderResult error(String error) {
+      return new NewServerBuilderResult(null, Preconditions.checkNotNull(error));
+    }
+
+    public ServerBuilder<?> getServerBuilder() {
+      return serverBuilder;
+    }
+
+    public String getError() {
+      return error;
+    }
+  }
 }
diff --git a/api/src/main/java/io/grpc/ServerRegistry.java b/api/src/main/java/io/grpc/ServerRegistry.java
@@ -0,0 +1,166 @@
+/*
+ * Copyright 2020 The gRPC Authors
+ *
+ * Licensed 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 io.grpc;
+
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.Preconditions;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.logging.Logger;
+import javax.annotation.concurrent.GuardedBy;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * Registry of {@link ServerProvider}s. The {@link #getDefaultRegistry default instance} loads
+ * providers at runtime through the Java service provider mechanism.
+ */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/7621")
+@ThreadSafe
+public final class ServerRegistry {
+  private static final Logger logger = Logger.getLogger(ServerRegistry.class.getName());
+  private static ServerRegistry instance;
+
+  @GuardedBy("this")
+  private final LinkedHashSet<ServerProvider> allProviders = new LinkedHashSet<>();
+  /** Immutable, sorted version of {@code allProviders}. Is replaced instead of mutating. */
+  @GuardedBy("this")
+  private List<ServerProvider> effectiveProviders = Collections.emptyList();
+
+  /**
+   * Register a provider.
+   *
+   * <p>If the provider's {@link ServerProvider#isAvailable isAvailable()} returns
+   * {@code false}, this method will throw {@link IllegalArgumentException}.
+   *
+   * <p>Providers will be used in priority order. In case of ties, providers are used in
+   * registration order.
+   */
+  public synchronized void register(ServerProvider provider) {
+    addProvider(provider);
+    refreshProviders();
+  }
+
+  private synchronized void addProvider(ServerProvider provider) {
+    Preconditions.checkArgument(provider.isAvailable(), "isAvailable() returned false");
+    allProviders.add(provider);
+  }
+
+  /**
+   * Deregisters a provider.  No-op if the provider is not in the registry.
+   *
+   * @param provider the provider that was added to the register via {@link #register}.
+   */
+  public synchronized void deregister(ServerProvider provider) {
+    allProviders.remove(provider);
+    refreshProviders();
+  }
+
+  private synchronized void refreshProviders() {
+    List<ServerProvider> providers = new ArrayList<>(allProviders);
+    // Sort descending based on priority.
+    // sort() must be stable, as we prefer first-registered providers
+    Collections.sort(providers, Collections.reverseOrder(new Comparator<ServerProvider>() {
+      @Override
+      public int compare(ServerProvider o1, ServerProvider o2) {
+        return o1.priority() - o2.priority();
+      }
+    }));
+    effectiveProviders = Collections.unmodifiableList(providers);
+  }
+
+  /**
+   * Returns the default registry that loads providers via the Java service loader mechanism.
+   */
+  public static synchronized ServerRegistry getDefaultRegistry() {
+    if (instance == null) {
+      List<ServerProvider> providerList = ServiceProviders.loadAll(
+          ServerProvider.class,
+          Collections.<Class<?>>emptyList(),
+          ServerProvider.class.getClassLoader(),
+          new ServerPriorityAccessor());
+      instance = new ServerRegistry();
+      for (ServerProvider provider : providerList) {
+        logger.fine("Service loader found " + provider);
+        if (provider.isAvailable()) {
+          instance.addProvider(provider);
+        }
+      }
+      instance.refreshProviders();
+    }
+    return instance;
+  }
+
+  /**
+   * Returns effective providers, in priority order.
+   */
+  @VisibleForTesting
+  synchronized List<ServerProvider> providers() {
+    return effectiveProviders;
+  }
+
+  // For emulating ServerProvider.provider()
+  ServerProvider provider() {
+    List<ServerProvider> providers = providers();
+    return providers.isEmpty() ? null : providers.get(0);
+  }
+
+  ServerBuilder<?> newServerBuilderForPort(int port, ServerCredentials creds) {
+    List<ServerProvider> providers = providers();
+    if (providers.isEmpty()) {
+      throw new ProviderNotFoundException("No functional server found. "
+          + "Try adding a dependency on the grpc-netty or grpc-netty-shaded artifact");
+    }
+    StringBuilder error = new StringBuilder();
+    for (ServerProvider provider : providers()) {
+      ServerProvider.NewServerBuilderResult result
+          = provider.newServerBuilderForPort(port, creds);
+      if (result.getServerBuilder() != null) {
+        return result.getServerBuilder();
+      }
+      error.append("; ");
+      error.append(provider.getClass().getName());
+      error.append(": ");
+      error.append(result.getError());
+    }
+    throw new ProviderNotFoundException(error.substring(2));
+  }
+
+  private static final class ServerPriorityAccessor
+      implements ServiceProviders.PriorityAccessor<ServerProvider> {
+    @Override
+    public boolean isAvailable(ServerProvider provider) {
+      return provider.isAvailable();
+    }
+
+    @Override
+    public int getPriority(ServerProvider provider) {
+      return provider.priority();
+    }
+  }
+
+  /** Thrown when no suitable {@link ServerProvider} objects can be found. */
+  public static final class ProviderNotFoundException extends RuntimeException {
+    private static final long serialVersionUID = 1;
+
+    public ProviderNotFoundException(String msg) {
+      super(msg);
+    }
+  }
+}