From b1fd52d56685a8bc48a43f2c3a159eb19a533387 Mon Sep 17 00:00:00 2001 From: Michael Lumish Date: Wed, 29 Jan 2025 12:40:24 -0800 Subject: [PATCH] Add retry example --- examples/retry/README.md | 57 ++++++++++++++++++++++++++++++ examples/retry/client.js | 75 ++++++++++++++++++++++++++++++++++++++++ examples/retry/server.js | 73 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 205 insertions(+) create mode 100644 examples/retry/README.md create mode 100644 examples/retry/client.js create mode 100644 examples/retry/server.js diff --git a/examples/retry/README.md b/examples/retry/README.md new file mode 100644 index 000000000..9109a5e56 --- /dev/null +++ b/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) }); +``` diff --git a/examples/retry/client.js b/examples/retry/client.js new file mode 100644 index 000000000..4eed54d73 --- /dev/null +++ b/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(); diff --git a/examples/retry/server.js b/examples/retry/server.js new file mode 100644 index 000000000..a58f72c40 --- /dev/null +++ b/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();