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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.