Add a simple Hello World Guide

README.md

@@ -16,9 +16,22 @@ frameworks, such as Python, Java, and Node. See the
 [roadmap](https://github.com/grpc/grpc-web/blob/master/ROADMAP.md) doc.
 
 
-## Quick Demo
+## Quick Start Guide: Hello World
 
-Try gRPC-Web and run a quick Echo example from the browser!
+You can follow the [Hello World Guide][] to get started with gRPC-Web quickly.
+
+From the guide, you will learn how to
+ - Define your service using protocol buffers
+ - Implement a simple gRPC Service using NodeJS
+ - Configure the Envoy proxy
+ - Generate protobuf message classes and client service stub for the client
+ - Compile all the JS dependencies into a static library that can be consumed
+   by the browser easily
+
+## Advanced Demo: Browser Echo App
+
+You can also try to run a more advanced Echo app from the browser with a
+streaming example.
 
 From the repo root directory:
 
@@ -270,3 +283,6 @@ this project!
 
 * [zaucy](https://github.com/zaucy)
 * [yannic](https://github.com/yannic)
+
+
+[Hello World Guide]:https://github.com/grpc/grpc-web/blob/master/net/grpc/gateway/examples/echo/helloworld/

net/grpc/gateway/examples/echo/helloworld/.gitignore

@@ -0,0 +1,4 @@
+dist/
+*_pb.js
+node_modules/
+package-lock.json

net/grpc/gateway/examples/echo/helloworld/README.md

@@ -0,0 +1,307 @@
+# gRPC-Web Hello World Guide
+
+This guide is intended to help you get started with gRPC-Web with a simple
+Hello World example. For more information about the gRPC-Web project as a
+whole, please visit the [main repo](https://github.com/grpc/grpc-web).
+
+All the code for this example can be found in this current directory.
+
+```sh
+$ cd net/grpc/gateway/examples/echo/helloworld
+```
+
+## Define the Service
+
+First, let's define a gRPC service using
+[protocol buffers](https://developers.google.com/protocol-buffers/). Put this
+in the `helloworld.proto` file. Here we define a request message, a response
+message, and a service with one RPC method: `SayHello`.
+
+```protobuf
+syntax = "proto3";
+
+package helloworld;
+
+service Greeter {
+  rpc SayHello (HelloRequest) returns (HelloReply);
+}
+
+message HelloRequest {
+  string name = 1;
+}
+
+message HelloReply {
+  string message = 1;
+}
+```
+
+## Implement the Service
+
+Then, we need to implement the gRPC Service. In this example, we will use
+NodeJS. Put this in a `server.js` file. Here, we receive the client request,
+and we can access the message field via `call.request.name`. Then we construct
+a nice response and send it back to the client via `callback(null, response)`.
+
+```js
+var PROTO_PATH = __dirname + '/helloworld.proto';
+
+var grpc = require('grpc');
+var protoLoader = require('@grpc/proto-loader');
+var packageDefinition = protoLoader.loadSync(
+    PROTO_PATH,
+    {keepCase: true,
+     longs: String,
+     enums: String,
+     defaults: true,
+     oneofs: true
+    });
+var protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+var helloworld = protoDescriptor.helloworld;
+
+function doSayHello(call, callback) {
+  callback(null, {
+    message: 'Hello! ' + call.request.name
+  });
+}
+
+function getServer() {
+  var server = new grpc.Server();
+  server.addProtoService(helloworld.Greeter.service, {
+    sayHello: doSayHello,
+  });
+  return server;
+}
+
+if (require.main === module) {
+  var server = getServer();
+  server.bind('0.0.0.0:9090', grpc.ServerCredentials.createInsecure());
+  server.start();
+}
+
+exports.getServer = getServer;
+```
+
+## Configure the Proxy
+
+Next up, we need to configure the Envoy proxy to forward the browser's gRPC-Web
+requests to the backend. Put this in an `envoy.yaml` file. Here we configure
+Envoy to listen at port `:8080`, and forward any gRPC-Web requests to a
+cluster at port `:9090`.
+
+```yaml
+admin:
+  access_log_path: /tmp/admin_access.log
+  address:
+    socket_address: { address: 0.0.0.0, port_value: 9901 }
+
+static_resources:
+  listeners:
+  - name: listener_0
+    address:
+      socket_address: { address: 0.0.0.0, port_value: 8080 }
+    filter_chains:
+    - filters:
+      - name: envoy.http_connection_manager
+        config:
+          codec_type: auto
+          stat_prefix: ingress_http
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: local_service
+              domains: ["*"]
+              routes:
+              - match: { prefix: "/" }
+                route: { cluster: greeter_service }
+              cors:
+                allow_origin:
+                - "*"
+                allow_methods: GET, PUT, DELETE, POST, OPTIONS
+                allow_headers: keep-alive,user-agent,cache-control,content-type,content-transfer-encoding,custom-header-1,x-accept-content-transfer-encoding,x-accept-response-streaming,x-user-agent,x-grpc-web
+                max_age: "1728000"
+                expose_headers: custom-header-1,grpc-status,grpc-message
+                enabled: true
+          http_filters:
+          - name: envoy.grpc_web
+          - name: envoy.cors
+          - name: envoy.router
+  clusters:
+  - name: greeter_service
+    connect_timeout: 0.25s
+    type: logical_dns
+    http2_protocol_options: {}
+    lb_policy: round_robin
+    hosts: [{ socket_address: { address: localhost, port_value: 9090 }}]
+```
+
+To run Envoy (for later), you will need a simple Dockerfile. Put this in a
+`envoy.Dockerfile`.
+
+```dockerfile
+FROM envoyproxy/envoy:latest
+COPY ./envoy.yaml /etc/envoy/envoy.yaml
+CMD /usr/local/bin/envoy -c /etc/envoy/envoy.yaml
+```
+
+## Write Client Code
+
+Now, we are ready to write some client code! Put this in a `client.js` file.
+
+```js
+const {HelloRequest, HelloReply} = require('./helloworld_pb.js');
+const {GreeterClient} = require('./helloworld_grpc_web_pb.js');
+
+var client = new GreeterClient('http://localhost:8080');
+
+var request = new HelloRequest();
+request.setName('World');
+
+client.sayHello(request, {}, (err, response) => {
+  console.log(response.getMessage());
+});
+```
+
+The classes `HelloRequest`, `HelloReply` and `GreeterClient` we import here are
+generated for you by the `protoc` generator utility (which we will cover in the
+next section) from the `helloworld.proto` file we defined earlier.
+
+Then we instantiate a `GreeterClient` instance, set the field in the
+`HelloRequest` protobuf object, and we can make a gRPC call via
+`client.sayHello()`, just like how we defined in the `helloworld.proto` file.
+
+
+You will need a `package.json` file. This is needed for both the `server.js` and
+the `client.js` files.
+
+```json
+{
+  "name": "grpc-web-simple-example",
+  "version": "0.1.0",
+  "description": "gRPC-Web simple example",
+  "devDependencies": {
+    "@grpc/proto-loader": "^0.3.0",
+    "google-protobuf": "^3.6.1",
+    "grpc": "^1.15.0",
+    "grpc-web": "^0.4.0",
+    "webpack": "^4.16.5",
+    "webpack-cli": "^3.1.0"
+  }
+}
+```
+
+And finally a simple `index.html` file.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>gRPC-Web Example</title>
+<script src="./dist/main.js"></script>
+</head>
+<body>
+</body>
+</html>
+```
+
+The `./dist/main.js` file will be generated by `webpack` (which will be covered
+in the next section).
+
+
+And that's it! We have all the code ready. Let's run the example!
+
+## Generate Protobuf Messages and Client Service Stub
+
+To generate the protobuf messages and client service stub class from your
+`.proto` definitions, we need the `protoc` binary and the
+`protoc-gen-grpc-web` plugin. In the meantime, you will need to compile the
+latter yourself. We hope to improve and streamline the process in the near
+future.
+
+```sh
+$ git clone https://github.com/grpc/grpc-web
+$ cd grpc-web
+$ sudo make install-plugin
+```
+
+If you do not already have `protoc` installed, you may have to do this first:
+
+```sh
+$ ./scripts/init_submodules.sh
+$ cd third_party/grpc/third_party/protobuf
+$ ./autogen.sh && ./configure && make -j8
+$ sudo make install
+```
+
+When you have both `protoc` and `protoc-gen-grpc-web` installed, you can now
+run this command:
+
+```sh
+$ protoc -I=. helloworld.proto \
+  --js_out=import_style=commonjs:. \
+  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:.
+```
+
+After the command runs successfully, you should now see two new files generated
+in the current directory:
+
+ - `helloworld_pb.js`: this contains the `HelloRequest` and `HelloReply`
+   classes
+ - `helloworld_grpc_web_pb.js`: this contains the `GreeterClient` class
+
+These are also the 2 files that our `client.js` file imported earlier in the
+example.
+
+## Compile the Client Javascript Code
+
+Next, we need to compile the client side Javascript code into something that
+can be consumed by the browser.
+
+```sh
+$ npm install
+$ npx webpack client.js
+```
+
+Here we use `webpack` and give it an entry point `client.js`. You can also use
+`browserify` or other similar tools. This will resolve all the `require()`
+statements and produce a `./dist/main.js` file that can be embedded in our
+`index.html` file.
+
+## Run the Example!
+
+We are ready to run the Hello World example. The following set of commands will
+run the 3 processes all in the background.
+
+ 1. Run the NodeJS gRPC Service. This listens at port `:9090`.
+
+ ```sh
+ $ node server.js &
+ ```
+
+ 2. Run the Envoy proxy. The `envoy.yaml` file configures Envoy to listen to
+ browser requests at port `:8080`, and forward them to port `:9090` (see
+ above).
+
+ ```sh
+ $ docker build -t helloworld/envoy -f ./envoy.Dockerfile .
+ $ docker run -d -p 8080:8080 --network=host helloworld/envoy
+ ```
+
+ 3. Run the simple Web Server. This hosts the static file `index.html` and
+ `dist/main.js` we generated earlier.
+
+ ```sh
+ $ python -m SimpleHTTPServer 8081 &
+ ```
+
+When these are all ready, you can open a browser tab and navigate to
+
+```
+localhost:8081
+```
+
+Open up the developer console and you should see the following printed out:
+
+```
+Hello! World
+```

net/grpc/gateway/examples/echo/helloworld/client.js

@@ -0,0 +1,30 @@
+/**
+ *
+ * Copyright 2018 Google LLC
+ *
+ * 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
+ *
+ *     https://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.
+ *
+ */
+
+const {HelloRequest, HelloReply} = require('./helloworld_pb.js');
+const {GreeterClient} = require('./helloworld_grpc_web_pb.js');
+
+var client = new GreeterClient('http://' + window.location.hostname + ':8080',
+                               null, null);
+
+var request = new HelloRequest();
+request.setName('World');
+
+client.sayHello(request, {}, (err, response) => {
+  console.log(response.getMessage());
+});

net/grpc/gateway/examples/echo/helloworld/envoy.Dockerfile

@@ -0,0 +1,19 @@
+# Copyright 2018 Google LLC
+#
+# 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
+#
+#     https://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.
+
+FROM envoyproxy/envoy:latest
+
+COPY ./envoy.yaml /etc/envoy/envoy.yaml
+
+CMD /usr/local/bin/envoy -c /etc/envoy/envoy.yaml