Merge pull request #548 from cfredri4/support-unix-domain-sockets

yidongnan · web-flow · commit 3e4deca041bb · 2021-06-07T16:30:36.000+08:00
Support unix domain sockets
diff --git a/docs/en/client/configuration.md b/docs/en/client/configuration.md
@@ -38,9 +38,10 @@ If you prefer to read the sources instead, you can do so
 [here](https://github.com/yidongnan/grpc-spring-boot-starter/blob/master/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/config/GrpcChannelProperties.java#L58).
 
 The properties for the channels are all prefixed with `grpc.client.__name__.` and `grpc.client.__name__.security.`
-respectively. The channel name is taken from the `@GrpcClient` annotation. If you wish to configure some options such as
-trusted certificates for all servers at once you can do so using `GLOBAL` as name. Properties that are defined for a
-name channel take precedence over global once.
+respectively. The channel name is taken from the `@GrpcClient("__name__")` annotation.
+If you wish to configure some options such as trusted certificates for all servers at once,
+you can do so using `GLOBAL` as name.
+Properties that are defined for a specific/named channel take precedence over `GLOBAL` ones.
 
 ### Choosing the Target
 
@@ -55,6 +56,7 @@ There are a number of supported schemes, that you can use to determine the targe
 
 - `static` (Prio 4): \
   A simple static list of IPs (both v4 and v6), that can be use connect to the server (Supports `localhost`). \
+  For resolvable hostnames please use `dns` instead. \
   Example: `static://192.168.1.1:8080,10.0.0.1:1337`
 - [`dns`](https://github.com/grpc/grpc-java/blob/master/core/src/main/java/io/grpc/internal/DnsNameResolver.java#L66)
   (Prio 5): \
@@ -77,6 +79,11 @@ There are a number of supported schemes, that you can use to determine the targe
   This is a special scheme that will bypass the normal channel factory and will use the `InProcessChannelFactory`
   instead. Use it to connect to the [`InProcessServer`](../server/configuration.md#enabling-the-inprocessserver). \
   Example: `in-process:foobar`
+- `unix` (Available on Unix based systems only): \
+  This is a special scheme that uses unix's domain socket addresses to connect to a server. \
+  If you are using `grpc-netty` you also need the `netty-transport-native-epoll` dependency.
+  `grpc-netty-shaded` already contains that dependency, so there is no need to add anything for it to work. \
+  Example: `unix:/run/grpc-server`
 - *custom*: \
   You can define custom
   [`NameResolverProvider`s](https://javadoc.io/page/io.grpc/grpc-all/latest/io/grpc/NameResolverProvider.html) those
@@ -267,6 +274,7 @@ you have to define it via spring context (unless you wish to use `static`).
 - [Getting Started](getting-started.md)
 - *Configuration*
 - [Security](security.md)
+- [Tests with Grpc-Stubs](testing.md)
 
 ----------
 
diff --git a/docs/en/server/configuration.md b/docs/en/server/configuration.md
@@ -75,6 +75,21 @@ grpc.client.inProcess.address=in-process:<SomeName>
 This is especially useful for tests as they don't need to open a specific port and thus can run concurrently (on a build
 server).
 
+### Using Unix's Domain Sockets
+
+On Unix based systems you can also use domain sockets to locally communicate between server and clients.
+
+Simply configure the address like this:
+
+````properties
+grpc.server.address=unix:/run/grpc-server
+````
+
+Clients can then connect to the server using the same address.
+
+If you are using `grpc-netty` you also need the `netty-transport-native-epoll` dependency.
+`grpc-netty-shaded` already contains that dependency, so there is no need to add anything for it to work.
+
 ## Configuration via Beans
 
 While this library intents to provide most of the features as configuration option, sometimes the overhead for adding it
diff --git a/grpc-client-spring-boot-autoconfigure/build.gradle b/grpc-client-spring-boot-autoconfigure/build.gradle
@@ -24,6 +24,7 @@ dependencies {
     // api comes from java-library, and allows exposure of the dependency to consumers of the library
     //  this means it can be used implicitly without specifying the dependency (unless you wish to override with a different version, or exclude)
     optionalSupportApi 'io.grpc:grpc-netty'
+    optionalSupportApi 'io.netty:netty-transport-native-epoll'
     api 'io.grpc:grpc-netty-shaded'
     api 'io.grpc:grpc-protobuf'
     api 'io.grpc:grpc-stub'
diff --git a/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/channelfactory/NettyChannelFactory.java b/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/channelfactory/NettyChannelFactory.java
@@ -18,6 +18,7 @@
 package net.devh.boot.grpc.client.channelfactory;
 
 import static java.util.Objects.requireNonNull;
+import static net.devh.boot.grpc.common.util.GrpcUtils.DOMAIN_SOCKET_ADDRESS_SCHEME;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -30,12 +31,16 @@
 
 import io.grpc.netty.GrpcSslContexts;
 import io.grpc.netty.NettyChannelBuilder;
+import io.netty.channel.epoll.EpollDomainSocketChannel;
+import io.netty.channel.epoll.EpollEventLoopGroup;
+import io.netty.channel.unix.DomainSocketAddress;
 import io.netty.handler.ssl.SslContextBuilder;
 import net.devh.boot.grpc.client.config.GrpcChannelProperties;
 import net.devh.boot.grpc.client.config.GrpcChannelProperties.Security;
 import net.devh.boot.grpc.client.config.GrpcChannelsProperties;
 import net.devh.boot.grpc.client.config.NegotiationType;
 import net.devh.boot.grpc.client.interceptor.GlobalClientInterceptorRegistry;
+import net.devh.boot.grpc.common.util.GrpcUtils;
 
 /**
  * This channel factory creates and manages netty based {@link GrpcChannelFactory}s.
@@ -71,8 +76,15 @@ protected NettyChannelBuilder newChannelBuilder(final String name) {
         if (address == null) {
             address = URI.create(name);
         }
-        return NettyChannelBuilder.forTarget(address.toString())
-                .defaultLoadBalancingPolicy(properties.getDefaultLoadBalancingPolicy());
+        if (DOMAIN_SOCKET_ADDRESS_SCHEME.equals(address.getScheme())) {
+            final String path = GrpcUtils.extractDomainSocketAddressPath(address.toString());
+            return NettyChannelBuilder.forAddress(new DomainSocketAddress(path))
+                    .channelType(EpollDomainSocketChannel.class)
+                    .eventLoopGroup(new EpollEventLoopGroup());
+        } else {
+            return NettyChannelBuilder.forTarget(address.toString())
+                    .defaultLoadBalancingPolicy(properties.getDefaultLoadBalancingPolicy());
+        }
     }
 
     @Override
diff --git a/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/channelfactory/ShadedNettyChannelFactory.java b/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/channelfactory/ShadedNettyChannelFactory.java
@@ -18,6 +18,7 @@
 package net.devh.boot.grpc.client.channelfactory;
 
 import static java.util.Objects.requireNonNull;
+import static net.devh.boot.grpc.common.util.GrpcUtils.DOMAIN_SOCKET_ADDRESS_SCHEME;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -30,12 +31,16 @@
 
 import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
 import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
+import io.grpc.netty.shaded.io.netty.channel.epoll.EpollDomainSocketChannel;
+import io.grpc.netty.shaded.io.netty.channel.epoll.EpollEventLoopGroup;
+import io.grpc.netty.shaded.io.netty.channel.unix.DomainSocketAddress;
 import io.grpc.netty.shaded.io.netty.handler.ssl.SslContextBuilder;
 import net.devh.boot.grpc.client.config.GrpcChannelProperties;
 import net.devh.boot.grpc.client.config.GrpcChannelProperties.Security;
 import net.devh.boot.grpc.client.config.GrpcChannelsProperties;
 import net.devh.boot.grpc.client.config.NegotiationType;
 import net.devh.boot.grpc.client.interceptor.GlobalClientInterceptorRegistry;
+import net.devh.boot.grpc.common.util.GrpcUtils;
 
 /**
  * This channel factory creates and manages shaded netty based {@link GrpcChannelFactory}s.
@@ -69,8 +74,15 @@ protected NettyChannelBuilder newChannelBuilder(final String name) {
         if (address == null) {
             address = URI.create(name);
         }
-        return NettyChannelBuilder.forTarget(address.toString())
-                .defaultLoadBalancingPolicy(properties.getDefaultLoadBalancingPolicy());
+        if (DOMAIN_SOCKET_ADDRESS_SCHEME.equals(address.getScheme())) {
+            final String path = GrpcUtils.extractDomainSocketAddressPath(address.toString());
+            return NettyChannelBuilder.forAddress(new DomainSocketAddress(path))
+                    .channelType(EpollDomainSocketChannel.class)
+                    .eventLoopGroup(new EpollEventLoopGroup());
+        } else {
+            return NettyChannelBuilder.forTarget(address.toString())
+                    .defaultLoadBalancingPolicy(properties.getDefaultLoadBalancingPolicy());
+        }
     }
 
     @Override
diff --git a/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/config/GrpcChannelProperties.java b/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/config/GrpcChannelProperties.java
@@ -104,6 +104,8 @@ public void setAddress(final URI address) {
      * <li>{@code dns:///example.com:9090}</li>
      * <li>{@code discovery:/foo-service}</li>
      * <li>{@code discovery:///foo-service}</li>
+     * <li>{@code unix:<relative-path>} (Additional dependencies may be required)</li>
+     * <li>{@code unix://</absolute-path>} (Additional dependencies may be required)</li>
      * </ul>
      *
      * @param address The string representation of an uri to use as target address or null to use a fallback.
diff --git a/grpc-common-spring-boot/src/main/java/net/devh/boot/grpc/common/util/GrpcUtils.java b/grpc-common-spring-boot/src/main/java/net/devh/boot/grpc/common/util/GrpcUtils.java
@@ -26,6 +26,16 @@
  */
 public final class GrpcUtils {
 
+    /**
+     * A constant that defines, the scheme of a Unix domain socket address.
+     */
+    public static final String DOMAIN_SOCKET_ADDRESS_SCHEME = "unix";
+
+    /**
+     * A constant that defines, the scheme prefix of a Unix domain socket address.
+     */
+    public static final String DOMAIN_SOCKET_ADDRESS_PREFIX = DOMAIN_SOCKET_ADDRESS_SCHEME + ":";
+
     /**
      * The cloud discovery metadata key used to identify the grpc port.
      */
@@ -36,6 +46,30 @@ public final class GrpcUtils {
      */
     public static final int INTER_PROCESS_DISABLE = -1;
 
+    /**
+     * Extracts the domain socket address specific path from the given full address. The address must fulfill the
+     * requirements as specified by <a href="https://grpc.github.io/grpc/cpp/md_doc_naming.html">grpc</a>.
+     *
+     * @param address The address to extract it from.
+     * @return The extracted domain socket address specific path.
+     * @throws IllegalArgumentException If the given address is not a valid address.
+     */
+    public static String extractDomainSocketAddressPath(final String address) {
+        if (!address.startsWith(DOMAIN_SOCKET_ADDRESS_PREFIX)) {
+            throw new IllegalArgumentException(address + " is not a valid domain socket address.");
+        }
+        String path = address.substring(DOMAIN_SOCKET_ADDRESS_PREFIX.length());
+        if (path.startsWith("//")) {
+            path = path.substring(2);
+            // We don't check this as there is no reliable way to check that it's an absolute path,
+            // especially when Windows adds support for these in the future
+            // if (!path.startsWith("/")) {
+            // throw new IllegalArgumentException("If the path is prefixed with '//', then the path must be absolute");
+            // }
+        }
+        return path;
+    }
+
     /**
      * Extracts the service name from the given method.
      *
diff --git a/grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/config/GrpcServerProperties.java b/grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/config/GrpcServerProperties.java
@@ -39,6 +39,7 @@
 import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
 import io.grpc.netty.shaded.io.netty.handler.ssl.SslContextBuilder;
 import lombok.Data;
+import net.devh.boot.grpc.common.util.GrpcUtils;
 
 /**
  * The properties for the gRPC server that will be started as part of the application.
@@ -69,6 +70,8 @@ public class GrpcServerProperties {
     /**
      * Bind address for the server. Defaults to {@link #ANY_IP_ADDRESS "*"}. Alternatively you can restrict this to
      * {@link #ANY_IPv4_ADDRESS "0.0.0.0"} or {@link #ANY_IPv6_ADDRESS "::"}. Or restrict it to exactly one IP address.
+     * On unix systems it is also possible to prefix it with {@link GrpcUtils#DOMAIN_SOCKET_ADDRESS_PREFIX unix:} to use
+     * domain socket addresses/paths (Additional dependencies may be required).
      *
      * @param address The address to bind to.
      * @return The address the server should bind to.
diff --git a/grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/serverfactory/NettyGrpcServerFactory.java b/grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/serverfactory/NettyGrpcServerFactory.java
@@ -18,6 +18,8 @@
 package net.devh.boot.grpc.server.serverfactory;
 
 import static java.util.Objects.requireNonNull;
+import static net.devh.boot.grpc.common.util.GrpcUtils.DOMAIN_SOCKET_ADDRESS_PREFIX;
+import static net.devh.boot.grpc.server.config.GrpcServerProperties.ANY_IP_ADDRESS;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -33,7 +35,11 @@
 
 import io.grpc.netty.GrpcSslContexts;
 import io.grpc.netty.NettyServerBuilder;
+import io.netty.channel.epoll.EpollEventLoopGroup;
+import io.netty.channel.epoll.EpollServerDomainSocketChannel;
+import io.netty.channel.unix.DomainSocketAddress;
 import io.netty.handler.ssl.SslContextBuilder;
+import net.devh.boot.grpc.common.util.GrpcUtils;
 import net.devh.boot.grpc.server.config.ClientAuth;
 import net.devh.boot.grpc.server.config.GrpcServerProperties;
 import net.devh.boot.grpc.server.config.GrpcServerProperties.Security;
@@ -61,7 +67,13 @@ public NettyGrpcServerFactory(final GrpcServerProperties properties,
     protected NettyServerBuilder newServerBuilder() {
         final String address = getAddress();
         final int port = getPort();
-        if (GrpcServerProperties.ANY_IP_ADDRESS.equals(address)) {
+        if (address.startsWith(DOMAIN_SOCKET_ADDRESS_PREFIX)) {
+            final String path = GrpcUtils.extractDomainSocketAddressPath(address);
+            return NettyServerBuilder.forAddress(new DomainSocketAddress(path))
+                    .channelType(EpollServerDomainSocketChannel.class)
+                    .bossEventLoopGroup(new EpollEventLoopGroup(1))
+                    .workerEventLoopGroup(new EpollEventLoopGroup());
+        } else if (ANY_IP_ADDRESS.equals(address)) {
             return NettyServerBuilder.forPort(port);
         } else {
             return NettyServerBuilder.forAddress(new InetSocketAddress(InetAddresses.forString(address), port));
diff --git a/grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/serverfactory/ShadedNettyGrpcServerFactory.java b/grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/serverfactory/ShadedNettyGrpcServerFactory.java
@@ -18,6 +18,8 @@
 package net.devh.boot.grpc.server.serverfactory;
 
 import static java.util.Objects.requireNonNull;
+import static net.devh.boot.grpc.common.util.GrpcUtils.DOMAIN_SOCKET_ADDRESS_PREFIX;
+import static net.devh.boot.grpc.server.config.GrpcServerProperties.ANY_IP_ADDRESS;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -33,7 +35,11 @@
 
 import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
 import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
+import io.grpc.netty.shaded.io.netty.channel.epoll.EpollEventLoopGroup;
+import io.grpc.netty.shaded.io.netty.channel.epoll.EpollServerDomainSocketChannel;
+import io.grpc.netty.shaded.io.netty.channel.unix.DomainSocketAddress;
 import io.grpc.netty.shaded.io.netty.handler.ssl.SslContextBuilder;
+import net.devh.boot.grpc.common.util.GrpcUtils;
 import net.devh.boot.grpc.server.config.ClientAuth;
 import net.devh.boot.grpc.server.config.GrpcServerProperties;
 import net.devh.boot.grpc.server.config.GrpcServerProperties.Security;
@@ -62,7 +68,13 @@ public ShadedNettyGrpcServerFactory(final GrpcServerProperties properties,
     protected NettyServerBuilder newServerBuilder() {
         final String address = getAddress();
         final int port = getPort();
-        if (GrpcServerProperties.ANY_IP_ADDRESS.equals(address)) {
+        if (address.startsWith(DOMAIN_SOCKET_ADDRESS_PREFIX)) {
+            final String path = GrpcUtils.extractDomainSocketAddressPath(address);
+            return NettyServerBuilder.forAddress(new DomainSocketAddress(path))
+                    .channelType(EpollServerDomainSocketChannel.class)
+                    .bossEventLoopGroup(new EpollEventLoopGroup(1))
+                    .workerEventLoopGroup(new EpollEventLoopGroup());
+        } else if (ANY_IP_ADDRESS.equals(address)) {
             return NettyServerBuilder.forPort(port);
         } else {
             return NettyServerBuilder.forAddress(new InetSocketAddress(InetAddresses.forString(address), port));
diff --git a/tests/src/test/java/net/devh/boot/grpc/test/setup/UnixSetupTest.java b/tests/src/test/java/net/devh/boot/grpc/test/setup/UnixSetupTest.java
@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2016-2021 Michael Zhang <yidongnan@gmail.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package net.devh.boot.grpc.test.setup;
+
+import org.junit.jupiter.api.condition.EnabledOnOs;
+import org.junit.jupiter.api.condition.OS;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import lombok.extern.slf4j.Slf4j;
+import net.devh.boot.grpc.test.config.BaseAutoConfiguration;
+import net.devh.boot.grpc.test.config.ServiceConfiguration;
+
+/**
+ * A test checking that the server and client can start and connect to each other with minimal config.
+ *
+ * @author Daniel Theuke (daniel.theuke@heuboe.de)
+ */
+@Slf4j
+@SpringBootTest(properties = {
+        "grpc.server.address=unix:unix-test",
+        "grpc.client.GLOBAL.address=unix:unix-test",
+        "grpc.client.GLOBAL.negotiationType=PLAINTEXT",
+})
+@SpringJUnitConfig(classes = {ServiceConfiguration.class, BaseAutoConfiguration.class})
+@DirtiesContext
+@EnabledOnOs(OS.LINUX)
+public class UnixSetupTest extends AbstractSimpleServerClientTest {
+
+    public UnixSetupTest() {
+        log.info("--- UnixSetupTest ---");
+    }
+
+}

Original file line number	Diff line number	Diff line change
`@@ -104,6 +104,8 @@ public void setAddress(final URI address) {`
`104`	`104`	`* <li>{@code dns:///example.com:9090}</li>`
`105`	`105`	`* <li>{@code discovery:/foo-service}</li>`
`106`	`106`	`* <li>{@code discovery:///foo-service}</li>`
	`107`	`+ * <li>{@code unix:<relative-path>} (Additional dependencies may be required)</li>`
	`108`	`+ * <li>{@code unix://</absolute-path>} (Additional dependencies may be required)</li>`
`107`	`109`	`* </ul>`
`108`	`110`	`*`
`109`	`111`	`* @param address The string representation of an uri to use as target address or null to use a fallback.`