Map federation errors to client-facing errors.

This module contains most of the error-mapping logic that turns the various possible errors that can occur while making a federated request into errors that are meaningful for the clients.

There are three types of errors, from lowest level to highest:

• FederatorClientHTTP2Error: this is thrown when something fails while connecting or making a request to the local federator.
• FederatorClientError: this is the most common type of error, corresponding to a failure at the level of the federator client. It includes, for example, a failure to reach a remote federator, or an error on the remote side.
• FederationError: this is created by users of the federator client. It can either wrap a FederatorClientError, or be an error that is outside the scope of the client, such as when a federated request succeeds with an unexpected result.

A general federated request is normally performed as a chain of HTTP requests (some of which are HTTP2). Errors can occur at each node of the chain, as well as in the communication between two adjacent nodes. A successful request goes through the following stages:

1) a service (say brig) makes a request to (the outward service of) the local federator (HTTP2); 2) the local federator processes this request; 3) the local federator makes a request to (the inward service of) a remote one (HTTP2); 4) the remote federator processes this request; 5) from the remote federator to a service on that backend (HTTP); 6) the remote service processes this request.

Failures at step 1 in the chain result in FederatorClientHTTP2Error, while any other failure results in a FederatorClientError.

Immediate failures in the outward service of a federator (stage 2) result in a 403 status code being returned to the federator client, which is then translated into an error with label federation-local-error.

Failures which occurred while making a request to a remote federator (stages 3 to 6) are turned into 5xx errors by federator itself, and then passed on through without any further mapping. This includes issues in stage 4, which are seen by the local federator as 403 status codes returned by the remote, as well as arbitrary error codes returned by a service.

Note that the federation API follows the convention that any error should be returned as part of a successful response with status code 200. Therefore any error response from services during a federated call should be considered a bug in the implementation of the federation API, and is therefore wrapped in a 533.