1 grpc Examples 2 ============================================== 3 4 The examples require grpc-java to already be built. You are strongly encouraged 5 to check out a git release tag, since there will already be a build of grpc 6 available. Otherwise you must follow [COMPILING](../COMPILING.md). 7 8 You may want to read through the 9 [Quick Start Guide](https://grpc.io/docs/quickstart/java.html) 10 before trying out the examples. 11 12 To build the examples, run in this directory: 13 14 ``` 15 $ ./gradlew installDist 16 ``` 17 18 This creates the scripts `hello-world-server`, `hello-world-client`, 19 `hello-world-tls-server`, `hello-world-tls-client`, 20 `route-guide-server`, and `route-guide-client` in the 21 `build/install/examples/bin/` directory that run the examples. Each 22 example requires the server to be running before starting the client. 23 24 For example, to try the hello world example first run: 25 26 ``` 27 $ ./build/install/examples/bin/hello-world-server 28 ``` 29 30 And in a different terminal window run: 31 32 ``` 33 $ ./build/install/examples/bin/hello-world-client 34 ``` 35 36 ### Hello World with TLS 37 38 Running the hello world with TLS is the same as the normal hello world, but takes additional args: 39 40 **hello-world-tls-server**: 41 42 ```text 43 USAGE: HelloWorldServerTls host port certChainFilePath privateKeyFilePath [trustCertCollectionFilePath] 44 Note: You only need to supply trustCertCollectionFilePath if you want to enable Mutual TLS. 45 ``` 46 47 **hello-world-tls-client**: 48 49 ```text 50 USAGE: HelloWorldClientTls host port [trustCertCollectionFilePath] [clientCertChainFilePath] [clientPrivateKeyFilePath] 51 Note: clientCertChainFilePath and clientPrivateKeyFilePath are only needed if mutual auth is desired. And if you specify clientCertChainFilePath you must also specify clientPrivateKeyFilePath 52 ``` 53 54 #### Generating self-signed certificates for use with grpc 55 56 You can use the following script to generate self-signed certificates for grpc-java including the hello world with TLS examples: 57 58 ```bash 59 # Changes these CN's to match your hosts in your environment if needed. 60 SERVER_CN=localhost 61 CLIENT_CN=localhost # Used when doing mutual TLS 62 63 echo Generate CA key: 64 openssl genrsa -passout pass:1111 -des3 -out ca.key 4096 65 echo Generate CA certificate: 66 # Generates ca.crt which is the trustCertCollectionFile 67 openssl req -passin pass:1111 -new -x509 -days 365 -key ca.key -out ca.crt -subj "/CN=${SERVER_CN}" 68 echo Generate server key: 69 openssl genrsa -passout pass:1111 -des3 -out server.key 4096 70 echo Generate server signing request: 71 openssl req -passin pass:1111 -new -key server.key -out server.csr -subj "/CN=${SERVER_CN}" 72 echo Self-signed server certificate: 73 # Generates server.crt which is the certChainFile for the server 74 openssl x509 -req -passin pass:1111 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt 75 echo Remove passphrase from server key: 76 openssl rsa -passin pass:1111 -in server.key -out server.key 77 echo Generate client key 78 openssl genrsa -passout pass:1111 -des3 -out client.key 4096 79 echo Generate client signing request: 80 openssl req -passin pass:1111 -new -key client.key -out client.csr -subj "/CN=${CLIENT_CN}" 81 echo Self-signed client certificate: 82 # Generates client.crt which is the clientCertChainFile for the client (need for mutual TLS only) 83 openssl x509 -passin pass:1111 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt 84 echo Remove passphrase from client key: 85 openssl rsa -passin pass:1111 -in client.key -out client.key 86 echo Converting the private keys to X.509: 87 # Generates client.pem which is the clientPrivateKeyFile for the Client (needed for mutual TLS only) 88 openssl pkcs8 -topk8 -nocrypt -in client.key -out client.pem 89 # Generates server.pem which is the privateKeyFile for the Server 90 openssl pkcs8 -topk8 -nocrypt -in server.key -out server.pem 91 ``` 92 93 #### Hello world example with TLS (no mutual auth): 94 95 ```bash 96 # Server 97 ./build/install/examples/bin/hello-world-server-tls mate 50440 ~/Downloads/sslcert/server.crt ~/Downloads/sslcert/server.pem 98 # Client 99 ./build/install/examples/bin/hello-world-client-tls mate 50440 ~/Downloads/sslcert/ca.crt 100 ``` 101 102 #### Hello world example with TLS with mutual auth: 103 104 ```bash 105 # Server 106 ./build/install/examples/bin/hello-world-server-tls mate 54440 ~/Downloads/sslcert/server.crt ~/Downloads/sslcert/server.pem ~/Downloads/sslcert/ca.crt 107 # Client 108 ./build/install/examples/bin/hello-world-client-tls mate 54440 ~/Downloads/sslcert/ca.crt ~/Downloads/sslcert/client.crt ~/Downloads/sslcert/client.pem 109 ``` 110 111 That's it! 112 113 Please refer to gRPC Java's [README](../README.md) and 114 [tutorial](https://grpc.io/docs/tutorials/basic/java.html) for more 115 information. 116 117 ## Maven 118 119 If you prefer to use Maven: 120 ``` 121 $ mvn verify 122 $ # Run the server 123 $ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldServer 124 $ # In another terminal run the client 125 $ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldClient 126 ``` 127 128 ## Bazel 129 130 If you prefer to use Bazel: 131 ``` 132 (With Bazel v0.8.0 or above.) 133 $ bazel build :hello-world-server :hello-world-client 134 $ # Run the server: 135 $ bazel-bin/hello-world-server 136 $ # In another terminal run the client 137 $ bazel-bin/hello-world-client 138 ``` 139 140 Unit test examples 141 ============================================== 142 143 Examples for unit testing gRPC clients and servers are located in [examples/src/test](src/test). 144 145 In general, we DO NOT allow overriding the client stub. 146 We encourage users to leverage `InProcessTransport` as demonstrated in the examples to 147 write unit tests. `InProcessTransport` is light-weight and runs the server 148 and client in the same process without any socket/TCP connection. 149 150 For testing a gRPC client, create the client with a real stub 151 using an 152 [InProcessChannel](../core/src/main/java/io/grpc/inprocess/InProcessChannelBuilder.java), 153 and test it against an 154 [InProcessServer](../core/src/main/java/io/grpc/inprocess/InProcessServerBuilder.java) 155 with a mock/fake service implementation. 156 157 For testing a gRPC server, create the server as an InProcessServer, 158 and test it against a real client stub with an InProcessChannel. 159 160 The gRPC-java library also provides a JUnit rule, 161 [GrpcServerRule](../testing/src/main/java/io/grpc/testing/GrpcCleanupRule.java), to do the graceful 162 shutdown boilerplate for you. 163
