
# Timeouts

Three properties limit time: `server.connection-timeout` (the network is silent), `server.request-timeout` (the application is slow), and `spring.mvc.async.request-timeout` (an `SseEmitter` stays open).

## Why

A server that waits forever can be held up by anyone:

- a client that starts to send a body and then sends nothing keeps a connection and a request open;
- idle keep-alive connections pile up;
- a handler that waits on a slow database or a slow remote service keeps its client waiting, and the client gave up long ago.

Each property covers one of these cases. They do not replace each other.

| Property | Limits | Default | Past it |
|---|---|---|---|
| `server.connection-timeout` | silence while a request body is read; idle keep-alive connections | `60s` | `408`, the connection closes; an idle connection closes |
| `server.request-timeout` | the time the filters and the handler take to start the answer | no limit | `503`; the request's `RequestDeadline` has passed |
| `spring.mvc.async.request-timeout` | the life of an `SseEmitter` without its own timeout | no limit | `onTimeout` callbacks, then the emitter completes |

## Example

```yaml
# lib/resources/application.yml
server:
  connection-timeout: 30s
  request-timeout: 10s
spring:
  mvc:
    async:
      request-timeout: 30m
```

```properties
server.connection-timeout=30s
server.request-timeout=10s
spring.mvc.async.request-timeout=30m
```

A handler that reads the deadline between its steps:

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

@RestController()
@RequestMapping('/api/reports')
class ReportController {
  ReportController(this.sales, this.stock);
  final SalesClient sales;   // a Feign client: it stops at the request's deadline
  final StockService stock;

