Customizing HTTP Request Retries

When working with HTTP requests, there are times when a request might fail due to network issues, server errors, or other unforeseen circumstances.

The retryHttpRequestConfig property of the NetworkConfig gives you control over how these failed requests are handled by allowing you to define custom retry logic.

This guide will walk you through what this property does, why it might be useful for your application, and how to implement it effectively.

What is retryHttpRequestConfig?

The retryHttpRequestConfig property allows you to override the default retry behavior for failed HTTP requests. By providing your own custom handler, you can specify how and when retries should occur, giving you the flexibility to tailor the retry logic to your specific needs.

Why Would You Want to Customize Retry Logic?

There are several reasons why you might want to customize the retry behavior of HTTP requests:

• Optimizing Retry Attempts: depending on the nature of your application, you may want to retry requests more or fewer times than the default.
• Custom Delay Logic: you might want to implement a different retry delay strategy, such as an exponential backoff, to better handle network congestion or server load.
• Handling Specific Errors: certain types of failures might require different retry strategies or even no retries at all.
• Handling Loss of Connection: you may want to add a custom logic in case the connection is lost.

How Does the Default Retry Logic Work?

If you don’t provide a custom retryHttpRequestConfig, the default will be used: RetryHttpRequestConfig. LinearIncreasingBackoffRetry. Here’s how this is defined:

• Retry Attempts: the request will be retried up to a maximum of 6 times for live streams or 3 times for all other stream types.
• Delay Between Retries: the delay between retries is calculated using a custom linear backoff formula, with a maximum delay of 5 seconds:
  • For each retry attempt, the delay is determined by the formula min(retryCount, 5.0), which produces a gradually increasing delay.
  • The delay is capped at 5 seconds to ensure retries occur within a reasonable timeframe.
• Aborting Retries: if the request has already been retried 6 times (or 3 times respective the stream type), no further retries will be made, and the retry process will be aborted.

This default logic is designed to handle common network issues gracefully, but it might not be suitable for all applications.

How to use RetryHttpRequestConfig.Retry

Using this predefined config will do a simple retry with the backoff times defined in the constructor, in seconds.

The size of the passed list is the maximum retry count.

The following example will do 3 retries with a backoff time of 1.0 seconds, 2.0 seconds and 5.0 seconds.

PlayerConfig(
    networkConfig = NetworkConfig(
        retryHttpRequestConfig = RetryHttpRequestConfig.Retry(
            listOf(
                1.0,
                2.0,
                5.0
            )
        )
    )
)

How to Use RetryHttpRequestConfig.Custom

Using the retryHttpRequestConfig property involves defining a custom handler that specifies your retry logic. Here’s how you can set it up.

By providing a callback to the RetryHttpRequestConfig.Custom constructor, your custom retry policy can use the provided RetryContext to apply a custom retry policy. This RetryContext is a data class providing everything needed to identify the failed request.

The following example is a custom implementation that:

• Retries HttpRequestType.MediaSubtitle request up to 3 times, all other requests up to 5 times
• Retries HttpRequestType.ManifestDash after 0.5 seconds without incrementing the delay
• Retries all other requests with a linear increasing backoff duration

PlayerConfig(
    networkConfig = NetworkConfig(
        retryHttpRequestConfig = RetryHttpRequestConfig.Custom { retryContext ->
            // Retry up to 5 times for critical requests
            val maxRetries = if (retryContext.httpRequestType == HttpRequestType.MediaSubtitles) {
                3
            } else {
                5
            }
            if (retryContext.currentRetryCount >= maxRetries) {
                return@Custom null
            }

            // Custom retry delay for the HttpRequestType.ManifestDash
            if (retryContext.httpRequestType == HttpRequestType.ManifestDash) {
                return@Custom 0.5
            }

            // Retry with the calculated delay of 2.0 * retryCount 
            return@Custom 2.0 * retryContext.currentRetryCount
        }
    )
)

Understanding the Process

• Retry Logic: your custom RetryHttpRequestConfig allows you to control how many times a request should be retried and how long to wait between retries.
• Request Identification: the retryContext parameter helps you apply specific retry logic based on the type of request. The RetryContext class contains following properties in order to help you identify the failed request and decide on the handling
  • currentRetryCount: Int
  • httpRequestType: HttpRequestType
  • httpRequest: HttpRequest
  • exception: IOException
• Handling Failures: if the retry count exceeds your threshold, simply return null to stop further retries.