Merge pull request #2894 from murgatroid99/retry_example

Add retry example

Author: murgatroid99

examples/retry/README.md

@@ -0,0 +1,57 @@
+# Retry
+
+This example shows how to enable and configure retry on gRPC clients.
+
+## Documentation
+
+[gRFC for client-side retry support](https://github.com/grpc/proposal/blob/master/A6-client-retries.md)
+
+## Try it
+
+This example includes a service implementation that fails requests three times with status code Unavailable, then passes the fourth. The client is configured to make four retry attempts when receiving an Unavailable status code.
+
+First start the server:
+
+```
+node server.js
+```
+
+Then run the client:
+
+```
+node client.js
+```
+
+## Usage
+
+### Define your retry policy
+
+Retry is configured via the service config, which can be provided by the name resolver, or as a channel option (described below). In the below example, we set the retry policy for the "grpc.example.echo.Echo" method.
+
+```js
+const serviceConfig = {
+  loadBalancingConfig: [],
+  methodConfig: [
+    {
+      name: [
+        {
+          service: 'grpc.examples.echo.Echo',
+        },
+      ],
+      retryPolicy: {
+        maxAttempts: 4,
+        initialBackoff: '0.01s',
+        maxBackoff: '0.01s',
+        backoffMultiplier: 1.0,
+        retryableStatusCodes: ['UNAVAILABLE'],
+      },
+    },
+  ],
+};
+```
+
+### Providing the retry policy as a channel option
+
+```js
+const client = new Echo('localhost:50052', grpc.credentials.createInsecure(), { 'grpc.service_config': JSON.stringify(serviceConfig) });
+```

examples/retry/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 parseArgs = require('minimist');
+
+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 serviceConfig = {
+  loadBalancingConfig: [],
+  methodConfig: [
+    {
+      name: [
+        {
+          service: 'grpc.examples.echo.Echo',
+        },
+      ],
+      retryPolicy: {
+        maxAttempts: 4,
+        initialBackoff: '0.01s',
+        maxBackoff: '0.01s',
+        backoffMultiplier: 1.0,
+        retryableStatusCodes: ['UNAVAILABLE'],
+      },
+    },
+  ],
+};
+
+function main() {
+  let argv = parseArgs(process.argv.slice(2), {
+    string: 'target',
+    default: {target: 'localhost:50052'}
+  });
+
+	// Set up a connection to the server with service config and create the channel.
+	// However, the recommended approach is to fetch the retry configuration
+	// (which is part of the service config) from the name resolver rather than
+	// defining it on the client side.
+  const client = new echoProto.Echo('localhost:50052', grpc.credentials.createInsecure(), { 'grpc.service_config': JSON.stringify(serviceConfig) });
+  client.unaryEcho({message: 'Try and Success'}, (error, value) => {
+    if (error) {
+      console.log(`Unexpected error from UnaryEcho: ${error}`);
+      return;
+    }
+    console.log(`RPC response: ${JSON.stringify(value)}`);
+  });
+}
+
+main();

examples/retry/server.js

@@ -0,0 +1,73 @@
+/*
+ *
+ * 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');
+
+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 SUCCEED_EVERY = 4
+let callCount = 0;
+
+/* This method will succeed every SUCCEED_EVERY calls, and fail all others with status code
+ * UNAVAILABLE. */
+function unaryEcho(call, callback) {
+  callCount++;
+  if (callCount % SUCCEED_EVERY === 0) {
+    console.log(`Request succeeded count: ${callCount}`);
+    callback(null, call.request);
+  } else {
+    console.log(`Request failed count: ${callCount}`);
+    callback({
+      code: grpc.status.UNAVAILABLE,
+      details: 'Request failed by policy'
+    });
+  }
+}
+
+const serviceImplementation = {
+  unaryEcho
+};
+
+function main() {
+  const argv = parseArgs(process.argv.slice(2), {
+    string: 'port',
+    default: {port: '50052'}
+  });
+  const server = new grpc.Server();
+  server.addService(echoProto.Echo.service, serviceImplementation);
+  server.bindAsync(`0.0.0.0:${argv.port}`, grpc.ServerCredentials.createInsecure(), (err, port) => {
+    if (err != null) {
+      return console.error(err);
+    }
+    console.log(`gRPC listening on ${port}`)
+  });
+}
+
+main();