nice-grpc-client-middleware-retry

nice-grpc-client-middleware-retry

Client middleware for nice-grpc that adds automatic retries to unary calls. Exponential backoff is added between retry attempts.

• Installation
• Idempotency
• Usage
  • Infinite retries
  • Deadlines
  • Client configuration

Installation

npm install nice-grpc-client-middleware-retry

Idempotency

It is generally not safe to retry calls in case of errors, because the failed call might have reached the server and had an effect on the system. For example, an increment operation is not idempotent, since executing it twice will increment by 2. In contrast, a delete operation can be made idempotent, if the server ignores the delete of an already non-existent entity. Any read-only operation is inherently idempotent.

In this middleware, the retries are disabled by default, unless the method is marked as idempotent:

service ExampleService {
  rpc ExampleMethod(ExampleMethodRequest) returns (ExampleMethodResponse) {
    option idempotency_level = IDEMPOTENT;
  }
}

or read-only:

service ExampleService {
  rpc ExampleMethod(ExampleMethodRequest) returns (ExampleMethodResponse) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}

Note that method options currently work only when compiling with ts-proto.

Usage

import {
  createClientFactory,
  createChannel,
  ClientError,
  Status,
} from 'nice-grpc';
import {retryMiddleware} from 'nice-grpc-client-middleware-retry';

const clientFactory = createClientFactory().use(retryMiddleware);

const channel = createChannel(address);
const client = clientFactory.create(ExampleService, channel);

const response = await client.exampleMethod(request, {
  // not needed if the method is marked as idempotent in Protobuf
  retry: true,
  // defaults to 1
  retryMaxAttempts: 5,
  // defaults to [UNKNOWN, INTERNAL, UNAVAILABLE, CANCELLED]
  retryableStatuses: [Status.UNAVAILABLE],
  onRetryableError(error: ClientError, attempt: number, delayMs: number) {
    logger.error(error, `Call failed (${attempt}), retrying in ${delayMs}ms`);
  },
});

Infinite retries

You can also set retryMaxAttempts to Infinity and use AbortSignal to cancel the retried call:

const abortController = new AbortController();

setTimeout(() => {
  abortController.abort();
}, 1000);

const response = await client.exampleMethod(request, {
  retry: true,
  retryMaxAttempts: Infinity,
  signal: abortController.signal,
});

Deadlines

When using this middleware together with deadline middleware, make sure to have them in correct order. This way, if the retry is currently in a backoff delay, it will be correctly aborted upon deadline:

const clientFactory = createClientFactory()
  .use(retryMiddleware)
  .use(deadlineMiddleware);

Client configuration

Instead of specifying retry options per call, you can configure retries when creating the client:

const clientFactory = createClientFactory().use(retryMiddleware);

const channel = createChannel(address);
const client = clientFactory.create(ExampleService, channel, {
  // set defaults for all methods
  '*': {
    retryMaxAttempts: 5,
  },
  // enable retries for particular method
  exampleMethod: {
    retry: true,
  },
});