Merge branch 'master' into support_unix_domain_sockets_in_server

Author: cfredri4

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016-2020 Michael Zhang <[email protected]>
+Copyright (c) 2016-2021 Michael Zhang <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README-zh-CN.md

@@ -37,7 +37,7 @@ QQ交流群：294712648
 
 2.x.x.RELEASE 支持 Spring Boot 2.1.x/2.2.x 和 Spring Cloud Greenwich / Hoxton。
 
-最新版本： `2.10.1.RELEASE`
+最新版本： `2.12.0.RELEASE`
 
 ( `2.4.0.RELEASE` 用于 Spring Boot 2.0.x & Spring Cloud Finchy).
 
@@ -57,15 +57,15 @@ QQ交流群：294712648
 <dependency>
   <groupId>net.devh</groupId>
   <artifactId>grpc-spring-boot-starter</artifactId>
-  <version>2.10.1.RELEASE</version>
+  <version>2.12.0.RELEASE</version>
 </dependency>
 ````
 
 Gradle：
 
 ````gradle
 dependencies {
-  compile 'net.devh:grpc-spring-boot-starter:2.10.1.RELEASE'
+  compile 'net.devh:grpc-spring-boot-starter:2.12.0.RELEASE'
 }
 ````
 
@@ -77,15 +77,15 @@ dependencies {
 <dependency>
   <groupId>net.devh</groupId>
   <artifactId>grpc-server-spring-boot-starter</artifactId>
-  <version>2.10.1.RELEASE</version>
+  <version>2.12.0.RELEASE</version>
 </dependency>
 ````
 
 Gradle：
 
 ````gradle
 dependencies {
-  compile 'net.devh:grpc-server-spring-boot-starter:2.10.1.RELEASE'
+  compile 'net.devh:grpc-server-spring-boot-starter:2.12.0.RELEASE'
 }
 ````
 
@@ -117,15 +117,15 @@ public class GrpcServerService extends GreeterGrpc.GreeterImplBase {
 <dependency>
   <groupId>net.devh</groupId>
   <artifactId>grpc-client-spring-boot-starter</artifactId>
-  <version>2.10.1.RELEASE</version>
+  <version>2.12.0.RELEASE</version>
 </dependency>
 ````
 
 Gradle：
 
 ````gradle
 dependencies {
-  compile 'net.devh:grpc-client-spring-boot-starter:2.10.1.RELEASE'
+  compile 'net.devh:grpc-client-spring-boot-starter:2.12.0.RELEASE'
 }
 ````
 在 grpc 客户端的的 stub 字段上添加 `@GrpcClient(serverName)` 注解。

README.md

@@ -52,7 +52,7 @@ README: [English](README.md) | [中文](README-zh-CN.md)
 
 2.x.x.RELEASE supports Spring Boot 2.1.x/2.2.x & Spring Cloud Greenwich/Hoxton.
 
-The latest version: ``2.10.1.RELEASE``
+The latest version: ``2.12.0.RELEASE``
 
 (Use `2.4.0.RELEASE` for Spring Boot 2.0.x & Spring Cloud Finchley).
 
@@ -72,15 +72,15 @@ To add a dependency using Maven, use the following:
 <dependency>
   <groupId>net.devh</groupId>
   <artifactId>grpc-spring-boot-starter</artifactId>
-  <version>2.10.1.RELEASE</version>
+  <version>2.12.0.RELEASE</version>
 </dependency>
 ````
 
 To add a dependency using Gradle:
 
 ````gradle
 dependencies {
-  implementation 'net.devh:grpc-spring-boot-starter:2.10.1.RELEASE'
+  implementation 'net.devh:grpc-spring-boot-starter:2.12.0.RELEASE'
 }
 ````
 
@@ -92,15 +92,15 @@ To add a dependency using Maven, use the following:
 <dependency>
   <groupId>net.devh</groupId>
   <artifactId>grpc-server-spring-boot-starter</artifactId>
-  <version>2.10.1.RELEASE</version>
+  <version>2.12.0.RELEASE</version>
 </dependency>
 ````
 
 To add a dependency using Gradle:
 
 ````gradle
 dependencies {
-  implementation 'net.devh:grpc-server-spring-boot-starter:2.10.1.RELEASE'
+  implementation 'net.devh:grpc-server-spring-boot-starter:2.12.0.RELEASE'
 }
 ````
 
@@ -134,15 +134,15 @@ To add a dependency using Maven, use the following:
 <dependency>
   <groupId>net.devh</groupId>
   <artifactId>grpc-client-spring-boot-starter</artifactId>
-  <version>2.10.1.RELEASE</version>
+  <version>2.12.0.RELEASE</version>
 </dependency>
 ````
 
 To add a dependency using Gradle:
 
 ````gradle
 dependencies {
-  compile 'net.devh:grpc-client-spring-boot-starter:2.10.1.RELEASE'
+  compile 'net.devh:grpc-client-spring-boot-starter:2.12.0.RELEASE'
 }
 ````
 

build.gradle

@@ -9,22 +9,25 @@ buildscript {
         }
     }
     ext {
-        projectVersion = '2.11.0-SNAPSHOT'
+        projectVersion = '2.13.0-SNAPSHOT'
 
         // https://github.com/grpc/grpc-java/releases
-        grpcVersion = '1.32.2'
+        grpcVersion = '1.37.0'
+
+        // https://github.com/google/guava/releases
+        guavaVersion = '30.1.1-jre'
         // https://github.com/protocolbuffers/protobuf/releases
-        protobufVersion = '3.13.0'
+        protobufVersion = '3.15.8'
         protobufGradlePluginVersion = '0.8.12'
 
         // https://github.com/spring-projects/spring-boot/releases
-        springBootVersion = '2.3.4.RELEASE'
+        springBootVersion = '2.4.5'
         // https://github.com/spring-cloud/spring-cloud-release/releases
-        springCloudVersion = 'Hoxton.SR8'
+        springCloudVersion = '2020.0.2'
         // https://github.com/alibaba/spring-cloud-alibaba/releases
-        springCloudAlibabaNacosVersion = '2.2.3.RELEASE'
+        springCloudAlibabaNacosVersion = '2021.1'
         // https://github.com/spring-projects/spring-security-oauth/releases
-        springSecurityOAuthVersion = '2.5.0.RELEASE'
+        springSecurityOAuthVersion = '2.5.1.RELEASE'
 
         lombokPluginVersion = '4.0.0'
         versioningPluginVersion = '2.14.0'
@@ -35,14 +38,13 @@ buildscript {
 plugins {
     id 'java'
     id 'java-library'
-    // future improvement would be to use the version declared above in the ext block instead of repeating it here
-    id 'org.springframework.boot' version '2.3.4.RELEASE' apply false
-    id 'io.spring.dependency-management' version '1.0.10.RELEASE'
+    id 'org.springframework.boot' version "${springBootVersion}" apply false
+    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
     id 'net.nemerosa.versioning' version '2.14.0'
-    id 'com.google.protobuf' version '0.8.13'
+    id 'com.google.protobuf' version '0.8.15'
     id 'io.franzbecker.gradle-lombok' version '4.0.0' apply false
-    id 'com.github.ben-manes.versions' version '0.33.0' // gradle dependencyUpdates
-    id 'com.diffplug.spotless' version '5.7.0'
+    id 'com.github.ben-manes.versions' version '0.36.0' // gradle dependencyUpdates
+    id 'com.diffplug.spotless' version '5.11.0'
 }
 
 // If you attempt to build without the `--scan` parameter in `gradle 6.0+` it will cause a build error that it can't find
@@ -58,7 +60,7 @@ if (hasProperty('buildScan')) {
 wrapper {
     // Update using:
     // ./gradlew wrapper --gradle-version=6.5 --distribution-type=bin
-    gradleVersion = '6.7'
+    gradleVersion = '7.0'
 }
 
 def buildTimeAndDate = OffsetDateTime.now()
@@ -77,6 +79,12 @@ allprojects {
     apply plugin: 'com.diffplug.spotless'
     apply plugin: 'io.franzbecker.gradle-lombok'
 
+    java {
+        toolchain {
+            languageVersion = JavaLanguageVersion.of(8)
+        }
+    }
+
     compileJava {
         sourceCompatibility = JavaVersion.VERSION_1_8
         targetCompatibility = JavaVersion.VERSION_1_8
@@ -87,6 +95,13 @@ allprojects {
         '-Xlint:all', '-Xlint:-processing'
     ]
 
+    eclipse {
+        classpath {
+            downloadJavadoc = true
+            downloadSources = true
+        }
+    }
+
     spotless {
         java {
             licenseHeaderFile rootProject.file('extra/spotless/mit-license.java')
@@ -96,11 +111,20 @@ allprojects {
         }
         format('misc') {
             target('**/*.gradle', '**/*.md', '**/*.yml')
+            targetExclude('**/build/**/*.*')
             trimTrailingWhitespace()
             endWithNewline()
         }
     }
 
+    normalization {
+        runtimeClasspath {
+            metaInf{
+                ignoreAttribute('Build-Time')
+            }
+        }
+    }
+
     // Copy LICENSE
     tasks.withType(Jar) {
         from(project.rootDir) {
@@ -131,7 +155,6 @@ allprojects {
 
     repositories {
         mavenCentral()
-        jcenter()
     }
 
     buildscript {
@@ -156,8 +179,11 @@ allprojects { project ->
             imports {
                 mavenBom "org.springframework.boot:spring-boot-starter-parent:${springBootVersion}"
                 mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
+                mavenBom "com.alibaba.cloud:spring-cloud-alibaba-dependencies:${springCloudAlibabaNacosVersion}"
                 mavenBom "com.google.protobuf:protobuf-bom:${protobufVersion}"
+                mavenBom "com.google.guava:guava-bom:${guavaVersion}"
                 mavenBom "io.grpc:grpc-bom:${grpcVersion}"
+                mavenBom "org.junit:junit-bom:5.7.0"
             }
         }
 

docs/en/client/configuration.md

@@ -13,6 +13,7 @@ This section describes how you can configure your grpc-spring-boot-starter clien
   - [ClientInterceptor](#clientinterceptor)
   - [StubFactory](#stubfactory)
   - [StubTransformer](#stubtransformer)
+- [Custom NameResolverProvider](#custom-nameresolverprovider)
 
 ## Additional Topics <!-- omit in toc -->
 
@@ -64,7 +65,7 @@ There are a number of supported schemes, that you can use to determine the targe
   one and also supports `SVC` lookups. See also [Kubernetes Setup](../kubernetes.md).
 - `discovery` (Prio 6): \
   (Optional) Uses spring-cloud's `DiscoveryClient` to lookup appropriate targets. The connections will be refreshed
-  automatically during `HeartbeatEvent`s. Uses the `gRPC.port` metadata to determine the port, otherwise uses the
+  automatically during `HeartbeatEvent`s. Uses the `gRPC_port` metadata to determine the port, otherwise uses the
   service port. \
   Example: `discovery:///service-name`
 - `self` (Prio 0): \
@@ -80,7 +81,8 @@ There are a number of supported schemes, that you can use to determine the targe
   You can define custom
   [`NameResolverProvider`s](https://javadoc.io/page/io.grpc/grpc-all/latest/io/grpc/NameResolverProvider.html) those
   will be picked up, by either via Java's `ServiceLoader` or from spring's application context and registered in
-  the `NameResolverRegistry`.
+  the `NameResolverRegistry`. \
+  See also [Custom NameResolverProvider](#custom-nameresolverprovider)
 
 If you don't define an address it will be guessed:
 
@@ -128,13 +130,60 @@ public GrpcChannelConfigurer keepAliveClientConfigurer() {
 
 ### ClientInterceptor
 
+`ClientInterceptor`s can be used for various tasks, including:
+
+- Authentication/Authorization
+- Request validation
+- Response filtering
+- Attaching additional context to the call (e.g. tracing ids)
+- Exception to error `Status` response mapping
+- Logging
+- ...
+
 There are three ways to add a `ClientInterceptor` to your channel.
 
 - Define the `ClientInterceptor` as a global interceptor using either the `@GrpcGlobalClientInterceptor` annotation,
   or a `GlobalClientInterceptorConfigurer`
 - Explicitly list them in the `@GrpcClient#interceptors` or `@GrpcClient#interceptorNames` field
 - Use a `StubTransformer` and call `stub.withInterceptors(ClientInterceptor... interceptors)`
 
+The following examples demonstrate how to use annotations to create a global client interceptor:
+
+````java
+@Configuration
+public class ThirdPartyInterceptorConfig {}
+
+    @GrpcGlobalServerInterceptor
+    LogGrpcInterceptor logServerInterceptor() {
+        return new LogGrpcInterceptor();
+    }
+
+}
+````
+
+This variant is very handy if you wish to add third-party interceptors to the global scope.
+
+For your own interceptor implementations you can achieve the same result by adding the annotation to the class itself:
+
+````java
+@GrpcGlobalServerInterceptor
+public class LogGrpcInterceptor implements ServerInterceptor {
+
+    private static final Logger log = LoggerFactory.getLogger(LogGrpcInterceptor.class);
+
+    @Override
+    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
+            ServerCall<ReqT, RespT> serverCall,
+            Metadata metadata,
+            ServerCallHandler<ReqT, RespT> serverCallHandler) {
+
+        log.info(serverCall.getMethodDescriptor().getFullMethodName());
+        return serverCallHandler.startCall(serverCall, metadata);
+    }
+
+}
+````
+
 ### StubFactory
 
 A `StubFactory` is used to create a `Stub` of a specific type. The registered stub factories will be checked in order
@@ -196,6 +245,23 @@ You can also use `StubTransformer`s to add custom `ClientInterceptor`s to your s
 
 > **Note**: The `StubTransformer`s are applied after the  `@GrpcClient#interceptors(Names)` have been added.
 
+## Custom NameResolverProvider
+
+Sometimes you might have some custom logic that decides which server you wish to connect to, you can achieve this
+using a custom `NameResolverProvider`.
+
+> **Note:** This can only be used to decide this on an application level and not on a per request level.
+
+This library provides some `NameResolverProvider`s itself so you can use them as a
+[reference](https://github.com/yidongnan/grpc-spring-boot-starter/tree/master/grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/nameresolver).
+
+You can register your `NameResolverProvider` by adding it to `META-INF/services/io.grpc.NameResolverProvider` for Java's
+`ServiceLoader` or adding it your spring context. If you wish to use some spring beans inside your `NameResolver`, then
+you have to define it via spring context (unless you wish to use `static`).
+
+> **Note:** `NameResolverProvider`s are registered gloablly, so might run into issues if you boot up two or more
+> applications simulataneosly in the same JVM (e.g. during tests).
+
 ## Additional Topics <!-- omit in toc -->
 
 - [Getting Started](getting-started.md)