
# Interceptors

A `RequestInterceptor` changes every request before it is sent. Use it for what all calls need and no method should repeat: an authentication header, a tracing id, a common query parameter. Every `RequestInterceptor` bean applies to every client, in `@Order`.

## Why

A token or a request id added by hand to every method is noise, and one forgotten method sends an unauthenticated request. An interceptor adds it once, for all clients or for some, and runs again at every attempt, so a refreshed token reaches a retry.

## Example

```dart
@Configuration()
class FeignSetup {
  // The user's token; the function may be async, and it is asked again at every attempt.
  @Bean()
  RequestInterceptor auth(TokenStore tokens) =>
      BearerTokenRequestInterceptor(() => tokens.accessToken);

  @Bean()
  @Order(10)
  RequestInterceptor requestIds() => RequestIds();
}

// Every call carries a request id; the catalog also gets the language.
final class RequestIds implements RequestInterceptor {
  @override
  void apply(RequestTemplate template) {
    template.header('X-Request-Id', newId());
    if (template.clientName == 'catalog') template.query('lang', 'en');
  }
}
```

## RequestTemplate

| Member | Meaning |
|---|---|
| `method`, `url` | The HTTP method and the full URL (base URL, path and query); an interceptor may replace them. |
| `headers` | The request headers, to read or change. |
| `body` | The encoded body, or `null`. Replacing it does not change the `Content-Type`. |
| `header(name, value)` | Adds a value, as Feign's does. To replace a header, call `removeHeader(name)` first. |
| `removeHeader(name)` | Removes a header. |
| `query(name, value)` | Adds a query parameter. |
| `methodKey` | Which method makes the call, such as `CatalogClient#find(String)`; error decoders get the same key. |
| `clientName` | The client's `@FeignClient` name, to act on some clients only. |

## How interceptors run

- `apply` may return a `Future`, for example to fetch a fresh token; the call waits for it. An exception fails the call.
- They run for every attempt of a call, retries included, each time on a new template, so header values never pile up.
- They run under the call's `call-timeout` and the caller's deadline.
- For a server-sent event stream, they run for every connection, so a refreshed token is used when the stream reconnects.
- After them, the `default-request-headers`, `default-query-parameters` and the default `Accept` header are added, for names they did not set.

## Ready-made interceptors

| Interceptor | Sends |
|---|---|
| `BearerTokenRequestInterceptor(token)` | `Authorization: Bearer ...` from a function that may be async; adds nothing when it returns `null`. |
| `BasicAuthRequestInterceptor(user, password)` | HTTP Basic credentials, encoded in ISO-8859-1 as Feign does; pass `encoding: utf8` for other characters. |

## Which interceptors a client gets

1. The application's `RequestInterceptor` beans and those of the client's `@FeignClient(configuration:)` classes, all together in `@Order`.
2. Then the beans the `request-interceptors` property names, `default`'s first, then the client's. A bean that is both runs once.

Beans of one client's configuration classes never reach the other clients (see [Configuration](configuration.md)).

## Secrets

Send secrets as headers, not query parameters: the URL with its query is in the logs and in exception messages. `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie` and `DPoP` are always masked in the logs; name others in `sensitive-headers` (see [Logging](logging.md)).

## In Spring (Java)

```java
@Bean
RequestInterceptor requestIds() {
  return template -> template.header("X-Request-Id", newId());
}
```

The same interface. Each retry starts from a new template here; Feign runs the interceptors again on the same one, where header values pile up.

## See also

- [Configuration](configuration.md)
- [Errors, retries and timeouts](errors-and-retries.md)
- [Logging](logging.md)
