[breaking change] `HttpClient`: change `StateError` to `RedirectException` when redirect response has no `Location` header

[brianquinlan]

Change Intent

Currently, HttpClient throws a StateError when the server responds with a 302 but there is no Location header.

Instead, RedirectException (a subclass of HttpException) should be thrown.

See #53158

Justification

StateError should be thrown in response to programmer errors, not errors external to the application. Also, HttpException subclasses are thrown in response to other HTTP protocol errors.

Some users (e.g. package:http) assume that HttpClient will only throw SocketException or HttpException.

Impact

This will break HTTP client code that catches StateError but not HttpException and interacts with HTTP servers that return 302 but don't include a Location header. This seems unlikely to happen in practice.

Mitigation

It is likely that no actual code will need to be migrated. In the worst case, an exception type in a on clause might need to change.

Change Timeline

N/A.

Associated CLs

No response

[lrhn]

Technically not breaking to change a thrown error to something else, but if it's the only signal we've given people, for something which ought to have been an exception, it's likely it's been treated like an exception.

[brianquinlan]

Technically not breaking to change a thrown error to something else, but if it's the only signal we've given people, for something which ought to have been an exception, it's likely it's been treated like an exception.

How is that not breaking? If my current code is:

do {
  try {
    HttpClientRequest request = await client.get('brokenserver.com?token=$token', 80, '/');
  } on StateError {
    // brokenserver.com serves broken redirects if the auth token has expired, refetch it
    token = reauth(...);
    continue;
  }
  break;
} while (true)

Then I will break because I'm handling StateError rather than RedirectException.

[itsjustkevin]

@brianquinlan based on @lrhn comment and the context you provided in the following comment, I assume we are still considering this as a breaking change to go through the approval process. Am I misreading this?

[lrhn]

@brianquinlan
Technically (always a good start) a "breaking change" isn't just any change that makes a hypothetical program change behavior.
We've tried to define it as not breaking well behaved programs.

If some program starts using private API from lib/src/, or does things the documentation clearly says not to do, then it getting broken is it's own damn fault.
One of the things we have listed as not being guaranteed behavior is errors.
We reserve the right to make code that currently throw an Error behave differently, either throwing a different error, or succeeding. An error is intended to report a programming error, and currently unsupported operation, so a program which depends on a specific error being thrown is not "well behaved".

In this particular case, because we probably should have made it an exception to begin with, and users have had no alternative to handle the exceptional situation other than to catch the error, we will treat it as if it has been an exception.

(A less breaking change could be to throw an object which implements both RedirectException and StateError, document it as only being the former, and maybe start hinting to change catches of the latter that we can detect statically.)