# Add Graceful Shutdown to a Ktor Server

Yes. An agent configures Ktor's shutdown grace period, closes your database connection on ApplicationStopping, adds a shutdown test, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-graceful-shutdown/ktor/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the server starts and holds its resources before it changes how it stops. In a service shaped like the `postgres` sample in ktorio/ktor-samples, `build.gradle.kts` applies Kotlin 2.4.20 and the `io.ktor.plugin` 3.6.0 with `ktor-server-netty-jvm`, `ktor-server-config-yaml`, `ktor-server-content-negotiation-jvm`, the PostgreSQL JDBC driver 42.7.8 and `ktor-server-test-host-jvm` for tests, and sets `mainClass` to `io.ktor.server.netty.EngineMain`. `src/main/resources/application.yaml` names the module `com.example.PostgresApplicationKt.module` and sets port 8080 and nothing else. `PostgresApplication.kt`'s `module` calls `configureSerialization()` and `configureRouting(dbConnection = connectToPostgres(embedded = false))`, and `connectToPostgres` in `plugins/Routing.kt` opens one `java.sql.Connection` with `DriverManager.getConnection` from the credentials in `postgres.yaml`. `ArticleService` keeps that connection for the life of the process and runs every statement on `Dispatchers.IO`. Nothing closes the connection, and no shutdown timing is configured, so a `SIGTERM` from a container runtime stops Netty with whatever defaults it has while a `withContext(Dispatchers.IO)` block may still be mid-statement. There is no test source set.

It adds the two engine settings Ktor reads from configuration, `ktor.deployment.shutdownGracePeriod` and `ktor.deployment.shutdownTimeout`, to `application.yaml` under the existing `deployment` key, with values chosen to let an in-flight `POST /articles` finish before the engine stops accepting and then stops hard. In `PostgresApplication.kt` the module subscribes to the application's `ApplicationStopping` event and closes the connection there, and to `ApplicationStopped` to log that it did, using the `monitor` the `Application` exposes. The connection is created in the module as before, but it is passed to the subscription as well as to `configureRouting`, so the close happens once and on the right lifecycle event, after Netty has stopped taking new requests and after the grace period for running ones. `ArticleService` gets a check that a statement is not started on a closed connection and answers the caller with a `503` through the existing exception handling in `Routing.kt` rather than a stack trace.

Because the sample runs under `EngineMain`, the JVM's own shutdown hook triggers the engine stop on `SIGTERM`, so no custom hook is needed; the agent says so in the pull request rather than adding one. It also adds a `GET /health` route that answers `200` while the application is running and `503` once `ApplicationStopping` has fired, by flipping an `AtomicBoolean` in the same subscription, so a load balancer stops sending traffic during the grace period. `docker-compose.yaml` already runs PostgreSQL 18 on port 5432 from `postgres.yaml`; the agent leaves it alone and notes the `stop_grace_period` a compose service would need to exceed `shutdownGracePeriod`.

The project has no tests, so the agent adds `src/test/kotlin/com/example/ShutdownTest.kt` on the `ktor-server-test-host-jvm` dependency `build.gradle.kts` already declares. One test starts the application with `testApplication`, requests `/health`, asserts `200`, then stops the application and asserts the connection reports `isClosed`, using a connection to a database the test starts, or a fake `Connection` when none is available, which the pull request states. Another asserts that the configured grace period and timeout are read from `application.yaml` by loading the test configuration. Before pushing it runs `./gradlew build`, which compiles and runs the tests, and `./gradlew run` long enough to send `SIGTERM` and read the stop log lines, and pastes both into the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add graceful shutdown to this Ktor server and open a pull request. Read build.gradle.kts, gradle.properties, src/main/resources/application.yaml, src/main/kotlin/com/example/PostgresApplication.kt, src/main/kotlin/com/example/plugins/Routing.kt, src/main/kotlin/com/example/service/ArticleService.kt, docker-compose.yaml and postgres.yaml first. Set ktor.deployment.shutdownGracePeriod and ktor.deployment.shutdownTimeout in application.yaml. In the module, subscribe to ApplicationStopping to close the JDBC connection and to ApplicationStopped to log it, keeping one connection shared with configureRouting. Make ArticleService answer 503 rather than throw when the connection is closed. Add GET /health that answers 200 while running and 503 once stopping has begun. Do not add a dependency; the server runs under EngineMain, so do not add a custom shutdown hook, and say why in the pull request. Add src/test/kotlin/com/example/ShutdownTest.kt with testApplication covering the health route before and after stop, the connection being closed, and the two settings being read from configuration. Run ./gradlew build and a run that receives SIGTERM, and paste the output in the pull request. Do not change the article routes.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that edits `application.yaml`, `PostgresApplication.kt`, `Routing.kt` and `ArticleService.kt`, and adds `src/test/kotlin/com/example/ShutdownTest.kt`. `build.gradle.kts` is unchanged, since the test host dependency is already there. The description explains the two settings and the values chosen, shows the log lines from a run that received `SIGTERM`, with the stopping and stopped events and the connection close in order, and pastes the `./gradlew build` output.

