nice-grpc-client-middleware-retry is a client-side middleware for the `nice-grpc` TypeScript gRPC library, enabling automatic retries for unary gRPC calls. It integrates seamlessly with the `nice-grpc` client factory to add robust fault tolerance with features like exponential backoff. The current stable version is 3.1.14, and the `nice-grpc` ecosystem, which this package is part of, maintains an active and frequent release cadence, often with updates every few weeks for core packages. A key differentiator is its strong TypeScript support and modern API leveraging Promises and Async Iterables, providing a more ergonomic experience compared to traditional gRPC implementations. It also emphasizes the importance of idempotency, requiring explicit configuration for retries on non-idempotent operations to prevent unintended side effects.
npm install nice-grpc-client-middleware-retryVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to apply the `retryMiddleware` to a `nice-grpc` client, configure retry parameters like max attempts and retryable statuses, and handle potential errors. It also illustrates the `onRetry` callback for logging retry attempts and highlights the configuration options for exponential backoff.
For non-idempotent operations, carefully evaluate the risks before enabling retries. If retries are necessary, ensure your server-side logic can handle duplicate requests safely (e.g., by using idempotency keys). Explicitly set `retry: true` in the call options only when appropriate.
Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`). Use `import` statements exclusively. If using TypeScript, set `"module": "Node16"` or `"ES2022"` and `"moduleResolution": "Node16"` or `"Bundler"` in `tsconfig.json`.
Only include truly transient error statuses (e.g., `UNAVAILABLE`, `INTERNAL`, `UNKNOWN` (if appropriate for transient server errors), `DEADLINE_EXCEEDED`) in `retryableStatuses`. Avoid retrying on deterministic application-level errors.
Always set a reasonable `retryMaxAttempts` and configure exponential backoff (`retryDelay`, `retryDelayMax`, `retryDelayMultiplier`) with jitter to prevent retries from overwhelming the server. Consider implementing circuit breakers or timeouts for more advanced resilience patterns.
Update your import statement to `import { retryMiddleware } from 'nice-grpc-client-middleware-retry';` and ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`).Increase the `callTimeout` in your gRPC call options or ensure that server processing times are within acceptable limits. Verify that `AbortSignal`s are not prematurely aborting the call. If retries are configured, ensure the total time for retries does not exceed an overarching call timeout.
Ensure `nice-grpc` (and its types, which it ships) is correctly installed: `npm install nice-grpc`. Check `tsconfig.json` for `"moduleResolution": "Node16"` or `"Bundler"` and `"module": "Node16"` or `"ESNext"` to correctly resolve ES Modules.