Sync fork

.github/workflows/grpc-tools-build.yml

@@ -8,9 +8,9 @@ on:
     branches:
       - master
 
-permissions:
+permissions:
   contents: read #  to fetch code (actions/checkout)
-
+
 jobs:
   linux_build:
     name: Linux grpc-tools Build
@@ -23,7 +23,7 @@ jobs:
         run: |
           docker build -t kokoro-native-image tools/release/native
           docker run -v /var/run/docker.sock:/var/run/docker.sock -v $GITHUB_WORKSPACE:$GITHUB_WORKSPACE kokoro-native-image $GITHUB_WORKSPACE/packages/grpc-tools/build_binaries.sh
-      - uses: actions/upload-artifact@v2
+      - uses: actions/upload-artifact@v4
         with:
           name: grpc-tools_linux
           path: artifacts/
@@ -36,7 +36,7 @@ jobs:
           submodules: recursive
       - name: Build
         run: packages/grpc-tools/build_binaries.sh
-      - uses: actions/upload-artifact@v2
+      - uses: actions/upload-artifact@v4
         with:
           name: grpc-tools_macos
           path: artifacts/
@@ -55,7 +55,7 @@ jobs:
       - name: Build
         run: powershell -File ./packages/grpc-tools/build_binaries.ps1
         shell: cmd
-      - uses: actions/upload-artifact@v1
+      - uses: actions/upload-artifact@v4
         with:
           name: grpc-tools_windows_${{matrix.arch}}
           path: artifacts/
@@ -64,12 +64,12 @@ jobs:
     runs-on: ubuntu-latest
     needs: [linux_build, macos_build, windows_build]
     steps:
-      - uses: actions/download-artifact@v2
+      - uses: actions/download-artifact@v4
       - name: Copy
         run: |
           mkdir artifacts
           cp -r ./**/* artifacts/
-      - uses: actions/upload-artifact@v2
+      - uses: actions/upload-artifact@v4
         with:
           name: combined-artifacts
           path: artifacts/

README.md

