@ydbjs/retry

The @ydbjs/retry package provides utilities for implementing retry logic in your applications. It is designed to work seamlessly with YDB services, allowing you to handle transient errors and ensure reliable operations.

Features

• Configurable retry policies
• Support for custom retry strategies
• Budget management for retry attempts
• Predicate functions to determine retryability
• TypeScript support with type definitions
• Lightweight and easy to integrate

Installation

To install the package, use your preferred package manager:

npm install @ydbjs/[email protected]

Usage

Basic Example

Here is an example of how to use the @ydbjs/retry package to implement retry logic:

import { retry, defaultRetryConfig } from '@ydbjs/retry'

async function fetchData() {
  return await retry(defaultRetryConfig, async () => {
    // Your operation that might fail
    const response = await fetch('https://example.com/api')
    if (!response.ok) {
      throw new Error('Failed to fetch data')
    }
    return response.json()
  })
}

fetchData()
  .then((data) => {
    console.log('Data fetched successfully:', data)
  })
  .catch((error) => {
    console.error('Failed to fetch data:', error)
  })

Configuration Options

The retry function accepts the following configuration options:

import type { RetryConfig } from '@ydbjs/retry';

const options: RetryConfig = {
    /** Predicate to determine if an error is retryable */
    retry?: boolean | ((error: RetryContext['error'], idempotent: boolean) => boolean),
    /** Budget for retry attempts */
    budget?: number | RetryBudget,
    /** Strategy to calculate delay */
    strategy?: number | RetryStrategy,
    /** Idempotent operation */
    idempotent?: boolean,
    /** Hook to be called before retrying */
    onRetry?: (ctx: RetryContext) => void,
    /** Optional AbortSignal (from Abortable) */
    signal?: AbortSignal,
};

• retry (boolean | (error, idempotent) => boolean): Predicate to determine if an error is retryable. Receives both the error and the idempotent flag.
• budget (number | RetryBudget): The budget for retry attempts. Can be a fixed number or a custom function.
• strategy (number | RetryStrategy): Strategy to calculate delay between retries. Can be a fixed number or a custom function.
• idempotent (boolean): Indicates if the operation is idempotent.
• onRetry ((ctx) => void): Hook called before each retry attempt.
• signal (AbortSignal): Optional signal to support cancellation.

Advanced Usage

Custom Retry Strategy

You can define your own retry strategy to control the delay between attempts:

import { retry } from '@ydbjs/retry'

const customStrategy = (ctx, cfg) => {
  // Exponential backoff with a cap
  return Math.min(1000 * 2 ** ctx.attempt, 10000)
}

await retry(
  {
    strategy: customStrategy,
    budget: 5,
    retry: (error) => error instanceof Error,
  },
  async () => {
    // Your operation
  }
)

Dynamic Retry Budget

Budgets can be dynamic, based on error type or context:

const dynamicBudget = (ctx, cfg) => {
  // Allow more attempts for network errors
  if (ctx.error && ctx.error.message.includes('network')) {
    return 10
  }
  return 3
}

await retry(
  {
    budget: dynamicBudget,
    // ...other config
  },
  async () => {
    /* ... */
  }
)

onRetry Hook

You can use the onRetry hook to log or perform side effects on each retry:

await retry(
  {
    onRetry: (ctx) => {
      console.log(`Retry attempt #${ctx.attempt} after error:`, ctx.error)
    },
    // ...other config
  },
  async () => {
    /* ... */
  }
)

Combining Strategies

You can compose multiple strategies for more advanced control:

import { strategies, retry } from '@ydbjs/retry'

const combined = strategies.compose(strategies.exponential(500), strategies.jitter(100))

await retry(
  {
    strategy: combined,
    budget: 5,
  },
  async () => {
    /* ... */
  }
)

Using AbortSignal in Retry Callback

You can use the AbortSignal provided to the retried function to support cancellation with custom clients (for example, a YDB driver from the core package):

import { retry } from '@ydbjs/retry'
import { Driver } from '@ydbjs/core'

const driver = new Driver('grpc://localhost:2135?database=/local')

