# Add Graceful Shutdown to a Go chi API

Yes. An agent makes a Go chi API stop cleanly on SIGTERM: drain requests with a deadline, stop background goroutines, close the database pool, with a test, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-graceful-shutdown/chi/). 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 stops today. In an API laid out like dhax/go-base, `cmd/serve.go` calls `api.NewServer()` and then `Start()` in `api/server.go`. `Start()` runs `ListenAndServe` in a goroutine and panics on any error other than `http.ErrServerClosed`, waits on a channel registered with `signal.Notify(quit, os.Interrupt)`, and then calls `srv.Shutdown(context.Background())` under a comment that reads `teardown logic...`. Half of a graceful stop is there, and three things are missing. Only `os.Interrupt` is caught, and a container runtime stops a process with `SIGTERM`; the `Dockerfile` ends in `CMD ["./main", "serve"]`, so the binary is the process that receives it and exits at once, mid-request. `Shutdown` has no deadline, so one stuck connection can hold the old process open indefinitely. And nothing the server started is told to stop.

It lists what is left running. `api.New` in `api/api.go` opens the Bun database pool with `database.DBConn()` and keeps it in a local variable, so nothing can close it. `pwdless.NewResource` calls `choresTicker()`, which starts an hourly ticker goroutine that purges expired tokens and never ends. The `login` handler sends the login-token email from a bare `go func()`, so a shutdown a moment after a login request can exit before the mail is handed to the SMTP server. The `http.Server` is built with `Addr` and `Handler` and no timeouts of its own; the router applies `middleware.Timeout(15 * time.Second)` to each request.

The change keeps the structure and closes those gaps. `Start()` takes its signal from `signal.NotifyContext` with `os.Interrupt` and `syscall.SIGTERM`, returns an error where it used to panic, and calls `Shutdown` with a context that expires after a `shutdown_timeout` read through Viper, defaulting to a value above the 15-second request timeout so a request that is allowed to finish has time to. `api.New` returns the pool alongside the router so the server can close it after the last request has drained, in that order. The auth resource gains a `Stop()` that stops the ticker and waits on a `sync.WaitGroup` that now tracks each mail goroutine. `/healthz`, which today always writes `ok`, answers 503 once shutdown has begun, so a load balancer stops sending traffic. `ReadHeaderTimeout` is set on the server, `.env.example` gains `SHUTDOWN_TIMEOUT`, and the readme gets a short paragraph on what happens on stop.

To check it the agent writes `api/server_test.go`, which starts the server on `127.0.0.1:0` with a handler that sleeps, cancels the context while a request is in flight, and asserts that the request completes with 200, that `Start` returns nil, and that a second case with a handler slower than the timeout returns the deadline error. The existing `auth/pwdless/api_test.go` builds the resource with mocks, so it gains an assertion that `Stop()` returns after a pending mail is sent. Then it does the real thing: installs PostgreSQL in its sandbox, runs `go run main.go migrate` and `go run main.go serve` with the variables from `.env.example`, opens a slow request with `curl`, sends `kill -TERM` to the process and records the request's status, the log lines and the exit code. `go vet ./...` and `go test -race ./...` run last.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add graceful shutdown to this Go API built on chi. Read go.mod, main.go, cmd/serve.go, cmd/root.go, api/server.go, api/api.go, database/postgres.go, auth/pwdless/api.go, auth/pwdless/chores.go, auth/pwdless/api_test.go, email/smtp.go, Dockerfile, docker-compose.yml, .env.example and README.md first. In api/server.go handle SIGTERM as well as os.Interrupt with signal.NotifyContext, return errors instead of panicking, and call Shutdown with a deadline read from a new shutdown_timeout Viper setting whose default is above the 15 second request timeout. Make api.New return the database pool so the server closes it after requests drain. Give the auth resource a Stop method that stops the chores ticker and waits for in-flight login emails tracked by a WaitGroup. Make /healthz answer 503 once shutdown starts. Set ReadHeaderTimeout on the http.Server. Add SHUTDOWN_TIMEOUT to .env.example and a paragraph to README.md. Write api/server_test.go covering a request that finishes during shutdown and one that outlives the deadline, and extend the auth test for Stop. Install PostgreSQL in the sandbox, run the migrate and serve commands, send SIGTERM during a slow curl request, and paste the status, log lines and exit code plus go vet and go test -race output into a pull request. Change no route.",
  "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