@@ -1,4 +1,3 @@
-[![Build Status](https://travis-ci.org/grpc/grpc-node.svg?branch=master)](https://travis-ci.org/grpc/grpc-node)
 # gRPC on Node.js
 
 ## Implementations

doc/environment_variables.md

@@ -11,8 +11,10 @@ can be set.
   checked in order, and the first one that has a value is used.
 
 * no_grpc_proxy, no_proxy
-  A comma separated list of hostnames to connect to without using a proxy even
-  if a proxy is set. These variables are checked in order, and the first one
+  A comma separated list of hostnames, IP addresses,
+  or CIDR blocks to connect to without using a proxy even
+  if a proxy is set, for example: no_proxy=example.com,192.168.0.1,192.168.0.0/16.
+  These variables are checked in order, and the first one
   that has a value is used.
 
 * GRPC_SSL_CIPHER_SUITES
@@ -66,4 +68,4 @@ can be set.
 * GRPC_NODE_USE_ALTERNATIVE_RESOLVER
   Allows changing dns resolve behavior and parse DNS server authority as described in https://github.com/grpc/grpc/blob/master/doc/naming.md
   - true - use alternative resolver
-  - false - use default resolver (default)
+  - false - use default resolver (default)

examples/debugging/README.md

@@ -0,0 +1,27 @@
+# Debugging
+
+Currently, grpc provides two major tools to help user debug issues, which are logging and channelz.
+
+## Logs
+
+gRPC has put substantial logging instruments on critical paths of gRPC to help users debug issues. The [Environment Variables](https://github.com/grpc/grpc-node/blob/master/doc/environment_variables.md) doc describes the environment variables that control debug logging.
+
+To enable full debug logging, run the code with the following environment variables: `GRPC_TRACE=all GRPC_VERBOSITY=DEBUG`.
+
+## Channelz
+
+We also provide a runtime debugging tool, Channelz, to help users with live debugging.
+
+See the channelz blog post here ([link](https://grpc.io/blog/a-short-introduction-to-channelz/)) for details about how to use channelz service to debug live program.
+
+## Try it
+
+The example is able to showcase how logging and channelz can help with debugging. See the channelz blog post linked above for full explanation.
+
+```
+node server.js
+```
+
+```
+node client.js
+```

examples/debugging/client.js

@@ -0,0 +1,97 @@
+/*
+ *
+ * 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 parseArgs = require('minimist');
+
+var PROTO_PATH = __dirname + '/../protos/helloworld.proto';
+
+const packageDefinition = protoLoader.loadSync(
+  PROTO_PATH,
+  {keepCase: true,
+   longs: String,
+   enums: String,
+   defaults: true,
+   oneofs: true
+  });
+var helloProto = grpc.loadPackageDefinition(packageDefinition).helloworld;
+
+function serverBindPort(server, port) {
+  return new Promise((resolve, reject) => {
+    server.bindAsync(port, grpc.ServerCredentials.createInsecure(), (error, port) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(port);
+      }
+    })
+  });
+}
+
+const addressString = 'ipv4:///127.0.0.1:10001,127.0.0.1:10002,127.0.0.1:10003';
+
+function callSayHello(client, name) {
+  return new Promise((resolve, reject) => {
+    const deadline = new Date();
+    deadline.setMilliseconds(deadline.getMilliseconds() + 150);
+    client.sayHello({name}, {deadline}, (error, response) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(response);
+      }
+    });
+  });
+}
+
+async function main() {
+  const argv = parseArgs(process.argv.slice(2), {
+    string: ['addr', 'name'],
+    default: {addr: 'localhost:50051', name: 'world'}
+  });
+
+  // Set up the server serving channelz service.
+  const channelzServer = new grpc.Server();
+  grpc.addAdminServicesToServer(channelzServer);
+  await serverBindPort(channelzServer, argv.addr);
+
+  const roundRobinServiceConfig = {
+    methodConfig: [],
+    loadBalancingConfig: [{ round_robin: {} }]
+  };
+  const client = new helloProto.Greeter(addressString, grpc.credentials.createInsecure(), {'grpc.service_config': JSON.stringify(roundRobinServiceConfig)});
+
+  // Contact the server and print out its response
+
+  // Make 100 SayHello RPCs
+  for (let i = 0; i < 100; i++) {
+    try {
+      const response = await callSayHello(client, argv.name);
+      console.log(`Greeting: ${response.message}`);
+    } catch (e) {
+      console.log(`could not greet: ${e.message}`);
+    }
+  }
+
+  // Unless you exit the program (e.g. CTRL+C), channelz data will be available for querying.
+	// Users can take time to examine and learn about the info provided by channelz.
+  setInterval(() => {}, 10000);
+}
+
+main();

examples/debugging/server.js

@@ -0,0 +1,79 @@
+/*
+ *
+ * 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');
+
+var PROTO_PATH = __dirname + '/../protos/helloworld.proto';
+
+const packageDefinition = protoLoader.loadSync(
+  PROTO_PATH,
+  {keepCase: true,
+   longs: String,
+   enums: String,
+   defaults: true,
+   oneofs: true
+  });
+var helloProto = grpc.loadPackageDefinition(packageDefinition).helloworld;
+
+const greeterImplementation = {
+  sayHello: (call, callback) => {
+    callback(null, { message: `Hello ${call.request.name}`});
+  }
+};
+
+const slowGreeterImplementation = {
+  sayHello: (call, callback) => {
+    const waitTimeMs = 100 + (Math.random() * 100)|0;
+    setTimeout(() => {
+      callback(null, { message: `Hello ${call.request.name}`});
+    }, waitTimeMs);
+  }
+}
+
+function serverBindPort(server, port) {
+  return new Promise((resolve, reject) => {
+    server.bindAsync(`0.0.0.0:${port}`, grpc.ServerCredentials.createInsecure(), (error, port) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(port);
+      }
+    })
+  });
+}
+
+async function main() {
+  const channelzServer = new grpc.Server();
+  grpc.addAdminServicesToServer(channelzServer);
+  await serverBindPort(channelzServer, 50052);
+
+  const server1 = new grpc.Server();
+  server1.addService(helloProto.Greeter.service, greeterImplementation);
+  await serverBindPort(server1, 10001);
+
+  const server2 = new grpc.Server();
+  server2.addService(helloProto.Greeter.service, greeterImplementation);
+  await serverBindPort(server2, 10002);
+
+  const server3 = new grpc.Server();
+  server3.addService(helloProto.Greeter.service, slowGreeterImplementation);
+  await serverBindPort(server3, 10003);
+}
+
+main();

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.