await retry(
  {
    budget: 5,
  },
  async (signal) => {
    // Pass the signal to a method that supports AbortSignal, e.g., driver.ready
    await driver.ready(signal)
    // Or, if using a generated client:
    // const client = driver.createClient(SomeServiceDefinition);
    // return await client.someMethod(request, { signal });
  }
)

Observability via node:diagnostics_channel

@ydbjs/retry publishes events to node:diagnostics_channel so external subscribers (@ydbjs/telemetry, OpenTelemetry, custom loggers) can build traces and metrics for retry behaviour without the caller knowing anything about them.

Every code path that uses retry() — driver discovery, query execution, transactions, auth token refresh — inherits these channels automatically.

Channels

| Channel | Type | Payload | | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tracing:ydb:retry.run | tracing | { idempotent: boolean, outcome?: RetryOutcome } — whole retry loop. outcome is set on the ctx before resolve / throw. | | tracing:ydb:retry.attempt | tracing | { attempt: number, idempotent: boolean, backoffMs: number } — a single attempt (including the first); backoffMs is the wait actually observed before this attempt (0 for attempt === 1) | | ydb:retry.attempt.completed | publish | { attempt: number, idempotent: boolean, outcome: RetryOutcome } — emitted once per attempt with its outcome | | ydb:retry.exhausted | publish | { attempts: number, totalDuration: number, lastError: unknown } — ms. See below. |

type RetryOutcome = 'success' | 'retried' | 'non_retryable' | 'exhausted'

retry.attempt is published once per attempt starting from attempt: 1. Because tracingChannel.tracePromise wraps every attempt, tracing:ydb:retry.attempt.error fires for every failed attempt — both the ones that will be retried and the final one that exits the loop. The final attempt's failure additionally surfaces on tracing:ydb:retry.run.error.

ydb:retry.attempt.completed is the metrics-friendly companion: it fires exactly once per attempt regardless of success or failure, with an outcome tag suited for a Counter. Use it instead of subscribing to both attempt.asyncEnd and attempt.error when all you want is a count.

ydb:retry.exhausted fires when the retry policy itself gives up — either the budget ran out or the predicate returned false. It does not fire when the loop exits via AbortError or TimeoutError: those are rethrown immediately as caller-driven cancellations. Subscribers tracking "retry budget exhausted" should not expect this event for cancellations or timeouts; use tracing:ydb:retry.run.error for the broader "retry loop failed" signal.

For end-to-end retry duration with outcome dimensions, read outcome off the retry.run ctx on asyncEnd / error:

tracingChannel('tracing:ydb:retry.run').subscribe({
  asyncEnd(ctx) {
    histogram.record(elapsed, { outcome: ctx.outcome })
  },
  error(ctx) {
    histogram.record(elapsed, { outcome: ctx.outcome })
  },
})

Subscribing

import { channel, tracingChannel } from 'node:diagnostics_channel'

tracingChannel('tracing:ydb:retry.run').subscribe({
  start(ctx) {
    // ctx.idempotent
  },
  asyncEnd() {
    /* success */
  },
  error(ctx) {
    /* ctx.error is the final failure */
  },
})

channel('ydb:retry.exhausted').subscribe((msg) => {
  alert.budgetExhausted.add(1, { attempts: msg.attempts })
})

⚠️ Subscribers must be safe

node:diagnostics_channel invokes subscribers synchronously. Any exception thrown inside a subscriber propagates up the call stack and will disrupt the SDK — a buggy retry subscriber can break the very operation it observes. @ydbjs/retry does not wrap subscribers; wrap them yourself:

tracingChannel('tracing:ydb:retry.attempt').subscribe({
  start(ctx) {
    try {
      span.startChild({ name: 'retry.attempt', attributes: { attempt: ctx.attempt } })
    } catch (err) {
      console.error('telemetry subscriber failed', err)
    }
  },
})

Stability

Channel names and payload field names follow semantic versioning. Adding new optional fields is a minor change; renaming or removing fields is a major change. Treat the channel surface as a public API.

Development

To build the package:

npm run build

To run tests:

npm test

License

This project is licensed under the Apache 2.0 License.

Links

• YDB Documentation
• GitHub Repository
• Issues