The pull request changes `api/server.go`, `api/api.go`, `cmd/serve.go`, `auth/pwdless/api.go`, `auth/pwdless/chores.go`, `.env.example` and `README.md`, extends `auth/pwdless/api_test.go` and adds `api/server_test.go`. `cmd/gendoc.go` also calls `api.New`, so it is updated for the new return value. The description carries the `go vet` and `go test -race` output and the sandbox experiment: the `curl` status of the request that was in flight when `SIGTERM` arrived, the shutdown log lines in order, and the process's exit code.

Routes, middleware order, CORS and authentication are untouched, and the workflow's `test` job runs the new tests with `go test -v ./...` as it does the old ones. The `Dockerfile` needs no change, because its exec-form `CMD` already makes the binary the process a container runtime signals; the description says so, since it is the first thing a reviewer of shutdown code checks.

Before merging, a reviewer sets `SHUTDOWN_TIMEOUT` against the platform's own grace period, so the server's deadline expires before the platform's kill arrives, and decides whether a 503 from `/healthz` during the drain suits their load balancer or should be a separate readiness path. The order of teardown, requests first, then background work, then the pool, is stated in the description and enforced by the test.

## Run it on every service that ignores SIGTERM

A team with several Go services sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started and opens no second pull request. Each run reads its own entry point: a service on `database/sql` closes that pool, one with a queue consumer stops consuming before it drains, and one that already handles `SIGTERM` gets its existing handler checked against the same experiment and left alone if it passes.

With a `webhook_url` on the key, each run posts `run.completed` when its turn ends, and the handler reads the pull request from the session at `data.session_url`. Runs past the key's `max_concurrent` wait in `queued` and start as slots free, so the batch needs no retry loop.

## Why run it on Rush?

Whether a server drains can only be seen at the moment a signal lands on a request in progress, and that moment is hard to stage by hand. The agent stages it in a sandbox of its own: it builds the service, starts Postgres, holds a request open, sends the signal and records what the client and the process each saw. The pull request carries that record, so review is about the timeout value and the health check, and not about whether the mechanism works.

The record also preserves the details that are easy to get wrong in Go: catching `SIGTERM` and not only the interrupt, a deadline on `Shutdown`, closing the pool after the listeners and not before, and waiting for goroutines the handlers started. Each service gets its own sandbox and database, so many can be done at the same time without interfering.

## Frequently asked questions

### The server already calls Shutdown. What is actually missing?

The signal and the deadline. `signal.Notify` is registered for `os.Interrupt` only, so the `SIGTERM` a container runtime sends ends the process immediately and `Shutdown` never runs. When it does run, for Ctrl-C in a terminal, it has no deadline and leaves the ticker, the mail goroutines and the database pool to be cut off by exit.

### What happens to a request that takes longer than the timeout?

It is cut off when the deadline passes, and `Start` returns the deadline error so the exit is logged as a forced one. The router's own 15-second timeout already bounds most requests, which is why the default shutdown timeout is set above it.

### Why wait for the login emails?

`login` answers the client first and sends the mail from a goroutine. If the process exits in between, the user has been told to check their inbox and nothing arrives. Tracking those goroutines in a `WaitGroup` and waiting during shutdown, within the same deadline, closes that gap.

### Does it change how the app runs in Docker or Kubernetes?

Not the image. The `CMD` is in exec form, so signals already reach the binary. What changes is the behaviour on stop: the process now drains and exits by itself within `SHUTDOWN_TIMEOUT`, which should be set below the platform's termination grace period.

## More chi jobs

- [Add Health Checks to a chi API](https://getrush.ai/run/add-health-checks/chi/)
- [Add HTTP Server Timeouts to a chi API](https://getrush.ai/run/add-http-timeouts/chi/)
- [Add OpenAPI Docs to a chi API](https://getrush.ai/run/add-openapi-docs/chi/)

## The same job on other stacks

- [Add Graceful Shutdown to an Echo App](https://getrush.ai/run/add-graceful-shutdown/echo/)
- [Add Graceful Shutdown to a Fiber App](https://getrush.ai/run/add-graceful-shutdown/fiber/)
- [Add Graceful Shutdown to a Gin API](https://getrush.ai/run/add-graceful-shutdown/gin/)

## 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/)