A reviewer checks the grace period against the longest request the service handles and against the `terminationGracePeriodSeconds` or `stop_grace_period` of their runtime, since the runtime's limit must be longer. Then they point their load balancer's check at `/health` so the `503` during shutdown drains traffic.

## Run it on every Ktor service deployed in containers

A team with several Ktor services sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own engine, configuration format and resources, so a service on `embeddedServer` with HOCON gets a `shutdown` block and a custom hook where `EngineMain` would not need one, and a service with a HikariCP pool closes the pool instead of a connection, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request and the build output from.

## Why run it on Rush?

Shutdown bugs only show when a process is stopped while it is busy, which is the one moment nobody watches a laptop. In a Rush sandbox the agent builds the service, starts it, sends it `SIGTERM` and reads the order of the stop events and the connection close from the logs, and runs the test that stops a `testApplication` and checks the connection, keeping every command and its output in the run's record. The pull request shows the sequence rather than reasoning about what Netty probably does.

The change uses what Ktor already provides: the engine's grace and timeout settings read from the same `application.yaml`, the `ApplicationStopping` and `ApplicationStopped` events, and the test host that was already a dependency. No library is added, the article routes are untouched, and the same request works on any Ktor 3 server that holds a connection, a pool or a client that needs closing.

## Frequently asked questions

### What do shutdownGracePeriod and shutdownTimeout do?

The grace period is how long the engine keeps serving requests that were already in progress after it stops accepting new ones; the timeout is the hard limit after which it stops regardless. Both are read from `application.yaml` under `ktor.deployment` because the server starts with `EngineMain`, and a test loads the configuration to assert they are set.

### Why no custom shutdown hook?

`EngineMain` installs one. When the JVM receives `SIGTERM`, the engine's stop runs with the configured grace period and timeout, which fires `ApplicationStopping`, where the connection is closed. Adding another hook would race with it. The pull request states this so nobody adds one later.

### Does the health route need a dependency?

No. It is one `get` route in `Routing.kt` that reads an `AtomicBoolean` the stopping subscription flips. A load balancer that sees `503` stops routing to the instance during the grace period. A fuller health plugin can replace it later.

### How is the shutdown checked?

Two ways. A test stops a `testApplication` and asserts the connection reports `isClosed`. And the agent runs the server, sends `SIGTERM` and pastes the log lines showing the stopping event, the connection close and the stopped event in that order. No numbers in the pull request are estimates.

## More Ktor jobs

- [Add Health Check Endpoints to a Ktor Server](https://getrush.ai/run/add-health-checks/ktor/)
- [Add Input Validation to a Ktor API](https://getrush.ai/run/add-input-validation/ktor/)
- [Add JWT Authentication to a Ktor API](https://getrush.ai/run/add-jwt-auth/ktor/)

## The same job on other stacks

- [Add Graceful Shutdown to Services Running on Kubernetes](https://getrush.ai/run/add-graceful-shutdown/kubernetes/)
- [Add Graceful Shutdown to a Leptos Axum Server](https://getrush.ai/run/add-graceful-shutdown/leptos/)
- [Add Graceful Shutdown to a Litestar App](https://getrush.ai/run/add-graceful-shutdown/litestar/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
