Merge pull request #2966 from murgatroid99/load_balancing_example

Add load balancing example

Author: murgatroid99

examples/load_balancing/README.md

@@ -0,0 +1,57 @@
+# Load balancing
+
+This examples shows how `Client` can pick different load balancing policies.
+
+## Try it
+
+```
+node server.js
+```
+
+```
+node client.js
+```
+
+## Explanation
+
+Two echo servers are serving on "0.0.0.0:50051" and "0.0.0.0:50052". They will include their serving address in the response. So the server on "0.0.0.0:50051" will reply to the RPC with this is examples/load_balancing (from 0.0.0.0:50051).
+
+Two clients are created, to connect to both of these servers. Each client picks a different load balancer (using the `grpc.service_config` option): `pick_first` or `round_robin`.
+
+Note that balancers can also be switched using service config, which allows service owners (instead of client owners) to pick the balancer to use. Service config doc is available at https://github.com/grpc/grpc/blob/master/doc/service_config.md.
+
+### pick_first
+
+The first client is configured to use `pick_first`. `pick_first` tries to connect to the first address, uses it for all RPCs if it connects, or try the next address if it fails (and keep doing that until one connection is successful). Because of this, all the RPCs will be sent to the same backend. The responses received all show the same backend address.
+
+```
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+```
+
+### round_robin
+
+The second client is configured to use `round_robin`. `round_robin` connects to all the addresses it sees, and sends an RPC to each backend one at a time in order. E.g. the first RPC will be sent to backend-1, the second RPC will be sent to backend-2, and the third RPC will be sent to backend-1 again.
+
+```
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50052)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50052)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50052)
+this is examples/load_balancing (from 0.0.0.0:50051)
+this is examples/load_balancing (from 0.0.0.0:50052)
+this is examples/load_balancing (from 0.0.0.0:50051)
+```
+
+Note that it's possible to see two consecutive RPC sent to the same backend. That's because `round_robin` only picks the connections ready for RPCs. So if one of the two connections is not ready for some reason, all RPCs will be sent to the ready connection.

examples/load_balancing/client.js

@@ -0,0 +1,75 @@
+/*
+ *
+ * Copyright 2025 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.
+ *
+ */
+
+const grpc = require('@grpc/grpc-js');
+const protoLoader = require('@grpc/proto-loader');
+
+const PROTO_PATH = __dirname + '/../protos/echo.proto';
+
+const packageDefinition = protoLoader.loadSync(
+  PROTO_PATH,
+  {keepCase: true,
+   longs: String,
+   enums: String,
+   defaults: true,
+   oneofs: true
+  });
+const echoProto = grpc.loadPackageDefinition(packageDefinition).grpc.examples.echo;
+
+const addressString = 'ipv4:///127.0.0.1:50051,127.0.0.1:50052';
+
+function callUnaryEcho(client, message) {
+  return new Promise((resolve, reject) => {
+    const deadline = new Date();
+    deadline.setSeconds(deadline.getSeconds() + 1);
+    client.unaryEcho({message}, {deadline}, (error, response) => {
+      if (error) {
+        reject(error);
+      } else {
+        console.log(response.message);
+        resolve(response);
+      }
+    });
+  });
+}
+
+async function makeRPCs(client, count) {
+  for (let i = 0; i < count; i++) {
+    await callUnaryEcho(client, "this is examples/load_balancing");
+  }
+}
+
+async function main() {
+  // "pick_first" is the default, so there's no need to set the load balancing policy.
+  const pickFirstClient = new echoProto.Echo(addressString, grpc.credentials.createInsecure());
+  console.log("--- calling helloworld.Greeter/SayHello with pick_first ---");
+  await makeRPCs(pickFirstClient, 10);
+  console.log();
+
+  const roundRobinServiceConfig = {
+    methodConfig: [],
+    loadBalancingConfig: [{ round_robin: {} }]
+  };
+  const roundRobinClient = new echoProto.Echo(addressString, grpc.credentials.createInsecure(), {'grpc.service_config': JSON.stringify(roundRobinServiceConfig)});
+  console.log("--- calling helloworld.Greeter/SayHello with round_robin ---");
+  await makeRPCs(roundRobinClient, 10);
+  pickFirstClient.close();
+  roundRobinClient.close();
+}
+
+main();

examples/load_balancing/server.js

@@ -0,0 +1,60 @@
+/*
+ *
+ * Copyright 2025 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.
+ *
+ */
+
+const grpc = require('@grpc/grpc-js');
+const protoLoader = require('@grpc/proto-loader');
+
+const PROTO_PATH = __dirname + '/../protos/echo.proto';
+
+const packageDefinition = protoLoader.loadSync(
+  PROTO_PATH,
+  {keepCase: true,
+   longs: String,
+   enums: String,
+   defaults: true,
+   oneofs: true
+  });
+const echoProto = grpc.loadPackageDefinition(packageDefinition).grpc.examples.echo;
+
+function startServer(address) {
+  return new Promise((resolve, reject) => {
+    const server = new grpc.Server();
+    server.addService(echoProto.Echo.service, {
+      unaryEcho: (call, callback) => {
+        callback(null, {message: `${call.request.message} (from ${address})`});
+      }
+    });
+    server.bindAsync(address, grpc.ServerCredentials.createInsecure(), (error, port) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(server);
+      }
+    });
+  });
+}
+
+const addresses = ['0.0.0.0:50051', '0.0.0.0:50052'];
+
+async function main() {
+  for (const address of addresses) {
+    await startServer(address)
+  }
+}
+
+main();