New redirect features

[tmenier]

Background

More than anything, this is a necessary prerequisite for implementing request-level cookies. Since CookieContainer is only available at the client level, Flurl will need to sort of reinvent the wheel (process cookie headers and provide its own "container") in order for it to work at the request level. However, if a web server sets cookies and then does a redirect (a very common pattern), Flurl won't be able to intercept those headers unless HttpClientHandler.AllowAutoRedirect is disabled, meaning that wheel will need to be re-invented too.

Feature Overview

Since all this re-inventing needs to be done anyway, I figure why not try and make it a little better than what you get out of the box with HttpClient. At a high level, Flurl will provide the following advantages:

1. The ability to enable/disable auto-redirect on a per-request basis.

2. More fine-grained control over how and when to auto-redirect (by status code and/or HTTP verb) and whether not to change the verb to GET on redirect.

If you want similar behavior to HttpClient, do nothing. Redirects will be followed by default. Just note the subtle differences in the last section below.

Enable/disable fluently per request

flurlRequestOrUrl.WithAutoRedirect(true)...
flurlRequestOrUrl.WithAutoRedirect(false)...

Configure globally, on client, or on request

Like other Flurl settings, redirect behaviors are configurable/overrideable at various levels:

FlurlHttp.GlobalSettings.Redirects.Enabled = false; // default true

client.Settings.Redirects.Enabled = true; // default true
client.Settings.Redirects.AllowSecureToInsecure = false; // default false

request.Settings.Redirects.ForwardAuthorizationHeader = true; // default false
request.Settings.Redirects.MaxAutoRedirects = 5; // default 10 (consecutive)

Handle per request

Flurl will define a new OnRedirect event that gets fired upon receiving any 3xx response with a Location header, and provides a new FlurlCall.Redirect property that allows you to capture that information and react however you want:

clientOrRequest.OnRedirect(call => {
    if (call.Redirect.Count > 5) {
        call.Redirect.Follow = false;
    }
    else {
        log.WriteInfo($"redirecting from {call.Request.Url} to {call.Redirect.Url}");
        call.Redirect.ChangeVerbToGet = (call.Response.Status == 301);
        call.Redirect.Follow = true;
    }
})...

Differences from default HttpClient behavior

HttpClientHandler's auto-redirect changes the verb to GET and discards the body on:

• 300 (POST only)
• 301 (POST only)
• 302 (POST only)
• 303 (POST only)

Flurl's auto-redirect will change the verb to GET and discard the body on:

• 301 (POST only)
• 302 (POST only)
• 303 (always)