  @GetMapping('/daily')
  Future<Report> daily() async {
    final totals = await sales.totals();
    RequestDeadline.current?.check(); // nobody waits any more: stop here
    final levels = await stock.levels();
    return Report(totals, levels);
  }
}
```

## `server.connection-timeout`

- **Type:** `Duration` (`60s`, `500ms`, `PT1M`; a plain number is **milliseconds**). **Default:** `60s`.
- **No limit:** `0` or any negative value (`-1`), as in Tomcat.
- **What it does, case 1: a stalled body.** While a request body is read, the timer restarts with every chunk that arrives. When nothing arrives for this long, the read fails with a `408 Request Timeout` `ProblemDetail` (detail `The request body did not arrive in time`), and the connection closes after the answer. Time while the reader itself pauses (back-pressure) does not count.
- **What it does, case 2: idle connections.** A keep-alive connection with no request for this long is closed. This is `dart:io`'s `idleTimeout`. Tomcat's keep-alive timeout is also its connection timeout.
- **What it does not do:** it does not limit a slow handler, a slow answer, or the total time of an upload that keeps sending. A handler is limited by `server.request-timeout`.
- **Why change it:** lower it (`10s`) on a public server, so that silent clients free their connection sooner. Raise it for clients on very slow links that upload large files with long pauses.
- **Example:** `server.connection-timeout=20s`.
- **Careful:** `server.connection-timeout=60` is 60 milliseconds, not 60 seconds. Write the unit.

## `server.request-timeout`

- **Type:** `Duration`. **Default:** not set: no limit. `0` or a negative value: no limit either.
- **What it does:** the filters and the handler must start the answer within this time. When the time passes first:
  - the client gets `503 Service Unavailable`, a `ProblemDetail` with the detail `The request did not complete in time.`. It does not mention the limit or what the handler was doing;
  - whatever the handler does with the response afterwards is dropped: no second answer, no error;
  - the 503 is logged as a warning, like other 5xx answers, at most once per 10 seconds for the same kind.
- **The deadline.** The request runs under a `RequestDeadline` of that length (from `spring_web_dart`). It is carried in the `Zone`, like a transaction, so it follows `await`s. Code the request calls can read it:

| Member | What |
|---|---|
| `RequestDeadline.current` | the deadline of the code that runs now, or `null` |
| `budget` | the length it was given |
| `remaining` | the time left; never negative |
| `isExpired` | whether the time has passed |
| `check()` | throws a `RequestDeadlineExceededException` when the time has passed |
| `RequestDeadline.run(budget, body)` | runs `body` under a deadline of its own; inside another one, the earlier end wins |

- **Feign clients honour it.** A call a controller makes through a Feign client stops at the request's deadline: the limit of the call is the earlier of its own `call-timeout` and the time left. The call then throws, and the request is answered with the 503.
- **Errors at the deadline are a 503.** A `RequestDeadlineExceededException`, or any error thrown in the last 10 ms of the deadline, is answered with the 503 (also a `RequestDeadlineExceededException` thrown by a `RequestDeadline.run` of your own without the property). Other errors keep their own answer (a 400, a 500).
- **Filters count.** The filters (the security filter chain too) run inside the budget. Time a filter uses is taken from the handler.
- **Why change it:** a public API whose clients give up after some seconds anyway; a backend whose callers have their own timeout (set it a little below theirs); to stop slow remote calls from piling up.
- **Example:** `server.request-timeout=10s`.

### What it does not do

- **It does not stop running code.** Dart cannot interrupt a function. A handler that never reads the deadline runs on after the 503; its late answer is dropped. Call `RequestDeadline.current?.check()` between steps, or use clients that read the deadline.
- **Streams are not cut.** A response that starts to stream (server-sent events, an `SseEmitter`, NDJSON, a byte stream, a `StreamingResponseBody`) leaves the deadline when it starts. What the stream does later runs under no deadline. Use `spring.mvc.async.request-timeout` or `SseEmitter(timeout:)` for event streams.
- **A response already being sent is left alone.** Once the status and headers are out, the timer does nothing.
- **WebSocket handshakes are not timed.**
- **`@ExceptionHandler` methods do not see this 503**, because the handler is still running.
- **Uploads count.** The time the handler spends reading a slow upload counts. `server.connection-timeout` still ends a body that sends nothing.
- **One value for all requests.** There is no per-route value yet.
- **Not in a customizer.** The dispatcher reads it from the property. A `WebServerFactoryCustomizer` cannot change it.

## `spring.mvc.async.request-timeout`

- **Type:** `Duration`. **Default:** not set: no limit.
- **What it does:** the timeout of an `SseEmitter` created without one (`SseEmitter()`). It counts from when the response starts. When it passes, the emitter's `onTimeout` callbacks run, then the emitter completes and the stream ends.
- **An emitter with its own timeout** (`SseEmitter(timeout: const Duration(minutes: 5))`) keeps it.
- **A `Stream` or `EventStream` result is not limited by it.** It ends when the stream ends, when the client goes away, or when the server stops.
- **Why change it:** give every emitter a maximum life, so that forgotten emitters do not stay open forever. Browsers' `EventSource` reconnects by itself.
- **Example:** `spring.mvc.async.request-timeout=30m`.

```dart
@GetMapping('/api/orders/updates')
SseEmitter updates() {
  final emitter = SseEmitter(); // ends after spring.mvc.async.request-timeout
  emitter.onTimeout(() => emitter.send('bye'));
  orders.watch(emitter);
  return emitter;
}
```

See [Server-sent events](../streaming/sse.md).

## How they work together

- A client uploads a 50 MB file over a slow link and pauses for 2 minutes: `server.connection-timeout` (60 s) ends it with a 408.
- The same upload keeps sending, but takes 3 minutes in all, with `server.request-timeout=30s`: the 503 comes at 30 s, because the handler that reads the body has not answered yet.
- A handler waits 20 s for a Feign call, with `server.request-timeout=10s`: the call stops at 10 s, and the client gets the 503.
- An event stream stays open for an hour, with `server.request-timeout=10s`: it is not cut, because it left the deadline when it started. With `spring.mvc.async.request-timeout=30m`, an `SseEmitter` ends after 30 minutes.
- A client keeps a connection open without sending a request: it closes after `server.connection-timeout`.

At shutdown, `spring.lifecycle.timeout-per-shutdown-phase` limits how long running requests may still take. See [Shutdown](shutdown.md).

## In Spring (Java)

```properties
server.tomcat.connection-timeout=30s
spring.mvc.async.request-timeout=30m
```

Differences that matter:

- `server.connection-timeout` is the key Spring Boot 2.0 had. Spring Boot 3 and 4 use `server.tomcat.connection-timeout` (or Jetty's and Undertow's keys).
- A stalled body gets a 408 here. With Tomcat the read fails and Spring answers 400.
- `server.request-timeout` and `RequestDeadline` are extensions. Spring has no limit for synchronous requests, and no limit follows a request into the calls it makes.
- `spring.mvc.async.request-timeout` applies only to `SseEmitter`s here. In Spring it applies to every asynchronous request (`DeferredResult`, `Callable`, `ResponseBodyEmitter`), and without it the container's default (Tomcat: 30 seconds) applies. Here, without it, an emitter never times out.

## See also

- [The embedded server](index.md)
- [Overload](overload.md)
- [Shutdown](shutdown.md)
- [Server-sent events](../streaming/sse.md)
- [Uploads](../streaming/uploads.md)
- [Streaming response bodies](../streaming/streaming-response-body.md)
- [All properties](../properties.md)
- [Durations](../../spring-core-dart/conversion/durations.md)
