All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading