retriable request

strategy type

use hook

Before using extension hooks, make sure you are familiar with the basic usage of alova.

A use hook that automatically retries failed requests. Use it for important requests.

Features

• Customize the number of retries, or decide whether to retry based on a condition;
• Retry delay mechanism;
• Manually stop retrying;

Usage

Basic usage

import { useRetriableRequest } from 'alova/client';

const {
  // Loading status, always true during retry, until retry succeeds or fails
  loading,

  // response data
  data,

  // Request error information, every time a request or retry fails, there will be an error instance
  // The last error instance will be overwritten
  error,

  // Every time a request or retry fails, the onError event will be triggered
  onError,

  // Request retry event, triggered immediately after each retry request is issued
  onRetry,

  // request retry failure event
  // The request is not successful after reaching the maximum number of retries, or manually stopping retries will trigger
  onFail,

  // request or retry success event
  onSuccess,

  // Every request or retry, regardless of success or failure, will trigger the completion event
  onComplete
} = useRetriableRequest(request);

The maximum number of request retries for useRetriableRequest defaults to 3, and each retry is delayed by 1 second. It also sends a request by default; you can change this by setting immediate to false.

Set the static maximum number of retries

The maximum number of retries indicates the maximum number of times to retry the request after the first request fails. During this period, if the request succeeds, it will stop continuing to retry. The default maximum number of retries is 3, and you can customize the settings in the following ways.

When the request reaches the maximum number of retries and still fails, the onFail event is triggered and retrying stops. If you want to keep retrying after a failure, call the send function to start a new round of retries.

const { send } = useRetriableRequest(request, {
  //...
  // Set the maximum number of retries to 5
  retry: 5
});

Dynamically set the maximum number of retries

Sometimes you may want to use a condition to decide whether to keep retrying. In that case, set retry to a function that returns a boolean value to decide dynamically whether to continue retrying.

useRetriableRequest(request, {
  //...
  // The first parameter is the last error instance, and the parameters passed in from the second parameter to send
  retry(error, ...args) {
    // If the request times out, continue to retry
    return /network timeout/i.test(error.message);
  }
});

Set delay time

The default retry delay time is 1 second, you can customize the setting in the following ways.

useRetriableRequest(request, {
  //...
  backoff: {
    // Set the delay time to 2 seconds
    delay: 2000
  }
});

Set an unfixed retry delay time

Sometimes you may want each retry's delay to vary. You can set a delay multiplier so the delay grows exponentially with the number of retries.

useRetriableRequest(request, {
  //...
  backoff: {
    delay: 2000,
    // When the multiplier is set to 2, the first retry delay is 2 seconds, the second is 4 seconds, the third is 8 seconds, and so on.
    multiplier: 2
  }
});

You can even add a random jitter to each delay to make it less predictable.

useRetriableRequest(request, {
   //...
   backoff: {
     delay: 2000,
     multiplier: 2,
     /**
      * The initial jitter percentage value of the delay request, the range is 0-1
      * When only startQuiver is set, endQuiver defaults to 1
      * For example set to 0.5, it will add 50% to 100% random time on the current delay time
      * If endQuiver has a value, the delay time will be increased by a random value in the range of startQuiver and endQuiver
      */
     startQuiver: 0.5,

     /**
      * The jitter end percentage value of the delayed request, the range is 0-1
      * When only endQuiver is set, startQuiver defaults to 0
      * For example set to 0.8, it will add a random time from 0% to 80% on the current delay time
      * If startQuiver has a value, the delay time will increase the random value in the range of startQuiver and endQuiver
      */
     endQuiver: 0.8;
   }
});

Manually stop retrying

In some cases, you need to manually stop the retry, whether you are currently requesting or waiting for the next retry, you can use stop to stop it.

const { stop } = useRetriableRequest(request, {
  //...
});

const handleStop = () => {
  stop();
};

API

Hook configuration

Inherit all configurations from useRequest.

| Name | Description | Type | Default | Version | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------- | ------- | --- | | retry | The maximum number of retries can also be set as a function returning a boolean value to dynamically determine whether to continue to retry. | number | (error: Error, ...args: any[]) => boolean | 3 | - | | backoff | Backoff policy, set retry delay time, etc. | BackoffPolicy | - | - |

BackoffPolicy

Name	Description	Type	Default	Version
delay	Delay time for another request, in milliseconds	number	1000	-
multiplier	Specify the delay multiplier, for example, when multiplier is set to 2 and delay is 1 second, the first retry is 1 second, the second is 2 seconds, the third is 4 seconds, and so on	number	1	-
startQuiver	The initial jitter percentage value of the delay request, ranging from 0-1. When only startQuiver is set, endQuiver defaults to 1. For example, if it is set to 0.5, it will increase the current delay time by 50% to 100% randomly; if endQuiver has a value, the delay time will be increased by a random value in the range of startQuiver and endQuiver	number	0	-
endQuiver	The jitter end percentage value of the delayed request, the range is 0-1; when only endQuiver is set, startQuiver defaults to 0. For example, if it is set to 0.5, it will add a random time from 0% to 50% to the current delay time. If startQuiver has a value, the delay time will increase the random value in the range of startQuiver and endQuiver	number	0	-

Responsive data

Inherit all responsive data from useRequest.

Action function

Inherit all action functions of useRequest.

name	description	function parameters	return value	version
stop	Stop retrying, it is only valid during retrying, and the onFail event will be triggered immediately after stopping	-	-	-

Event

Inherit all events from useRequest.

Name	Description	Callback Parameters	Version
onRetry	Retry event bindings, they will fire after a retry is initiated	Retry event instance RetriableRetryEvent	-
onFail	Triggered when the request fails. It will be triggered when no more retries are made. For example, when the maximum number of retries is reached, when the retry callback returns false, manually call stop to stop retrying Note: 1. The onError event will be triggered every time an error is reported. 2. If there are no retries, onError, onComplete and onFail will be triggered at the same time	Retry event instance RetriableFailEvent	-

RetriableRetryEvent

Event event instance inherited from alova.

Name	Description	Type	Default	Version
retryTimes	current retry times	number	required	-
retryDelay	The delay time of this retry, in ms	number	required	-

RetriableFailEvent

Event event instance inherited from alova.

Name	Description	Type	Default	Version
retryTimes	current retry times	number	required	-